fix(harness): harden Claude Code + OpenAI taps and span tracing

[declan-scale]

Summary

Hardens the unified-harness taps (Claude Code stream-json + OpenAI Agents sync converter) and the shared span-tracing path. Started from the three P1 Greptile findings on PR #443's new OpenAI sync converter, then grew to cover several real defects surfaced while running the golden agent against this branch locally (duplicate messages, missing reasoning traces). Also documents migrating off the legacy Temporal claude_agents plugin.

All fixes are behavior-only (no public API changes) and land on the unified harness shared by every harness (LangGraph, Pydantic-AI, OpenAI Agents, Claude Code, Codex).

Fixes

OpenAI Agents sync converter (_openai_sync.py)

• Bad tool args no longer abort the turn — raw tool-call arguments flow through a defensive _safe_parse_arguments helper. Malformed/truncated JSON is preserved under raw, non-dict JSON under value, and non-string/non-dict payloads (lists, scalars, SDK objects) are serialized or wrapped — always returning a dict so ToolRequestContent.arguments (Dict[str, object]) never rejects it and kills the run. (Greptile P1 + follow-up.)
• Reasoning streams no longer hang — completed reasoning content/summary items emit a matching StreamTaskMessageDone, so UnifiedEmitter.auto_send releases the context. (Greptile P1.)
• Text no longer collides with reasoning — every new text item_id reserves a fresh message index, so a final answer can't overwrite the reasoning message on reasoning-model streams. (Greptile P1.)

OpenAI Agents Temporal model (temporal_streaming_model.py)

• Hosted-tool response shape aligned — hosted/server-side tool responses emit content as a plain string, matching the function-tool response path so both render identically. (Greptile summary flag.)

Claude Code tap (_claude_code_sync.py)

• No more duplicate text/reasoning messages — dedup of streamed-vs-materialized blocks is now content-based (record the streamed block's text, consume on match) instead of numeric block index, which couldn't distinguish "already-streamed block materializing in a later envelope" from "a new turn's block at the same index".
• Interleaved materialized blocks deduped — Claude can emit the materialized assistant envelope mid-stream (before content_block_stop). When a same-type streamed block is still open and its partial buffer is a prefix of the materialized text, the materialized copy is suppressed.

Span tracing (span_derivation.py, tracer.py)

• Reasoning text now recorded on derived reasoning spans — SpanDeriver opened reasoning spans with empty input and output=None, so reasoning text never reached the trace. It now accumulates ReasoningContentDelta / ReasoningSummaryDelta text (and any text seeded on the Start content) and records it as the span output. Affects every harness that streams reasoning.
• Non-dict span input/output coerced — the SGP spans API requires input/output to be objects; a scalar/string payload is 422-rejected and the span silently dropped by the async processor. This is exactly why reasoning spans (string output) showed up as "0 reasoning traces" in the golden agent while tool spans (dict output) survived. The tracer now wraps any non-dict payload ({"output": ...} / {"input": ...}); dicts and None pass through.

Docs

• adk/docs/migration-0.16.0.md — migration guide for agentex-client 0.16.0 / agentex-sdk 0.15.0: removed LangGraph/Pydantic-AI tracing handlers, private _modules path moves, OpenAI harness facade relocation, the new run_turn Temporal entry point, the defect fixes above, and §6: migrating off the legacy Temporal claude_agents plugin to the unified harness tap. Linked from adk/docs/harness.md. Deprecation note added to the plugin module docstring. (Follow-up tracked in AGX1-402.)

Tests

• New: tests/lib/adk/test_openai_sync.py (arg parsing + reasoning/text sequencing), reasoning-span tests in test_span_derivation.py, content/interleaved dedup tests in test_claude_code_sync.py, payload-coercion tests in test_tracer.py.
• Full harness + Claude Code + OpenAI suites green; lint/format clean.

Verification

Confirmed against the golden agent on this branch: DEDUP-HIT prefix (skip) fires (duplicate reasoning gone), and the SGP 422 on string span output is the confirmed cause of the missing reasoning traces (now coerced). Worker must be restarted to pick up the editable install.

🤖 Generated with Claude Code

Greptile Summary

This PR hardens the OpenAI and unified harness paths for streaming, tracing, and migration. The main changes are:

• Safer OpenAI sync tool-argument parsing and reasoning message closure.
• Fresh text message indexing after reasoning and tool output.
• Hosted-tool response content aligned with function-tool responses.
• Reasoning text captured in derived spans and span payloads normalized for SGP tracing.
• Claude Code streamed/materialized block dedup updated to use delivered content.
• Migration documentation added for the 0.16.0 client and 0.15.0 SDK release.

Confidence Score: 5/5

The changes are focused, covered by targeted tests, and do not leave known merge-blocking issues.

The updated OpenAI sync conversion, hosted-tool response shape, tracing normalization, and Claude Code dedup behavior are exercised by the added and updated test coverage, with no accepted code issues remaining.

T-Rex Logs

What T-Rex did

• T-Rex ran tests to exercise malformed JSON handling and ToolRequestContent arguments validation, producing payloads for malformed JSON and for a valid [1, 2] input, and finishing with exit code 0.
• The reasoning-index traces were inspected to confirm that text start and delta routing stay anchored at index 1, with text_fresh_index reported as false in both before and after cases.
• The hosted tool response flow was observed to transition from a dict payload to a string payload, with shapes_align flipping from false to true, and the related artifacts capture the full command context and JSON output.

_{Ran code and verified through T-Rex}

Comments Outside Diff (1)

1. General comment

   OpenAI sync text items still collide with reasoning message indexes

   • Bug
     • In the head run, a completed reasoning item followed by a separate text item still produces both StreamTaskMessageStart events at index 1, with the text delta also routed to index 1. The validation contract requires each new text item_id after reasoning to reserve a fresh message index so final answer text does not collide with the reasoning context.
   • Cause
     • The text-delta branch in src/agentex/lib/adk/_modules/_openai_sync.py only increments message_index for a new text item_id when seen_tool_output is true. For a reasoning-only stream, the branch falls through to item_id_to_index[item_id] = message_index, reusing the current reasoning index.
   • Fix
     • In the ResponseTextDeltaEvent handling for any unseen text item_id, increment message_index before assigning item_id_to_index[item_id], regardless of seen_tool_output, or otherwise detect prior reasoning item allocation and reserve a new index for the text item.

   _{Ran code and verified through T-Rex}

_{Reviews (5): Last reviewed commit: "fix(harness): coerce non-dict span input..." | Re-trigger Greptile}