8000 Add OpenCode as a CLI Base Agent (acting agent and opencode Evolver) by veoery · Pull Request #94 · Infini-AI-Lab/hermit · GitHub
[go: up one dir, main page]

Skip to content
Add OpenCode as a CLI Base Agent (acting agent and opencode Evolver) - #94
Merged
haizhongzheng merged 6 commits into
Infini-AI-Lab:mainfrom
veoery:feat/opencode
Nov 10, 2026
Merged

haizhongzheng merged 6 commits into
Infini-AI-Lab:mainfrom
veoery:feat/opencode

Conversation

@veoery
@veoery veoery commented Nov 10, 2026
Copy link
Copy Markdown
Contributor

Change

Adds OpenCode (opencode, v2.2.6) as a CLI Base Agent beside codex, claude, pi and mini-swe-agent, as one
CliAgent subclass. It can act (agent.base: opencode) and learn (the new opencode Evolver). It follows Pi's pattern: a model
reference only (no login), no roles, no web search.

  • Layer 1 (hermit/agent/model/backends.py): a <backend>/<model> reference becomes OpenCode's config provider
    hermit (Binding.opencode_provider): its OpenAI-compatible package (@ai-sdk/openai-compatible, shipped in the
    binary), the backend's URL, the key written as {env:VARIABLE} (never the value) and the context window. OpenCode
    is bound for chat completions only (NEEDS["opencode"] = "chat"), so hermit check and train refuse a backend
    without them.
  • Layer 2 (hermit/agent/base/cli.py, class OpenCode): runs opencode run --standalone --format json in a
    private home (HOME and the four XDG folders), with update and catalog requests and Claude Code's files
    (~/.claude, .claude/) switched off (OPENCODE_DISABLE_AUTOUPDATE, _MODELS_FETCH, _CLAUDE_CODE).
    • Config split. What the session must hold is the inline config (OPENCODE_CONFIG_CONTENT), which outranks a
      workspace's opencode.json: the provider, enabled_providers: [hermit], the permissions, no sharing, no
      snapshots, and the system instructions' file. The call's tools are the home's config (OPENCODE_CONFIG) as an
      MCP server with codemode: false, so the model is offered them directly rather than through code mode, with a
      1800 s timeout.
    • Tools denied: question (no one answers), subagent (no roles), execute (code mode), webfetch and
      websearch (they reach the network past the sandbox), opencode_*. The same permissions are given to the agent
      the session runs (default_agent: build, agent.build.permission): an agent-level permission in a workspace's
      or a parent folder's opencode.json would otherwise outrank the inline top-level ones.
    • Skills: only the deployment's (skills, which the acting agent sets from deployed["skills"]; none for the
      Evolver): permission.skill denies every other, so a parent folder's .agents/skills (OpenCode 2.2 looks up to
      /, and reads no variable that stops it) offers nothing.
    • Outages from OpenCode's own error type. outcome() reads the final error event:
      provider.rate-limit, provider.internal, provider.transport and provider.timeout (or a 429/5xx status)
      set unavailable, so the acting agent runs the task again; provider.auth, provider.quota (a 402),
      provider.invalid-request, provider.content-filter and provider.unsupported-operation (or 400/401/403/404)
      set rejected. Other types (provider.invalid-output, provider.unknown) leave the session failed only. Nothing is
      read from the error's wording, and the shared UNAVAILABLE regex is not used.
    • Model reference only. _sign_in refuses a login and a run without a bound provider before OpenCode starts,
      so no file of the user's OpenCode data folder is ever copied. Roles, web search and container isolation are
      refused with Unsupported.
    • Two OpenCode behaviours found by running the real binary. OpenCode 2.x connects by default to a shared
      background service, which would mix sessions across homes and parallel tasks: every session passes
      --standalone (a private server). And OpenCode works in the directory its inherited PWD names, not the one it
      is started in: dropped_env() drops PWD (and every inherited OPENCODE_*), so it works in the workspace.
    • --title hermit saves a title-generation request; --thinking keeps reasoning in the stream; resume passes
      --session <id>; effort becomes the model's reasoningEffort; usage and trajectory are read from the events
      (records.parse_opencode, trajectory.opencode_steps, agent-opencode.jsonl); a bound model's cost follows its
      price, as Pi's does.
  • Layer 3:
    • New deploy host hermit/hosts/opencode.py (hermit deploy --host opencode): AGENTS.md, the project's
      opencode.json (the adapter's tools as a local MCP server, codemode: false, 120 s timeout) and
      .opencode/skills/; roles and hooks are named in AGENTS.md, as for Pi. OpenCode loads these with no trust step.
    • The acting agent (hermit/agent/acting/workspace.py, agent.py), AgentEvolver, the config
      (hermit/config.py, defaults.yaml) accept opencode. New hermit/agent/evolver/methods/opencode/ Evolver
      (prompts as Pi's; home: [], web_search: false).
  • Shared code (core): the "takes no login" checks (workspace._check, isolate.py's config check,
    login.evolver_problems), which main writes as ("pi", "mini-swe-agent") inline, now read one list,
    login.NO_LOGIN = ("pi", "mini-swe-agent", "opencode"); Pi's and mini-swe-agent's messages are unchanged.
    CLI_KINDS, CLI_AGENTS, NEEDS, STREAM_HOSTS, READERS, MARKS and CLIS gain opencode (after
    mini-swe-agent). No sandbox behaviour changes: the only isolate.py line changed is that config check.
  • Merged with origin/main (962a604, after mini-swe-agent: a Base Agent, an acting agent and a deployment host #49 mini-swe-agent, Add ASPIRE: the aspire template and Evolver, with a Robosuite example #74 ASPIRE, Stop the wire meters a launcher starts once its runs end #87, Stop a CLI session's processes on macOS too #88; then ee27441, after GPUs in the sandbox (environment.gpu); ASPIRE's simulator confined with them #93
    GPUs in the sandbox, with no conflict): every conflict was both sides adding a CLI to the same lists and docs; both
    are kept. GPUs in the sandbox (environment.gpu); ASPIRE's simulator confined with them #93's environment.gpu applies to an OpenCode acting agent's task sandbox as to any other; it is off
    unless set and needs nothing of OpenCode's.
  • Docs: agent-layers.md, task.md, evolver.md, custom-evolver.md, methods/agent.md, model-backends.md,
    config-fields.md, configuration.md, compatibility.md, installation.md, commands.md, adapter.md (an
    OpenCode column in the deploy mapping and an OpenCode workspace tree), ahe_adapter.md,
    what-is-a-harness-adapter.md, faq.md, docs/web/index.html, CHANGELOG. Two lines that main's mini-swe-agent: a Base Agent, an acting agent and a deployment host #49 left naming
    no mini-swe-agent (commands.md's --host list, adapter.md's rewritten files) name it too.
  • Release choice: v2.2.6 (2026-11-06), the most recent release. GitHub's "Latest" label still points at the 1.x
    maintenance release v1.19.5; the deprecated 1.x config keys this uses (provider, permission) work in 2.2.6,
    but 1.x itself is not tested.

Validation

Run on Linux with bubblewrap 0.9.0, Python 3.12.9, OpenCode 2.2.6 (release binary, checked against the release's
sha256 digest) and Pi 1.5.0. No real provider was used: a local scripted chat-completions server stands in for
the model.

Check Result
python -m pytest --integration (full suite; --changed selects every group for this change), on the head ee27441 4 failed, 1237 passed, 95 skipped (14 min 27 s)
tests/core/test_opencode_agent.py --integration (18 tests: 15 offline, most replaying a recorded stream; 3 with the real opencode) 18 passed (about 16 s)
The tests the first merge touches, on 962a604: OpenCode, mini-swe-agent, Pi, CLI agent, isolate, deploy, selection, backends, the installed-CLI sandbox test, with --integration 205 passed, 29 skipped (mini-swe-agent's own, which need the mini-swe-agent extra, not installed here; CI installs it)
The tests #93 touches, with OpenCode's, on ee27441: test_opencode_agent.py, test_sandbox.py, test_isolate.py, with --integration 163 passed, 2 skipped, 1 failed (test_inside_the_sandbox_the_hidden_paths_are_empty, the .venv-in-checkout failure below)
Regression checks with PWD kept (reverting dropped_env), test_opencode_runs_in_its_home_… and the unsandboxed integration test fail; without the agent-level permissions and the skill allowlist, the unsandboxed integration test fails (question and webfetch offered)
hermit check / train / eval, sandbox enforced, OpenCode acting and learning, on the docs' toy task (first_training data, prompt-only@1.0), on 962a604 (before #93, which changes nothing it uses: no environment.gpu) check ok; the learner wrote the rule and called check_spec (passed); test split: untrained (--adapter root) 0.0, trained (--adapter final) 1.0
Offline walkthrough (docs/_examples/first_training: check, train, eval final), before the merge ok; eval 1.0
docs/build.sh equivalent (sphinx-build -W --keep-going), on ee27441 builds with no warning
  • Failures: the same 4 as without this change: 3 in examples/clbench_database (golden parity; they also fail
    on a clean extract of origin/main) and test_inside_the_sandbox_the_hidden_paths_are_empty, which fails because
    this checkout keeps .venv inside the repository.

  • Fixtures (tests/fixtures/opencode/) are OpenCode's output unchanged (they hold no host path), recorded through
    make("opencode").run: success, resume, 500, 429, a refused connection, 401 and 402.

  • Sandbox records of the toy run on 962a604:

    learner-1.json / rollout-1.json (excerpt)
    learner-1: role=learner enforced=True network=isolated probe=True forwarded=[<model>, <tool server>]
       env: CODEX_HOME, HOME, LANG, MOCK_KEY, OPENCODE_CONFIG, OPENCODE_CONFIG_CONTENT, OPENCODE_DISABLE_AUTOUPDATE,
            OPENCODE_DISABLE_CLAUDE_CODE, OPENCODE_DISABLE_MODELS_FETCH, PATH, PYTHONPATH, XDG_CACHE_HOME,
            XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME
       program: <opencode install>/opencode
    rollout-1: role=rollout enforced=True network=isolated probe=True forwarded=[<model>]
       env: CODEX_HOME, HA_ADAPTER_SANDBOX_ENFORCE, HA_RESULT_FD, HOME, LANG, MOCK_KEY, PATH, PYTHONPATH, XDG_DATA_HOME
    

    (CODEX_HOME is in the sandbox's ALWAYS list and was set in the shell; unrelated to this change.)

  • Not verified: reaching a real provider, directly or through the sandbox's allowlist proxy (OpenCode honours
    HTTPS_PROXY per its documentation, not from a run); macOS; OpenCode 1.x.

  • Known limits:

    • opencode_worktree_remove is offered and runs although opencode_* is denied (no permission or 1.x tools
      switch reaches it in 2.2.6); it acts only on worktrees of the session's own project.
    • Outside a sandbox, a parent folder up to a Git repository's root still gives the session its AGENTS.md,
      opencode.json (instructions, MCP servers, agents) and .opencode/ (as Codex reads AGENTS.md to that root);
      the permissions and the skills stay held. Inside the run's sandbox no parent folder is shown.
    • An unknown --session id makes OpenCode start a new session under that id rather than fail.
    • The prompt is always an argument (stdin is not used): a prompt over the system's argument limit fails to start.
    • hermit convert --target is not extended; AHE's middleware refuses a copy deployed into an OpenCode workspace.

Review

  • Tests and documentation cover the affected behavior: see Validation and the docs list.
  • Commands, defaults, and public interfaces are consistent. New: agent.base: opencode, evolver.base: opencode, agent.name: opencode, an opencode: settings section, hermit deploy --host opencode.
  • Shared logs and examples contain no credentials or private data. The fixtures hold no key and no host path;
    the inline config holds the key's variable name, never its value.
  • Documentation-only: N/A.
  • Core changes: the shared NO_LOGIN list (three checks, one of them in isolate.py's config validation,
    no sandbox behaviour); the registries listed under Change.
  • Failures reported accurately: outages (500, 429, refused connection) are unavailable and retried by the
    acting agent, then an error (test_the_acting_agent_runs_a_task_again_…); a 401 is rejected; a session without
    an answer is failed and becomes an error record, never a wrong answer.
  • Real entry points: make("opencode").run, the acting agent's run, hermit deploy, hermit train and
    hermit eval. Stand-ins only at the edges (the CLI, the model).
  • Test checklist:
    • The tests are in tests/core/; the fixtures are registered in tests/selection.py (CORE) and tests/README.md;
      test_selection.py's BUILT_IN gains opencode; test_an_installed_cli_starts_with_only_its_own_paths gains it.
    • The stand-ins replay recorded OpenCode 2.2.6 output; the tests use no network, no sign-in, and no installed CLI
      outside integration tests, which skip without opencode.
    • The unsandboxed integration test points PWD at a directory of its own, so a regression fails it rather than
      writing outside tmp_path.
  • Sandbox checklist, reuse: OpenCode runs through CliAgent inside the task and evolver sandboxes; all of its
    variables come from home_env(); see the records above.
  • Sandbox checklist, core change: isolate.py's config check now reads NO_LOGIN; no change to what a
    sandbox shows or allows. Please confirm this counts as no sandbox change.
  • In 8000 dependent review (post-PR audit): pending for the current head (the fixes and the merges below). A
    separate agent (Opus 5.5, high effort) reviewed commit b36e198
    against the general, test and sandbox checklists, reproduced the validation numbers and probed the real binary.
    Findings and resolution:
    • Medium: a workspace's or a parent folder's opencode.json could give the build agent its own permissions
      (webfetch, question back), and .agents/skills from parent folders reached the model; two of the variables
      (OPENCODE_DISABLE_EXTERNAL_SKILLS, _LSP_DOWNLOAD) do not exist in 2.2.6. Fixed: the permissions on the
      agent, the skill allowlist, the two variables removed; the integration test adds such a parent folder.
    • Low: opencode_* does not stop opencode_worktree_remove. Not fixable from config in 2.2.6; documented.
    • Low: error types outside both lists. provider.quota added to rejected (recorded 402 fixture); the rest
      stay failed.
    • Low: the prompt is always an argument. Kept (as Pi's); documented.
    • Tests: reasoning tokens, the key's substitution, effort, the denies and the parent folder are now asserted
      against the real binary; hermit deploy --host opencode has a test. Docs: adapter.md (rewritten files, an
      OpenCode workspace tree), commands.md (--host), ahe_adapter.md. Fixed.
    • Remaining: the claims above about parent folders outside a sandbox; a real provider is not verified.
    • Not independently audited yet: the review's fixes (ff65173) and the merges with origin/main (962a604,
      ee27441).
      Both are covered by the tests and checks above, run by the author.

🤖 Generated with Claude Code

veoery and others added 4 commits November 9, 2026 23:12
origin/main adds mini-swe-agent as a CLI Base Agent (Infini-AI-Lab#49), ASPIRE (Infini-AI-Lab#74), the macOS process stop (Infini-AI-Lab#88) and the
wire meter stop (Infini-AI-Lab#87). Every conflict was both sides adding a fifth CLI to the same lists and docs: both are kept
(mini-swe-agent, then opencode). The "takes no login" checks read one list, login.NO_LOGIN = ("pi",
"mini-swe-agent", "opencode"), where main had ("pi", "mini-swe-agent") inline. The docs lists that name the CLI
agents and deployment hosts now name both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
haizhongzheng and others added 2 commits November 10, 2026 11:15
…paction usage

- The adapter's tools reach an OpenCode acting agent through the Base Agent's
  tool server: OpenCode 2.2 waits at most 2 s for an MCP server it starts
  (STARTUP_GRACE_MS) and the adapter's takes ~3 s, so the first request often
  went without them. hosts/opencode.prepare takes serve_tools; docs say so.
- The prompt is OpenCode's stdin, not an argument (E2BIG past 128 KiB).
- A binding's extra_body becomes the OpenCode model's options; the effort
  setting outranks its reasoning_effort.
- Usage counts compactions' model calls, which `run --format json` never
  streams: this call's share of the session's totals in OpenCode's database
  (read-only, immutable, nothing followed out of the home), a resumed
  session's earlier totals taken off (_this_call, now with `fields`).
- parse_log reads OpenCode's stream by its name.
- The AHE Evolver's texts name OpenCode's stream (agent-opencode.jsonl) as
  they name Pi's and mini-swe-agent's (Infini-AI-Lab#91).
- The deployer's docstring gives AGENTS.md discovery's real boundary.

Tests: the first request offers the adapter's tools (real binary); a prompt
past ARG_MAX; extra_body and effort; compaction usage from a stand-in
database and from the real binary (mid-run compaction, then a resume).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@haizhongzheng haizhongzheng left a comment
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the PR. We reviewed it in two rounds (our own read plus an independent Codex review each round) and checked every finding against the OpenCode 2.2.6 binary or its source. The fixes are pushed to this branch as one commit, 80e04b1, after a merge of current main (52c0011). Each code fix has a test that fails without it.

Three-layer abstraction

It follows docs/framework/agent-layers.md:

  • Layer 2. OpenCode is a Base Agent: a CliAgent subclass in CLIS, with its stream reader in records.py and trajectory.py.
  • Layer 1. Its model binding is Binding.opencode_provider() in backends.py.
  • Layer 3. The workspace Acting Agent is reused, and the opencode Evolver is a method directory.
  • Shared runner. OpenCode uses only hooks that already exist.

As with mini-swe-agent, _deploy in acting/workspace.py branches on the backend to choose who serves the adapter's tools. The fix below adds opencode to that branch.

What we patched (80e04b1)

Before After
Adapter tools on the first request The deployment's opencode.json named a local MCP server that OpenCode starts itself. OpenCode 2.2 waits at most 2 s for a starting server (STARTUP_GRACE_MS, hard-coded), and the adapter's server takes about 3 s. So the first request often went without the adapter's tools: in 5 of 8 runs with 1 s of model latency, and the PR's own integration test failed about 1 run in 3. The acting agent serves the adapter's tools through the Base Agent's tool server, which runs before OpenCode starts, as it already does for containers and mini-swe-agent. hosts/opencode.prepare takes serve_tools. commands.md notes the limit for a standalone hermit deploy --host opencode that runs opencode run right away.
Long prompts The prompt was a command-line argument, so a prompt past 128 KiB failed with E2BIG before OpenCode started. The prompt goes on stdin, which opencode run reads to its end.
extra_body opencode_provider() dropped the binding's extra_body (for example chat_template_kwargs). It becomes the OpenCode model's options, which reach the request body (checked with the binary). An explicit effort outranks its reasoning_effort.
Compaction usage Only step_finish events were counted. OpenCode's compaction calls, and the summaries it writes ahead of one, are never streamed by run --format json, so tokens and cost were undercounted for long or resumed sessions. After each run, this call's share of the session's totals is read from OpenCode's database in the session's home 8000 . Earlier totals of a resumed session are taken off through the existing _this_call ledger, which now takes fields. Each field is the larger of the stream's count and the database's. The database is opened read-only as an immutable file, and nothing is followed out of the home. If it cannot be read, the stream's usage is kept and a warning is printed once.
AHE texts (#91, from the main merge) #91 names each acting agent's own event stream in the AHE Evolver's texts. This PR adds agent-opencode.jsonl to STREAMS but not to STREAM_TEXTS, so its test failed, and an OpenCode stream would have been described as agent-codex.jsonl. STREAM_TEXTS names OpenCode's stream as it does Pi's and mini-swe-agent's (the OpenCode event stream, `opencode run --format json` event stream). The AHE template still refuses an OpenCode workspace, so this keeps the texts consistent.
parse_log The generic reader fell through to Claude Code's parser for opencode and returned (None, []). It dispatches to parse_opencode.
Docs The deployer's docstring put the end of AGENTS.md discovery at the Git root. It gives OpenCode's actual boundary.

Tests:

  • New: the first request offers the adapter's tools (real binary); a prompt past ARG_MAX; extra_body with effort; compaction usage from a stand-in database; compaction usage from the real binary, with a mid-run compaction and then a resume.
  • pytest --changed --base origin/main selected every group, since the PR touches shared code. Run with mini-swe-agent installed and OpenCode 2.2.6 on PATH: 1270 passed and 70 skipped. One test failed: the AHE stream-naming test, which arrived with #91 in the main merge. It is fixed by the AHE row above, and the AHE tests then give 230 passed and 6 skipped.

Left for follow-ups (not blocking)

  • Redeploy keeps removed skills. copy_skills merges into the skills directory and never removes anything. This holds for every workspace host, so it is filed as #96.
  • Inherited MCP servers. A parent folder's opencode.json can add MCP servers when the sandbox is off. The PR already lists this as a known limit.
  • Compaction call count. A compaction counts as one call. A retry inside it, such as OpenCode's reminder when a summary misses the template, shows only in its tokens.
  • Database schema. The usage read depends on OpenCode 2.2's session_v2 and session_message tables. A later version that changes them falls back to the stream's usage, with the warning.

Minor, recorded only:

  • last_message falls back to an earlier message's text when the last one has none.
  • effort is passed to the model unchanged, as for Pi.

🤖 Generated with Claude Code

@haizhongzheng
haizhongzheng merged commit 1310de6 into Infini-AI-Lab:main Nov 10, 2026
iamziyuzhao added a commit that referenced this pull request Nov 10, 2026
main gained #91 (the AHE Evolver's texts name a Pi or mini-swe-agent
acting agent's stream), #94 (OpenCode as a CLI Base Agent), #97
(hermit deploy retires skills the adapter no longer exports) and #99
(agent skills for this repository). #94 adds OpenCode at the places
this branch adds dsh, so 36 files conflicted. Each conflict keeps both
sides, OpenCode before dsh:

- CLIS, the readers (records.parse_log, trajectory's STREAM_HOSTS,
  READERS and MARKS, the AHE debugger's STREAM_TEXTS) and every list
  of CLIs name both, dsh last; cli.py's Dsh part follows OpenCode's;
- main's NO_LOGIN replaces this branch's tuples in login.py,
  isolate.py and acting/workspace.py, and gains "dsh";
- a comment that no longer fits 120 columns with both names is on
  its own line;
- docs: both names in each list. docs/methods/agent.md's dsh learner
  now "signs in as the pi learner does", since OpenCode's sentence
  stands between them; in docs/methods/ahe_adapter.md, #91's general
  wording ("the one its CLI wrote") replaces this branch's list of
  streams.

dsh does not call #97's check_skills and retire_skills yet; the next
commit does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

0