opencode

# 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`) is delivered verbatim on the `opencode::raw-event` trigger type; a translated AgentEvent view is delivered on `opencode::agent-event`, which the acp worker renders. Bind either with `{ session_id }`; frames are ephemeral (not stored, not replayed). 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; bind `opencode::agent-event` with `{ session_id }` for the rendered view or `opencode::raw-event` for raw JSON, or poll `opencode::status`; 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.