Unix shell + filesystem worker — exec with denylist/timeout/output caps and background jobs; fs::ls|stat|mkdir|rm|chmod|mv|grep|sed|read|write with host jail, denylist, size caps, and sandbox-target forwarding
iii trigger compose::add worker=ide@0.12.32Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.
Internal console UI: retrieve an exact before/after snapshot by change id.
Exact post-mutation body. Missing when either side is not UTF-8.
Exact pre-mutation body. Missing when either side is not UTF-8.
Create one or more files atomically; per-file overwrite and parents flags. For a conflict-safe overwrite pass the revision from coder::read-file as expected_revision (stale revision: C221, nothing written). Paths: relative to the primary root or absolute inside an allowed root (see coder::info).
Optimistic-concurrency guard for an overwrite: the `revision` from coder::read-file; if the content changed the entry fails C221 unwritten.
Octal permission bits as a string, e.g. "0644". Defaults to "0644".
When false (the default), refuse to write if `path` already exists.
Create missing parent directories. Defaults to true so a single `coder::create-file` call can scaffold a fresh subtree.
File to create.
Structured error for this entry. `code` is stable for programmatic branching (e.g. `"C213"` means already-exists; pass `overwrite=true` to replace). `message` carries the corrective action an LLM agent needs to make a successful second call.
Stable error code, e.g. "C211". See the README error table.
Human/LLM-readable message: problem + actual values + corrective next call.
Canonical absolute path (resolved through the jail); the caller's input verbatim when resolution failed.
Opaque revision for the exact bytes written. Supply this as `expected_revision` on a later overwrite to avoid lost updates.
Remove one or more paths. Directories need recursive: true; missing paths succeed; recursion refuses to descend through non-accessible entries. Paths: relative to the primary root or absolute inside an allowed root (see coder::info).
Paths to remove.
Required for non-empty directories. Files and empty dirs ignore it.
Structured error for this entry. `code` is stable for programmatic branching (e.g. `"C211"` for not-found-or-denied; `"C210"` for refusing to delete an allowed root). `message` carries the corrective action an LLM agent needs to make a successful second call.
Stable error code, e.g. "C211". See the README error table.
Human/LLM-readable message: problem + actual values + corrective next call.
Canonical absolute path (resolved through the jail); the caller's input verbatim when resolution failed.
Report the coder access contract: mode (jailed | unjailed), allowed roots (primary first), the session_root relative paths anchor against, size caps, response budgets, listing/search limits, non-accessible globs and default_exclude_globs. Call it first when a path is rejected.
Canonical absolute paths of the allowed roots, in configuration order. The primary root (index 0) is where relative wire paths resolve; an absolute path is accepted when it canonicalises inside ANY of these (in `unjailed` mode: anywhere on the host). In `jailed` mode paths outside every root are rejected — use `shell::fs::*` instead.
Aggregate budget across a single `paths[]` batch call to `coder::read-file`, measured in bytes of returned content (after UTF-8 sanitization — invalid bytes expand to U+FFFD before being counted, so the cap bounds what the caller actually receives). Entries are collected in request order; each entry may consume up to `min(remaining_budget, max_read_bytes)`. An entry reached with zero remaining budget receives a per-entry C218 naming this key, its value, and the bytes already consumed, with recovery guidance. Budget topology: batch reads are governed by this key; single-path full reads by `max_output_bytes`; windowed reads by `max_read_bytes` applied per returned window — `max_read_bytes` is also the per-file IO ceiling for all of them.
Noise-exclusion globs (root-relative, same matching as `non_accessible_globs`): matching paths (node_modules, .git, …) are omitted from `coder::search` results and pruned from `coder::tree` descent — the directory surfaces as a childless `truncated` stub. Hide-only — no access protection. Pass `use_default_excludes: false` on those calls to look inside.
Default `page_size` used by `coder::list-folder` when the caller omits it.
Hard cap on `page_size` accepted by `coder::list-folder`.
Context budget for single-path FULL reads in `coder::read-file`, in bytes of returned content. Full reads larger than this return C218 with the file's size/line count and window/stat recovery guidance; a per-call `max_output_bytes` override is available on `coder::read-file` (clamped to `max_read_bytes`).
Per-file IO ceiling for `coder::read-file`. Full reads of files larger than this are rejected with C218; windowed reads cap the returned window bytes instead, so larger files stay readable window by window. Also the ceiling for `coder::search` content scanning — larger files are silently skipped during search.
Maximum bytes that `coder::create-file` or `coder::update-file` will accept for a single file write. Larger writes are rejected with C218.
`jailed`: paths must stay inside `base_paths`. `unjailed`: absolute paths anywhere on the host are accepted (deny-only, like `shell::fs::*`) and `base_paths` only anchor relative paths.
Glob patterns matched per root (root-relative). Files whose root-relative path matches are listable but not readable/writable/deletable/creatable; they return C211.
Convenience duplicate of `base_paths[0]` — the primary allowed root. Relative paths resolve against this directory UNLESS `session_root` is set, which takes precedence.
Per-line byte cap in `coder::search`: matching considers at most this many bytes of each line, and matched/context lines are truncated to it.
Default `max_matches` used by `coder::search` when the caller omits it.
Aggregate byte budget for one `coder::search` response, measured in payload bytes (paths + matched text + context lines). When the budget is hit the response sets `truncated: true` — refine the query or add `include_globs`.
The session's working directory when the caller runs under a harness-stamped filesystem scope; `null` otherwise. When set, THIS is what relative wire paths (and `coder::search` glob matching) anchor against — not `primary_root`. In `unjailed` mode it may sit outside every `base_paths` entry, so a relative path that looks wrong against the allowed roots can still be correct here. Check it first when a relative path was rejected.
Default `max_depth` used by `coder::tree` when the caller omits it.
Maximum entries returned per folder node by `coder::tree`; folders that exceed this are flagged `truncated`.
Coder worker version (`CARGO_PKG_VERSION`).
List one folder, paginated and sorted by name. Entries carry only name; entry path = response path + '/' + name. Non-accessible entries are listed with non_accessible: true. Paths: relative to the primary root or absolute inside an allowed root (see coder::info).
Capped at list_max_page_size; defaults to list_default_page_size (see coder::info).
Folder to list (default `.`).
Entry basename. The absolute path is derivable from the response's `path`: entry path = folder path + "/" + name.
True if this entry matches `non_accessible_globs` — caller cannot read/write/delete it via `coder::*` even though it shows up here.
Canonical absolute path of the listed folder (resolved through the jail). Entries carry only `name`; derive an entry's absolute path by joining: entry path = this path + "/" + name. Operations on derived paths re-validate through the jail.
List the worker templates coder::scaffold-worker creates from: id, name, description, language (node | python) and requires (the compose containers the worker needs, e.g. http). source names where they come from: a local dir, or a cached git clone with ref and revision; warning means the clone could not refresh and is stale. refresh: true re-fetches it now.
Re-fetch the cached git clone now instead of after `code.templates.refresh_secs`. No effect on a local dir.
Where the templates were read from.
`dir` (a local checkout) or `git` (a cached clone).
The templates directory (`dir`) or the clone URL (`git`).
Branch or tag of the clone (`git` only).
Commit the clone is at (`git` only).
Set when the clone could not be refreshed and a stale copy is served.
Pass as `template` to coder::scaffold-worker.
Runtime of a worker template, from the template's own `requires`.
Compose containers the worker needs, e.g. `http`.
Move or rename one or more paths; per-entry overwrite and parents flags. Same-root moves rename atomically; cross-root moves copy+delete files only (move directory contents individually) and remove the copy if the delete fails. Paths: relative to the primary root or absolute inside an allowed root (see coder::info).
Entries to move. Each entry is processed independently so a single failure never aborts the rest.
Source path.
When false (the default), refuse to overwrite an existing destination. Pass `overwrite: true` to replace an existing file at `to`.
Create missing parent directories of the destination. Defaults to true.
Destination path.
Structured error for this entry. `code` is stable for programmatic branching (e.g. `"C213"` means destination exists; pass `overwrite=true` to replace; `"C210"` for disallowed operations such as cross-root directory moves, moving a root itself, or a destination that is a directory — the message then names the corrected target path). `message` carries the corrective action an LLM agent needs to make a successful second call.
Stable error code, e.g. "C211". See the README error table.
Human/LLM-readable message: problem + actual values + corrective next call.
Canonical absolute path of the source (resolved through the jail); the caller's input verbatim when resolution failed.
True only when the move fully completed; false for a no-op self-move (`from` and `to` resolve to the same file).
Canonical absolute path of the destination (resolved through the jail); the caller's input verbatim when resolution failed.
Read a file. stat: true probes size/mtime/total_lines without content; line_from/line_to (1-based, inclusive) read a window of a file of any size; numbered: true prefixes absolute line numbers; paths[] (XOR path) batch-reads. Paths: relative to the primary root or absolute inside an allowed root (see coder::info).
Content encoding for full reads; `base64` returns the exact file bytes (encoded length is budgeted). C210 with stat/window/numbered.
First line (1-based, >= 1) of a windowed read; windows keep files over max_read_bytes readable slice by slice. `path` mode only.
Last line of the window, 1-based inclusive, >= `line_from`; omit to read from `line_from` to EOF. `path` mode only.
Full-read byte budget (returned bytes, clamped to max_read_bytes); over budget fails C218 naming size/total_lines. C210 with a window.
Prefix each line with its absolute 1-based file line number (`N→`), matching coder::update-file line ops; C210 with `stat`. `path` mode only.
Single file to read; XOR with `paths` (C210 if both or neither is set).
Batch of files to read in one call (bare path strings or window objects), processed in order against batch_read_budget_bytes; XOR with `path`.
First line of the window, 1-based inclusive (>= 1); defaults to 1 when only `line_to` is set.
Last line of the window, 1-based inclusive, >= `line_from`; omit to read to EOF.
Prefix this entry's lines with their absolute 1-based line numbers (`N→`); prefix bytes count toward the batch budget.
File to read.
Metadata probe for this entry: size/mode/mtime plus total_lines, content null, no budget consumed; C210 with a window or `numbered`.
Metadata probe: size/mode/mtime plus total_lines/is_utf8, no content; C210 with line_from/line_to/numbered/max_output_bytes.
File content as a UTF-8 string — the whole file, or just the requested window when `line_from`/`line_to` was given (window lines keep their newline terminators). Binary content is returned with invalid bytes replaced by U+FFFD; request `encoding: "base64"` when exact bytes matter (content is then the file's bytes base64-encoded). **Single-path mode only; null when the request used `paths[]`.**
Whether `content` survived UTF-8 conversion without losing bytes. Reflects the RETURNED content only: a clean window inside an otherwise-binary file is still `true`. **Single-path mode only; null when the request used `paths[]`.**
Number of lines in `content`. For full reads this equals the file's total line count. **Single-path mode only; null when the request used `paths[]`.**
Unix permission bits (lower 9 bits of `st_mode`), e.g. 0o644. **Single-path mode only; null when the request used `paths[]`.**
True when the file has content beyond what `content` includes: the window ended before EOF, or the byte budget cut the window short. Always false for full reads. **Single-path mode only; null when the request used `paths[]`.**
Last-modified time as a Unix epoch in seconds. **Single-path mode only; null when the request used `paths[]`.**
Canonical absolute path of the file read (resolved through the jail). **Single-path mode only; null when the request used `paths[]`.**
Per-entry results for a batch `paths[]` request. **Present only when the request used `paths[]`; null in single-path mode.**
File content as a UTF-8 string — the whole file or the requested window. Binary bytes are replaced by U+FFFD (`is_utf8: false`). `null` on failure.
Structured error — present only when `success: false`.
Stable error code, e.g. "C211". See the README error table.
Human/LLM-readable message: problem + actual values + corrective next call.
Whether `content` survived UTF-8 conversion without losing bytes. `null` on failure.
Number of lines returned in `content`. `null` on failure.
Unix permission bits (lower 9 bits of `st_mode`), e.g. 0o644. `null` on failure.
`true` when the file has content beyond what `content` includes (window ended before EOF, or byte budget cut the window short). `null` on failure.
Last-modified time as a Unix epoch in seconds. `null` on failure.
Canonical absolute path of the file (resolved through the jail). If resolution failed, this echoes the caller's input verbatim.
Size of the FILE in bytes (from metadata). `null` on failure or when the entry budget was exhausted before the file was opened.
`true` when the read succeeded (content/metadata fields are populated); `false` when an error occurred (only `error` is set).
Total lines in the file; present when the stream reached EOF during this entry's read. `null` when not traversed or on failure.
Opaque identity of the file's exact bytes. Present for complete single-path reads only; pass it as `expected_revision` to `coder::create-file` for a conflict-safe whole-file overwrite.
Size of the FILE in bytes (from metadata) — not the size of `content`; in windowed mode the two differ. **Single-path mode only; null when the request used `paths[]`.**
Total number of lines in the file. Present only when the read traversed the whole file: always for full reads; for windowed reads only when the stream naturally reached EOF within the byte cap. Never computed by forcing an extra full scan — absent means the file was not fully traversed. **Single-path mode only; null when the request used `paths[]`.**
Create a new iii worker from a coder::list-templates template and start it: write its files into directory (default workers/<name>; its last folder must be <name>, C232 otherwise) with the template's name token replaced, all or nothing (a directory that exists and is not empty fails C233), then add it to the stack in the same call (compose::add with the worker, its start_after and the requires the stack lacks) and return operation_id and started, or start_error with the files kept. A container already named <name> fails C235 before any write. To be woken when it is up, register a trigger on an operation_id you pick and pass it here. start: false writes the files only; send the returned compose_add whole to compose::add, adding start_after to its workers entry and one entry per missing requires (never move its fields to the top level, where scripts are ignored, or use the bare worker string form, which drops them). Paths: relative to the primary root or absolute inside an allowed root (see coder::info).
Folder to create the worker in: missing or empty, and its last folder must be `name` (compose names the container after it). Defaults to the template's worker folder for this name (`workers/<name>`).
The new worker's name: lowercase kebab-case, 1-63 chars. It replaces the template's name token, so it names the folder, the compose container and the function prefix (`<name>::hello`).
With start: the compose::add operation id. Pick one and register a trigger on it before this call to be woken when it ends; compose picks one when omitted.
Add the worker to the stack in this call (default true): compose::add with the worker and each requires that compose::status does not list, then return its operation_id. A container with this name already in the stack fails C235 before any file is written. false writes the files only.
With start: containers the worker cannot run without (its compose entry's start_after); compose stops it whenever one of them exits. Never the console's: a worker's UI triggers wait for the console.
Template id from coder::list-templates.
Container object to pass whole in `compose::add { workers: [compose] }` (the bare `worker` string form drops its scripts): `worker` is the absolute folder path; `start_after` is left to the caller.
The compose::add payload: send it whole (do not move its entry's fields to the top level, where scripts are ignored), adding start_after to its workers entry and, for each requires that compose::status does not list, one more entry in workers.
Canonical absolute path of the new worker folder.
Canonical absolute path.
Revision of the bytes written, as coder::read-file reports it.
With start: compose::add's operation (follow it with compose::operation, or a trigger registered on its id).
Compose containers the worker needs (e.g. `http`); add the ones `compose::status` does not list in the same `compose::add`.
With start: why compose::add failed. The files are written; send compose_add to compose::add to add the worker.
With start: the containers compose::add was asked to add, the worker first.
Search file contents (literal or regex) and/or paths (files and dirs); first match per line only; path may be a folder or a single file. default_exclude_globs noise is skipped unless use_default_excludes: false. truncated: true means refine the query, not paginate. Paths: relative to the primary root or absolute inside an allowed root (see coder::info).
Lines of context after each content match; same rules as `context_lines_before`.
Lines of context before each content match (max 10; more is clamped to 10); truncated to max_line_bytes and counted in the budget. Default 0.
Glob patterns (relative to the session root, like include_globs) that exclude paths.
Rank path matches by fuzzy subsequence score (quick-open style) instead of substring/regex matching; `path_matches` then comes back best first. Content matching is unaffected.
Glob patterns paths must match, relative to the SESSION ROOT, never to `path`: with path `ade`, write `ade/README.md` or `**/README.md`, not `README.md`. Empty = everything.
Walk dot-files and dot-folders (`.github`, `.env`, …); default true. `false` leaves them out, the way an editor's quick open does. A `path` that names a dot-file or dot-folder is still searched: naming it is explicit intent.
Bytes per line to consider when scanning content; longer lines are truncated for the match snippet.
Optional explicit cap. Falls back to config when unset.
Folder or file to search (default `.`); a file searches just that file. It only narrows the walk: globs are NOT relative to it, they match paths relative to the session root (or to the configured root that contains them; see coder::info). Result paths are absolute.
Text to find: a literal substring, or a regex with `regex: true`. Always send it; `""` is allowed only when `search_content` is false, and lists every path (with `fuzzy_paths`, shallow and short paths first).
Honour `.gitignore`/`.ignore` rules (inside a Git repository) while walking, the way an editor's search does; default false keeps every non-excluded file searchable.
Search file contents (default true).
Search file paths (default true).
Skip paths matching default_exclude_globs (.git, node_modules, …; see coder::info) in content and path results; false searches inside them.
Context lines immediately after the matched line — same file only, in file order, each truncated to `max_line_bytes`. Omitted when empty (no `context_lines_after` requested, or the match is at the end of the file).
Context lines immediately before the matched line — same file only, in file order, each truncated to `max_line_bytes`. Omitted when empty (no `context_lines_before` requested, or the match is at the start of the file).
Absolute path under the canonical parent; symlinks at the entry itself are not resolved. Operations on it re-validate through the jail.
Matched line; truncated to `max_line_bytes` and never spans newlines.
Set when the request was adjusted to run (a field read under its canonical name, or a value clamped); send the canonical form.
What matched: `file` or `dir`. Directories match by NAME only — content search never reads them.
Absolute path under the canonical parent; symlinks at the entry itself are not resolved. Operations on it re-validate through the jail.
True if results were cut off — either match list hit the `max_matches` cap, or the response hit the `search_response_budget_bytes` byte budget. When true, refine the query or add include_globs rather than paginate.
Show a directory tree, bounded by max_depth, per_folder_limit and a node budget. Nodes carry only name (child path = parent path + '/' + name); over-limit folders are truncated stubs to paginate with coder::list-folder. Paths: relative to the primary root or absolute inside an allowed root (see coder::info).
List dot-prefixed entries; false omits them at every level (they then don't count toward per_folder_limit). The requested root is exempt.
Maximum depth to descend; the root node is depth 0.
Base folder for the snapshot (default `.`).
Maximum children listed per folder. When more exist, the folder is flagged `truncated` and callers should switch to `coder::list-folder`.
Prune directories matching default_exclude_globs (see coder::info) into childless `truncated` stubs; false lists everything.
Canonical absolute path of the requested folder (resolved through the jail). Nodes carry only `name`, and the root node's path IS this `path` — do not join the root's `name` onto it; derive children by joining from here: child path = parent path + "/" + name. Operations on derived paths re-validate through the jail.
Root node of the snapshot; its `name` is the folder's basename.
Entry basename. The ROOT node's path is the response's top-level `path` itself; every other node's path derives by joining from there: child path = parent path + "/" + name.
Set on directories whose `children` was capped at `per_folder_limit`, whose subtree was cut off by `max_depth`, which matched `default_exclude_globs` or omitted matching non-directory children (reason "default_exclude"), or where the snapshot's node budget ran out (reason "max_nodes").
Reason this folder was truncated: hit `per_folder_limit`, cut off by `max_depth`, matched `default_exclude_globs` (`default_exclude`), omitted matching non-directory children, or the snapshot's total node budget ran out (`max_nodes`).
Number of children actually returned.
Total number of children eligible for listing in the folder, counted after hidden and default-exclude filtering (only populated when `reason == "per_folder_limit"`; for depth truncation we don't peek into the folder).
Edit one or more files: batched line ops (1-based, inclusive, applied bottom-up), then regex replace ops; each file commits atomically. To rewrite a whole file use coder::create-file with overwrite: true. To replace a large region use two short anchors joined by .*? with dot_matches_newline: true instead of quoting it. Paths: relative to the primary root or absolute inside an allowed root (see coder::info).
When true `.` also matches newline, so a short pattern like `start.*?end` spans lines; by default a multi-line pattern matches nothing.
Expected match count; a mismatch fails this file with C210 and writes nothing (0 asserts absence). Omit to replace all matches.
Substitution text; $1/${1}/$name/${name} expand captures ($0 = whole match), a literal $ is written $$ (`$${name}`). Unknown references fail C210.
File to edit.
Number of operations applied (only meaningful when `success`).
Per-op bounded post-apply echoes for edit verification; each applied op returns a snapshot of the affected region (±2 context lines) so the caller can confirm the edit landed at the right position without receiving the full file body. See `OpEcho` for field semantics. Empty on failure. Always present on the wire.
Number of middle lines elided from a large region: for line ops, set when the affected region exceeded the per-echo cap; for replace sites, the count of inner lines between the region's echoed first and last line (set when the region spans >2 lines).
1-based line number of the first echoed line (after all ops applied).
The echoed lines, post-apply. When the region is large, middle lines are elided and `elided` is set to indicate how many were skipped.
Index of the op in the request's ops array (0-based).
Total number of replacements the regex op made across the whole file (set only on replace-op site echoes, duplicated on each site). Sites are capped at 5 — when more matched, this count is the only record of the extras.
True when the total echo budget (~4 KiB) was exhausted before all op echoes could be emitted. Use `coder::read-file` to inspect the full result if needed. Always present on the wire.
Structured error for this entry. `code` is stable for programmatic branching (e.g. `"C211"` for not-found-or-denied; `"C210"` for bad input such as overlapping ops). `message` carries the corrective action an LLM agent needs to make a successful second call.
Stable error code, e.g. "C211". See the README error table.
Human/LLM-readable message: problem + actual values + corrective next call.
Final line count after applying (only meaningful when `success`).
Set when ops were sent without `op` and it was inferred from their keys; send `op` explicitly.
Canonical absolute path (resolved through the jail); the caller's input verbatim when resolution failed.
Returns this worker instance's effective configuration entry ID, without its value.
Serve the ide worker's injected console UI assets (content function for its console:script / console:style / console:module triggers).
The asset path from the trigger config (e.g. `state/page.js`).
The asset source, verbatim.
MIME type the console should serve the asset with.
Report the last configuration hot-reload outcome: last_outcome (applied|rejected), last_error, and rejected_reloads since boot. A rejected outcome means shell is enforcing an older policy than the central store. Takes no arguments.
Build error from the most recent rejected reload (why it was refused).
Outcome of the most recent hot-reload attempt, exposed via `shell::config-status`.
Cumulative count of rejected reloads since boot (never reset).
Run a command in the foreground and return its full output. Put the program in `command` (string) and arguments in `args` (string[]), never argv in `command`. Host-only cwd/env/stdin reject S210 on a sandbox target. Errors return { code, message }; common: S216 host exec error, S300 VM boot failed, S200 in-VM failure.
Arguments, in order (all strings). Omit/null to tokenize `command` shell-words style; pass an array (even empty) to use it verbatim.
Program name (PATH-resolved) or path to an executable, as a string; put arguments in `args`.
Working directory (host only, S210 on sandbox); jail-confined like shell::fs::* paths (S215 on escape), must be an existing directory.
Per-call env values (host only, S210 on sandbox); exec-hijacking keys (PATH, IFS, HOME, LD_*/DYLD_*, …) reject the whole call S210.
Bytes written to the program's stdin, then EOF (host only, S210 on sandbox); omit to leave stdin at /dev/null.
Where to run the command. Defaults to the host worker; pass `{ kind: "sandbox", sandbox_id }` to forward the call to a microVM.
Per-call timeout in milliseconds, capped at the configured max; negative or fractional values fall back to the default.
Spawn a background job; returns { job_id, argv } immediately. Accepts the shell::exec payload plus optional job_id. Register shell::job-finished with a fresh job_id before calling exec_bg with that same ID, or omit job_id to generate one. Duplicate retained IDs reject before execution. Host jobs ignore timeout_ms and use the configured background hard cap; read output with shell::status, list jobs with shell::list. Spawn-time failures are plain-string messages; later failures emit shell::job-finished and appear in shell::status.
Arguments, in order (all strings). Omit/null to tokenize `command` shell-words style; pass an array (even empty) to use it verbatim.
Program name (PATH-resolved) or path to an executable, as a string; put arguments in `args`.
Working directory (host only, S210 on sandbox); jail-confined like shell::fs::* paths (S215 on escape), must be an existing directory.
Per-call env values (host only, S210 on sandbox); exec-hijacking keys (PATH, IFS, HOME, LD_*/DYLD_*, …) reject the whole call S210.
Optional non-blank ID for registering shell::job-finished before execution. Must be unique among retained jobs in this worker. Omit or pass null to generate a job-UUID automatically.
Bytes written to the program's stdin, then EOF (host only, S210 on sandbox); omit to leave stdin at /dev/null.
Where to run: the host (default) or { kind: "sandbox", sandbox_id }.
Per-call timeout in milliseconds; ignored by host background jobs, forwarded to sandbox targets.
Change a file or directory's permissions. `mode` is an octal string like "0644". `uid`/`gid` optionally chown. `recursive: true` walks the tree (symlinks skipped). Returns { entries_changed, path, recursive }. Errors return { code, message }; common: S210 bad mode, S211 not found or not accessible, S215 jail escape.
Optional chown to this numeric gid.
Octal permission string, e.g. "0755".
Jail-relative when fs.host_roots are set, else absolute.
Apply mode/owner change to all files under the path recursively.
host (default) or { kind: "sandbox", sandbox_id }.
Optional chown to this numeric uid.
Number of filesystem entries whose mode/owner changed.
The path that was targeted. Empty for sandbox targets.
Whether the change was applied recursively. Host only.
Search file contents for a pattern (Rust regex, RE2-like); `include_glob`/`exclude_glob` filter paths. Returns { matches, truncated }. Errors return { code, message }; common: S217 bad regex, S215 jail escape. coder::search adds context lines and noise filtering.
Glob filters excluding file paths from the search.
Match pattern case-insensitively.
Glob filters restricting which file paths are searched.
Skip lines longer than this many bytes (default 4 096).
Stop collecting matches after this many results (default 10 000).
Jail-relative when fs.host_roots are set, else absolute.
Rust regex (RE2-like) matched against each line.
Descend into subdirectories (default true).
host (default) or { kind: "sandbox", sandbox_id }.
All collected match locations up to `max_matches`.
True when the result was capped by `max_matches` or `max_line_bytes`.
List the files and subdirectories of a directory on the filesystem, sorted by name and paginated: `page` (1-based, default 1) and `page_size` (default 500, max 2000); `has_more: true` means request the next page. Errors return { code, message }; common: S210 bad path, S211 not found or not accessible, S212 not a directory, S215 jail escape. For recursive listings prefer coder::tree.
1-based page of the name-sorted listing. Default 1.
Entries per page. Default 500, clamped to 2000. A directory larger than one page answers `has_more: true` — request the next `page` rather than expecting the whole directory in one result.
Jail-relative when fs.host_roots are set, else absolute.
host (default) or { kind: "sandbox", sandbox_id }.
Metadata for each entry on this page, sorted by name.
True when later pages exist; request `page + 1` to continue.
The 1-based page this response carries.
The page size actually applied (after clamping).
Entries in the whole directory, across every page.
Create a directory. `mode` is an octal string like "0755". `parents: true` creates missing parents and is idempotent. Returns { created, path, already_existed }. Errors return { code, message }; common: S210 bad mode, S213 exists, S215 jail escape.
Octal permission string, e.g. "0755".
Create missing parent directories.
Jail-relative when fs.host_roots are set, else absolute.
host (default) or { kind: "sandbox", sandbox_id }.
True when the path already existed and `parents` was set. Host only; sandbox targets default this to false (not a signal there).
True when a new directory was created; false when it already existed (only possible with `parents: true`, which is idempotent).
The directory path that was targeted. Empty for sandbox targets.
Move or rename a file or directory. `overwrite: true` allows replacing an existing dst. Returns { moved, src, dst, overwrote }. Errors return { code, message }; common: S211 src not found or not accessible, S213 dst exists, S215 jail escape. coder::move moves several paths per call.
Destination path; jail-relative when fs.host_roots are set, else absolute.
Replace an existing destination instead of returning an error.
Source path; jail-relative when fs.host_roots are set, else absolute.
host (default) or { kind: "sandbox", sandbox_id }.
Destination path. Empty for sandbox targets.
True when the move/rename succeeded.
True when an existing destination was overwritten. Host only (sandbox targets default this to false, not a signal there). Best-effort: derived from a pre-rename existence check, so under a concurrent writer racing the destination it may under-report (and an `overwrite:false` move can still replace a file created in that window).
Source path. Empty for sandbox targets.
Stream a file: returns a ContentRef handle (channel_id/access_key) plus size/mode/mtime, NOT the text — for text use coder::read-file, which returns content inline. Errors return { code, message }; common: S211 not found or not accessible, S212 is a directory, S218 over max_read_bytes, S216 channel/IO error.
Jail-relative when fs.host_roots are set, else absolute.
host (default) or { kind: "sandbox", sandbox_id }.
Channel reference for streaming the file content back to the caller.
Secret key that authorises access to this channel.
Opaque identifier for the open stream channel.
Direction of data flow: "read" (consume) or "write" (produce).
Octal permission string of the file, e.g. "0644".
Last-modified time as a Unix timestamp (seconds).
File size in bytes at the time of the read.
Delete a file or directory. `recursive: true` is required for a non-empty directory. Returns { removed, path, was_present }. Errors return { code, message }; common: S211 not found or not accessible, S214 dir not empty, S215 jail escape. coder::delete-file removes several paths per call.
Jail-relative when fs.host_roots are set, else absolute.
Required to delete a non-empty directory.
host (default) or { kind: "sandbox", sandbox_id }.
The path that was targeted. Empty for sandbox targets.
True when the path was removed.
True when the path existed before removal. Host only; sandbox targets default this to false, which does NOT mean the path was absent.
Find-and-replace across files. `pattern` is a Rust regex (regex: false for a literal). Provide either `files` or `path` (+ recursive). Returns { results, total_replacements }. Errors return { code, message }; common: S217 bad regex, S211 not found, S215 jail escape.
Glob filters excluding file paths from editing.
Explicit list of file paths to edit; provide either this or `path`, not both.
Replace only the first match per file instead of all matches.
Match pattern case-insensitively.
Glob filters restricting which file paths are edited.
Root path to walk for files; used with `recursive`, `include_glob`, `exclude_glob`.
Rust regex by default; set regex:false for a literal string.
Descend into subdirectories when `path` is set (default true).
Treat pattern as a regex (default true) or a literal string (false).
String to substitute for each match.
host (default) or { kind: "sandbox", sandbox_id }.
Per-file replacement details.
Sum of replacements made across all files.
Stat one file or directory: its type, size, mode, and mtime (paths jail-relative when fs.host_roots are set). Errors return { code, message }; common: S211 not found or not accessible, S215 jail escape. coder::read-file with stat: true additionally reports total_lines.
Jail-relative when fs.host_roots are set, else absolute.
host (default) or { kind: "sandbox", sandbox_id }.
Write a file. A string `content` is written inline (host only); large payloads or a sandbox target need a ContentRef { channel_id, access_key, direction } from a write stream channel. `files: [...]` writes several files (host, inline). Errors return { code, message }; common: S210 bad mode or inline-on-sandbox, S218 over max_write_bytes.
Single-file content: an inline string (host only) or a ContentRef { channel_id, access_key, direction } for an open write stream; omit with `files`.
Secret key that authorises access to this channel.
Opaque identifier for the open stream channel.
Direction of data flow: "read" (consume) or "write" (produce).
Batch form: write several files in one call. When present, the single-file fields (`path`/`content`/`mode`/`parents`) must be omitted.
Inline string (recommended) or a streaming ContentRef.
Secret key that authorises access to this channel.
Opaque identifier for the open stream channel.
Direction of data flow: "read" (consume) or "write" (produce).
Octal permission string, e.g. "0644".
Create missing parent directories.
Jail-relative when fs.host_roots are set, else absolute.
Octal permission string for the single-file form, e.g. "0644" (the default); omit when using `files`.
Create missing parent directories (single-file form, default false); omit when using `files`.
Single-file form: the path to write. Jail-relative when fs.host_roots are set, else absolute. Omit when using `files`.
host (default) or { kind: "sandbox", sandbox_id }.
Bytes written: this file for a single write; the sum across `files` for a batch write.
Per-file results for a batch (`files: [...]`) write; empty for a single-file write.
Bytes written to this file.
Path of the written file.
Path written for a single write; empty for a batch (see `files`).
Terminate a running background job by job_id (returned by shell::exec_bg). Errors return { code, message }; common: S211 no such job, S216 kill/signal delivery failure.
List background jobs (running + recently completed). Takes no arguments.
Internal: reload the security policy + fs backend on configuration change.
Configuration id that changed (advisory; the handler re-fetches the value). Schema-only: kept to publish a typed request schema; the handler ignores it.
Take back an unattached PTY session whose reconnect token is gone, from the console page that owns it. Refuses a session someone is attached to, and a page that is not the session's own.
Where output goes next; must belong to the same console page family as the target it replaces.
Attach to a retained PTY session and replay buffered output.
Terminate and close a PTY session.
Detach a browser output target while retaining its PTY session.
Open a persistent host PTY running the user's login shell, or the program named in `program`.
argv for `program`. Ignored without `program` (a login shell takes no arguments here).
Extra environment on top of what the worker forwards; exec-hijacking keys (PATH, LD_*, DYLD_*, BASH_ENV, …) fail the call.
Program to run instead of the user's login shell (an agent CLI, REPL, TUI), resolved on the worker's PATH.
The program the session runs; absent for a login shell.
Resize a PTY session in terminal columns and rows.
List live PTY sessions with program, cwd, sequence, replay buffer size, and output target. Diagnostics only — no credentials.
Frames still replayable from the ring buffer.
Where output is being delivered; absent while detached.
Sequence number of the last frame the session produced.
Whether the buffer has dropped frames a full replay would need.
The console page family this session belongs to — the `<name>` in `iii::<name>-ui::pty-output::console-<browser>`. Present whether or not anyone is attached, because it is what a page uses to recognise its own orphaned session; it names a page, never a browser.
Write base64-encoded keyboard input to a PTY session.
Console-only: write a git commit message for the diff text `changes` (stat + unified diff, capped at 60000 chars) with an LLM through router::complete. Optional `recent_subjects` give the repository's style; `fallback_model` (provider::model) is used when commit_messages.model is unset. Returns { message, model }. Errors return { code, message }: NO_MODEL no model configured or passed, EMPTY_CHANGES blank diff, ROUTER_FAILED the model call failed, EMPTY_MESSAGE the model returned no text.
Diff text prepared by the UI (stat + unified diff). Capped at 60000 characters; the rest is cut and marked `[diff truncated]`.
`provider::model` (or bare model id) used when `commit_messages.model` is unset: the chat's default model.
Recent commit subjects of the repository, for style.
The commit message: summary line, and a body when the change needs one.
The model id actually used, as configured or passed.
Console-only: the live `commit_messages` settings behind the Commit panel's Generate button. Returns { model: string|null, thinking: string, instructions: string }; `model` is null when unset (the panel then passes the chat's default model as `fallback_model`).
Configured `commit_messages.instructions`.
Configured `commit_messages.model`, trimmed; null when unset.
Configured reasoning effort: default|minimal|low|medium|high|xhigh.
Fetch the full record (status, exit_code, timing) of a background job by job_id. Errors return { code, message }; common: S211 no such job.
Internal: add a newly created project root to the active Harness turn after a confirmed workspace proposal.
Fetch one turn of a session's change history: every file it changed, the change kind, the function that made it, the sub-agent that did it when one did, the file's body before the turn and, once the turn has ended or a later turn kept it, the body it left behind (`after`). Bodies come from the root's tree snapshots when the turn has them, hooked or not, else from the hooks' pre-images; 1 MiB of bodies per response. Omit turn_id for the newest turn.
Omit for the newest turn.
The body after this turn's last write, when a later turn kept it as its own pre-image. Never stored; filled in by `shell::turns::get`. Absent means the working copy is the body after this turn.
UTF-8 body before the write. Never stored in the record; filled in by `shell::turns::get` from the blob store, up to `MAX_PRE_IMAGE_BYTES`.
The path did not exist before the call.
`sha256:<hex>` of the bytes before the write; absent when the file did not exist or could not be read. Doubles as the blob key.
A blob for `revision` exists in the store.
The body was larger than the cap (not kept) or did not fit the response budget; the revision still identifies it.
Revision after the last write, when the file could be read back.
The sub-agent session that made the change, when it was not the turn's own session. Children's changes are recorded under the turn of the top-level agent that spawned them, so one turn reads as one unit of work whoever did the typing.
The `subagent_display` name the harness stamped, when it did.
UTF-8 body before the write. Never stored in the record; filled in by `shell::turns::get` from the blob store, up to `MAX_PRE_IMAGE_BYTES`.
The path did not exist before the call.
`sha256:<hex>` of the bytes before the write; absent when the file did not exist or could not be read. Doubles as the blob key.
A blob for `revision` exists in the store.
The body was larger than the cap (not kept) or did not fit the response budget; the revision still identifies it.
Function id that made the change.
Set for a `moved` record: where the file came from.
`created` | `modified` | `deleted` | `moved`.
Absolute path on the host.
The session's workspace root at the time, when the harness named one.
Trees of the root around the turn (see `turn_snapshot`): where `shell::turns::get` reads the sides of every file from, hooked or not.
The tree when the turn ended; absent while it runs.
When `after` was taken. A file the turn was still gaining after that (a sub-agent at work past its parent's end) is not in the tree; its after side is the working copy.
The tree when the turn started.
When `before` was taken, unix ms.
The canonical root the trees describe.
The first characters of the message that started the turn, from the harness `turn-started` event; what a timeline calls the turn.
List the turns of a harness session with the files each one changed through shell or coder functions, newest first. Paths and kinds only; use shell::turns::get for the pre-images.
Newest first.
Paths with their change kind, without bodies.
The sub-agent that made the change, when it was not the turn's own session.
The `subagent_display` name the harness stamped, when it did.
First characters of the message that started the turn.
Internal: records a file change made through a shell or coder call into the session's durable change history. Observes only; always continues.
The call's return value (`post_trigger` only). `touches` reads the files `coder::scaffold-worker` wrote from it.
Internal: photographs the session's workspace root as a turn ends, the after side of every file it changed. Observes only; always continues.
The call's return value (`post_trigger` only). `touches` reads the files `coder::scaffold-worker` wrote from it.
Internal: keeps the pre-image of a file a shell or coder call is about to change. Observes only; always continues.
The call's return value (`post_trigger` only). `touches` reads the files `coder::scaffold-worker` wrote from it.
Internal: photographs the session's workspace root before a turn's first call, so every file the turn changes has an exact before, however it is written. Observes only; always continues.
The call's return value (`post_trigger` only). `touches` reads the files `coder::scaffold-worker` wrote from it.
Internal: closes a turn in the session's change history.
First characters of the message that started the turn.
The spawning turn, for a sub-agent session.
Internal: opens a turn in the session's change history.
First characters of the message that started the turn.
The spawning turn, for a sub-agent session.
Undo the file changes one turn made, from the pre-images kept in the change history: created files are removed, modified and deleted files get their earlier body back, moved files return to their original path. Pass `paths` to revert a subset. Per-file results say what happened; bodies that were never stored are reported, not guessed.
Restrict the revert to these absolute paths; omit for every file the turn changed.
Files whose revert failed; their `error` says why.
`restored` (body written back), `removed`, `moved-back`, or `skipped` (nothing to undo, e.g. a delete of a file that never existed).
The recorded change kind that was undone.
Files whose revert succeeded (skips included).
Console-only: the explorer page's stored state for one pane (`key` is the console pane id; `legacy_key`, the workspace tab id, is read when the pane has nothing stored). `state` is null when nothing is stored. Kept under the worker's data directory, per pane.
The pane's state key (the console pane id).
The workspace tab id: saves made before panes had ids are read from here when `key` has nothing stored.
The stored object, or null when nothing is stored.
Console-only: replace the explorer page's stored state for one pane. Writes only that pane's file, atomically, so panes never clobber each other.
The pane's whole state; replaces what was stored.
Size of the stored document.
Console-only workspace picker control plane: list child directories under an existing host directory. Returns canonical paths and never returns files.
Console-only: one bounded byte range of a file, base64 (at most 4 MiB raw per call), so a page can stream a large image without one oversized frame.
Bytes to return; omitted or over the cap = `READ_BYTES_MAX_CHUNK`.
First byte of the range (default 0).
Absolute path, or relative to the primary root (same rules as coder::read-file).
The chunk, base64 (standard alphabet, padded).
True when `offset + length` reached the end of the file.
Raw bytes in this chunk (before base64).
Last-modified time as a Unix epoch in seconds.
Offset the returned range starts at.
Canonical absolute path.
Size of the whole file in bytes.
Console-only workspace picker control plane: return canonical host directory anchors that an operator can browse before choosing a per-session working directory.
Console-only workspace picker control plane: validate that `path` is an existing host directory and return its canonical path.
Fires when anything under the watched directory changes, whoever changed it — bind with config: { path } naming the directory (jail-checked like every coder::* path). Ignored paths (git-ignored; outside a repository data/, config/, .iii/, node_modules/) are skipped unless config also sets include_ignored: true, which also watches inside ignored trees. Symlinks are not followed. A tree holding more than 32768 directories (fewer on a host with a low inotify limit) is watched breadth-first from the top for that many: changes deeper down go unreported.
Fires when the git repository a directory sits in changes state — bind with config: { path } naming any directory in the worktree (jail-checked like every coder::* path). One event per ~200 ms batch, listing what moved in `changes`: head (this worktree's HEAD: a switch, a checkout), index (staged changes, a commit), refs (branches, tags, remotes, packed-refs), worktrees (another worktree's HEAD, a worktree added or removed), repository (the repository appeared, disappeared or moved — re-read everything). A path in no repository fires repository once a .git appears in it. Worktree file edits are not reported here: bind shell::changed for those.
The directory whose repository to follow (jail-checked).
What moved in this batch, sorted: `head`, `index`, `refs`, `worktrees`, `repository`.
The repository's common dir (refs, packed-refs, worktrees).
The worktree's own git dir (`.git`, or `<common>/worktrees/<name>`).
The watched directory: the binding's `path`, canonical.
The worktree's top level; absent while `path` is in no repository.
Fires once when a shell::exec_bg background job reaches a terminal status (finished, killed, or failed). Bind with config: { job_id } to wake on one job (replaying its result if already terminal and still retained), or omit it to receive future completions. The event carries job_id, argv, status, exit_code and timings; call shell::status for the job's output.
Replay a terminal job while its record is retained in worker memory.
The command as spawned, so a subscriber bound without a `job_id` filter can tell jobs apart without a second call.
`None` when the job never produced one (killed before exit, or a sandbox response that carried no code).
`finished`, `killed`, or `failed` — never `running`.
Fires when a session's change history (shell::turns::list) changes: a turn opened or closed, a file change recorded, a snapshot taken. Bind with config: { session_id } for one top-level session, or omit it for every session. At most one event per session per ~200 ms, carrying { session_id }; read the turns with shell::turns::list.
The top-level session to follow. A sub-agent's changes are recorded under the session that spawned it, so they wake this binding too.
Find workers, kits and executables, or jump to a page.