| name | pi |
| description | Run headless Pi coding-agent turns over the iii bus — file edits, shell, and search against any host directory — with verbatim event streaming, session resume, and live steering. |
pi
The pi worker exposes the Pi coding-agent API as iii functions. One pi::run
call executes one headless Pi turn — the same in-process agent loop Pi runs in
the terminal, with the same tools (read, bash, edit, write) — in a chosen
working directory, and returns the final result, token usage, and cost. Every
event Pi emits mirrors untouched onto the pi::events stream; a translated
AgentEvent view lands on agent::events, which is what the iii console and the
acp worker render.
Pi runs the loop in-process (no CLI subprocess), so it needs model credentials
in the worker environment (e.g. ANTHROPIC_API_KEY) or an existing Pi login.
When a turn needs a capability beyond Pi 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: pi::run with prompt and cwd.
- Continue a conversation across calls: pass the same
session_id again and
the worker resumes the underlying Pi session file with full context.
- Run long jobs without holding the call open:
pi::start returns
{session_id, started} immediately; follow pi::events (group_id =
session_id) for raw progress or agent::events for the rendered view;
interrupt with pi::stop.
- Steer a run while it works:
pi::steer injects an instruction applied after
the current tool calls finish; pi::follow_up queues a message processed
after the agent would otherwise 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.
- Tune depth and scope per turn:
thinking_level (off → xhigh) sets reasoning
effort, and tools narrows the active tool set to an allowlist.
Boundaries
- Runs the Pi loop in-process — needs model credentials in the worker
environment; without them a turn fails at the first model request.
- Tool execution happens inside Pi's own tool set (
tools allowlist), not the
engine's permission model; pi::run / pi::start are not agent-callable
without human approval (see iii-permissions.yaml).
- One turn per session at a time: check
pi::status (live: true) before
sending another pi::run for the same session_id; parallel runs against
one session race on the underlying session file.
agent::events carries whole-message frames (message_complete,
function_execution_start/end, turn_end, agent_end); the raw Pi event
shapes (including token deltas via message_update) live on pi::events.
Functions
pi::run — run one Pi turn and wait; accepts prompt (or a messages
array whose last user entry becomes the prompt), plus model, cwd,
thinking_level, tools, and iii_context; returns {session_id, pi_session_id, result, stop_reason, usage, total_cost_usd}.pi::start — same payload, returns {session_id, started} immediately;
progress arrives on the streams.pi::steer — inject a steering instruction into a live run.pi::follow_up — queue a follow-up message for a live run.pi::stop — interrupt the live run for a session.pi::status — point-in-time session view: live flag, status, turns, usage,
cost.pi::sessions::list — every session this worker has run.run::start_and_wait — alias for pi::run under the entrypoint the console
and acp worker drive, so both run Pi with no changes.
