@cleocode/core 2026.3.69 → 2026.3.71

package/src/memory/embedding-queue.ts

@@ -0,0 +1,304 @@
+/**
+ * Embedding Queue Manager
+ *
+ * Manages an async queue of embedding requests, processing them in batches
+ * via a worker thread to avoid blocking the main Node.js event loop.
+ *
+ * Architecture:
+ *   - {@link EmbeddingQueue} is a singleton — one worker thread per process
+ *   - {@link EmbeddingQueue.enqueue} adds items; the drain loop batches them
+ *   - Batches up to {@link BATCH_SIZE} items per processing cycle
+ *   - Falls back to `setImmediate` + direct embedding when worker threads
+ *     are unavailable or the worker script cannot be resolved
+ *   - Registers a `process.on('exit')` handler for graceful shutdown
+ *
+ * @epic T134
+ * @task T137
+ * @why Non-blocking embedding generation for observeBrain()
+ * @what Singleton queue + worker-thread batch processor
+ */
+
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Maximum items processed per worker message cycle. */
+const BATCH_SIZE = 10;
+
+/** How long to wait between drain cycles when the queue is non-empty (ms). */
+const DRAIN_INTERVAL_MS = 50;
+
+/** Pending queue item. */
+interface QueueItem {
+  observationId: string;
+  text: string;
+}
+
+/**
+ * Resolve the absolute path to the compiled embedding-worker script.
+ *
+ * Strategy (cheap-first):
+ * 1. Adjacent to this file (tsc dev: `dist/memory/embedding-worker.js`)
+ * 2. Falls back to null when the file cannot be found (esbuild bundle context)
+ */
+function resolveWorkerPath(): string | null {
+  try {
+    // In ESM, __dirname is not available — use import.meta.url
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    const candidate = join(currentDir, 'embedding-worker.js');
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    // Also try ../ for cases where the queue is loaded from a subdirectory
+    const parentCandidate = join(currentDir, '..', 'memory', 'embedding-worker.js');
+    if (existsSync(parentCandidate)) {
+      return parentCandidate;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Singleton embedding queue.
+ *
+ * Batches embedding requests and processes them via a worker thread,
+ * keeping heavy model inference off the main event loop.
+ *
+ * Use {@link getEmbeddingQueue} to obtain the shared instance.
+ */
+export class EmbeddingQueue {
+  private readonly queue: QueueItem[] = [];
+  private worker: import('node:worker_threads').Worker | null = null;
+  private workerAvailable = false;
+  private draining = false;
+  private shutdownPromise: Promise<void> | null = null;
+
+  /**
+   * Store the observation ID → DB write callback so the worker result
+   * can be persisted back to brain_embeddings without coupling to SQLite here.
+   */
+  private readonly callbacks = new Map<
+    string,
+    (observationId: string, embedding: Float32Array) => Promise<void>
+  >();
+
+  /** Initialise the worker thread if possible. Called lazily on first enqueue. */
+  private async initWorker(): Promise<void> {
+    if (this.workerAvailable || this.worker !== null) return;
+
+    const workerPath = resolveWorkerPath();
+    if (!workerPath) {
+      // esbuild bundle context — worker file not available, use fallback
+      this.workerAvailable = false;
+      return;
+    }
+
+    try {
+      const { Worker } = await import('node:worker_threads');
+      const worker = new Worker(workerPath);
+
+      worker.on('message', (msg: { id: string; embedding?: number[]; error?: string }) => {
+        const cb = this.callbacks.get(msg.id);
+        if (!cb) return;
+        this.callbacks.delete(msg.id);
+
+        if (msg.embedding) {
+          const vector = Float32Array.from(msg.embedding);
+          cb(msg.id, vector).catch(() => {
+            // Persistence is best-effort; observation already saved without vector
+          });
+        }
+        // On error, skip silently — observation exists without embedding
+      });
+
+      worker.on('error', () => {
+        // Worker crashed — disable worker path, drain remaining via fallback
+        this.worker = null;
+        this.workerAvailable = false;
+        this.callbacks.clear();
+      });
+
+      worker.on('exit', () => {
+        this.worker = null;
+        this.workerAvailable = false;
+      });
+
+      this.worker = worker;
+      this.workerAvailable = true;
+    } catch {
+      // worker_threads unavailable (rare)
+      this.workerAvailable = false;
+    }
+  }
+
+  /**
+   * Add an observation to the embedding queue.
+   *
+   * The observation must already be persisted in brain_observations before
+   * calling this method. `onComplete` is called asynchronously with the
+   * generated vector once the worker finishes.
+   *
+   * @param observationId - The brain observation ID (e.g. `O-abc123-0`)
+   * @param text - Raw text to embed
+   * @param onComplete - Callback to persist the embedding vector
+   */
+  enqueue(
+    observationId: string,
+    text: string,
+    onComplete: (observationId: string, embedding: Float32Array) => Promise<void>,
+  ): void {
+    if (this.shutdownPromise) return; // queue is shutting down
+    this.callbacks.set(observationId, onComplete);
+    this.queue.push({ observationId, text });
+    if (!this.draining) {
+      this.scheduleDrain();
+    }
+  }
+
+  /** Schedule the next drain cycle via setImmediate. */
+  private scheduleDrain(): void {
+    setImmediate(() => {
+      this.drain().catch(() => {
+        // Drain errors are non-fatal
+        this.draining = false;
+      });
+    });
+  }
+
+  /**
+   * Process up to {@link BATCH_SIZE} items from the queue.
+   * Uses the worker thread when available, falls back to inline setImmediate.
+   */
+  private async drain(): Promise<void> {
+    this.draining = true;
+
+    // Ensure worker is initialised (no-op after first call)
+    await this.initWorker();
+
+    while (this.queue.length > 0) {
+      const batch = this.queue.splice(0, BATCH_SIZE);
+
+      if (this.workerAvailable && this.worker) {
+        // Dispatch to worker thread — results arrive via 'message' event
+        for (const item of batch) {
+          this.worker.postMessage({ id: item.observationId, text: item.text });
+        }
+      } else {
+        // Fallback: process inline via setImmediate to yield to event loop
+        for (const item of batch) {
+          setImmediate(() => {
+            this.fallbackEmbed(item).catch(() => {
+              // Silently skip — observation already persisted without embedding
+              this.callbacks.delete(item.observationId);
+            });
+          });
+        }
+      }
+
+      if (this.queue.length > 0) {
+        // Yield to event loop between batches
+        await new Promise<void>((resolve) => setTimeout(resolve, DRAIN_INTERVAL_MS));
+      }
+    }
+
+    this.draining = false;
+  }
+
+  /**
+   * Inline fallback embedding — used when worker thread is unavailable.
+   * Runs directly on the main thread (but inside setImmediate to yield first).
+   */
+  private async fallbackEmbed(item: QueueItem): Promise<void> {
+    const cb = this.callbacks.get(item.observationId);
+    if (!cb) return;
+    this.callbacks.delete(item.observationId);
+
+    const { getLocalEmbeddingProvider } = await import('./embedding-local.js');
+    const provider = getLocalEmbeddingProvider();
+    const vector = await provider.embed(item.text);
+    await cb(item.observationId, vector);
+  }
+
+  /**
+   * Flush the queue and terminate the worker thread.
+   *
+   * Waits for in-flight worker messages to drain, then terminates.
+   * Safe to call multiple times — subsequent calls return the same promise.
+   */
+  shutdown(): Promise<void> {
+    if (this.shutdownPromise) return this.shutdownPromise;
+    this.shutdownPromise = this.doShutdown();
+    return this.shutdownPromise;
+  }
+
+  private async doShutdown(): Promise<void> {
+    // Drain remaining queue items
+    if (this.queue.length > 0) {
+      await this.drain();
+    }
+
+    // Terminate the worker
+    if (this.worker) {
+      try {
+        await this.worker.terminate();
+      } catch {
+        // Worker may already be gone
+      }
+      this.worker = null;
+    }
+
+    this.callbacks.clear();
+  }
+}
+
+/** Module-level singleton. */
+let _instance: EmbeddingQueue | null = null;
+
+/**
+ * Get or create the shared EmbeddingQueue singleton.
+ *
+ * Registers a process `exit` handler on first call to flush and
+ * terminate the worker thread cleanly.
+ *
+ * @returns The shared EmbeddingQueue instance.
+ */
+export function getEmbeddingQueue(): EmbeddingQueue {
+  if (!_instance) {
+    _instance = new EmbeddingQueue();
+    // Best-effort flush on process exit (synchronous handlers only get ~50ms)
+    process.on('exit', () => {
+      _instance?.shutdown().catch(() => {
+        // exit handler — cannot await
+      });
+    });
+    // For SIGTERM/SIGINT give the queue time to flush
+    const gracefulShutdown = (): void => {
+      if (_instance) {
+        _instance
+          .shutdown()
+          .catch(() => {})
+          .finally(() => process.exit(0));
+      } else {
+        process.exit(0);
+      }
+    };
+    process.once('SIGTERM', gracefulShutdown);
+    process.once('SIGINT', gracefulShutdown);
+  }
+  return _instance;
+}
+
+/**
+ * Reset the singleton (for testing only).
+ * Shuts down the existing queue before clearing the reference.
+ *
+ * @internal
+ */
+export async function resetEmbeddingQueue(): Promise<void> {
+  if (_instance) {
+    await _instance.shutdown();
+    _instance = null;
+  }
+}

package/src/memory/embedding-worker.ts

@@ -0,0 +1,79 @@
+/**
+ * Embedding Worker Thread Script
+ *
+ * Runs inside a `worker_threads.Worker` to perform embedding generation
+ * off the main thread. Receives messages with text to embed, calls
+ * LocalEmbeddingProvider, and sends results back via parentPort.
+ *
+ * Message protocol:
+ *   Inbound:  { id: string; text: string }
+ *   Outbound: { id: string; embedding: number[] } on success
+ *             { id: string; error: string }       on failure
+ *
+ * @epic T134
+ * @task T137
+ * @why Prevent @xenova/transformers model inference from blocking the main thread
+ * @what Worker thread script for async embedding generation
+ */
+
+import { parentPort } from 'node:worker_threads';
+
+/** Inbound message from the queue manager. */
+interface WorkerRequest {
+  id: string;
+  text: string;
+}
+
+/** Successful embedding result sent to the queue manager. */
+interface WorkerSuccess {
+  id: string;
+  embedding: number[];
+}
+
+/** Error result sent to the queue manager. */
+interface WorkerError {
+  id: string;
+  error: string;
+}
+
+if (!parentPort) {
+  throw new Error('embedding-worker.ts must be run as a worker thread');
+}
+
+const port = parentPort;
+
+/**
+ * Handle a single embedding request from the queue manager.
+ * Imports LocalEmbeddingProvider lazily so the model loads once
+ * per worker lifetime.
+ */
+async function handleRequest(req: WorkerRequest): Promise<void> {
+  try {
+    const { getLocalEmbeddingProvider } = await import('./embedding-local.js');
+    const provider = getLocalEmbeddingProvider();
+    const vector = await provider.embed(req.text);
+    // Transfer as plain number[] — structured clone handles Float32Array
+    const response: WorkerSuccess = {
+      id: req.id,
+      embedding: Array.from(vector),
+    };
+    port.postMessage(response);
+  } catch (err) {
+    const response: WorkerError = {
+      id: req.id,
+      error: err instanceof Error ? err.message : String(err),
+    };
+    port.postMessage(response);
+  }
+}
+
+port.on('message', (req: WorkerRequest) => {
+  handleRequest(req).catch((err) => {
+    // Catch any unhandled rejection in handleRequest itself
+    const response: WorkerError = {
+      id: req.id,
+      error: err instanceof Error ? err.message : String(err),
+    };
+    port.postMessage(response);
+  });
+});

package/src/memory/memory-bridge.ts

@@ -259,10 +259,25 @@ export async function writeMemoryBridge(
 /**
  * Best-effort refresh: call from session.end, tasks.complete, or memory.observe.
  * Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @param scope - Optional session scope for context-aware generation (T139).
+ * @param currentTaskId - Optional current task ID for scoped context (T139).
  */
-export async function refreshMemoryBridge(projectRoot: string): Promise<void> {
+export async function refreshMemoryBridge(
+  projectRoot: string,
+  scope?: string,
+  currentTaskId?: string,
+): Promise<void> {
   try {
-    await writeMemoryBridge(projectRoot);
+    const { loadConfig } = await import('../config.js');
+    const config = await loadConfig(projectRoot);
+
+    if (config.brain?.memoryBridge?.contextAware && scope) {
+      await generateContextAwareContent(projectRoot, scope, currentTaskId);
+    } else {
+      await writeMemoryBridge(projectRoot);
+    }
   } catch (err) {
     console.error(
       '[CLEO] Memory bridge refresh failed:',
@@ -271,6 +286,90 @@ export async function refreshMemoryBridge(projectRoot: string): Promise<void> {
   }
 }
 
+/**
+ * Generate context-aware memory bridge content and write to disk.
+ *
+ * When `brain.memoryBridge.contextAware` is true and a scope is available,
+ * uses hybridSearch() to surface memories relevant to the current scope,
+ * then enforces the `brain.memoryBridge.maxTokens` budget.
+ *
+ * Falls back to standard generation if hybrid search is unavailable.
+ * Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @param scope - Session scope string (e.g. 'global', 'epic:T###').
+ * @param currentTaskId - Optional current task ID for narrower scoping.
+ * @task T139 @epic T134
+ */
+export async function generateContextAwareContent(
+  projectRoot: string,
+  scope: string,
+  currentTaskId?: string,
+): Promise<void> {
+  try {
+    const { loadConfig } = await import('../config.js');
+    const config = await loadConfig(projectRoot);
+    const maxTokens = config.brain?.memoryBridge?.maxTokens ?? 2000;
+
+    // Build a search query from scope + currentTaskId
+    const query = currentTaskId ? `${scope} ${currentTaskId}` : scope;
+
+    let contextSections: string[] = [];
+    try {
+      const { hybridSearch } = await import('./brain-search.js');
+      const hits = await hybridSearch(query, projectRoot, { limit: 10 });
+      if (hits && hits.length > 0) {
+        contextSections = hits
+          .slice(0, 5)
+          .map((h) => `- [${h.id}] ${h.title ?? h.text?.slice(0, 120) ?? ''}`);
+      }
+    } catch {
+      // Hybrid search unavailable — fall back to standard generation
+      await writeMemoryBridge(projectRoot);
+      return;
+    }
+
+    // Build content with token budget enforcement (rough estimate: 4 chars/token)
+    const charsPerToken = 4;
+    const budgetChars = maxTokens * charsPerToken;
+
+    const cleoDir = join(projectRoot, '.cleo');
+    const bridgePath = join(cleoDir, 'memory-bridge.md');
+
+    const headerLines = [
+      '# CLEO Memory Bridge',
+      '',
+      `> Auto-generated at ${new Date().toISOString().slice(0, 19)} (context-aware: ${scope})`,
+      '> Do not edit manually. Regenerate with `cleo refresh-memory`.',
+      '',
+    ];
+
+    const contextBlock =
+      contextSections.length > 0 ? ['## Relevant Context', '', ...contextSections, ''] : [];
+
+    // Append standard content but enforce token budget
+    const standardContent = await generateMemoryBridgeContent(projectRoot);
+    const combined = [...headerLines, ...contextBlock].join('\n');
+    const remainingChars = budgetChars - combined.length;
+
+    const finalContent =
+      remainingChars > 200 ? combined + '\n' + standardContent.slice(0, remainingChars) : combined;
+
+    if (!existsSync(cleoDir)) {
+      mkdirSync(cleoDir, { recursive: true });
+    }
+
+    writeFileSync(bridgePath, finalContent, 'utf-8');
+  } catch {
+    // Best-effort — fall through to standard generation
+    try {
+      await writeMemoryBridge(projectRoot);
+    } catch {
+      // Ignore
+    }
+  }
+}
+
 // ============================================================================
 // Query helpers
 // ============================================================================

package/src/memory/session-memory.ts

@@ -223,6 +223,129 @@ export async function persistSessionMemory(
   return result;
 }
 
+// ============================================================================
+// buildSummarizationPrompt (T140)
+// ============================================================================
+
+/**
+ * Build a summarization prompt from debrief data.
+ *
+ * Returns a formatted prompt string that guides an LLM to produce a structured
+ * session summary (key learnings, decisions, patterns, next actions). The result
+ * can be passed to an LLM or stored directly as a `memoryPrompt` in the session
+ * end result.
+ *
+ * Returns null when debrief contains no meaningful content to summarize.
+ *
+ * @param sessionId - The session ID to summarize.
+ * @param debrief - Rich debrief data from sessionComputeDebrief().
+ * @task T140 @epic T134
+ */
+export function buildSummarizationPrompt(
+  sessionId: string,
+  debrief: DebriefData | null | undefined,
+): string | null {
+  if (!debrief) return null;
+
+  const tasksCompleted = debrief.handoff?.tasksCompleted ?? [];
+  const decisions = (debrief.decisions ?? []) as DebriefDecision[];
+  const note = debrief.handoff?.note ?? '';
+  const nextSuggested = debrief.handoff?.nextSuggested ?? [];
+
+  if (tasksCompleted.length === 0 && decisions.length === 0 && !note) {
+    return null;
+  }
+
+  const parts: string[] = [
+    `Summarize session ${sessionId} for brain memory storage.`,
+    '',
+    `Tasks completed: ${tasksCompleted.join(', ') || 'none'}`,
+  ];
+
+  if (decisions.length > 0) {
+    parts.push('');
+    parts.push('Decisions made:');
+    for (const d of decisions) {
+      parts.push(`- ${d.decision ?? 'unknown'} (rationale: ${d.rationale ?? 'N/A'})`);
+    }
+  }
+
+  if (note) {
+    parts.push('');
+    parts.push(`Session note: ${note}`);
+  }
+
+  if (nextSuggested.length > 0) {
+    parts.push('');
+    parts.push(`Suggested next: ${nextSuggested.join(', ')}`);
+  }
+
+  parts.push('');
+  parts.push(
+    'Produce a JSON object with keys: keyLearnings (string[]), decisions (string[]), patterns (string[]), nextActions (string[]).',
+  );
+
+  return parts.join('\n');
+}
+
+/**
+ * Ingest a structured session summary directly into brain.db.
+ *
+ * Stores each field as a typed brain observation. Best-effort — never throws.
+ *
+ * @param projectRoot - Absolute path to project root.
+ * @param sessionId - The session ID the summary belongs to.
+ * @param summary - Structured summary with key learnings, decisions, patterns, next actions.
+ * @task T140 @epic T134
+ */
+export async function ingestStructuredSummary(
+  projectRoot: string,
+  sessionId: string,
+  summary: import('@cleocode/contracts').SessionSummaryInput,
+): Promise<void> {
+  try {
+    const { observeBrain } = await import('./brain-retrieval.js');
+
+    // Ingest key learnings
+    for (const learning of summary.keyLearnings) {
+      if (!learning.trim()) continue;
+      await observeBrain(projectRoot, {
+        text: learning,
+        title: learning.slice(0, 120),
+        type: 'discovery',
+        sourceSessionId: sessionId,
+        sourceType: 'agent',
+      });
+    }
+
+    // Ingest decisions
+    for (const decision of summary.decisions) {
+      if (!decision.trim()) continue;
+      await observeBrain(projectRoot, {
+        text: decision,
+        title: decision.slice(0, 120),
+        type: 'decision',
+        sourceSessionId: sessionId,
+        sourceType: 'agent',
+      });
+    }
+
+    // Ingest patterns
+    for (const pattern of summary.patterns) {
+      if (!pattern.trim()) continue;
+      await observeBrain(projectRoot, {
+        text: pattern,
+        title: pattern.slice(0, 120),
+        type: 'discovery',
+        sourceSessionId: sessionId,
+        sourceType: 'agent',
+      });
+    }
+  } catch {
+    // Best-effort: must never throw
+  }
+}
+
 // ============================================================================
 // getSessionMemoryContext
 // ============================================================================

package/src/sessions/index.ts

@@ -262,12 +262,8 @@ export async function endSession(
     /* Memory bridge is best-effort */
   });
 
-  // Regenerate .cleo/memory-bridge.md (best-effort, T5240)
-  import('../memory/memory-bridge.js')
-    .then(({ refreshMemoryBridge }) => refreshMemoryBridge(cwd ?? process.cwd()))
-    .catch(() => {
-      /* Memory bridge refresh is best-effort */
-    });
+  // NOTE: Memory bridge refresh is now handled by the onSessionEnd hook
+  // via memory-bridge-refresh.ts (T138). No direct call needed here.
 
   // NOTE: Do NOT clear grade mode env vars here — gradeSession() needs them
   // to query audit entries after the session ends. The caller (admin.grade handler

package/src/store/__tests__/test-db-helper.js

@@ -7,7 +7,7 @@
  *
  * @task T5244
  */
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { resetDbState } from '../sqlite.js';
@@ -26,8 +26,20 @@ export async function createTestDb() {
     const tempDir = mkdtempSync(join(tmpdir(), 'cleo-test-'));
     // Reset singleton to avoid cross-test contamination
     resetDbState();
-    const accessor = await createSqliteDataAccessor(tempDir);
+    // Write test config that disables session enforcement and lifecycle enforcement
+    // so unit tests don't require active sessions or pipeline stage validation.
     const cleoDir = join(tempDir, '.cleo');
+    mkdirSync(cleoDir, { recursive: true });
+    const configContent = JSON.stringify({
+        enforcement: {
+            session: { requiredForMutate: false },
+            acceptance: { mode: 'off' },
+        },
+        lifecycle: { mode: 'off' },
+        verification: { enabled: false },
+    });
+    writeFileSync(join(cleoDir, 'config.json'), configContent);
+    const accessor = await createSqliteDataAccessor(tempDir);
     return {
         tempDir,
         cleoDir,

package/src/store/__tests__/test-db-helper.ts

@@ -48,7 +48,10 @@ export async function createTestDb(): Promise<TestDbEnv> {
   const cleoDir = join(tempDir, '.cleo');
   mkdirSync(cleoDir, { recursive: true });
   const configContent = JSON.stringify({
-    enforcement: { session: { requiredForMutate: false } },
+    enforcement: {
+      session: { requiredForMutate: false },
+      acceptance: { mode: 'off' },
+    },
     lifecycle: { mode: 'off' },
     verification: { enabled: false },
   });