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
iiiverifiedexact versions are immutable; binary and bundle artifacts are 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`).
Paginated single-folder listing 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.
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[]`.**
Search file contents (literal or regex) and/or paths (files and dirs); first match per line only. 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, C210 above); truncated to max_line_bytes and counted in the budget. Default 0.
Glob patterns (same relative-to-root matching) 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.
Root-relative glob patterns paths must match; empty = everything.
Walk dot-files and dot-folders (`.github`, `.env`, …); default true. `false` leaves them out, the way an editor's quick open does.
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 to search (default `.`); globs match relative to its root, result paths are absolute.
Pattern to search for. Treated as a regex when `regex: true`, otherwise as a literal substring. May be empty only when `search_content` is false: a path-only search with no query 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.
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.
Recursive directory snapshot 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).
Apply batched line ops (1-based, inclusive, applied bottom-up) then regex replace ops to one or more files; each file commits atomically. 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`).
Canonical absolute path (resolved through the jail); the caller's input verbatim when resolution failed.
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. Same payload as shell::exec. Host jobs ignore timeout_ms and run until exit or shell::kill; poll with shell::status, list with shell::list. Spawn-time failures are plain-string messages; later failures surface in shell::status, not here.
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 host (default) or { kind: "sandbox", sandbox_id }.
Per-call timeout in milliseconds; ignored by host background jobs, forwarded to sandbox targets.
Change 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. `pattern` is a 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 directory contents. Errors return { code, message }; common: S210 bad path, S211 not found or not accessible, S212 not a directory, S215 jail escape. For paginated or recursive listings prefer coder::list-folder / coder::tree.
Jail-relative when fs.host_roots are set, else absolute.
host (default) or { kind: "sandbox", sandbox_id }.
Metadata for each entry in the directory.
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/rename a path. `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.
Remove a path. `recursive: true` is required to delete 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 a single path (jail-relative when fs.host_roots are set). Returns the entry's type, size, mode, and mtime. 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 (the UUID from 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.
Live PTY sessions with their 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.
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.
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 pre-image (revision and body up to 64 KiB each, 1 MiB per response) and, when a later turn kept it, the body the turn left behind (`after`), so the exact patch of that turn can be shown later. 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.
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.
Internal: keeps the pre-image of a file a shell or coder call is about to change. Observes only; always continues.
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).
Serve the shell worker's injected console UI assets (content function for its console:script / console:style 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.
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).
