opencode

name	opencode
description	Run headless OpenCode turns over the iii bus — file edits, shell, and search against any host directory — with verbatim JSON event streaming, session resume, and inline token usage and cost.

opencode

The opencode worker exposes the OpenCode API as iii functions. One opencode::run call executes one headless OpenCode turn — the same agent the user runs in their terminal, with the same tools — in a chosen working directory, and returns the final result, token usage, and cost. Every JSON event OpenCode emits (step_start, text, tool_use, step_finish) mirrors verbatim onto opencode::events; a translated AgentEvent view lands on agent::events, which the iii console and the acp worker render.

Requires the opencode CLI on the host and an API key for the LLM provider you use (e.g. ANTHROPIC_API_KEY, or opencode auth). When a turn needs a capability beyond OpenCode itself, add another iii worker to the bus instead of bolting anything onto this one.

When to Use

• Delegate a whole coding task ("add an endpoint and run the tests") in one call: opencode::run with prompt and cwd.
• Continue a conversation across calls: pass the same session_id again and the worker resumes the underlying OpenCode session (--session).
• Run long jobs without holding the call open: opencode::start returns {session_id, started} immediately; follow agent::events (group_id = session_id) for the rendered view or opencode::events for raw JSON; interrupt with opencode::stop.
• Act on the whole backend: turns carry the iii runtime context by default, so the agent discovers and calls any registered function through the iii CLI (engine::functions::list, iii trigger <fn> --help); disable per turn with iii_context: false.
• Pick a model or agent per turn: model as provider/model, agent as an OpenCode agent name.

Boundaries

• Spawns the host opencode CLI per turn — needs OpenCode installed and a provider key; not available in a bare container without it.
• opencode::run / opencode::start are not agent-callable without human approval (they spawn a full agent with the host's shell + filesystem); read-only introspection is allowed (see iii-permissions.yaml).
• One turn per session at a time: check opencode::status (live: true) before another opencode::run for the same session_id.

Functions

• opencode::run — run one turn, wait; accepts prompt (or a messages array), plus model, cwd, agent, iii_context; returns {session_id, opencode_session_id, result, stop_reason, usage, total_cost_usd}.
• opencode::start — same payload, returns {session_id, started} immediately.
• opencode::stop — interrupt the live run for a session.
• opencode::status — point-in-time session view: live flag, status, turns, usage, cost.
• opencode::sessions::list — every session this worker has run.
• run::start_and_wait — alias for opencode::run under the entrypoint the console and acp worker drive.