envs/opencode_env: OpenCode coding-agent harness primitive

[adithya-s-k]

Stacked on #471.

Adds envs/opencode_env/, a harness primitive that runs the OpenCode
coding agent inside a sandbox against an OpenAI-compatible LLM endpoint
and exposes it via the ResourceSessionFactory / ResourceSession
contracts from openenv.core.harness.

Functionality

Session + factory

• OpenCodeSession(ResourceSession) implements:
  • initial_messages() -> list[Message] — returns the task instruction
    as the single user message.
  • list_tools() -> list[Tool] — returns []. OpenCode owns its own
    tool loop internally; no tools are exposed to the harness.
  • call_tool(name, arguments) -> ToolResult — returns an error
    ToolResult; direct tool invocation is not supported (by design).
  • verify(transcript, final_state=None) -> VerifyResult — delegates
    to an optional user-supplied verifier callable; defaults to
    VerifyResult(env_reward=None, done=True).
  • close() — kills any background jobs and the sandbox.
• OpenCodeSessionFactory(ResourceSessionFactory) implements:
  • create(task, seed=None, episode_id=None) -> OpenCodeSession —
    creates a sandbox, bootstraps it, optionally starts the proxy,
    optionally starts opencode serve, fires the task, returns the
    session.

Session also exposes agentic-runtime methods (not part of the ABC):
start_agent(), wait_for_completion(timeout_s), abort(),
fetch_trace(), fetch_proxy_trace().

Two drivers

• driver=\"cli\" — runs opencode run --format json as a background
  shell job. Completion is detected by subprocess exit.
• driver=\"serve\" — runs opencode serve --port 4096 --hostname 0.0.0.0 as a background job, exposes the port via
  sandbox.get_host(4096), creates a session through POST /session,
  fires the instruction via POST /session/:id/prompt_async.
  Completion is detected by polling GET /session/status for
  {\"type\": \"idle\"}.

Two modes

• mode=\"black_box\" — opencode talks directly to the caller-supplied
  LLM endpoint.
• mode=\"transparent_proxy\" — a FastAPI/uvicorn proxy runs on
  localhost:7000 inside the sandbox. The primitive rewrites
  opencode.json so the agent talks to the proxy. The proxy:
  • Forces logprobs=true and top_logprobs=N on every forwarded
    chat-completions request.
  • Caps max_tokens / max_completion_tokens to
    proxy_max_tokens_cap.
  • Injects chat_template_kwargs.enable_thinking when
    proxy_disable_thinking is set.
  • Optionally overrides the forwarded model field.
  • Assembles streaming response chunks (content, tool calls,
    per-token logprobs, reasoning) into a per-turn record and writes
    it to proxy_trace.jsonl.

Interception proxy details

• Streams responses to opencode unmodified while simultaneously
  accumulating per-turn state.
• Preserves delta.reasoning from streamed chunks and reassembles it
  as message.reasoning on the final response.
• Emits one JSON-line per LLM turn: {turn_index, request_body, response_body, completion_tokens, per_token_logps, finish_reason, reasoning, latency_s, timestamp}.

Configuration

• OpenCodeConfig (Pydantic) fields:
  • LLM endpoint: provider, base_url, api_key, model,
    request_timeout_ms.
  • Opencode CLI: opencode_version, disabled_tools, enabled_tools,
    system_prompt, extra_opencode_json.
  • CLI invocation: run_format, agent_timeout_s, extra_env,
    extra_setup_shell.
  • Sandbox paths: sandbox_home.
  • Proxy tuning: proxy_max_tokens_cap, proxy_top_logprobs,
    proxy_disable_thinking.
• opencode_runtime.py — pure builder functions called during
  bootstrap: build_opencode_json, build_install_cmd,
  build_run_cmd, build_env_vars, plus path helpers
  (opencode_config_path, instruction_path, agent_log_path,
  system_prompt_path, verifier_reward_path, workdir_path).
• opencode_client.py — OpenCodeServerClient, a typed httpx wrapper
  over the opencode serve HTTP API: create_session, send_message
  (sync), send_prompt_async, list_messages, get_all_status,
  abort, stream_events (sync and async SSE).

Sandbox abstraction

• sandbox/base.py defines a SandboxBackend Protocol (create,
  exec, start_bg, write_text, read_text, get_host, kill)
  plus dataclasses (SandboxHandle, BgJob, ExecResult).
• sandbox/e2b.py provides E2BSandboxBackend, a thin wrapper over
  the E2B Code Interpreter SDK.
• Any backend implementing the Protocol can be passed to
  OpenCodeSessionFactory(backend=...).

Task payload

• OpenCodeTask(instruction, setup_shell=None, upload_files={}, metadata={}) is the payload shape factory.create(task) accepts.
• OpenCodeTask.coerce(value) accepts a bare string, a dict, or an
  existing OpenCodeTask.

Public API

from openenv.envs.opencode_env import (
    OpenCodeConfig,
    OpenCodeSession,
    OpenCodeSessionFactory,
    OpenCodeTask,
    Provider,
    SandboxBackend,
    SandboxHandle,
    E2BSandboxBackend,
    RolloutSummary,
    collect_rollout_summary,
    print_rollout_summary,
)

Tests

envs/opencode_env/tests/, ~40 tests, all runnable offline (no
network, no external secrets):

• test_config.py — pydantic validation.
• test_task.py — OpenCodeTask.coerce variants.
• test_opencode_runtime.py — builder outputs for opencode.json,
  install/run commands, env vars, path helpers.
• test_interception.py — request/response transformations against a
  fake upstream, streaming-chunk assembly, reasoning preservation.
• test_opencode_client.py — serve-API client against mocked HTTP.
• test_sandbox_base.py — Protocol conformance and E2B-key required
  check.
• test_harness.py — end-to-end factory lifecycle against a mock
  sandbox and mock OpenAI endpoint.

File layout

envs/opencode_env/
├── __init__.py
├── README.md
├── pyproject.toml
├── harness.py
├── config.py
├── opencode_runtime.py
├── opencode_client.py
├── interception.py
├── live_watch.py
├── task.py
├── sandbox/
│   ├── __init__.py
│   ├── base.py
│   └── e2b.py
└── tests/
    ├── test_config.py
    ├── test_task.py
    ├── test_opencode_runtime.py
    ├── test_interception.py
    ├── test_opencode_client.py
    ├── test_sandbox_base.py
    └── test_harness.py

Test plan

• pytest envs/opencode_env/tests/ -v passes.

[meta-cla]

Hi @adithya-s-k!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

[greptile-apps]

Greptile Summary

This PR introduces envs/opencode_env/, a harness primitive that runs the OpenCode coding agent inside an E2B sandbox against an OpenAI-compatible LLM endpoint, with two drivers (cli/serve) and two modes (black_box/transparent_proxy with logprob capture). The overall structure is clean and well-tested, but there are three P1 issues in harness.py to address before merge:

• API key in process table (harness.py:594): self._config.api_key is passed directly as a CLI arg to the proxy process, exposing it via ps aux. Use an environment variable instead.
• Premature idle detection (harness.py:233-241): The stable_ticks >= 12 (6 s) heuristic can misfire on thinking/reasoning models with natural pauses, causing verify() to run on an in-progress session.
• get_host outside the SandboxHandle Protocol (harness.py:693-699): driver="serve" silently bypasses the Protocol by accessing sandbox.raw.get_host(), breaking custom backends.

ALIGNMENT FLAG: list_tools() unconditionally returns [] and call_tool() always errors because OpenCode owns its own internal tool loop. This circumvents the "MCP as universal standard" principle (RFC 003 / PRINCIPLES.md) — all agent–environment tooling is opaque to the harness with no MCP surface or observability.

• Principle at stake: MCP as universal standard for agent–environment tool interaction
• The concern: OpenCode's internal tool loop is entirely opaque to the harness
• Suggested reviewer: @darktex

Confidence Score: 3/5

Not safe to merge without addressing the API key exposure and the serve-driver idle-detection false-positive.

Three P1 findings in harness.py: a security invariant violation (credential in process table), a correctness bug (premature idle detection for thinking models), and a broken abstraction for custom backends (get_host outside Protocol). These need resolution before merge.

envs/opencode_env/harness.py requires the most attention for all three P1 issues; envs/opencode_env/sandbox/base.py needs a get_host addition to close the protocol gap.

Security Review

• Credential exposure via process table (harness.py line 594): self._config.api_key is interpolated directly into the proxy shell command as --upstream-api-key <value>, making it visible in ps aux / /proc/<pid>/cmdline within the sandbox. Should be passed via environment variable instead.
• No other credential leakage, injection, or auth/authz issues identified in the changed files.

Important Files Changed

Filename	Overview
envs/opencode_env/harness.py	Core session/factory implementation; contains API key exposure in proxy CLI args (P1 security), fragile idle-detection heuristic for serve driver (P1 logic), and get_host protocol bypass (P1 design).
envs/opencode_env/interception.py	FastAPI proxy for transparent LLM interception; well-structured streaming accumulation, reasoning preservation, and error surfacing.
envs/opencode_env/sandbox/base.py	SandboxHandle/SandboxBackend Protocol definitions; missing get_host method that the serve driver depends on, creating an undocumented protocol extension requirement.
envs/opencode_env/config.py	Pydantic config model; clean, well-documented fields with sensible defaults.
envs/opencode_env/opencode_runtime.py	Pure builder functions for sandbox bootstrap artifacts; no IO coupling, well-tested.
envs/opencode_env/opencode_client.py	Thin typed httpx wrapper over opencode serve HTTP API; straightforward and well-structured.
envs/opencode_env/task.py	Simple Pydantic task model with coerce() helper; clean and well-covered by tests.
envs/opencode_env/live_watch.py	Post-rollout summary helpers; paths are hardcoded to /home/user/... rather than using config.sandbox_home, which could break non-default sandbox layouts.
envs/opencode_env/sandbox/e2b.py	E2B backend implementation; correctly wraps CommandHandle with thread-based timeout, handles CommandExitException cleanly.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant Factory as OpenCodeSessionFactory
    participant Sandbox as SandboxBackend
    participant Proxy as InterceptionProxy (Mode B)
    participant OC as OpenCode CLI/serve
    participant LLM as Upstream LLM

    Caller->>Factory: create(task)
    Factory->>Sandbox: create(timeout_s)
    Factory->>Sandbox: exec(install_cmd)
    Factory->>Sandbox: write_text(opencode.json, instruction.md)

    alt mode=transparent_proxy
        Factory->>Sandbox: start_bg(interception.py)
        Factory->>Sandbox: write_text(opencode.json) rewrite baseURL to proxy
    end

    alt driver=serve
        Factory->>Sandbox: start_bg(opencode serve)
        Factory->>OC: POST /session
        Factory->>OC: POST /session/:id/prompt_async
    else driver=cli
        Factory->>Sandbox: start_bg(opencode run)
    end

    Factory->>Caller: OpenCodeSession

    OC->>Proxy: POST /v1/chat/completions
    Proxy->>LLM: POST /v1/chat/completions (+logprobs)
    LLM-->>Proxy: stream response
    Proxy-->>OC: stream response (logprobs stripped)
    Proxy->>Proxy: write proxy_trace.jsonl

    Caller->>Factory: session.wait_for_completion()
    Note over Factory: CLI: bg_job.wait() / Serve: poll GET /session/status

    Caller->>Factory: session.verify(transcript)
    Caller->>Factory: session.close()
    Factory->>Sandbox: kill()

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: envs/opencode_env/harness.py
Line: 590-596

Comment:
**API key exposed in process table**

`self._config.api_key` is interpolated directly into the shell command as `--upstream-api-key <value>`. Any process listing tool (`ps aux`, `/proc/<pid>/cmdline`) inside or outside the sandbox will expose the upstream API key in plain text. This violates the "No credential exposure" security invariant.

Pass the key via an environment variable instead:
```python
proxy_env = {"UPSTREAM_API_KEY": self._config.api_key}
proxy_cmd = (
    "cd /home/user/proxy && "
    "python interception.py "
    f"--upstream-url {self._config.base_url} "
    "--upstream-api-key $UPSTREAM_API_KEY "  # read from env, not argv
    ...
)
proxy_job = sandbox.start_bg(proxy_cmd, envs=proxy_env)
```
Then update `interception.py`'s CLI parser to fall back to `os.environ.get("UPSTREAM_API_KEY")`.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: envs/opencode_env/harness.py
Line: 231-244

Comment:
**False-idle detection for thinking models**

The `stable_ticks >= 12` heuristic (12 × 0.5 s = 6 s) treats any 6-second gap in new messages as "idle". A reasoning/thinking model (e.g. Qwen3 with `disable_thinking=False`) can pause for tens of seconds between outputting tokens without the session being finished. During these pauses `list_messages` returns the same count, stable_ticks climbs to 12, and `wait_for_completion` returns 0 — causing `verify()` to be called on an in-progress run and potentially reporting incorrect results.

Consider raising the threshold significantly (e.g. `stable_ticks >= 60` → 30 s) or replacing the heuristic with the `GET /event` SSE stream idle signal so completion detection is driven by the server's own state machine rather than a message-count derivative.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: envs/opencode_env/harness.py
Line: 693-699

Comment:
**`get_host` bypasses the SandboxHandle protocol**

`driver="serve"` reaches through `sandbox.raw.get_host()` — a property specific to `E2BSandboxHandle` and absent from the `SandboxHandle` Protocol. Any custom backend that correctly implements the Protocol but does not expose a `.raw` attribute with `get_host` will fail here at runtime with a non-obvious error.

The `SandboxHandle` Protocol should declare a `get_host(port: int) -> str` method (optional, raising `NotImplementedError` by default) so custom backend authors know the contract.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: envs/opencode_env/harness.py
Line: 289-295

Comment:
**`import json` inside a for loop**

`import json as _json` is placed inside the `for` loop body in `fetch_proxy_trace`. Python caches imports so this is not a correctness bug, but it's misleading and would fail a lint pass. Move the import to the top of the file alongside the other standard-library imports.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: envs/opencode_env/harness.py
Line: 707

Comment:
**Module-level import at bottom of file**

`from pathlib import Path` is placed after the class definitions with a `# noqa: E402` suppression. Move this to the top of the file with the other imports.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "test(opencode_env): drop live integratio..." | Re-trigger Greptile}

[greptile-apps]

API key exposed in process table

self._config.api_key is interpolated directly into the shell command as --upstream-api-key <value>. Any process listing tool (ps aux, /proc/<pid>/cmdline) inside or outside the sandbox will expose the upstream API key in plain text. This violates the "No credential exposure" security invariant.

Pass the key via an environment variable instead:

proxy_env = {"UPSTREAM_API_KEY": self._config.api_key}
proxy_cmd = (
    "cd /home/user/proxy && "
    "python interception.py "
    f"--upstream-url {self._config.base_url} "
    "--upstream-api-key $UPSTREAM_API_KEY "  # read from env, not argv
    ...
)
proxy_job = sandbox.start_bg(proxy_cmd, envs=proxy_env)

Then update interception.py's CLI parser to fall back to os.environ.get("UPSTREAM_API_KEY").

Prompt To Fix With AI

This is a comment left during a code review.
Path: envs/opencode_env/harness.py
Line: 590-596

Comment:
**API key exposed in process table**

`self._config.api_key` is interpolated directly into the shell command as `--upstream-api-key <value>`. Any process listing tool (`ps aux`, `/proc/<pid>/cmdline`) inside or outside the sandbox will expose the upstream API key in plain text. This violates the "No credential exposure" security invariant.

Pass the key via an environment variable instead:
```python
proxy_env = {"UPSTREAM_API_KEY": self._config.api_key}
proxy_cmd = (
    "cd /home/user/proxy && "
    "python interception.py "
    f"--upstream-url {self._config.base_url} "
    "--upstream-api-key $UPSTREAM_API_KEY "  # read from env, not argv
    ...
)
proxy_job = sandbox.start_bg(proxy_cmd, envs=proxy_env)
```
Then update `interception.py`'s CLI parser to fall back to `os.environ.get("UPSTREAM_API_KEY")`.

How can I resolve this? If you propose a fix, please make it concise.

[burtenshaw]

Agreed. This is still valid on the current head: the proxy command still passes the upstream key via --upstream-api-key, so this should stay open. The fix should pass the key through sandbox.start_bg(..., envs={"OPENCODE_UPSTREAM_API_KEY": ...}) and have interception.py read it from the environment instead of argv. I would also handle model/URL shell quoting in the same cleanup pass.

[greptile-apps]

False-idle detection for thinking models

The stable_ticks >= 12 heuristic (12 × 0.5 s = 6 s) treats any 6-second gap in new messages as "idle". A reasoning/thinking model (e.g. Qwen3 with disable_thinking=False) can pause for tens of seconds between outputting tokens without the session being finished. During these pauses list_messages returns the same count, stable_ticks climbs to 12, and wait_for_completion returns 0 — causing verify() to be called on an in-progress run and potentially reporting incorrect results.

Consider raising the threshold significantly (e.g. stable_ticks >= 60 → 30 s) or replacing the heuristic with the GET /event SSE stream idle signal so completion detection is driven by the server's own state machine rather than a message-count derivative.

Prompt To Fix With AI

This is a comment left during a code review.
Path: envs/opencode_env/harness.py
Line: 231-244

Comment:
**False-idle detection for thinking models**

The `stable_ticks >= 12` heuristic (12 × 0.5 s = 6 s) treats any 6-second gap in new messages as "idle". A reasoning/thinking model (e.g. Qwen3 with `disable_thinking=False`) can pause for tens of seconds between outputting tokens without the session being finished. During these pauses `list_messages` returns the same count, stable_ticks climbs to 12, and `wait_for_completion` returns 0 — causing `verify()` to be called on an in-progress run and potentially reporting incorrect results.

Consider raising the threshold significantly (e.g. `stable_ticks >= 60` → 30 s) or replacing the heuristic with the `GET /event` SSE stream idle signal so completion detection is driven by the server's own state machine rather than a message-count derivative.

How can I resolve this? If you propose a fix, please make it concise.

[burtenshaw]

This thread is outdated on the latest branch. The opencode serve path was removed; the harness now uses a single CLI/background-job path and waits on process completion rather than message-count idle detection.

[greptile-apps]

get_host bypasses the SandboxHandle protocol

driver="serve" reaches through sandbox.raw.get_host() — a property specific to E2BSandboxHandle and absent from the SandboxHandle Protocol. Any custom backend that correctly implements the Protocol but does not expose a .raw attribute with get_host will fail here at runtime with a non-obvious error.

The SandboxHandle Protocol should declare a get_host(port: int) -> str method (optional, raising NotImplementedError by default) so custom backend authors know the contract.

Prompt To Fix With AI

This is a comment left during a code review.
Path: envs/opencode_env/harness.py
Line: 693-699

Comment:
**`get_host` bypasses the SandboxHandle protocol**

`driver="serve"` reaches through `sandbox.raw.get_host()` — a property specific to `E2BSandboxHandle` and absent from the `SandboxHandle` Protocol. Any custom backend that correctly implements the Protocol but does not expose a `.raw` attribute with `get_host` will fail here at runtime with a non-obvious error.

The `SandboxHandle` Protocol should declare a `get_host(port: int) -> str` method (optional, raising `NotImplementedError` by default) so custom backend authors know the contract.

How can I resolve this? If you propose a fix, please make it concise.

[burtenshaw]

This is outdated after the latest rewrite. The serve driver was removed, so the harness no longer reaches through sandbox.raw.get_host() for opencode serve exposure.

[greptile-apps]

import json inside a for loop

import json as _json is placed inside the for loop body in fetch_proxy_trace. Python caches imports so this is not a correctness bug, but it's misleading and would fail a lint pass. Move the import to the top of the file alongside the other standard-library imports.

Prompt To Fix With AI

This is a comment left during a code review.
Path: envs/opencode_env/harness.py
Line: 289-295

Comment:
**`import json` inside a for loop**

`import json as _json` is placed inside the `for` loop body in `fetch_proxy_trace`. Python caches imports so this is not a correctness bug, but it's misleading and would fail a lint pass. Move the import to the top of the file alongside the other standard-library imports.

How can I resolve this? If you propose a fix, please make it concise.

[burtenshaw]

Agreed. This is still present on current head in fetch_proxy_trace; the json import should be moved to the module import block and the loop should call json.loads(line) directly.

[greptile-apps]

Module-level import at bottom of file

from pathlib import Path is placed after the class definitions with a # noqa: E402 suppression. Move this to the top of the file with the other imports.

Prompt To Fix With AI

This is a comment left during a code review.
Path: envs/opencode_env/harness.py
Line: 707

Comment:
**Module-level import at bottom of file**

`from pathlib import Path` is placed after the class definitions with a `# noqa: E402` suppression. Move this to the top of the file with the other imports.

How can I resolve this? If you propose a fix, please make it concise.

[burtenshaw]

This is fixed on the current head. Path is now imported in the top-level stdlib import block rather than at module bottom.

[Darktex]

Note: This is an automated review by Claude Code, not a human review.

---

Alignment Review

Automated Checks

• Lint: manual ruff pass shows one E402 (noqa'd) and one E731 (noqa'd) in the new files; no additional failures.
• Debug code: FOUND — one print() call in production proxy code (see below).

Tier 1: Fixes Required

• envs/opencode_env/interception.py (~line 1382) — print(...) left in _proxy_streaming error path ([proxy] turn {turn_idx}: upstream ...). Should use logging.getLogger(__name__).warning(...) to match the rest of the file's logging discipline.
• envs/opencode_env/harness.py (~line 942) — The api_key is interpolated directly into the shell command string passed to sandbox.start_bg(proxy_cmd). Keys containing shell-special characters (spaces, quotes, $, backticks) will corrupt the command or enable injection. Pass it via the envs= dict and read it from an environment variable in interception.py.
• envs/opencode_env/harness.py (~line 1055) — from pathlib import Path is at module scope after class definitions (E402, noqa'd). Move to the top of the file per PEP 8 and the project's usort/ruff pipeline.
• envs/opencode_env/tests/test_harness.py (~line 2957) — pytest.raises(RuntimeError, match="install failed") only accidentally matches the actual "opencode install failed after 3 attempts ...". Tighten the match string to something stable (e.g., "opencode install").

Tier 2: Alignment Discussion

ALIGNMENT FLAG: external verifier callable breaks "rewards inside environment"

• Principle at stake: "Rewards inside environment" (RFC 002, PRINCIPLES.md). External reward augmentation should use the Transform pipeline.
• Concern: OpenCodeSessionFactory(verifier=my_verifier) accepts an arbitrary callable from the caller and uses it to produce env_reward, putting reward logic outside the environment. This can harm reproducibility and opens reward-hacking at the orchestration layer.
• Suggested reviewer: @Darktex

ALIGNMENT FLAG: stacked on unmerged RFC 005 / PR #471

• Concern: This env imports ResourceSession/ResourceSessionFactory from openenv.core.harness, which does not exist on main yet. Merging before #471 lands will break import/test against main. Please mark the dependency explicitly (e.g., "Depends on #471") rather than relying on description text alone.
• Suggested reviewer: @Darktex

Summary

• 4 mechanical issues to fix (debug print, credential injection risk, misplaced import, fragile test match).
• 2 alignment points for human review.

---

Automated review by Claude Code | Learn more

[Darktex]

Note: This is an automated review by Claude Code, not a human review.

---

Alignment Review Report

Automated Checks

• Lint (pre-existing failures only): PASS for opencode_env — the 5 failing files are in chat_env, repl_env, and textarena_env, all pre-existing and unrelated to this PR.
• Debug code: FOUND — see Tier 1 below.

---

Tier 1: Fixes Required

• envs/opencode_env/harness.py line ~942 — Credential exposed via CLI argument (Security Invariant)

  f"--upstream-api-key {self._config.api_key} "

  The API key is passed as a positional shell argument, making it visible in /proc/<pid>/cmdline and ps aux inside the sandbox. Any process in the sandbox can read it. Fix: pass the key through an environment variable instead (e.g., PROXY_API_KEY) and read it in interception.py's main() via os.environ. The env-var injection path (build_env_vars) already sets OPENAI_API_KEY — the proxy key should follow the same pattern.

• envs/opencode_env/interception.py line ~1382 — Bare print() in production code path (Debug code invariant)

  print(
      f"[proxy] turn {turn_idx}: upstream {upstream.status_code}: "
      f"{str(error_json)[:400]}",
      flush=True,
  )

  This print() is in a production code path (_proxy_streaming) and fires on every upstream error response during live rollouts. Replace with logging.getLogger(__name__).warning(...) so it respects the caller's log level and format.

• envs/opencode_env/harness.py line 1055 — Late Path import at module bottom

  from pathlib import Path  # noqa: E402  (used only inside _start_proxy)

  The # noqa: E402 suppresses the lint rule rather than fixing the structure. Move the import to the top of the file with the other stdlib imports.

• envs/opencode_env/harness.py line ~937 — Shell injection via model field

  model_override_flag = f"--model-override '{upstream_model}' "

  A model value containing a single quote (e.g., openai/foo' && malicious_cmd #) breaks out of the shell argument. Use shlex.quote(upstream_model) or pass the value as an environment variable consumed by the proxy rather than embedding it directly in the command string.

• Missing openenv.yaml manifest

  Every OpenEnv environment package requires an openenv.yaml per PATTERNS.md. This PR has no manifest file. Add it (even a minimal one) to conform to the expected package structure.

---

Tier 2: Alignment Discussion

ALIGNMENT FLAG 1: Hard dependency on unmerged PR #471

• Principle at stake: From PRINCIPLES.md "Be hands-on: Provide ready-to-use implementations, not just specs" and general integration hygiene.
• The concern: envs/opencode_env/harness.py imports ResourceSession, ResourceSessionFactory, VerifyResult, ToolResult, Message from openenv.core.harness. This module does not exist on main — it lives in open PR #471. The PR description acknowledges this with "Stacked on #471," but the base contracts it depends on are themselves still in review. This PR cannot land until #471 merges and the core contracts it implements are stable.
• Suggested reviewer: @Darktex

ALIGNMENT FLAG 2: Reward computed outside the environment boundary

• Principle at stake: PRINCIPLES.md "Rewards inside environment" (RFC 002); INVARIANTS.md §Architectural §3 "Reward computation must stay inside environment boundary."
• The concern: OpenCodeSession.verify() delegates entirely to a caller-supplied Verifier = Callable[[SandboxHandle, OpenCodeTask], VerifyResult]. The reward function is injected at factory construction time as arbitrary external code — it runs outside the environment's own logic. The question for the reviewer: does a post-hoc sandbox-execution verifier count as "inside the environment boundary" since it runs on the same sandbox object, or is it an invariant violation requiring an RFC discussion?
• Suggested reviewer: @Darktex

ALIGNMENT FLAG 3: No Docker container — E2B-only sandbox model

• Principle at stake: INVARIANTS.md §Security §2 "Container isolation — environments run in isolated Docker containers"; PATTERNS.md canonical structure requires server/Dockerfile.
• The concern: This environment has no Dockerfile, no server/ directory, and no local Docker path. Isolation is provided entirely through E2B's cloud SDK, which is a paid external service. The PR uses SandboxBackend as a Protocol abstraction (so Docker could theoretically be added), but there is no Docker backend provided. The tradeoff may be justified, but should be explicitly called out and approved.
• Suggested reviewer: @Darktex

ALIGNMENT FLAG 4: serve_client public attribute on OpenCodeSession

• Principle at stake: INVARIANTS.md §Security §1 "Agents cannot access reset/simulation controls."
• The concern: OpenCodeSession.serve_client is a public attribute of type OpenCodeServerClient. That client has methods including create_session(), send_prompt_async(), and abort() — these are simulation control operations. The attribute should be prefixed _serve_client (private) to signal it is not part of the public API.
• Suggested reviewer: @Darktex

---

Summary

• 4 mechanical issues to fix (credential exposure via CLI arg, bare print() in production, late import, shell injection via model field) plus 1 missing openenv.yaml.
• 4 alignment points for human review: stacked-on-unmerged-PR dependency, reward-outside-environment-boundary pattern, no Docker/container isolation, and serve_client public attribute exposure.

The code quality overall is high — test coverage is thorough and the two-driver/two-mode design is clean. The mechanical issues are fixable without design changes. The alignment issues (especially the reward boundary and container invariant) need explicit sign-off before this can land.

---

Automated review by Claude Code | Learn more

[Darktex]

Note: This is an automated review by Claude Code, not a human review.

---

Alignment Review Report

Automated Checks

• Lint: PASS for opencode_env (files not yet on disk; carla_env pre-existing failures are unrelated to this PR)
• Debug code: FOUND — one live print() in production code path (see Tier 1)

---

Tier 1: Fixes Required

• /envs/opencode_env/interception.py:1382 — print() call in the production streaming error path (_proxy_streaming). This logs upstream error bodies directly to stdout in the running sandbox process. Should be logging.warning(...) or removed; stdout in a sandbox is not the right telemetry channel.

• /envs/opencode_env/harness.py:942 — api_key passed as a CLI argument on the proxy command line: f"--upstream-api-key {self._config.api_key}". This exposes the secret in the sandbox process list (ps aux) and in the proxy log file (_PROXY_LOG_PATH), violating the "no credential exposure" security invariant. Pass the key via an environment variable instead (e.g. OPENCODE_UPSTREAM_API_KEY) and read it in main() / ProxyConfig.

• /envs/opencode_env/harness.py:1055 — from pathlib import Path is deferred to the bottom of the module (after the class definitions). E402 placement is explicitly noted with a noqa comment, but the cleaner fix is to hoist it to the top-level imports block where it belongs.

---

Tier 2: Alignment Discussion

ALIGNMENT FLAG: Stacks on an unmerged PR

• Principle at stake: "Be hands-on — provide ready-to-use implementations" (PRINCIPLES.md); also general merge-stability
• The concern: harness.py imports from openenv.core.harness (the ResourceSession, ResourceSessionFactory, Message, ToolResult, VerifyResult contracts) that are defined only in PR #471, which is currently open. If this PR is merged before #471 the import path does not exist in main, making the package entirely non-functional at import time. The README acknowledges this but there is no CI guard.
• Suggested reviewer: @Darktex

ALIGNMENT FLAG: Verifier callable is caller-supplied, injected from outside the environment boundary

• Principle at stake: "Rewards inside environment" (RFC 002, PRINCIPLES.md)
• The concern: OpenCodeSessionFactory(verifier=my_verifier) delegates reward computation to an arbitrary callable passed by the trainer/caller. This is structurally equivalent to external reward augmentation and differs from the pattern where reward logic is encapsulated inside the environment. The design rationale — that different tasks need different verifiers — may be sound, but it has not been documented in an RFC. If the intent is that this primitive is task-agnostic plumbing (akin to a Transform), the boundary needs to be explicit.
• Suggested reviewer: @Darktex

ALIGNMENT FLAG: start_agent(), wait_for_completion(), and abort() are public on the session object

• Principle at stake: "Agents cannot reset" / dual API boundary (INVARIANTS.md §Security §Architectural)
• The concern: These methods control simulation lifecycle. They are called by the factory on behalf of the training orchestrator, which is correct. However, they are on the ResourceSession object which is also handed to HarnessAdapter.run_white_box(session, ...). If a harness adapter or downstream code exposes the session reference to the agent being evaluated, the agent could call abort() or observe completion-state. This is the same class of risk as exposing reset() via MCP. The ABC contract in PR #471 (ResourceSession) does not include these methods, so they are extra-protocol additions. The fix would be either to not inherit them from the public ABC or to document explicitly that these must never be forwarded to agents.
• Suggested reviewer: @Darktex

---

Summary

• 3 mechanical issues to fix (1 debug print, 1 credential-in-args, 1 import placement)
• 3 alignment points for human review (dependency ordering, reward-boundary, lifecycle method exposure)

The overall implementation quality is high — good test coverage, clean Protocol-based sandbox abstraction, well-commented internals. The Tier 1 items are straightforward to fix. The Tier 2 items are design questions that need human sign-off given the newness of both this primitive and the harness contract it builds on.

---

Automated review by Claude Code | Learn more

[Darktex]

Note: This is an automated review by Claude Code, not a human review.

---

Summary

This is a well-structured, documented, and tested harness primitive for running OpenCode inside E2B sandboxes. The code quality is high overall. However it has two categories of blocking issues: (1) it hard-depends on openenv.core.harness (PR #471) which does not exist on main, making it un-importable today; and (2) a credential exposure bug where api_key is interpolated into a shell command argument string. There are also several minor quality issues and one alignment flag that needs human sign-off before merge.

Tier 1 — Bugs / Quality

• envs/opencode_env/harness.py:1-20 — Hard dependency on unmerged PR #471. from openenv.core.harness import ResourceSession, ResourceSessionFactory, VerifyResult, Message, ToolResult fails with ModuleNotFoundError on current main because openenv.core.harness does not exist yet. This PR must stack on #471 (e.g. via Graphite) and cannot merge before its parent lands.

• envs/opencode_env/harness.py (proxy_cmd construction, around diff line 942) — Credential exposure in shell command. self._config.api_key is interpolated directly into proxy_cmd as --upstream-api-key {self._config.api_key}. Shell commands can appear in ps aux, audit logs, and E2B execution records. Pass it via an environment variable instead, consistent with the OPENAI_API_KEY pattern already used in build_env_vars.

• envs/opencode_env/interception.py (@app.on_event("shutdown")) — @app.on_event is deprecated in FastAPI 0.93+ (PendingDeprecationWarning). The declared dependency is fastapi>=0.104. Replace with a @asynccontextmanager lifespan passed to FastAPI(lifespan=...).

• envs/opencode_env/harness.py (final line, from pathlib import Path) — Module-level import placed after all class definitions with # noqa: E402 to suppress the lint error. Move from pathlib import Path to the top of the file alongside the other stdlib imports.

• envs/opencode_env/interception.py (error branch inside _proxy_streaming) — Bare print(f"[proxy] turn {turn_idx}: upstream {upstream.status_code}: ..."). Production code should use logging.warning(...) or logging.error(...) instead of print() so operators can route, filter, and suppress log output.

• No openenv.yaml present. Every env in the repo (echo_env, repl_env, etc.) ships an openenv.yaml runtime descriptor. Add one even if the type is harness rather than space.

• envs/opencode_env/harness.py module-level constants _PROXY_TRACE_PATH, _PROXY_LOG_PATH, _SERVE_LOG_PATH, _OPENCODE_BIN are hardcoded to /home/user/.... OpenCodeConfig.sandbox_home exists to support non-E2B backends (e.g. Docker-as-root where home is /root). These paths should be derived from config.sandbox_home via helper functions in opencode_runtime.py (matching the pattern used by agent_log_path, workdir_path, etc.), otherwise non-E2B backends silently use the wrong paths.

Tier 2 — Alignment

ALIGNMENT FLAG: User-supplied verifier callable lives outside environment boundary

• Principle at stake: "Rewards inside environment" (RFC 002, PRINCIPLES.md)
• The concern: OpenCodeSessionFactory(verifier=my_verifier) accepts an arbitrary callable that runs in the trainer process and returns a reward scalar. RFC 002 says "domain knowledge encapsulated in env, not external." The verifier here is deliberately external — it runs in the caller's process, inspects the sandbox via sandbox.exec(...), and produces the reward. This is a pragmatic choice for a closed-binary harness (the env has no hook point), but it departs from the principle without a documented trade-off. Either (a) add an RFC note or README section explaining why verifier-as-callback is the correct pattern for harness primitives, or (b) get explicit sign-off that this trade-off is intentional.
• Suggested reviewer: @Darktex

ALIGNMENT FLAG: New contract (ResourceSession/ResourceSessionFactory) diverges from Gymnasium-style API

• Principle at stake: "Simple Gymnasium-style API" (PRINCIPLES.md); RFC 005 is "In Review" status
• The concern: This PR introduces a new top-level contract (ResourceSession / ResourceSessionFactory) rather than extending Environment[ActT, ObsT, StateT]. RFC 005 is still marked "In Review." Merging an env that depends on a still-in-review RFC could lock in a contract before the RFC is settled. The dependency structure (this PR stacked on #471) makes the order correct, but the alignment question is: has RFC 005's contract been finalized for the ResourceSession shape?
• Suggested reviewer: @Darktex

Verdict

Request changes: the openenv.core.harness import dependency on unmerged PR #471 is a hard blocker, and the api_key in shell command is a security invariant violation — both must be fixed before this can merge.

---

Automated review by Claude Code | Learn more

[sergiopaniego]

Thanks!!!
Could be nice to add examples as it's common for other envs.
Additionally, you could link to a running remote env (I guess it's https://huggingface.co/spaces/AdithyaSK/opencode-env-rollout)

I think we can do a small round to clean some parts that are draft instead of intended to be part of the final version

[sergiopaniego]

should be updated/cleaned (and the rest of the appearances of similar patterns)

[burtenshaw]

This README thread looks outdated after the latest docs rewrite. The current README now uses the deployed Space endpoints and the task/setup/verify terminology rather than the earlier placeholder wording.

[sergiopaniego]

this doesn't make sense from the perspective of a final user since once this is live, #471 should also be merged

[burtenshaw]

This is outdated in the current README. The final-user docs no longer frame usage around manually depending on PR #471; the branch still remains stacked on #471 for merge ordering, but that should not be part of the final user-facing instructions.

[meta-cla]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!