feat(harness): public adk facade + docs for the unified harness surface (PR 9)

[declan-scale]

Summary

• Public import path (AGX1-375): re-exports UnifiedEmitter, SpanTracer, TurnUsage, TurnResult, HarnessTurn, StreamTaskMessage, OpenSpan, CloseSpan, SpanSignal from agentex.lib.adk — additive, consistent with how convert_pydantic_ai_to_agentex_events / convert_langgraph_to_agentex_events are already exported. Agent authors can now do from agentex.lib.adk import UnifiedEmitter, TurnUsage, ... without touching internal core.harness paths.
• Docs (adk/docs/harness.md): covers the canonical StreamTaskMessage* stream, convert_<harness>_to_agentex_events tap contract, HarnessTurn protocol, UnifiedEmitter (yield_turn vs auto_send_turn delivery modes), tracing-on-by-default semantics, TurnUsage fields, TurnResult, span derivation rules, and per-channel usage examples.
• Dead-code sweep: nothing safe to remove in this branch. The _async modules (_pydantic_ai_async, _langgraph_async) still use direct adk.streaming calls — those migrations are separate PRs. The _*_tracing handlers are not present on this branch.

Test plan

• uv run --all-packages --all-extras pytest tests/lib/core/harness/ -q — 45 passed
• uv run --all-packages python -c "from agentex.lib.adk import UnifiedEmitter" — OK
• uv run ruff check src/agentex/lib/adk/__init__.py — all checks passed
• uv run pyright src/agentex/lib/adk/__init__.py — 0 errors

🤖 Generated with Claude Code

Greptile Summary

• Adds public ADK re-exports for unified harness classes and stream/message types.
• Documents the canonical harness event stream, tap contract, turn protocol, emitter delivery modes, usage/result fields, and tracing behavior.
• Provides examples for yield-based and auto-send harness integration paths.

Confidence Score: 4/5

The import facade change is small, but the public API remains incomplete for the documented harness integration flow.

The review is based on a narrow diff with one clear public API gap in the newly added exports. Runtime verification was limited by local environment constraints, but the code-level issue is straightforward in the facade export list.

src/agentex/lib/adk/init.py

T-Rex Logs

What T-Rex did

• Ran a focused Python import check script for the ADK facade and implementation modules; the run was blocked because temporalio was missing before the facade export check, and the ADK package could not install in the current Python 3.11 environment.
• Observed the public ADK facade import progression from failure to success: initial ImportError cannot import name 'UnifiedEmitter' from agentex.lib.adk, followed by a successful import where all claimed names are imported and the process exited with code 0.
• Ran the harness docs-coverage check; the before state showed a missing_document result on the base worktree, while the after state shows the head worktree with EXISTS True, LINE_COUNT 196, all required terms present, and RESULT ok_all_required_terms_present.

_{Ran code and verified through T-Rex}

Comments Outside Diff (1)

1. src/agentex/lib/adk/__init__.py, line 16-22 (link)

   Incomplete public facade

   The new facade exports UnifiedEmitter and the shared harness types, but it still leaves PydanticAITurn, LangGraphTurn, and OpenAITurn behind private module paths. Agent authors can import the emitter and taps from agentex.lib.adk, but attempts to use the same public path for the turn wrappers needed by yield_turn() or auto_send_turn() fail with ImportError. Please re-export the existing turn classes and usage helpers so each shipped harness has a complete public import path.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: src/agentex/lib/adk/__init__.py
   Line: 16-22
   
   Comment:
   **Incomplete public facade**
   
   The new facade exports `UnifiedEmitter` and the shared harness types, but it still leaves `PydanticAITurn`, `LangGraphTurn`, and `OpenAITurn` behind private module paths. Agent authors can import the emitter and taps from `agentex.lib.adk`, but attempts to use the same public path for the turn wrappers needed by `yield_turn()` or `auto_send_turn()` fail with `ImportError`. Please re-export the existing turn classes and usage helpers so each shipped harness has a complete public import path.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

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

---

### Issue 1 of 1
src/agentex/lib/adk/__init__.py:16-22
**Incomplete public facade**

The new facade exports `UnifiedEmitter` and the shared harness types, but it still leaves `PydanticAITurn`, `LangGraphTurn`, and `OpenAITurn` behind private module paths. Agent authors can import the emitter and taps from `agentex.lib.adk`, but attempts to use the same public path for the turn wrappers needed by `yield_turn()` or `auto_send_turn()` fail with `ImportError`. Please re-export the existing turn classes and usage helpers so each shipped harness has a complete public import path.

_{Reviews (9): Last reviewed commit: "docs(harness-cleanup): move PR 10 plan o..." | Re-trigger Greptile}

[danielmillerp]

nice