@cleocode/core 2026.4.14 → 2026.4.16

package/src/memory/brain-retrieval.ts

@@ -58,6 +58,8 @@ export interface SearchBrainCompactParams {
   tables?: Array<'decisions' | 'patterns' | 'learnings' | 'observations'>;
   dateStart?: string;
   dateEnd?: string;
+  /** T418: filter results to observations produced by a specific agent (Wave 8 mental models). */
+  agent?: string;
 }
 
 /** Result from searchBrainCompact. */
@@ -121,6 +123,8 @@ export interface ObserveBrainParams {
   project?: string;
   sourceSessionId?: string;
   sourceType?: BrainObservationSourceType;
+  /** T417: agent provenance — the name of the spawned agent producing this observation. */
+  agent?: string;
 }
 
 /** Result from observeBrain. */
@@ -149,15 +153,21 @@ export async function searchBrainCompact(
   projectRoot: string,
   params: SearchBrainCompactParams,
 ): Promise<SearchBrainCompactResult> {
-  const { query, limit, tables, dateStart, dateEnd } = params;
+  const { query, limit, tables, dateStart, dateEnd, agent } = params;
 
   if (!query || !query.trim()) {
     return { results: [], total: 0, tokensEstimated: 0 };
   }
 
+  // T418: when agent filter is set, restrict search to observations table only
+  const effectiveTables =
+    agent !== undefined && agent !== null
+      ? (['observations'] as Array<'decisions' | 'patterns' | 'learnings' | 'observations'>)
+      : tables;
+
   const searchResult = await searchBrain(projectRoot, query, {
     limit: limit ?? 10,
-    tables,
+    tables: effectiveTables,
   });
 
   // Project full results to compact format.
@@ -166,38 +176,45 @@ export async function searchBrainCompact(
   // We handle both naming conventions for robustness.
   let results: BrainCompactHit[] = [];
 
-  for (const d of searchResult.decisions) {
-    const raw = d as Record<string, unknown>;
-    results.push({
-      id: d.id,
-      type: 'decision',
-      title: d.decision.slice(0, 80),
-      date: (d.createdAt ?? (raw['created_at'] as string)) || '',
-    });
-  }
+  if (!agent) {
+    for (const d of searchResult.decisions) {
+      const raw = d as Record<string, unknown>;
+      results.push({
+        id: d.id,
+        type: 'decision',
+        title: d.decision.slice(0, 80),
+        date: (d.createdAt ?? (raw['created_at'] as string)) || '',
+      });
+    }
 
-  for (const p of searchResult.patterns) {
-    const raw = p as Record<string, unknown>;
-    results.push({
-      id: p.id,
-      type: 'pattern',
-      title: p.pattern.slice(0, 80),
-      date: (p.extractedAt ?? (raw['extracted_at'] as string)) || '',
-    });
-  }
+    for (const p of searchResult.patterns) {
+      const raw = p as Record<string, unknown>;
+      results.push({
+        id: p.id,
+        type: 'pattern',
+        title: p.pattern.slice(0, 80),
+        date: (p.extractedAt ?? (raw['extracted_at'] as string)) || '',
+      });
+    }
 
-  for (const l of searchResult.learnings) {
-    const raw = l as Record<string, unknown>;
-    results.push({
-      id: l.id,
-      type: 'learning',
-      title: l.insight.slice(0, 80),
-      date: (l.createdAt ?? (raw['created_at'] as string)) || '',
-    });
+    for (const l of searchResult.learnings) {
+      const raw = l as Record<string, unknown>;
+      results.push({
+        id: l.id,
+        type: 'learning',
+        title: l.insight.slice(0, 80),
+        date: (l.createdAt ?? (raw['created_at'] as string)) || '',
+      });
+    }
   }
 
   for (const o of searchResult.observations) {
     const raw = o as Record<string, unknown>;
+    // T418: apply agent post-filter when specified
+    if (agent) {
+      const rowAgent = o.agent ?? (raw['agent'] as string | null) ?? null;
+      if (rowAgent !== agent) continue;
+    }
     results.push({
       id: o.id,
       type: 'observation',
@@ -524,7 +541,15 @@ export async function observeBrain(
   projectRoot: string,
   params: ObserveBrainParams,
 ): Promise<ObserveBrainResult> {
-  const { text, title: titleParam, type: typeParam, project, sourceSessionId, sourceType } = params;
+  const {
+    text,
+    title: titleParam,
+    type: typeParam,
+    project,
+    sourceSessionId,
+    sourceType,
+    agent,
+  } = params;
 
   if (!text || !text.trim()) {
     throw new Error('Observation text is required');
@@ -588,6 +613,7 @@ export async function observeBrain(
     project: project ?? null,
     sourceSessionId: validSessionId,
     sourceType: sourceType ?? 'agent',
+    agent: agent ?? null,
     createdAt: now,
   });
 

package/src/memory/embedding-local.ts

@@ -10,11 +10,11 @@
  * @task T136
  * @why Ship vector search out-of-the-box without external API keys
  * @what Local embedding provider using @huggingface/transformers all-MiniLM-L6-v2
- * @remarks Migrated from @xenova/transformers (v2) to @huggingface/transformers
- *   (v4) — the upstream rename, same author. v4 drops the deprecated
- *   prebuild-install transitive (via sharp@0.34+) and ships with newer
- *   onnxruntime. Public API (`pipeline`, `FeatureExtractionPipeline`) is
- *   unchanged; Xenova-hosted models still resolve by their original names.
+ * @remarks Brain embeddings are a FIRST-CLASS CLEO feature — the transformers
+ *   package is a regular dependency of `@cleocode/core`, not optional.
+ *   Migrated from `@xenova/transformers` v2 to `@huggingface/transformers`
+ *   v4 (upstream rename, same author) which drops the deprecated
+ *   `prebuild-install` transitive via `sharp@0.34+`.
  */
 
 import type { EmbeddingProvider } from './brain-embedding.js';

package/src/memory/engine-compat.ts

@@ -35,6 +35,8 @@ import {
   searchLearnings,
   storeLearning,
 } from './learnings.js';
+// T419: async reinforcement queue for mental-model writes (ULTRAPLAN L5)
+import { isMentalModelObservation, mentalModelQueue } from './mental-model-queue.js';
 // BRAIN memory imports (T4770)
 import {
   patternStats,
@@ -412,6 +414,8 @@ export async function memoryFind(
     tables?: string[];
     dateStart?: string;
     dateEnd?: string;
+    /** T418: filter results to observations produced by a specific agent. */
+    agent?: string;
   },
   projectRoot?: string,
 ): Promise<EngineResult> {
@@ -425,6 +429,7 @@ export async function memoryFind(
         | undefined,
       dateStart: params.dateStart,
       dateEnd: params.dateEnd,
+      agent: params.agent,
     });
     return { success: true, data: result };
   } catch (error) {
@@ -536,19 +541,36 @@ export async function memoryObserve(
     project?: string;
     sourceSessionId?: string;
     sourceType?: string;
+    /** T417: agent provenance — name of the spawned agent producing this observation. */
+    agent?: string;
   },
   projectRoot?: string,
 ): Promise<EngineResult> {
   try {
     const root = resolveRoot(projectRoot);
-    const result = await observeBrain(root, {
+    const observeParams: ObserveBrainParams = {
       text: params.text,
       title: params.title,
       type: params.type as ObserveBrainParams['type'],
       project: params.project,
       sourceSessionId: params.sourceSessionId,
       sourceType: params.sourceType as ObserveBrainParams['sourceType'],
-    });
+      agent: params.agent,
+    };
+
+    // T419: route mental-model observations (agent-tagged, relevant type) through
+    // the async reinforcement queue for non-blocking writes (ULTRAPLAN L5).
+    // All other observations use the existing synchronous path.
+    let result: Awaited<ReturnType<typeof observeBrain>>;
+    if (isMentalModelObservation(observeParams) && observeParams.agent) {
+      result = await mentalModelQueue.enqueue(root, {
+        ...observeParams,
+        agent: observeParams.agent,
+      });
+    } else {
+      result = await observeBrain(root, observeParams);
+    }
+
     return { success: true, data: result };
   } catch (error) {
     return {

package/src/memory/mental-model-injection.ts

@@ -0,0 +1,87 @@
+/**
+ * Pure helpers for validate-on-load mental-model injection.
+ *
+ * These helpers are used by:
+ *   - The Pi CANT bridge (cleo-cant-bridge.ts) to build the system-prompt block
+ *   - T421 empirical tests to assert on preamble content without a real Pi runtime
+ *
+ * No I/O. Safe to call in tests without a real DB or Pi extension context.
+ *
+ * @task T420
+ * @epic T377
+ * @wave W8
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Minimal observation shape returned by memoryFind / searchBrainCompact. */
+export interface MentalModelObservation {
+  /** Brain DB observation ID (O- prefix). */
+  id: string;
+  /** Observation type: discovery, change, feature, decision, bugfix, refactor, etc. */
+  type: string;
+  /** Short observation title or truncated text. */
+  title: string;
+  /** ISO date string for display. */
+  date?: string;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Preamble text injected into the Pi system prompt when an agent has a
+ * `mental_model:` CANT block. The agent MUST re-evaluate each observation
+ * against the current project state before acting.
+ *
+ * Exported so empirical tests (T421) can assert on its presence.
+ */
+export const VALIDATE_ON_LOAD_PREAMBLE =
+  '===== MENTAL MODEL (validate-on-load) =====\n' +
+  'These are your prior observations, patterns, and learnings for this project.\n' +
+  'Before acting, you MUST re-evaluate each entry against current project state.\n' +
+  'If an entry is stale, note it and proceed with fresh understanding.';
+
+// ============================================================================
+// Pure helpers
+// ============================================================================
+
+/**
+ * Build the validate-on-load mental-model injection string.
+ *
+ * Pure function — no I/O, safe to call in tests without a real DB.
+ *
+ * @param agentName - Name of the spawned agent (used in the header line).
+ * @param observations - Prior mental-model observations to list.
+ * @returns System-prompt block containing the preamble and numbered observations,
+ *          or an empty string when `observations` is empty.
+ *
+ * @example
+ * ```ts
+ * const block = buildMentalModelInjection('my-agent', [
+ *   { id: 'O-abc1', type: 'discovery', title: 'Auth uses JWT', date: '2026-04-08' },
+ * ]);
+ * // block contains VALIDATE_ON_LOAD_PREAMBLE + numbered list
+ * ```
+ */
+export function buildMentalModelInjection(
+  agentName: string,
+  observations: MentalModelObservation[],
+): string {
+  if (observations.length === 0) return '';
+
+  const lines: string[] = ['', `// Agent: ${agentName}`, VALIDATE_ON_LOAD_PREAMBLE, ''];
+
+  for (let i = 0; i < observations.length; i++) {
+    const obs = observations[i];
+    const datePart = obs.date ? ` [${obs.date}]` : '';
+    lines.push(`${i + 1}. [${obs.id}] (${obs.type})${datePart}: ${obs.title}`);
+  }
+
+  lines.push('===== END MENTAL MODEL =====');
+
+  return lines.join('\n');
+}

package/src/memory/mental-model-queue.ts

@@ -0,0 +1,291 @@
+/**
+ * Async reinforcement queue for non-blocking mental-model writes.
+ *
+ * ULTRAPLAN L5 compliance: observations tagged with an `agent` provenance and a
+ * mental-model-relevant type ('discovery', 'change', 'feature', 'decision') are
+ * routed through this queue instead of writing synchronously to brain.db. This
+ * decouples the hot path (agent execution) from I/O latency.
+ *
+ * The queue is drained to brain.db either:
+ *   1. Periodically — every {@link FLUSH_INTERVAL_MS} milliseconds via a timer.
+ *   2. On high watermark — when the queue exceeds {@link FLUSH_WATERMARK} entries.
+ *   3. On process exit — SIGINT, SIGTERM, and 'exit' hooks perform a best-effort
+ *      synchronous flush so no observations are lost.
+ *
+ * Observations without an `agent` field continue to use the existing synchronous
+ * path in observeBrain() and are never routed here.
+ *
+ * @task T383/T419
+ * @epic T377
+ */
+
+import type { ObserveBrainParams, ObserveBrainResult } from './brain-retrieval.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Drain interval in milliseconds. */
+const FLUSH_INTERVAL_MS = 5_000;
+
+/** Drain when queue exceeds this many entries, regardless of timer. */
+const FLUSH_WATERMARK = 50;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Queued observation entry with its write callback. */
+interface QueuedObservation {
+  /** Project root the observation is scoped to. */
+  projectRoot: string;
+  /** Full observation parameters, including the required `agent` field. */
+  params: ObserveBrainParams & { agent: string };
+  /** Resolve callback — called with the persisted result after flush. */
+  resolve: (result: ObserveBrainResult) => void;
+  /** Reject callback — called if the observation cannot be persisted. */
+  reject: (err: Error) => void;
+}
+
+/**
+ * Public interface for the mental-model queue singleton.
+ *
+ * @example
+ * ```ts
+ * const q = getMentalModelQueue();
+ * await q.enqueue(projectRoot, { text: 'Agent learned X', agent: 'my-agent', ... });
+ * const remaining = q.size();
+ * await q.flush();
+ * ```
+ */
+export interface MentalModelQueue {
+  /**
+   * Enqueue a mental-model observation for async write.
+   *
+   * Returns a Promise that resolves with the persisted {@link ObserveBrainResult}
+   * once the batch flush runs. Non-blocking for the caller.
+   *
+   * @param projectRoot - Project root directory for the brain.db path.
+   * @param params - Observation parameters. MUST include `agent`.
+   */
+  enqueue(
+    projectRoot: string,
+    params: ObserveBrainParams & { agent: string },
+  ): Promise<ObserveBrainResult>;
+
+  /**
+   * Drain the queue immediately.
+   *
+   * Writes all pending observations to brain.db.
+   * Safe to call concurrently — duplicate calls are serialised internally.
+   *
+   * @returns The number of observations successfully drained.
+   */
+  flush(): Promise<number>;
+
+  /** Current number of pending observations in the queue. */
+  size(): number;
+}
+
+// ---------------------------------------------------------------------------
+// Observation types that route through the mental-model queue.
+// ---------------------------------------------------------------------------
+
+/**
+ * Observation types that are considered mental-model relevant and therefore
+ * eligible for async queuing when produced by a named agent.
+ */
+const MENTAL_MODEL_TYPES = new Set<string>([
+  'discovery',
+  'change',
+  'feature',
+  'decision',
+  'bugfix',
+  'refactor',
+]);
+
+// ---------------------------------------------------------------------------
+// Queue implementation
+// ---------------------------------------------------------------------------
+
+/** In-memory queue of pending mental-model observations. */
+const _queue: QueuedObservation[] = [];
+
+/** Whether a flush is currently in progress (prevents re-entrant flushes). */
+let _flushing = false;
+
+/** Whether process-exit hooks have been registered. */
+let _hooksRegistered = false;
+
+/** Handle for the periodic flush timer (undefined = no active timer). */
+let _timer: ReturnType<typeof setInterval> | undefined;
+
+/**
+ * Drain the queue synchronously where possible, or fall back to async writes.
+ * Returns when all observations in the current batch have been persisted.
+ */
+async function drainQueue(): Promise<number> {
+  if (_queue.length === 0) return 0;
+
+  // Snapshot current batch and clear the queue
+  const batch = _queue.splice(0, _queue.length);
+  let count = 0;
+
+  // Import observeBrain lazily to avoid circular dependencies at module load
+  const { observeBrain } = await import('./brain-retrieval.js');
+
+  for (const entry of batch) {
+    try {
+      const result = await observeBrain(entry.projectRoot, entry.params);
+      entry.resolve(result);
+      count++;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      entry.reject(error);
+    }
+  }
+
+  return count;
+}
+
+/**
+ * Best-effort synchronous exit flush.
+ * Used in 'exit' event handler where async I/O is not guaranteed.
+ * Falls back to fire-and-forget if the environment does not support
+ * synchronous-style promises (i.e., in environments where the event
+ * loop may already be draining).
+ */
+function exitFlush(): void {
+  if (_queue.length === 0) return;
+  // We can't reliably await in a synchronous exit handler. The best we
+  // can do is trigger the drain and hope the pending writes complete.
+  drainQueue().catch(() => {
+    // Silently swallow — process is terminating anyway
+  });
+}
+
+/**
+ * Register process-exit hooks once.
+ * Ensures that no observations are silently dropped on graceful shutdown.
+ */
+function registerExitHooks(): void {
+  if (_hooksRegistered) return;
+  _hooksRegistered = true;
+
+  process.on('exit', exitFlush);
+
+  process.once('SIGINT', () => {
+    drainQueue()
+      .catch(() => {
+        /* best-effort */
+      })
+      .finally(() => {
+        process.exit(130); // 128 + SIGINT
+      });
+  });
+
+  process.once('SIGTERM', () => {
+    drainQueue()
+      .catch(() => {
+        /* best-effort */
+      })
+      .finally(() => {
+        process.exit(143); // 128 + SIGTERM
+      });
+  });
+}
+
+/**
+ * Start the periodic flush timer if it isn't already running.
+ */
+function ensureTimer(): void {
+  if (_timer !== undefined) return;
+  _timer = setInterval(() => {
+    if (_queue.length === 0) return;
+    if (_flushing) return;
+    _flushing = true;
+    drainQueue()
+      .catch(() => {
+        /* best-effort */
+      })
+      .finally(() => {
+        _flushing = false;
+      });
+  }, FLUSH_INTERVAL_MS);
+  // Unref so the timer doesn't prevent process exit when queue is idle
+  if (typeof _timer.unref === 'function') {
+    _timer.unref();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public singleton
+// ---------------------------------------------------------------------------
+
+/**
+ * Mental-model queue singleton.
+ *
+ * Use this instead of calling observeBrain() directly when writing agent-tagged
+ * observations that should be queued for async persistence (ULTRAPLAN L5).
+ */
+export const mentalModelQueue: MentalModelQueue = {
+  enqueue(
+    projectRoot: string,
+    params: ObserveBrainParams & { agent: string },
+  ): Promise<ObserveBrainResult> {
+    registerExitHooks();
+    ensureTimer();
+
+    return new Promise<ObserveBrainResult>((resolve, reject) => {
+      _queue.push({ projectRoot, params, resolve, reject });
+
+      // High-watermark flush
+      if (_queue.length >= FLUSH_WATERMARK && !_flushing) {
+        _flushing = true;
+        drainQueue()
+          .catch(() => {
+            /* best-effort */
+          })
+          .finally(() => {
+            _flushing = false;
+          });
+      }
+    });
+  },
+
+  async flush(): Promise<number> {
+    if (_flushing) {
+      // Wait for the current flush to settle then flush again
+      await new Promise<void>((r) => setTimeout(r, 50));
+    }
+    _flushing = true;
+    try {
+      return await drainQueue();
+    } finally {
+      _flushing = false;
+    }
+  },
+
+  size(): number {
+    return _queue.length;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine whether an observation should be routed through the mental-model
+ * queue rather than written synchronously.
+ *
+ * Returns `true` when the observation has a non-empty `agent` field AND a
+ * mental-model-relevant type.
+ *
+ * @param params - Observation parameters to evaluate.
+ */
+export function isMentalModelObservation(params: ObserveBrainParams): boolean {
+  if (!params.agent) return false;
+  const type = params.type ?? 'discovery';
+  return MENTAL_MODEL_TYPES.has(type);
+}

package/src/orchestration/index.ts

@@ -55,6 +55,8 @@ export interface SpawnContext {
     fullyResolved: boolean;
     unresolvedTokens: string[];
   };
+  /** Optional compiled CANT agent definition attached by `cleo orchestrate spawn`. */
+  agentDef?: unknown;
 }
 
 /** Task readiness assessment. */