Session tools: create_session, delete_session #156

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

"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 no masterKey — verified — so no vault work.

initial_message is a launch argument, not a nudge. claude accepts the prompt as a positional argument, so it appends in buildLaunchCommand and becomes the session's first turn. No tmux 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 with Input must be provided either through stdin or as a prompt argument. Audit argument order in composeLaunch and pin it with a test: the nexus plugin's --plugin-dir is unconditional and extraClaudeArgs are 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 --print mode.

Session names are validated against git check-ref-format --branch via nexus/src/lib/git-ref.ts — reuse it rather than re-deriving. Slashes are allowed (feature/login).

Serialize creates per workspace. createSession shells out to git -C /workspace worktree add with no serialization, and concurrent adds contend on index.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_session

Wraps deleteSession, which hard-deletes so the UNIQUE(worker_id, name) slot frees for re-creation. No masterKey.

Watch for

createSession refuses a removing row — 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 own POST/DELETE /api/workers/:id/sessions/workspace endpoints. 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.

"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 no `masterKey` — verified — so no vault work. **`initial_message` is a launch argument, not a nudge.** `claude` accepts the prompt as a **positional argument**, so it appends in `buildLaunchCommand` and becomes the session's first turn. No `tmux 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 with `Input must be provided either through stdin or as a prompt argument`. Audit argument order in `composeLaunch` and **pin it with a test**: the nexus plugin's `--plugin-dir` is unconditional and `extraClaudeArgs` are 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 `--print` mode. Session names are validated against `git check-ref-format --branch` via `nexus/src/lib/git-ref.ts` — reuse it rather than re-deriving. Slashes are allowed (`feature/login`). **Serialize creates per workspace.** `createSession` shells out to `git -C /workspace worktree add` with no serialization, and concurrent adds contend on `index.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_session` Wraps `deleteSession`, which hard-deletes so the `UNIQUE(worker_id, name)` slot frees for re-creation. No `masterKey`. ## Watch for `createSession` refuses a `removing` row — 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 own `POST/DELETE /api/workers/:id/sessions/workspace` endpoints. 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.
lz added this to the MCP support (#140) milestone 2026-09-15 18:25:01 +02:00
Author
Owner

#174 put the tool surface on a contract. These become nexus_create_session and nexus_delete_session — the nexus_ prefix is in the type (`nexus_${string}`), so an unprefixed name is a compile error. See AGENTS.md fact #40; worked example mcp/tools/sessions.ts.

Three more things it now requires:

  • The tool lives in a file under mcp/tools/, which may not import registry.ts (import cycle — invisible in one of the two bundles).
  • annotations requires all four hints explicitly. nexus_create_session is readOnly: false, destructive: false, idempotent: false, openWorld: false; nexus_delete_session is readOnly: false, destructive: true, idempotent: true, openWorld: false. The SDK's own ToolAnnotations has every field optional and destructiveHint defaults to true, which is exactly why they are required here.
  • outputSchema is mandatory and run returns the payload typed against it. The SDK validates structuredContent against it on every call; a mismatch arrives as isError: true content on a 200, not as a JSON-RPC error.

Refusals — the workspace_shell rejection, and createSession refusing a removing row — should throw. The registry wrapper logs and rethrows, the SDK turns that into isError content, and an isError result skips output validation, so the refusal need not satisfy the schema. Make the message a sentence naming what to do about it.

#174 put the tool surface on a contract. These become **`nexus_create_session`** and **`nexus_delete_session`** — the `nexus_` prefix is in the type (``` `nexus_${string}` ```), so an unprefixed name is a compile error. See AGENTS.md fact #40; worked example `mcp/tools/sessions.ts`. Three more things it now requires: - The tool lives in a file under `mcp/tools/`, which may not import `registry.ts` (import cycle — invisible in one of the two bundles). - `annotations` requires all four hints **explicitly**. `nexus_create_session` is `readOnly: false, destructive: false, idempotent: false, openWorld: false`; `nexus_delete_session` is `readOnly: false, destructive: true, idempotent: true, openWorld: false`. The SDK's own `ToolAnnotations` has every field optional and `destructiveHint` defaults to **true**, which is exactly why they are required here. - `outputSchema` is mandatory and `run` returns the payload typed against it. The SDK validates `structuredContent` against it on every call; a mismatch arrives as `isError: true` content on a 200, not as a JSON-RPC error. Refusals — the `workspace_shell` rejection, and `createSession` refusing a `removing` row — should **throw**. The registry wrapper logs and rethrows, the SDK turns that into `isError` content, and an `isError` result skips output validation, so the refusal need not satisfy the schema. Make the message a sentence naming what to do about it.
Author
Owner

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 describes spawnWorker, which backgrounds provisionWorker. createSession inserts the row and then awaits the worktree add, .worktreeinclude, the trust write and tmux new-window before 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, since extraClaudeArgs grows.

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: convergeSessions builds its own --resume launch and never sees it, so a restored session cannot replay the opening instruction.

The mutex does not become a shared module. convergingWorkers is the same shape and is already instantiated twice, one per bundle, and its collision is latent rather than live — src/server.ts awaits restoreSessionsOnBoot before 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.ts calls tool.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): createSession against a booting workspace fails at tmux new-window, and nothing clears booting without a browser open.

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 describes `spawnWorker`, which backgrounds `provisionWorker`. `createSession` inserts the row and then **awaits** the worktree add, `.worktreeinclude`, the trust write and `tmux new-window` before 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, since `extraClaudeArgs` grows. **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: `convergeSessions` builds its own `--resume` launch and never sees it, so a restored session cannot replay the opening instruction. **The mutex does not become a shared module.** `convergingWorkers` is the same shape and is already instantiated twice, one per bundle, and its collision is latent rather than live — `src/server.ts` awaits `restoreSessionsOnBoot` before 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.ts` calls `tool.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): `createSession` against a `booting` workspace fails at `tmux new-window`, and nothing clears `booting` without a browser open.
lz closed this issue 2026-09-24 09:25:42 +02:00
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#156
No description provided.