docs: PR 4 plan — pydantic-ai migration onto the unified harness surface

[declan-scale]

Implementation plan for PR 4 (pydantic-ai migration) of the unified harness surface workstream. Stacked on the foundation branch (#412) so the diff is just the plan doc.

Covers: PydanticAITurn (HarnessTurn) + usage normalization, reimplementing stream_pydantic_ai_events on UnifiedEmitter (default tracing, same public signature), deprecating the bespoke _pydantic_ai_tracing handler, cross-channel conformance fixtures, and the 3 integration test agents (sync/async/temporal) under examples/.

Dependencies called out in the plan: AGX1-373 (cross-channel conformance — in progress) and AGX1-375 (public adk import path). This plan is the template PR 5 (langgraph) and PR 6 (openai) will follow.

🤖 Generated with Claude Code

Greptile Summary

• Adds a PR 4 implementation plan for migrating pydantic-ai onto the unified harness surface.
• Defines planned work for PydanticAITurn, usage normalization, UnifiedEmitter streaming, tracing deprecation, conformance fixtures, integration test agents, and CI wiring.
• Calls out dependencies on cross-channel conformance and the public adk import path.

Confidence Score: 4/5

The PR is documentation-only, but the implementation plan contains two concrete migration instructions that would cause behavior regressions if followed as written.

The changed file is narrow and the issues are localized to usage normalization and tracing migration guidance, with runtime checks confirming both documented assumptions conflict with the current code/dependency behavior.

docs/superpowers/plans/2026-06-18-unified-harness-surface-pr4-pydantic-ai.md

T-Rex Logs

What T-Rex did

• I reproduced the cache-token normalization behavior by running a local Python repro that constructs RunUsage from pydantic-ai-slim 1.107.0 and shows that cache_read_tokens and cache_write_tokens exist while cached_input_tokens is absent.
• I exercised a focused harness around the pydantic_ai_async streamer and observed that the streaming module does not read a contextvar or trace_id in AST, while the tracing handler path creates a span from the supplied trace_id and parent_id.
• I reviewed the plan validation artifacts and confirmed the before state showed a base plan path issue, and the after state shows head validation, file presence, changed-file listing, and PASS results with document excerpts proving the plan entries exist.

_{Ran code and verified through T-Rex}

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
docs/superpowers/plans/2026-06-18-unified-harness-surface-pr4-pydantic-ai.md:109
**Cache tokens dropped**

The plan tells the implementer to populate `TurnUsage.cached_input_tokens` only from a same-named pydantic-ai field. Current pydantic-ai `RunUsage` exposes cache input usage as `cache_read_tokens` and `cache_write_tokens`, so following this mapping silently drops cached-token usage even when the run reports it. Please spell out the real mapping, such as combining the cache read/write token fields if that matches Agentex semantics, and add a fixture that asserts cache usage survives normalization.

### Issue 2 of 2
docs/superpowers/plans/2026-06-18-unified-harness-surface-pr4-pydantic-ai.md:156
**Tracing context has no source**

This step says to resolve `trace_id` and `parent_span_id` "the same way the module does today", but `_pydantic_ai_async.py` currently does not read any tracing context vars. Current callers pass those values through `tracing_handler`; if the implementation preserves the signature but builds `UnifiedEmitter` with no actual trace context, default tracing is disabled and existing callers that still pass `tracing_handler` silently lose their tool spans. Please specify how to bridge the preserved handler into the emitter, or add explicit context access, with a regression test for an existing caller that passes a handler.

_{Reviews (2): Last reviewed commit: "docs: PR 4 implementation plan — pydanti..." | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

[greptile-apps]

Cache tokens dropped

The plan tells the implementer to populate TurnUsage.cached_input_tokens only from a same-named pydantic-ai field. Current pydantic-ai RunUsage exposes cache input usage as cache_read_tokens and cache_write_tokens, so following this mapping silently drops cached-token usage even when the run reports it. Please spell out the real mapping, such as combining the cache read/write token fields if that matches Agentex semantics, and add a fixture that asserts cache usage survives normalization.

Artifacts

Repro: Python script constructing pydantic-ai RunUsage and applying same-name-only cache-token normalization

• Contains supporting evidence from the run (text/x-python; charset=utf-8).

Repro: failing script output showing cache_read_tokens and cache_write_tokens are dropped by cached_input_tokens-only mapping

• Keeps the command output available without making the summary code-heavy.

_{Ran code and verified through T-Rex}

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/superpowers/plans/2026-06-18-unified-harness-surface-pr4-pydantic-ai.md
Line: 109

Comment:
**Cache tokens dropped**

The plan tells the implementer to populate `TurnUsage.cached_input_tokens` only from a same-named pydantic-ai field. Current pydantic-ai `RunUsage` exposes cache input usage as `cache_read_tokens` and `cache_write_tokens`, so following this mapping silently drops cached-token usage even when the run reports it. Please spell out the real mapping, such as combining the cache read/write token fields if that matches Agentex semantics, and add a fixture that asserts cache usage survives normalization.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Tracing context has no source

This step says to resolve trace_id and parent_span_id "the same way the module does today", but _pydantic_ai_async.py currently does not read any tracing context vars. Current callers pass those values through tracing_handler; if the implementation preserves the signature but builds UnifiedEmitter with no actual trace context, default tracing is disabled and existing callers that still pass tracing_handler silently lose their tool spans. Please specify how to bridge the preserved handler into the emitter, or add explicit context access, with a regression test for an existing caller that passes a handler.

Artifacts

Repro: focused harness that imports the pydantic-ai async streamer and exercises handler-derived tracing context

• Contains supporting evidence from the run (text/x-python; charset=utf-8).

Repro: harness output showing absent context-var reads and handler-sourced tool span tracing

• Keeps the command output available without making the summary code-heavy.

_{Ran code and verified through T-Rex}

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/superpowers/plans/2026-06-18-unified-harness-surface-pr4-pydantic-ai.md
Line: 156

Comment:
**Tracing context has no source**

This step says to resolve `trace_id` and `parent_span_id` "the same way the module does today", but `_pydantic_ai_async.py` currently does not read any tracing context vars. Current callers pass those values through `tracing_handler`; if the implementation preserves the signature but builds `UnifiedEmitter` with no actual trace context, default tracing is disabled and existing callers that still pass `tracing_handler` silently lose their tool spans. Please specify how to bridge the preserved handler into the emitter, or add explicit context access, with a regression test for an existing caller that passes a handler.

How can I resolve this? If you propose a fix, please make it concise.