@iflow-mcp/shaun0927-openchrome 1.7.13

package/dist/hints/pattern-learner.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * 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
+ */
+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.PatternLearner = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class PatternLearner {
+    pending = [];
+    rawObservations = new Map();
+    patterns = [];
+    filePath = null;
+    dirty = false;
+    static WATCH_WINDOW = 3;
+    static PROMOTE_THRESHOLD = 3;
+    static CONFIDENCE_THRESHOLD = 0.6;
+    static MAX_PENDING = 10;
+    /**
+     * Enable persistence — load existing patterns and save new ones.
+     */
+    enablePersistence(dirPath) {
+        try {
+            fs.mkdirSync(dirPath, { recursive: true });
+            this.filePath = path.join(dirPath, 'learned-patterns.json');
+            this.load();
+        }
+        catch {
+            // Best-effort
+        }
+    }
+    /**
+     * Called when a hint miss occurs on an error (no static rule matched).
+     * Starts observing subsequent calls to detect recovery pattern.
+     */
+    onMiss(toolName, errorText) {
+        const fingerprint = this.normalizeError(errorText);
+        if (!fingerprint)
+            return;
+        // Limit pending observations to prevent memory buildup
+        if (this.pending.length >= PatternLearner.MAX_PENDING) {
+            this.pending.shift();
+        }
+        this.pending.push({
+            errorTool: toolName,
+            errorFingerprint: fingerprint,
+            timestamp: Date.now(),
+            remainingSlots: PatternLearner.WATCH_WINDOW,
+        });
+    }
+    /**
+     * Called on every tool completion to observe potential recovery patterns.
+     */
+    onToolComplete(toolName, isError) {
+        const resolved = [];
+        for (let i = 0; i < this.pending.length; i++) {
+            const obs = this.pending[i];
+            if (!isError && toolName !== obs.errorTool) {
+                // Success with different tool = potential recovery
+                this.recordRecovery(obs.errorFingerprint, obs.errorTool, toolName);
+                resolved.push(i);
+            }
+            else if (!isError && toolName === obs.errorTool) {
+                // Same tool succeeded = self-resolved, discard
+                resolved.push(i);
+            }
+            else {
+                // Another error, keep watching
+                obs.remainingSlots--;
+                if (obs.remainingSlots <= 0)
+                    resolved.push(i);
+            }
+        }
+        // Remove resolved observations (reverse order to preserve indices)
+        for (let i = resolved.length - 1; i >= 0; i--) {
+            this.pending.splice(resolved[i], 1);
+        }
+    }
+    /**
+     * Record an observed error→recovery correlation.
+     */
+    recordRecovery(errorFingerprint, errorTool, recoveryTool) {
+        let raw = this.rawObservations.get(errorFingerprint);
+        if (!raw) {
+            raw = {
+                errorFingerprint,
+                errorTools: new Set(),
+                recoveryTools: new Map(),
+                totalObservations: 0,
+            };
+            this.rawObservations.set(errorFingerprint, raw);
+        }
+        raw.errorTools.add(errorTool);
+        raw.recoveryTools.set(recoveryTool, (raw.recoveryTools.get(recoveryTool) || 0) + 1);
+        raw.totalObservations++;
+        this.tryPromote(raw);
+    }
+    /**
+     * Check if a raw observation should be promoted to a learned pattern.
+     */
+    tryPromote(raw) {
+        let bestTool = '';
+        let bestCount = 0;
+        for (const [tool, count] of raw.recoveryTools) {
+            if (count > bestCount) {
+                bestTool = tool;
+                bestCount = count;
+            }
+        }
+        const confidence = bestCount / raw.totalObservations;
+        if (bestCount < PatternLearner.PROMOTE_THRESHOLD || confidence < PatternLearner.CONFIDENCE_THRESHOLD) {
+            return;
+        }
+        const existing = this.patterns.find(p => p.errorFingerprint === raw.errorFingerprint);
+        if (existing) {
+            existing.occurrences = bestCount;
+            existing.confidence = confidence;
+            existing.recoveryTool = bestTool;
+            existing.lastSeen = Date.now();
+            existing.errorTools = Array.from(raw.errorTools);
+            existing.hint = PatternLearner.generateHint(bestTool, bestCount);
+        }
+        else {
+            this.patterns.push({
+                id: `learned-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+                errorFingerprint: raw.errorFingerprint,
+                errorTools: Array.from(raw.errorTools),
+                recoveryTool: bestTool,
+                occurrences: bestCount,
+                confidence,
+                firstSeen: Date.now(),
+                lastSeen: Date.now(),
+                hint: PatternLearner.generateHint(bestTool, bestCount),
+            });
+        }
+        this.dirty = true;
+        this.save();
+    }
+    /**
+     * Match an error against learned patterns.
+     */
+    matchPattern(errorText, toolName) {
+        const fingerprint = this.normalizeError(errorText);
+        for (const pattern of this.patterns) {
+            if (pattern.errorTools.includes(toolName) &&
+                (fingerprint.includes(pattern.errorFingerprint) || pattern.errorFingerprint.includes(fingerprint))) {
+                return pattern;
+            }
+        }
+        return null;
+    }
+    /**
+     * Normalize error text for fingerprinting.
+     * Strips dynamic values (IDs, large numbers) to group similar errors.
+     */
+    normalizeError(text) {
+        return text
+            .toLowerCase()
+            .replace(/\b[0-9a-f]{8,}\b/g, '{id}')
+            .replace(/\d{4,}/g, '{n}')
+            .replace(/\s+/g, ' ')
+            .trim()
+            .slice(0, 100);
+    }
+    /**
+     * Get all learned patterns (for testing/inspection).
+     */
+    getPatterns() {
+        return this.patterns;
+    }
+    /**
+     * Get pending observation count (for testing).
+     */
+    getPendingCount() {
+        return this.pending.length;
+    }
+    static generateHint(recoveryTool, occurrences) {
+        return `Hint: Try ${recoveryTool} — learned from ${occurrences} previous recoveries.`;
+    }
+    load() {
+        if (!this.filePath)
+            return;
+        try {
+            const data = fs.readFileSync(this.filePath, 'utf-8');
+            const store = JSON.parse(data);
+            this.patterns = store.patterns || [];
+        }
+        catch {
+            this.patterns = [];
+        }
+    }
+    /**
+     * Persist learned patterns to disk.
+     */
+    save() {
+        if (!this.filePath || !this.dirty)
+            return;
+        try {
+            const dir = path.dirname(this.filePath);
+            fs.mkdirSync(dir, { recursive: true });
+            const store = {
+                version: 1,
+                patterns: this.patterns,
+                updatedAt: Date.now(),
+            };
+            fs.writeFileSync(this.filePath, JSON.stringify(store, null, 2));
+            this.dirty = false;
+        }
+        catch {
+            // Best-effort
+        }
+    }
+}
+exports.PatternLearner = PatternLearner;
+//# sourceMappingURL=pattern-learner.js.map

package/dist/hints/pattern-learner.js.map

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

package/dist/hints/progress-tracker.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ProgressTracker — Detects when the LLM agent is not making meaningful progress.
+ *
+ * Instead of matching specific error patterns, measures whether recent tool calls
+ * represent meaningful progress (URL change, content extraction, successful interaction)
+ * or spinning (auth redirects, stale refs, non-interactive clicks, timeouts).
+ */
+import type { ToolCallEvent } from '../dashboard/types.js';
+export type ProgressStatus = 'progressing' | 'stalling' | 'stuck';
+/**
+ * Signals in tool results that indicate NO meaningful progress was made,
+ * even if the tool call technically "succeeded".
+ */
+declare const NON_PROGRESS_SIGNALS: string[];
+export declare class ProgressTracker {
+    /**
+     * Evaluate recent tool calls to determine if the agent is making progress.
+     *
+     * @param recentCalls - Last 5 tool calls from ActivityTracker (newest first)
+     * @param currentToolName - Current tool being evaluated
+     * @param currentResultText - Text content of current tool result
+     * @param currentIsError - Whether current tool call errored
+     * @returns ProgressStatus
+     */
+    evaluate(recentCalls: ToolCallEvent[], _currentToolName: string, currentResultText: string, currentIsError: boolean): ProgressStatus;
+    /**
+     * Check if a tool result text contains non-progress signals.
+     * Used for the CURRENT tool call where we have the full result text.
+     */
+    isProgressResult(resultText: string): boolean;
+    /**
+     * Check if a completed tool call was likely progress-producing.
+     * Used for PAST calls where we only have ToolCallEvent metadata.
+     *
+     * LIMITATION: For past calls with result='success' and no error field,
+     * this method returns true (progress) even if the actual result text
+     * contained non-progress signals. Only the CURRENT call's full result
+     * text is inspected by isProgressResult(). Past call evaluation is
+     * limited to the error field and tool metadata.
+     */
+    private isLikelyProgressCall;
+}
+export { NON_PROGRESS_SIGNALS };
+//# sourceMappingURL=progress-tracker.d.ts.map

package/dist/hints/progress-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-tracker.d.ts","sourceRoot":"","sources":["../../src/hints/progress-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,UAAU,GAAG,OAAO,CAAC;AAElE;;;GAGG;AACH,QAAA,MAAM,oBAAoB,UAmBzB,CAAC;AAEF,qBAAa,eAAe;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CACN,WAAW,EAAE,aAAa,EAAE,EAC5B,gBAAgB,EAAE,MAAM,EACxB,iBAAiB,EAAE,MAAM,EACzB,cAAc,EAAE,OAAO,GACtB,cAAc;IAwCjB;;;OAGG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAM7C;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;CAe7B;AAGD,OAAO,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/hints/progress-tracker.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * ProgressTracker — Detects when the LLM agent is not making meaningful progress.
+ *
+ * Instead of matching specific error patterns, measures whether recent tool calls
+ * represent meaningful progress (URL change, content extraction, successful interaction)
+ * or spinning (auth redirects, stale refs, non-interactive clicks, timeouts).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NON_PROGRESS_SIGNALS = exports.ProgressTracker = void 0;
+/**
+ * Signals in tool results that indicate NO meaningful progress was made,
+ * even if the tool call technically "succeeded".
+ */
+const NON_PROGRESS_SIGNALS = [
+    'authRedirect', // Auth redirect detected
+    'not interactive', // Clicked non-interactive element
+    'is stale', // Stale ref
+    'timed out', // Timeout
+    'No significant visual change', // Screenshot unchanged
+    'element not found', // Element not found (tightened from 'not found')
+    'no longer available', // Tab gone
+    'Login page detected', // Login redirect (from hint)
+    'CAPTCHA', // CAPTCHA blocked
+    '404', // Page not found
+    'Access Denied', // Access denied
+    'Forbidden', // 403
+    'net::ERR_', // Chromium network errors
+    'Navigation timeout', // Puppeteer navigation timeout
+    'Protocol error', // CDP-level failures
+    'bot-check', // Bot verification page detected
+    'captcha detected', // CAPTCHA page detected
+    'Blocking page detected', // Any blocking page warning from navigate
+];
+exports.NON_PROGRESS_SIGNALS = NON_PROGRESS_SIGNALS;
+class ProgressTracker {
+    /**
+     * Evaluate recent tool calls to determine if the agent is making progress.
+     *
+     * @param recentCalls - Last 5 tool calls from ActivityTracker (newest first)
+     * @param currentToolName - Current tool being evaluated
+     * @param currentResultText - Text content of current tool result
+     * @param currentIsError - Whether current tool call errored
+     * @returns ProgressStatus
+     */
+    evaluate(recentCalls, _currentToolName, currentResultText, currentIsError) {
+        // Build a list of recent "progress" assessments including the current call
+        const currentIsProgress = !currentIsError && this.isProgressResult(currentResultText);
+        let consecutiveNonProgress = currentIsProgress ? 0 : 1;
+        let consecutiveErrors = currentIsError ? 1 : 0;
+        // Walk backward through recent calls
+        for (const call of recentCalls) {
+            if (call.result === 'error') {
+                consecutiveErrors++;
+                consecutiveNonProgress++;
+            }
+            else {
+                // Check if the successful call had non-progress signals
+                // We can only check error field; for successful calls we check the tool name pattern
+                const wasProgress = this.isLikelyProgressCall(call);
+                if (!wasProgress) {
+                    consecutiveNonProgress++;
+                    // Do NOT reset consecutiveErrors — a non-progress success
+                    // is not evidence that the error streak ended
+                }
+                else {
+                    consecutiveErrors = 0; // Only reset on genuine progress
+                    break; // Found progress, stop counting
+                }
+            }
+        }
+        // Stuck: 3+ consecutive errors, or 5+ non-progress calls
+        if (consecutiveErrors >= 3 || consecutiveNonProgress >= 5) {
+            return 'stuck';
+        }
+        // Stalling: 3+ non-progress calls (mix of errors and non-progress successes)
+        if (consecutiveNonProgress >= 3) {
+            return 'stalling';
+        }
+        return 'progressing';
+    }
+    /**
+     * Check if a tool result text contains non-progress signals.
+     * Used for the CURRENT tool call where we have the full result text.
+     */
+    isProgressResult(resultText) {
+        if (!resultText || resultText.trim().length === 0)
+            return false;
+        const lower = resultText.toLowerCase();
+        return !NON_PROGRESS_SIGNALS.some(signal => lower.includes(signal.toLowerCase()));
+    }
+    /**
+     * Check if a completed tool call was likely progress-producing.
+     * Used for PAST calls where we only have ToolCallEvent metadata.
+     *
+     * LIMITATION: For past calls with result='success' and no error field,
+     * this method returns true (progress) even if the actual result text
+     * contained non-progress signals. Only the CURRENT call's full result
+     * text is inspected by isProgressResult(). Past call evaluation is
+     * limited to the error field and tool metadata.
+     */
+    isLikelyProgressCall(call) {
+        // Errors are never progress
+        if (call.result === 'error')
+            return false;
+        // If error field is set (even on "success"), check for non-progress signals
+        if (call.error) {
+            return !NON_PROGRESS_SIGNALS.some(signal => call.error.includes(signal));
+        }
+        // Tool-based heuristics for past calls without full result text:
+        // - navigate with very fast completion (~<500ms) might be a redirect
+        // - computer/click calls without errors are usually progress
+        // - read_page/find calls are usually progress (information gathering)
+        return true;
+    }
+}
+exports.ProgressTracker = ProgressTracker;
+//# sourceMappingURL=progress-tracker.js.map

package/dist/hints/progress-tracker.js.map

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

package/dist/hints/rules/blocking-page.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Blocking Page Rules — detect CAPTCHAs, bot-checks, and access-denied pages.
+ * Fires on successful navigate results that contain a blockingPage field,
+ * providing immediate guidance instead of waiting for the progress tracker.
+ */
+import type { HintRule } from '../hint-engine';
+export declare const blockingPageRules: HintRule[];
+//# sourceMappingURL=blocking-page.d.ts.map

package/dist/hints/rules/blocking-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocking-page.d.ts","sourceRoot":"","sources":["../../../src/hints/rules/blocking-page.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,eAAO,MAAM,iBAAiB,EAAE,QAAQ,EAsDvC,CAAC"}

package/dist/hints/rules/blocking-page.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Blocking Page Rules — detect CAPTCHAs, bot-checks, and access-denied pages.
+ * Fires on successful navigate results that contain a blockingPage field,
+ * providing immediate guidance instead of waiting for the progress tracker.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blockingPageRules = void 0;
+exports.blockingPageRules = [
+    {
+        name: 'captcha-detected',
+        priority: 120, // Higher than error-recovery (100-108), lower than navigate-to-login (150)
+        match(ctx) {
+            if (ctx.toolName !== 'navigate')
+                return null;
+            if (ctx.isError)
+                return null;
+            // Check for structured blockingPage field in navigate response
+            if (/"blockingPage"\s*:\s*\{[^}]*"type"\s*:\s*"captcha"/i.test(ctx.resultText)) {
+                return ('Hint: CAPTCHA detected on this page. OpenChrome cannot solve CAPTCHAs programmatically. ' +
+                    'STOP all interaction attempts with this page. ' +
+                    'Ask the user to solve the CAPTCHA in their Chrome browser, then use wait_for to detect when the page changes, and resume automation.');
+            }
+            return null;
+        },
+    },
+    {
+        name: 'bot-check-detected',
+        priority: 121,
+        match(ctx) {
+            if (ctx.toolName !== 'navigate')
+                return null;
+            if (ctx.isError)
+                return null;
+            if (/"blockingPage"\s*:\s*\{[^}]*"type"\s*:\s*"bot-check"/i.test(ctx.resultText)) {
+                return ('Hint: Bot verification detected. OpenChrome cannot bypass bot checks. ' +
+                    'Ask the user to complete the verification in their Chrome browser, then retry navigation.');
+            }
+            return null;
+        },
+    },
+    {
+        name: 'access-denied-detected',
+        priority: 122,
+        match(ctx) {
+            if (ctx.toolName !== 'navigate')
+                return null;
+            if (ctx.isError)
+                return null;
+            if (/"blockingPage"\s*:\s*\{[^}]*"type"\s*:\s*"access-denied"/i.test(ctx.resultText)) {
+                return ('Hint: Access denied (403/Forbidden). The site may be blocking automated access. ' +
+                    'Ask the user to verify they have permission to access this URL, or try navigating in their Chrome browser first.');
+            }
+            return null;
+        },
+    },
+];
+//# sourceMappingURL=blocking-page.js.map

package/dist/hints/rules/blocking-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocking-page.js","sourceRoot":"","sources":["../../../src/hints/rules/blocking-page.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAIU,QAAA,iBAAiB,GAAe;IAC3C;QACE,IAAI,EAAE,kBAAkB;QACxB,QAAQ,EAAE,GAAG,EAAE,2EAA2E;QAC1F,KAAK,CAAC,GAAG;YACP,IAAI,GAAG,CAAC,QAAQ,KAAK,UAAU;gBAAE,OAAO,IAAI,CAAC;YAC7C,IAAI,GAAG,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAC;YAE7B,+DAA+D;YAC/D,IAAI,qDAAqD,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC/E,OAAO,CACL,0FAA0F;oBAC1F,gDAAgD;oBAChD,sIAAsI,CACvI,CAAC;YACJ,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;KACF;IACD;QACE,IAAI,EAAE,oBAAoB;QAC1B,QAAQ,EAAE,GAAG;QACb,KAAK,CAAC,GAAG;YACP,IAAI,GAAG,CAAC,QAAQ,KAAK,UAAU;gBAAE,OAAO,IAAI,CAAC;YAC7C,IAAI,GAAG,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAC;YAE7B,IAAI,uDAAuD,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBACjF,OAAO,CACL,wEAAwE;oBACxE,2FAA2F,CAC5F,CAAC;YACJ,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;KACF;IACD;QACE,IAAI,EAAE,wBAAwB;QAC9B,QAAQ,EAAE,GAAG;QACb,KAAK,CAAC,GAAG;YACP,IAAI,GAAG,CAAC,QAAQ,KAAK,UAAU;gBAAE,OAAO,IAAI,CAAC;YAC7C,IAAI,GAAG,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAC;YAE7B,IAAI,2DAA2D,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBACrF,OAAO,CACL,kFAAkF;oBAClF,kHAAkH,CACnH,CAAC;YACJ,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;KACF;CACF,CAAC"}

package/dist/hints/rules/composite-suggestions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Composite Suggestions — suggests combining multi-step patterns into single calls.
+ */
+import type { HintRule } from '../hint-engine';
+export declare const compositeSuggestionRules: HintRule[];
+//# sourceMappingURL=composite-suggestions.d.ts.map

package/dist/hints/rules/composite-suggestions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite-suggestions.d.ts","sourceRoot":"","sources":["../../../src/hints/rules/composite-suggestions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAe,MAAM,gBAAgB,CAAC;AAU5D,eAAO,MAAM,wBAAwB,EAAE,QAAQ,EAqH9C,CAAC"}

package/dist/hints/rules/composite-suggestions.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * Composite Suggestions — suggests combining multi-step patterns into single calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compositeSuggestionRules = void 0;
+function lastToolWas(ctx, name) {
+    return ctx.recentCalls.length > 0 && ctx.recentCalls[0].toolName === name;
+}
+function recentToolCount(ctx, name) {
+    return ctx.recentCalls.filter(c => c.toolName === name).length;
+}
+exports.compositeSuggestionRules = [
+    {
+        name: 'find-then-click',
+        priority: 200,
+        maxSeverity: 'info',
+        match(ctx) {
+            if (ctx.toolName !== 'computer' && ctx.toolName !== 'click')
+                return null;
+            if (!lastToolWas(ctx, 'find'))
+                return null;
+            return 'Hint: Use click_element to find+click in one call.';
+        },
+    },
+    {
+        name: 'multiple-form-input',
+        priority: 201,
+        maxSeverity: 'warning',
+        match(ctx) {
+            if (ctx.toolName !== 'form_input')
+                return null;
+            if (recentToolCount(ctx, 'form_input') >= 1) {
+                return 'Hint: Use fill_form({fields:{...}}) for multiple fields.';
+            }
+            return null;
+        },
+    },
+    {
+        name: 'navigate-then-click',
+        priority: 202,
+        maxSeverity: 'info',
+        match(ctx) {
+            if (ctx.toolName !== 'computer' && ctx.toolName !== 'click' && ctx.toolName !== 'click_element')
+                return null;
+            if (!lastToolWas(ctx, 'navigate'))
+                return null;
+            // Don't match screenshot operations — handled by sequence-detection
+            if (/screenshot/i.test(ctx.resultText))
+                return null;
+            return 'Hint: Use wait_and_click to handle loading delays.';
+        },
+    },
+    {
+        name: 'read-page-truncated',
+        priority: 203,
+        maxSeverity: 'info',
+        match(ctx) {
+            if (ctx.toolName !== 'read_page')
+                return null;
+            if (ctx.isError)
+                return null;
+            if (/truncat|too (long|large)|content cut|\.\.\.$/i.test(ctx.resultText)) {
+                return 'Hint: Output was truncated. Use inspect(query) for targeted state checks, find(query) for element search, or read_page mode="dom" for compact output.';
+            }
+            return null;
+        },
+    },
+    {
+        name: 'contenteditable-click-hint',
+        priority: 204, // After existing composite rules (200-203)
+        maxSeverity: 'info',
+        match(ctx) {
+            if (ctx.toolName !== 'computer')
+                return null;
+            if (ctx.isError)
+                return null;
+            // Check if the hit info mentions contenteditable
+            if (/contenteditable|lexical|prosemirror|tiptap|slate|editor/i.test(ctx.resultText)) {
+                return ('Hint: Click inside a rich text editor (contenteditable). ' +
+                    'Editor frameworks may intercept click events. ' +
+                    'Prefer: (1) click_element with text query, (2) javascript_tool for direct element.click(), ' +
+                    '(3) read_page mode="dom" to get backendNodeId then use computer ref parameter.');
+            }
+            return null;
+        },
+    },
+    {
+        name: 'coordinate-click-after-read',
+        priority: 205,
+        maxSeverity: 'warning',
+        match(ctx) {
+            if (ctx.toolName !== 'computer')
+                return null;
+            if (ctx.isError)
+                return null;
+            // Check if this is a coordinate click (not ref-based)
+            if (!/Clicked at \(\d/.test(ctx.resultText))
+                return null;
+            // Check if the hit was not interactive
+            if (/\[not interactive\]/.test(ctx.resultText)) {
+                return ('Hint: Clicked a non-interactive element. Use click_element with a text query ' +
+                    'or read_page mode="dom" to find the correct target.');
+            }
+            return null;
+        },
+    },
+    {
+        name: 'state-check-after-action',
+        priority: 206,
+        maxSeverity: 'warning',
+        match(ctx) {
+            if (ctx.toolName !== 'read_page')
+                return null;
+            if (lastToolWas(ctx, 'navigate') ||
+                lastToolWas(ctx, 'click_element') ||
+                lastToolWas(ctx, 'wait_and_click') ||
+                lastToolWas(ctx, 'interact')) {
+                return 'Hint: Use inspect(query) for quick page state checks after actions — e.g. inspect("error messages") or inspect("form field values").';
+            }
+            return null;
+        },
+    },
+    {
+        name: 'repeated-read-page',
+        priority: 207,
+        maxSeverity: 'warning',
+        match(ctx) {
+            if (ctx.toolName !== 'read_page')
+                return null;
+            if (recentToolCount(ctx, 'read_page') >= 2) {
+                return 'Hint: Use inspect(query) for targeted extraction instead of repeated full page reads — e.g. inspect("what tabs are active") or inspect("visible errors").';
+            }
+            return null;
+        },
+    },
+];
+//# sourceMappingURL=composite-suggestions.js.map