Workspace tools: stop_workspace, delete_workspace #157
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#157
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 two workspace-lifecycle operations that need no vault key — verified:
stopWorkerandremoveWorkertake nomasterKey, whilespawnWorkerandstartWorkerdo (those are slice 2, #159).Depends on #154. Scope:
nexus:write.stop_workspaceWraps
stopWorker.Note the asymmetry it creates and reflect it in the tool's output:
stopWorkerwritesworkers.statusand never touches a session row, so every session of a stopped workspace still readsstatus: '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
startWorkerneeds the vault key. Say so in the tool description rather than letting Claude discover it by failing.delete_workspaceWraps
removeWorker, and removal is asynchronous (AGENTS.md fact #27).DELETE /api/workers/:idcallsbeginRemoval(row →removing), returns 202, and reaps in the background; the row hard-deletes itself at the end, soremovingis the one phase that ends with the row disappearing.The tool reports accepted, never gone. Measured:
docker volume rmruns at ~4s per 50k files, so a clone withnode_modulesper 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.isRunningis false whileremoving, 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 fromerror. Don't collapse them:erroris whatretryWorkeraccepts, 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_workspaceshould require confirmation in its description so the model treats it as weightier thanstop_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.
#174 put the tool surface on a contract. These become
nexus_stop_workspaceandnexus_delete_workspace— the prefix is in the type, so an unprefixed name is a compile error. See AGENTS.md fact #40; worked examplemcp/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
ToolAnnotationshas every field optional anddestructiveHintdefaults to true — so shipping{}would have madenexus_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: falsenexus_delete_workspace:readOnly: false, destructive: true, idempotent: true, openWorld: falseThey are hints, never the enforcement; the scope filter in
registry.tsis.Half of the "listing during teardown" worry is already handled.
mcpWorkspacerecomputesrunningasstatus === 'running' && provision_phase !== 'removing', becauseworkers.statusreadsrunningfor the whole of an asynchronous removal. Verified live against the built server: a workspace atprovision_phase: 'removing'reportsstatus: "running",running: false. So a listing during teardown already shows it as going away. What is still yours is thedeletetool returning accepted, never gone, and saying so in its description.Also required now:
outputSchemais mandatory and validated againststructuredContenton every call, with a mismatch arriving asisErrorcontent on a 200 rather than as a JSON-RPC error — assertisErrorexplicitly in tests. And the tool file may not importregistry.ts(import cycle, invisible in one of the two bundles).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_workspaceships 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_workspaceis 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 keepsnexus_get_workspacehonestlyreadOnlyHint: true.A getter must not be written as a single-id twin of
listWorkers. That function assembles from three sources — rows,listManagedContainers' live status, andcountEnvVarsByRepo— so agetWorkeris a drift hazard forlive_statusandenv_var_countspecifically. Either find-by-id over the existinglistWorkspacesdep, or add anid?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.