[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

Low Risk
New public types and re-exports only; no subprocess, routing, or changes to rollout/collect behavior.

Overview
Adds the RFC 005 type layer for turn-based external agentic harnesses (OpenClaw, Claude Code, etc.) alongside the existing trainer-side rollout API, without running a harness yet.

New modules define HarnessConfig / HarnessTransport, normalized HarnessEvent streams and HarnessResponse, AgenticHarnessAdapter (lifecycle, tool injection with list[Tool], streaming turns) with a concrete send_message() that requires a terminal TURN_COMPLETE event, harness-specific errors, events_to_metadata() for wire-safe observation metadata, and resolve_tool_conflicts() (prefix env_, fail on reserved/duplicate/ambiguous names). openenv.core.harness re-exports these symbols and documents both layers; AgenticHarnessAdapter stays distinct from rollout HarnessAdapter.

Unit tests cover config validation, event serialization, conflict resolution branches, default send_message behavior, and rollout back-compat.

^{Reviewed by Cursor Bugbot for commit a1ea5d3. 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.

[cursor]

Unable to authenticate your request. Please make sure to connect your GitHub account to Cursor. Go to Cursor

[burtenshaw]

LGTM. moving on to 3 and 4