Agent shell

substrio_shell runs one shell command over your app, the way you work on a checkout: grep -rn, sed -n 10,40p, find ... | xargs sed -i, a heredoc, a pipe. It is the operation source.shell (POST /v1/_source/shell, MCP tool substrio_shell).

Mounts

A command starts in /src (or cwd). Any other path, / itself included, is refused with SHELL_PATH_OUTSIDE.

One call, one commit

• Reads see the stores as they are, and every write of the call is staged: a later command in the same call reads what an earlier one wrote (sed -i ... && grep ... sees the edit).
• When the whole command ends with status 0, every /src change lands as ONE commit on the branch (its message: message, else what commit -m set, else the command itself), then each /files write is stored.
• Any other status lands nothing. A refusal ends the call at once and lands nothing.
• A command that changes nothing (a sed -i that matched nothing) makes no commit.
• Nothing is kept between calls: no variables, no working directory, no history. Each call stands alone.

The call

{"command": "grep -rn 'TODO' /src", "branch": "main", "cwd": "/src", "offset": 0, "message": "..."}

The answer

{"stdout": "...", "stderr": "", "exit_code": 0, "offset": 0, "truncated": false, "next_offset": 812,
 "commit": {"branch": "main", "version": "<64 hex>", "number": 14, "changed": ["src/a.js", "src/lib/b.js"]},
 "files": ["exports/report.csv"]}

commit is there only when the call committed; files only when it stored files. exit_code is the last pipeline's status, as in a shell (grep's 1 for no match is an answer, not a refusal).

Output past the output budget is never dropped in silence: the answer carries the first part, truncated: true, and next_offset; call again with offset: next_offset for the next part. stderr_truncated: true says the errors were cut at the same budget.

Budgets

Each is a server setting:

Who may run it

source.shell is a read operation: every caller that may read the app's source may run it, a read-only grant included. A write is checked at the write against the operation it stands for: a /src write as source.edit, a /files write as file.upload. A caller whose grant does not reach it gets SHELL_WRITE_NOT_GRANTED at the first write, and nothing lands.

Grammar

• Pipes |, lists ;, &&, ||, and ! before a pipeline.
• Redirections >, >>, <, 2>, 2>&1, >&2, &>, here-strings <<< and heredocs <<EOF (expanded) and <<'EOF' (literal), <<- strips leading tabs.
• Single quotes, double quotes, backslash escapes.
• Globs *, ? and [...] on unquoted words (a name starting with . is matched only by a pattern that starts with .).
• Variables, a fixed set: $PWD, $HOME (/src), $SRC, $SITE, $FILES, $BRANCH, $?. Any other is SHELL_UNKNOWN_VARIABLE.
• Not in the grammar (SHELL_SYNTAX): $(...) and backticks, subshells ( ), if, for, while, case, functions, NAME=value assignments, background &.

Builtins

An unknown command is refused with SHELL_UNKNOWN_COMMAND, whose detail lists the builtins.

js

js 'SCRIPT' [ARGS], js -e 'SCRIPT', js FILE [ARGS], or js <<'EOF' ... EOF (the heredoc is the script). The script runs in the app's own JavaScript runtime, as a function body with these in scope:

A value the script returns is printed. An uncaught error is status 1 with the error on stderr. A refusal inside fs (a path outside the mounts, a write the grant does not reach) refuses the whole call even when the script catches it.

Refusals

Every refusal carries field: "command" and a detail naming the word, path or budget. Nothing lands on any refusal.

What it costs

Per call: one parse of the command, one head read and one read of what live runs. Each directory is read once per call and each file once (later reads in the call are a hash probe), and every builtin works on a view of those bytes: nothing is copied until the answer is written. A pipe hands one buffer to the next stage (two buffers, reused). A write stages one copy of the new bytes (none for mv or cp of an unchanged file). The commit is one History::commit of every changed unit. A js script takes the app's runtime once per script.

Examples

Find every TODO with line numbers:

{"name": "substrio_shell", "arguments": {"command": "grep -rn TODO /src"}}

Read lines 10 to 40 of a file:

{"name": "substrio_shell", "arguments": {"command": "sed -n 10,40p functions/orders.js"}}

Rename a function across every file, one commit:

{"name": "substrio_shell", "arguments": {"command": "grep -rl getOrders functions | xargs sed -i 's/getOrders/listOrders/g'"}}

Write a new page from a heredoc:

{"name": "substrio_shell", "arguments": {"command": "cat > site/about.html <<'EOF'\n<h1>About</h1>\n<p>We make todo lists.</p>\nEOF"}}

Transform a file with a script:

{"name": "substrio_shell", "arguments": {"command": "js 'const rows = JSON.parse(fs.readFile(\"data/todos.json\")); fs.writeFile(\"data/todos.json\", JSON.stringify(rows.filter(r => !r.done), null, 2)); rows.length'"}}

Compare the source with what is live:

{"name": "substrio_shell", "arguments": {"command": "diff -u /site/index.html site/index.html"}}

Page through a long output:

{"name": "substrio_shell", "arguments": {"command": "cat data/big.csv", "offset": 1048576}}