thinkpool-pair 0.5.1 → 0.6.2

package/bridge.mjs

@@ -34,6 +34,7 @@ import path from 'node:path'
 import readline from 'node:readline'
 import { randomUUID } from 'node:crypto'
 import { createClient } from '@supabase/supabase-js'
+import { startClaudeSession } from './claude-session.mjs'
 
 // Public client creds (the same anon values the web app ships — safe to embed).
 // Override with TP_SUPABASE_URL / TP_SUPABASE_ANON if you ever need to.
@@ -118,6 +119,15 @@ const argv = process.argv.slice(2)
 const room = (argv[0] || '').toUpperCase().trim()
 if (!room || room.startsWith('-')) { console.error('usage: npx thinkpool-pair <ROOM> [--headless] [--continue|--fresh] [-- <command…>]'); process.exit(1) }
 const headless = argv.includes('--headless')
+// Structured mode (Phase 2, opt-in): Claude Code runs through the Agent SDK
+// (structured events + risk-tiered permission gate) instead of the PTY byte
+// relay. Default OFF — the PTY path is untouched. Only applies to `claude`.
+// Spec: docs/specs/2026-06-11-code-structured-reader.md
+const STRUCTURED = process.env.TP_STRUCTURED === '1' || argv.includes('--structured')
+// Claude Code runs as a STRUCTURED Agent-SDK session by default now (the picked
+// design — structured reader, risk-tiered permissions). Other CLIs keep the PTY
+// relay. TP_PTY=1 forces claude back to the raw PTY if ever needed.
+const wantStructured = (cmd) => /(^|[/\\])claude$/.test(cmd || '') && process.env.TP_PTY !== '1'
 const installedAgents = KNOWN_AGENTS.filter(a => onPath(a.cmd))
 const dashIdx = argv.indexOf('--')
 // Own flags are only read from BEFORE `--`; after it, every token belongs
@@ -187,6 +197,10 @@ const channel = supabase.channel(`tpcode:${room}`, {
 // ── terminal registry ──────────────────────────────────────────────
 // id → { term (pty), cmd, attached, scrollback, buf }
 const terms = new Map()
+// Structured Claude sessions live in their own registry, separate from the
+// PTY `terms` map so none of the byte-relay code paths (flush, resize,
+// pty-in, scrollback) ever touch them. id → { session, cmd, log, pending }.
+const sessions = new Map()
 let attachedId = null
 let shuttingDown = false
 
@@ -223,7 +237,12 @@ const announce = () =>
     }),
     // cols/rows: the PTY's one true size — web viewers render this grid and
     // scale it to their own page instead of voting to reflow it.
-    terms: [...terms.entries()].map(([id, t]) => ({ id, cmd: t.cmd, alive: true, cols: t.term.cols, rows: t.term.rows })),
+    terms: [
+      ...[...terms.entries()].map(([id, t]) => ({ id, cmd: t.cmd, alive: true, cols: t.term.cols, rows: t.term.rows })),
+      // Structured sessions advertise kind:'structured' so the web renders the
+      // reader (not xterm) and drives them with code-turn / code-perm.
+      ...[...sessions.entries()].map(([id, s]) => ({ id, cmd: s.cmd, kind: 'structured', alive: true })),
+    ],
   })
 
 // One flush timer batches every terminal's pending bytes (~35ms cadence).
@@ -289,6 +308,33 @@ function openTerm({ id, cmd, args = [], attached = false, cols, rows }) {
   return entry
 }
 
+// ── structured Claude session ──────────────────────────────────────
+// The Phase-2 path: instead of a PTY, run Claude Code through the Agent
+// SDK and relay STRUCTURED events. onEvent → broadcast `code-event`;
+// every tool call round-trips through `code-perm-req`/`code-perm` (the
+// risk-tiered permission card). A rolling event log replays to joiners.
+const STRUCTURED_LOG_MAX = 400
+function openStructured({ id, model, resume }) {
+  if (sessions.has(id)) return
+  const entry = { cmd: 'claude', kind: 'structured', log: [], pending: new Map(), session: null }
+  sessions.set(id, entry)
+  entry.session = startClaudeSession({
+    cwd: process.cwd(), model, resume,
+    onEvent: (evt) => {
+      entry.log.push(evt)
+      if (entry.log.length > STRUCTURED_LOG_MAX) entry.log.shift()
+      bcast('code-event', { term: id, evt })
+    },
+    requestPermission: (req) => new Promise((resolve) => {
+      entry.pending.set(req.id, resolve)
+      bcast('code-perm-req', { term: id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk })
+    }),
+  })
+  announce()
+  process.stderr.write(`\n  ◆ structured Claude session (${id.slice(0, 8)}) — driven from the room.\n`)
+  return entry
+}
+
 // After the attached CLI exits, the host's stdin stops feeding a PTY —
 // restore the cooked terminal so Ctrl-C reaches the bridge itself.
 const detachLocal = () => {
@@ -341,6 +387,11 @@ channel
       const agent = KNOWN_AGENTS.find(a => a.cmd === payload.cmd)
       if (agent?.resume) { try { if (agent.resume.probe()) args = [...agent.resume.args] } catch { /* fresh */ } }
     }
+    if (wantStructured(payload.cmd)) {
+      openStructured({ id: payload.id })
+      process.stderr.write(`\n  ◆ web opened a structured "${payload.cmd}" session.\n`)
+      return
+    }
     openTerm({ id: payload.id, cmd: payload.cmd, args })
     process.stderr.write(`\n  ◆ web opened a "${payload.cmd}"${args.length ? ' (continue)' : ''} terminal (headless).\n`)
   })
@@ -359,6 +410,11 @@ channel
         b64: Buffer.from(t.scrollback, 'utf8').toString('base64'),
       })
     }
+    // Structured sessions replay their event log (reader rebuilds from it).
+    for (const [id, s] of sessions) {
+      if (!s.log.length) continue
+      bcast('code-replay', { to: payload?.to ?? null, term: id, events: s.log })
+    }
     announce()
   })
   .on('broadcast', { event: 'file-put' }, ({ payload }) => {
@@ -381,11 +437,47 @@ channel
       }
     })()
   })
+  // ── structured-session control (Phase 2) ──
+  .on('broadcast', { event: 'code-open' }, ({ payload }) => {
+    if (payload?.host && payload.host !== name) return
+    openStructured({ id: payload?.id || randomUUID(), model: payload?.model, resume: payload?.resume })
+  })
+  .on('broadcast', { event: 'code-turn' }, ({ payload }) => {
+    const s = payload?.term && sessions.get(payload.term)
+    if (s && payload.text != null) {
+      s.session.sendTurn(payload.text)
+      // Echo the turn so BOTH readers (and late joiners, via the log) show who
+      // said what — UNLESS silent (an @pool synthesis, which renders as its own
+      // 'pool' line). The sender rendered it optimistically; partner gets this.
+      if (!payload.silent) {
+        const evt = { kind: 'you', text: payload.text, cid: payload.cid, by: payload.by }
+        s.log.push(evt); if (s.log.length > STRUCTURED_LOG_MAX) s.log.shift()
+        bcast('code-event', { term: payload.term, evt })
+      }
+    }
+  })
+  .on('broadcast', { event: 'code-perm' }, ({ payload }) => {
+    const s = payload?.term && sessions.get(payload.term)
+    const resolve = s && payload.id && s.pending.get(payload.id)
+    if (resolve) { s.pending.delete(payload.id); resolve(payload.decision === 'deny' ? 'deny' : 'allow') }
+  })
+  .on('broadcast', { event: 'code-abort' }, ({ payload }) => {
+    const s = payload?.term && sessions.get(payload.term)
+    if (s) s.session.abort()
+  })
+  .on('broadcast', { event: 'code-close' }, ({ payload }) => {
+    const s = payload?.id && sessions.get(payload.id)
+    if (s) { try { s.session.end() } catch { /* noop */ } ; sessions.delete(payload.id); bcast('term-exit', { id: payload.id }); announce() }
+  })
   .on('broadcast', { event: 'who' }, announce)
   .subscribe(status => {
     if (status === 'SUBSCRIBED') {
       channel.track({ name, role: 'bridge' })
-      if (attachedCmd && !terms.size) openTerm({ id: randomUUID(), cmd: attachedCmd, args: attachedArgs, attached: true })
+      if (attachedCmd && !terms.size && !sessions.size) {
+        // Claude + structured mode → Agent SDK session; everything else → PTY.
+        if (wantStructured(attachedCmd)) openStructured({ id: randomUUID() })
+        else openTerm({ id: randomUUID(), cmd: attachedCmd, args: attachedArgs, attached: true })
+      }
       announce()
       process.stderr.write(headless
         ? `\n  ◆ thinkpool — relaying room ${room} (headless). Open terminals from the web UI.\n\n`
@@ -403,6 +495,7 @@ function shutdown() {
   } catch { /* noop */ }
   try { supabase.removeChannel(channel) } catch { /* noop */ }
   for (const t of terms.values()) { try { t.term.kill() } catch { /* noop */ } }
+  for (const s of sessions.values()) { try { s.session.end() } catch { /* noop */ } }
   detachLocal()
   process.exit(0)
 }

package/claude-session.mjs

@@ -0,0 +1,165 @@
+/* ─────────────────────────────────────────────────────────────
+   claude-session.mjs — a structured, interactive Claude Code session
+   for the ThinkPool bridge. Wraps @anthropic-ai/claude-agent-sdk:
+   one long-lived streaming-input query() per terminal, structured
+   events out, user turns + abort in, and a PreToolUse permission gate
+   that classifies each tool call's risk and round-trips the decision
+   to the room (the risk-tiered permission card).
+
+   This replaces the PTY byte relay for Claude Code only. Other CLIs
+   keep the node-pty path in bridge.mjs. Auth is the HOST's own Claude
+   Code login (Keychain / API key) — no ThinkPool credential involved.
+   Spec: docs/specs/2026-06-11-code-structured-reader.md
+   ───────────────────────────────────────────────────────────── */
+
+import { randomUUID } from 'node:crypto'
+import { query } from '@anthropic-ai/claude-agent-sdk'
+
+// ── risk classification — the accent/danger tier of the permission card ──
+// low (read-only) · medium (writes/runs) · network (leaves the machine) ·
+// high (destructive, deny-first). See the permission spec + mockups.
+// Any `rm`/`rmdir` with an argument is destructive (a bare `rm NOTES.md`
+// deletes just as permanently as `rm -rf`). Plus force-push, hard reset,
+// clean -f, DROP, mkfs/dd, sudo, /dev redirects, recursive chmod/chown, etc.
+const DESTRUCTIVE = /\brm\s+\S|\brmdir\s+\S|\bgit\s+(push\s+(-f|--force)|reset\s+--hard|clean\s+-[a-z]*f)|\bdrop\s+(table|database)\b|\b(mkfs|dd)\b|\bsudo\b|>\s*\/dev\/|\bchmod\s+-R|\bchown\s+-R|\bkillall\b|\btruncate\b/i
+const READONLY_TOOLS = new Set(['Read', 'Grep', 'Glob', 'NotebookRead', 'TodoRead', 'LS'])
+const NETWORK_TOOLS = new Set(['WebFetch', 'WebSearch'])
+const WRITE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'TodoWrite'])
+
+export function classifyRisk(toolName, input) {
+  if (toolName === 'Bash') {
+    const cmd = (input && (input.command ?? input.cmd)) || ''
+    return DESTRUCTIVE.test(cmd) ? 'high' : 'medium'
+  }
+  if (READONLY_TOOLS.has(toolName)) return 'low'
+  if (NETWORK_TOOLS.has(toolName)) return 'network'
+  if (WRITE_TOOLS.has(toolName)) return 'medium'
+  // Unknown / MCP / Task tools: treat as medium (asks, amber) rather than
+  // silently allowing — safer default for a remote-driven agent.
+  return 'medium'
+}
+
+// ── input stream — a generator we keep open and feed turns into ──
+function makeInputStream() {
+  const queue = []
+  let wake = null
+  let ended = false
+  async function* gen() {
+    while (!ended) {
+      if (queue.length) { yield queue.shift(); continue }
+      await new Promise((r) => { wake = r })
+    }
+  }
+  return {
+    stream: gen(),
+    push(content) {
+      queue.push({ type: 'user', message: { role: 'user', content } })
+      if (wake) { wake(); wake = null }
+    },
+    end() { ended = true; if (wake) { wake(); wake = null } },
+  }
+}
+
+// Simplify SDK assistant content blocks to a stable wire shape.
+const simplifyBlocks = (blocks = []) => blocks.map((b) => {
+  if (b.type === 'text') return { type: 'text', text: b.text }
+  if (b.type === 'thinking') return { type: 'thinking', text: b.thinking || '' }
+  if (b.type === 'tool_use') return { type: 'tool_use', id: b.id, name: b.name, input: b.input }
+  return { type: b.type }
+}).filter(Boolean)
+
+/**
+ * Start a structured Claude Code session.
+ *
+ * @param {object}   o
+ * @param {string=}  o.cwd               working directory for the agent
+ * @param {string=}  o.model             model id (default: host's configured)
+ * @param {string=}  o.resume            session id to resume
+ * @param {(evt)=>void} o.onEvent        receives normalized structured events
+ * @param {(req)=>Promise<'allow'|'deny'>} o.requestPermission
+ *        called for EVERY tool call with { id, toolName, input, risk };
+ *        resolve 'allow'/'deny'. (Caller implements any auto-allow policy.)
+ * @returns {{ sendTurn(text), abort(), end(), readonly sessionId }}
+ */
+export function startClaudeSession({ cwd, model, resume, onEvent, requestPermission }) {
+  const ac = new AbortController()
+  const input = makeInputStream()
+  let sessionId = resume || null
+  let closed = false
+
+  const emit = (evt) => { try { onEvent?.(evt) } catch { /* never let a consumer throw into the loop */ } }
+
+  // PreToolUse — fires on EVERY tool call (the universal gate). Classify
+  // risk, round-trip the decision to the room, return allow/deny.
+  const preTool = async (hookInput) => {
+    const toolName = hookInput.tool_name
+    const toolInput = hookInput.tool_input
+    const risk = classifyRisk(toolName, toolInput)
+    let decision = 'allow'
+    try {
+      decision = await requestPermission?.({ id: randomUUID(), toolName, input: toolInput, risk }) ?? 'allow'
+    } catch { decision = 'deny' } // a broken permission path must fail safe (deny)
+    // On deny, permissionDecisionReason IS what the model receives as the
+    // tool error — make it a real instruction, not an opaque tag.
+    const denied = decision === 'deny'
+    return {
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: denied ? 'deny' : 'allow',
+        permissionDecisionReason: denied
+          ? 'Denied by the user in the ThinkPool room. Do not retry this tool — ask what to do instead.'
+          : 'Approved in the ThinkPool room.',
+      },
+    }
+  }
+
+  const opts = {
+    abortController: ac,
+    permissionMode: 'default',
+    hooks: { PreToolUse: [{ hooks: [preTool] }] },
+  }
+  if (cwd) opts.cwd = cwd
+  if (model) opts.model = model
+  if (resume) opts.resume = resume
+
+  ;(async () => {
+    try {
+      for await (const m of query({ prompt: input.stream, options: opts })) {
+        if (closed) break
+        switch (m.type) {
+          case 'system':
+            if (m.session_id) sessionId = m.session_id
+            emit({ kind: 'system', sessionId, model: m.model || model || null })
+            break
+          case 'assistant':
+            emit({ kind: 'assistant', blocks: simplifyBlocks(m.message?.content) })
+            break
+          case 'user':
+            // tool_result blocks arrive on the user-role echo
+            for (const b of (m.message?.content || [])) {
+              if (b?.type === 'tool_result') {
+                emit({ kind: 'tool_result', toolUseId: b.tool_use_id, content: b.content, isError: !!b.is_error })
+              }
+            }
+            break
+          case 'result':
+            if (m.session_id) sessionId = m.session_id
+            emit({ kind: 'result', subtype: m.subtype, sessionId, costUsd: m.total_cost_usd, usage: m.usage, numTurns: m.num_turns })
+            break
+          default:
+            break
+        }
+      }
+    } catch (e) {
+      if (!closed) emit({ kind: 'error', message: e?.message || String(e) })
+    }
+  })()
+
+  return {
+    sendTurn(text) { if (!closed) input.push(String(text)) },
+    abort() { try { ac.abort() } catch { /* noop */ } },
+    end() { closed = true; input.end(); try { ac.abort() } catch { /* noop */ } },
+    get sessionId() { return sessionId },
+  }
+}

package/devbox/setup-devbox.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# thinkpool devbox — turn an always-plugged-in Mac into a permanent
+# ThinkPool code host (the old-MacBook-on-a-shelf setup, 2026-06-11).
+#
+#   bash setup-devbox.sh <ROOM> [project-dir]
+#
+#   ROOM         fixed room code — thinkpool.io/code?r=<ROOM> becomes the
+#                permanent address you and your partner share
+#   project-dir  the repo the bridge shares (default: current directory)
+#
+# What it does:
+#   1. pmset: never sleep (lid closed included), restart after power loss
+#   2. Remote Login (SSH) on — your emergency way in
+#   3. LaunchAgent com.thinkpool.pair: runs `npx thinkpool-pair@latest
+#      <ROOM> --continue` from the project dir, restarts it forever
+#      (KeepAlive). --continue resumes the latest Claude Code session in
+#      that directory on every restart; harmless for agents without
+#      resume support (they start fresh).
+#
+# What it can NOT do (one-time manual steps, printed at the end):
+#   - Auto-login (System Settings → Users & Groups)
+#   - Tailscale install (recommended)
+#
+# Re-run any time — it rewrites the agent idempotently.
+
+set -euo pipefail
+
+ROOM="${1:?usage: setup-devbox.sh <ROOM> [project-dir]}"
+PROJ="${2:-$PWD}"
+ROOM="$(echo "$ROOM" | tr '[:lower:]' '[:upper:]')"
+PROJ="$(cd "$PROJ" && pwd)"
+PLIST="$HOME/Library/LaunchAgents/com.thinkpool.pair.plist"
+LOG="$HOME/Library/Logs/thinkpool-pair.log"
+
+echo "── thinkpool devbox setup ──"
+echo "   room:    $ROOM"
+echo "   project: $PROJ"
+
+# ── 1. power: never sleep, survive power cuts ───────────────────────────
+echo "── pmset (needs sudo) ──"
+sudo pmset -a sleep 0 disksleep 0 displaysleep 1
+sudo pmset -a disablesleep 1      # lid closed ≠ sleep, no external display needed
+sudo pmset -a autorestart 1       # power cut → boots back up
+sudo pmset -a womp 1 2>/dev/null || true   # wake on LAN, when supported
+
+# ── 2. SSH in case the bridge wedges ────────────────────────────────────
+sudo systemsetup -setremotelogin on >/dev/null 2>&1 || \
+  echo "   (Remote Login refused — enable it in System Settings → Sharing)"
+
+# ── 3. the forever-bridge LaunchAgent ───────────────────────────────────
+# Login shell (-l) so launchd's bare PATH still finds node/npx/claude
+# (nvm, Homebrew, ~/.local/bin — whatever this Mac uses).
+mkdir -p "$HOME/Library/LaunchAgents" "$HOME/Library/Logs"
+cat > "$PLIST" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>            <string>com.thinkpool.pair</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/zsh</string>
+    <string>-l</string>
+    <string>-c</string>
+    <string>exec npx --yes thinkpool-pair@latest $ROOM --continue</string>
+  </array>
+  <key>WorkingDirectory</key> <string>$PROJ</string>
+  <key>RunAtLoad</key>        <true/>
+  <key>KeepAlive</key>        <true/>
+  <key>ThrottleInterval</key> <integer>15</integer>
+  <key>StandardOutPath</key>  <string>$LOG</string>
+  <key>StandardErrorPath</key><string>$LOG</string>
+</dict>
+</plist>
+PLIST
+
+launchctl unload "$PLIST" 2>/dev/null || true
+launchctl load "$PLIST"
+echo "   LaunchAgent loaded — log: $LOG"
+
+# ── done ────────────────────────────────────────────────────────────────
+cat <<EOF
+
+── done. two manual steps remain ──
+  1. System Settings → Users & Groups → automatically log in as this
+     user (the agent runs at login, not at boot, until you do this).
+  2. Recommended: install Tailscale so you can SSH from anywhere.
+
+  permanent room:  https://thinkpool.io/code?r=$ROOM
+  watch the log:   tail -f $LOG
+  stop it:         launchctl unload $PLIST
+
+  battery note: a dead 2017 battery on permanent AC can swell — glance
+  at the lid/trackpad for bulge now and then, or have it removed.
+EOF

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.5.1",
+  "version": "0.6.2",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.173",
     "@supabase/supabase-js": "^2.45.0",
     "node-pty": "^1.2.0-beta.13"
   }