@soleri/core 2.1.0 → 2.5.0

package/dist/logging/logger.js

@@ -0,0 +1,145 @@
+/**
+ * Structured logger for Soleri agents.
+ *
+ * All output routes through stderr (stdout is reserved for MCP JSON-RPC).
+ * Supports optional file logging with daily rotation and 7-day retention.
+ *
+ * Ported from Salvador MCP's src/utils/logger.ts.
+ */
+import { appendFileSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+const LEVEL_ORDER = ['debug', 'info', 'warn', 'error'];
+// MCP stdio servers must keep stdout clean for JSON-RPC.
+// Route ALL log levels through stderr (console.error/console.warn).
+const LEVEL_METHODS = {
+    debug: 'error',
+    info: 'error',
+    warn: 'warn',
+    error: 'error',
+};
+/** Max age for log files before auto-pruning (7 days) */
+const LOG_RETENTION_DAYS = 7;
+export class Logger {
+    prefix;
+    minLevel;
+    fileLogDir = null;
+    fileLogPrefix;
+    currentLogDate = null;
+    currentLogPath = null;
+    constructor(config) {
+        this.prefix = config?.prefix ?? '[Soleri]';
+        this.fileLogPrefix = 'agent';
+        const envLevel = process.env.SOLERI_LOG_LEVEL;
+        const level = config?.level ?? envLevel ?? 'info';
+        const levelIndex = LEVEL_ORDER.indexOf(level);
+        this.minLevel = levelIndex >= 0 ? levelIndex : LEVEL_ORDER.indexOf('info');
+        if (config?.fileLogDir) {
+            this.enableFileLog(config.fileLogDir);
+        }
+    }
+    /**
+     * Enable file-based logging. Output is teed to
+     * {dir}/{prefix}-YYYY-MM-DD.log in addition to stderr.
+     * Automatically prunes log files older than 7 days.
+     */
+    enableFileLog(dir, prefix) {
+        mkdirSync(dir, { recursive: true });
+        this.fileLogDir = dir;
+        if (prefix)
+            this.fileLogPrefix = prefix;
+        this.rotateFileIfNeeded();
+        this.pruneOldLogs();
+    }
+    debug(message, context) {
+        this.log('debug', message, context);
+    }
+    info(message, context) {
+        this.log('info', message, context);
+    }
+    warn(message, context) {
+        this.log('warn', message, context);
+    }
+    error(message, context) {
+        this.log('error', message, context);
+    }
+    log(level, message, context) {
+        if (LEVEL_ORDER.indexOf(level) < this.minLevel)
+            return;
+        const method = LEVEL_METHODS[level];
+        const tag = level.toUpperCase();
+        // Console output (stderr)
+        if (context) {
+            console[method](`${this.prefix}[${tag}] ${message}`, context);
+        }
+        else {
+            console[method](`${this.prefix}[${tag}] ${message}`);
+        }
+        // File output (if enabled)
+        if (this.fileLogDir) {
+            this.writeToFile(tag, message, context);
+        }
+    }
+    writeToFile(tag, message, context) {
+        this.rotateFileIfNeeded();
+        if (!this.currentLogPath)
+            return;
+        const ts = new Date().toISOString();
+        let line = `${ts} [${tag}] ${message}`;
+        if (context) {
+            try {
+                line += ' ' + JSON.stringify(context);
+            }
+            catch {
+                // Skip unserializable context
+            }
+        }
+        try {
+            appendFileSync(this.currentLogPath, line + '\n');
+        }
+        catch {
+            // Silently fail — file logging should never break the app
+        }
+    }
+    /** Switch to a new log file if the date has changed */
+    rotateFileIfNeeded() {
+        if (!this.fileLogDir)
+            return;
+        const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+        if (today !== this.currentLogDate) {
+            this.currentLogDate = today;
+            this.currentLogPath = join(this.fileLogDir, `${this.fileLogPrefix}-${today}.log`);
+        }
+    }
+    /** Remove log files older than LOG_RETENTION_DAYS */
+    pruneOldLogs() {
+        if (!this.fileLogDir)
+            return;
+        const prefix = this.fileLogPrefix;
+        try {
+            const cutoff = Date.now() - LOG_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+            const files = readdirSync(this.fileLogDir);
+            for (const file of files) {
+                if (!file.startsWith(`${prefix}-`) || !file.endsWith('.log'))
+                    continue;
+                const dateStr = file.slice(`${prefix}-`.length, -'.log'.length);
+                const fileDate = new Date(dateStr).getTime();
+                if (!isNaN(fileDate) && fileDate < cutoff) {
+                    try {
+                        unlinkSync(join(this.fileLogDir, file));
+                    }
+                    catch {
+                        // Ignore individual file deletion errors
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore pruning errors
+        }
+    }
+}
+/** Factory function for creating a logger. */
+export function createLogger(config) {
+    return new Logger(config);
+}
+//# sourceMappingURL=logger.js.map

package/dist/logging/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,MAAM,WAAW,GAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnE,yDAAyD;AACzD,oEAAoE;AACpE,MAAM,aAAa,GAAuC;IACxD,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;CACf,CAAC;AAEF,yDAAyD;AACzD,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAE7B,MAAM,OAAO,MAAM;IACA,MAAM,CAAS;IACf,QAAQ,CAAS;IAC1B,UAAU,GAAkB,IAAI,CAAC;IACjC,aAAa,CAAS;IACtB,cAAc,GAAkB,IAAI,CAAC;IACrC,cAAc,GAAkB,IAAI,CAAC;IAE7C,YAAY,MAAqB;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,UAAU,CAAC;QAC3C,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;QAC7B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAwC,CAAC;QACtE,MAAM,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,QAAQ,IAAI,MAAM,CAAC;QAClD,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,CAAC,QAAQ,GAAG,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAE3E,IAAI,MAAM,EAAE,UAAU,EAAE,CAAC;YACvB,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,GAAW,EAAE,MAAe;QACxC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;QACtB,IAAI,MAAM;YAAE,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;QACxC,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC,YAAY,EAAE,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,OAAoB;QACzC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,OAAoB;QACxC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,OAAoB;QACxC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,OAAoB;QACzC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAEO,GAAG,CAAC,KAAe,EAAE,OAAe,EAAE,OAAoB;QAChE,IAAI,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,QAAQ;YAAE,OAAO;QACvD,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QACpC,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;QAEhC,0BAA0B;QAC1B,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,KAAK,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;QAChE,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC,CAAC;QACvD,CAAC;QAED,2BAA2B;QAC3B,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAEO,WAAW,CAAC,GAAW,EAAE,OAAe,EAAE,OAAoB;QACpE,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC,IAAI,CAAC,cAAc;YAAE,OAAO;QAEjC,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACpC,IAAI,IAAI,GAAG,GAAG,EAAE,KAAK,GAAG,KAAK,OAAO,EAAE,CAAC;QACvC,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC;gBACH,IAAI,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YACxC,CAAC;YAAC,MAAM,CAAC;gBACP,8BAA8B;YAChC,CAAC;QACH,CAAC;QACD,IAAI,CAAC;YACH,cAAc,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,IAAI,CAAC,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,0DAA0D;QAC5D,CAAC;IACH,CAAC;IAED,uDAAuD;IAC/C,kBAAkB;QACxB,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO;QAC7B,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa;QAClE,IAAI,KAAK,KAAK,IAAI,CAAC,cAAc,EAAE,CAAC;YAClC,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;YAC5B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,aAAa,IAAI,KAAK,MAAM,CAAC,CAAC;QACpF,CAAC;IACH,CAAC;IAED,qDAAqD;IAC7C,YAAY;QAClB,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO;QAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;YACrE,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC3C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;oBAAE,SAAS;gBACvE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBAChE,MAAM,QAAQ,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;gBAC7C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,MAAM,EAAE,CAAC;oBAC1C,IAAI,CAAC;wBACH,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;oBAC1C,CAAC;oBAAC,MAAM,CAAC;wBACP,yCAAyC;oBAC3C,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,wBAAwB;QAC1B,CAAC;IACH,CAAC;CACF;AAED,8CAA8C;AAC9C,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC"}

package/dist/logging/types.d.ts

@@ -0,0 +1,19 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogContext {
+    [key: string]: unknown;
+}
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    context?: LogContext;
+    timestamp: string;
+}
+export interface LoggerConfig {
+    /** Minimum log level. Default: 'info' (or SOLERI_LOG_LEVEL env var) */
+    level?: LogLevel;
+    /** Prefix for log messages. Default: '[Soleri]' */
+    prefix?: string;
+    /** Directory for file logging. If set, enables file output on construction. */
+    fileLogDir?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/logging/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/logging/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/logging/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/logging/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/logging/types.ts"],"names":[],"mappings":""}

package/dist/loop/loop-manager.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Loop manager — iterative validation loop state tracking with
+ * output scanning and gate decision system.
+ *
+ * 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';
+/**
+ * Extract text between <promise>...</promise> tags from output.
+ * Ported from Salvador's extractPromise.
+ */
+export declare function extractPromise(text: string): string | null;
+/**
+ * 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 declare function detectImplicitCompletion(lastOutput: string, config: LoopConfig): string | null;
+/**
+ * Detect anomalous loop iteration patterns.
+ * Flags fast + low-score combos that suggest the agent is spinning without making progress.
+ */
+export declare function detectAnomaly(iteration: LoopIteration, mode: LoopMode): string | null;
+export declare class LoopManager {
+    private activeLoop;
+    private completedLoops;
+    private historyEntries;
+    /**
+     * Start a new validation loop.
+     * Throws if a loop is already active.
+     */
+    startLoop(config: LoopConfig): LoopState;
+    /**
+     * 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.
+     * If max iterations reached and this iteration fails, status becomes 'max-iterations'.
+     */
+    iterate(result: {
+        validationScore?: number;
+        validationResult?: string;
+        passed: boolean;
+    }): LoopIteration;
+    /**
+     * 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;
+    /**
+     * Mark the active loop as completed (validation passed).
+     */
+    completeLoop(): LoopState;
+    /**
+     * Cancel the active loop.
+     */
+    cancelLoop(): LoopState;
+    /**
+     * Get current loop status. Returns null if no active loop.
+     */
+    getStatus(): LoopState | null;
+    /**
+     * Get history of all completed/cancelled/max-iterations loops.
+     */
+    getHistory(): LoopState[];
+    /**
+     * Get structured history entries (for brain session recording).
+     */
+    getHistoryEntries(): LoopHistoryEntry[];
+    /**
+     * Check if a loop is currently active.
+     */
+    isActive(): boolean;
+    /**
+     * Move active loop to history entries.
+     */
+    private moveToHistory;
+}
+//# sourceMappingURL=loop-manager.d.ts.map

package/dist/loop/loop-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-manager.d.ts","sourceRoot":"","sources":["../../src/loop/loop-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,aAAa,EACb,QAAQ,EACR,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAOpB;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAwD9F;AAgBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAarF;AAID,qBAAa,WAAW;IACtB,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,cAAc,CAAmB;IACzC,OAAO,CAAC,cAAc,CAA0B;IAEhD;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS;IAoBxC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE;QACd,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,MAAM,EAAE,OAAO,CAAC;KACjB,GAAG,aAAa;IA8BjB;;;;;;;;;;;;OAYG;IACH,eAAe,CACb,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,aAAa,EACzB,UAAU,CAAC,EAAE,MAAM,GAClB,mBAAmB;IA4ItB;;OAEG;IACH,YAAY,IAAI,SAAS;IAczB;;OAEG;IACH,UAAU,IAAI,SAAS;IAcvB;;OAEG;IACH,SAAS,IAAI,SAAS,GAAG,IAAI;IAI7B;;OAEG;IACH,UAAU,IAAI,SAAS,EAAE;IAIzB;;OAEG;IACH,iBAAiB,IAAI,gBAAgB,EAAE;IAIvC;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,OAAO,CAAC,aAAa;CAatB"}

package/dist/loop/loop-manager.js

@@ -0,0 +1,379 @@
+/**
+ * Loop manager — iterative validation loop state tracking with
+ * output scanning and gate decision system.
+ *
+ * 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.
+ */
+// ─── 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) {
+    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, config) {
+    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 = {
+    '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, mode) {
+    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;
+    // 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 {
+    activeLoop = null;
+    completedLoops = [];
+    historyEntries = [];
+    /**
+     * Start a new validation loop.
+     * Throws if a loop is already active.
+     */
+    startLoop(config) {
+        if (this.activeLoop) {
+            throw new Error(`Loop already active: ${this.activeLoop.id} (mode: ${this.activeLoop.config.mode}). ` +
+                'Cancel or complete it first.');
+        }
+        const loop = {
+            id: `loop-${Date.now()}`,
+            config,
+            iterations: [],
+            status: 'active',
+            startedAt: new Date().toISOString(),
+        };
+        this.activeLoop = loop;
+        return 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.
+     * If max iterations reached and this iteration fails, status becomes 'max-iterations'.
+     */
+    iterate(result) {
+        if (!this.activeLoop) {
+            throw new Error('No active loop. Start one first.');
+        }
+        const iteration = {
+            iteration: this.activeLoop.iterations.length + 1,
+            timestamp: new Date().toISOString(),
+            validationScore: result.validationScore,
+            validationResult: result.validationResult,
+            passed: result.passed,
+        };
+        this.activeLoop.iterations.push(iteration);
+        // Auto-transition to max-iterations if limit reached and not passing
+        if (!result.passed &&
+            this.activeLoop.iterations.length >= this.activeLoop.config.maxIterations) {
+            this.activeLoop.status = 'max-iterations';
+            this.activeLoop.completedAt = new Date().toISOString();
+            this.moveToHistory('max_iterations');
+            this.completedLoops.push(this.activeLoop);
+            this.activeLoop = null;
+        }
+        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, knowledge, durationMs) {
+        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 = {
+            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).
+     */
+    completeLoop() {
+        if (!this.activeLoop) {
+            throw new Error('No active loop to complete.');
+        }
+        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;
+    }
+    /**
+     * Cancel the active loop.
+     */
+    cancelLoop() {
+        if (!this.activeLoop) {
+            throw new Error('No active loop to cancel.');
+        }
+        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;
+    }
+    /**
+     * Get current loop status. Returns null if no active loop.
+     */
+    getStatus() {
+        return this.activeLoop;
+    }
+    /**
+     * Get history of all completed/cancelled/max-iterations loops.
+     */
+    getHistory() {
+        return [...this.completedLoops];
+    }
+    /**
+     * Get structured history entries (for brain session recording).
+     */
+    getHistoryEntries() {
+        return [...this.historyEntries];
+    }
+    /**
+     * Check if a loop is currently active.
+     */
+    isActive() {
+        return this.activeLoop !== null;
+    }
+    /**
+     * Move active loop to history entries.
+     */
+    moveToHistory(outcome) {
+        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(),
+        });
+    }
+}
+//# sourceMappingURL=loop-manager.js.map