codex

# codex The codex worker exposes the OpenAI Codex API as iii functions. One `codex::run` call executes one headless Codex turn — the same agent the user runs in their terminal, with the same login, filesystem, and sandbox — in a chosen working directory, and returns the final result and token usage. The worker is a pure pass-through: named payload fields cover the common path, the `options` field forwards any Codex SDK ThreadOption verbatim, and every thread event is delivered untouched on the `codex::raw-event` trigger type. A translated AgentEvent view is delivered on `codex::agent-event`, which is what the acp worker renders. Requires the `codex` CLI on the host with an existing `codex login` or `OPENAI_API_KEY` in the worker environment. When a turn needs a capability beyond Codex 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, instead of orchestrating individual `coder::*` / `shell::*` calls yourself: `codex::run` with `prompt` and `cwd`. - Continue a conversation across calls: pass the same `session_id` again and the worker resumes the underlying Codex thread with full context. - Run long jobs without holding the call open: `codex::start` returns `{session_id, started}` immediately; bind `codex::raw-event` with `{ session_id }` for raw progress or `codex::agent-event` for the rendered view (or poll `codex::status`); interrupt with `codex::stop`. - Act on the whole backend: turns carry the iii runtime context by default (delivered as Codex `developer_instructions`), 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`. - Plan before touching anything: run the planning prompt with `sandbox_mode: read-only` (writes physically fail), read the plan, then send "implement the plan" on the same `session_id` with `sandbox_mode: workspace-write`. - Get structured final output: pass `output_schema` (JSON schema) and the final agent message is JSON matching it. - Attach screenshots or diagrams: `images: ["/path/a.png"]` adds local images to the prompt. - Wire MCP servers or model providers into one turn: `codex_config` forwards any `config.toml` override, e.g. `{"codex_config": {"mcp_servers": {"github": {"command": "gh-mcp"}}}}`. - Reach past the named payload fields: anything the SDK ThreadOptions accept goes through `options` unchanged, e.g. `{"options": {"networkAccessEnabled": true, "webSearchMode": "live"}}`. ## Boundaries - Spawns the host `codex` CLI per turn — needs Codex installed and authenticated; not available inside a bare container without it. - Execution safety is Codex's own sandbox (`sandbox_mode`), not the engine's: `read-only` blocks writes, `workspace-write` allows edits in `cwd`, `danger-full-access` disables the sandbox. Headless turns run `approval_policy: never`, so blocked commands fail instead of prompting. - One turn per session at a time: check `codex::status` (`live: true`) before sending another `codex::run` for the same `session_id`; parallel runs against one session race on the underlying thread resume. - `codex::agent-event` carries whole-message frames; per-item progress detail (command output as it accumulates, todo lists) exists only on `codex::raw-event`. Both feeds are ephemeral (not stored or replayed); order by `(epoch, seq)`. ## Functions - `codex::run` — run one Codex turn and wait; accepts `prompt` (or a `messages` array whose last user entry becomes the prompt), plus `model`, `cwd`, `sandbox_mode`, `approval_policy`, `reasoning_effort`, `skip_git_repo_check`, `output_schema`, and raw `options`; returns `{session_id, codex_thread_id, result, stop_reason, usage}`. - `codex::start` — same payload, returns `{session_id, started}` immediately; progress arrives on the event feeds. - `codex::stop` — interrupt the live run for a session. - `codex::status` — point-in-time session view: live flag, status, turns, usage. - `codex::sessions::list` — every session this worker has run.