thinkpool-pair 0.7.176 → 0.7.177

package/agent-notify.mjs

@@ -0,0 +1,131 @@
+/* ─────────────────────────────────────────────────────────────
+   bridge/agent-notify.mjs — the PURE decision layer for agent push events.
+
+   The bridge is the only process that knows a turn ended or a permission
+   card went unanswered. It can't call /api/notify-code directly (that
+   endpoint is webhook-secret-gated and this is a published npm package), so
+   it writes a compact `__agent` row into code_messages and lets the existing
+   push_notify_on_code_message trigger fan it out.
+
+   Everything that DECIDES whether to write such a row lives here, with no
+   I/O, so bridge/agent-notify.test.mjs can exercise it without a room, a
+   socket, or a wall clock.
+
+   Spec: docs/specs/2026-07-09-code-notifications-rework.md (Slice 3)
+   ───────────────────────────────────────────────────────────── */
+
+// A turn shorter than this means somebody was almost certainly watching it —
+// pushing "done" 4 seconds after they hit enter is noise, not news.
+export const DEFAULT_MIN_TURN_MS = 30_000
+
+// How long a permission card may sit unanswered before we assume nobody is
+// looking at the room and push. Short enough to be useful, long enough that
+// the common case (you're right there, you click it) never fires.
+export const DEFAULT_PERM_GRACE_MS = 20_000
+
+// Push copy is a banner, not a transcript.
+export const SUMMARY_MAX = 200
+
+/* A lane is USER-FACING when a human opened it and is waiting on it.
+   - spawnedBy: a Dispatch worker lane an agent fanned out. Its owner is
+     another agent; the human never asked for it directly.
+   - flowTaskKey: a Flow slice lane. Same reasoning — the conductor collects
+     it, and a 12-lane flow would fan 12 banners at one person.
+   Both run in inherited/bypass modes almost always, so they also rarely
+   raise permission cards. The conductor lane itself (flowSessionId but no
+   flowTaskKey) IS user-facing — that's the one a human is watching. */
+export function isUserFacingLane(entry) {
+  if (!entry) return false
+  return !entry.spawnedBy && !entry.flowTaskKey
+}
+
+/* Collapse whitespace, clip, ellipsize. Never throws on non-strings. */
+export function clipSummary(text, max = SUMMARY_MAX) {
+  if (text == null) return ''
+  const s = String(text).replace(/\s+/g, ' ').trim()
+  if (s.length <= max) return s
+  return s.slice(0, max).replace(/\s+\S*$/, '').trimEnd() + '…'
+}
+
+/* Should a settled turn produce a `turn-done` event row?
+
+   No when: the lane isn't user-facing · the user pressed Stop (subtype
+   'aborted' — they know it's over, they're the one who ended it) · the turn
+   was short enough that somebody was plainly watching · we never saw the
+   turn start (startedAt null → a stray `error` event outside any turn, e.g.
+   the SDK-regression warning emitted at init).
+
+   `error` turns DO notify — with the same neutral copy as a success. Max's
+   call: "the agent stopped" is the news; the reason is in the room. */
+export function shouldNotifyTurnDone({ entry, subtype, startedAt, now, minTurnMs = DEFAULT_MIN_TURN_MS }) {
+  if (!isUserFacingLane(entry)) return false
+  if (subtype === 'aborted') return false
+  if (!startedAt) return false
+  if (!Number.isFinite(now)) return false
+  return (now - startedAt) >= minTurnMs
+}
+
+/* The one-line "what is it asking me" for a permission card.
+   AskUserQuestion cards carry `questions`; ordinary tool cards degrade to
+   `<ToolName> <first meaningful arg>`, matching the local stderr line. */
+export function permissionSummary(payload) {
+  const p = payload || {}
+  const qs = Array.isArray(p.questions) ? p.questions.map(q => q?.question).filter(Boolean) : []
+  if (qs.length) return clipSummary(qs.join(' / '))
+  if (p.risk === 'plan') return clipSummary(p.plan ? `Plan ready: ${p.plan}` : 'A plan is ready for review')
+  const i = p.input
+  const arg = i && (i.command || i.file_path || i.path || i.pattern || i.url || i.query || i.description)
+  const name = p.toolName || 'A tool'
+  return clipSummary(arg ? `${name} ${arg}` : name)
+}
+
+/* Per-session permission-card notifier.
+
+   arm(id, payload)  — a card was raised. Start the grace timer.
+   resolve(id)       — the card was answered (human click, mode-flip
+                       auto-approval, or a drain-to-deny). If its timer had
+                       already FIRED we pushed a banner, so retract it.
+   clearAll()        — turn ended / session died. Every outstanding card is
+                       dead; retract anything we announced.
+
+   Timers are injected so the unit test drives them synchronously. onFire /
+   onRetract are fire-and-forget (they end up as REST inserts); a throw in
+   either must never take the bridge down. */
+export function createPermNotifier({
+  graceMs = DEFAULT_PERM_GRACE_MS,
+  onFire = () => {},
+  onRetract = () => {},
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+} = {}) {
+  const cards = new Map()   // id → { timer, fired, payload }
+  const safe = (fn, id, payload) => { try { fn(id, payload) } catch { /* never break the turn */ } }
+
+  const settle = (id) => {
+    const rec = cards.get(id)
+    if (!rec) return
+    if (rec.timer) { try { clearTimer(rec.timer) } catch { /* noop */ } }
+    cards.delete(id)
+    if (rec.fired) safe(onRetract, id, rec.payload)
+  }
+
+  return {
+    arm(id, payload) {
+      if (!id || cards.has(id)) return
+      const rec = { timer: null, fired: false, payload }
+      rec.timer = setTimer(() => {
+        rec.timer = null
+        rec.fired = true
+        safe(onFire, id, payload)
+      }, graceMs)
+      // Never hold the process open on a permission timer.
+      try { rec.timer?.unref?.() } catch { /* not a node timer (test double) */ }
+      cards.set(id, rec)
+    },
+    resolve: settle,
+    clearAll() { for (const id of [...cards.keys()]) settle(id) },
+    // test/debug introspection only
+    size: () => cards.size,
+    fired: (id) => !!cards.get(id)?.fired,
+  }
+}

package/bridge.mjs

@@ -39,6 +39,9 @@ import { randomUUID } from 'node:crypto'
 import { createClient } from '@supabase/supabase-js'
 import { serveDecision, fetchServeRow, refusalMessage, gateFailAction } from './serve-consent.mjs'
 import { reapTerminalRow as _reapTerminalRow } from './reap-terminal.mjs'
+// Slice 3 — the pure decision layer for agent push events (turn-done / needs-input).
+// Unit-tested in bridge/agent-notify.test.mjs; everything with I/O stays here.
+import { createPermNotifier, shouldNotifyTurnDone, permissionSummary, clipSummary, isUserFacingLane, DEFAULT_MIN_TURN_MS } from './agent-notify.mjs'
 // resolveProviderEnv(id) → {ANTHROPIC_BASE_URL,ANTHROPIC_AUTH_TOKEN,ANTHROPIC_MODEL} for a
 // registered custom provider, or null for the built-in/unknown (leave the default env intact).
 // Multi-provider BYOK slice 1: a lane spawned with a `provider` id runs on that endpoint.
@@ -763,6 +766,46 @@ async function budgetRpc (fn, args) {
   const t = await r.text()
   return t ? JSON.parse(t) : null
 }
+
+// ── Agent push events — spec docs/specs/2026-07-09-code-notifications-rework.md (Slice 3).
+// The bridge is the only process that knows a turn ended or a permission card went
+// unanswered, and it CANNOT call /api/notify-code (webhook-secret-gated; this is a
+// published npm package). So it writes a compact `__agent` row into code_messages with
+// the SAME authed REST path budgetRpc uses; the existing push_notify_on_code_message
+// trigger fans it out and api/notify-code.js routes on payload.__agent.
+//
+// Durable by construction: the row is also the transport-neutral event log the iPhone
+// sender will read, and it feeds get_code_unread_counts for free.
+//
+// Fire-and-forget in the strictest sense — an anon bridge (no codeAuthToken/uid), a
+// dead network, or a 4xx must never surface in the turn. TP_AGENT_NOTIFY_OFF=1 kills
+// the whole path. The web client filters `ae:` rows out of its seed/replay (Slice 2),
+// so an old client paired with a new bridge renders nothing new.
+const AGENT_NOTIFY_OFF = process.env.TP_AGENT_NOTIFY_OFF === '1'
+const MIN_TURN_MS = Number(process.env.TP_NOTIFY_MIN_TURN_MS) > 0
+  ? Number(process.env.TP_NOTIFY_MIN_TURN_MS) : DEFAULT_MIN_TURN_MS
+function persistAgentEvent (payload) {
+  if (AGENT_NOTIFY_OFF || !codeAuthToken || !myServeUid || !room) return
+  const row = {
+    id: `ae:${randomUUID()}`,
+    session_code: room,
+    author_id: myServeUid,
+    payload: { __agent: true, ts: Date.now(), ...payload },
+  }
+  fetch(`${SUPABASE_URL}/rest/v1/code_messages`, {
+    method: 'POST',
+    headers: {
+      apikey: SUPABASE_ANON,
+      Authorization: `Bearer ${codeAuthToken}`,
+      'Content-Type': 'application/json',
+      Prefer: 'return=minimal',
+    },
+    body: JSON.stringify(row),
+  }).then((r) => {
+    if (!r.ok && process.env.TP_DEBUG) process.stderr.write(`\n  ◆ agent-event insert ${r.status}\n`)
+  }).catch(() => { /* best-effort — a missed banner is not worth a stack trace */ })
+}
+
 // Fire-and-forget: fold a completed turn's output tokens into the room's durable monthly
 // ledger. output_tokens = the billed reasoning+output spend the indicator already tracks.
 function recordRoomSpend (tokens) {
@@ -1542,6 +1585,13 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
     // order (not readdir/filesystem order). Legacy recs (no openedAt) derive it from the
     // first transcript event ts, so even the first post-fix restart is ordered right.
     openedAt: openedAt || (Array.isArray(log) ? (log.find((e) => e?.ts)?.ts || 0) : 0) || Date.now() }
+  // Slice 3 — a permission card left unanswered past the grace window pushes
+  // "<lane> — needs you: <what>"; answering it anywhere retracts the banner
+  // everywhere. Worker/flow lanes are excluded at arm() time (isUserFacingLane).
+  entry.permNotifier = createPermNotifier({
+    onFire:    (_cardId, summary) => persistAgentEvent({ kind: 'needs-input',    term: id, termName: termNames[id] || null, summary }),
+    onRetract: (_cardId)          => persistAgentEvent({ kind: 'needs-resolved', term: id, termName: termNames[id] || null }),
+  })
   // C1 (RT-2): per-term contiguous seq counter. Seeded from the restored log's max
   // so a bridge restart resumes ABOVE every persisted seq — fresh events never reuse
   // an old seq, which is what keeps the between-turns restart dup-free (see
@@ -2135,8 +2185,11 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
       // roster broadcast (delivered to every subscriber) instead of sniffing the live
       // code-event stream a passive dashboard channel misses. Covers every turn path
       // (normal, spawn, flow lane, cross-room) since they all flow through onEvent.
+      // The RISING edge is also where a turn's wall clock starts — the only place the
+      // bridge sees "this lane just began working". `result`/`error` reads it to decide
+      // whether the turn was long enough that nobody was watching (Slice 3).
       { const busyNow = entry.session?.turnActive ?? false
-        if (busyNow !== entry._busyAnn) { entry._busyAnn = busyNow; announce() } }
+        if (busyNow !== entry._busyAnn) { if (busyNow) entry._turnStart = Date.now(); entry._busyAnn = busyNow; announce() } }
       // Capture this session's current MODEL (resolved full id, with version — from
       // system/result `model` or usage `ctx.model`) and the SDK's supported-model
       // LIST (from the `models` event) so the announce carries them to EVERY device.
@@ -2247,6 +2300,30 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
         bcast('code-event', { term: id, evt: { kind: 'compact', status: 'done', ts: Date.now() } })
         entry.compactBy = null
       }
+      // ── Slice 3: the turn settled. Two things happen, in this order.
+      //   1. Every outstanding permission card on this lane is now dead (the SDK
+      //      won't ask again for a turn that ended) — clearAll retracts any
+      //      "needs you" banner we already pushed. Do this even for aborted turns
+      //      and non-user-facing lanes: a stale card can never fire later.
+      //   2. If the turn ran long enough that nobody was plausibly watching, and
+      //      the lane is one a human opened, and they didn't press Stop — write a
+      //      `turn-done` event row. An `error` turn uses the same neutral copy.
+      // _turnStart is cleared unconditionally so a stray post-settle event can't
+      // re-notify off a stale stamp.
+      if (evt.kind === 'result' || evt.kind === 'error') {
+        const startedAt = entry._turnStart
+        entry._turnStart = null
+        entry.permNotifier?.clearAll()
+        if (shouldNotifyTurnDone({ entry, subtype: evt.subtype, startedAt, now: Date.now(), minTurnMs: MIN_TURN_MS })) {
+          persistAgentEvent({
+            kind: 'turn-done',
+            term: id,
+            termName: termNames[id] || null,
+            summary: clipSummary(evt.kind === 'result' ? evt.resultText : evt.message),
+            subtype: evt.subtype || (evt.kind === 'error' ? 'error' : null),
+          })
+        }
+      }
       // Single tail: stamp into the log (transcript kinds only), broadcast live,
       // print locally, persist. Shared so a deferred image event re-enters it once
       // its base64 has been lifted to a Storage path (see deferImageEvent).
@@ -2281,6 +2358,13 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
       const payload = { term: id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk, plan: req.plan, questions: req.questions }
       entry.pending.set(req.id, { resolve, payload })
       bcast('code-perm-req', payload)
+      // Slice 3 — arm the grace timer. Fires a "needs you" push only if the card is
+      // STILL unanswered 20s from now (you're not in the room). Every resolve path —
+      // the code-perm broadcast, drainPending, and the bypass/acceptEdits mode-flip
+      // auto-approvals — calls permNotifier.resolve(id), which retracts the banner
+      // if it had fired. Worker + flow-slice lanes are skipped: their cards belong to
+      // an agent's fan-out, and a 12-lane flow would fan 12 banners at one person.
+      if (isUserFacingLane(entry)) entry.permNotifier?.arm(req.id, permissionSummary(payload))
       process.stderr.write(req.risk === 'plan'
         ? `\n  ${A.mag}◆ plan ready — approve in the room.${A.rst}\n`
         : req.risk === 'ask'
@@ -2310,6 +2394,8 @@ function drainPending(s) {
   if (!s?.pending) return
   for (const [, p] of s.pending) { try { p.resolve('deny') } catch { /* noop */ } }
   s.pending.clear()
+  // Every card just died → retract any "needs you" banner they raised (Slice 3).
+  s.permNotifier?.clearAll()
 }
 
 // Switching a terminal to bypassPermissions must RETROACTIVELY clear the cards the
@@ -2329,6 +2415,7 @@ function allowPending(s) {
     if (p?.payload?.risk === 'plan' || p?.payload?.risk === 'ask') continue
     try { p.resolve('allow') } catch { /* noop */ }
     s.pending.delete(key)
+    s.permNotifier?.resolve(key)   // auto-approved → retract the "needs you" banner
   }
 }
 
@@ -2347,6 +2434,7 @@ function acceptEditsPending(s) {
     if (!ACCEPT_EDIT_TOOLS.has(tn)) continue
     try { p.resolve('allow') } catch { /* noop */ }
     s.pending.delete(key)
+    s.permNotifier?.resolve(key)   // auto-approved → retract the "needs you" banner
   }
 }
 
@@ -2742,7 +2830,9 @@ channel
     const p = s && payload.id && s.pending.get(payload.id)
     // Pass the raw decision through — normal tools use allow/deny, plan cards
     // use run/accept/keep (claude-session interprets). Default deny on missing.
-    if (p) { s.pending.delete(payload.id); p.resolve(payload.decision || 'deny') }
+    // Answered from a device → retract the "needs you" banner on every OTHER device
+    // (permNotifier.resolve is a no-op unless its grace timer already fired).
+    if (p) { s.pending.delete(payload.id); s.permNotifier?.resolve(payload.id); p.resolve(payload.decision || 'deny') }
   })
   .on('broadcast', { event: 'code-abort' }, ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)

package/claude-session.mjs

@@ -978,7 +978,13 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
               }
               if (best) curModel = best
             }
-            emit({ kind: 'result', subtype: m.subtype, sessionId, model: curModel, costUsd: m.total_cost_usd, usage: m.usage, numTurns: m.num_turns, durationMs: m.duration_ms ?? null, denials: Array.isArray(m.permission_denials) ? m.permission_denials.length : 0 })
+            // resultText: the SDK's final assistant text, clipped. The bridge folds it
+            // into the `turn-done` push body ("<lane> — done: <summary>") so a banner
+            // says what happened, not just that something did. Clipped + whitespace-
+            // collapsed here so neither the broadcast frame nor the persisted log grows
+            // by a full turn's prose. Absent on aborted/error results — nothing to say.
+            { const rt = typeof m.result === 'string' ? m.result.replace(/\s+/g, ' ').trim().slice(0, 200) : ''
+              emit({ kind: 'result', subtype: m.subtype, sessionId, model: curModel, costUsd: m.total_cost_usd, usage: m.usage, numTurns: m.num_turns, durationMs: m.duration_ms ?? null, denials: Array.isArray(m.permission_denials) ? m.permission_denials.length : 0, resultText: rt || null }) }
             // Arm the Haiku fallback: if Claude's own prompt_suggestion doesn't arrive within
             // the window, generate one from the last assistant reply. (Skip aborted turns.)
             if (sugTimer) clearTimeout(sugTimer)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.176",
+  "version": "0.7.177",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "claude-session.mjs",
     "turn-stall.mjs",
     "update-gate.mjs",
+    "agent-notify.mjs",
     "event-id.mjs",
     "recap.mjs",
     "transcript-sanitize.mjs",