@iflow-mcp/shaun0927-openchrome 1.7.13

package/dist/errors/timeout.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenChromeTimeoutError = void 0;
+exports.isTimeoutError = isTimeoutError;
+/**
+ * Typed timeout error for OpenChrome.
+ * Replaces fragile string-based timeout detection across the codebase.
+ */
+class OpenChromeTimeoutError extends Error {
+    /** Whether the operation may have produced useful partial state (e.g., partial DOM load). */
+    recoverable;
+    /** Original operation label for diagnostics. */
+    label;
+    /** Timeout duration in milliseconds. */
+    timeoutMs;
+    constructor(label, timeoutMs, recoverable = false) {
+        super(`${label} timed out after ${timeoutMs}ms`);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = 'OpenChromeTimeoutError';
+        this.label = label;
+        this.timeoutMs = timeoutMs;
+        this.recoverable = recoverable;
+    }
+}
+exports.OpenChromeTimeoutError = OpenChromeTimeoutError;
+/**
+ * Type guard for timeout errors. Checks for:
+ * 1. OpenChromeTimeoutError instances (preferred)
+ * 2. Legacy string-based patterns including Puppeteer's "Waiting failed: Xms exceeded"
+ */
+function isTimeoutError(error) {
+    if (error instanceof OpenChromeTimeoutError)
+        return true;
+    if (error instanceof Error) {
+        const msg = error.message.toLowerCase();
+        return (msg.includes('timed out') ||
+            /waiting failed:.*exceeded/i.test(error.message));
+    }
+    return false;
+}
+//# sourceMappingURL=timeout.js.map

package/dist/errors/timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.js","sourceRoot":"","sources":["../../src/errors/timeout.ts"],"names":[],"mappings":";;;AA2BA,wCAUC;AArCD;;;GAGG;AACH,MAAa,sBAAuB,SAAQ,KAAK;IAC/C,6FAA6F;IACpF,WAAW,CAAU;IAC9B,gDAAgD;IACvC,KAAK,CAAS;IACvB,wCAAwC;IAC/B,SAAS,CAAS;IAE3B,YAAY,KAAa,EAAE,SAAiB,EAAE,WAAW,GAAG,KAAK;QAC/D,KAAK,CAAC,GAAG,KAAK,oBAAoB,SAAS,IAAI,CAAC,CAAC;QACjD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAhBD,wDAgBC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,YAAY,sBAAsB;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACxC,OAAO,CACL,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC;YACzB,4BAA4B,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CACjD,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/hints/hint-engine.d.ts

@@ -0,0 +1,117 @@
+/**
+ * HintEngine — evaluates rules against tool results to produce proactive hints.
+ *
+ * Rules are sorted by priority (lower = higher priority) and evaluated first-match-wins.
+ * Uses ActivityTracker's recent calls for sequence/pattern detection.
+ * Integrates PatternLearner for adaptive error→recovery learning.
+ *
+ * Escalation system (issue #71):
+ * - Fire count 1-2: info severity (original hint text)
+ * - Fire count 3-4: warning severity (⚠️ WARNING prefix)
+ * - Fire count 5+:  critical severity (🛑 CRITICAL prefix + action history)
+ * Fire counts accumulate per rule across the session and never reset.
+ */
+import type { ToolCallEvent } from '../dashboard/types';
+import type { ActivityTracker } from '../dashboard/activity-tracker';
+import { PatternLearner } from './pattern-learner';
+import { ProgressTracker } from './progress-tracker.js';
+export interface HintContext {
+    toolName: string;
+    resultText: string;
+    isError: boolean;
+    recentCalls: ToolCallEvent[];
+    fireCounts: Map<string, number>;
+}
+export interface HintRule {
+    name: string;
+    priority: number;
+    maxSeverity?: HintSeverity;
+    match(ctx: HintContext): string | null;
+}
+export type HintSeverity = 'info' | 'warning' | 'critical';
+export interface HintLogEntry {
+    timestamp: number;
+    toolName: string;
+    isError: boolean;
+    matchedRule: string | null;
+    hint: string | null;
+    severity: HintSeverity | null;
+    fireCount: number;
+}
+export interface HintResult {
+    severity: HintSeverity;
+    rule: string;
+    fireCount: number;
+    hint: string;
+    rawHint: string;
+    suggestion?: {
+        tool?: string;
+        reason: string;
+    };
+    context?: {
+        element?: string;
+        coordinates?: string;
+        ref?: string;
+    };
+}
+export declare class HintEngine {
+    private rules;
+    private activityTracker;
+    private learner;
+    private progressTracker;
+    private logFilePath;
+    private hintEscalation;
+    private missCounts;
+    private logStream;
+    private logBuffer;
+    private flushTimer;
+    private static readonly FLUSH_INTERVAL;
+    constructor(activityTracker: ActivityTracker, progressTracker?: ProgressTracker);
+    /**
+     * Enable hit/miss logging to a JSONL file for data collection.
+     */
+    enableLogging(dirPath: string): void;
+    /**
+     * Enable adaptive learning — load existing patterns and persist new ones.
+     */
+    enableLearning(dirPath: string): void;
+    /**
+     * Evaluate rules and return the first matching structured hint, or null.
+     * Also feeds the learner for adaptive pattern detection.
+     *
+     * Returns HintResult with escalating severity based on per-rule fire count:
+     * - 1-2 firings: info (original hint text)
+     * - 3-4 firings: warning (⚠️ WARNING prefix)
+     * - 5+ firings:  critical (🛑 CRITICAL prefix + action history)
+     */
+    getHint(toolName: string, result: Record<string, unknown>, isError: boolean, sessionId?: string): HintResult | null;
+    private getSeverity;
+    private formatHintMessage;
+    private extractContext;
+    private extractSuggestion;
+    /**
+     * Extract text content from an MCPResult for pattern matching.
+     */
+    private extractText;
+    /**
+     * Write a log entry via buffered async stream (best-effort, non-blocking).
+     */
+    private log;
+    /**
+     * Flush buffered log entries to the write stream.
+     */
+    private flushBuffer;
+    /**
+     * Flush pending writes and close the log stream. Call on shutdown.
+     */
+    destroy(): void;
+    /**
+     * Get all registered rules (for testing).
+     */
+    getRules(): HintRule[];
+    /**
+     * Get the pattern learner (for testing).
+     */
+    getLearner(): PatternLearner;
+}
+//# sourceMappingURL=hint-engine.d.ts.map

package/dist/hints/hint-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hint-engine.d.ts","sourceRoot":"","sources":["../../src/hints/hint-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAWxD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,KAAK,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,cAAc,CAAkC;IACxD,OAAO,CAAC,UAAU,CAAkC;IAGpD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAO;gBAEjC,eAAe,EAAE,eAAe,EAAE,eAAe,CAAC,EAAE,eAAe;IAyB/E;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAUpC;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIrC;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAoInH,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,iBAAiB;IAYzB;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,OAAO,CAAC,GAAG;IAUX;;OAEG;IACH,OAAO,CAAC,WAAW;IASnB;;OAEG;IACH,OAAO,IAAI,IAAI;IAYf;;OAEG;IACH,QAAQ,IAAI,QAAQ,EAAE;IAItB;;OAEG;IACH,UAAU,IAAI,cAAc;CAG7B"}

package/dist/hints/hint-engine.js

@@ -0,0 +1,347 @@
+"use strict";
+/**
+ * HintEngine — evaluates rules against tool results to produce proactive hints.
+ *
+ * Rules are sorted by priority (lower = higher priority) and evaluated first-match-wins.
+ * Uses ActivityTracker's recent calls for sequence/pattern detection.
+ * Integrates PatternLearner for adaptive error→recovery learning.
+ *
+ * Escalation system (issue #71):
+ * - Fire count 1-2: info severity (original hint text)
+ * - Fire count 3-4: warning severity (⚠️ WARNING prefix)
+ * - Fire count 5+:  critical severity (🛑 CRITICAL prefix + action history)
+ * Fire counts accumulate per rule across the session and never reset.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HintEngine = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const pattern_learner_1 = require("./pattern-learner");
+const progress_tracker_js_1 = require("./progress-tracker.js");
+const error_recovery_1 = require("./rules/error-recovery");
+const blocking_page_1 = require("./rules/blocking-page");
+const composite_suggestions_1 = require("./rules/composite-suggestions");
+const sequence_detection_1 = require("./rules/sequence-detection");
+const repetition_detection_1 = require("./rules/repetition-detection");
+const pagination_detection_1 = require("./rules/pagination-detection");
+const learned_rules_1 = require("./rules/learned-rules");
+const success_hints_1 = require("./rules/success-hints");
+const setup_hints_1 = require("./rules/setup-hints");
+class HintEngine {
+    rules;
+    activityTracker;
+    learner;
+    progressTracker;
+    logFilePath = null;
+    hintEscalation = new Map(); // ruleName -> session fire count
+    missCounts = new Map(); // ruleName -> consecutive miss count
+    // Buffered async write stream
+    logStream = null;
+    logBuffer = [];
+    flushTimer = null;
+    static FLUSH_INTERVAL = 200; // ms
+    constructor(activityTracker, progressTracker) {
+        this.activityTracker = activityTracker;
+        this.progressTracker = progressTracker ?? new progress_tracker_js_1.ProgressTracker();
+        this.learner = new pattern_learner_1.PatternLearner();
+        // Collect all rules and sort by priority (ascending = highest priority first)
+        // Learned rules (350) sit between repetition (250) and success hints (400)
+        this.rules = [
+            ...setup_hints_1.setupHintRules, // priority 90
+            ...error_recovery_1.errorRecoveryRules, // priority 100-108
+            ...blocking_page_1.blockingPageRules, // priority 120-122
+            ...pagination_detection_1.paginationDetectionRules, // priority 190-192
+            ...composite_suggestions_1.compositeSuggestionRules, // priority 200-203
+            ...repetition_detection_1.repetitionDetectionRules, // priority 245-252
+            ...sequence_detection_1.sequenceDetectionRules, // priority 300-304
+            ...(0, learned_rules_1.createLearnedRules)(this.learner), // priority 350
+            ...success_hints_1.successHintRules, // priority 400-403
+        ].sort((a, b) => a.priority - b.priority);
+        // Flush remaining buffer on process exit
+        process.on('exit', () => {
+            this.flushBuffer();
+        });
+    }
+    /**
+     * Enable hit/miss logging to a JSONL file for data collection.
+     */
+    enableLogging(dirPath) {
+        try {
+            fs.mkdirSync(dirPath, { recursive: true });
+            this.logFilePath = path.join(dirPath, `hints-${new Date().toISOString().slice(0, 10)}.jsonl`);
+            this.logStream = fs.createWriteStream(this.logFilePath, { flags: 'a' });
+        }
+        catch {
+            // Best-effort logging
+        }
+    }
+    /**
+     * Enable adaptive learning — load existing patterns and persist new ones.
+     */
+    enableLearning(dirPath) {
+        this.learner.enablePersistence(dirPath);
+    }
+    /**
+     * Evaluate rules and return the first matching structured hint, or null.
+     * Also feeds the learner for adaptive pattern detection.
+     *
+     * Returns HintResult with escalating severity based on per-rule fire count:
+     * - 1-2 firings: info (original hint text)
+     * - 3-4 firings: warning (⚠️ WARNING prefix)
+     * - 5+ firings:  critical (🛑 CRITICAL prefix + action history)
+     */
+    getHint(toolName, result, isError, sessionId) {
+        const resultText = this.extractText(result);
+        const recentCalls = this.activityTracker.getRecentCalls(5, sessionId);
+        // Priority 50: Progress tracking (highest priority, runs before all rules)
+        // NOTE: ProgressTracker returns early before the rule loop. Miss-count decay
+        // for individual rules is intentionally frozen during stuck/stalling phases —
+        // we don't want to spuriously reset escalating rule fire counts while the
+        // agent is not making progress.
+        const status = this.progressTracker.evaluate(recentCalls, toolName, resultText, isError);
+        // Scope escalation keys by sessionId when available to prevent cross-session pollution
+        const escalationKey = (ruleName) => sessionId !== undefined ? `${sessionId}:${ruleName}` : ruleName;
+        if (status === 'stuck') {
+            const key = escalationKey('progress-tracker-stuck');
+            const fireCount = (this.hintEscalation.get(key) || 0) + 1;
+            this.hintEscalation.set(key, fireCount);
+            const rawHintText = 'STOP — you are stuck. The last several tool calls made no meaningful progress ' +
+                '(errors, stale refs, auth redirects, or timeouts). ' +
+                'Step back and try a completely different approach, or ask the user for help.';
+            const severity = fireCount >= 2 ? 'critical' : 'warning';
+            this.log({ timestamp: Date.now(), toolName, isError, matchedRule: 'progress-tracker-stuck', hint: rawHintText, severity, fireCount });
+            return {
+                severity,
+                rule: 'progress-tracker-stuck',
+                fireCount,
+                hint: this.formatHintMessage(severity, rawHintText, fireCount),
+                rawHint: rawHintText,
+            };
+        }
+        if (status === 'stalling') {
+            const key = escalationKey('progress-tracker-stalling');
+            const fireCount = (this.hintEscalation.get(key) || 0) + 1;
+            this.hintEscalation.set(key, fireCount);
+            const rawHintText = 'Warning: recent tool calls are not making progress. ' +
+                'Consider trying a different approach before getting stuck.';
+            const severity = this.getSeverity(fireCount);
+            this.log({ timestamp: Date.now(), toolName, isError, matchedRule: 'progress-tracker-stalling', hint: rawHintText, severity, fireCount });
+            return {
+                severity,
+                rule: 'progress-tracker-stalling',
+                fireCount,
+                hint: this.formatHintMessage(severity, rawHintText, fireCount),
+                rawHint: rawHintText,
+            };
+        }
+        const ctx = { toolName, resultText, isError, recentCalls, fireCounts: this.hintEscalation };
+        let matchedRule = null;
+        let rawHint = null;
+        let matchedMaxSeverity;
+        for (const rule of this.rules) {
+            const h = rule.match(ctx);
+            if (h) {
+                matchedRule = rule.name;
+                rawHint = h;
+                matchedMaxSeverity = rule.maxSeverity;
+                // Reset miss count on match
+                this.missCounts.set(rule.name, 0);
+                break;
+            }
+            else {
+                // Increment miss count; after 10 consecutive misses, decay fire count to 0
+                const misses = (this.missCounts.get(rule.name) || 0) + 1;
+                this.missCounts.set(rule.name, misses);
+                if (misses >= 10) {
+                    this.hintEscalation.set(escalationKey(rule.name), 0);
+                    this.missCounts.set(rule.name, 0);
+                }
+            }
+        }
+        if (!rawHint || !matchedRule) {
+            // Feed the learner even on miss
+            this.learner.onToolComplete(toolName, isError);
+            if (isError) {
+                this.learner.onMiss(toolName, resultText);
+            }
+            this.log({ timestamp: Date.now(), toolName, isError, matchedRule: null, hint: null, severity: null, fireCount: 0 });
+            return null;
+        }
+        // Track fire count per rule, scoped by sessionId when available
+        const matchedKey = escalationKey(matchedRule);
+        const fireCount = (this.hintEscalation.get(matchedKey) || 0) + 1;
+        this.hintEscalation.set(matchedKey, fireCount);
+        const severity = this.getSeverity(fireCount, matchedMaxSeverity);
+        let formattedHint = this.formatHintMessage(severity, rawHint, fireCount);
+        // Context-aware: extract element/coordinate info from result
+        const context = this.extractContext(resultText);
+        // For critical hints (5+), add action history to force strategy change
+        if (severity === 'critical') {
+            const recentTools = recentCalls.slice(0, 5).map(c => c.toolName);
+            const toolCounts = recentTools.reduce((acc, t) => { acc[t] = (acc[t] || 0) + 1; return acc; }, {});
+            const summary = Object.entries(toolCounts).map(([t, c]) => `${t}×${c}`).join(', ');
+            formattedHint += ` Previous actions: [${summary}].`;
+            if (context?.coordinates) {
+                formattedHint += ` Last coordinates: ${context.coordinates}.`;
+            }
+            if (context?.element) {
+                formattedHint += ` Hit element: ${context.element}.`;
+            }
+        }
+        const suggestion = this.extractSuggestion(rawHint);
+        const hintResult = {
+            severity,
+            rule: matchedRule,
+            fireCount,
+            hint: formattedHint,
+            rawHint,
+            ...(suggestion && { suggestion }),
+            ...(context && { context }),
+        };
+        // Feed the learner
+        this.learner.onToolComplete(toolName, isError);
+        this.log({ timestamp: Date.now(), toolName, isError, matchedRule, hint: formattedHint, severity, fireCount });
+        return hintResult;
+    }
+    getSeverity(fireCount, maxSeverity) {
+        const raw = fireCount <= 2 ? 'info' : fireCount <= 4 ? 'warning' : 'critical';
+        if (!maxSeverity)
+            return raw;
+        const order = ['info', 'warning', 'critical'];
+        return order.indexOf(raw) <= order.indexOf(maxSeverity) ? raw : maxSeverity;
+    }
+    formatHintMessage(severity, rawHint, fireCount) {
+        switch (severity) {
+            case 'info':
+                return rawHint; // Keep original text (already has "Hint:" prefix from rules)
+            case 'warning':
+                return `⚠️ WARNING (${fireCount}x): ${rawHint}`;
+            case 'critical':
+                return `🛑 CRITICAL (${fireCount}x — you MUST change approach): ${rawHint}`;
+        }
+    }
+    extractContext(resultText) {
+        const context = {};
+        // Extract coordinates from "Clicked at (X, Y)" or "(X,Y)" patterns
+        const coordMatch = resultText.match(/\((\d+),\s*(\d+)\)/);
+        if (coordMatch)
+            context.coordinates = `(${coordMatch[1]}, ${coordMatch[2]})`;
+        // Extract element info from "Hit: ..." line
+        const hitMatch = resultText.match(/Hit:\s*(.+?)(?:\n|$)/);
+        if (hitMatch)
+            context.element = hitMatch[1].trim();
+        // Extract ref ID
+        const refMatch = resultText.match(/ref[_=]["']?(\w+)/i);
+        if (refMatch)
+            context.ref = refMatch[1];
+        return Object.keys(context).length > 0 ? context : undefined;
+    }
+    extractSuggestion(rawHint) {
+        // Extract tool name from common patterns like "Use X", "Try X", "Prefer X"
+        const toolMatch = rawHint.match(/\b(?:Use|Try|Prefer)\s+(\w+)(?:\(|[\s,.])/i);
+        if (toolMatch) {
+            return {
+                tool: toolMatch[1],
+                reason: rawHint,
+            };
+        }
+        return undefined;
+    }
+    /**
+     * Extract text content from an MCPResult for pattern matching.
+     */
+    extractText(result) {
+        const content = result.content;
+        if (!Array.isArray(content))
+            return JSON.stringify(result);
+        return content
+            .filter((c) => c.type === 'text')
+            .map((c) => c.text)
+            .join('\n');
+    }
+    /**
+     * Write a log entry via buffered async stream (best-effort, non-blocking).
+     */
+    log(entry) {
+        if (!this.logStream)
+            return;
+        this.logBuffer.push(JSON.stringify(entry) + '\n');
+        if (!this.flushTimer) {
+            this.flushTimer = setTimeout(() => {
+                this.flushBuffer();
+            }, HintEngine.FLUSH_INTERVAL);
+        }
+    }
+    /**
+     * Flush buffered log entries to the write stream.
+     */
+    flushBuffer() {
+        if (this.logBuffer.length > 0 && this.logStream) {
+            const data = this.logBuffer.join('');
+            this.logStream.write(data);
+            this.logBuffer = [];
+        }
+        this.flushTimer = null;
+    }
+    /**
+     * Flush pending writes and close the log stream. Call on shutdown.
+     */
+    destroy() {
+        this.flushBuffer();
+        if (this.logStream) {
+            this.logStream.end();
+            this.logStream = null;
+        }
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    /**
+     * Get all registered rules (for testing).
+     */
+    getRules() {
+        return this.rules;
+    }
+    /**
+     * Get the pattern learner (for testing).
+     */
+    getLearner() {
+        return this.learner;
+    }
+}
+exports.HintEngine = HintEngine;
+//# sourceMappingURL=hint-engine.js.map

package/dist/hints/hint-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hint-engine.js","sourceRoot":"","sources":["../../src/hints/hint-engine.ts"],"names":[],"mappings":"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"}

package/dist/hints/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Hints module — Proactive hint system
+ */
+export { HintEngine } from './hint-engine';
+export type { HintContext, HintRule, HintLogEntry, HintSeverity, HintResult } from './hint-engine';
+export { PatternLearner } from './pattern-learner';
+export type { LearnedPattern } from './pattern-learner';
+//# sourceMappingURL=index.d.ts.map

package/dist/hints/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hints/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACnG,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/hints/index.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Hints module — Proactive hint system
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PatternLearner = exports.HintEngine = void 0;
+var hint_engine_1 = require("./hint-engine");
+Object.defineProperty(exports, "HintEngine", { enumerable: true, get: function () { return hint_engine_1.HintEngine; } });
+var pattern_learner_1 = require("./pattern-learner");
+Object.defineProperty(exports, "PatternLearner", { enumerable: true, get: function () { return pattern_learner_1.PatternLearner; } });
+//# sourceMappingURL=index.js.map

package/dist/hints/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hints/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,6CAA2C;AAAlC,yGAAA,UAAU,OAAA;AAEnB,qDAAmD;AAA1C,iHAAA,cAAc,OAAA"}

package/dist/hints/pattern-learner.d.ts

@@ -0,0 +1,76 @@
+/**
+ * PatternLearner — Adaptive memory system that learns error→recovery patterns.
+ *
+ * Flow:
+ * 1. Hint miss on error → start observing next 3 tool calls
+ * 2. If a different tool succeeds → record as recovery pattern
+ * 3. Same error→recovery seen N times → promote to learned rule
+ * 4. Persisted to JSON, survives across sessions
+ */
+export interface LearnedPattern {
+    id: string;
+    errorFingerprint: string;
+    errorTools: string[];
+    recoveryTool: string;
+    occurrences: number;
+    confidence: number;
+    firstSeen: number;
+    lastSeen: number;
+    hint: string;
+}
+export declare class PatternLearner {
+    private pending;
+    private rawObservations;
+    private patterns;
+    private filePath;
+    private dirty;
+    static readonly WATCH_WINDOW = 3;
+    static readonly PROMOTE_THRESHOLD = 3;
+    static readonly CONFIDENCE_THRESHOLD = 0.6;
+    static readonly MAX_PENDING = 10;
+    /**
+     * Enable persistence — load existing patterns and save new ones.
+     */
+    enablePersistence(dirPath: string): void;
+    /**
+     * Called when a hint miss occurs on an error (no static rule matched).
+     * Starts observing subsequent calls to detect recovery pattern.
+     */
+    onMiss(toolName: string, errorText: string): void;
+    /**
+     * Called on every tool completion to observe potential recovery patterns.
+     */
+    onToolComplete(toolName: string, isError: boolean): void;
+    /**
+     * Record an observed error→recovery correlation.
+     */
+    private recordRecovery;
+    /**
+     * Check if a raw observation should be promoted to a learned pattern.
+     */
+    private tryPromote;
+    /**
+     * Match an error against learned patterns.
+     */
+    matchPattern(errorText: string, toolName: string): LearnedPattern | null;
+    /**
+     * Normalize error text for fingerprinting.
+     * Strips dynamic values (IDs, large numbers) to group similar errors.
+     */
+    normalizeError(text: string): string;
+    /**
+     * Get all learned patterns (for testing/inspection).
+     */
+    getPatterns(): LearnedPattern[];
+    /**
+     * Get pending observation count (for testing).
+     */
+    getPendingCount(): number;
+    static generateHint(recoveryTool: string, occurrences: number): string;
+    private load;
+    /**
+     * Persist learned patterns to disk.
+     */
+    save(): void;
+}
+//# sourceMappingURL=pattern-learner.d.ts.map

package/dist/hints/pattern-learner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern-learner.d.ts","sourceRoot":"","sources":["../../src/hints/pattern-learner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAsBD,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,KAAK,CAAS;IAEtB,MAAM,CAAC,QAAQ,CAAC,YAAY,KAAK;IACjC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,KAAK;IACtC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,OAAO;IAC3C,MAAM,CAAC,QAAQ,CAAC,WAAW,MAAM;IAEjC;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAUxC;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAiBjD;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IA0BxD;;OAEG;IACH,OAAO,CAAC,cAAc;IAmBtB;;OAEG;IACH,OAAO,CAAC,UAAU;IA0ClB;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAaxE;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAUpC;;OAEG;IACH,WAAW,IAAI,cAAc,EAAE;IAI/B;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB,MAAM,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAItE,OAAO,CAAC,IAAI;IAWZ;;OAEG;IACH,IAAI,IAAI,IAAI;CAgBb"}