feat(harness): unified harness surface — foundation (span derivation, delivery adapters, emitter)

[declan-scale]

What this is

Foundation (PRs 1–3 of the rollout) for a unified harness tracing/message-emitting surface: the Agentex StreamTaskMessage* stream is the single source of truth, and shared harness-independent machinery derives spans from it and delivers it over both channels:

• yield — pass the canonical stream through to the caller (sync HTTP ACP agents),
• auto-send — push to the task stream via adk.streaming (async + temporal agents, from inside an activity),

with tracing on by default (derived from the same stream) and overridable, and a unified TurnUsage/TurnResult shape for per-harness usage normalization.

Design: docs/superpowers/specs/2026-06-18-unified-harness-surface-design.md
Plan: docs/superpowers/plans/2026-06-18-unified-harness-surface-foundation.md

What's in src/agentex/lib/core/harness/

• types.py — StreamTaskMessage, OpenSpan/CloseSpan/SpanSignal, TurnUsage, TurnResult, HarnessTurn protocol.
• span_derivation.py — SpanDeriver: pure reducer (no adk dep), canonical stream → span signals. Tool span opens on the Done of a ToolRequestContent index, closes on the matching ToolResponseContent by tool_call_id; reasoning span open-on-Start / close-on-Done; parallel-safe; flush() closes unclosed spans.
• tracer.py — SpanTracer: best-effort adapter from span signals to adk.tracing (never raises; overridable; guarded make_logger).
• yield_delivery.py / auto_send.py — the two delivery adapters (both feed the same SpanDeriver/SpanTracer; finally-flush on early close/error).
• emitter.py — UnifiedEmitter: ties trace context + delivery + usage; default-on/overridable tracing; injectable tracing/streaming backends.
• conformance/ — shared conformance scaffold each future harness tap registers fixtures with.
• .github/workflows/harness-integration.yml — conformance CI job (via ./scripts/test) + an if: false live-matrix placeholder enabled by the migration PRs.

Scope / what's NOT here

Per-harness migration (pydantic-ai / langgraph / openai) and parser taps (claude-code / codex), plus their 3 e2e test agents each (sync/async/temporal), are future migration PRs (4–8) — not in this branch.

Quality gates

• 30 tests passing on Python 3.12 + 3.13 (via ./scripts/test tests/lib/core/harness/).
• pyright clean (0 errors/warnings), no # type: ignore in the package.
• Each task spec- + quality-reviewed; final whole-branch review passed with no Critical issues.

Follow-ups (filed)

• AGX1-373 (High) — make conformance assert true yield-vs-auto-send equivalence + reconcile Full tool-message wire shape (blocks migration backward-compat claims).
• AGX1-374 (Medium) — auto_send reasoning + mixed-ordering tests.
• AGX1-375 (Medium) — expose the surface via the public adk facade before the first consumer migration.
• AGX1-376 (Low) — widen CI paths to agentex.types; SpanTracer duplicate-open guard.
• AGX1-371 — deferred optional is_error on ToolResponseContent (tool-span error status).

Note: total diff is ~3k lines but ~1.6k of that is the spec + plan docs; the package code + tests + CI is ~1.4k. Reviewable per-commit (one commit per plan task).

🤖 Generated with Claude Code

Greptile Summary

This PR introduces the foundation for a unified harness tracing/message-emitting surface: a StreamTaskMessage*-based canonical stream is the single source of truth, and shared machinery derives spans from it and delivers it via two channels — yield (sync HTTP ACP) and auto-send (async/Temporal activities) — with tracing on by default and a unified TurnUsage/TurnResult shape.

• span_derivation.py — pure SpanDeriver reducer with dual open paths: Start+Delta+Done (streamed tool requests) and Full(ToolRequestContent) (LangGraph-style); parallel-safe via tool_call_id keying; flush() closes any unclosed spans on early exit.
• auto_send.py — index-keyed ctx_map routing, per-context error-guarded _close_all(), last-segment final_text semantics, and correct finally-flush; all previously flagged gaps (single-slot ctx, eager usage read, missing ToolRequest Start delivery) are resolved in this HEAD.
• emitter.py — UnifiedEmitter correctly reads turn.usage() after auto_send exhausts the stream, not eagerly.

Confidence Score: 5/5

Safe to merge; all delivery paths have corresponding tests and the foundational gaps called out in earlier review rounds have been addressed in this HEAD.

The core machinery — index-keyed context routing, per-context error-guarded teardown, correct post-exhaustion usage read, dual span-open paths in SpanDeriver, and finally-flush on early close — all work correctly and are well-covered by 30 tests across 6 modules. The only items worth flagging are the conformance test's idempotency-only assertion (correctness verification is deferred to AGX1-373) and the string-comparison reasoning guard in SpanDeriver.

tests/lib/core/harness/conformance/test_conformance.py — conformance suite currently provides no signal-correctness coverage, only idempotency.

Important Files Changed

Filename	Overview
src/agentex/lib/core/harness/types.py	Defines core types: StreamTaskMessage union, OpenSpan/CloseSpan/SpanSignal, TurnUsage, TurnResult, HarnessTurn protocol. Clean dataclass/Pydantic design; runtime-checkable protocol for structural duck-typing.
src/agentex/lib/core/harness/span_derivation.py	Pure stateful reducer converting StreamTaskMessage events to span open/close signals. Handles both Start+Delta+Done (streamed) and Full (LangGraph-style) tool-request paths. Minor: reasoning detection uses string comparison (content.type == "reasoning") rather than isinstance, which is fragile if the type string changes.
src/agentex/lib/core/harness/auto_send.py	Async delivery adapter: index-keyed ctx_map routing, per-context error-guarded _close_all(), last-segment final_text semantics, Full(TextContent) contributing to final_text, and correct streaming of Start(ToolRequestContent). All previously flagged gaps addressed in current HEAD.
src/agentex/lib/core/harness/emitter.py	UnifiedEmitter facade wiring trace context + delivery mode. auto_send_turn correctly calls turn.usage() after auto_send consumes the stream; the previously flagged eager-evaluation bug is resolved.
src/agentex/lib/core/harness/tracer.py	Best-effort span adapter to adk.tracing; correctly swallows tracing errors, records is_error via span.data mutation. Duplicate-open span orphan behavior is documented and tracked in AGX1-376.
src/agentex/lib/core/harness/yield_delivery.py	Straightforward passthrough async generator with try/finally flush; correctly handles early aclose() via GeneratorExit triggering the finally block.
tests/lib/core/harness/conformance/test_conformance.py	Conformance test asserts only idempotency (derive_all(x)==derive_all(x)), not correctness of the actual span signals. The registered builtin-single-tool fixture never has its expected signals verified. Tracked in AGX1-373 but currently provides near-zero regression value.
.github/workflows/harness-integration.yml	New CI job delegating to ./scripts/test (preserving exact multi-Python-version invocation); placeholder live-matrix job with if:false is intentional and harmless.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Harness as Harness tap
    participant Emitter as UnifiedEmitter
    participant YD as yield_events
    participant AS as auto_send
    participant SD as SpanDeriver
    participant ST as SpanTracer
    participant Streaming as adk.streaming

    Note over Emitter: yield_turn (sync HTTP ACP)
    Harness->>Emitter: yield_turn(turn)
    Emitter->>YD: yield_events(turn.events, tracer)
    loop each event
        YD->>SD: observe(event)
        SD-->>YD: [SpanSignals]
        YD->>ST: handle(signal)
        YD-->>Emitter: yield event
    end
    YD->>SD: flush()
    SD-->>YD: [unclosed signals]
    YD->>ST: handle(signal)

    Note over Emitter: auto_send_turn (async/Temporal)
    Harness->>Emitter: auto_send_turn(turn)
    Emitter->>AS: auto_send(turn.events, ...)
    loop each event
        AS->>SD: observe(event)
        SD-->>AS: [SpanSignals]
        AS->>ST: handle(signal)
        AS->>Streaming: streaming_task_message_context(...)
        Streaming-->>AS: ctx
        AS->>Streaming: ctx.stream_update(delta) / ctx.close()
    end
    AS->>SD: flush()
    AS-->>Emitter: TurnResult(final_text)
    Emitter->>Harness: "result (with result.usage = turn.usage())"

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Harness as Harness tap
    participant Emitter as UnifiedEmitter
    participant YD as yield_events
    participant AS as auto_send
    participant SD as SpanDeriver
    participant ST as SpanTracer
    participant Streaming as adk.streaming

    Note over Emitter: yield_turn (sync HTTP ACP)
    Harness->>Emitter: yield_turn(turn)
    Emitter->>YD: yield_events(turn.events, tracer)
    loop each event
        YD->>SD: observe(event)
        SD-->>YD: [SpanSignals]
        YD->>ST: handle(signal)
        YD-->>Emitter: yield event
    end
    YD->>SD: flush()
    SD-->>YD: [unclosed signals]
    YD->>ST: handle(signal)

    Note over Emitter: auto_send_turn (async/Temporal)
    Harness->>Emitter: auto_send_turn(turn)
    Emitter->>AS: auto_send(turn.events, ...)
    loop each event
        AS->>SD: observe(event)
        SD-->>AS: [SpanSignals]
        AS->>ST: handle(signal)
        AS->>Streaming: streaming_task_message_context(...)
        Streaming-->>AS: ctx
        AS->>Streaming: ctx.stream_update(delta) / ctx.close()
    end
    AS->>SD: flush()
    AS-->>Emitter: TurnResult(final_text)
    Emitter->>Harness: "result (with result.usage = turn.usage())"

Loading

Comments Outside Diff (1)

1. General comment

   UnifiedEmitter ignores duck-typed tracer override and constructs real SpanTracer

   • Bug
     • Passing a custom tracer object with an async handle() method to UnifiedEmitter(..., tracer=custom_tracer) did not use that object. Instead, the emitter fell through to default construction of SpanTracer, which attempted to import the real ADK stack and failed in this environment with ModuleNotFoundError: No module named 'temporalio'. This contradicts the requested override behavior for tracing in the unified emitter surface.
   • Cause
     • src/agentex/lib/core/harness/emitter.py only accepts overrides when isinstance(tracer, SpanTracer) is true. A valid injected/duck-typed tracer object is ignored, causing fallback to SpanTracer(...) whenever trace_id is truthy.
   • Fix
     • Relax the override branch to accept any non-None, non-False tracer object that implements the expected handle(signal) contract, or define and use a runtime-checkable tracer Protocol instead of requiring isinstance(tracer, SpanTracer).

   _{Ran code and verified through T-Rex}

_{Reviews (12): Last reviewed commit: "feat(harness): mark derived tool spans a..." | Re-trigger Greptile}

[declan-scale]

@greptile review

[declan-scale]

@greptile review

[danielmillerp]

On AGX1-371 (no is_error/status on ToolResponseContent) — flagging this as more than a nice-to-have for the golden-agent adoption (#422).

Golden agent's ToolCompleted carries is_error today, so a derived tool span can mark failure. Without that field, golden agent loses tool-error status the moment it moves onto this surface — i.e. adoption is a regression on tracing fidelity, not a clean swap.

Since it's an additive optional (is_error: bool | None), can we pull it into this stack rather than deferring? Would rather land it here than block #422 on it later.

[declan-scale]

On AGX1-371 (no is_error/status on ToolResponseContent) — flagging this as more than a nice-to-have for the golden-agent adoption (#422).

Golden agent's ToolCompleted carries is_error today, so a derived tool span can mark failure. Without that field, golden agent loses tool-error status the moment it moves onto this surface — i.e. adoption is a regression on tracing fidelity, not a clean swap.

Since it's an additive optional (is_error: bool | None), can we pull it into this stack rather than deferring? Would rather land it here than block #422 on it later.

Will land this in scale-agentex and then have a follow up here.