[RFC 005] 2/4: foundation types for agentic harnesses - #1098
Open
splusq wants to merge 4 commits into
Open
Conversation
Moves the trainer-side rollout API out of the package __init__ and into `openenv.core.harness.rollout`, leaving __init__ as a re-export shim. No behavior change: every name previously importable from `openenv.core.harness` still is, and is the same object. The module was ~730 lines living directly in __init__ with a docstring noting it sat outside the stable surface "while RFC 005 is still under review". Splitting it now makes room for the RFC 005 turn-based agentic harness layer to land in sibling modules instead of growing the __init__ further. Also re-exports the private `_resolve_env_reward`, which tests/scripts/test_browsergym_harness_eval_examples.py imports from the package root, and points `collect.py` at `.rollout` directly rather than importing from its own package. Consumers left untouched and verified: `openenv collect`, pi_env, opencode_env, browsergym_env, reasoning_gym_env, openspiel_env. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Adds the type layer for wrapping an external agentic harness (Claude Code, OpenClaw, Codex) as an OpenEnv environment. No runtime behavior yet — this PR is types plus their unit tests. - `config.py`: `HarnessConfig` / `HarnessTransport`. `session_timeout_s` is documented as bounding ONE conversational turn, per the RFC's temporal-semantics section (the field comment in the RFC is ambiguous; flagging for reviewer sign-off). - `events.py`: `HarnessEventType` / `HarnessEvent` / `HarnessResponse`, plus `events_to_metadata()`, the sanctioned JSON-safe path for putting events into `Observation.metadata` so they survive wire serialization. - `adapter.py`: `AgenticHarnessAdapter` ABC and its error hierarchy. - `tools.py`: `resolve_tool_conflicts()` for the RFC's tool-name collision rules (`env_` prefixing, error on ambiguity). Two deliberate deviations from the RFC text, both because the RFC is stale against the code: 1. The RFC's `ToolDefinition` does not exist; the type is `Tool` (`env_server/mcp_types.py`), reused here rather than duplicated. Same for `RESERVED_TOOL_NAMES`, which `resolve_tool_conflicts` re-checks as defense in depth. 2. `send_message()` is concrete rather than abstract. Streaming is the single abstract turn primitive and `send_message()` drains it, which removes duplication from every concrete adapter and makes the terminal TURN_COMPLETE event an enforced contract instead of a convention. The ABC is named `AgenticHarnessAdapter` to avoid colliding with the rollout layer's existing `HarnessAdapter`. Worth discussing whether to rename the rollout classes instead and reclaim the RFC's plain names -- see the PR description. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
splusq
marked this pull request as ready for review
August 31, 2026 21:22
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stack for RFC 005 — 2 of 4. Depends on #1097.
Cross-fork PRs cannot chain bases, so this targets
mainand its diff includes #1097. Review the top commit only:01bb0ce.HarnessEnvironment+ subprocess + tool bridge/harnessroute + mode wiringWhat
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.
config.pyHarnessConfig,HarnessTransportevents.pyHarnessEventType,HarnessEvent,HarnessResponse,events_to_metadata()adapter.pyAgenticHarnessAdapterABC + error hierarchytools.pyresolve_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:
ToolDefinitiondoes not exist. The type isTool(env_server/mcp_types.py,name/description/input_schema). Reused rather than duplicated, soinject_toolstakeslist[Tool]. Same forRESERVED_TOOL_NAMES, whichresolve_tool_conflictsre-checks as defense in depth even thoughMCPEnvironment.__init__already validates.send_message()is concrete, not abstract. Streaming is the single abstract turn primitive;send_message()drains it and pulls the response/doneoff the terminal event. This removes the same boilerplate from every concrete adapter, and turns "the stream ends withTURN_COMPLETE" from a convention into an enforced contract — a stream that ends without it raises rather than silently yielding an empty response.events_to_metadata()is new.Observation.metadatagets serialized over the wire, so raw pydantic events inmetadata["turn_events"]would not survive. This is the one sanctioned way to put events there; 3/4 uses it and asserts the result isjson.dumps-able.Naming
The ABC is
AgenticHarnessAdapterbecauseHarnessAdapteris taken by the rollout layer (see the question at the end of #1097 — if we rename that layer, this becomes plainHarnessAdapter, matching the RFC).Needs a decision:
session_timeout_sThe 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
test_agentic_harness_types.pycovers config defaults/validation, event JSON round-trip,events_to_metadataserializability, all sixresolve_tool_conflictsbranches (passthrough,env_prefixing with schema preserved, reserved-name rejection, duplicate rejection, and both ambiguity cases where the prefixed name is also taken), and the defaultsend_messageincluding the missing-TURN_COMPLETEerror. Back-compat and rollout suites still green. Lint clean.Note
Low Risk
Types and re-exports only—no subprocess or harness runtime yet—and existing rollout/collect imports are preserved with explicit back-compat tests.
Overview
Adds the RFC 005 type layer for wrapping external agentic harnesses (e.g. OpenClaw, Claude Code) as OpenEnv environments, alongside the existing trainer-side rollout API now living in
openenv.core.harness.rollout.New modules expose
HarnessConfig/HarnessTransport, turnHarnessEvent/HarnessResponseschemas (plusHarnessClientMessagefor the future/harnessWebSocket),AgenticHarnessAdapterwith a concretesend_message()built on streamingTURN_COMPLETE, harness-specific errors,events_to_metadata()for wire-safe observation metadata, andresolve_tool_conflicts()to prefix env tools that clash with harness builtins.openenv.core.harnessre-exports both layers;collectimports rollout symbols from.rollout;_resolve_env_rewardstays on the package root for back-compat.Unit tests cover config validation, event serialization, tool conflict branches, default
send_messagebehavior, and rollout re-export guarantees.Reviewed by Cursor Bugbot for commit 933e113. Bugbot is set up for automated code reviews on this repo. Configure here.