Workspace tools: stop_workspace, delete_workspace #157

Open
opened 2026-09-15 18:25:13 +02:00 by lz · 2 comments
Owner

The two workspace-lifecycle operations that need no vault key — verified: stopWorker and removeWorker take no masterKey, while spawnWorker and startWorker do (those are slice 2, #159).

Depends on #154. Scope: nexus:write.

stop_workspace

Wraps stopWorker.

Note the asymmetry it creates and reflect it in the tool's output: stopWorker writes workers.status and never touches a session row, so every session of a stopped workspace still reads status: 'running' while its probe reports the container down. That is exactly the trap #155's roll-up has to handle — do not let this tool report those sessions as healthy.

Once stopped, the workspace cannot be restarted through MCP until slice 2, because startWorker needs the vault key. Say so in the tool description rather than letting Claude discover it by failing.

delete_workspace

Wraps removeWorker, and removal is asynchronous (AGENTS.md fact #27). DELETE /api/workers/:id calls beginRemoval (row → removing), returns 202, and reaps in the background; the row hard-deletes itself at the end, so removing is the one phase that ends with the row disappearing.

The tool reports accepted, never gone. Measured: docker volume rm runs at ~4s per 50k files, so a clone with node_modules per worktree is tens of seconds. A tool that claims completion on return is lying for most of that window, and the natural follow-up — Claude immediately listing workspaces and still seeing it — reads as a bug.

isRunning is false while removing, so a listing during teardown should show it as going away rather than as a running workspace with a failing health entry.

A failed teardown parks in remove-error, a phase distinct from error. Don't collapse them: error is what retryWorker accepts, and offering to re-provision a workspace whose removal failed means an empty re-clone against a half-reaped volume.

Watch for

Both tools are destructive and reachable from a phone. The consent screen already lists "Stop and delete workspaces" as a granted capability, but consider whether delete_workspace should require confirmation in its description so the model treats it as weightier than stop_workspace.

Done when

Claude can stop and delete a workspace; the delete returns promptly with an accepted-not-done result; and a listing during teardown reports the workspace as being removed rather than as running-and-unhealthy.

The two workspace-lifecycle operations that need no vault key — verified: `stopWorker` and `removeWorker` take no `masterKey`, while `spawnWorker` and `startWorker` do (those are slice 2, #159). Depends on #154. Scope: `nexus:write`. ## `stop_workspace` Wraps `stopWorker`. Note the asymmetry it creates and reflect it in the tool's output: `stopWorker` writes `workers.status` and **never touches a session row**, so every session of a stopped workspace still reads `status: 'running'` while its probe reports the container down. That is exactly the trap #155's roll-up has to handle — do not let this tool report those sessions as healthy. Once stopped, the workspace cannot be restarted through MCP until slice 2, because `startWorker` needs the vault key. Say so in the tool description rather than letting Claude discover it by failing. ## `delete_workspace` Wraps `removeWorker`, and **removal is asynchronous** (AGENTS.md fact #27). `DELETE /api/workers/:id` calls `beginRemoval` (row → `removing`), returns 202, and reaps in the background; the row hard-deletes itself at the end, so `removing` is the one phase that ends with the row **disappearing**. **The tool reports *accepted*, never *gone*.** Measured: `docker volume rm` runs at ~4s per 50k files, so a clone with `node_modules` per worktree is tens of seconds. A tool that claims completion on return is lying for most of that window, and the natural follow-up — Claude immediately listing workspaces and still seeing it — reads as a bug. `isRunning` is false while `removing`, so a listing during teardown should show it as going away rather than as a running workspace with a failing health entry. A failed teardown parks in `remove-error`, a phase distinct from `error`. Don't collapse them: `error` is what `retryWorker` accepts, and offering to re-provision a workspace whose *removal* failed means an empty re-clone against a half-reaped volume. ## Watch for Both tools are destructive and reachable from a phone. The consent screen already lists "Stop and delete workspaces" as a granted capability, but consider whether `delete_workspace` should require confirmation in its description so the model treats it as weightier than `stop_workspace`. ## Done when Claude can stop and delete a workspace; the delete returns promptly with an accepted-not-done result; and a listing during teardown reports the workspace as being removed rather than as running-and-unhealthy.
lz added this to the MCP support (#140) milestone 2026-09-15 18:25:13 +02:00
Author
Owner

#174 put the tool surface on a contract. These become nexus_stop_workspace and nexus_delete_workspace — the prefix is in the type, so an unprefixed name is a compile error. See AGENTS.md fact #40; worked example mcp/tools/workspaces.ts.

The annotations are the part that matters most here, and #174 made them required for exactly this pair. The SDK's own ToolAnnotations has every field optional and destructiveHint defaults to true — so shipping {} would have made nexus_stop_workspace, which is reversible, read to a client as exactly as dangerous as a delete. State all four:

  • nexus_stop_workspace: readOnly: false, destructive: false, idempotent: true, openWorld: false
  • nexus_delete_workspace: readOnly: false, destructive: true, idempotent: true, openWorld: false

They are hints, never the enforcement; the scope filter in registry.ts is.

Half of the "listing during teardown" worry is already handled. mcpWorkspace recomputes running as status === 'running' && provision_phase !== 'removing', because workers.status reads running for the whole of an asynchronous removal. Verified live against the built server: a workspace at provision_phase: 'removing' reports status: "running", running: false. So a listing during teardown already shows it as going away. What is still yours is the delete tool returning accepted, never gone, and saying so in its description.

Also required now: outputSchema is mandatory and validated against structuredContent on every call, with a mismatch arriving as isError content on a 200 rather than as a JSON-RPC error — assert isError explicitly in tests. And the tool file may not import registry.ts (import cycle, invisible in one of the two bundles).

#174 put the tool surface on a contract. These become **`nexus_stop_workspace`** and **`nexus_delete_workspace`** — the prefix is in the type, so an unprefixed name is a compile error. See AGENTS.md fact #40; worked example `mcp/tools/workspaces.ts`. **The annotations are the part that matters most here, and #174 made them required for exactly this pair.** The SDK's own `ToolAnnotations` has every field optional and `destructiveHint` defaults to **true** — so shipping `{}` would have made `nexus_stop_workspace`, which is reversible, read to a client as exactly as dangerous as a delete. State all four: - `nexus_stop_workspace`: `readOnly: false, destructive: false, idempotent: true, openWorld: false` - `nexus_delete_workspace`: `readOnly: false, destructive: true, idempotent: true, openWorld: false` They are hints, never the enforcement; the scope filter in `registry.ts` is. **Half of the "listing during teardown" worry is already handled.** `mcpWorkspace` recomputes `running` as `status === 'running' && provision_phase !== 'removing'`, because `workers.status` reads `running` for the whole of an asynchronous removal. Verified live against the built server: a workspace at `provision_phase: 'removing'` reports `status: "running"`, `running: false`. So a listing during teardown already shows it as going away. What is still yours is the `delete` tool returning *accepted*, never *gone*, and saying so in its description. Also required now: `outputSchema` is mandatory and validated against `structuredContent` on every call, with a mismatch arriving as `isError` content on a 200 rather than as a JSON-RPC error — assert `isError` explicitly in tests. And the tool file may not import `registry.ts` (import cycle, invisible in one of the two bundles).
Author
Owner

Superseded in part by docs/superpowers/specs/2026-09-17-mcp-cold-start-design.md.

The "cannot be restarted through MCP until slice 2" caveat goes away. The operator's requirement is now that the whole flow works from an instance with no workspace at all, so the machine principal (#159) is in scope alongside this, and start_workspace ships with it rather than after it. Word the tool descriptions accordingly — there is no longer a stop-you-cannot-undo asymmetry to warn about.

nexus_start_workspace is specified as "ensure this workspace is up and usable" rather than "start it": idempotent, and it awaits readiness. That means calling it on an already-running workspace is also how a model waits out a boot, which subsumes a separate wait tool and keeps nexus_get_workspace honestly readOnlyHint: true.

A getter must not be written as a single-id twin of listWorkers. That function assembles from three sources — rows, listManagedContainers' live status, and countEnvVarsByRepo — so a getWorker is a drift hazard for live_status and env_var_count specifically. Either find-by-id over the existing listWorkspaces dep, or add an id? filter to the existing list tool (~6 lines against two new tool modules). The argument for a real getter is that it returns one object rather than a page envelope, so it is cheaper context and a model picks it more reliably — it is a judgement call, not settled.

The asynchronous-removal reasoning in the body above stands unchanged and is carried into the spec.

Blocked on #177.

Superseded in part by `docs/superpowers/specs/2026-09-17-mcp-cold-start-design.md`. **The "cannot be restarted through MCP until slice 2" caveat goes away.** The operator's requirement is now that the whole flow works from an instance with **no workspace at all**, so the machine principal (#159) is in scope alongside this, and `start_workspace` ships with it rather than after it. Word the tool descriptions accordingly — there is no longer a stop-you-cannot-undo asymmetry to warn about. `nexus_start_workspace` is specified as *"ensure this workspace is up and usable"* rather than *"start it"*: idempotent, and it awaits readiness. That means calling it on an already-running workspace is also how a model waits out a boot, which subsumes a separate wait tool and keeps `nexus_get_workspace` honestly `readOnlyHint: true`. **A getter must not be written as a single-id twin of `listWorkers`.** That function assembles from three sources — rows, `listManagedContainers`' live status, and `countEnvVarsByRepo` — so a `getWorker` is a drift hazard for `live_status` and `env_var_count` specifically. Either find-by-id over the existing `listWorkspaces` dep, or add an `id?` filter to the existing list tool (~6 lines against two new tool modules). The argument for a real getter is that it returns one object rather than a page envelope, so it is cheaper context and a model picks it more reliably — it is a judgement call, not settled. The asynchronous-removal reasoning in the body above stands unchanged and is carried into the spec. Blocked on #177.
Sign in to join this conversation.
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#157
No description provided.