@soleri/core 2.4.0 → 2.5.0

package/src/loop/loop-manager.ts

@@ -1,16 +1,150 @@
 /**
- * Loop manager — lightweight in-memory state tracker for iterative
- * validation loops.
+ * Loop manager — iterative validation loop state tracking with
+ * output scanning and gate decision system.
  *
- * Tracks active loop, iteration history, and past loop results.
- * Session-scoped (no persistence across restarts).
+ * Ported from Salvador's loop.facade.ts with:
+ * - Promise tag extraction (<promise>...</promise>)
+ * - 5-tier heuristic completion detection
+ * - Gate decision pattern (allow/block) for Stop hook integration
+ * - Knowledge tracking for brain session recording
+ *
+ * Session-scoped (in-memory). Persistence is optional via external store.
+ */
+
+import type {
+  LoopConfig,
+  LoopIteration,
+  LoopMode,
+  LoopState,
+  LoopKnowledge,
+  LoopHistoryEntry,
+  LoopIterateDecision,
+} from './types.js';
+
+// ─── Grade ordering for plan-iteration mode ──────────────────────
+const GRADE_ORDER = ['A+', 'A', 'B', 'C', 'D', 'F'];
+
+// ─── Output Scanning ─────────────────────────────────────────────
+
+/**
+ * Extract text between <promise>...</promise> tags from output.
+ * Ported from Salvador's extractPromise.
+ */
+export function extractPromise(text: string): string | null {
+  const match = /<promise>([\s\S]*?)<\/promise>/.exec(text);
+  if (!match) return null;
+  return match[1].trim().replace(/\s+/g, ' ');
+}
+
+/**
+ * 5-tier heuristic completion detection.
+ * Returns a reason string if completion is detected, null otherwise.
+ * Ported from Salvador's detectImplicitCompletion.
+ *
+ * Tiers:
+ * 1. Validation tool score (token-migration, component-build)
+ * 2. Contrast mode — all PASS, no FAIL
+ * 3. Plan mode — grade meets target
+ * 4. Completion language + file modification signals (requires BOTH)
+ * 5. Test pass signals
+ */
+export function detectImplicitCompletion(lastOutput: string, config: LoopConfig): string | null {
+  const text = lastOutput;
+
+  // 1. Validation tool score (token-migration, component-build)
+  if (config.mode === 'token-migration' || config.mode === 'component-build') {
+    const scoreMatch = /"score"\s*:\s*(\d+(?:\.\d+)?)/.exec(text);
+    if (scoreMatch) {
+      const score = parseFloat(scoreMatch[1]);
+      const target = config.targetScore ?? (config.mode === 'token-migration' ? 95 : 90);
+      if (score >= target) {
+        return `Auto-detected: validation score ${score} >= target ${target}`;
+      }
+    }
+  }
+
+  // 2. Contrast mode — all PASS, no FAIL
+  if (config.mode === 'contrast-fix') {
+    const hasPass = /\bPASS\b/i.test(text);
+    const hasFail = /\bFAIL\b/i.test(text);
+    if (hasPass && !hasFail) {
+      return 'Auto-detected: all contrast checks PASS, no FAIL';
+    }
+  }
+
+  // 3. Plan mode — grade meets target
+  if (config.mode === 'plan-iteration') {
+    const gradeMatch = /"grade"\s*:\s*"([A-F][+-]?)"/.exec(text);
+    if (gradeMatch) {
+      const grade = gradeMatch[1];
+      const target = config.targetGrade ?? 'A';
+      const gradeIdx = GRADE_ORDER.indexOf(grade);
+      const targetIdx = GRADE_ORDER.indexOf(target);
+      if (gradeIdx >= 0 && targetIdx >= 0 && gradeIdx <= targetIdx) {
+        return `Auto-detected: plan grade ${grade} >= target ${target}`;
+      }
+    }
+  }
+
+  // 4. Completion language + file modification signals (requires BOTH)
+  const completionPhrases =
+    /\b(task complete|implementation finished|implementation complete|work complete|all done|changes complete|finished implementing|done implementing)\b/i;
+  const fileModPhrases =
+    /\b(file modified|wrote to|saved to|created file|updated file|edited file|changes written)\b/i;
+  if (completionPhrases.test(text) && fileModPhrases.test(text)) {
+    return 'Auto-detected: completion language with file modification evidence';
+  }
+
+  // 5. Test pass signals
+  const testPass =
+    /(\d+)\s+tests?\s+passed[,\s]+0\s+fail/i.test(text) ||
+    /\ball\s+tests?\s+(passing|passed)\b/i.test(text);
+  if (testPass) {
+    return 'Auto-detected: test suite passing';
+  }
+
+  return null;
+}
+
+// ─── Anomaly Detection ──────────────────────────────────────────
+
+/**
+ * Minimum expected duration (ms) per mode.
+ * Iterations finishing faster than this with low scores are flagged as anomalous.
  */
+const MIN_DURATION_MS: Record<LoopMode, number> = {
+  'token-migration': 5000,
+  'contrast-fix': 2000,
+  'component-build': 5000,
+  'plan-iteration': 3000,
+  custom: 0,
+};
+
+/**
+ * Detect anomalous loop iteration patterns.
+ * Flags fast + low-score combos that suggest the agent is spinning without making progress.
+ */
+export function detectAnomaly(iteration: LoopIteration, mode: LoopMode): string | null {
+  const minDuration = MIN_DURATION_MS[mode];
+  if (minDuration === 0) return null; // custom mode — no threshold
+
+  const duration = iteration.durationMs ?? 0;
+  const score = iteration.validationScore ?? 0;
 
-import type { LoopConfig, LoopIteration, LoopState } from './types.js';
+  // Flag: iteration completed very fast with a low score
+  if (duration > 0 && duration < minDuration && !iteration.passed && score < 50) {
+    return `Anomaly: iteration ${iteration.iteration} completed in ${duration}ms (min expected: ${minDuration}ms) with score ${score} — possible no-op loop`;
+  }
+
+  return null;
+}
+
+// ─── LoopManager ─────────────────────────────────────────────────
 
 export class LoopManager {
   private activeLoop: LoopState | null = null;
   private completedLoops: LoopState[] = [];
+  private historyEntries: LoopHistoryEntry[] = [];
 
   /**
    * Start a new validation loop.
@@ -37,9 +171,9 @@ export class LoopManager {
   }
 
   /**
-   * Record an iteration result on the active loop.
+   * Record an iteration result on the active loop (simple API).
    * If the iteration passes, the loop status is NOT automatically changed —
-   * call `completeLoop()` explicitly when validation is confirmed.
+   * call completeLoop() explicitly when validation is confirmed.
    * If max iterations reached and this iteration fails, status becomes 'max-iterations'.
    */
   iterate(result: {
@@ -68,6 +202,7 @@ export class LoopManager {
     ) {
       this.activeLoop.status = 'max-iterations';
       this.activeLoop.completedAt = new Date().toISOString();
+      this.moveToHistory('max_iterations');
       this.completedLoops.push(this.activeLoop);
       this.activeLoop = null;
     }
@@ -75,6 +210,163 @@ export class LoopManager {
     return iteration;
   }
 
+  /**
+   * Gate-based iteration — accepts LLM output and returns allow/block decision.
+   * Ported from Salvador's loop_iterate handler.
+   *
+   * This is the primary method for Stop hook integration:
+   * - Scans output for completion promise tags
+   * - Runs 5-tier heuristic completion detection
+   * - Returns 'block' with injected prompt/systemMessage for next iteration
+   * - Returns 'allow' when loop ends (completed, max_iterations)
+   *
+   * @param lastOutput - The LLM's last response to scan for completion signals
+   * @param knowledge - Optional knowledge items discovered during this iteration
+   */
+  iterateWithGate(
+    lastOutput: string,
+    knowledge?: LoopKnowledge,
+    durationMs?: number,
+  ): LoopIterateDecision {
+    if (!this.activeLoop) {
+      return { decision: 'allow', reason: 'No active loop' };
+    }
+
+    const config = this.activeLoop.config;
+
+    // Accumulate knowledge
+    if (knowledge) {
+      if (!this.activeLoop.knowledge) {
+        this.activeLoop.knowledge = {};
+      }
+      if (knowledge.items) {
+        this.activeLoop.knowledge.items = [
+          ...(this.activeLoop.knowledge.items ?? []),
+          ...knowledge.items,
+        ];
+      }
+      if (knowledge.patternsApplied) {
+        this.activeLoop.knowledge.patternsApplied = [
+          ...(this.activeLoop.knowledge.patternsApplied ?? []),
+          ...knowledge.patternsApplied,
+        ];
+      }
+      if (knowledge.antiPatternsAvoided) {
+        this.activeLoop.knowledge.antiPatternsAvoided = [
+          ...(this.activeLoop.knowledge.antiPatternsAvoided ?? []),
+          ...knowledge.antiPatternsAvoided,
+        ];
+      }
+    }
+
+    // Check for completion promise
+    if (config.completionPromise) {
+      const promiseText = extractPromise(lastOutput);
+      if (promiseText && promiseText === config.completionPromise) {
+        const iterCount = this.activeLoop.iterations.length;
+        this.activeLoop.status = 'completed';
+        this.activeLoop.completedAt = new Date().toISOString();
+        this.moveToHistory('completed');
+        this.completedLoops.push(this.activeLoop);
+        this.activeLoop = null;
+        return {
+          decision: 'allow',
+          reason: `Loop completed — promise "${config.completionPromise}" detected`,
+          outcome: 'completed',
+          iteration: iterCount,
+        };
+      }
+    }
+
+    // Heuristic completion detection
+    const autoReason = detectImplicitCompletion(lastOutput, config);
+    if (autoReason) {
+      const iterCount = this.activeLoop.iterations.length;
+      this.activeLoop.status = 'completed';
+      this.activeLoop.completedAt = new Date().toISOString();
+      this.moveToHistory('completed');
+      this.completedLoops.push(this.activeLoop);
+      this.activeLoop = null;
+      return {
+        decision: 'allow',
+        reason: autoReason,
+        outcome: 'completed',
+        iteration: iterCount,
+        autoCompleted: true,
+      };
+    }
+
+    // Check max iterations
+    if (config.maxIterations > 0 && this.activeLoop.iterations.length >= config.maxIterations) {
+      const iterCount = this.activeLoop.iterations.length;
+      this.activeLoop.status = 'max-iterations';
+      this.activeLoop.completedAt = new Date().toISOString();
+      this.moveToHistory('max_iterations');
+      this.completedLoops.push(this.activeLoop);
+      this.activeLoop = null;
+      return {
+        decision: 'allow',
+        reason: `Max iterations (${config.maxIterations}) reached`,
+        outcome: 'max_iterations',
+        iteration: iterCount,
+      };
+    }
+
+    // Continue loop — increment iteration
+    const nextIteration = this.activeLoop.iterations.length + 1;
+    const iterationEntry: LoopIteration = {
+      iteration: nextIteration,
+      timestamp: new Date().toISOString(),
+      passed: false,
+      ...(durationMs !== undefined && { durationMs }),
+    };
+    this.activeLoop.iterations.push(iterationEntry);
+
+    // Run anomaly detection
+    const anomalyWarning = detectAnomaly(iterationEntry, config.mode);
+
+    // Build validation hint for system message
+    let validationHint = '';
+    switch (config.mode) {
+      case 'token-migration':
+        validationHint = `Run validation (tokens check). Target: score >= ${config.targetScore ?? 95}`;
+        break;
+      case 'contrast-fix':
+        validationHint = 'Run contrast check on all color pairs. Target: all PASS';
+        break;
+      case 'component-build':
+        validationHint = `Run validation (full check). Target: score >= ${config.targetScore ?? 90}`;
+        break;
+      case 'plan-iteration':
+        validationHint = `Run plan grading. Target: grade >= ${config.targetGrade ?? 'A'}`;
+        break;
+      case 'custom':
+        validationHint = 'Complete the task and validate your work';
+        break;
+    }
+
+    const maxDisplay = config.maxIterations > 0 ? String(config.maxIterations) : 'unlimited';
+    const systemMessage =
+      `[Loop — Iteration ${nextIteration}/${maxDisplay} | Mode: ${config.mode}] ${validationHint}` +
+      (config.completionPromise
+        ? ` | Output <promise>${config.completionPromise}</promise> ONLY when validation passes`
+        : '');
+
+    // Build full prompt with validation instructions
+    const fullPrompt = config.validationInstructions
+      ? `${config.prompt}\n\n${config.validationInstructions}`
+      : config.prompt;
+
+    return {
+      decision: 'block',
+      reason: fullPrompt,
+      prompt: fullPrompt,
+      systemMessage,
+      iteration: nextIteration,
+      ...(anomalyWarning && { anomalyWarning }),
+    };
+  }
+
   /**
    * Mark the active loop as completed (validation passed).
    */
@@ -86,6 +378,7 @@ export class LoopManager {
     this.activeLoop.status = 'completed';
     this.activeLoop.completedAt = new Date().toISOString();
     const completed = this.activeLoop;
+    this.moveToHistory('completed');
     this.completedLoops.push(completed);
     this.activeLoop = null;
     return completed;
@@ -102,6 +395,7 @@ export class LoopManager {
     this.activeLoop.status = 'cancelled';
     this.activeLoop.completedAt = new Date().toISOString();
     const cancelled = this.activeLoop;
+    this.moveToHistory('cancelled');
     this.completedLoops.push(cancelled);
     this.activeLoop = null;
     return cancelled;
@@ -121,10 +415,34 @@ export class LoopManager {
     return [...this.completedLoops];
   }
 
+  /**
+   * Get structured history entries (for brain session recording).
+   */
+  getHistoryEntries(): LoopHistoryEntry[] {
+    return [...this.historyEntries];
+  }
+
   /**
    * Check if a loop is currently active.
    */
   isActive(): boolean {
     return this.activeLoop !== null;
   }
+
+  /**
+   * Move active loop to history entries.
+   */
+  private moveToHistory(outcome: 'completed' | 'cancelled' | 'max_iterations'): void {
+    if (!this.activeLoop) return;
+    this.historyEntries.push({
+      id: this.activeLoop.id,
+      mode: this.activeLoop.config.mode,
+      intent: this.activeLoop.config.intent,
+      prompt: this.activeLoop.config.prompt,
+      iterations: this.activeLoop.iterations.length,
+      outcome,
+      startedAt: this.activeLoop.startedAt,
+      completedAt: this.activeLoop.completedAt ?? new Date().toISOString(),
+    });
+  }
 }

package/src/loop/types.ts

@@ -2,7 +2,10 @@
  * Loop system types — iterative validation loop state tracking.
  *
  * Loops let agents run validate-fix-validate cycles (e.g. token migration,
- * contrast fixes, component builds). In-memory only — session-scoped.
+ * contrast fixes, component builds).
+ *
+ * Ported from Salvador's loop.facade.ts with full gate decision system,
+ * output scanning, and completion promise detection.
  */
 
 /** Supported loop modes — each maps to a different validation strategy. */
@@ -18,7 +21,16 @@ export interface LoopConfig {
   mode: LoopMode;
   prompt: string;
   maxIterations: number;
+  /** Target validation score for score-based modes (token-migration, component-build). */
   targetScore?: number;
+  /** Target grade for plan-iteration mode (e.g., 'A', 'A+'). */
+  targetGrade?: string;
+  /** Completion promise text — loop completes when this appears in output. */
+  completionPromise?: string;
+  /** Validation instructions appended to the prompt each iteration. */
+  validationInstructions?: string;
+  /** Detected intent for this loop (e.g., 'BUILD', 'FIX'). Used for brain session recording. */
+  intent?: string;
 }
 
 /** A single iteration result within a loop. */
@@ -28,11 +40,26 @@ export interface LoopIteration {
   validationScore?: number;
   validationResult?: string;
   passed: boolean;
+  /** Duration of this iteration in milliseconds. */
+  durationMs?: number;
 }
 
 /** Loop lifecycle status. */
 export type LoopStatus = 'active' | 'completed' | 'cancelled' | 'max-iterations';
 
+/**
+ * Knowledge items tracked during loop execution.
+ * Ported from Salvador's loop knowledge tracking for brain session recording.
+ */
+export interface LoopKnowledge {
+  /** Knowledge items discovered during the loop. */
+  items?: string[];
+  /** Patterns successfully applied during the loop. */
+  patternsApplied?: string[];
+  /** Anti-patterns intentionally avoided during the loop. */
+  antiPatternsAvoided?: string[];
+}
+
 /** Full state of a loop (active or historical). */
 export interface LoopState {
   id: string;
@@ -41,4 +68,48 @@ export interface LoopState {
   status: LoopStatus;
   startedAt: string;
   completedAt?: string;
+  /** Knowledge accumulated during the loop. */
+  knowledge?: LoopKnowledge;
+}
+
+/**
+ * Loop history entry — stored after loop completion.
+ * Ported from Salvador's LoopHistoryEntry.
+ */
+export interface LoopHistoryEntry {
+  id: string;
+  mode: LoopMode;
+  intent?: string;
+  prompt: string;
+  iterations: number;
+  outcome: 'completed' | 'cancelled' | 'max_iterations';
+  startedAt: string;
+  completedAt: string;
+}
+
+/**
+ * Gate decision returned by iterateWithGate().
+ * Ported from Salvador's LoopIterateDecision.
+ *
+ * - 'allow': Loop has ended (completed, max_iterations, or error). Exit the loop.
+ * - 'block': Loop continues. The returned prompt and systemMessage are injected
+ *   into the next iteration of the Stop hook.
+ */
+export interface LoopIterateDecision {
+  /** Gate decision: 'allow' to exit loop, 'block' to continue iterating. */
+  decision: 'allow' | 'block';
+  /** Human-readable reason for this decision. */
+  reason: string;
+  /** Full prompt for the next iteration (only when decision = 'block'). */
+  prompt?: string;
+  /** System message for the next iteration (only when decision = 'block'). */
+  systemMessage?: string;
+  /** Current iteration number. */
+  iteration?: number;
+  /** Outcome when loop ends (only when decision = 'allow'). */
+  outcome?: 'completed' | 'max_iterations';
+  /** Whether completion was auto-detected (heuristic, not explicit promise). */
+  autoCompleted?: boolean;
+  /** Warning if anomalous patterns detected in this iteration. */
+  anomalyWarning?: string;
 }

package/src/persistence/index.ts

@@ -0,0 +1,7 @@
+export type {
+  PersistenceProvider,
+  PersistenceParams,
+  RunResult,
+  PersistenceConfig,
+} from './types.js';
+export { SQLitePersistenceProvider } from './sqlite-provider.js';

package/src/persistence/sqlite-provider.ts

@@ -0,0 +1,62 @@
+/**
+ * SQLite persistence provider backed by better-sqlite3.
+ *
+ * Supports both positional (array) and named (object) parameters.
+ * Exposes getDatabase() for backward-compat consumers that need the raw db.
+ */
+
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { PersistenceProvider, PersistenceParams, RunResult } from './types.js';
+
+export class SQLitePersistenceProvider implements PersistenceProvider {
+  private db: Database.Database;
+
+  constructor(path: string = ':memory:') {
+    if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true });
+    this.db = new Database(path);
+  }
+
+  execSql(sql: string): void {
+    this.db.exec(sql);
+  }
+
+  run(sql: string, params?: PersistenceParams): RunResult {
+    const stmt = this.db.prepare(sql);
+    if (!params) return stmt.run();
+    if (Array.isArray(params)) return stmt.run(...params);
+    return stmt.run(params);
+  }
+
+  get<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T | undefined {
+    const stmt = this.db.prepare(sql);
+    if (!params) return stmt.get() as T | undefined;
+    if (Array.isArray(params)) return stmt.get(...params) as T | undefined;
+    return stmt.get(params) as T | undefined;
+  }
+
+  all<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T[] {
+    const stmt = this.db.prepare(sql);
+    if (!params) return stmt.all() as T[];
+    if (Array.isArray(params)) return stmt.all(...params) as T[];
+    return stmt.all(params) as T[];
+  }
+
+  transaction<T>(fn: () => T): T {
+    return this.db.transaction(fn)();
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  /**
+   * Escape hatch: get the raw better-sqlite3 Database.
+   * Used by modules that need direct db access (ProjectRegistry, BrainIntelligence, etc.).
+   * Will be deprecated once those modules migrate to PersistenceProvider.
+   */
+  getDatabase(): Database.Database {
+    return this.db;
+  }
+}

package/src/persistence/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Abstract persistence layer.
+ *
+ * Decouples Vault (and future modules) from any specific database engine.
+ * The default implementation is SQLitePersistenceProvider (better-sqlite3).
+ */
+
+export type PersistenceParams = unknown[] | Record<string, unknown>;
+
+export interface RunResult {
+  changes: number;
+  lastInsertRowid: number | bigint;
+}
+
+/**
+ * Minimal database provider interface.
+ *
+ * Supports both positional (`?`) and named (`@param`) parameter styles.
+ * Implementations must handle both array and object params.
+ */
+export interface PersistenceProvider {
+  /** Run raw SQL (DDL, multi-statement). No return value. */
+  execSql(sql: string): void;
+
+  /** Run a parameterized statement (INSERT, UPDATE, DELETE). */
+  run(sql: string, params?: PersistenceParams): RunResult;
+
+  /** Get a single row. Returns undefined if no match. */
+  get<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T | undefined;
+
+  /** Get all matching rows. */
+  all<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T[];
+
+  /** Run a function inside a transaction. Commits on success, rolls back on error. */
+  transaction<T>(fn: () => T): T;
+
+  /** Close the connection. */
+  close(): void;
+}
+
+export interface PersistenceConfig {
+  type: 'sqlite';
+  path: string;
+}