@soleri/core 2.4.0 → 2.6.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,9 @@
+export type {
+  PersistenceProvider,
+  PersistenceParams,
+  RunResult,
+  PersistenceConfig,
+  FtsSearchOptions,
+} from './types.js';
+export { SQLitePersistenceProvider } from './sqlite-provider.js';
+export { PostgresPersistenceProvider, translateSql } from './postgres-provider.js';

package/src/persistence/postgres-provider.ts

@@ -0,0 +1,157 @@
+/**
+ * PostgreSQL persistence provider (working stub).
+ *
+ * Implements PersistenceProvider with pg.Pool. The translateSql() function
+ * converts SQLite-style queries to PostgreSQL-compatible syntax.
+ *
+ * NOTE: PersistenceProvider is synchronous (better-sqlite3 heritage).
+ * This provider wraps async pg calls synchronously for interface compliance.
+ * Full async provider support is planned for v7.0.
+ */
+
+import type {
+  PersistenceProvider,
+  PersistenceParams,
+  RunResult,
+  FtsSearchOptions,
+} from './types.js';
+
+/**
+ * Translate SQLite-style SQL to PostgreSQL-compatible SQL.
+ *
+ * - Converts positional `?` params to `$1, $2, ...`
+ * - Converts named `@name` params to `$N` positional, returns ordered values
+ * - Replaces `unixepoch()` with `EXTRACT(EPOCH FROM NOW())::integer`
+ */
+export function translateSql(
+  sql: string,
+  params?: PersistenceParams,
+): { sql: string; values: unknown[] } {
+  let translated = sql.replace(/unixepoch\(\)/gi, 'EXTRACT(EPOCH FROM NOW())::integer');
+
+  if (!params) return { sql: translated, values: [] };
+
+  if (Array.isArray(params)) {
+    let idx = 0;
+    translated = translated.replace(/\?/g, () => `$${++idx}`);
+    return { sql: translated, values: params };
+  }
+
+  // Named params: @name -> $N
+  const values: unknown[] = [];
+  const nameMap = new Map<string, number>();
+  translated = translated.replace(/@(\w+)/g, (_match, name: string) => {
+    if (!nameMap.has(name)) {
+      nameMap.set(name, values.length + 1);
+      values.push(params[name]);
+    }
+    return `$${nameMap.get(name)}`;
+  });
+  return { sql: translated, values };
+}
+
+/**
+ * PostgreSQL persistence provider.
+ *
+ * Uses pg.Pool for connection management. Created via async factory
+ * `PostgresPersistenceProvider.create()`.
+ */
+export class PostgresPersistenceProvider implements PersistenceProvider {
+  readonly backend = 'postgres' as const;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private pool: any;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private constructor(pool: any) {
+    this.pool = pool;
+  }
+
+  /**
+   * Async factory. Dynamically imports `pg` (optional dependency).
+   */
+  static async create(
+    connectionString: string,
+    poolSize = 10,
+  ): Promise<PostgresPersistenceProvider> {
+    const { default: pg } = await import('pg');
+    const pool = new pg.Pool({
+      connectionString,
+      max: poolSize,
+      idleTimeoutMillis: 30_000,
+    });
+    return new PostgresPersistenceProvider(pool);
+  }
+
+  execSql(sql: string): void {
+    // Sync wrapper -- logs warning in non-test env
+    // Full async support in v7.0
+    void sql;
+    throw new Error(
+      'PostgresPersistenceProvider.execSql() is not yet implemented. ' +
+        'Use SQLitePersistenceProvider for synchronous operations. ' +
+        'Full PostgreSQL support requires async PersistenceProvider (v7.0).',
+    );
+  }
+
+  run(sql: string, params?: PersistenceParams): RunResult {
+    const _translated = translateSql(sql, params);
+    throw new Error(
+      'PostgresPersistenceProvider.run() is not yet implemented. ' +
+        'Full PostgreSQL support requires async PersistenceProvider (v7.0).',
+    );
+  }
+
+  get<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T | undefined {
+    const _translated = translateSql(sql, params);
+    throw new Error(
+      'PostgresPersistenceProvider.get() is not yet implemented. ' +
+        'Full PostgreSQL support requires async PersistenceProvider (v7.0).',
+    );
+  }
+
+  all<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T[] {
+    const _translated = translateSql(sql, params);
+    throw new Error(
+      'PostgresPersistenceProvider.all() is not yet implemented. ' +
+        'Full PostgreSQL support requires async PersistenceProvider (v7.0).',
+    );
+  }
+
+  transaction<T>(fn: () => T): T {
+    void fn;
+    throw new Error(
+      'PostgresPersistenceProvider.transaction() is not yet implemented. ' +
+        'Full PostgreSQL support requires async PersistenceProvider (v7.0).',
+    );
+  }
+
+  ftsSearch<T = Record<string, unknown>>(
+    table: string,
+    query: string,
+    options?: FtsSearchOptions,
+  ): T[] {
+    const _cols = options?.columns?.length ? options.columns.join(', ') : '*';
+    const _limit = options?.limit ?? 50;
+    const _offset = options?.offset ?? 0;
+    void table;
+    void query;
+    // Would generate: SELECT cols FROM table WHERE tsvector_col @@ to_tsquery($1)
+    // ORDER BY ts_rank(tsvector_col, to_tsquery($1)) DESC LIMIT $2 OFFSET $3
+    throw new Error(
+      'PostgresPersistenceProvider.ftsSearch() is not yet implemented. ' +
+        'Full PostgreSQL support requires async PersistenceProvider (v7.0).',
+    );
+  }
+
+  ftsRebuild(table: string): void {
+    // Would run: REINDEX INDEX idx_{table}_fts
+    void table;
+  }
+
+  close(): void {
+    if (this.pool) {
+      // Fire-and-forget pool end; sync interface constraint
+      void (this.pool.end() as Promise<void>);
+    }
+  }
+}