MCP tool surface: nexus_* names, annotations, outputSchema, paging #174

Merged
lz merged 11 commits from feat/mcp-tool-contract into main 2026-09-18 09:30:16 +02:00
Owner

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-reads tools/list on 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 bare list_sessions is a name several services would claim, and a collision doesn't error — it leaves the model choosing between indistinguishable names.
  • A NexusToolAnnotations whose four hints are all required. The SDK's own ToolAnnotations has every field optional, so typing against it lets a tool ship {} and inherit the spec defaults — where destructiveHint is true. A reversible nexus_stop_workspace (#157) would have read as exactly as dangerous as a delete.
  • A mandatory outputSchema, with run returning the payload typed against it.
  • A non-exported unique symbol brand, so defineTool is the only way to mint a tool at all.

Plus limit/offset with total_count / has_more / next_offset, and workspace now optional on nexus_list_sessions — which kills the 1+N that asking "what is waiting on me?" used to cost.

registry.ts splits into tool.ts / paging.ts / projection.ts / tools/* as a strict DAG. No tool module under tools/ may import registry.ts: a cycle there is a ReferenceError under Rollup and silently undefined under 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.

running reported a crashed container as up. It reimplemented isRunning without its live_status term. The amplifier: nothing on the server reconciles workers.status against Docker — checkWorkerHealth is reached only from GET /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 read running forever, and the projection had dropped live_status, so a client couldn't detect it. isRunning/isReady now live in $lib/workspace-state (out of the runes store, which server code can't import) and both sides call one implementation; live_status is on the wire.

provision_error leaked host topology. It stores the daemon's err.message verbatim, and a refused mount fails at container.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_phase already separates error from remove-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. validateToolInput returns parseResult.data; validateToolOutput discards it, and z.object is non-strict — so an undeclared field passed validation and shipped. defineTool now parses, which strips undeclared keys and moves the failure inside registerToolsFor'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: "outputSchema is 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 status is intent rather than liveness and now says so on the wire (stopWorker never touches a session row, so every session of a stopped workspace reads running); an unknown workspace id is refused instead of reported as total_count: 0; the status vocabulary is derived from one const rather than hand-written a fourth time (workers.status has no CHECK constraint, so widening it is a pure TS edit, and one unknown row failed the whole page); id breaks 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 build 0 after rm -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_status term, the inline running, provision_error put back on the wire, the output parse removed, the session describe, 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 mcpWorkspace directly — 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.ts now drives every tool through its own inputSchema and checks both result arms, with a positive control on the fixture. It also found listSessions' ordering unpinned just as paging made it load-bearing, and three assertions that could not fail (including one of mine asserting listSessions(db) and listSessions(db, undefined) both return 2 — the same call twice). All fixed or removed.

Live, against node build/server.js on an isolated DATA_DIR seeded with three workspaces, three sessions, and a workspace whose provision_error really contains 10.0.0.3 and /volume1/music: 21/21 legacy-leg checks and 7/7 modern-leg checks. tools/list advertises only nexus_* names with annotations and schemas; paging pages and terminates; the fleet form spans workspaces; limit: 0 refuses as isError content; 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, and hostHeaderValidationResponse reads whatever proxy_set_header Host gave it. The Host allowlist stays unverified against the deployment until one request goes through the real ingress.

Follow-up

#175 — nexus_list_artifacts and nexus_get_artifact, the structural gap where nothing can read what an agent produced.

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-reads `tools/list` on 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 bare `list_sessions` is a name several services would claim, and a collision doesn't error — it leaves the model choosing between indistinguishable names. - A `NexusToolAnnotations` whose four hints are all **required**. The SDK's own `ToolAnnotations` has every field optional, so typing against it lets a tool ship `{}` and inherit the spec defaults — where `destructiveHint` is **true**. A reversible `nexus_stop_workspace` (#157) would have read as exactly as dangerous as a delete. - A mandatory `outputSchema`, with `run` returning the payload typed against it. - A non-exported `unique symbol` brand, so `defineTool` is the only way to mint a tool at all. Plus `limit`/`offset` with `total_count` / `has_more` / `next_offset`, and `workspace` now **optional** on `nexus_list_sessions` — which kills the 1+N that asking "what is waiting on me?" used to cost. `registry.ts` splits into `tool.ts` / `paging.ts` / `projection.ts` / `tools/*` as a strict DAG. No tool *module* under `tools/` may import `registry.ts`: a cycle there is a `ReferenceError` under Rollup and silently `undefined` under 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. **`running` reported a crashed container as up.** It reimplemented `isRunning` without its `live_status` term. The amplifier: **nothing on the server reconciles `workers.status` against Docker** — `checkWorkerHealth` is reached only from `GET /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 read `running` forever, and the projection had dropped `live_status`, so a client couldn't detect it. `isRunning`/`isReady` now live in `$lib/workspace-state` (out of the runes store, which server code can't import) and both sides call one implementation; `live_status` is on the wire. **`provision_error` leaked host topology.** It stores the daemon's `err.message` verbatim, and a refused mount fails at `container.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_phase` already separates `error` from `remove-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.** `validateToolInput` returns `parseResult.data`; `validateToolOutput` **discards** it, and `z.object` is non-strict — so an undeclared field passed validation and shipped. `defineTool` now parses, which strips undeclared keys *and* moves the failure inside `registerToolsFor`'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:** "`outputSchema` is 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 `status` is intent rather than liveness and now says so on the wire (`stopWorker` never touches a session row, so every session of a stopped workspace reads `running`); an unknown workspace id is refused instead of reported as `total_count: 0`; the status vocabulary is derived from one const rather than hand-written a fourth time (`workers.status` has **no CHECK constraint**, so widening it is a pure TS edit, and one unknown row failed the *whole page*); `id` breaks 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 build` 0 after `rm -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_status` term, the inline `running`, `provision_error` put back on the wire, the output parse removed, the session `describe`, 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 `mcpWorkspace` directly — 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.ts` now drives every tool through its own `inputSchema` and checks **both** result arms, with a positive control on the fixture. It also found `listSessions`' ordering unpinned just as paging made it load-bearing, and three assertions that could not fail (including one of mine asserting `listSessions(db)` and `listSessions(db, undefined)` both return 2 — the same call twice). All fixed or removed. **Live, against `node build/server.js`** on an isolated `DATA_DIR` seeded with three workspaces, three sessions, and a workspace whose `provision_error` really contains `10.0.0.3` and `/volume1/music`: 21/21 legacy-leg checks and 7/7 modern-leg checks. `tools/list` advertises only `nexus_*` names with annotations and schemas; paging pages and terminates; the fleet form spans workspaces; `limit: 0` refuses as `isError` content; 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, and `hostHeaderValidationResponse` reads whatever `proxy_set_header Host` gave it. The Host allowlist stays unverified against the deployment until one request goes through the real ingress. ## Follow-up #175 — `nexus_list_artifacts` and `nexus_get_artifact`, the structural gap where nothing can read what an agent produced.
lz added 7 commits 2026-09-17 17:32:40 +02:00
docs: correct what unparsed paging arguments actually compute
All checks were successful
ci / nexus (pull_request) Successful in 9m23s
ci / images (pull_request) Successful in 14m32s
b032cd6370
lz added 2 commits 2026-09-17 18:38:03 +02:00
Review findings on the tool surface. The load-bearing ones:

- `running` reimplemented `isRunning` without its `live_status` term, so a
  container that exited on its own reported as up. Nothing on the server
  reconciles `workers.status` against Docker — checkWorkerHealth is reached
  only from the browser's poll — so the column is most stale exactly when MCP
  is the only caller. isRunning moves to a client-safe module so both sides
  call one implementation, and live_status goes on the wire.
- `provision_error` shipped the daemon's message verbatim, which carries the
  NFS server address and export path for a refused mount. Withheld;
  provision_phase already separates error from remove-error. The leak fixture
  now contains real host values, so that guard stops being decorative.
- The SDK validates output but ships the unparsed object, so defineTool parses
  it: the schema gates what leaves, and a mismatch is finally logged.
- A hand-written McpToolDef literal bypassed defineTool and compiled. Branded.
- Session `status` is intent, not liveness, and now says so on the wire.
- An unknown workspace id refused instead of reported as empty.
- Status vocabulary derived from one const; id breaks sort ties.
docs(mcp): say which workspace field is an observation and which is intent
All checks were successful
ci / nexus (pull_request) Successful in 12m8s
ci / images (pull_request) Successful in 15m51s
2e17eb27a9
test(mcp): assert the privacy property where it is delivered, and drop what cannot fail
All checks were successful
ci / nexus (pull_request) Successful in 9m15s
ci / images (pull_request) Successful in 10m31s
pr-image-cleanup / delete-pr-images (pull_request) Successful in 12s
6a275bf291
From the test-coverage review. The first item is the one that mattered:

- The no-leak assertion tested mcpWorkspace directly, one function away from
  the path a client takes. Measured: making a tool spread the row into its
  result left the whole suite green. defineTool's parse already strips that,
  so it no longer leaks — but nothing asserted it, so removing the parse would
  have reopened the hole silently. tools-leak.test.ts drives every tool
  through its own inputSchema and checks BOTH result arms, with a positive
  control on the fixture.
- listSessions' ordering was unpinned just as paging made it load-bearing;
  deleting the orderBy passed. Now asserted with a deliberate created_at tie.
- Dropped three assertions that could not fail: outputSchema toBeDefined on a
  required field, and two schema round-trips tsc already enforces. Replaced a
  case asserting listSessions(db) and listSessions(db, undefined) both return
  2 — the same call twice.
- A 'continue' made the paging assertion a silent no-op if the page shape were
  renamed; limit: expect.any(Number) passed for NaN, which is what an
  unapplied default produces.

Comments that named the SDK as the output validator now describe defineTool's
parse, which runs first. The tools/ import rule was already false on disk —
the test file beside them imports registry, which is fine and now said.
lz merged commit 49bb6fb889 into main 2026-09-18 09:30:16 +02:00
lz deleted branch feat/mcp-tool-contract 2026-09-18 09:30:17 +02:00
Sign in to join this conversation.
No reviewers
No milestone
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!174
No description provided.