Improve the extension example: distinguish returned, raised and cancelled tool calls

[Inference1]

For extension authors building tool monitoring, the current example demonstrates counting calls, but not how to observe their outcomes and elapsed time while preserving execution behavior. I propose extending that same example and its existing /api/extension-example/stats response.

Concrete gap

At 53df22bd, the async tool wrapper increments tool_calls before awaiting the handler. After task finalization, the count alone cannot distinguish three normal returns from one return, one raised exception and one cancellation. The example also has no sync observation wrapper.

Illustrative outcome for three calls taking 10, 20 and 30 ms respectively — proposed output, not a measured result:

Today:     tool_calls = 3
Proposed:  tool_calls = 3
           returned = 1, raised = 1, cancelled = 1
           duration_samples = 3, duration_total_ms = 60

This would give extension authors a tested reference for preserving results and cancellation while collecting statistics, using existing public hooks without a telemetry service or new dependencies. It relates to the monitoring use case in #4357.

One bounded PR

• Update the existing example implementation, offline tests and README.
• Observe sync and async logical tool calls at the existing TOOL_VISIBLE boundary; call the handler exactly once and preserve its result or exception.
• Keep existing fields; add fixed outcome counters and monotonic duration totals/sample counts. returned includes error messages returned normally, so it does not mean business success. raised counts exceptions escaping this wrapper.
• Retain finalized-task, process-local aggregation and restart reset. Durations include downstream processing and are not wall-clock run time. Store no arguments, outputs, exception text or identifying labels in the new fields.

Tests would use a fake clock and synthetic handlers to cover returns (including returned error messages), exceptions, cancellation, zero duration, concurrent calls, missing task scope and aggregation without double-counting. Disabled behavior and existing endpoint fields would remain covered.

No core runtime, public contract, persistence or UI changes are proposed.

Would you welcome a PR limited to this example, its tests and README? I have not started implementation.

[willem-bd]

This looks like a useful, well-scoped example improvement. I support a PR limited to the example implementation, its offline tests, and README; the existing extension hooks appear sufficient.

The reported gap is reproducible. In a focused local exercise through the host's IsolatedMiddleware, one normal return, one raised exception, and one actual task cancellation produced only tool_calls = 3 after finalization. A synchronous call executed successfully but added no observation. Results, exceptions, and cancellation were preserved by the current wrapper.

The proposal already makes the right distinction between a normal return and business success. A few acceptance criteria would make the reference especially useful:

• Preserve control flow: test real Task.cancel(), result/exception identity, and exactly one downstream handler invocation in both execution paths. Include LangGraph interruption/control-flow signals (GraphBubbleUp) and document their classification if they count as raised; they must propagate unchanged.
• Define aggregation precisely: merge outcome counters and duration samples consistently under concurrent calls. Clarify the intended behavior for duplicate finalization. In a synthetic repeated-stop check, the current on_task_stop() counted the task twice while absorbing tool calls only once. This does not establish that the host normally sends duplicate stops, but it is worth pinning down in the proposed no-double-counting tests.
• Keep the measurement boundary explicit: at TOOL_VISIBLE, a tool exception converted downstream into an error ToolMessage is a normal return. Durations include downstream middleware processing, and overlapping lead/subagent durations are not total run time. The proposed wording correctly avoids presenting these counters as business-success metrics.

One existing test-fixture issue surfaced separately: FakeRegistry in tests/test_plugin.py lacks the current ExtensionRegistry.plugin() method, so its protocol-conformance assertion fails. Updating that fake should fit naturally into the test changes. Verification here was focused local execution, not a clean installed-package or full-suite validation.

No architectural blocker found for the proposed scope.

[Inference1]

Thanks for checking this and supporting the scope. I'll keep the PR limited
to the example, its offline tests and README, and cover the control-flow,
aggregation and measurement-boundary cases you listed. I'll also update
FakeRegistry to match the current public protocol.