devin

The devin worker exposes Devin as iii functions across two distinct surfaces.

The CLI surface drives the local Devin CLI (the SWE-1.6 coding agent that runs in your terminal on your files). devin::run executes one headless turn (devin --permission-mode dangerous --print -- ) and streams stdout onto devin::events with a terminal AgentEvent frame on agent::events. Because the agent runs locally with the iii runtime context prepended, a plain-language prompt makes Devin discover and operate your engine on its own: it runs iii trigger engine::functions::list, calls any registered function, and reports back, reaching the engine at localhost with no exposure.

The cloud surface calls the Devin REST API: devin::session::create starts an autonomous cloud session, devin::session::get reads it, devin::session::message steers it, devin::pr-review::* runs code reviews, and devin::api reaches any endpoint the typed wrappers do not cover.

The CLI surface needs the official Devin CLI installed (brew install --cask devin-cli) and authenticated (devin auth login). The cloud surface needs DEVIN_API_KEY (and DEVIN_ORG_ID for a service key). When a run needs a capability beyond Devin itself, add another iii worker to the bus instead of bolting it on.

When to Use

• Delegate a coding task to the local agent in a chosen directory: devin::run with prompt and cwd; follow devin::events / agent::events; interrupt with devin::stop.
• Have Devin operate your iii mesh: with iii_context on (default), ask a plain question ("what workers are connected and what does each do?") and Devin discovers and calls engine functions itself through the iii CLI.
• Delegate a whole task to Devin's cloud agent ("open a PR that adds X"): devin::session::create, then poll devin::session::get and steer with devin::session::message.
• Review a pull request: devin::pr-review::trigger with a pr_url, then devin::pr-review::status; bind a GitHub PR-opened trigger for auto-review.
• Reach any other Devin capability with no typed wrapper (knowledge, playbooks, secrets, repos, code scan, org admin): devin::api with { method, path, query?, body? }.
• Schedule or fan out: bind a cron trigger to devin::session::create, or spawn multiple runs with harness::spawn. The worker does not re-implement scheduling or sub-agents.

Boundaries

• devin::run / devin::start spawn the local Devin CLI headless with --permission-mode dangerous by default, so the agent auto-approves all local tools (needed to run iii trigger without blocking). Drop to accept-edits or auto via cli_extra_args to restrict it.
• devin::run needs the official Devin CLI installed and devin auth login; it is not available inside a bare container without it.
• The cloud surface spends ACUs and mutates real Devin state; cloud functions return JSON directly and do not stream, so poll devin::session::get (or schedule the poll with cron) rather than spinning a tight loop.
• Mutating functions (run, start, session::create / message, pr-review::trigger, api) stay at the needs_approval default; read-only reads and stop are allow-listed.
• An empty api_key disables the cloud surface; the CLI surface still works if the local binary is authenticated.

Functions

• devin::run — run one local CLI turn and wait; accepts prompt (or a messages array), cwd, and iii_context; returns {session_id, devin_session_id, url, result, stop_reason, is_error}.
• devin::start — same payload, returns {session_id, started} immediately; progress arrives on the streams.
• devin::stop — interrupt the live CLI run for a session.
• devin::status — point-in-time view of a recorded run: live flag, status, linked Devin session id.
• devin::sessions::list — every run this worker has recorded (each linked to its Devin session). For all cloud sessions org-wide, use devin::api.
• devin::session::create — start a Devin cloud session; accepts prompt (or a messages array) plus title, tags, playbook_id, knowledge_ids, secret_ids, max_acu_limit, and the v3 (devin_mode, repos, ...) or v1 (snapshot_id, unlisted, idempotent) fields your token accepts.
• devin::session::get — fetch one session by id (status, output).
• devin::session::message — send a follow-up message to a running session.
• devin::pr-review::trigger — start a Devin review for a pr_url.
• devin::pr-review::status — latest review for a pr_url (optional commit_sha).
• devin::api — raw authenticated call to any v1/v3 endpoint: { method, path, query?, body? }.