thinkpool-pair 0.7.84 → 0.7.85

package/bridge.mjs

@@ -39,7 +39,7 @@ import { createClient } from '@supabase/supabase-js'
 import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
 import { z } from 'zod'
 import { startClaudeSession } from './claude-session.mjs'
-import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST } from './cross-terminal.mjs'
+import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST, spawnDecision } from './cross-terminal.mjs'
 import { turnInFlight } from './update-gate.mjs'
 import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames } from './session-store.mjs'
 import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks } from './event-id.mjs'
@@ -965,6 +965,74 @@ function openStructured({ id, model, resume, log, commands, mode }) {
           return okText(`Delivered to terminal ${target.ref} (${target.cmd}). It will respond in its own lane; check back with read_terminal.`)
         },
       ),
+      // Tier C+ — SPAWN a fresh agent lane the caller OWNS. The motivating bug:
+      // an agent fanned a research task into SIBLINGS that were already busy (a
+      // release lane, a Q&A lane) because it had no way to make its own lanes.
+      // This opens a brand-new structured session server-side (the same path the
+      // web's "+ New terminal" and the restore loop use), so announce() surfaces
+      // its tab in the open web UI live. Auto-allowed by the PreToolUse gate but
+      // bounded by spawnDecision (hop-0-only, per-turn cap, the live terminal cap,
+      // TP_SPAWN_OFF kill-switch). A spawned lane runs one hop deep, so it cannot
+      // recursively spawn/post onward — the fork-bomb breaker (mirrors Tier C).
+      tool(
+        'spawn_terminal',
+        'Open a NEW agent terminal (a fresh Claude lane) in this ThinkPool Code room — YOUR lane to use, not a sibling that is already working. Use it to fan work out: give it an initial `task` and it runs in parallel in its own lane; collect its result later with read_terminal, and close it with close_terminal when done. ALWAYS prefer spawning a fresh lane over post_to_terminal into one that is already busy. Bounded by the room terminal cap and a per-turn limit.',
+        {
+          name: z.string().max(80).optional().describe('a short label for the new lane so the room (and you) can find it, e.g. "Research: topologies"'),
+          task: z.string().optional().describe('an initial task to hand the new lane immediately; omit to open it idle'),
+          model: z.string().optional().describe('optional model for the lane, e.g. opus / sonnet / haiku'),
+        },
+        async (args) => {
+          const okText = (t) => ({ content: [{ type: 'text', text: t }] })
+          const gate = spawnDecision({ hop: entry.hop || 0, spawnCount: entry.spawnCount || 0, liveCount: sessions.size + terms.size, disabled: process.env.TP_SPAWN_OFF === '1' })
+          if (!gate.ok) return okText(gate.reason)
+          entry.spawnCount = (entry.spawnCount || 0) + 1
+          const newId = randomUUID()
+          const newRef = String(newId).slice(0, 8)
+          const fromRef = String(id).slice(0, 8)
+          // Name BEFORE opening so openStructured's own announce already carries the label.
+          if (args?.name) { termNames[newId] = String(args.name).slice(0, 80); saveNames(room, termNames) }
+          openStructured({ id: newId, model: args?.model })
+          const ne = sessions.get(newId)
+          if (!ne) { if (args?.name) { delete termNames[newId]; saveNames(room, termNames) } return okText('Could not open a new lane — the terminal cap may have just been reached. Close one and retry.') }
+          ne.spawnedBy = id   // ownership: only the spawner may close_terminal it
+          announce()          // (defensive) ensure the web renders the new tab live
+          if (args?.task) {
+            // One hop deep: the spawned lane cannot spawn/post onward until a person
+            // speaks to it (code-turn resets hop to 0). Mirrors the Tier C injection.
+            ne.hop = 1; ne.peekCount = 0; ne.postCount = 0; ne.spawnCount = 0
+            const msg = `[Task from terminal ${fromRef}'s agent — relayed via ThinkPool cross-terminal; you are a fresh lane it opened for you]\n${args.task}`
+            const evt = { kind: 'you', text: msg, by: `terminal ${fromRef} (agent)`, crosspost: true }
+            stampEvent(evt); pushLog(ne, evt); bcast('code-event', { term: newId, evt })
+            try { ne.session.sendTurn(msg) } catch { return okText(`Opened lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — could not hand off the task. Try post_to_terminal shortly.`) }
+            return okText(`Opened agent lane ${newRef}${args?.name ? ` ("${args.name}")` : ''} and handed it the task. It runs in its own lane — check back with read_terminal, then close_terminal when done.`)
+          }
+          return okText(`Opened idle agent lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}. Hand it work with post_to_terminal, or a person can type into it.`)
+        },
+      ),
+      // Tier C+ — CLOSE a lane the caller spawned. Restricted to self-spawned agent
+      // lanes (spawnedBy === this id): an agent must never be able to kill a sibling
+      // someone else is working in, nor the host/attached terminal. The fan-out
+      // cleanup half of spawn_terminal. Routes through endStructured (same path as
+      // the web's code-close), which no-ops if the id isn't a live session.
+      tool(
+        'close_terminal',
+        'Close an agent lane that YOU opened with spawn_terminal (identified by ref/id/name). You can only close lanes you spawned yourself — never a sibling someone else is working in, and never the main terminal. Use it to clean up after a fan-out once you have collected the results with read_terminal.',
+        {
+          terminal: z.string().describe('ref, id, or name of the lane you spawned (from read_terminal)'),
+        },
+        async (args) => {
+          const okText = (t) => ({ content: [{ type: 'text', text: t }] })
+          const sib = siblingsOf({ selfId: id, sessions, terms, names: termNames })
+          const target = resolveSibling(sib, args?.terminal)
+          if (!target) return okText(`No terminal matches "${args?.terminal}". Call read_terminal with no argument to list the open terminals.`)
+          const te = sessions.get(target.id)
+          if (!te) return okText(`Terminal ${target.ref} is not an agent lane (or already closed) — only spawned agent lanes can be closed this way.`)
+          if (te.spawnedBy !== id) return okText(`Terminal ${target.ref} was not opened by you — you can only close lanes you spawned yourself. Leave it to the person running it.`)
+          endStructured(target.id)
+          return okText(`Closed agent lane ${target.ref}${target.name ? ` ("${target.name}")` : ''}.`)
+        },
+      ),
     ],
   })
   entry.session = startClaudeSession({

package/claude-session.mjs

@@ -253,6 +253,16 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
     if (toolName === 'mcp__thinkpool__read_terminal') {
       return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: 'Auto-approved (read-only ThinkPool cross-terminal read).' } }
     }
+    // ThinkPool cross-terminal SPAWN / CLOSE (Tier C+) — lane management the agent
+    // OWNS. Unlike post_to_terminal (which WRITES into someone else's working lane,
+    // so it's human-gated every time), these only ever open a FRESH lane or close a
+    // lane the agent itself spawned — they never touch a sibling's work. Auto-allow
+    // (surfaced as a card for visibility); the bridge-side handler enforces the real
+    // bounds (hop-0-only, per-turn cap, the 8-terminal cap, TP_SPAWN_OFF) and can
+    // only close self-spawned lanes. This is the "you open them yourself" path.
+    if (toolName === 'mcp__thinkpool__spawn_terminal' || toolName === 'mcp__thinkpool__close_terminal') {
+      return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: 'Auto-approved (ThinkPool cross-terminal lane management — bounded by the room caps; closes only self-spawned lanes).' } }
+    }
     // ThinkPool cross-terminal POST (Tier C) WRITES into a sibling agent's lane —
     // human-gated EVERY time, never remembered. First a bridge-side precheck
     // (kill-switch / loop-breaker / per-turn cap) so a blocked or runaway post
@@ -386,6 +396,7 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
       'RUN IT, DO NOT ASK: verify your own work before calling it done. Actually run or serve what you changed, observe that it behaves correctly, and show the evidence in the room — a screenshot of the running result, the passing test output, or the real response — rather than telling the user "this should work, go test it." If you could not verify something, say exactly what is unverified. This room follows verify-before-claiming: runtime evidence you produced, not assertion.',
       'CROSS-TERMINAL AWARENESS: this room may have other terminals open alongside yours — other agents working, or shells the people are driving. You have a READ-ONLY tool, read_terminal: call it with no arguments to list the other open terminals, or with a terminal ref/id/command to read that terminal\'s recent activity. Reach for it when your work depends on what another terminal is doing (e.g. someone says "see what the other terminal hit", or you need to coordinate with a sibling agent before acting). It only ever reads — it never changes another terminal. Identify a terminal by its NAME or its ref/id from the roster, never by an on-screen number like "Terminal 2" — those positional labels renumber when a terminal is closed, so they do not reliably point at a lane.',
       'CROSS-TERMINAL HAND-OFF: you also have post_to_terminal(terminal, text) to send a message or task to ANOTHER AGENT terminal in this room (not a plain shell). Use it sparingly and only when the people clearly want the lanes to coordinate — e.g. "tell the backend terminal the API is ready", or to hand a sibling agent a concrete task. Every post requires a person in the room to approve a card before it is delivered, and an agent that was itself reached via a cross-post cannot post onward — so do not rely on it for chit-chat or loops. Prefer read_terminal to understand a sibling before you ever post to it.',
+      'CROSS-TERMINAL SPAWN: when a person asks you to fan work out across multiple agents — research lanes, parallel sub-tasks, a swarm — open YOUR OWN fresh lanes with spawn_terminal(name?, task?, model?); do NOT dump the work into siblings that are already busy (a sibling is mid-task unless read_terminal shows it idle, and hijacking it derails their work). spawn_terminal opens a brand-new Claude lane and, if you pass `task`, hands it that task immediately; it appears as a new terminal in the room. Collect each lane\'s result later with read_terminal (a spawned lane cannot post back to you), and tidy up with close_terminal once you have what you need — you may only close lanes you spawned yourself. You are bounded: at most a few new lanes per turn and 8 terminals total in the room, and a lane you were spawned/cross-posted into cannot itself spawn (so no runaway). This is how you "open the terminals yourself" instead of asking a person to.',
       'WRITE PLANS INTO THE CHAT: whenever you form or revise a plan — because the room is in Plan mode, or because someone asked you to plan, design, or think it through first — write the actual plan out as a normal message in the room as you develop it: the approach, the concrete steps, the files you will touch, the open questions. The room does NOT surface plan files at all, and the plan-approval card does not reliably carry the plan text, so a plan that lives only in a plan file or only inside ExitPlanMode is INVISIBLE to the people you are working with — they just see "plan ready" with no content. The chat is the canonical place your plan lives; put it there so the room can read and react to it before you proceed.',
     ].join(' '),
     // Needed for live thinking-token progress (SDKThinkingTokensMessage) to

package/cross-terminal.mjs

@@ -158,3 +158,31 @@ export const crossPostDecision = ({ hop = 0, postCount = 0, disabled = false } =
   if (postCount >= o.perTurnCap) return { ok: false, reason: `Cross-terminal post limit reached for this turn (${o.perTurnCap}).` }
   return { ok: true }
 }
+
+// ── Tier C+: cross-terminal SPAWN (open a FRESH lane the agent owns) ──────────
+// Pure gate for whether a session may open a new terminal on THIS call. The
+// motivating bug: an agent dumped a fan-out into SIBLINGS that were already
+// working (a bridge release lane, a Q&A lane) because it had no way to make its
+// OWN lanes. spawn_terminal gives it fresh lanes; this gate keeps that from
+// becoming a fork bomb. Bounds, in order:
+//   • kill-switch (TP_SPAWN_OFF)
+//   • hop — a lane REACHED via cross-post/spawn (hop ≥ 1) cannot spawn onward, so
+//     a spawned agent can't recursively spawn (the loop breaker, mirrors CROSSPOST)
+//   • maxTerms — the hard live-terminal cap (matches openTerm's cap of 8); the
+//     real backstop, since spawned lanes are bounded by it regardless of turns
+//   • perTurnCap — a per-turn runaway breaker (mirrors PEEK/CROSSPOST)
+// liveCount is the caller's measured sessions.size + terms.size at call time.
+export const SPAWN = {
+  maxHop: 1,       // human turn = hop 0; a spawned/injected lane = hop ≥ 1, which CANNOT spawn onward
+  perTurnCap: 4,   // spawn_terminal calls allowed per turn (total still capped by maxTerms)
+  maxTerms: 8,     // hard cap on live terminals in the room (matches openTerm)
+}
+
+export const spawnDecision = ({ hop = 0, spawnCount = 0, liveCount = 0, disabled = false } = {}, limits = SPAWN) => {
+  const o = { ...SPAWN, ...(limits || {}) }
+  if (disabled) return { ok: false, reason: 'Spawning terminals is disabled in this room.' }
+  if (hop >= o.maxHop) return { ok: false, reason: 'Spawn limit reached — a terminal reached via cross-terminal cannot itself open further terminals; a person must open the next lane.' }
+  if (liveCount >= o.maxTerms) return { ok: false, reason: `Terminal cap (${o.maxTerms}) reached — close a terminal before opening another.` }
+  if (spawnCount >= o.perTurnCap) return { ok: false, reason: `Spawn limit reached for this turn (${o.perTurnCap}).` }
+  return { ok: true }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.84",
+  "version": "0.7.85",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {