Session tools: create_session, delete_session #156
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#156
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?
"Open a session on the auth bug" — the capability most of the value rides on. Depends on #154. Scope:
nexus:write.create_session(workspace, name, initial_message?)Wraps
createSession, which takes nomasterKey— verified — so no vault work.initial_messageis a launch argument, not a nudge.claudeaccepts the prompt as a positional argument, so it appends inbuildLaunchCommandand becomes the session's first turn. Notmux send-keys, no window resolution, no race against startup.Trap, hit during the original probe: several claude flags are variadic —
--channels <servers...>,--dangerously-load-development-channels <servers...>— and silently swallow a trailing positional prompt. The session died withInput must be provided either through stdin or as a prompt argument. Audit argument order incomposeLaunchand pin it with a test: the nexus plugin's--plugin-diris unconditional andextraClaudeArgsare appended after it, so the positional has to land after all of them.Second trap from the same probe: piping claude's stdout (e.g.
| tee) flips it into--printmode.Session names are validated against
git check-ref-format --branchvianexus/src/lib/git-ref.ts— reuse it rather than re-deriving. Slashes are allowed (feature/login).Serialize creates per workspace.
createSessionshells out togit -C /workspace worktree addwith no serialization, and concurrent adds contend onindex.lock. The retry-once path is scoped to each session's own name, so the failure mode is flakiness rather than data loss — but two simultaneous creates can both land in it, and a tool makes rapid succession easy in a way the UI did not.The optimistic
status: 'creating'row is inserted before the slow worktree and tmux work, so the tool returns promptly and the client polls rather than blocking.delete_sessionWraps
deleteSession, which hard-deletes so theUNIQUE(worker_id, name)slot frees for re-creation. NomasterKey.Watch for
createSessionrefuses aremovingrow — surface that as a clear tool error rather than a generic failure.Both tools must reject a
kind='workspace_shell'row, or offer it deliberately: the workspace shell is at most one per worker, reuses the entrypoint's boot tmux window, and has its ownPOST/DELETE /api/workers/:id/sessions/workspaceendpoints. Deleting it through the generic path is not the same operation.Done when
Claude can open a named session in a chosen workspace with a first instruction that actually runs as its opening turn, and close it again — plus a test that fails if a variadic flag is ever appended after the positional prompt.
#174 put the tool surface on a contract. These become
nexus_create_sessionandnexus_delete_session— thenexus_prefix is in the type (`nexus_${string}`), so an unprefixed name is a compile error. See AGENTS.md fact #40; worked examplemcp/tools/sessions.ts.Three more things it now requires:
mcp/tools/, which may not importregistry.ts(import cycle — invisible in one of the two bundles).annotationsrequires all four hints explicitly.nexus_create_sessionisreadOnly: false, destructive: false, idempotent: false, openWorld: false;nexus_delete_sessionisreadOnly: false, destructive: true, idempotent: true, openWorld: false. The SDK's ownToolAnnotationshas every field optional anddestructiveHintdefaults to true, which is exactly why they are required here.outputSchemais mandatory andrunreturns the payload typed against it. The SDK validatesstructuredContentagainst it on every call; a mismatch arrives asisError: truecontent on a 200, not as a JSON-RPC error.Refusals — the
workspace_shellrejection, andcreateSessionrefusing aremovingrow — should throw. The registry wrapper logs and rethrows, the SDK turns that intoisErrorcontent, and anisErrorresult skips output validation, so the refusal need not satisfy the schema. Make the message a sentence naming what to do about it.Superseded in part by
docs/superpowers/specs/2026-09-17-mcp-cold-start-design.md. Four corrections to this issue's body, all verified against the tree.The optimistic-return claim is wrong. This issue says "the optimistic
status: 'creating'row is inserted before the slow worktree and tmux work, so the tool returns promptly and the client polls rather than blocking." That describesspawnWorker, which backgroundsprovisionWorker.createSessioninserts the row and then awaits the worktree add,.worktreeinclude, the trust write andtmux new-windowbefore returning. Any design that assumed a fast return needs revisiting.The variadic-flag trap was probed and the positional survives. Measured against claude 2.1.274 on 2026-09-17: a trailing positional is not swallowed by
--plugin-dir <path>, and--is accepted as a separator. Both still get a test, sinceextraClaudeArgsgrows.What remains unverified is the combination this feature rests on — that
claude --remote-control "<label>" "<prompt>"submits the prompt as the opening turn. Probe it in a scratch workspace before writing code.The message is stored nowhere, deliberately. Passing it only to the launch builder is what makes it once-only for free:
convergeSessionsbuilds its own--resumelaunch and never sees it, so a restored session cannot replay the opening instruction.The mutex does not become a shared module.
convergingWorkersis the same shape and is already instantiated twice, one per bundle, and its collision is latent rather than live —src/server.tsawaitsrestoreSessionsOnBootbefore the listener opens, so no browser poll can overlap the boot pass. Two locks do not pay for a shared keyed-lock module; a third would.One trap for any tool added here:
tools-leak.test.tscallstool.inputSchema.parse({}), which throws for any tool with a required field. Add an argument fixture. Do not make the parse lenient to get past it — that silently drops the leak guard for every tool.Blocked on #177 (the fleet status layer):
createSessionagainst abootingworkspace fails attmux new-window, and nothing clearsbootingwithout a browser open.