feat(agents): promote run-end telemetry to a RunTelemetry capability (after_run seam)

[mpfaffenberger]

What

Fifteenth entry in the capability series (#828–#836, #838–#842). The agent_run_end payload extraction — human-readable response text plus the six-figure usage token metadata dict — moves from eager post-await bookkeeping at the tail of _runtime.run_with_mcp to a first-class capability, RunTelemetry, on pydantic-ai 2.31.0's after_run seam. This is the first claim of after_run in this codebase.

Why this feature

After #842 converted the sub-agent invocation layer's around-the-run bookkeeping, the main path's mirror-image bookkeeping was the last unclaimed custody on the run boundary: the tail of run_with_mcp fishes response_text and usage numbers out of the returned AgentRunResult and feeds them to on_agent_run_end consumers (run-stats calibration, the kennel, token-tracking plugins). That extraction describes the result of a run — exactly what after_run exists to observe.

Scouting note (kennel'd): the round's first candidate — the main-run cancellation checkpoint (_checkpoint_cancelled_history) via wrap_run — was rejected on empirical evidence: at the wrap_run boundary the delivered CancelledError is a fresh injected exception without the RunCancelled snapshot (_translate_cancellation's _attach_to runs above the seam), and the seam's RunContext is pre-run state (ctx.messages == [] even mid-run). Cancelled-run history custody cannot move inside the run boundary with parity. Spiked before writing, saved to the kennel so no future round chases it.

Seam mechanics (verified against installed pydantic-ai 2.31.0)

• after_run(ctx, *, result) fires once per successful Agent.run() and receives the identical AgentRunResult object the caller gets back — verified under direct registration and under CombinedCapability composition.
• It is not called when the run ends without a result (failure/cancellation) — matching the eager code, which only extracted after a successful await.
• A turn may contain several runs (initial call + queued-steer / hook-retry follow-ups). Each capture overwrites the last, so the surviving snapshot always describes the run whose result run_with_mcp ultimately returns.

Design: identity-gated custody

RunTelemetry holds one last-capture slot (result, text, usage). The consumer calls consume(result) — read-and-clear, returning telemetry only when the captured result is (object identity) the result about to be reported. Everything else converges on the fallback:

• guest wrappers that bypass capabilities (wrap_pydantic_agent swaps),
• None results (a swallowed UsageLimitExceeded returns None from the task body),
• stale captures from an earlier turn whose task failed before consuming.

The fallback is the same pair of helper functions the capability itself uses (extract_response_text / extract_usage_metadata, moved verbatim from _runtime — including the int(value) or None zero-token quirk, which is pinned by a dedicated test, and the provider alias fallback chains). Both paths produce byte-identical payloads; ownership only changes where the extraction runs, not what it produces. This is the #838/#841/#842 explicit-when-ours, fallback-for-guests split with the cheapest ownership check in the series: is.

Wiring

• _builder.build_pydantic_agent hoists one instance shared by the probe + final construction passes (series precedent from Promote per-model settings to a PerModelSettings capability #831/refactor: promote system-prompt delivery to an AssembledInstructions capability #832/Promote model delivery to a ResolvedModel capability #833; the probe never runs, so its slot stays empty) and stashes it as agent._run_telemetry — documented alongside the other build side effects in the docstring.
• The run_with_mcp success tail consumes-or-falls-back; init uses the shared empty_usage_metadata() factory instead of a hand-rolled literal.
• Scope: main path only. The sub-agent invoker keeps its separate include_usage_metrics capture; pinned by a source test asserting subagent_invocation.py never mentions RunTelemetry (mirrors feat(agents): SubagentSessionPersistence capability on the wrap_run seam #842's scope pin, in reverse).

Feature parity checklist

• response text extraction: same branch order (None → "", .data wins over .output, str fallback)
• usage extraction: same alias chains, same int(value) or None zero→None short-circuit, same all-None dict on any failure (property access, not the deprecated callable)
• success-only: failed/cancelled turns report "" + all-None exactly as before (after_run doesn't fire; fallback sees None/no capture)
• UsageLimitExceeded swallowed → task returns None → "" + all-None (identity gate can't match None)
• multi-run turns: last capture == returned result (verified identity per run)
• no behavioral divergences found — extraction is pure and runs on the same object either way; the only delta is when (run boundary vs. post-await), which is unobservable to consumers

Tests

21 contract tests in tests/agents/test_run_telemetry_capability.py:

• extraction-helper parity (incl. the zero-token quirk pin and alias fallbacks)
• seam contract: identical-object capture, CombinedCapability composition, read-and-clear + identity-gate semantics, result pass-through, from_spec
• builder wiring: real build_pydantic_agent drive proving the stashed instance is the one riding the built agent
• run_with_mcp custody: capability-owns (sentinel-proof the fallback wasn't used), guest-bypass fallback, stale-capture rejection, no-attribute fallback
• sub-agent scope pin

Full suite: 7618 passed, 0 failed (up from 7617 on the previous branch — the 21 new tests net against the moved helpers' old coverage).

Series context

Fifteen capability PRs (#828–#836, #838–#842, this one) now share the capabilities=[...] blocks. This one touches only the main builder block, so it collides mildly with the main-path subset. Rebases remain trivial in any merge order.

Not merged — awaiting human review, per standing orders.