thinkpool-pair 0.2.0 → 0.3.4

package/README.md

@@ -5,27 +5,37 @@ room, live. Both people see the real terminal stream and can both drive it —
 no copy/paste.
 
 > A web page can't read your terminal directly (browser security). This tiny
-> helper is the bridge: it runs the CLI in a PTY and streams it to the room.
+> helper is the bridge: it runs CLIs in PTYs and streams them to the room.
 
 ## Run it (one command)
 
 ```bash
 cd bridge && npm i        # one-time (builds node-pty — needs Xcode CLT / build-essential)
-node bridge.mjs <ROOM>    # launches `claude`, shared into room <ROOM>
+node bridge.mjs <ROOM>    # picks an installed agent, shared into room <ROOM>
 ```
 
 - `<ROOM>` is the 5-char room code from the ThinkPool Code web UI (`/code`).
-- Share any other CLI: `node bridge.mjs <ROOM> -- aider`  /  `… -- bash`.
-- Use the terminal exactly as normal — it's seamless locally, and every byte
-  mirrors to the web for your partner. Prompts/keys typed in the web come back
-  into your session.
+- Share a specific CLI: `node bridge.mjs <ROOM> -- aider`  /  `… -- bash`.
+- Pure relay (no local terminal): `node bridge.mjs <ROOM> --headless`.
+
+Your first agent runs **attached** — use it exactly like your normal terminal,
+every byte mirrors to the web. The web's **"+ New terminal"** spawns additional
+**headless** terminals here (same directory, same env), driven entirely from
+the room. One bridge, many terminals.
 
 ## How it works
 
 `bridge.mjs` ⇄ **Supabase realtime** (`tpcode:<ROOM>`) ⇄ web `xterm`:
-- `pty-out` — terminal bytes (base64) → both web clients render them.
-- `pty-in`  — keystrokes/prompts from the web → written to your PTY.
-- `resize`  — web viewport size → `term.resize`.
+- `bridge` — announce: installed agents + live terminals.
+- `pty-out` — terminal bytes (base64, per-terminal) → web clients render them.
+- `pty-in` — keystrokes/prompts from the web → written to that terminal's PTY.
+- `term-open` / `term-close` / `term-exit` — web-driven terminal lifecycle.
+- `replay-request` / `pty-replay` — each terminal keeps a rolling ~120 KB
+  scrollback buffer; joining/reloading clients get it replayed, so the room
+  never opens blank while the bridge is up. **Nothing is stored server-side** —
+  history lives exactly as long as the bridge runs.
+- `resize` — web viewport size → headless PTYs only (the attached terminal
+  follows your own TTY).
 
 Public anon creds are embedded (the same ones the web app ships). Override with
 `TP_SUPABASE_URL` / `TP_SUPABASE_ANON` if needed. Set `TP_NAME` to label yourself.

package/bridge.mjs

@@ -3,20 +3,26 @@
    thinkpool-pair — share your local Claude (or any CLI) into a
    ThinkPool Code room, live. ONE command, seamless:
 
-     npx thinkpool-pair <ROOM>            # auto-detects your agents, pick one
-     npx thinkpool-pair <ROOM> -- <cmd…>  # share a specific CLI (skip the picker)
-
-   It spawns the CLI in a PTY so you use it exactly like your normal
-   terminal — and every byte streams to the room over Supabase realtime
-   (the relay), while prompts/keys from the web come back into the PTY.
-   No copy/paste. A web page can't read your terminal directly — this
-   tiny helper is the bridge.
+     npx thinkpool-pair <ROOM>             # auto-detects your agents, pick one
+     npx thinkpool-pair <ROOM> -- <cmd…>   # share a specific CLI (skip the picker)
+     npx thinkpool-pair <ROOM> --headless  # pure relay — terminals open from the web
+
+   v0.3 — multi-terminal. The bridge is your machine's presence in the
+   room; terminals are things you open inside it. Your first agent runs
+   ATTACHED (your own terminal, exactly as before). The web's
+   "+ New terminal" spawns additional HEADLESS PTYs here — same cwd,
+   same env — and every terminal streams to the room over Supabase
+   realtime. Each terminal keeps a rolling scrollback buffer that
+   replays to anyone who joins or reloads, so the room never opens
+   blank while the bridge is up. Nothing is stored server-side.
+   Spec: docs/specs/2026-06-10-code-multi-terminal.md
    ───────────────────────────────────────────────────────────── */
 
 import os from 'node:os'
 import fs from 'node:fs'
 import path from 'node:path'
 import readline from 'node:readline'
+import { randomUUID } from 'node:crypto'
 import { createClient } from '@supabase/supabase-js'
 
 // Public client creds (the same anon values the web app ships — safe to embed).
@@ -24,6 +30,10 @@ import { createClient } from '@supabase/supabase-js'
 const SUPABASE_URL  = process.env.TP_SUPABASE_URL  || 'https://daytvtakmlixpfbbqzjd.supabase.co'
 const SUPABASE_ANON = process.env.TP_SUPABASE_ANON || 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImRheXR2dGFrbWxpeHBmYmJxempkIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzgwNTMxNzEsImV4cCI6MjA5MzYyOTE3MX0.zYmz8bHUNEY4STUr2JuXChAsKwxNwkwFHe1Hd0Betqo'
 
+// Per-terminal rolling scrollback (raw chars). Replayed to joining clients.
+// Kept comfortably under realtime payload limits once base64'd.
+const SCROLLBACK_MAX = 120_000
+
 // node-pty is a native module — loaded lazily so a friendly message shows
 // if it isn't built yet.
 let pty
@@ -82,24 +92,32 @@ const pickAgent = (installed) => new Promise((resolve) => {
 
 const argv = process.argv.slice(2)
 const room = (argv[0] || '').toUpperCase().trim()
-if (!room) { console.error('usage: npx thinkpool-pair <ROOM> [-- <command…>]'); process.exit(1) }
+if (!room || room.startsWith('-')) { console.error('usage: npx thinkpool-pair <ROOM> [--headless] [-- <command…>]'); process.exit(1) }
+const headless = argv.includes('--headless')
+const installedAgents = KNOWN_AGENTS.filter(a => onPath(a.cmd))
 const dashIdx = argv.indexOf('--')
-let cmd, cmdArgs
+let attachedCmd = null, attachedArgs = []
 if (dashIdx >= 0) {
-  // Explicit override: `-- <cmd> [args…]` skips the picker.
-  ;[cmd, ...cmdArgs] = argv.slice(dashIdx + 1)
-} else {
-  // Auto-detect: probe the known agents, then pick (or auto-pick a lone match).
-  const installed = KNOWN_AGENTS.filter(a => onPath(a.cmd))
-  if (installed.length === 0) {
+  ;[attachedCmd, ...attachedArgs] = argv.slice(dashIdx + 1)
+} else if (!headless) {
+  if (installedAgents.length === 0) {
     console.error(`\n  No known coding-agent CLI found on your PATH.\n  Install one (claude / codex / gemini / aider / cursor-agent / opencode …)\n  or share a specific command:  npx thinkpool-pair ${room} -- <your-command>\n`)
     process.exit(1)
   }
-  cmd = await pickAgent(installed)
-  cmdArgs = []
+  attachedCmd = await pickAgent(installedAgents)
 }
 const name = process.env.TP_NAME || os.userInfo().username || 'host'
 
+// Repo awareness — the room shows which project this machine is sharing.
+// Cheap reads, no subprocess: directory name + .git/HEAD.
+const cwd = process.cwd()
+const repoLabel = path.basename(cwd)
+let branch = null
+try {
+  const head = fs.readFileSync(path.join(cwd, '.git', 'HEAD'), 'utf8').trim()
+  branch = head.startsWith('ref:') ? head.split('/').pop() : head.slice(0, 7)
+} catch { /* not a git repo — fine */ }
+
 const supabase = createClient(SUPABASE_URL, SUPABASE_ANON, {
   realtime: { params: { eventsPerSecond: 60 } },
 })
@@ -107,52 +125,163 @@ const channel = supabase.channel(`tpcode:${room}`, {
   config: { broadcast: { self: false }, presence: { key: `bridge:${name}` } },
 })
 
-// ── spawn the CLI in a PTY; the host uses it like a normal terminal ──
-const cols = process.stdout.columns || 100
-const rows = process.stdout.rows || 30
-const term = pty.spawn(cmd || 'claude', cmdArgs, {
-  name: 'xterm-256color', cols, rows, cwd: process.cwd(), env: process.env,
+// ── terminal registry ──────────────────────────────────────────────
+// id → { term (pty), cmd, attached, scrollback, buf }
+const terms = new Map()
+let attachedId = null
+let shuttingDown = false
+
+const announce = () =>
+  channel.send({ type: 'broadcast', event: 'bridge', payload: {
+    v: 2, name, repo: repoLabel, branch,
+    agents: installedAgents,
+    // 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 })),
+  } })
+
+// One flush timer batches every terminal's pending bytes (~35ms cadence).
+const flushAll = () => {
+  for (const [id, t] of terms) {
+    if (!t.buf) continue
+    const b64 = Buffer.from(t.buf, 'utf8').toString('base64')
+    t.buf = ''
+    channel.send({ type: 'broadcast', event: 'pty-out', payload: { term: id, b64 } })
+  }
+}
+const flushTimer = setInterval(flushAll, 35)
+
+// ── shared-PTY geometry ───────────────────────────────────────────
+// The room's view is the product: the shared PTY never goes below
+// FLOOR_COLS×FLOOR_ROWS, no matter what the host does to their local
+// window. Below the floor the HOST's rendering wraps oddly (the agent
+// keeps drawing for the floor width) — the pair's view stays clean.
+// Pin an exact size with TP_COLS/TP_ROWS (disables host-following).
+const FLOOR_COLS = 100, FLOOR_ROWS = 28
+const PIN_COLS = parseInt(process.env.TP_COLS, 10) || null
+const PIN_ROWS = parseInt(process.env.TP_ROWS, 10) || null
+const attachedDims = () => ({
+  cols: PIN_COLS || Math.max(process.stdout.columns || FLOOR_COLS, FLOOR_COLS),
+  rows: PIN_ROWS || Math.max(process.stdout.rows || FLOOR_ROWS, FLOOR_ROWS),
 })
 
-// host's own keystrokes → the CLI (so it's seamless locally too)
-if (process.stdin.isTTY) process.stdin.setRawMode(true)
-process.stdin.resume()
-process.stdin.on('data', d => term.write(d.toString('utf8')))
-
-// CLI output → host's screen + batched out to the room
-let buf = ''
-term.onData(d => { process.stdout.write(d); buf += d })
-const flush = () => {
-  if (!buf) return
-  const b64 = Buffer.from(buf, 'utf8').toString('base64'); buf = ''
-  channel.send({ type: 'broadcast', event: 'pty-out', payload: { b64 } })
+function openTerm({ id, cmd, args = [], attached = false, cols, rows }) {
+  if (terms.has(id)) return
+  const ad = attached ? attachedDims() : null
+  const term = pty.spawn(cmd, args, {
+    name: 'xterm-256color',
+    cols: cols || (attached ? ad.cols : 100),
+    rows: rows || (attached ? ad.rows : 30),
+    cwd: process.cwd(), env: process.env,
+  })
+  const entry = { term, cmd, attached, scrollback: '', buf: '' }
+  terms.set(id, entry)
+  if (attached) attachedId = id
+  term.onData(d => {
+    if (attached) process.stdout.write(d)
+    entry.buf += d
+    entry.scrollback = (entry.scrollback + d).slice(-SCROLLBACK_MAX)
+  })
+  term.onExit(() => {
+    terms.delete(id)
+    if (id === attachedId) { attachedId = null; detachLocal() }
+    if (shuttingDown) return
+    try { channel.send({ type: 'broadcast', event: 'term-exit', payload: { id } }) } catch { /* noop */ }
+    announce()
+    if (terms.size === 0 && !headless) shutdown()
+    else process.stderr.write(`\n  ◇ terminal "${cmd}" ended — still relaying ${terms.size} terminal(s). Ctrl-C to stop.\n`)
+  })
+  announce()
+  return entry
 }
-const flushTimer = setInterval(flush, 35)
 
-const announce = () =>
-  channel.send({ type: 'broadcast', event: 'bridge', payload: { name, cmd: cmd || 'claude', cols, rows } })
+// 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 = () => {
+  try { if (process.stdin.isTTY) process.stdin.setRawMode(false) } catch { /* noop */ }
+}
+
+// host's own keystrokes → the attached CLI (so it's seamless locally too)
+if (attachedCmd && process.stdin.isTTY) process.stdin.setRawMode(true)
+process.stdin.resume()
+process.stdin.on('data', d => {
+  const t = attachedId && terms.get(attachedId)
+  if (t) t.term.write(d.toString('utf8'))
+  else if (d.includes(3)) shutdown()   // Ctrl-C once detached/headless
+})
+// attached terminal follows the host's TTY size — but never below the
+// floor, and never at all when pinned. Re-announce so viewers rescale.
+process.stdout.on('resize', () => {
+  const t = attachedId && terms.get(attachedId)
+  if (!t) return
+  const { cols, rows } = attachedDims()
+  if (t.term.cols === cols && t.term.rows === rows) return
+  try { t.term.resize(cols, rows); announce() } catch { /* noop */ }
+})
 
 channel
-  .on('broadcast', { event: 'pty-in' }, ({ payload }) => { if (payload?.data) term.write(payload.data) })
+  .on('broadcast', { event: 'pty-in' }, ({ payload }) => {
+    if (!payload?.data) return
+    const t = terms.get(payload.term) || (payload.term == null && attachedId ? terms.get(attachedId) : null)
+    if (t) t.term.write(payload.data)
+  })
   .on('broadcast', { event: 'resize' }, ({ payload }) => {
-    if (payload?.cols && payload?.rows) { try { term.resize(payload.cols, payload.rows) } catch { /* noop */ } }
+    // headless terms are web-sized (last writer wins); the attached term is
+    // host-sized. Floor at 80 cols — one narrow phone viewer must not reflow
+    // the shared PTY into a 40-col column for everyone (2026-06-10 bug).
+    if (!payload?.cols || !payload?.rows) return
+    const t = terms.get(payload.term)
+    if (t && !t.attached) { try { t.term.resize(Math.max(payload.cols, 80), Math.max(payload.rows, 20)); announce() } catch { /* noop */ } }
+  })
+  .on('broadcast', { event: 'term-open' }, ({ payload }) => {
+    if (!payload?.id || !payload?.cmd) return
+    // Multi-bridge rooms: a targeted open is for ONE machine. Untargeted
+    // opens (older web) are taken by whoever hears them — the solo case.
+    if (payload.host && payload.host !== name) return
+    openTerm({ id: payload.id, cmd: payload.cmd })
+    process.stderr.write(`\n  ◆ web opened a "${payload.cmd}" terminal (headless).\n`)
+  })
+  .on('broadcast', { event: 'term-close' }, ({ payload }) => {
+    const t = payload?.id && terms.get(payload.id)
+    if (t && !t.attached) { try { t.term.kill() } catch { /* noop */ } }
+  })
+  .on('broadcast', { event: 'replay-request' }, ({ payload }) => {
+    // Flush pending bytes first so the replay is complete up to "now"; both
+    // ride the same ordered socket, so the client sees replay-then-live.
+    flushAll()
+    for (const [id, t] of terms) {
+      if (!t.scrollback) continue
+      channel.send({ type: 'broadcast', event: 'pty-replay', payload: {
+        to: payload?.to ?? null, term: id,
+        b64: Buffer.from(t.scrollback, 'utf8').toString('base64'),
+      } })
+    }
+    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 })
       announce()
-      process.stderr.write(`\n  ◆ thinkpool — sharing "${cmd || 'claude'}" into room ${room}.  Open the web UI and you're both in.\n\n`)
+      process.stderr.write(headless
+        ? `\n  ◆ thinkpool — relaying room ${room} (headless). Open terminals from the web UI.\n\n`
+        : `\n  ◆ thinkpool — sharing "${attachedCmd}" into room ${room}.  Open the web UI and you're both in.\n\n`)
     }
   })
 
-const shutdown = () => {
+function shutdown() {
+  if (shuttingDown) return
+  shuttingDown = true
   clearInterval(flushTimer)
-  try { channel.send({ type: 'broadcast', event: 'pty-out', payload: { b64: Buffer.from('\r\n[ shared session ended ]\r\n', 'utf8').toString('base64') } }) } catch { /* noop */ }
+  try {
+    const bye = Buffer.from('\r\n[ shared session ended ]\r\n', 'utf8').toString('base64')
+    for (const id of terms.keys()) channel.send({ type: 'broadcast', event: 'pty-out', payload: { term: id, b64: bye } })
+  } catch { /* noop */ }
   try { supabase.removeChannel(channel) } catch { /* noop */ }
-  try { term.kill() } catch { /* noop */ }
+  for (const t of terms.values()) { try { t.term.kill() } catch { /* noop */ } }
+  detachLocal()
   process.exit(0)
 }
-term.onExit(shutdown)
 process.on('SIGINT', shutdown)
 process.on('SIGTERM', shutdown)

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.2.0",
+  "version": "0.3.4",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
-  "bin": "bridge.mjs",
+  "bin": { "thinkpool-pair": "bridge.mjs" },
   "engines": {
     "node": ">=18"
   },