thinkpool-pair 0.7.82 → 0.7.84

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 } from './cross-terminal.mjs'
+import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSPOST } 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'
@@ -921,15 +921,58 @@ function openStructured({ id, model, resume, log, commands, mode }) {
           if (entry.peekCount > PEEK.perTurnCap) {
             return { content: [{ type: 'text', text: `Cross-terminal read limit reached for this turn (${PEEK.perTurnCap}). Continue with what you have, or ask the people in the room.` }] }
           }
-          const text = formatPeek({ selfId: id, sessions, terms, terminal: args?.terminal, lines: args?.lines })
+          const text = formatPeek({ selfId: id, sessions, terms, names: termNames, terminal: args?.terminal, lines: args?.lines })
           return { content: [{ type: 'text', text }] }
         },
       ),
+      // Tier C — directed cross-lane action. WRITES into a sibling AGENT lane.
+      // The PreToolUse gate (claude-session.mjs) already enforced: precheck passed
+      // + a human approved the card. This handler routes only; it re-asserts the
+      // bounds defensively. Targets AGENT terminals only (not human shells —
+      // injecting keystrokes into someone's shell is out of scope for v1).
+      tool(
+        'post_to_terminal',
+        'Send a message or task to ANOTHER AGENT terminal in this ThinkPool Code room. Use `terminal` (a ref/id/command from read_terminal) and `text` (what to send). A person in the room must approve before it is delivered, and an agent reached via a cross-post cannot post onward. Targets agent terminals only, not plain shells. Use read_terminal first to understand the sibling.',
+        {
+          terminal: z.string().describe('ref, id, or command of the AGENT terminal to send to (from read_terminal)'),
+          text: z.string().describe('the message or task to deliver to that terminal'),
+        },
+        async (args) => {
+          const okText = (t) => ({ content: [{ type: 'text', text: t }] })
+          // Defensive re-check (the gate already passed in PreToolUse).
+          const gate = crossPostDecision({ hop: entry.hop || 0, postCount: entry.postCount || 0, disabled: process.env.TP_CROSSPOST_OFF === '1' })
+          if (!gate.ok) return okText(gate.reason)
+          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.`)
+          if (target.kind !== 'agent') return okText(`Terminal ${target.ref} is a shell, not an agent — cross-posting is only allowed to agent terminals.`)
+          const te = sessions.get(target.id)
+          if (!te?.session) return okText(`Terminal ${target.ref} is no longer live.`)
+          entry.postCount = (entry.postCount || 0) + 1
+          const fromRef = String(id).slice(0, 8)
+          const msg = `[From: terminal ${fromRef}'s agent — relayed via ThinkPool cross-terminal, approved by a person in the room]\n${args.text}`
+          // The injected turn starts fresh budgets, one hop deeper (loop breaker).
+          te.hop = (entry.hop || 0) + 1
+          te.peekCount = 0
+          te.postCount = 0
+          // Echo the injected prompt into the TARGET lane so both people see what
+          // arrived (rides the existing code-event 'you' path — no new topic).
+          const evt = { kind: 'you', text: msg, by: `terminal ${fromRef} (agent)`, crosspost: true }
+          stampEvent(evt)
+          pushLog(te, evt)
+          bcast('code-event', { term: target.id, evt })
+          try { te.session.sendTurn(msg) } catch { return okText(`Could not deliver to terminal ${target.ref} — it may have just closed.`) }
+          return okText(`Delivered to terminal ${target.ref} (${target.cmd}). It will respond in its own lane; check back with read_terminal.`)
+        },
+      ),
     ],
   })
   entry.session = startClaudeSession({
     cwd: process.cwd(), model, resume, mode,
     mcpServers: { thinkpool: peekServer },
+    // Tier C precheck — the PreToolUse gate calls this BEFORE raising a card, so a
+    // disabled/looping/over-cap post never bothers a person. Closes over `entry`.
+    crossPostGate: () => crossPostDecision({ hop: entry.hop || 0, postCount: entry.postCount || 0, disabled: process.env.TP_CROSSPOST_OFF === '1' }),
     env: { ...process.env, TP_MOCKUP_OUTBOX: mockupOutbox },
     onEvent: (evt) => {
       // Self-heal a stale resume — the saved SDK session expired. Reopen fresh,
@@ -1216,7 +1259,13 @@ channel
     const s = payload?.term && sessions.get(payload.term)
     if (!s || payload.text == null) return
     markActivity()
-    s.peekCount = 0   // B2: fresh cross-terminal read budget per user turn
+    // B2/C: a real human turn is hop 0 with fresh cross-terminal budgets. This is
+    // the loop-breaker reset point — an injected (cross-posted) turn does NOT come
+    // through here, so its deeper hop level + spent budget stick until a person
+    // speaks again.
+    s.peekCount = 0
+    s.postCount = 0
+    s.hop = 0
     const text = String(payload.text)
     // Echo the turn so BOTH readers (and late joiners, via the log) show who
     // said what — UNLESS silent (an @pool fire, which renders its own line).
@@ -1225,7 +1274,7 @@ channel
       // Display the clean body (web sends `body` when the agent `text` carries host
       // file paths) + the uploaded attachments, so the partner shows the image — not
       // a raw /var path. The agent already got the full `text` via sendTurn above.
-      const evt = { kind: 'you', text: payload.body != null ? String(payload.body) : text, cid: payload.cid, by: payload.by, ...(Array.isArray(payload.files) && payload.files.length ? { files: payload.files } : {}) }
+      const evt = { kind: 'you', text: payload.body != null ? String(payload.body) : text, cid: payload.cid, by: payload.by, ...(Array.isArray(payload.files) && payload.files.length ? { files: payload.files } : {}), ...(Array.isArray(payload.pastes) && payload.pastes.length ? { pastes: payload.pastes } : {}) }
       pushLog(s, evt)
       bcast('code-event', { term: payload.term, evt })
     }

package/claude-session.mjs

@@ -120,7 +120,7 @@ const simplifyBlocks = (blocks = []) => blocks.map((b) => {
  */
 const MODES = new Set(['default', 'acceptEdits', 'plan', 'bypassPermissions'])
 
-export function startClaudeSession({ cwd, model, resume, env, mode: initialMode = 'default', onEvent, requestPermission, mcpServers }) {
+export function startClaudeSession({ cwd, model, resume, env, mode: initialMode = 'default', onEvent, requestPermission, mcpServers, crossPostGate }) {
   const ac = new AbortController()
   let input = makeInputStream()   // `let`: auto-restart swaps in a fresh stream
   let sessionId = resume || null
@@ -248,12 +248,26 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
     // Surface it to the room when it changes; absent on models without effort.
     const lvl = hookInput.effort?.level
     if (lvl && lvl !== effort) { effort = lvl; emit({ kind: 'effort', level: effort }) }
-    // ThinkPool's own in-process tools (B2 cross-terminal read) are read-only and
-    // within-room — never prompt for them, in any mode. They still surface as
-    // tool_use/tool_result cards so the room sees the peek.
-    if (typeof toolName === 'string' && toolName.startsWith('mcp__thinkpool__')) {
+    // ThinkPool cross-terminal READ (B2) is read-only + within-room — never
+    // prompt, in any mode. It still surfaces as a tool card so the room sees the peek.
+    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 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
+    // never even raises a card; then the standard permission round-trip at 'high'
+    // risk (card offers Deny / Allow-once only — no "always"). Spec INV-4.
+    if (toolName === 'mcp__thinkpool__post_to_terminal') {
+      const gate = crossPostGate ? crossPostGate() : { ok: true }
+      if (!gate.ok) {
+        return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: gate.reason || 'Cross-terminal post not allowed right now.' } }
+      }
+      let decision = 'deny'
+      try { decision = await requestPermission?.({ id: randomUUID(), toolName, input: toolInput, risk: 'high' }) ?? 'deny' } catch { decision = 'deny' }
+      const allowed = decision === 'allow'
+      return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: allowed ? 'allow' : 'deny', permissionDecisionReason: allowed ? 'Cross-terminal post approved in the ThinkPool room.' : 'Cross-terminal post denied in the room — do not retry; ask what to do instead.' } }
+    }
     // ── Plan approval — ExitPlanMode is how the agent presents its plan in
     // plan mode. Render a dedicated plan card (not the generic perm card) with
     // three outcomes: run (exit → default), accept (exit → acceptEdits), keep
@@ -370,7 +384,8 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
       'SHOW YOUR WORK, do not just describe it: the room is watched live from a phone, where a wall of text is painful to read. Whenever you build, change, or fix anything visual — a UI, a page, an HTML artifact, a chart, a diagram, a rendered result — capture a screenshot and surface the PNG (for example, read the image file into your turn) so it appears inline in the room. The room auto-uploads any image you surface. Default to showing a picture of the result over narrating it; err toward more screenshots, not fewer.',
       'HTML PREVIEWS: for any HTML you produce, give the room something it can actually open, by whichever path is available. (a) IN-ROOM PREVIEW: if a mockup render helper is present — one that writes a manifest into the directory named by $TP_MOCKUP_OUTBOX, such as the mockup-iterate render.sh script when the bridge was launched from the thinkpool repo — use it; it surfaces an inline card with desktop and mobile views that the room can expand. (b) SHAREABLE LINK: additionally or otherwise, publish the HTML to a GitHub Pages URL per the LINKS & ARTIFACTS rule above and post the link. Never leave an HTML artifact viewable only as a local path.',
       '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.',
+      '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.',
       '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

@@ -59,36 +59,77 @@ export const cleanPtyTail = (buf, n) => {
 // Build the tool's text reply. `selfId` is excluded. `sessions` (structured) and
 // `terms` (PTY) are the bridge's module-scope Maps (id → entry). With no
 // `terminal`, returns the roster; with one, returns that lane's recent output.
-export const formatPeek = ({ selfId, sessions, terms, terminal, lines } = {}) => {
-  const n = Math.min(PEEK.maxLines, Math.max(1, Number(lines) || PEEK.defaultLines))
+// ── shared sibling resolution (used by formatPeek + the cross-post handler) ──
+export const siblingRef = (id) => String(id).slice(0, 8)
+
+// Every terminal in the room except `selfId`, normalized. Structured sessions →
+// kind 'agent' (carry `log`); PTY terminals → kind 'shell' (carry `buf`). `names`
+// is the bridge's id→label map (termNames) — the HUMAN names people actually use
+// ("Pivot", "Grug"); without it the roster is just hashes and an agent can't map
+// "what is Pivot doing" to a lane.
+export const siblingsOf = ({ selfId, sessions, terms, names = {} } = {}) => {
+  const nm = (id) => (names && names[id]) || ''
   const sib = []
   for (const [id, s] of (sessions || new Map())) {
     if (id === selfId) continue
-    sib.push({ id, kind: 'agent', cmd: s?.cmd || 'claude', log: Array.isArray(s?.log) ? s.log : [] })
+    sib.push({ id, ref: siblingRef(id), name: nm(id), kind: 'agent', cmd: s?.cmd || 'claude', log: Array.isArray(s?.log) ? s.log : [] })
   }
   for (const [id, t] of (terms || new Map())) {
     if (id === selfId) continue
-    sib.push({ id, kind: 'shell', cmd: t?.cmd || 'shell', buf: t?.buf || '' })
+    sib.push({ id, ref: siblingRef(id), name: nm(id), kind: 'shell', cmd: t?.cmd || 'shell', buf: t?.buf || '' })
   }
-  if (!sib.length) return 'No other terminals are open in this room right now.'
+  return sib
+}
 
-  const ref = (x) => String(x.id).slice(0, 8)
+// True for a POSITIONAL on-screen label ("Terminal 2", "t3", bare "2"). These
+// renumber when a sibling closes (Terminal 3 → Terminal 2 after a delete), so the
+// bridge — which only ever knows stable UUIDs — must NEVER resolve them, or a
+// delete could silently re-point a cross-post at the wrong lane. We refuse them
+// explicitly (safe miss) instead. The stable handles are the UUID/ref and the
+// custom name (both bound to the UUID, immune to renumbering).
+export const isOrdinalRef = (q) => /^(terminal\s*)?\d+$/i.test(q) || /^t\d+$/i.test(q)
+
+// Resolve an agent-supplied reference to one sibling, or null. Match priority:
+// exact id → exact name → exact short-ref → id-prefix (≥4 chars) → name substring
+// → command substring. Name matching is what makes "Pivot" / "Grug" resolvable;
+// positional ordinals are refused (see isOrdinalRef).
+export const resolveSibling = (siblings, terminal) => {
+  const q = String(terminal || '').toLowerCase().trim()
+  if (!q || isOrdinalRef(q)) return null
+  const list = Array.isArray(siblings) ? siblings : []
+  return list.find(x => String(x.id).toLowerCase() === q)
+    || list.find(x => String(x.name || '').toLowerCase() === q)
+    || list.find(x => String(x.ref).toLowerCase() === q)
+    || list.find(x => q.length >= 4 && String(x.id).toLowerCase().startsWith(q))
+    || list.find(x => x.name && String(x.name).toLowerCase().includes(q))
+    || list.find(x => String(x.cmd).toLowerCase().includes(q))
+    || null
+}
+
+const label = (x) => `${x.ref}${x.name ? ` · "${x.name}"` : ''}`
+
+export const formatPeek = ({ selfId, sessions, terms, names = {}, terminal, lines } = {}) => {
+  const n = Math.min(PEEK.maxLines, Math.max(1, Number(lines) || PEEK.defaultLines))
+  const sib = siblingsOf({ selfId, sessions, terms, names })
+  if (!sib.length) return 'No other terminals are open in this room right now.'
 
   if (!terminal) {
     const rows = sib.map(x => {
       let preview
       if (x.kind === 'agent') { const ls = x.log.map(e => digestLogEvent(e, PEEK.rosterPreview)).filter(Boolean); preview = ls[ls.length - 1] || '(no activity yet)' }
       else { preview = cleanPtyTail(x.buf, 1)[0] || '(no output yet)' }
-      return `- ${ref(x)} · ${x.kind} · ${x.cmd} — ${clip(preview, PEEK.rosterPreview)}`
+      return `- ${label(x)} · ${x.kind} · ${x.cmd} — ${clip(preview, PEEK.rosterPreview)}`
     })
-    return `Other terminals in this room (call read_terminal with one of these refs to read it):\n${rows.join('\n')}`
+    return `Other terminals in this room (call read_terminal with a ref or name to read one):\n${rows.join('\n')}`
   }
 
-  const q = String(terminal).toLowerCase().trim()
-  const hit = sib.find(x => String(x.id).toLowerCase() === q)
-    || sib.find(x => ref(x).toLowerCase() === q || String(x.id).toLowerCase().startsWith(q))
-    || sib.find(x => String(x.cmd).toLowerCase().includes(q))
-  if (!hit) return `No terminal matches "${terminal}". Call read_terminal with no argument to list the open terminals.`
+  const hit = resolveSibling(sib, terminal)
+  if (!hit) {
+    const extra = isOrdinalRef(String(terminal || '').toLowerCase().trim())
+      ? ` On-screen numbers like "Terminal N" shift when a terminal closes, so they can't identify a lane — use a terminal's name or ref instead.`
+      : ''
+    return `No terminal matches "${terminal}". Call read_terminal with no argument to list the open terminals (refer to one by its name or ref).${extra}`
+  }
 
   let body
   if (hit.kind === 'agent') {
@@ -96,5 +137,24 @@ export const formatPeek = ({ selfId, sessions, terms, terminal, lines } = {}) =>
   } else {
     body = cleanPtyTail(hit.buf, n).join('\n') || '(no output yet)'
   }
-  return `Terminal ${ref(hit)} (${hit.kind} · ${hit.cmd}) — last ${n} lines:\n${body}`
+  return `Terminal ${label(hit)} (${hit.kind} · ${hit.cmd}) — last ${n} lines:\n${body}`
+}
+
+// ── Tier C: cross-terminal POST (directed, gated cross-lane action) ──────────
+// Pure gate for whether a session may post into a sibling lane on THIS call:
+// kill-switch, loop-breaker (hop), per-turn cap. The routing itself (sendTurn
+// into the target) lives in bridge.mjs — it needs the live session. Spec INV-4:
+// no text reaches a sibling without an approved code-perm; agent-originated turns
+// are hop-capped so two agents can't ping-pong forever.
+export const CROSSPOST = {
+  maxHop: 1,      // human turn = hop 0; an injected turn = hop 1, which CANNOT post onward
+  perTurnCap: 3,  // post_to_terminal calls allowed per turn
+}
+
+export const crossPostDecision = ({ hop = 0, postCount = 0, disabled = false } = {}, limits = CROSSPOST) => {
+  const o = { ...CROSSPOST, ...(limits || {}) }
+  if (disabled) return { ok: false, reason: 'Cross-terminal posting is disabled in this room.' }
+  if (hop >= o.maxHop) return { ok: false, reason: 'Cross-terminal hop limit reached — an agent reached via cross-post cannot itself post onward; a person must direct the next cross-terminal action.' }
+  if (postCount >= o.perTurnCap) return { ok: false, reason: `Cross-terminal post limit reached for this turn (${o.perTurnCap}).` }
+  return { ok: true }
 }

package/package.json

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