dual-brain 0.2.14 → 0.2.16

package/src/cognitive-loop.mjs

@@ -0,0 +1,557 @@
+// Cognitive Loop — the integration layer that makes HEAD a continuous process.
+// Replaces single-shot deliberation with: perceive → plan → predict → dispatch → debrief → replan → ...
+
+import { processTurn, loadState, perceive, assessUncertainty, deriveObligations, notice, deliberate, assessDepth, recordDispatchOutcome } from './head.mjs';
+import { planWaves, shouldReplan, replan, estimateWaveCost } from './wave-planner.mjs';
+import { parseDebrief, generateDebriefInstruction, integrateDebrief, summarizeWaveOutcome } from './debrief.mjs';
+import { predictFailureModes, generatePreventions, scoreDispatchReadiness, evolvePatterns, loadSessionPatterns } from './predictive.mjs';
+import { writeDeliberation } from './head-protocol.mjs';
+import { check as checkInbox, generateInboxBrief, purge as purgeInbox } from './inbox.mjs';
+import * as memoryTiers from './memory-tiers.mjs';
+import * as narrative from './narrative.mjs';
+import * as simmer from './simmer.mjs';
+import { build as buildEnvelope } from './envelope.mjs';
+import { acquire as acquireSession, release as releaseSession, isOwner as isSessionOwner } from './session-lock.mjs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ── Pattern cache ──────────────────────────────────────────────────────────
+let _patternsCache = null;
+let _patternsCacheTs = 0;
+function getCachedPatterns() {
+  if (!_patternsCache || Date.now() - _patternsCacheTs > 5000) {
+    _patternsCache = loadSessionPatterns();
+    _patternsCacheTs = Date.now();
+  }
+  return _patternsCache;
+}
+
+const LOOP_STATE_DIR = join(process.cwd(), '.dualbrain');
+const LOOP_STATE_FILE = join(LOOP_STATE_DIR, 'cognitive-loop.json');
+
+// ── Loop state persistence ──────────────────────────────────────────────────
+
+function loadLoopState() {
+  try {
+    if (existsSync(LOOP_STATE_FILE)) {
+      return JSON.parse(readFileSync(LOOP_STATE_FILE, 'utf8'));
+    }
+  } catch {}
+  return freshLoopState();
+}
+
+function freshLoopState() {
+  return {
+    sessionId: Date.now().toString(36),
+    activePlan: null,
+    completedWaves: [],
+    debriefs: [],
+    situationHistory: [],
+    replans: 0,
+    totalDispatches: 0,
+    totalTokensEstimated: 0,
+  };
+}
+
+function saveLoopState(state) {
+  mkdirSync(LOOP_STATE_DIR, { recursive: true });
+  writeFileSync(LOOP_STATE_FILE, JSON.stringify(state, null, 2));
+}
+
+// ── The cognitive loop ──────────────────────────────────────────────────────
+
+/**
+ * Entry point: process a user message through the full cognitive loop.
+ * Returns a LoopResult that tells the caller exactly what to do next.
+ *
+ * @param {string} userMessage
+ * @param {object} context - { files, recentFiles, priorFailures, uncommittedFiles, etc }
+ * @returns {LoopResult}
+ */
+export function enter(userMessage, context = {}) {
+  // Session lock: one HEAD at a time
+  const lock = acquireSession();
+  if (!lock.acquired) {
+    return {
+      phase: 'readonly',
+      action: { type: 'respond', mode: 'readonly' },
+      rationale: `Another session (${lock.existingSession}) is active. This session is read-only to prevent split-brain.`,
+      shouldAskUser: false,
+      surfaceNoticings: [],
+      plan: null,
+      nextDispatch: null,
+    };
+  }
+
+  const headState = loadState();
+  const loopState = loadLoopState();
+
+  // Check if we just auto-updated — surface it naturally
+  _checkUpdateNotice(context);
+
+  // Immersion: load memory tiers so HEAD is "in the song"
+  const memory = memoryTiers.assemble({
+    userMessage,
+    files: context.files || [],
+    intent: context._detectedIntent || null,
+  });
+  if (memory.combined) {
+    context._immersionContext = memory.combined;
+  }
+
+  // Check inbox for HEAD before processing
+  const inboxBrief = generateInboxBrief('head');
+  if (inboxBrief) {
+    context._inboxBrief = inboxBrief;
+  }
+
+  // Simmer: check for crystallized ideas to surface
+  const crystallized = simmer.harvest();
+  if (crystallized.length > 0) {
+    context._crystallizedIdeas = crystallized.map(i => i.idea);
+  }
+
+  // Phase 1: Full cognitive pipeline
+  const turn = processTurn(headState, userMessage, context);
+
+  // Save situation for history
+  loopState.situationHistory.push({
+    ts: Date.now(),
+    depth: turn.depth,
+    action: turn.action.type,
+    confidence: turn.result.confidence.score,
+  });
+
+  // Surface update notice as a noticing
+  if (context._updateNotice) {
+    turn.result.surfaceNoticings = turn.result.surfaceNoticings || [];
+    turn.result.surfaceNoticings.unshift(context._updateNotice);
+  }
+
+  // Narrative evolution: update HEAD's running understanding
+  _evolveNarrative(turn, userMessage, context);
+
+  // Simmer: capture any ideas from user message that aren't direct tasks
+  _captureSimmerSignals(userMessage, turn);
+
+  // If HEAD says don't dispatch, or it's a "proceed" with no active plan, respond
+  if ((!turn.shouldDispatch && !turn.shouldThink) || (turn.action.type === 'proceed' && !loopState.activePlan)) {
+    saveLoopState(loopState);
+    return {
+      phase: 'respond',
+      action: turn.action,
+      rationale: turn.rationale,
+      shouldAskUser: turn.shouldAskUser,
+      surfaceNoticings: turn.result.surfaceNoticings,
+      plan: null,
+      nextDispatch: null,
+    };
+  }
+
+  // Persist deliberation artifact for deliberation-gate hook validation
+  try {
+    writeDeliberation(userMessage, { situation: turn.situation, result: turn.result });
+  } catch (err) {
+    // Non-fatal: don't break the loop if deliberation persistence fails
+    process.stderr.write(`[cognitive-loop] writeDeliberation failed: ${err?.message?.slice(0, 120)}\n`);
+  }
+
+  // Phase 2: Plan waves
+  const plan = planWaves(turn, {
+    files: context.files || [],
+    priorDebriefs: loopState.debriefs,
+    diagnosticPatterns: getCachedPatterns(),
+  });
+
+  loopState.activePlan = plan;
+  saveLoopState(loopState);
+
+  // Phase 3: Prepare first wave for dispatch
+  const firstWave = plan.waves[0];
+  if (!firstWave) {
+    return {
+      phase: 'respond',
+      action: turn.action,
+      rationale: 'Wave planner produced empty plan — falling back to direct response',
+      shouldAskUser: true,
+      surfaceNoticings: turn.result.surfaceNoticings,
+      plan,
+      nextDispatch: null,
+    };
+  }
+
+  const prepared = prepareWave(firstWave, turn, context, loopState);
+
+  // Don't dispatch unready work — return as blocked
+  if (prepared.blockers.length > 0 && !prepared.allReady) {
+    saveLoopState(loopState);
+    return {
+      phase: 'blocked',
+      action: turn.action,
+      rationale: turn.rationale,
+      shouldAskUser: true,
+      surfaceNoticings: turn.result.surfaceNoticings,
+      plan,
+      nextDispatch: prepared,
+      suggestion: prepared.blockers[0],
+    };
+  }
+
+  return {
+    phase: 'dispatch',
+    action: turn.action,
+    rationale: turn.rationale,
+    shouldAskUser: turn.shouldAskUser,
+    surfaceNoticings: turn.result.surfaceNoticings,
+    plan,
+    nextDispatch: prepared,
+    estimatedCost: plan.estimatedCost,
+  };
+}
+
+/**
+ * Called after a wave completes. Processes debriefs and determines next action.
+ *
+ * @param {string[]} rawResults - raw output from each agent in the completed wave
+ * @param {string} completedWaveId - which wave just finished
+ * @param {object} context
+ * @returns {LoopResult}
+ */
+export function advance(rawResults, completedWaveId, context = {}) {
+  const loopState = loadLoopState();
+  const plan = loopState.activePlan;
+
+  if (!plan) {
+    return { phase: 'done', action: { type: 'respond', mode: 'direct' }, rationale: 'No active plan', plan: null, nextDispatch: null };
+  }
+
+  // Parse debriefs from raw results
+  const debriefs = rawResults.map(r => parseDebrief(r));
+
+  // Track dispatch outcomes in HEAD state for self-awareness
+  const headState = loadState();
+  for (const d of debriefs) {
+    recordDispatchOutcome(headState, { type: d.artifacts?.tier || 'execute', objective: completedWaveId, status: d.status, durationMs: 0 });
+  }
+
+  const waveSummary = summarizeWaveOutcome(debriefs);
+  // Bridge field names between debrief (scopeDelta) and wave-planner (scopeChange)
+  waveSummary.scopeChange = waveSummary.scopeDelta;
+  waveSummary.confidence = waveSummary.aggregateConfidence;
+  waveSummary.blockers = waveSummary.allBlockers;
+
+  // Record
+  loopState.debriefs.push(...debriefs);
+  loopState.completedWaves.push(completedWaveId);
+
+  // Evolve prediction accuracy
+  const predictions = loopState._lastPredictions || [];
+  for (const d of debriefs) {
+    evolvePatterns(d, predictions);
+  }
+
+  // Post-wave verbal reflection (Reflexion pattern)
+  _postWaveReflection(waveSummary, loopState);
+
+  // Check if we need to replan
+  const needsReplan = shouldReplan(plan, waveSummary);
+
+  let activePlan = plan;
+  if (needsReplan) {
+    // Integrate each debrief into situation progressively
+    let updatedSituation = loopState.situationHistory[loopState.situationHistory.length - 1] || {};
+    for (const d of debriefs) {
+      updatedSituation = integrateDebrief(updatedSituation, d);
+    }
+
+    activePlan = replan(plan, waveSummary, { situation: updatedSituation, result: { depth: plan._depth || 'full' } });
+    loopState.activePlan = activePlan;
+    loopState.replans++;
+  }
+
+  // Find next wave to dispatch
+  const nextWave = activePlan.waves.find(w => !loopState.completedWaves.includes(w.id));
+
+  if (!nextWave) {
+    // All waves done — synthesize
+    const finalSummary = summarizeWaveOutcome(loopState.debriefs);
+
+    // Clean expired inbox messages now that all work is complete
+    try { purgeInbox(); } catch { /* non-fatal */ }
+
+    saveLoopState(loopState);
+    return {
+      phase: 'done',
+      action: { type: 'synthesize', mode: 'complete' },
+      rationale: `All ${loopState.completedWaves.length} waves complete. ${loopState.replans} replan(s).`,
+      plan: activePlan,
+      nextDispatch: null,
+      waveSummary: finalSummary,
+      replanned: needsReplan,
+    };
+  }
+
+  // Check gate condition
+  if (nextWave.gateCondition) {
+    const gateMet = evaluateGate(nextWave.gateCondition, waveSummary, loopState);
+    if (!gateMet) {
+      saveLoopState(loopState);
+      return {
+        phase: 'gated',
+        action: { type: 'pause', mode: 'gate-unmet' },
+        rationale: `Gate condition not met: ${nextWave.gateCondition}`,
+        plan: activePlan,
+        nextDispatch: null,
+        waveSummary,
+        gateCondition: nextWave.gateCondition,
+      };
+    }
+  }
+
+  // Prepare next wave
+  const lastDeliberation = { situation: context, result: { depth: activePlan._depth || 'full' } };
+  const prepared = prepareWave(nextWave, lastDeliberation, { ...context, priorDebriefs: loopState.debriefs }, loopState);
+
+  saveLoopState(loopState);
+
+  return {
+    phase: 'dispatch',
+    action: { type: 'dispatch', mode: nextWave.phase },
+    rationale: `Wave ${loopState.completedWaves.length + 1}/${activePlan.waves.length}: ${nextWave.phase}`,
+    plan: activePlan,
+    nextDispatch: prepared,
+    waveSummary,
+    replanned: needsReplan,
+  };
+}
+
+/**
+ * Prepare a wave for dispatch: run predictions, generate preventions, check readiness.
+ */
+function prepareWave(wave, deliberation, context, loopState) {
+  const agents = wave.agents.map(agentSpec => {
+    // Predict failure modes for this agent
+    const predictions = predictFailureModes(agentSpec, {
+      priorDebriefs: context.priorDebriefs || [],
+      diagnosticPatterns: getCachedPatterns(),
+      files: context.files || [],
+    });
+
+    // Generate prevention instructions
+    const preventions = generatePreventions(predictions);
+
+    // Generate debrief instruction
+    const debriefInstruction = generateDebriefInstruction(agentSpec.tier, {
+      objective: agentSpec.objective,
+      scope: agentSpec.scope,
+    });
+
+    // Score readiness
+    const readiness = scoreDispatchReadiness(agentSpec, { waves: [wave] }, predictions);
+
+    // Check inbox for messages relevant to this worker tier
+    const workerInbox = generateInboxBrief(`worker:${agentSpec.tier}`);
+
+    return {
+      ...agentSpec,
+      preventions,
+      debriefInstruction,
+      readiness,
+      predictions,
+      prompt: buildAgentPrompt(agentSpec, preventions, debriefInstruction, workerInbox),
+    };
+  });
+
+  // Store predictions for later evolution
+  loopState._lastPredictions = agents.flatMap(a => a.predictions);
+
+  return {
+    waveId: wave.id,
+    phase: wave.phase,
+    parallel: wave.parallel,
+    agents,
+    allReady: agents.every(a => a.readiness.ready),
+    blockers: agents.flatMap(a => a.readiness.blockers),
+    warnings: agents.flatMap(a => a.readiness.warnings),
+  };
+}
+
+/**
+ * Build the full prompt for an agent using dispatch envelopes.
+ * Workers get understanding (prose preamble), not just instructions.
+ */
+function buildAgentPrompt(agentSpec, preventions, debriefInstruction, inboxBrief) {
+  const envelope = buildEnvelope(agentSpec, {
+    preventions,
+    debriefInstruction,
+    inboxBrief,
+  });
+  return envelope.full;
+}
+
+/**
+ * Evaluate a wave gate condition against the current state.
+ */
+function evaluateGate(condition, waveSummary, loopState) {
+  const lower = condition.toLowerCase();
+
+  if (lower.includes('confidence') && lower.includes('above')) {
+    const threshold = parseFloat(condition.match(/[\d.]+/)?.[0] || '0.5');
+    return (waveSummary.aggregateConfidence || 0) >= threshold;
+  }
+
+  if (lower.includes('no blocker')) {
+    return (waveSummary.allBlockers || []).length === 0;
+  }
+
+  if (lower.includes('scope confirmed')) {
+    return waveSummary.scopeDelta === 'same' || waveSummary.scopeDelta === 'smaller';
+  }
+
+  // Default: gate passes
+  return true;
+}
+
+// ── Immersion helpers ──────────────────────────────────────────────────────
+
+/**
+ * Evolve HEAD's running narrative after processing a turn.
+ * Captures: what happened, what was decided, what the user cared about.
+ */
+function _evolveNarrative(turn, userMessage, context) {
+  const parts = [];
+
+  // What the user said (compressed)
+  const userSnippet = userMessage.length > 120 ? userMessage.slice(0, 120) + '...' : userMessage;
+  parts.push(`User: "${userSnippet}"`);
+
+  // What HEAD decided
+  const action = turn.action;
+  if (action.type === 'dispatch') {
+    parts.push(`Decision: dispatch ${action.mode || 'work'} (confidence: ${turn.result.confidence.score})`);
+  } else if (action.type === 'respond') {
+    parts.push(`Decision: respond directly (${turn.depth} depth)`);
+  } else if (action.type === 'clarify') {
+    parts.push(`Decision: need clarification`);
+  }
+
+  // Noticings worth remembering
+  if (turn.result.surfaceNoticings?.length) {
+    parts.push(`Noticed: ${turn.result.surfaceNoticings.join('; ')}`);
+  }
+
+  // Crystallized simmer items surfaced this turn
+  if (context._crystallizedIdeas?.length) {
+    parts.push(`Crystallized ideas surfaced: ${context._crystallizedIdeas.join('; ')}`);
+  }
+
+  narrative.evolve(parts.join('. '));
+}
+
+/**
+ * Capture signals from user message that might be simmer-worthy.
+ * Looks for: analogies, "what if" ideas, vague suggestions, meta-observations.
+ */
+function _captureSimmerSignals(userMessage, turn) {
+  const lower = userMessage.toLowerCase();
+
+  // Skip short/command messages
+  if (userMessage.length < 30) return;
+
+  // Detect idea-like patterns
+  const ideaPatterns = [
+    /what if (.{10,80})/i,
+    /maybe (?:we |it |this )(.{10,80})/i,
+    /i feel like (.{10,80})/i,
+    /(?:like|similar to) (.{10,80}?)(?: - | — |\.|\?|$)/i,
+    /consider (.{10,80})/i,
+  ];
+
+  for (const pattern of ideaPatterns) {
+    const match = userMessage.match(pattern);
+    if (match) {
+      simmer.add(match[0].slice(0, 120), { origin: 'user-message' });
+      return; // One simmer per message max
+    }
+  }
+
+  // If the message is exploratory (questions about approach) and depth is "full" or "deep",
+  // the whole message might be worth simmering
+  if (turn.depth === 'deep' && /\?/.test(userMessage) && userMessage.length > 60) {
+    const isExploration = /how|should|could|what about|think/i.test(lower);
+    if (isExploration) {
+      simmer.add(userMessage.slice(0, 150), { origin: 'exploratory-question', initialHeat: 1.5 });
+    }
+  }
+}
+
+/**
+ * Post-wave narrative reflection — called after advance() processes debriefs.
+ * This is the verbal self-reflection piece (Reflexion pattern).
+ */
+function _postWaveReflection(waveSummary, loopState) {
+  const parts = [];
+
+  parts.push(`Wave ${loopState.completedWaves.length} complete.`);
+
+  if (waveSummary.aggregateConfidence != null) {
+    parts.push(`Confidence: ${waveSummary.aggregateConfidence.toFixed(2)}`);
+  }
+
+  if (waveSummary.allBlockers?.length) {
+    parts.push(`Blockers emerged: ${waveSummary.allBlockers.join('; ')}`);
+  }
+
+  if (waveSummary.scopeDelta && waveSummary.scopeDelta !== 'same') {
+    parts.push(`Scope shifted: ${waveSummary.scopeDelta}`);
+  }
+
+  if (loopState.replans > 0) {
+    parts.push(`Replanned ${loopState.replans} time(s) — adapting to reality.`);
+  }
+
+  narrative.evolve(parts.join(' '));
+}
+
+/**
+ * Check for update notice and surface it to HEAD's awareness.
+ */
+function _checkUpdateNotice(context) {
+  try {
+    const noticeFile = join(LOOP_STATE_DIR, '.update-notice');
+    if (!existsSync(noticeFile)) return;
+    const notice = JSON.parse(readFileSync(noticeFile, 'utf8'));
+    if (Date.now() - notice.ts < 5 * 60 * 1000) {
+      context._updateNotice = `Updated dual-brain ${notice.from} → ${notice.to}`;
+    }
+    // Clear it after reading (one-shot)
+    try { writeFileSync(noticeFile, ''); } catch {}
+  } catch {}
+}
+
+// ── Query functions ─────────────────────────────────────────────────────────
+
+export function getActivePlan() {
+  return loadLoopState().activePlan;
+}
+
+export function getLoopStatus() {
+  const state = loadLoopState();
+  return {
+    hasActivePlan: !!state.activePlan,
+    completedWaves: state.completedWaves.length,
+    totalWaves: state.activePlan?.waves?.length || 0,
+    replans: state.replans,
+    totalDispatches: state.totalDispatches,
+    debriefCount: state.debriefs.length,
+  };
+}
+
+export function resetLoop() {
+  saveLoopState(freshLoopState());
+  releaseSession();
+}
+
+export function shutdown() {
+  releaseSession();
+}

package/src/continuity.mjs

@@ -32,13 +32,13 @@ import { join } from 'node:path';
  */
 export function generateHandoff(sessionState) {
   return {
-    version: 1,
+    version: 2,
     timestamp: new Date().toISOString(),
     task: sessionState.taskDescription || null,
     progress: {
       filesChanged: (sessionState.filesChanged || []).slice(0, 20),
       testsRun: sessionState.testsRun || [],
-      decisions: (sessionState.decisions || []).slice(0, 5), // most recent routing decisions
+      decisions: (sessionState.decisions || []).slice(0, 5),
     },
     unresolved: (sessionState.unresolved || []).slice(0, 5),
     routing: {
@@ -48,19 +48,20 @@ export function generateHandoff(sessionState) {
     },
     preferences: sessionState.activePreferences || [],
     resumeHint: sessionState.resumeHint || null,
+    narrative: sessionState.narrative || null,
   };
 }
 
 // ─── Handoff persistence ──────────────────────────────────────────────────────
 
 /**
- * Persist a handoff object to .dual-brain/handoffs/.
+ * Persist a handoff object to .dualbrain/handoffs/.
  * @param {object} handoff   Result of generateHandoff()
  * @param {string} [cwd]     Project root (defaults to process.cwd())
  * @returns {string}         Absolute path of the written file
  */
 export function saveHandoff(handoff, cwd) {
-  const dir = join(cwd || process.cwd(), '.dual-brain', 'handoffs');
+  const dir = join(cwd || process.cwd(), '.dualbrain', 'handoffs');
   mkdirSync(dir, { recursive: true });
   const filename = `handoff-${Date.now()}.json`;
   writeFileSync(join(dir, filename), JSON.stringify(handoff, null, 2));
@@ -68,13 +69,13 @@ export function saveHandoff(handoff, cwd) {
 }
 
 /**
- * Load the most recent handoff from .dual-brain/handoffs/.
+ * Load the most recent handoff from .dualbrain/handoffs/.
  * Returns null when no handoffs exist or all are unreadable.
  * @param {string} [cwd]
  * @returns {object|null}
  */
 export function getLatestHandoff(cwd) {
-  const dir = join(cwd || process.cwd(), '.dual-brain', 'handoffs');
+  const dir = join(cwd || process.cwd(), '.dualbrain', 'handoffs');
   if (!existsSync(dir)) return null;
   const files = readdirSync(dir)
     .filter(f => f.startsWith('handoff-') && f.endsWith('.json'))
@@ -196,7 +197,7 @@ export function buildResumeBrief(cwd) {
  * @returns {number}  Count of files pruned
  */
 export function pruneHandoffs(cwd, keep = 10) {
-  const dir = join(cwd || process.cwd(), '.dual-brain', 'handoffs');
+  const dir = join(cwd || process.cwd(), '.dualbrain', 'handoffs');
   if (!existsSync(dir)) return 0;
   const files = readdirSync(dir)
     .filter(f => f.startsWith('handoff-') && f.endsWith('.json'))
@@ -227,7 +228,7 @@ export function pruneHandoffs(cwd, keep = 10) {
  * }}
  */
 export function extractRoutingPatterns(cwd) {
-  const dir = join(cwd || process.cwd(), '.dual-brain', 'handoffs');
+  const dir = join(cwd || process.cwd(), '.dualbrain', 'handoffs');
   if (!existsSync(dir)) return { patterns: [], confidence: 0, sampleSize: 0 };
 
   const files = readdirSync(dir)

package/src/cost-tracker.mjs

@@ -1,4 +1,4 @@
-// cost-tracker.mjs — Lightweight cost estimation and efficiency tracking for .dual-brain/costs.jsonl.
+// cost-tracker.mjs — Lightweight cost estimation and efficiency tracking for .dualbrain/costs.jsonl.
 
 import { readFileSync, appendFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
@@ -21,7 +21,7 @@ export function estimateTokenCost(model, tokens) {
 
 export function trackCost(action, cwd = process.cwd()) {
   try {
-    const dir = join(cwd, '.dual-brain');
+    const dir = join(cwd, '.dualbrain');
     mkdirSync(dir, { recursive: true });
     const entry = {
       timestamp:      new Date().toISOString(),
@@ -41,7 +41,7 @@ export function trackCost(action, cwd = process.cwd()) {
 }
 
 function readCostLines(cwd) {
-  const p = join(cwd, '.dual-brain', 'costs.jsonl');
+  const p = join(cwd, '.dualbrain', 'costs.jsonl');
   if (!existsSync(p)) return [];
   try {
     return readFileSync(p, 'utf8').trim().split('\n').filter(Boolean).flatMap(line => {