heyspex 0.1.0

package/vendor/heyspex-mcp/capture-channel.mjs

@@ -0,0 +1,577 @@
+// capture-channel.mjs — MCP Channels push from console capture sessions.
+//
+// Consumes console's per-session SSE relay
+// (spex-console/src/app/api/capture/sessions/<id>/events) and emits
+// `notifications/claude/channel` events into the Claude Code session so the
+// agent reacts to new user_quotes in real time.
+//
+// Owning epic: [[HS-EPIC-QXJ3-modal-agent-handshake-mcp-channels-push-]].
+// Sibling tasks: HS-TASK-72SI (capability), HS-TASK-HHEY (this file), HS-TASK-19VY (fs.watch).
+//
+// Channels reference: https://code.claude.com/docs/en/channels-reference
+
+import { existsSync, watch as fsWatch } from 'node:fs';
+import { basename as pathBasename, dirname, join } from 'node:path';
+import { loadCaptureFocus, captureFocusPath } from './capture-focus.mjs';
+import { parseSpecId } from './spec-id-lib.mjs';
+
+// Exponential reconnect backoff (ms). Capped at 30s; jittered ±50% on use.
+const RECONNECT_DELAYS_MS = [1000, 2000, 4000, 8000, 16000, 30000];
+
+// Give-up cap for TRANSIENT failures (5xx / network). A terminal 404/410 stops
+// immediately regardless — see supervisor(). Without this cap a wedged console
+// would spin the watcher forever (HS-EPIC-HEAL: same bug class as the console
+// zombie-SSE / companion long-poll, fixed here for the MCP capture channel).
+const MAX_TRANSIENT_ATTEMPTS = 10;
+
+// Pin-file fs.watch debounce — Windows fires `change` twice per save.
+const PIN_WATCH_DEBOUNCE_MS = 100;
+
+/**
+ * Sleep for `ms` milliseconds, abortable via signal.
+ *
+ * @param {number} ms
+ * @param {AbortSignal} [signal]
+ */
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error('aborted'));
+      return;
+    }
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(t);
+      reject(signal.reason ?? new Error('aborted'));
+    }, { once: true });
+  });
+}
+
+function isAbortError(err) {
+  return err?.name === 'AbortError' || /aborted/i.test(err?.message ?? '');
+}
+
+/**
+ * Derive the console session id from a focus pin.
+ *
+ * The focus pin carries `spec_path` (relative to vault root). Sessions in
+ * `capture_sessions` are keyed by their HS-CAP id, which is also the file's
+ * basename prefix (`HS-CAP-XXXX-<slug>.md`). Pull the id from the path.
+ *
+ * @param {{ spec_path?: string }} focus
+ * @returns {string | null}
+ */
+function deriveSessionIdFromFocus(focus) {
+  if (!focus?.spec_path) return null;
+  // Dual-read: the basename prefix is the capture's bare id in EITHER ordering —
+  // type-first HS-CAP-XXXX or family-first HS-XXXX-CAP ([[HS-EPIC-DLE3]]). Parse
+  // it and return the bare id in its on-disk ordering (the session key matches
+  // the basename prefix).
+  const base = pathBasename(String(focus.spec_path).replace(/\\/g, '/')).replace(/\.md$/i, '');
+  const p = parseSpecId(base);
+  if (!p || p.typeLabel !== 'CAP') return null;
+  // Era 3 (file-key-first): the basename prefix — and the stored `id:` — is the
+  // bare file key. The old two-way branch fell through to `HS-CAP-<family>`,
+  // a session key shared by every sibling capture in the family.
+  if (p.era === 3 && p.fileKey) return `HS-${p.fileKey}`;
+  return p.ordering === 'family-first'
+    ? `HS-${p.familyKey}-CAP`
+    : `HS-CAP-${p.familyKey}`;
+}
+
+/**
+ * Extract `at` timestamps from a user_quotes array. Used for dedup.
+ *
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+function extractQuoteAts(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((q) => (q && typeof q === 'object' && typeof q.at === 'string' ? q.at : null))
+    .filter((at) => at != null);
+}
+
+/**
+ * Parse a single SSE event block (split by blank line in the source stream).
+ * Returns { event, data } or null if malformed.
+ *
+ * SSE wire format spec:
+ *   - `event: <name>\n`
+ *   - `data: <json>\n` (possibly multi-line; concatenated with `\n`)
+ *   - `id: <id>\n` (optional)
+ *   - `: <comment>\n` (heartbeat — ignored at parse layer)
+ *   - blank line terminates the event
+ */
+function parseSseBlock(block) {
+  let event = 'message';
+  const dataLines = [];
+  for (const rawLine of block.split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!line) continue;
+    if (line.startsWith(':')) continue; // comment / heartbeat
+    const colon = line.indexOf(':');
+    if (colon === -1) continue;
+    const field = line.slice(0, colon).trim();
+    let value = line.slice(colon + 1);
+    if (value.startsWith(' ')) value = value.slice(1);
+    if (field === 'event') event = value;
+    else if (field === 'data') dataLines.push(value);
+  }
+  if (dataLines.length === 0) return null;
+  const dataText = dataLines.join('\n');
+  let data;
+  try {
+    data = JSON.parse(dataText);
+  } catch {
+    return null;
+  }
+  return { event, data };
+}
+
+/**
+ * Create the capture-channel watcher.
+ *
+ * The watcher owns one active SSE stream at a time and emits exactly one
+ * `notifications/claude/channel` notification per qualifying inbound event
+ * (new user_quote, or final `materialized`).
+ *
+ * Public surface:
+ *   - start(): kick off pin-file watcher + initial stream
+ *   - stop(): tear everything down
+ *   - retargetTo(sessionId): switch active stream to a new session
+ *   - getState(): debugging snapshot
+ *
+ * @param {object} opts
+ * @param {string} opts.vaultRoot
+ * @param {() => string} opts.getConsoleUrl
+ * @param {(method: string, params: unknown) => void} opts.sendNotification
+ * @param {(msg: string) => void} [opts.logger]
+ * @param {typeof fetch} [opts.fetch] — injectable for tests
+ */
+export function createCaptureChannelWatcher({
+  vaultRoot,
+  getConsoleUrl,
+  sendNotification,
+  logger,
+  fetch: fetchImpl = globalThis.fetch,
+}) {
+  const log = (msg) => {
+    if (logger) {
+      try {
+        logger(`[capture-channel] ${msg}`);
+      } catch {
+        // ignore
+      }
+      return;
+    }
+    try {
+      process.stderr.write(`[capture-channel] ${msg}\n`);
+    } catch {
+      // stderr may already be closed during shutdown
+    }
+  };
+
+  let stopped = false;
+  let activeSessionId = null;
+  let activeController = null;
+  let activeLoop = null;
+  let seenAts = new Set();
+  let reconnectAttempt = 0;
+  let lastEventAt = null;
+
+  // ---------------------------------------------------------------------------
+  // SSE stream consumption
+  // ---------------------------------------------------------------------------
+
+  /**
+   * GET the current session row from console — used to re-fetch the
+   * content_buffer after a pointer-only `content_buffer.patch` notification
+   * ([[HS-ECLH-DIAG-BX7R-capture-patch-fails-on-any-value-over]]: pg_notify
+   * has a hard 8000-byte payload limit, so the wire event never carries the
+   * patch `value`; consumers must re-fetch to see the new content).
+   *
+   * @param {string} sessionId
+   * @returns {Promise<object|null>} the session object, or null if absent.
+   */
+  async function fetchSessionSnapshot(sessionId) {
+    const consoleUrl = getConsoleUrl();
+    const url = `${consoleUrl.replace(/\/$/, '')}/api/capture/sessions/${encodeURIComponent(sessionId)}`;
+    const res = await fetchImpl(url, { headers: { accept: 'application/json' } });
+    if (!res.ok) {
+      throw new Error(`GET session returned ${res.status} ${res.statusText ?? ''}`.trim());
+    }
+    const body = await res.json();
+    return body?.session ?? null;
+  }
+
+  async function openAndConsumeStream(sessionId, controller) {
+    const consoleUrl = getConsoleUrl();
+    const url = `${consoleUrl.replace(/\/$/, '')}/api/capture/sessions/${encodeURIComponent(sessionId)}/events`;
+    log(`opening SSE stream → ${url}`);
+
+    const res = await fetchImpl(url, {
+      signal: controller.signal,
+      headers: { accept: 'text/event-stream' },
+    });
+
+    if (!res.ok) {
+      const err = new Error(`SSE GET returned ${res.status} ${res.statusText}`);
+      // Tag the status so the supervisor can distinguish a terminal 404/410
+      // (the pinned capture has no live session row — materialized or never
+      // created) from a transient 5xx / network blip worth retrying.
+      err.status = res.status;
+      throw err;
+    }
+    if (!res.body) {
+      throw new Error('SSE response has no body');
+    }
+
+    // Decode bytes → text → split into event blocks on blank line.
+    const decoder = new TextDecoder();
+    let buffer = '';
+    const reader = res.body.getReader();
+
+    while (true) {
+      if (controller.signal.aborted) {
+        try { await reader.cancel(); } catch { /* ignore */ }
+        return;
+      }
+      const { value, done } = await reader.read();
+      if (done) {
+        log(`SSE stream closed cleanly for ${sessionId}`);
+        return;
+      }
+      buffer += decoder.decode(value, { stream: true });
+
+      // Process complete events (terminated by blank line).
+      let blankIdx;
+      while ((blankIdx = buffer.indexOf('\n\n')) !== -1) {
+        const block = buffer.slice(0, blankIdx);
+        buffer = buffer.slice(blankIdx + 2);
+        const parsed = parseSseBlock(block);
+        if (!parsed) continue;
+        handleEvent(sessionId, parsed.event, parsed.data);
+        lastEventAt = new Date();
+      }
+    }
+  }
+
+  function handleEvent(sessionId, event, data) {
+    switch (event) {
+      case 'hello':
+        // connection established — nothing to do
+        return;
+      case 'snapshot':
+        seedDedupFromSnapshot(data);
+        return;
+      case 'content_buffer.patch':
+        handlePatch(sessionId, data);
+        return;
+      case 'materialized':
+        emitMaterialized(sessionId);
+        // Session is no longer pending; close cleanly. The next pin change
+        // (or the next session) triggers a fresh stream.
+        if (activeController && activeSessionId === sessionId) {
+          activeController.abort();
+        }
+        return;
+      case 'agent_attached':
+      default:
+        // Ignore other events. Heartbeat comments are stripped at parse layer.
+        return;
+    }
+  }
+
+  function seedDedupFromSnapshot(data) {
+    const buf = data?.session?.contentBuffer ?? data?.session?.content_buffer ?? null;
+    const quotes = buf?.userQuotes ?? buf?.user_quotes ?? null;
+    if (!Array.isArray(quotes)) return;
+    let seeded = 0;
+    for (const at of extractQuoteAts(quotes)) {
+      if (!seenAts.has(at)) {
+        seenAts.add(at);
+        seeded += 1;
+      }
+    }
+    if (seeded > 0) {
+      log(`snapshot seeded ${seeded} existing quote(s) into dedup set`);
+    }
+  }
+
+  function handlePatch(sessionId, data) {
+    // Only act on user_quotes patches. The agent-authored sections
+    // (coreIdea / concept / details) are read-only-from-modal and don't need
+    // to wake the agent; the agent is the one writing them.
+    const path = data?.path;
+    if (path !== 'user_quotes' && path !== 'userQuotes') return;
+
+    // The notification is pointer-only ([[HS-ECLH-DIAG-BX7R]]) — it never
+    // carries `value`. Re-fetch the session to see the new user_quotes.
+    // Fire-and-forget from the sync SSE-event handler; failures degrade
+    // gracefully (log, keep old dedup state) rather than crash the channel.
+    void (async () => {
+      let session;
+      try {
+        session = await fetchSessionSnapshot(sessionId);
+      } catch (err) {
+        log(`re-fetch failed for ${sessionId} after content_buffer.patch: ${err?.message ?? err}`);
+        return;
+      }
+      if (!session) return;
+
+      const buf = session.contentBuffer ?? session.content_buffer ?? null;
+      const quotes = buf?.userQuotes ?? buf?.user_quotes ?? null;
+      const ats = extractQuoteAts(quotes);
+      if (ats.length === 0) return;
+
+      const newAts = ats.filter((at) => !seenAts.has(at));
+      if (newAts.length === 0) {
+        // Replay (likely from a snapshot rehydration after reconnect). Drop.
+        return;
+      }
+      for (const at of newAts) seenAts.add(at);
+
+      try {
+        sendNotification('notifications/claude/channel', {
+          content:
+            `New user_quote in ${sessionId} — call heyspex_active_capture({ spec_id: "${sessionId}" }) for state, ` +
+            `and pass spec_id: "${sessionId}" to every heyspex_update_capture for this capture. ` +
+            `Do not call them without spec_id — that would attach to the wrong capture.`,
+          meta: {
+            capture_id: sessionId,
+            event_type: 'user_quote',
+          },
+        });
+        log(`pushed channel notification for ${sessionId} (${newAts.length} new quote(s))`);
+      } catch (err) {
+        log(`push failed for ${sessionId}: ${err?.message ?? err}`);
+      }
+    })();
+  }
+
+  function emitMaterialized(sessionId) {
+    try {
+      sendNotification('notifications/claude/channel', {
+        content: `Capture ${sessionId} materialized to disk.`,
+        meta: {
+          capture_id: sessionId,
+          event_type: 'materialized',
+        },
+      });
+      log(`pushed materialized notification for ${sessionId}`);
+    } catch (err) {
+      log(`materialized push failed for ${sessionId}: ${err?.message ?? err}`);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Connection supervisor — reconnect with exponential backoff
+  // ---------------------------------------------------------------------------
+
+  async function supervisor(sessionId, controller) {
+    while (!stopped && !controller.signal.aborted) {
+      try {
+        await openAndConsumeStream(sessionId, controller);
+        // Clean close (server closed stream or controller aborted via retarget/stop).
+        if (controller.signal.aborted) return;
+        reconnectAttempt = 0;
+      } catch (err) {
+        if (stopped || isAbortError(err)) return;
+
+        // Terminal: the pinned capture has no live session row (404) or it's
+        // permanently gone (410). Retrying would 404 forever — the exact flood
+        // this watcher used to produce. STOP. We deliberately leave the pin
+        // watcher running and `activeSessionId` set, so reevaluatePin() treats
+        // the unchanged pin as a no-op and won't reopen; pinning a *different*
+        // live capture still retargets to a fresh stream.
+        if (err?.status === 404 || err?.status === 410) {
+          log(
+            `session ${sessionId} has no live row (HTTP ${err.status}) — stopping stream (pinned capture is materialized or never opened a session). Will reopen only if the pin changes.`,
+          );
+          return;
+        }
+
+        // Transient (5xx / network): capped exponential backoff. Give up after
+        // MAX_TRANSIENT_ATTEMPTS so a wedged server can't spin us forever.
+        if (reconnectAttempt >= MAX_TRANSIENT_ATTEMPTS) {
+          log(
+            `giving up on ${sessionId} after ${reconnectAttempt} consecutive transient failures (last: ${err?.message ?? err}).`,
+          );
+          return;
+        }
+        const idx = Math.min(reconnectAttempt, RECONNECT_DELAYS_MS.length - 1);
+        const base = RECONNECT_DELAYS_MS[idx];
+        const jittered = base * (0.5 + Math.random() * 0.5);
+        log(`stream error for ${sessionId}: ${err?.message ?? err} — retry in ${Math.round(jittered)}ms`);
+        try {
+          await sleep(jittered, controller.signal);
+        } catch {
+          return; // aborted during sleep
+        }
+        reconnectAttempt += 1;
+      }
+    }
+  }
+
+  function openStreamFor(sessionId) {
+    if (activeController) activeController.abort();
+    seenAts = new Set();
+    reconnectAttempt = 0;
+    activeSessionId = sessionId;
+    activeController = new AbortController();
+    activeLoop = supervisor(sessionId, activeController).catch((err) => {
+      if (!isAbortError(err)) log(`supervisor crashed for ${sessionId}: ${err?.message ?? err}`);
+    });
+  }
+
+  function closeStream() {
+    if (activeController) {
+      activeController.abort();
+      activeController = null;
+    }
+    activeSessionId = null;
+    seenAts = new Set();
+    reconnectAttempt = 0;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Pin file watcher (fs.watch + debounce) — HS-TASK-19VY
+  // ---------------------------------------------------------------------------
+
+  let pinWatcher = null;
+  let pinWatcherTarget = null; // null = watching parent dir; otherwise direct file watch
+  let pinDebounceTimer = null;
+
+  function scheduleReevaluate() {
+    if (pinDebounceTimer) clearTimeout(pinDebounceTimer);
+    pinDebounceTimer = setTimeout(() => {
+      pinDebounceTimer = null;
+      reevaluatePin();
+    }, PIN_WATCH_DEBOUNCE_MS);
+  }
+
+  function reevaluatePin() {
+    if (stopped) return;
+    const focus = loadCaptureFocus(vaultRoot);
+    const nextSessionId = focus ? deriveSessionIdFromFocus(focus) : null;
+
+    if (nextSessionId === activeSessionId) {
+      return; // no-op — pin file touched but target unchanged
+    }
+    if (!nextSessionId) {
+      log('pin cleared — closing active stream and idling');
+      closeStream();
+      return;
+    }
+
+    // Skip already-materialized captures up front. A capture's markdown file at
+    // `spec_path` only exists once it has materialized — at which point its live
+    // `capture_sessions` row is gone and `/events` would 404. Opening a stream
+    // for it is pointless (this is exactly the HS-CAP-SID6 case). Detecting it
+    // on disk avoids even the single 404 the supervisor's terminal-404 branch
+    // would otherwise absorb. Pending sessions have no file yet → we still open.
+    if (focus.spec_path && existsSync(join(vaultRoot, focus.spec_path))) {
+      log(
+        `pin → ${nextSessionId} is already materialized (file exists at ${focus.spec_path}) — not streaming a closed capture`,
+      );
+      closeStream();
+      // Mark this session as the one we're responsible for so a repeated
+      // pin-touch for the same id stays a no-op (we don't re-open or re-log).
+      activeSessionId = nextSessionId;
+      return;
+    }
+
+    log(`pin retargeted: ${activeSessionId ?? '(idle)'} → ${nextSessionId}`);
+    openStreamFor(nextSessionId);
+  }
+
+  function startPinWatcher() {
+    const pinPath = captureFocusPath(vaultRoot);
+    try {
+      if (existsSync(pinPath)) {
+        pinWatcher = fsWatch(pinPath, () => scheduleReevaluate());
+        pinWatcherTarget = pinPath;
+      } else {
+        // File doesn't exist yet — watch the parent directory and filter by name.
+        const dir = dirname(pinPath);
+        if (!existsSync(dir)) {
+          log(`pin parent dir does not exist (${dir}) — pin watcher deferred`);
+          return;
+        }
+        const expectedName = pinPath.split(/[\\/]/).pop();
+        pinWatcher = fsWatch(dir, (_eventType, filename) => {
+          if (filename === expectedName) scheduleReevaluate();
+        });
+        pinWatcherTarget = dir;
+      }
+      log(`pin watcher started on ${pinWatcherTarget}`);
+    } catch (err) {
+      log(`failed to start pin watcher: ${err?.message ?? err}`);
+    }
+  }
+
+  function stopPinWatcher() {
+    if (pinDebounceTimer) {
+      clearTimeout(pinDebounceTimer);
+      pinDebounceTimer = null;
+    }
+    if (pinWatcher) {
+      try { pinWatcher.close(); } catch { /* ignore */ }
+      pinWatcher = null;
+      pinWatcherTarget = null;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public surface
+  // ---------------------------------------------------------------------------
+
+  function start() {
+    if (stopped) {
+      log('start() called after stop() — ignoring');
+      return;
+    }
+    startPinWatcher();
+    reevaluatePin(); // initial open if pin already exists
+  }
+
+  function stop() {
+    if (stopped) return;
+    stopped = true;
+    stopPinWatcher();
+    closeStream();
+    log('watcher stopped');
+  }
+
+  function retargetTo(sessionId) {
+    if (stopped) return;
+    if (sessionId === activeSessionId) return;
+    if (!sessionId) {
+      closeStream();
+      return;
+    }
+    log(`explicit retargetTo(${sessionId})`);
+    openStreamFor(sessionId);
+  }
+
+  function getState() {
+    return {
+      stopped,
+      activeSessionId,
+      lastEventAt: lastEventAt ? lastEventAt.toISOString() : null,
+      reconnectAttempt,
+      pinWatcherTarget,
+      seenQuoteCount: seenAts.size,
+    };
+  }
+
+  return { start, stop, retargetTo, getState };
+}
+
+// Exposed for unit tests.
+export const __test__ = {
+  parseSseBlock,
+  extractQuoteAts,
+  deriveSessionIdFromFocus,
+};