Artifact read tools: nexus_list_artifacts and nexus_get_artifact #175
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#175
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
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?
The structural gap in this milestone. Depends on #174 (the tool contract). Scope:
nexus:read, both tools.Why this exists
The loop on a phone is:
We are building 1 and 3 and skipping 2, which is the step that makes the other two worth anything. As it stands the operator gets a notification and must open the web UI to act on it — precisely the thing the milestone exists to avoid.
ArtifactDTOalready exists ({ id, session_id, path, label, kind, source, created_at, updated_at, comment_counts }), agents already register plans, reports and screenshots throughnotify-artifact, and no tool exposes any of it.comment_countsalready distinguishes an artifact awaiting review from one already handled.Design record:
.agent/docs/mcp-tool-surface.mdfinding 5; plandocs/superpowers/plans/2026-09-17-mcp-tool-surface.md"PR B".The contract to build on
#174 shipped it, and AGENTS.md fact #40 states it. A new tool is a file under
nexus/src/lib/server/mcp/tools/, and:nameis typed`nexus_${string}`— the prefix is a compile error to omit.annotationsrequires all four hints explicitly (readOnlyHint,destructiveHint,idempotentHint,openWorldHint). Both tools here arereadOnly: true, destructive: false, idempotent: true, openWorld: false.outputSchemais mandatory, andrunreturns the payload typed against it.PAGE_INPUT/pageOutputFieldsfrompaging.ts.tools/may importregistry.ts— the cycle would be aReferenceErrorunder Rollup and silentlyundefinedunder esbuild (fact #31).Add
McpArtifactSchema/mcpArtifacttoprojection.tsbeside the other two.ArtifactDTOcarries nothing host-shaped so it is close to identity — keep the projection anyway, and use it to say on the wire thatpathis relative to the session's worktree, which reads as an absolute-ish path to a model otherwise.Task 1 —
nexus_list_artifacts(session?, limit, offset)Make
listArtifacts' session filter optional (nexus/src/lib/server/artifacts/service.ts:100), exactly as #174 did forlistSessions:The
ifhas to stay anif. Written as.where('session_id', '=', sessionId!)behind a conditional expression, an undefined bound parameter matches nothing in SQLite, so the fleet-wide listing comes back empty with no error and nothing logged. Seed two sessions with one artifact each and assert the fleet case is non-empty — with one session, "the fleet" and "this session" agree and a droppedwherepasses both.Add
listArtifacts: (session?: string) => Promise<unknown[]>toToolDeps, wire it indeps.ts, and extenddeps.test.ts's "binds each tool dependency to its service" with both the named and the omitted case — asserted on the ARGUMENT, sincelistArtifacts(deps, undefined)andlistArtifacts(deps, 'undefined')are indistinguishable from the result.Description should name what
comment_countsmeans:openis feedback the operator has written but not submitted,submittedhas been sent back to the agent.Task 2 —
nexus_get_artifact(artifact)The only tool in either PR that reads a file out of a worker container, so the only one with a real failure surface.
Keep SvelteKit's
error()inside the depresolveWorkerFsthrows anHttpError, which is not anError. Reaching the SDK'serror instanceof Error ? error.message : String(error)it surfaces as{"message":"worker container not found"}— a JSON blob where an actionable sentence belongs. Convert at the boundary:In
deps.ts, roughly:describeReadFailuremapsVolumeFsErrorcodes (NOT_FOUND→ "the file is no longer in the worktree",TOO_LARGE→ "too large to read through MCP") and anHttpError's status (404 → "the workspace container is gone", 503 → "the workspace is not running — start it first"), falling back to a generic sentence plus alogger.warncarrying the real error. Log it: without that the sentence is all anyone ever sees.MCP_TEXT_MAXis a module constant, notmax_file_bytesThe two exist for different consumers: 256 KiB is a sane editor limit and roughly 64k tokens of a model's context. Start at 64 KiB and say why in a comment. Report the full
sizealongsidetruncated: true, never the truncated length — a caller has to be able to tell how much it is missing.The tool
Throwing is correct, and worth knowing why: the registry's wrapper logs and rethrows, the SDK turns a rejecting executor into
isError: truecontent on a 200 — the right wire answer for "this call failed", distinct from a protocol error — and anisErrorresult skips output validation, so the refusal does not have to satisfy the schema.Tests, each proven able to fail
truncated: trueand reports the fullsize.HttpErrorfromresolveWorkerFsbecomes a sentence naming the workspace state, and the body never contains{"message".VolumeFsErrorNOT_FOUNDbecomes a sentence, and the underlying error reacheslogger.warn.if/wheretrap above).Add the new guards to the mutation gate. Watch specifically for one that cannot fail: the "refuses by kind" test passes trivially if the fs dep is a stub that returns something — assert the call count.
Consent copy, and a caveat that belongs in the PR body
nexus/src/lib/server/oauth/consent.ts:18reads "See workspaces, sessions, and what needs your attention". Artifact contents are agent output the operator has not seen described. Change to something like "See workspaces, sessions, what needs your attention, and what agents have written".State the caveat explicitly: scopes are coarse, so every already-issued
nexus:readtoken gains artifact reading the moment this deploys, including the one authorized on 2026-09-17. The copy fixes what the next operator sees, not what the current grant agreed to. The remedy — revoking a grant — is #171 §1 and does not exist yet.Live verification
Register an artifact in a real worker with
notify-artifact, then read it back through MCP end to end:nexus_list_artifactswith nosessionspans sessions.nexus_get_artifactreturns the bytes the file actually holds — diff againstcat, do not eyeball a prefix.Drive both protocol legs. A modern
tools/callneedsMcp-Nameas well asMcp-Method; a legacy POST needsAccept: application/json, text/event-streamand frames its success as SSE.Deliberately out of scope
imagecontent blocks. Genuinely useful — a screenshot is often exactly what "what does it want?" means — but the media cap is 10 MiB, whose base64 is ~13 MB of context. It needs a second, much smaller cap and a refusal path above it: a design decision, not a line of code. Text closes the loop for plans, reports and diffs today./api/config-explorer/*,/api/tokens,/api/connections,/api/settings/environment. A stolen MCP token must not become control-plane compromise;TOKEN_ROUTES' exclusions are the precedent.Done when
Claude can ask what needs attention, read the plan or report the agent produced, and do it from a phone — with a refusal for every failure mode that names the thing to do about it, and a mutation gate proving each new guard bites.