nexus_list_artifacts and nexus_get_artifact: read what an agent wants (#175) #200

Merged
lz merged 27 commits from feat/mcp-artifacts into main 2026-09-23 18:46:27 +02:00
Owner

Closes #175. Plan: docs/superpowers/plans/2026-09-23-mcp-artifact-reads.md.

Stacked on #199 (feat/mcp-status). Both PRs touch the same ToolDeps, fixtures, registry and tool-name arrays, and this PR's list description points models at #199's id filter on nexus_list_sessions. Retarget to main once #199 merges.

This covers the second step of the phone loop, "what does it want?". It sits between nexus_get_status (#155) and send_message (#158).

The tools

  • nexus_list_artifacts(session?, limit, offset)
    • Lists plans, reports, screenshots and other registered files, newest first.
    • Covers one session, or the whole fleet when session is omitted.
    • Each field describes itself on the wire.
    • An unknown session id is refused with a sentence naming nexus_list_sessions. A real session with no artifacts gets an empty page.
  • nexus_get_artifact(artifact)
    • Returns the text of one artifact, plus its metadata.
    • Text is capped at 64 KiB by its own constant, MCP_TEXT_MAX, not the 256 KiB editor limit.
    • Past the cap, truncated: true is set and size is the whole file's size.
    • A multi-byte character cut at the cap is dropped rather than decoded as U+FFFD.
  • Both tools are nexus:read and read-only.
  • path is described as relative to the session's worktree.

Failures are sentences, and refusals are not faults

resolveWorkerFs throws SvelteKit's HttpError, which is not an Error. Without handling, the model would receive {"message":"worker container not found"}. Instead, every failure to find or read the file becomes a sentence:

  • Stopped workspace: "the workspace is not running (its container is exited) — if it was stopped, start it in Nexus, then ask again".
  • Container gone: the sentence says so.
  • File moved, deleted, binary or a symlink: the sentence names the path.
  • Image or video: refused by kind before anything is read.

Refusals written for the model, from every tool, are thrown as ToolRefusal. The registry logs each once at info, with no stack. Anything unrecognised is logged at error with its cause, and the model gets a generic sentence. A database fault still throws.

Hardening that came with it

Artifact contents now reach bearer clients, so this PR also rebuilds the read path that the web UI, the raw endpoint and MCP share: WorkerFsService.readFile.

One exec, one opened file. The read is now a single timeout 30 sh -c …. It opens the target once on fd 3 and decides everything from /proc/self/fd/3, then reads that same descriptor:

  • containment inside the session's base;
  • the base resolving to itself;
  • a regular-file check;
  • the .nexus exclusion below.

A refused file exits before head, so its bytes never leave the container. Before this PR there was no containment check at all. Tested live: a symlinked directory in the middle of a path (docs → /workspace/.nexus) returned TOPSECRET. It is now refused, while a symlinked directory that stays inside the worktree still reads.

Deterministic race tests swap a directory between open and check, in both directions, and confirm that reverting to "read by path" or "check by path" fails.

Nexus's own directory is off limits to artifacts. MCP, agent registration and the operator artifact routes refuse anything whose opened name is inside /workspace/.nexus. The workspace shell's base is /workspace, which would otherwise admit .nexus/secrets.env (FORGEJO_TOKEN, REPO_CLONE_URL_AUTHED). The operator's file explorer is unaffected.

What containment does not stop. It holds the kernel's name for the opened file inside the base. That stops Nexus following a confused or symlinked path out of the worktree. It does not stop a hostile agent: the agent runs as root on the same volume, so it can cp or hardlink a file into its worktree and register it. The comments and AGENTS.md say so.

Other readFile fixes:

  • An oversized file is refused from its size, before any bytes are read. An intermediate version of this PR read the file first: about 140 MB at the 100 MiB media cap. The unauthenticated agent-registration route could trigger that repeatedly.
  • Truncation is reported from what was actually read, so a file that grew after the size check is still marked truncated.
  • A failed read no longer looks like success (this bug predates the PR). head … | base64 exits with base64's status, so a failed head came back as empty content. Measured on the worker image.
  • mtime was always NaN (also predates the PR). On GNU coreutils 9.1 the old stat format %Y.%6N prints the quoted file name after the dot. It is now %.6Y.
  • Fewer round trips. Every read is now one docker exec instead of three.

Other supporting changes

  • listArtifacts:
    • The session filter is optional, written as an if. A conditional .where would bind an undefined parameter, which matches nothing in SQLite.
    • Comment counts come from one grouped subquery. It replaces one query per artifact, and avoids an id list that would fail above SQLite's 32,766-variable limit.
  • classifyReadFailure (artifacts/read-failure.ts) is now the single mapping of VolumeFsError/HttpError for the three artifact routes and MCP. A reviewer checked each route's responses route by route: they are unchanged, except for a file resolving inside /workspace/.nexus, which is now refused.
  • Artifact kinds and sources are value arrays in schema.ts.

⚠️ Existing grants gain artifact reading on deploy

Scopes are coarse. Every already-issued nexus:read token, including the one authorized on 2026-09-17, can read artifacts the moment this deploys.

The new consent wording ("…and what agents have written") fixes what the next operator agrees to. It does not change what an existing grant agreed to. Revoking a grant is #171 §1, which does not exist yet.

Checked

  • Live, against node build/server.js with real containers, on both MCP protocol legs:
    • the fleet listing;
    • byte-exact content;
    • a truncation boundary that falls inside a €;
    • every refusal sentence;
    • the symlink escape.
  • Live, driving readFile directly against a container for every case × base × flag.
  • Review:
    • a simplify pass;
    • a five-angle review (code, tests, silent failures, comments, types);
    • separate reviews of the hardening commits and of the single-exec rewrite. The last one used a race harness.
  • Mutation testing: every guard added was mutation-tested and fails its named test. The one exception is the in-script type check after open. [ -f ] and exec 3< are both shell builtins, so no deterministic test can swap between them. The JS type check behind it still refuses.

Not in this PR

  • Images as MCP image content blocks. These need a second, much smaller cap.
  • Artifact feedback through MCP. This belongs with #158.
  • Write-side containment. writeFile, mkdir, rename and deletePath still check only the path text. They serve the operator's cookie-authenticated file explorer, not MCP.
  • Route-level tests for the three operator artifact routes. Their shared mapping is pinned in read-failure.test.ts.
Closes #175. Plan: `docs/superpowers/plans/2026-09-23-mcp-artifact-reads.md`. **Stacked on #199** (`feat/mcp-status`). Both PRs touch the same `ToolDeps`, fixtures, registry and tool-name arrays, and this PR's list description points models at #199's `id` filter on `nexus_list_sessions`. Retarget to `main` once #199 merges. This covers the second step of the phone loop, *"what does it want?"*. It sits between `nexus_get_status` (#155) and `send_message` (#158). ## The tools - **`nexus_list_artifacts(session?, limit, offset)`** - Lists plans, reports, screenshots and other registered files, newest first. - Covers one session, or the whole fleet when `session` is omitted. - Each field describes itself on the wire. - An unknown session id is refused with a sentence naming `nexus_list_sessions`. A real session with no artifacts gets an empty page. - **`nexus_get_artifact(artifact)`** - Returns the text of one artifact, plus its metadata. - Text is capped at **64 KiB** by its own constant, `MCP_TEXT_MAX`, not the 256 KiB editor limit. - Past the cap, `truncated: true` is set and `size` is the whole file's size. - A multi-byte character cut at the cap is dropped rather than decoded as U+FFFD. - Both tools are `nexus:read` and read-only. - `path` is described as relative to the session's worktree. ## Failures are sentences, and refusals are not faults `resolveWorkerFs` throws SvelteKit's `HttpError`, which is not an `Error`. Without handling, the model would receive `{"message":"worker container not found"}`. Instead, every failure to find or read the file becomes a sentence: - **Stopped workspace:** "the workspace is not running (its container is exited) — if it was stopped, start it in Nexus, then ask again". - **Container gone:** the sentence says so. - **File moved, deleted, binary or a symlink:** the sentence names the path. - **Image or video:** refused by kind before anything is read. Refusals written for the model, from every tool, are thrown as `ToolRefusal`. The registry logs each once at `info`, with no stack. Anything unrecognised is logged at `error` with its cause, and the model gets a generic sentence. A database fault still throws. ## Hardening that came with it Artifact contents now reach bearer clients, so this PR also rebuilds the read path that the web UI, the raw endpoint and MCP share: `WorkerFsService.readFile`. **One exec, one opened file.** The read is now a single `timeout 30 sh -c …`. It opens the target once on fd 3 and decides everything from `/proc/self/fd/3`, then reads that same descriptor: - containment inside the session's base; - the base resolving to itself; - a regular-file check; - the `.nexus` exclusion below. A refused file exits before `head`, so its bytes never leave the container. Before this PR there was no containment check at all. Tested live: a symlinked directory in the middle of a path (`docs → /workspace/.nexus`) returned `TOPSECRET`. It is now refused, while a symlinked directory that stays inside the worktree still reads. Deterministic race tests swap a directory between open and check, in both directions, and confirm that reverting to "read by path" or "check by path" fails. **Nexus's own directory is off limits to artifacts.** MCP, agent registration and the operator artifact routes refuse anything whose opened name is inside `/workspace/.nexus`. The workspace shell's base is `/workspace`, which would otherwise admit `.nexus/secrets.env` (`FORGEJO_TOKEN`, `REPO_CLONE_URL_AUTHED`). The operator's file explorer is unaffected. **What containment does not stop.** It holds the kernel's name for the opened file inside the base. That stops Nexus following a confused or symlinked path out of the worktree. It does not stop a hostile agent: the agent runs as root on the same volume, so it can `cp` or hardlink a file into its worktree and register it. The comments and AGENTS.md say so. **Other `readFile` fixes:** - **An oversized file is refused from its size, before any bytes are read.** An intermediate version of this PR read the file first: about 140 MB at the 100 MiB media cap. The unauthenticated agent-registration route could trigger that repeatedly. - **Truncation is reported from what was actually read**, so a file that grew after the size check is still marked truncated. - **A failed read no longer looks like success** (this bug predates the PR). `head … | base64` exits with `base64`'s status, so a failed `head` came back as empty content. Measured on the worker image. - **`mtime` was always `NaN`** (also predates the PR). On GNU coreutils 9.1 the old stat format `%Y.%6N` prints the quoted file name after the dot. It is now `%.6Y`. - **Fewer round trips.** Every read is now one `docker exec` instead of three. ## Other supporting changes - **`listArtifacts`:** - The session filter is optional, written as an `if`. A conditional `.where` would bind an undefined parameter, which matches nothing in SQLite. - Comment counts come from one grouped subquery. It replaces one query per artifact, and avoids an id list that would fail above SQLite's 32,766-variable limit. - **`classifyReadFailure`** (`artifacts/read-failure.ts`) is now the single mapping of `VolumeFsError`/`HttpError` for the three artifact routes and MCP. A reviewer checked each route's responses route by route: they are unchanged, except for a file resolving inside `/workspace/.nexus`, which is now refused. - **Artifact kinds and sources** are value arrays in `schema.ts`. ## ⚠️ Existing grants gain artifact reading on deploy Scopes are coarse. **Every already-issued `nexus:read` token, including the one authorized on 2026-09-17, can read artifacts the moment this deploys.** The new consent wording (*"…and what agents have written"*) fixes what the next operator agrees to. It does not change what an existing grant agreed to. Revoking a grant is #171 §1, which does not exist yet. ## Checked - **Live, against `node build/server.js` with real containers, on both MCP protocol legs:** - the fleet listing; - byte-exact content; - a truncation boundary that falls inside a `€`; - every refusal sentence; - the symlink escape. - **Live, driving `readFile` directly against a container** for every case × base × flag. - **Review:** - a simplify pass; - a five-angle review (code, tests, silent failures, comments, types); - separate reviews of the hardening commits and of the single-exec rewrite. The last one used a race harness. - **Mutation testing:** every guard added was mutation-tested and fails its named test. The one exception is the in-script type check after open. `[ -f ]` and `exec 3<` are both shell builtins, so no deterministic test can swap between them. The JS type check behind it still refuses. ## Not in this PR - **Images as MCP `image` content blocks.** These need a second, much smaller cap. - **Artifact feedback through MCP.** This belongs with #158. - **Write-side containment.** `writeFile`, `mkdir`, `rename` and `deletePath` still check only the path text. They serve the operator's cookie-authenticated file explorer, not MCP. - **Route-level tests for the three operator artifact routes.** Their shared mapping is pinned in `read-failure.test.ts`.
lz added this to the MCP support (#140) milestone 2026-09-23 16:29:45 +02:00
lz added 11 commits 2026-09-23 16:29:45 +02:00
perf(artifacts): count every listed artifact's comments in one query
Some checks failed
ci / nexus (pull_request) Successful in 12m59s
ci / images (pull_request) Has been cancelled
61ee2f9005
lz added 4 commits 2026-09-23 17:08:03 +02:00
lz added 3 commits 2026-09-23 17:31:15 +02:00
readFile checked the path text and refused a symlink only as the final
component, so a symlinked directory in the middle (docs -> /workspace/.nexus)
was followed inside the container. With #175 that read reaches nexus:read
MCP clients as well as the web UI and the raw endpoint.

readFile now resolves the base and the target with one `realpath -e` and
refuses with BAD_PATH unless the target is the base or lies under it. A
missing path is still NOT_FOUND; the stat and read still act on the
original path, so a final-component symlink inside the base is still
refused as SYMLINK.

Known remaining gap: writeFile, mkdir, rename and deletePath still check
only the path text and would follow a mid-path symlink.
registerToolsFor logged every tool throw at error with a stack, including
the ordinary refusals written for the model (an unknown id, a refused
artifact, a stopped workspace), so the log read like a fault each time.

ToolRefusal marks those throws. The registry logs one at info with its
reason and no stack; any other throw is still a fault logged at error.
Both are rethrown, so the client still gets isError content. The five
intentional refusals in tools/ now throw ToolRefusal; defineTool's
output-schema mismatch stays a plain Error, because that one is a fault.
refactor(artifacts): classify a failed artifact read once
Some checks failed
ci / nexus (pull_request) Failing after 10m17s
ci / images (pull_request) Has been skipped
184a05b060
The artifact detail endpoint, the raw endpoint, the pop-out page and the
MCP read each mapped a failed read to an outcome on their own, and had
drifted: the routes duck-typed `'status' in err` while the MCP read used
isHttpError.

classifyReadFailure now owns the VolumeFsError-code and HttpError 404/503
mapping, including the container state named in a 503. Every caller
switches on its closed result exhaustively. Each keeps exactly the
behaviour it had: two kinds exist for that alone. fs_other is a
VolumeFsError code no read produces, which the operator views still show
as not_found; status_other is any other object carrying a `status`, which
the routes still treat as a worker that is down and the MCP read still
does not recognise.
lz added 3 commits 2026-09-23 17:51:40 +02:00
- realpath -z, split on NUL, so a newline in a file name cannot shift the
  resolved base and target apart.
- A symlink loop is a SYMLINK refusal (400), not a plain Error (500).
- The resolved base must equal the requested one: a symlinked base would
  move containment to wherever it points.
- A target resolving to the base itself is refused as BAD_PATH; it is a
  directory and was never readable.
- New ReadFileOptions.excludeNexusDir refuses a target in /workspace/.nexus
  unless the base is a session worktree. The workspace shell's base is
  /workspace, which otherwise admits .nexus/secrets.env directly or via a
  symlink.
- stat's mtime format is %.6Y; %Y.%6N printed the quoted file name after
  the dot, so every mtime was NaN.
The workspace shell's base is /workspace, so an artifact registered there
could name .nexus/secrets.env, directly or through a symlink, and
nexus_get_artifact would hand it to any nexus:read client. Every artifact
read now passes excludeNexusDir: MCP, agent registration (refused with the
route's existing 400 invalid path), and the operator GET, raw and pop-out
views, so a .nexus artifact is neither registered nor served.

artifact-read no longer logs a refusal it recognises: the registry logs
every ToolRefusal at info with its reason. Unrecognised failures still log
at error.
docs: correct the read-failure comment and record the containment rules
Some checks failed
ci / nexus (pull_request) Successful in 15m14s
ci / images (pull_request) Has been cancelled
b5caa04ca2
lz added 2 commits 2026-09-23 18:17:34 +02:00
readFile ran realpath, stat and head as three separate execs, so a middle
directory swapped for a symlink between them moved the read to a file that
had never been checked. One script now opens the target once on fd 3 and
decides containment, the Nexus-dir exclusion and the file type from
/proc/self/fd/3 before head reads that same descriptor, so bytes from
outside the base never leave the container. The JS side re-checks the same
rules on the script's output.

timeout bounds the residual FIFO race; the -f test before the open keeps a
FIFO from blocking it. `command exec` is required: a plain exec redirection
failure exits dash with status 2 before `||` runs.
docs: describe the artifact read as one opened file
Some checks failed
ci / nexus (pull_request) Failing after 7m1s
ci / images (pull_request) Has been skipped
6f7c30d8b9
lz added 3 commits 2026-09-23 18:39:07 +02:00
PATH shims for readlink, realpath and stat swap a directory once between
the open and the containment check, in both directions: a file opened
inside must be read though its directory now points outside, and one
opened outside must be refused though its directory now points inside.
Also pins the sibling-prefix refusal in the script itself.
A non-truncating read of a file larger than maxBytes transferred
maxBytes+1 bytes, base64-encoded, before readFile threw TOO_LARGE: at
the 100 MiB media cap that is ~140 MB over the exec stream per request.
The script now takes the truncate flag and, when not truncating, stops
after the header if the fstat size already exceeds the cap, so readFile
refuses from the size alone. The post-read length check stays for a
file that grows after the fstat.
docs(worker-fs): say what containment does and does not stop
Some checks failed
ci / nexus (pull_request) Failing after 7m32s
ci / images (pull_request) Has been skipped
pr-image-cleanup / delete-pr-images (pull_request) Successful in 14s
1bbe31737c
Containment holds the kernel's name for the opened file inside the base
at check time. That stops Nexus following a confused or symlinked path
out of the base; it does not stop an agent, root on the same volume,
copying or hardlinking a file into its worktree and registering it. The
final-symlink refusal is best-effort, with containment behind it.
lz changed target branch from feat/mcp-status to main 2026-09-23 18:45:16 +02:00
lz merged commit fa6eacbdbb into main 2026-09-23 18:46:27 +02:00
lz deleted branch feat/mcp-artifacts 2026-09-23 18:46:28 +02:00
Sign in to join this conversation.
No reviewers
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
lz/agent-nexus!200
No description provided.