autokap 1.0.6 → 1.0.8

package/dist/v2/recovery-chain.js

@@ -0,0 +1,368 @@
+/**
+ * Capture Agent — Recovery Chain
+ *
+ * Ordered recovery strategies when a deterministic opcode fails:
+ * 1. Deterministic retry (same opcode, fresh observation)
+ * 2. Selector memory lookup (known-good selectors from Supabase)
+ * 3. Alternative interaction (keyboard, JS dispatch, coordinates)
+ * 4. Targeted reload (reload page and retry)
+ * 5. LLM Healer (last resort)
+ */
+import { resolveSelector } from './selector-resolver.js';
+import { evaluatePostcondition } from './postcondition.js';
+import { LLMHealer } from './llm-healer.js';
+import { serializeAKTree } from '../ak-tree.js';
+export class RecoveryChainImpl {
+    healer;
+    selectorMemory;
+    programSteps;
+    constructor(options = {}) {
+        this.selectorMemory = options.selectorMemory ?? {};
+        this.programSteps = options.programSteps ?? [];
+        this.healer = options.llmProvider
+            ? new LLMHealer(options.llmProvider, { maxInvocations: options.maxHealerInvocations ?? 3 })
+            : null;
+    }
+    async attempt(failedOpcode, opcodeIndex, adapter, options = {}) {
+        const recovery = failedOpcode.recovery;
+        // Strategy 1: Deterministic retry
+        const retryBudget = Math.max(0, Math.min(recovery.retries, options.maxDeterministicRetries ?? recovery.retries));
+        if (retryBudget > 0) {
+            const result = await retryOpcode(failedOpcode, adapter, retryBudget, options.remainingTimeMs);
+            if (result.recovered)
+                return result;
+        }
+        // Strategy 2: Selector memory + alternate selectors
+        if (recovery.useSelectorMemory && hasSelector(failedOpcode)) {
+            const result = await trySelectorAlternatives(failedOpcode, opcodeIndex, adapter, this.selectorMemory);
+            if (result.recovered)
+                return result;
+        }
+        // Strategy 3: Alternative interaction methods
+        if (recovery.useAltInteraction && hasSelector(failedOpcode)) {
+            const result = await tryAltInteraction(failedOpcode, adapter);
+            if (result.recovered)
+                return result;
+        }
+        // Strategy 4: Targeted reload
+        if (recovery.allowReload) {
+            const result = await tryReload(failedOpcode, adapter);
+            if (result.recovered)
+                return result;
+        }
+        // Strategy 5: LLM Healer
+        if (recovery.allowHealer && this.healer && this.healer.remainingInvocations > 0) {
+            const result = await tryHealer(failedOpcode, opcodeIndex, adapter, this.healer, this.programSteps);
+            return result;
+        }
+        return { recovered: false, reason: 'all recovery strategies exhausted' };
+    }
+}
+// ── Strategy 1: Deterministic retry ─────────────────────────────────
+async function retryOpcode(opcode, adapter, maxRetries, remainingTimeMs) {
+    const deadlineMs = typeof remainingTimeMs === 'number'
+        ? Date.now() + remainingTimeMs
+        : Number.POSITIVE_INFINITY;
+    for (let i = 0; i < maxRetries; i++) {
+        if (Date.now() >= deadlineMs) {
+            return { recovered: false, reason: 'retry budget exhausted by timeout' };
+        }
+        await sleep(500 * (i + 1)); // backoff
+        try {
+            await executeRawAction(opcode, adapter);
+            const postcondition = await evaluatePostcondition(adapter, clampPostconditionWait(opcode.postcondition, deadlineMs));
+            if (postcondition.passed) {
+                return { recovered: true, strategy: 'retry', reason: `retry ${i + 1}/${maxRetries} succeeded` };
+            }
+        }
+        catch {
+            // continue to next retry
+        }
+    }
+    return { recovered: false, reason: `${maxRetries} retries exhausted` };
+}
+// ── Strategy 2: Selector memory ─────────────────────────────────────
+async function trySelectorAlternatives(opcode, opcodeIndex, adapter, selectorMemory) {
+    if (!hasSelector(opcode)) {
+        return { recovered: false, reason: 'opcode has no selector' };
+    }
+    const selectorOpcode = opcode;
+    const primarySelector = selectorOpcode.selector ?? '';
+    const stepSignature = `${opcode.kind}:${primarySelector}`;
+    const resolved = await resolveSelector(adapter, {
+        primary: primarySelector,
+        fingerprint: selectorOpcode.fingerprint,
+        alternates: selectorOpcode.selectorAlternates,
+        selectorMemory,
+        stepSignature,
+        description: opcode.description,
+    });
+    if (!resolved || resolved.strategy === 'primary') {
+        return { recovered: false, reason: 'no alternative selectors found' };
+    }
+    // Try the resolved selector
+    try {
+        await executeWithSelector(opcode, adapter, resolved.selector);
+        const postcondition = await evaluatePostcondition(adapter, opcode.postcondition);
+        if (postcondition.passed) {
+            return {
+                recovered: true,
+                strategy: 'selector_memory',
+                reason: `resolved via ${resolved.strategy}: "${resolved.selector}"`,
+            };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return { recovered: false, reason: `resolved selector "${resolved.selector}" also failed` };
+}
+// ── Strategy 3: Alternative interaction ─────────────────────────────
+async function tryAltInteraction(opcode, adapter) {
+    if (opcode.kind !== 'CLICK' || !opcode.selector) {
+        return { recovered: false, reason: 'alt interaction only for CLICK opcodes with selectors' };
+    }
+    const clickOpcode = opcode;
+    const sel = clickOpcode.selector;
+    const methods = [
+        { name: 'keyboard', options: { useKeyboard: true } },
+        { name: 'js_dispatch', options: { useJsDispatch: true } },
+    ];
+    for (const method of methods) {
+        try {
+            await adapter.click(sel, method.options);
+            await sleep(500);
+            const postcondition = await evaluatePostcondition(adapter, opcode.postcondition);
+            if (postcondition.passed) {
+                return {
+                    recovered: true,
+                    strategy: 'alt_interaction',
+                    reason: `${method.name} interaction succeeded`,
+                };
+            }
+        }
+        catch {
+            // continue to next method
+        }
+    }
+    // Try coordinate-based click from AKTree
+    try {
+        const tree = await adapter.getAKTree();
+        const node = findInteractiveNodeBySelector(tree, sel);
+        if (node) {
+            const x = node.bounds.x + node.bounds.w / 2;
+            const y = node.bounds.y + node.bounds.h / 2;
+            await adapter.click(sel, { coordinates: { x, y } });
+            await sleep(500);
+            const postcondition = await evaluatePostcondition(adapter, opcode.postcondition);
+            if (postcondition.passed) {
+                return {
+                    recovered: true,
+                    strategy: 'alt_interaction',
+                    reason: `coordinate click at (${x}, ${y}) succeeded`,
+                };
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    return { recovered: false, reason: 'all alternative interactions failed' };
+}
+// ── Strategy 4: Targeted reload ─────────────────────────────────────
+async function tryReload(opcode, adapter) {
+    try {
+        const url = await adapter.getCurrentUrl();
+        await adapter.navigate(url);
+        await sleep(1000);
+        await adapter.dismissOverlays();
+        await executeRawAction(opcode, adapter);
+        const postcondition = await evaluatePostcondition(adapter, opcode.postcondition);
+        if (postcondition.passed) {
+            return { recovered: true, strategy: 'reload', reason: 'reload + retry succeeded' };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return { recovered: false, reason: 'reload + retry failed' };
+}
+// ── Strategy 5: LLM Healer ─────────────────────────────────────────
+async function tryHealer(failedOpcode, opcodeIndex, adapter, healer, programSteps) {
+    try {
+        const tree = await adapter.getAKTree();
+        const akTreeSerialized = serializeAKTree(tree);
+        const currentUrl = await adapter.getCurrentUrl();
+        let screenshot;
+        try {
+            screenshot = await adapter.takeScreenshot();
+        }
+        catch { /* optional */ }
+        // Get surrounding opcodes for context
+        const start = Math.max(0, opcodeIndex - 3);
+        const end = Math.min(programSteps.length, opcodeIndex + 4);
+        const surroundingOpcodes = programSteps.slice(start, end).filter((_, i) => start + i !== opcodeIndex);
+        const context = {
+            failedOpcode,
+            opcodeIndex,
+            akTreeSerialized,
+            currentUrl,
+            screenshot,
+            surroundingOpcodes,
+            errorMessage: `opcode ${failedOpcode.kind} failed after all deterministic recovery strategies`,
+        };
+        const result = await healer.heal(context);
+        if (result.healed && result.patch) {
+            // Execute the replacement opcode(s) to verify they work
+            for (const replacementOp of result.patch.replacementOpcodes) {
+                try {
+                    await executeRawAction(replacementOp, adapter);
+                }
+                catch (err) {
+                    return {
+                        recovered: false,
+                        reason: `healer patch failed during execution: ${err instanceof Error ? err.message : String(err)}`,
+                    };
+                }
+            }
+            // Verify the last replacement's postcondition
+            const lastOp = result.patch.replacementOpcodes[result.patch.replacementOpcodes.length - 1];
+            const postcondition = await evaluatePostcondition(adapter, lastOp.postcondition);
+            if (postcondition.passed) {
+                return {
+                    recovered: true,
+                    strategy: 'healer',
+                    patch: result.patch,
+                    reason: result.reason,
+                };
+            }
+            return { recovered: false, reason: `healer patch executed but postcondition failed: ${postcondition.reason}` };
+        }
+        return { recovered: false, reason: result.reason };
+    }
+    catch (err) {
+        return {
+            recovered: false,
+            reason: `healer error: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+// ── Shared helpers ──────────────────────────────────────────────────
+function hasSelector(opcode) {
+    return 'selector' in opcode && typeof opcode.selector === 'string' && !!opcode.selector;
+}
+async function executeRawAction(opcode, adapter) {
+    switch (opcode.kind) {
+        case 'NAVIGATE':
+            await adapter.navigate(opcode.url);
+            break;
+        case 'DISMISS_OVERLAYS':
+            await adapter.dismissOverlays();
+            break;
+        case 'CLICK':
+            try {
+                await adapter.click(opcode.selector);
+            }
+            catch (error) {
+                if (!adapter.clickByTarget || !opcode.target)
+                    throw error;
+                await adapter.clickByTarget({
+                    selector: opcode.selector,
+                    target: opcode.target,
+                    selectorAlternates: opcode.selectorAlternates,
+                });
+            }
+            break;
+        case 'TYPE':
+            try {
+                await adapter.type(opcode.selector, opcode.text, opcode.clearFirst);
+            }
+            catch (error) {
+                if (!adapter.typeByTarget || !opcode.target)
+                    throw error;
+                await adapter.typeByTarget({
+                    selector: opcode.selector,
+                    target: opcode.target,
+                    selectorAlternates: opcode.selectorAlternates,
+                }, opcode.text, opcode.clearFirst);
+            }
+            break;
+        case 'PRESS_KEY':
+            await adapter.pressKey(opcode.key);
+            break;
+        case 'WAIT_FOR':
+            if (opcode.selector) {
+                await adapter.waitFor({ selector: opcode.selector, state: opcode.state, timeoutMs: opcode.timeoutMs });
+            }
+            else if (adapter.waitForTarget) {
+                await adapter.waitForTarget({ target: opcode.target }, opcode.timeoutMs);
+            }
+            break;
+        case 'SCROLL':
+            if (opcode.targetSelector)
+                await adapter.scrollIntoView(opcode.targetSelector);
+            else
+                await adapter.scroll(opcode.direction, opcode.amount);
+            break;
+        case 'SET_LOCALE':
+            if (opcode.method === 'browser_context') {
+                await adapter.setLocale(opcode.locale);
+                if (adapter.reloadPage)
+                    await adapter.reloadPage();
+            }
+            else if (opcode.method === 'ui_interaction' && opcode.selector) {
+                await adapter.click(opcode.selector);
+            }
+            break;
+        case 'SET_THEME':
+            if (opcode.method === 'color_scheme')
+                await adapter.setColorScheme(opcode.theme);
+            else if (opcode.method === 'ui_interaction' && opcode.selector)
+                await adapter.click(opcode.selector);
+            break;
+        case 'CAPTURE_SCREENSHOT':
+        case 'BEGIN_CLIP':
+        case 'END_CLIP':
+        case 'ASSERT_ROUTE':
+        case 'ASSERT_SURFACE':
+            // These are handled by postconditions, not raw actions
+            break;
+    }
+}
+async function executeWithSelector(opcode, adapter, newSelector) {
+    switch (opcode.kind) {
+        case 'CLICK':
+            await adapter.click(newSelector);
+            break;
+        case 'TYPE':
+            await adapter.type(newSelector, opcode.text, opcode.clearFirst);
+            break;
+        default:
+            throw new Error(`cannot swap selector for opcode kind: ${opcode.kind}`);
+    }
+}
+function findInteractiveNodeBySelector(tree, selector) {
+    function walk(node) {
+        if (node.visible && node.interactive && node.sourceRef.includes(selector.replace(/[[\]"#.]/g, ''))) {
+            return node;
+        }
+        for (const child of node.children) {
+            const found = walk(child);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    return walk(tree.root);
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function clampPostconditionWait(spec, deadlineMs) {
+    const remainingTimeMs = Math.max(1, deadlineMs - Date.now());
+    return {
+        ...spec,
+        waitMs: Math.max(1, Math.min(spec.waitMs ?? remainingTimeMs, remainingTimeMs)),
+    };
+}
+//# sourceMappingURL=recovery-chain.js.map