grok

name	grok
description	Run headless xAI Grok CLI turns over the iii bus — shell, file edits, and tools against any host directory — with verbatim event streaming and session resume.

grok

The grok worker exposes the xAI Grok CLI as iii functions. One grok::run call executes one headless Grok turn (grok --single <prompt> --output-format streaming-json) — the same agent the user runs in their terminal, with the same XAI_API_KEY, filesystem, and working directory — in a chosen directory, and returns the final result. Every Grok event mirrors untouched onto the grok::events stream; a translated AgentEvent view lands on agent::events, which is what the iii console renders.

Requires the grok CLI on the host with XAI_API_KEY in the worker environment. When a turn needs a capability beyond Grok 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: grok::run with prompt and cwd.
• Continue a conversation across calls: pass the same session_id again and the worker resumes the underlying Grok session with full context.
• Run long jobs without holding the call open: grok::start returns {session_id, started} immediately; follow grok::events (group_id = session_id) for raw progress or agent::events for the rendered view; interrupt with grok::stop.
• Act on the whole backend: turns carry the iii runtime context by default (prepended to the first prompt of a session), 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.

Boundaries

• Spawns the host grok CLI per turn — needs Grok installed and authenticated (XAI_API_KEY); not available inside a bare container without it.
• Tool/command execution is the Grok CLI's own; headless turns auto-approve by default (always_approve: true) so they don't block on an interactive approval prompt. Set always_approve: false to let the CLI's approval policy gate execution.
• One turn per session at a time: check grok::status (live: true) before sending another grok::run for the same session_id; parallel runs against one session race on the underlying session resume.
• agent::events carries whole-message frames; per-item progress detail exists only on grok::events.

Functions

• grok::run — run one Grok turn and wait; accepts prompt (or a messages array whose last user entry becomes the prompt), plus model, cwd, always_approve, and iii_context; returns {session_id, grok_thread_id, result, stop_reason, num_turns}.
• grok::start — same payload, returns {session_id, started} immediately; progress arrives on the streams.
• grok::stop — interrupt the live run for a session.
• grok::status — point-in-time session view: live flag, status, turn count.
• grok::sessions::list — every session this worker has run.