Agent shell

substrio_shell supports commands such as grep -rn and sed -n 10,40p. It is the source.shell operation (POST /v1/_source/shell, MCP tool substrio_shell).

There is no process or access to the host filesystem. The server interprets a POSIX shell subset, and each command is a builtin operating on the app's stores. Paths cannot use .. to leave a mount. Symlinks, devices, and network access are unavailable.

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 exits with status 0, every /src change is committed together on the branch. The commit message comes from message, commit -m, or the command itself, in that order. Each /files write is then stored.
• Any other exit status writes nothing. A refusal ends the call immediately and writes 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 present only when the call committed; files appears only when it stored files. exit_code is the last pipeline's status, as in a shell. For example, grep's status 1 means no match and is not a refusal.

When output exceeds the budget, the response contains the first part, truncated: true, and next_offset. Call again with offset: next_offset for the next part. stderr_truncated: true indicates stderr was cut at the same budget.

Budgets

Each is a server setting:

Who may run it

source.shell is a read operation. Anyone allowed to read the app's source can run it, including a caller with a read-only grant. Each write is checked against its corresponding operation: source.edit for /src, or file.upload for /files. A caller without the required grant receives SHELL_WRITE_NOT_GRANTED at the first write, and nothing is written.

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}}