nexus_create_session and nexus_delete_session: open and close sessions from MCP (#156) #202
No reviewers
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!202
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/mcp-session-tools"
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?
Closes #156. Spec:
docs/superpowers/specs/2026-09-23-mcp-session-tools-design.md; plan:docs/superpowers/plans/2026-09-23-mcp-session-tools.md.What it adds
nexus_create_session(nexus:write) opens a session in a running workspace.initial_messagebecomes the agent's first turn.modelandeffortapply to that launch.agent_teamsdefaults to on, as in the UI.markasnexus_list_sessions, plusconfirmed: whether claude was seen starting.nexus_delete_session(nexus:write) deletes a session's worktree and branch.force: truediscards them and reports what went.A
nexus:write-only credential now reaches exactly these two tools.Shared with the UI, not MCP-only
The behaviour lives in
sessions/service.ts, so the UI routes run the same code.--model,--effortand then the first message, LAST and behind--. No flag can consume the message, and a leading-is not read as a flag. Nothing is stored, so a restore or restart never replays it.claude_alive. This is the same shape the agent restart already used, now one helper (observeClaude) for create, restart, stop and the workspace shell. A timeout recordsnull("not confirmed"), never absence. Waiters share one proc walk per container (claude-waiter.ts) instead of a poll per session, and each waiter's deadline runs on its own timer, so a hung exec cannot strand the rest.{ session, confirmed }. An unconfirmed start toasts as a warning, not a failure: the session exists, and a retry would hit "already exists".deleteSessiontakes a required{ force }. The unsaved-work check runs before any side effect. The UI route passesforce: true, because its confirm dialog is the consent.deleteSessionforce-deletes the branch, and it always did. Both now say so.Why model and effort are never stored
Measured on claude 2.1.280/281:
--resumerestores the conversation's latest model, including a/modelchange made inside the session. Re-passing--modelon a restart would override the operator's own choice.effortLevelon resume. So does an in-session/effort.The tool descriptions say both.
Concurrency, measured rather than assumed
git worktree adddoes not contend (60/60). The issue's premise that creates need serialising does not hold, and serialising would make a burst of twelve about five times slower.branch -Ddoes contend (could not lock config file .git/config). Everybranch -Dnow runs underflock /workspace/.nexus/git.lock.~/.claude.jsonlost trust entries: 7–10 of 12 survived. This is a pre-existing bug for UI creates and convergence restores too. The trust write now runs underflock. On current claude trust is also inherited from/workspace, which covers a per-session entry that claude's own startup rewrite drops. AGENTS.md fact #4 said trust keys were exact paths only; that is corrected.errored, so it never holds the name.Two bugs the live run found that the suite could not
deleteSessionnow deletes the row before killing the window, and a test pins that order.Also fixed on the way
docs,nexus,workerhere) hit git's "ambiguous argument", and every delete of it refused. It now usesrefs/heads/<name> … --.deleteSessionthat exit non-zero are logged instead of vanishing.git,jqandflock, so the real-shell tests for the unsaved-work check and the trust lock run there instead of skipping.Verified live
Verified against the built server in Docker-in-Docker, with a real worker image, a real clone and MCP calls over HTTP:
forceand reported.Not in this PR
model/effortin the UI create form.send_message(#158).