[RFC 005] 2/4: foundation types for agentic harnesses

[splusq]

Stack for RFC 005 — 2 of 4. Depends on #1097.

Cross-fork PRs cannot chain bases, so this targets main and its diff includes #1097. Review the top commit only: 01bb0ce.

1. 1/4 — package split ([RFC 005] 1/4: split openenv.core.harness into a package #1097)
2. 2/4 — this PR: foundation types
3. 3/4 — HarnessEnvironment + subprocess + tool bridge
4. 4/4 — production /harness route + mode wiring

---

What

The type layer for wrapping an external agentic harness (Claude Code, OpenClaw, Codex) as an OpenEnv environment. Types plus unit tests only — nothing runs a harness yet, that is 3/4.

module	contents
config.py	HarnessConfig, HarnessTransport
events.py	HarnessEventType, HarnessEvent, HarnessResponse, events_to_metadata()
adapter.py	AgenticHarnessAdapter ABC + error hierarchy
tools.py	resolve_tool_conflicts()

Deviations from the RFC text, and why

The RFC has drifted from the code in a few places. Flagging each rather than silently following either one:

1. ToolDefinition does not exist. The type is Tool (env_server/mcp_types.py, name/description/input_schema). Reused rather than duplicated, so inject_tools takes list[Tool]. Same for RESERVED_TOOL_NAMES, which resolve_tool_conflicts re-checks as defense in depth even though MCPEnvironment.__init__ already validates.
2. send_message() is concrete, not abstract. Streaming is the single abstract turn primitive; send_message() drains it and pulls the response/done off the terminal event. This removes the same boilerplate from every concrete adapter, and turns "the stream ends with TURN_COMPLETE" from a convention into an enforced contract — a stream that ends without it raises rather than silently yielding an empty response.
3. events_to_metadata() is new. Observation.metadata gets serialized over the wire, so raw pydantic events in metadata["turn_events"] would not survive. This is the one sanctioned way to put events there; 3/4 uses it and asserts the result is json.dumps-able.

Naming

The ABC is AgenticHarnessAdapter because HarnessAdapter is taken by the rollout layer (see the question at the end of #1097 — if we rename that layer, this becomes plain HarnessAdapter, matching the RFC).

Needs a decision: session_timeout_s

The RFC's field comment says "Max time for a single session/episode" but its temporal-semantics section says it bounds one turn. I implemented and documented the per-turn reading, since an episode-wide bound is not enforceable by an adapter that only sees one turn at a time. Flagging explicitly for sign-off.

Verification

82 passed

test_agentic_harness_types.py covers config defaults/validation, event JSON round-trip, events_to_metadata serializability, all six resolve_tool_conflicts branches (passthrough, env_ prefixing with schema preserved, reserved-name rejection, duplicate rejection, and both ambiguity cases where the prefixed name is also taken), and the default send_message including the missing-TURN_COMPLETE error. Back-compat and rollout suites still green. Lint clean.

---

Note

Medium Risk
Large public-surface refactor (new exports + module split) with explicit back-compat tests; behavior change risk is low because this PR adds types only, though mistaken imports of rollout internals could break if re-exports drift.

Overview
Adds the RFC 005 turn-based agentic harness type layer alongside the existing trainer rollout API, without running external harnesses yet.

Package layout: Trainer rollout code moves from harness/__init__.py into harness/rollout.py. The package root becomes a thin facade that documents both layers and re-exports rollout symbols (including private _resolve_env_reward for back-compat). collect now imports rollout types from .rollout.

New modules: HarnessConfig / HarnessTransport; turn events (HarnessEvent, HarnessResponse, HarnessClientMessage) plus events_to_metadata() for wire-safe observation metadata; AgenticHarnessAdapter with streaming as the abstract turn primitive and a concrete send_message() that requires a terminal TURN_COMPLETE event; resolve_tool_conflicts() for env vs harness tool names using existing Tool / RESERVED_TOOL_NAMES.

Tests: Unit coverage for config, events, tool conflict resolution, and default send_message; rollout re-export and distinct-ABC back-compat checks.

^{Reviewed by Cursor Bugbot for commit f52d608. Bugbot is set up for automated code reviews on this repo. Configure here.}

[bot-ci-comment]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.