feat: deliver Logfire tracing as an explicit Instrumentation capability

[mpfaffenberger]

What

Tenth in the capability-conversion series (#828–#836). Promotes OpenTelemetry/Logfire tracing from the process-global mutable default (logfire.instrument_pydantic_ai() → Agent.instrument_all(settings)) to a first-class, explicitly-declared Instrumentation capability on the agents code_puppy constructs.

pydantic-ai 2.31.0 itself treats the capability as the canonical form — instrument_all's own docstring reads "for all agents that don't explicitly add an Instrumentation capability", and the run layer skips its internal injection whenever an explicit one is present ("explicit-capability-wins").

How

• New code_puppy/agents/_instrumentation.py — build_instrumentation() resolves the effective global default at build time (mirroring Agent._resolve_instrumentation_settings) and returns a stock Instrumentation capability carrying the exact settings object logfire installed (True → default-constructed settings; unset/False → empty list).
• Both construction sites converted — main builder (_builder.py) and sub-agent invoker (subagent_invocation.py) splat *build_instrumentation() into their capabilities=[...] blocks. List position is inert: the capability declares position='outermost' ordering — the same slot the run layer's internal prepend targets.
• observability.configure_logfire() unchanged in behaviour; docstring now documents the two delivery paths.

Why the global default is deliberately retained

1. Out-of-tree agents. Core plugins construct their own raw pydantic-ai agents (wiggum's judge, btw's side-query) and receive spans purely from Agent.instrument_all. Removing it would silently kill their telemetry — a parity break.
2. ctx.tracer consistency. pydantic-ai resolves the run context's tracer from global/instance settings independently of explicit capabilities; keeping both in sync means capabilities/toolsets observing ctx.tracer never see a NoOpTracer while spans exist.
3. Ordering robustness. An agent built before configure_logfire runs carries no capability and degrades to exactly the old behaviour via the run-layer fallback.

Explicit-when-ours, fallback-for-guests.

Divergence (documented + pinned)

The capability is a build-time snapshot; the global default is read per run. If Agent.instrument_all(False) were called after a build, that agent would keep tracing until rebuilt (previously it would go quiet on the next run). Nothing in code_puppy or its plugins flips the default after startup. Pinned by test_snapshot_survives_later_global_disable.

Tests

12 contract tests in tests/agents/test_instrumentation_capability.py:

• builder contract (empty/verbatim/True-normalisation/fresh-per-call)
• private-seam pin on Agent._instrument_default (a pydantic-ai rename fails loudly here; runtime degrades soft to the fallback)
• position='outermost' ordering pin
• span parity: identical span name + gen_ai.operation.name sequences between the old global-only path and the new explicit path (in-memory OTel exporter)
• no double instrumentation with both the explicit capability and the global default live
• both real construction paths (main builder + _invoke_agent_impl) deliver the verbatim settings object

Full suite: 7609 passed, 28 skipped, 1 xpassed, 0 failed — including the previously-eternal test_render_version_check_current, healed on main by #837.

[mpfaffenberger]

Review trail (code-puppy clone, session pr-838-review):

• Pass 1: APPROVE — 4 non-blocking findings + 2 nits. Applied in 58a3847: span-parity test upgraded to fully-normalized comparison (status codes, parent topology, attribute key sets, stable values — equality also rules out duplicated request/tool spans), new ctx.tracer identity contract test, for_run isolation test, docstring scoped to classic run/iter with realtime nuance. DBOS wrapper test declined (DBOS not installed; capability attaches before on_wrap_pydantic_agent, wrapper transparency established by feat: deliver MCP toolsets via a pydantic-ai capability (McpToolsets) #834/Deliver stream rendering via a StreamRendering capability #835) — reviewer accepted: 'Mocking a fake DBOS-like wrapper would mostly test the mock. YAGNI wins.'
• Pass 2: APPROVE — zero blocking findings.

Final state: 14 contract tests, full suite 7611 passed, 0 failed.