@jhizzard/termdeck 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"
@@ -30,7 +30,8 @@
     "start": "NODE_ENV=production node packages/cli/src/index.js",
     "test": "node --test packages/server/tests/**/*.test.js",
     "install:app": "bash install.sh",
-    "sync-rumen-functions": "bash scripts/sync-rumen-functions.sh"
+    "sync-rumen-functions": "bash scripts/sync-rumen-functions.sh",
+    "sync:agents": "node scripts/sync-agent-instructions.js"
   },
   "dependencies": {
     "@homebridge/node-pty-prebuilt-multiarch": "^0.13.1",

package/packages/server/src/agent-adapters/claude.js

@@ -0,0 +1,158 @@
+// Claude Code adapter — Sprint 44 T3
+//
+// First adapter in the AGENT_ADAPTERS registry (see ./index.js). Lifts the
+// claude-code logic that previously lived as hardcoded branches in
+// packages/server/src/session.js. Behavior is bit-for-bit identical to the
+// pre-Sprint-44 inline path: same regexes, same status strings, same
+// transcript-parser cut-offs. Sprint 45 adds Codex / Gemini / Grok adapters
+// alongside this one; Sprint 46 wires per-lane agent assignment in 4+1.
+//
+// Contract (memorialization doc § 4 + lane brief T3):
+//   {
+//     name:           string,                     // adapter id used in registry
+//     sessionType:    string,                     // session.meta.type produced
+//     matches:        (cmd) => boolean,           // command-string detection
+//     spawn:          { binary, defaultArgs, env },
+//     patterns:       { prompt, thinking, editing, tool, idle, error },
+//     patternNames:   { error: string },          // diag-event label preservation
+//     statusFor:      (data) => { status, statusDetail } | null,
+//     parseTranscript:(raw) => Memory[],          // for memory-session-end hook
+//     bootPromptTemplate: (lane, sprint) => string,
+//     costBand:       'free' | 'pay-per-token' | 'subscription',
+//   }
+//
+// `statusFor` returns null when no pattern matches — preserves the original
+// "no change" semantics for the claude-code switch case. Caller leaves
+// `meta.status` and `meta.statusDetail` untouched on null.
+
+// ──────────────────────────────────────────────────────────────────────────
+// Patterns — verbatim regexes lifted from session.js so the adapter and the
+// shim remain reference-equal. Don't redeclare these elsewhere; import from
+// the adapter so future tweaks land in one place.
+// ──────────────────────────────────────────────────────────────────────────
+
+const PROMPT = /^[>❯]\s/m;
+const THINKING = /\b(thinking|Thinking)\b/;
+const EDITING = /^(Edit|Create|Update|Delete)\s/m;
+const EDITING_DETAIL = /^(Edit|Create|Update|Delete)\s+(.+)$/m;
+const TOOL = /^⏺\s/m;
+const IDLE = /^>\s*$/m;
+
+// errorLineStart from session.js — line-anchored variant for claude-code
+// sessions whose tool output (grep results, test logs, file dumps) routinely
+// mentions "Error" mid-line without representing an actual failure.
+// Sprint 40 T2 added mixed-case `Fatal` + the special-cased `npm ERR!` shape.
+const ERROR = /^\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;
+
+// ──────────────────────────────────────────────────────────────────────────
+// statusFor — replaces the `case 'claude-code':` block of _updateStatus.
+// Order matters: thinking → editing → tool → idle. First match wins, exactly
+// as the original switch did with cascading `else if`s.
+// ──────────────────────────────────────────────────────────────────────────
+
+function statusFor(data) {
+  if (THINKING.test(data)) {
+    return { status: 'thinking', statusDetail: 'Claude is reasoning...' };
+  }
+  if (EDITING.test(data)) {
+    const match = data.match(EDITING_DETAIL);
+    return {
+      status: 'editing',
+      statusDetail: match ? `${match[1]} ${match[2]}` : 'Editing files',
+    };
+  }
+  if (TOOL.test(data)) {
+    return { status: 'active', statusDetail: 'Using tools' };
+  }
+  if (IDLE.test(data)) {
+    return { status: 'idle', statusDetail: 'Waiting for input' };
+  }
+  return null;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// parseTranscript — Claude Code JSONL format, lifted from
+// packages/stack-installer/assets/hooks/memory-session-end.js:88-102.
+// Emits records of shape { role: 'user'|'assistant', content: string }
+// truncated to 400 chars per message. The hook itself remains the consumer
+// in Sprint 44; Sprint 45 T4 wires it to read from this adapter so other
+// agents can plug in their own format parsers.
+// ──────────────────────────────────────────────────────────────────────────
+
+function parseTranscript(raw) {
+  if (typeof raw !== 'string' || raw.length === 0) return [];
+  const lines = raw.split('\n').filter(Boolean);
+  const messages = [];
+  for (const line of lines) {
+    let msg;
+    try { msg = JSON.parse(line); } catch (_) { continue; }
+    const role = msg && msg.message && msg.message.role;
+    if (role !== 'user' && role !== 'assistant') continue;
+    const content = msg.message.content;
+    let text = '';
+    if (typeof content === 'string') {
+      text = content;
+    } else if (Array.isArray(content)) {
+      text = content
+        .filter((c) => c && c.type === 'text')
+        .map((c) => c.text)
+        .join(' ');
+    }
+    if (text) messages.push({ role, content: text.slice(0, 400) });
+  }
+  return messages;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// bootPromptTemplate — minimal scaffold matching the global-CLAUDE.md 4+1
+// boot block. Sprint 46 T2 will refine per-agent prompts; this is the
+// placeholder so the adapter contract is complete in Sprint 44.
+// ──────────────────────────────────────────────────────────────────────────
+
+function bootPromptTemplate(lane = {}, sprint = {}) {
+  const tn = lane.id || 'T?';
+  const sprintNum = sprint.number || '?';
+  const sprintName = sprint.name || 'unnamed';
+  const project = (lane.project || sprint.project || 'termdeck');
+  const briefing = lane.briefingPath || `docs/sprint-${sprintNum}-${sprintName}/${tn}-<lane>.md`;
+  return [
+    `You are ${tn} in Sprint ${sprintNum} (${sprintName}). Boot sequence:`,
+    `1. memory_recall(project="${project}", query="<topic>")`,
+    `2. memory_recall(query="<broader topic>")`,
+    `3. Read ~/.claude/CLAUDE.md and ./CLAUDE.md`,
+    `4. Read docs/sprint-${sprintNum}-${sprintName}/PLANNING.md`,
+    `5. Read docs/sprint-${sprintNum}-${sprintName}/STATUS.md`,
+    `6. Read ${briefing}`,
+    '',
+    'Then begin. Stay in your lane. Post FINDING / FIX-PROPOSED / DONE in STATUS.md.',
+    "Don't bump versions, don't touch CHANGELOG, don't commit.",
+  ].join('\n');
+}
+
+const claudeAdapter = {
+  name: 'claude',
+  sessionType: 'claude-code',
+  matches: (cmd) => typeof cmd === 'string' && /claude/i.test(cmd),
+  spawn: {
+    binary: 'claude',
+    defaultArgs: [],
+    env: {},
+  },
+  patterns: {
+    prompt: PROMPT,
+    thinking: THINKING,
+    editing: EDITING,
+    tool: TOOL,
+    idle: IDLE,
+    error: ERROR,
+  },
+  patternNames: {
+    error: 'errorLineStart',
+  },
+  statusFor,
+  parseTranscript,
+  bootPromptTemplate,
+  costBand: 'pay-per-token',
+};
+
+module.exports = claudeAdapter;

package/packages/server/src/agent-adapters/index.js

@@ -0,0 +1,55 @@
+// Agent adapter registry — Sprint 44 T3
+//
+// Single source of truth for per-agent terminal behavior. Each adapter
+// implements the contract documented in ./claude.js (and the memorialization
+// doc § 4) — type detection, status patterns, transcript parsing, boot prompt
+// templating, cost band. session.js consults this registry when analyzing
+// PTY output so adding a new agent (Codex / Gemini / Grok in Sprint 45) is a
+// new file in this directory + one entry in `AGENT_ADAPTERS` below — no
+// switch statements to extend.
+//
+// Sprint 44 lands the Claude adapter only. The other agents stay on the
+// in-file shim path in session.js until Sprint 45 T1-T3 ship their adapters
+// and Sprint 45 T4 wires the launcher UI through the same registry.
+
+const claude = require('./claude');
+
+// Keyed by adapter name (NOT session.meta.type — adapters expose their own
+// `sessionType` field for that mapping). Order is iteration order for the
+// detect loop in session.js, so list more-specific adapters before less.
+const AGENT_ADAPTERS = {
+  claude,
+};
+
+// Convenience accessor — returns the adapter whose `sessionType` matches the
+// session.meta.type value, or undefined if no adapter has claimed that type.
+// session.js calls this in the hot path; keep it cheap.
+function getAdapterForSessionType(type) {
+  if (!type) return undefined;
+  for (const adapter of Object.values(AGENT_ADAPTERS)) {
+    if (adapter.sessionType === type) return adapter;
+  }
+  return undefined;
+}
+
+// Convenience accessor — first adapter whose prompt regex matches `data` or
+// whose `matches(command)` returns true. Returns undefined if no adapter
+// claims the session, leaving the caller to fall back to legacy detection
+// (gemini / python-server / shell). session.js calls this from `_detectType`.
+function detectAdapter(data, command) {
+  for (const adapter of Object.values(AGENT_ADAPTERS)) {
+    const promptHit = adapter.patterns
+      && adapter.patterns.prompt
+      && typeof data === 'string'
+      && adapter.patterns.prompt.test(data);
+    const cmdHit = typeof adapter.matches === 'function' && adapter.matches(command);
+    if (promptHit || cmdHit) return adapter;
+  }
+  return undefined;
+}
+
+module.exports = {
+  AGENT_ADAPTERS,
+  getAdapterForSessionType,
+  detectAdapter,
+};

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