MCP tool surface: nexus_* names, annotations, outputSchema, paging #174
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/mcp-tool-contract"
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?
Puts the MCP tool surface on a contract before #155–#158 ship on it. Plan:
docs/superpowers/plans/2026-09-17-mcp-tool-surface.md.This is a breaking rename of a live surface, and its whole justification is timing. The connector authorized on 2026-09-17 with one consumer and two tools. Once #155–#158 land on the old convention this stops being a rename and becomes a migration.
What changes
list_workspaces→nexus_list_workspaces,list_sessions→nexus_list_sessions. A connected client re-readstools/liston reconnect, so the only cost is the model no longer knowing the old names — verified live: the pre-rename name answers-32602 Tool list_workspaces not found.Four rules are enforced by the type, so a new tool cannot forget them:
name: `nexus_${string}`. Claude connects many servers at once; a barelist_sessionsis a name several services would claim, and a collision doesn't error — it leaves the model choosing between indistinguishable names.NexusToolAnnotationswhose four hints are all required. The SDK's ownToolAnnotationshas every field optional, so typing against it lets a tool ship{}and inherit the spec defaults — wheredestructiveHintis true. A reversiblenexus_stop_workspace(#157) would have read as exactly as dangerous as a delete.outputSchema, withrunreturning the payload typed against it.unique symbolbrand, sodefineToolis the only way to mint a tool at all.Plus
limit/offsetwithtotal_count/has_more/next_offset, andworkspacenow optional onnexus_list_sessions— which kills the 1+N that asking "what is waiting on me?" used to cost.registry.tssplits intotool.ts/paging.ts/projection.ts/tools/*as a strict DAG. No tool module undertools/may importregistry.ts: a cycle there is aReferenceErrorunder Rollup and silentlyundefinedunder esbuild (fact #31), and neither build warns.What a review found, and what it changed
The first revision of this branch shipped with real defects. They're fixed here; recording them because several are the kind that pass every gate.
runningreported a crashed container as up. It reimplementedisRunningwithout itslive_statusterm. The amplifier: nothing on the server reconcilesworkers.statusagainst Docker —checkWorkerHealthis reached only fromGET /api/workers/:id/health, i.e. the browser's poll — so the column is most stale exactly when MCP is the only caller, which is the case this milestone exists for. A container that exited on its own readrunningforever, and the projection had droppedlive_status, so a client couldn't detect it.isRunning/isReadynow live in$lib/workspace-state(out of the runes store, which server code can't import) and both sides call one implementation;live_statusis on the wire.provision_errorleaked host topology. It stores the daemon'serr.messageverbatim, and a refused mount fails atcontainer.start()and lands there — so it routinely carries the NFS server address and export path, the exact values the projection exists to withhold. Withheld now;provision_phasealready separateserrorfromremove-error, which is what a caller needs. The leak fixture nulled that field, so the guard was decorative for a whole revision; it now contains a real daemon message.The output schema described the payload without gating it.
validateToolInputreturnsparseResult.data;validateToolOutputdiscards it, andz.objectis non-strict — so an undeclared field passed validation and shipped.defineToolnow parses, which strips undeclared keys and moves the failure insideregisterToolsFor's wrapper, where it is finally logged. The SDK's own check runs after the executor returns, so a mismatch previously reached the client with the Nexus log silent — the exact silence that wrapper was written to prevent.Correcting this PR's own earlier claim: "
outputSchemais load-bearing at compile time" was true of the input and false of the output. It is now true of both, and the guarantee is conditional on the schema generics being inferred — annotate either with the generic's own constraint and inference collapses, accepting any payload with nothing to see.Also: session
statusis intent rather than liveness and now says so on the wire (stopWorkernever touches a session row, so every session of a stopped workspace readsrunning); an unknown workspace id is refused instead of reported astotal_count: 0; the status vocabulary is derived from one const rather than hand-written a fourth time (workers.statushas no CHECK constraint, so widening it is a pure TS edit, and one unknown row failed the whole page);idbreaks sort ties now that paging slices a live list.Verification
Gates, each its own invocation with the exit status read directly: typecheck 5177 files / 0 errors, vitest 200 files / 2235 tests / exit 0, lint 0,
pnpm build0 afterrm -rf .svelte-kit build.Mutation gate: 25/25 KILLED, clean baseline. The twelve #154 guards plus thirteen new ones, including one per review finding — the
live_statusterm, the inlinerunning,provision_errorput back on the wire, the output parse removed, the sessiondescribe, the unknown-workspace check, the sort tie-break.Two guards were proven by hand because the harness only applies single-file mutations: the privacy property needs a compound mutation (a tool spreading the row plus removing the parse) to fail — verified both ways, the spread alone passes because the parse strips it, and the pair fails naming
10.0.0.3.Test quality. A coverage review found the no-leak assertion was testing
mcpWorkspacedirectly — one function away from the path a client takes — so making a tool spread the row left the whole suite green.tools/tools-leak.test.tsnow drives every tool through its owninputSchemaand checks both result arms, with a positive control on the fixture. It also foundlistSessions' ordering unpinned just as paging made it load-bearing, and three assertions that could not fail (including one of mine assertinglistSessions(db)andlistSessions(db, undefined)both return 2 — the same call twice). All fixed or removed.Live, against
node build/server.json an isolatedDATA_DIRseeded with three workspaces, three sessions, and a workspace whoseprovision_errorreally contains10.0.0.3and/volume1/music: 21/21 legacy-leg checks and 7/7 modern-leg checks.tools/listadvertises onlynexus_*names with annotations and schemas; paging pages and terminates; the fleet form spans workspaces;limit: 0refuses asisErrorcontent; none of six host-shaped needles appears in any response body.What this does not prove: the live run drives the built server directly with
Host: nexus.test. Production has nginx in front, andhostHeaderValidationResponsereads whateverproxy_set_header Hostgave it. The Host allowlist stays unverified against the deployment until one request goes through the real ingress.Follow-up
#175 —
nexus_list_artifactsandnexus_get_artifact, the structural gap where nothing can read what an agent produced.