@jhizzard/termdeck 0.11.0 → 0.13.0

package/packages/server/src/flashback-diag.js

@@ -1,15 +1,37 @@
-// Flashback diagnostic ring buffer (Sprint 39 T1).
+// Flashback diagnostic ring buffer (Sprint 39 T1) + durable audit table
+// (Sprint 43 T2).
 //
-// Six decision points along the Flashback pipeline write structured events
-// here so production-flow regressions surface as a readable timeline instead
-// of a silent gate failure. The ring is in-memory and lost on restart by
-// design — persistence is a Sprint-40+ concern. Public surface:
+// Two layers of observability for the Flashback pipeline:
 //
-//   log({ sessionId, event, ...fields })  — append one event
-//   snapshot({ sessionId?, eventType?, limit? }) — read back filtered tail
-//   _resetForTest()                                — test-only ring clear
+//   (1) IN-MEMORY RING — six decision points along the pipeline write
+//       structured events to a 200-event ring. Lost on restart. Powers the
+//       /api/flashback/diag endpoint and the live diagnostic UI. This is
+//       fine-grained: every pattern match, every rate-limit hit, every
+//       bridge query gets logged.
 //
-// Event shape (all events): { ts, sessionId, event, ...event-specific fields }.
+//   (2) SQLITE AUDIT TABLE (flashback_events) — every actual fire (the
+//       moment a proactive_memory frame is sent over WS to the user's
+//       panel) gets one durable row. Survives restart. Powers the
+//       /flashback-history.html dashboard and the click-through funnel.
+//       This is coarse-grained: one row per fire, plus dismiss/click-through
+//       outcome.
+//
+// Public surface:
+//
+//   In-memory ring (Sprint 39):
+//     log({ sessionId, event, ...fields }) — append one event
+//     snapshot({ sessionId?, eventType?, limit? }) — read back filtered tail
+//     _resetForTest() — test-only ring clear
+//
+//   SQLite audit (Sprint 43 T2):
+//     recordFlashback(db, { sessionId, project, error_text, hits_count,
+//                           top_hit_id, top_hit_score, fired_at? }) → id
+//     markDismissed(db, eventId, dismissedAt?) → bool
+//     markClickedThrough(db, eventId) → bool
+//     getRecentFlashbacks(db, { since?, limit? }) → row[]
+//     getFunnelStats(db, { since? }) → { fires, dismissed, clicked_through }
+//
+// Event shape (ring): { ts, sessionId, event, ...event-specific fields }.
 //
 // Event types and their producers:
 //   pattern_match           — session.js _detectErrors (PATTERNS.error /
@@ -21,9 +43,13 @@
 //   bridge_result           — mnestra-bridge queryMnestra at call return
 //   proactive_memory_emit   — index.js onErrorDetected WS send block
 //
-// The route GET /api/flashback/diag (registered in index.js) returns
-// snapshot() output as JSON for ad-hoc inspection by Joshua and consumption
-// by T4's production-flow e2e test.
+// The audit table is an EXTENSION of the ring, not a replacement. Ring stays
+// for the live UI; SQLite is for the historical question "did flashback fire
+// when I needed it, and did I act on it?"
+//
+// SQLite functions are SAFE when db is null/undefined: they no-op and return
+// null/false/[] so test fixtures and Database-unavailable installs don't
+// break the live emit path.
 
 const RING_SIZE = 200;
 
@@ -48,4 +74,152 @@ function _resetForTest() {
   ring = [];
 }
 
-module.exports = { log, snapshot, _resetForTest, RING_SIZE };
+// ---- SQLite audit (Sprint 43 T2) ----------------------------------------
+
+// Persists one row per actual flashback fire. Returns the inserted row id
+// (number) or null when persistence is unavailable. Errors are caught and
+// logged — flashback persistence must never break the live emit path.
+function recordFlashback(db, event) {
+  if (!db) return null;
+  if (!event || (!event.sessionId && !event.session_id)) return null;
+  try {
+    const fired_at = event.fired_at || new Date().toISOString();
+    const session_id = event.session_id || event.sessionId;
+    const hits_count = Number.isFinite(event.hits_count) ? event.hits_count : 0;
+    const top_hit_score = (typeof event.top_hit_score === 'number'
+      && Number.isFinite(event.top_hit_score)) ? event.top_hit_score : null;
+    const result = db.prepare(`
+      INSERT INTO flashback_events
+        (fired_at, session_id, project, error_text, hits_count,
+         top_hit_id, top_hit_score)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      fired_at,
+      session_id,
+      event.project || null,
+      event.error_text || '',
+      hits_count,
+      event.top_hit_id || null,
+      top_hit_score,
+    );
+    // better-sqlite3 returns BigInt for lastInsertRowid; coerce to Number
+    // so it serializes naturally into JSON and the WS frame.
+    return Number(result.lastInsertRowid);
+  } catch (err) {
+    console.warn('[flashback-diag] recordFlashback INSERT failed:', err.message);
+    return null;
+  }
+}
+
+// Marks an event as dismissed (toast went away — by user, by 30s timeout,
+// or implicitly via click-through). Idempotent: only writes when
+// dismissed_at is currently NULL, so the FIRST dismiss wins. Returns true
+// when a row was actually updated.
+function markDismissed(db, eventId, dismissedAt) {
+  if (!db || !eventId) return false;
+  const id = Number(eventId);
+  if (!Number.isFinite(id) || id <= 0) return false;
+  try {
+    const ts = dismissedAt || new Date().toISOString();
+    const result = db.prepare(`
+      UPDATE flashback_events
+         SET dismissed_at = ?
+       WHERE id = ? AND dismissed_at IS NULL
+    `).run(ts, id);
+    return result.changes > 0;
+  } catch (err) {
+    console.warn('[flashback-diag] markDismissed UPDATE failed:', err.message);
+    return false;
+  }
+}
+
+// Marks an event as clicked-through (user opened the modal). Click-through
+// is also an implicit dismiss, so if dismissed_at is still NULL we set it
+// at the same moment. Idempotent: clicking twice is a no-op on the second
+// pass. Returns true when a row was actually updated.
+function markClickedThrough(db, eventId) {
+  if (!db || !eventId) return false;
+  const id = Number(eventId);
+  if (!Number.isFinite(id) || id <= 0) return false;
+  try {
+    const ts = new Date().toISOString();
+    const result = db.prepare(`
+      UPDATE flashback_events
+         SET clicked_through = 1,
+             dismissed_at    = COALESCE(dismissed_at, ?)
+       WHERE id = ? AND clicked_through = 0
+    `).run(ts, id);
+    return result.changes > 0;
+  } catch (err) {
+    console.warn('[flashback-diag] markClickedThrough UPDATE failed:', err.message);
+    return false;
+  }
+}
+
+// Reads the most-recent N flashback fires, optionally filtered to events
+// fired at-or-after the `since` ISO timestamp. Hard cap of 500 rows so
+// pathological queries can't OOM the dashboard.
+function getRecentFlashbacks(db, { since, limit } = {}) {
+  if (!db) return [];
+  try {
+    const cap = Math.max(1, Math.min(500, Number(limit) || 100));
+    const cols = `id, fired_at, session_id, project, error_text, hits_count,
+                  top_hit_id, top_hit_score, dismissed_at, clicked_through`;
+    if (since) {
+      return db.prepare(
+        `SELECT ${cols} FROM flashback_events
+          WHERE fired_at >= ?
+          ORDER BY fired_at DESC
+          LIMIT ?`
+      ).all(since, cap);
+    }
+    return db.prepare(
+      `SELECT ${cols} FROM flashback_events
+        ORDER BY fired_at DESC
+        LIMIT ?`
+    ).all(cap);
+  } catch (err) {
+    console.warn('[flashback-diag] getRecentFlashbacks SELECT failed:', err.message);
+    return [];
+  }
+}
+
+// Click-through funnel aggregates: total fires, dismissed (any reason),
+// clicked-through (modal opened). Optional `since` ISO timestamp filter.
+// All three are scalar counts — the dashboard renders them as a percentage
+// funnel chart.
+function getFunnelStats(db, { since } = {}) {
+  const empty = { fires: 0, dismissed: 0, clicked_through: 0 };
+  if (!db) return empty;
+  try {
+    const where = since ? `WHERE fired_at >= ?` : '';
+    const args = since ? [since] : [];
+    const row = db.prepare(
+      `SELECT
+         COUNT(*) AS fires,
+         SUM(CASE WHEN dismissed_at IS NOT NULL THEN 1 ELSE 0 END) AS dismissed,
+         SUM(CASE WHEN clicked_through = 1 THEN 1 ELSE 0 END) AS clicked_through
+       FROM flashback_events ${where}`
+    ).get(...args);
+    return {
+      fires: Number(row?.fires || 0),
+      dismissed: Number(row?.dismissed || 0),
+      clicked_through: Number(row?.clicked_through || 0),
+    };
+  } catch (err) {
+    console.warn('[flashback-diag] getFunnelStats SELECT failed:', err.message);
+    return empty;
+  }
+}
+
+module.exports = {
+  log,
+  snapshot,
+  _resetForTest,
+  RING_SIZE,
+  recordFlashback,
+  markDismissed,
+  markClickedThrough,
+  getRecentFlashbacks,
+  getFunnelStats,
+};

package/packages/server/src/index.js

@@ -911,10 +911,22 @@ function createServer(config) {
               return;
             }
             if (sess.ws && sess.ws.readyState === 1) {
-              const frame = JSON.stringify({ type: 'proactive_memory', hit });
+              // Sprint 43 T2: persist the fire to flashback_events BEFORE
+              // serializing the WS frame so we can include the row id. The
+              // client uses flashback_event_id to POST dismiss/click-through
+              // updates back to the audit dashboard.
+              const flashback_event_id = flashbackDiag.recordFlashback(db, {
+                sessionId: sess.id,
+                project: sess.meta.project || null,
+                error_text: question,
+                hits_count: count,
+                top_hit_id: hit.id || null,
+                top_hit_score: typeof hit.similarity === 'number' ? hit.similarity : null,
+              });
+              const frame = JSON.stringify({ type: 'proactive_memory', hit, flashback_event_id });
               try {
                 sess.ws.send(frame);
-                console.log(`[flashback] proactive_memory sent to session ${sess.id} (source_type=${hit.source_type}, project=${hit.project})`);
+                console.log(`[flashback] proactive_memory sent to session ${sess.id} (source_type=${hit.source_type}, project=${hit.project}, event_id=${flashback_event_id})`);
                 flashbackDiag.log({
                   sessionId: sess.id,
                   event: 'proactive_memory_emit',
@@ -922,6 +934,7 @@ function createServer(config) {
                   frame_size_bytes: Buffer.byteLength(frame, 'utf8'),
                   result_count_in_frame: 1,
                   outcome: 'emitted',
+                  flashback_event_id,
                 });
               } catch (err) {
                 console.error('[flashback] proactive_memory send failed:', err);
@@ -1442,6 +1455,49 @@ function createServer(config) {
     res.json({ count: events.length, events });
   });
 
+  // GET /api/flashback/history - Sprint 43 T2 durable audit dashboard.
+  // Returns the most-recent flashback fires from SQLite (survives restart)
+  // plus the click-through funnel aggregate. The dashboard uses one fetch
+  // for both so it can render the table and the funnel in lockstep.
+  // Optional filters: ?since=<ISO8601>, ?limit=N (default 100, max 500).
+  app.get('/api/flashback/history', (req, res) => {
+    const rawSince = req.query && req.query.since;
+    const since = (typeof rawSince === 'string' && rawSince.length) ? rawSince : undefined;
+    const rawLimit = req.query && req.query.limit;
+    const limit = rawLimit != null ? parseInt(rawLimit, 10) : undefined;
+    const events = flashbackDiag.getRecentFlashbacks(db, {
+      since,
+      limit: Number.isFinite(limit) && limit > 0 ? limit : undefined,
+    });
+    const funnel = flashbackDiag.getFunnelStats(db, { since });
+    res.json({ count: events.length, events, funnel });
+  });
+
+  // POST /api/flashback/:id/dismissed - mark a flashback toast as dismissed.
+  // Called by the client when the user clicks ×, presses Escape, lets the
+  // 30s auto-timer fire, OR clicks "Not relevant" / "Dismiss" in the modal.
+  // Idempotent: subsequent calls are no-ops (first dismiss timestamp wins).
+  app.post('/api/flashback/:id/dismissed', (req, res) => {
+    const id = parseInt(req.params.id, 10);
+    if (!Number.isFinite(id) || id <= 0) {
+      return res.status(400).json({ error: 'Invalid id' });
+    }
+    const updated = flashbackDiag.markDismissed(db, id);
+    res.json({ ok: true, updated });
+  });
+
+  // POST /api/flashback/:id/clicked - mark a flashback toast as clicked-
+  // through (user opened the modal). Click-through is also an implicit
+  // dismiss, so this updates dismissed_at if it's still NULL. Idempotent.
+  app.post('/api/flashback/:id/clicked', (req, res) => {
+    const id = parseInt(req.params.id, 10);
+    if (!Number.isFinite(id) || id <= 0) {
+      return res.status(400).json({ error: 'Invalid id' });
+    }
+    const updated = flashbackDiag.markClickedThrough(db, id);
+    res.json({ ok: true, updated });
+  });
+
   // GET /api/pty-reaper/status — Sprint 42 T2 observability surface.
   // Returns the live registry (per-session PTY pid + tracked descendants) and
   // the reaped-history ring buffer so heavy-use installs can tell whether the

package/packages/server/src/session.js

@@ -15,6 +15,8 @@ const os = require('os');
 const path = require('path');
 const { resolveTheme } = require('./theme-resolver');
 const flashbackDiag = require('./flashback-diag');
+const claudeAdapter = require('./agent-adapters/claude');
+const { detectAdapter, getAdapterForSessionType } = require('./agent-adapters');
 
 // Strip ANSI escape codes for pattern matching
 function stripAnsi(str) {
@@ -25,14 +27,22 @@ function stripAnsi(str) {
     .replace(/\x1b[>=<]/g, '');                      // Keypad/cursor modes
 }
 
-// Pattern matchers for detecting terminal type and status
+// Pattern matchers for detecting terminal type and status.
+//
+// Sprint 44 T3: claudeCode patterns are owned by the Claude adapter at
+// ./agent-adapters/claude.js. This object continues to expose them under
+// the legacy `PATTERNS.claudeCode.*` shape so external callers
+// (tests/rcfile-noise.test.js, tests/analyzer-error-fixtures.test.js, the
+// rcfile-noise analyze.js fixture script) keep working without import
+// changes. Sprint 45 T4 removes this shim — new code should consume the
+// adapter directly via require('./agent-adapters/claude').
 const PATTERNS = {
   claudeCode: {
-    prompt: /^[>❯]\s/m,
-    thinking: /\b(thinking|Thinking)\b/,
-    editing: /^(Edit|Create|Update|Delete)\s/m,
-    tool: /^⏺\s/m,
-    idle: /^>\s*$/m
+    prompt: claudeAdapter.patterns.prompt,
+    thinking: claudeAdapter.patterns.thinking,
+    editing: claudeAdapter.patterns.editing,
+    tool: claudeAdapter.patterns.tool,
+    idle: claudeAdapter.patterns.idle
   },
   geminiCli: {
     prompt: /^gemini>\s/m,
@@ -86,7 +96,11 @@ const PATTERNS = {
   // Sprint 40 T2: added mixed-case `Fatal` (mirrors `fatal` / `FATAL`) and
   // the `npm ERR!` shape (special-cased outside the alternation because
   // `!` is not a word character so `\b` after `npm ERR!` doesn't match).
-  errorLineStart: /^\s*(?:(?:error|Error|ERROR|exception|Exception|Traceback|fatal|Fatal|FATAL|segmentation fault|panic|EACCES|ECONNREFUSED|ENOENT|command not found|undefined reference|cannot find module|failed with exit code|No such file or directory|Permission denied)\b|npm ERR!)/m,
+  // Sprint 44 T3: this regex is now owned by the Claude adapter
+  // (./agent-adapters/claude.js patterns.error). The shim below preserves
+  // the legacy PATTERNS.errorLineStart export — same regex object, so any
+  // existing reference equality (e.g. `=== PATTERNS.errorLineStart`) holds.
+  errorLineStart: claudeAdapter.patterns.error,
   // Sprint 33: PATTERNS.error misses the most common Unix shell errors —
   // `cat: /foo: No such file or directory`, `bash: foo: command not found`,
   // `rm: cannot remove ...: Permission denied`. These have a colon-prefix
@@ -241,9 +255,18 @@ class Session {
   }
 
   _detectType(data) {
-    if (PATTERNS.claudeCode.prompt.test(data) || /claude/i.test(this.meta.command)) {
-      this.meta.type = 'claude-code';
-    } else if (PATTERNS.geminiCli.prompt.test(data) || /gemini/i.test(this.meta.command)) {
+    // Sprint 44 T3: registry-aware detection. detectAdapter() iterates
+    // AGENT_ADAPTERS in declaration order and returns the first hit by
+    // prompt regex OR command-string match. Sprint 44 lands Claude only
+    // (so this returns the Claude adapter or undefined); Sprint 45 adds
+    // Codex / Gemini / Grok adapters and the gemini fall-through below
+    // moves into gemini.js.
+    const adapter = detectAdapter(data, this.meta.command);
+    if (adapter) {
+      this.meta.type = adapter.sessionType;
+      return;
+    }
+    if (PATTERNS.geminiCli.prompt.test(data) || /gemini/i.test(this.meta.command)) {
       this.meta.type = 'gemini';
     } else if (
       PATTERNS.pythonServer.uvicorn.test(data) ||
@@ -259,24 +282,21 @@ class Session {
     const p = PATTERNS;
     const oldStatus = this.meta.status;
 
-    switch (this.meta.type) {
-      case 'claude-code':
-        if (p.claudeCode.thinking.test(data)) {
-          this.meta.status = 'thinking';
-          this.meta.statusDetail = 'Claude is reasoning...';
-        } else if (p.claudeCode.editing.test(data)) {
-          this.meta.status = 'editing';
-          const match = data.match(/^(Edit|Create|Update|Delete)\s+(.+)$/m);
-          this.meta.statusDetail = match ? `${match[1]} ${match[2]}` : 'Editing files';
-        } else if (p.claudeCode.tool.test(data)) {
-          this.meta.status = 'active';
-          this.meta.statusDetail = 'Using tools';
-        } else if (p.claudeCode.idle.test(data)) {
-          this.meta.status = 'idle';
-          this.meta.statusDetail = 'Waiting for input';
-        }
-        break;
-
+    // Sprint 44 T3: claude-code status detection now lives in the Claude
+    // adapter's `statusFor(data)` method. Returns { status, statusDetail }
+    // on a match, null on no-change — preserves the original switch's
+    // "leave status untouched if no claude pattern fires" semantics.
+    // Other types (gemini, python-server, default shell) stay in-file
+    // until Sprint 45 migrates them.
+    const adapter = getAdapterForSessionType(this.meta.type);
+    if (adapter && typeof adapter.statusFor === 'function') {
+      const result = adapter.statusFor(data);
+      if (result && result.status) {
+        this.meta.status = result.status;
+        this.meta.statusDetail = result.statusDetail || '';
+      }
+    } else {
+      switch (this.meta.type) {
       case 'gemini':
         if (p.geminiCli.thinking.test(data)) {
           this.meta.status = 'thinking';
@@ -309,6 +329,7 @@ class Session {
         } else {
           this.meta.status = 'active';
         }
+      }
     }
 
     // Debounce status change events (3s) to avoid flooding RAG with active↔idle flaps
@@ -387,10 +408,20 @@ class Session {
     // Claude Code's tool output frequently contains "error"/"Error" mid-line
     // (grep matches, test results, log dumps). Use a line-anchored pattern
     // for that session type so we don't flag content as failure.
-    const primaryPattern = this.meta.type === 'claude-code'
-      ? PATTERNS.errorLineStart
+    //
+    // Sprint 44 T3: per-agent primary error pattern is now read off the
+    // adapter (`patterns.error` + `patternNames.error`). Falls back to the
+    // generic prose-shape PATTERNS.error when no adapter has claimed the
+    // session type. The Claude adapter's `patterns.error` IS the same regex
+    // object as PATTERNS.errorLineStart (the shim wires them together), so
+    // existing `=== PATTERNS.errorLineStart` reference checks still hold.
+    const adapter = getAdapterForSessionType(this.meta.type);
+    const primaryPattern = adapter && adapter.patterns && adapter.patterns.error
+      ? adapter.patterns.error
       : PATTERNS.error;
-    const primaryName = this.meta.type === 'claude-code' ? 'errorLineStart' : 'error';
+    const primaryName = adapter && adapter.patternNames && adapter.patternNames.error
+      ? adapter.patternNames.error
+      : 'error';
     // Sprint 33 fix: the structured patterns above miss `cat: /foo: No such
     // file or directory` and friends — the most common Unix shell error
     // shapes Josh hits day-to-day. Fall through to PATTERNS.shellError so

package/packages/server/src/setup/migrations.js

@@ -73,16 +73,54 @@ function listRumenMigrations() {
   return tryNodeModules('@jhizzard/rumen');
 }
 
-function rumenFunctionDir() {
-  // Same resolution order.
+// Resolve the parent directory containing the bundled Rumen Edge Function
+// source. Sprint 43 T3: bundled-FIRST (matches listMnestraMigrations and
+// listRumenMigrations since v0.6.8). The npm `@jhizzard/rumen` package's
+// `files` array is `["dist", "migrations", "README.md", "LICENSE",
+// "CHANGELOG.md"]` — it does NOT ship `supabase/functions/`. So the npm
+// fallback only ever matters for someone who has installed `@jhizzard/rumen`
+// from a local checkout (not the published tarball). Bundled-first prevents
+// a stale local rumen install from shadowing the source TermDeck developed
+// and tested against.
+//
+// Returns the directory whose immediate children are the function-name
+// subdirectories (e.g., `rumen-tick/`, `graph-inference/`).
+function rumenFunctionsRoot() {
+  const bundledRoot = path.join(SETUP_DIR, 'rumen', 'functions');
+  if (fs.existsSync(bundledRoot) && fs.readdirSync(bundledRoot).length > 0) {
+    return bundledRoot;
+  }
   try {
     const pkgJsonPath = require.resolve('@jhizzard/rumen/package.json', {
       paths: [process.cwd(), SETUP_DIR]
     });
-    const candidate = path.join(path.dirname(pkgJsonPath), 'supabase', 'functions', 'rumen-tick');
+    const candidate = path.join(path.dirname(pkgJsonPath), 'supabase', 'functions');
     if (fs.existsSync(candidate)) return candidate;
   } catch (_err) { /* fallthrough */ }
-  return path.join(SETUP_DIR, 'rumen', 'functions', 'rumen-tick');
+  return bundledRoot;
+}
+
+// Enumerate the function-name subdirectories under the resolved Rumen
+// functions root. Each entry must contain at least an `index.ts`. Sprint 43
+// T3 bundled both `rumen-tick` and `graph-inference`.
+function listRumenFunctions() {
+  const root = rumenFunctionsRoot();
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root)
+    .filter((name) => {
+      const dir = path.join(root, name);
+      return fs.statSync(dir).isDirectory()
+        && fs.existsSync(path.join(dir, 'index.ts'));
+    })
+    .sort();
+}
+
+// Back-compat: pre-Sprint-43 callers expected a single path resolving to the
+// `rumen-tick/` directory specifically. Delegates to rumenFunctionsRoot()
+// + 'rumen-tick'. Prefer rumenFunctionsRoot() / listRumenFunctions() for new
+// code that needs to operate over multiple functions.
+function rumenFunctionDir() {
+  return path.join(rumenFunctionsRoot(), 'rumen-tick');
 }
 
 function readFile(filepath) {
@@ -92,6 +130,8 @@ function readFile(filepath) {
 module.exports = {
   listMnestraMigrations,
   listRumenMigrations,
+  rumenFunctionsRoot,
+  listRumenFunctions,
   rumenFunctionDir,
   readFile
 };