nexus_list_artifacts and nexus_get_artifact: read what an agent wants (#175) #200
No reviewers
Labels
No labels
bug
duplicate
enhancement
help wanted
invalid
question
wontfix
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
lz/agent-nexus!200
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/mcp-artifacts"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Closes #175. Plan:
docs/superpowers/plans/2026-09-23-mcp-artifact-reads.md.Stacked on #199 (
feat/mcp-status). Both PRs touch the sameToolDeps, fixtures, registry and tool-name arrays, and this PR's list description points models at #199'sidfilter onnexus_list_sessions. Retarget tomainonce #199 merges.This covers the second step of the phone loop, "what does it want?". It sits between
nexus_get_status(#155) andsend_message(#158).The tools
nexus_list_artifacts(session?, limit, offset)sessionis omitted.nexus_list_sessions. A real session with no artifacts gets an empty page.nexus_get_artifact(artifact)MCP_TEXT_MAX, not the 256 KiB editor limit.truncated: trueis set andsizeis the whole file's size.nexus:readand read-only.pathis described as relative to the session's worktree.Failures are sentences, and refusals are not faults
resolveWorkerFsthrows SvelteKit'sHttpError, which is not anError. Without handling, the model would receive{"message":"worker container not found"}. Instead, every failure to find or read the file becomes a sentence:Refusals written for the model, from every tool, are thrown as
ToolRefusal. The registry logs each once atinfo, with no stack. Anything unrecognised is logged aterrorwith 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:.nexusexclusion 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) returnedTOPSECRET. 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
cpor hardlink a file into its worktree and register it. The comments and AGENTS.md say so.Other
readFilefixes:head … | base64exits withbase64's status, so a failedheadcame back as empty content. Measured on the worker image.mtimewas alwaysNaN(also predates the PR). On GNU coreutils 9.1 the old stat format%Y.%6Nprints the quoted file name after the dot. It is now%.6Y.docker execinstead of three.Other supporting changes
listArtifacts:if. A conditional.wherewould bind an undefined parameter, which matches nothing in SQLite.classifyReadFailure(artifacts/read-failure.ts) is now the single mapping ofVolumeFsError/HttpErrorfor 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.schema.ts.⚠️ Existing grants gain artifact reading on deploy
Scopes are coarse. Every already-issued
nexus:readtoken, 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
node build/server.jswith real containers, on both MCP protocol legs:€;readFiledirectly against a container for every case × base × flag.[ -f ]andexec 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
imagecontent blocks. These need a second, much smaller cap.writeFile,mkdir,renameanddeletePathstill check only the path text. They serve the operator's cookie-authenticated file explorer, not MCP.read-failure.test.ts.