autokap 1.0.7 → 1.0.8

package/dist/v2/overlay-engine.js

@@ -0,0 +1,150 @@
+/**
+ * Capture Agent — Overlay Engine
+ *
+ * Consolidated deterministic overlay handling.
+ * Wraps and extends the existing cookie-dismiss module with
+ * additional patterns for newsletter popups, chat widgets, and age gates.
+ *
+ * This module is used by the DISMISS_OVERLAYS opcode.
+ */
+/**
+ * Multi-pass overlay dismissal.
+ * 1. Delegate to the adapter's built-in dismissOverlays (cookie-dismiss.ts)
+ * 2. Check AKTree for remaining blocking overlays
+ * 3. Try additional heuristics for newsletter/chat/age gate
+ * 4. Final AKTree check
+ */
+export async function dismissAllOverlays(adapter) {
+    const methods = [];
+    let totalFound = 0;
+    // Pass 1: Built-in cookie/widget dismissal
+    const cookieResult = await adapter.dismissOverlays();
+    if (cookieResult.dismissed) {
+        methods.push(cookieResult.method ?? 'cookie-dismiss');
+    }
+    // Check remaining overlays
+    let tree = await adapter.getAKTree();
+    const blocking = tree.overlays.filter(o => o.blocksInteraction);
+    totalFound = tree.overlays.length;
+    if (blocking.length === 0) {
+        return { dismissed: methods.length > 0, methods, overlaysFound: totalFound, overlaysRemaining: 0 };
+    }
+    // Pass 2: Try Escape key to dismiss modals/popups
+    try {
+        await adapter.pressKey('Escape');
+        await sleep(300);
+        tree = await adapter.getAKTree();
+        const remaining = tree.overlays.filter(o => o.blocksInteraction);
+        if (remaining.length < blocking.length) {
+            methods.push('escape-key');
+        }
+        if (remaining.length === 0) {
+            return { dismissed: true, methods, overlaysFound: totalFound, overlaysRemaining: 0 };
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+    // Pass 3: Try clicking common close patterns in AKTree
+    const closePatterns = [
+        'close', 'dismiss', 'fermer', 'schließen', 'cerrar', 'chiudi',
+        'no thanks', 'non merci', 'maybe later', 'not now', 'skip',
+    ];
+    for (const overlay of tree.overlays) {
+        if (!overlay.blocksInteraction)
+            continue;
+        // Look for close buttons within the overlay's subtree
+        const closeNode = findCloseButton(tree, overlay.nodeId, closePatterns);
+        if (closeNode) {
+            try {
+                // Build selector from the close node's sourceRef
+                const selector = buildSelectorFromSourceRef(closeNode.sourceRef);
+                if (selector) {
+                    await adapter.click(selector);
+                    methods.push(`close-button:${selector}`);
+                    await sleep(300);
+                }
+            }
+            catch {
+                // Continue to next overlay
+            }
+        }
+    }
+    // Final check
+    tree = await adapter.getAKTree();
+    const finalBlocking = tree.overlays.filter(o => o.blocksInteraction);
+    return {
+        dismissed: methods.length > 0,
+        methods,
+        overlaysFound: totalFound,
+        overlaysRemaining: finalBlocking.length,
+    };
+}
+function findCloseButton(tree, overlayNodeId, patterns) {
+    // Find the overlay node first
+    const overlayNode = findNodeById(tree.root, overlayNodeId);
+    if (!overlayNode)
+        return null;
+    // Search for interactive close-like buttons within this subtree
+    let best = null;
+    function walk(node) {
+        if (node.visible && node.interactive) {
+            const label = node.label.toLowerCase();
+            const ref = node.sourceRef.toLowerCase();
+            const combined = label + ' ' + ref;
+            for (const pattern of patterns) {
+                if (combined.includes(pattern)) {
+                    // Prefer buttons over links, and shorter labels over longer ones
+                    if (!best || (node.type === 'button' && best.type !== 'button') || node.label.length < best.label.length) {
+                        best = node;
+                    }
+                    break;
+                }
+            }
+            // Also match aria-label="close" or title="close" in sourceRef
+            if (ref.includes('aria-label="close"') || ref.includes('title="close"') || ref.includes('class="close"')) {
+                if (!best)
+                    best = node;
+            }
+        }
+        node.children.forEach(walk);
+    }
+    walk(overlayNode);
+    return best;
+}
+function findNodeById(node, id) {
+    if (node.id === id)
+        return node;
+    for (const child of node.children) {
+        const found = findNodeById(child, id);
+        if (found)
+            return found;
+    }
+    return null;
+}
+function buildSelectorFromSourceRef(sourceRef) {
+    // Extract data-testid
+    const testIdMatch = sourceRef.match(/data-testid="([^"]+)"/);
+    if (testIdMatch)
+        return `[data-testid="${testIdMatch[1]}"]`;
+    // Extract id
+    const idMatch = sourceRef.match(/ id="([^"]+)"/);
+    if (idMatch)
+        return `#${idMatch[1]}`;
+    // Extract aria-label
+    const ariaMatch = sourceRef.match(/aria-label="([^"]+)"/);
+    if (ariaMatch)
+        return `[aria-label="${ariaMatch[1]}"]`;
+    // Extract class-based close button
+    const classMatch = sourceRef.match(/class="([^"]*close[^"]*)"/);
+    if (classMatch) {
+        const tagMatch = sourceRef.match(/^<(\w+)/);
+        const tag = tagMatch?.[1] ?? 'button';
+        return `${tag}.${classMatch[1].split(/\s+/).find(c => c.includes('close'))}`;
+    }
+    return null;
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=overlay-engine.js.map

package/dist/v2/postcondition.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Capture Agent — Postcondition Evaluator
+ *
+ * Deterministic evaluation of postconditions after each opcode.
+ * No LLM calls — purely structural checks against AKTree, URL, and screenshots.
+ */
+import type { RuntimeAdapter, PostconditionSpec } from './types.js';
+/**
+ * Evaluates whether a postcondition holds.
+ * Retries internally up to postcondition.waitMs (polling).
+ * Returns true if the condition is satisfied, false otherwise.
+ */
+export declare function evaluatePostcondition(adapter: RuntimeAdapter, spec: PostconditionSpec): Promise<{
+    passed: boolean;
+    reason: string;
+}>;

package/dist/v2/postcondition.js

@@ -0,0 +1,249 @@
+/**
+ * Capture Agent — Postcondition Evaluator
+ *
+ * Deterministic evaluation of postconditions after each opcode.
+ * No LLM calls — purely structural checks against AKTree, URL, and screenshots.
+ */
+import { serializeAKTree } from '../ak-tree.js';
+/**
+ * Evaluates whether a postcondition holds.
+ * Retries internally up to postcondition.waitMs (polling).
+ * Returns true if the condition is satisfied, false otherwise.
+ */
+export async function evaluatePostcondition(adapter, spec) {
+    const maxWait = spec.waitMs ?? 5000;
+    const pollInterval = 500;
+    const deadline = Date.now() + maxWait;
+    // 'always' postcondition always passes immediately
+    if (spec.type === 'always') {
+        return { passed: true, reason: 'always passes' };
+    }
+    while (Date.now() < deadline) {
+        const result = await checkOnce(adapter, spec);
+        if (result.passed)
+            return result;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        await sleep(Math.min(pollInterval, remaining));
+    }
+    // Final check after timeout
+    return checkOnce(adapter, spec);
+}
+async function checkOnce(adapter, spec) {
+    switch (spec.type) {
+        case 'route_matches':
+            return checkRouteMatches(adapter, spec.pattern);
+        case 'element_visible':
+            return checkElementVisible(adapter, spec.selector);
+        case 'element_absent':
+            return checkElementAbsent(adapter, spec.selector);
+        case 'text_contains':
+            return checkTextContains(adapter, spec.selector, spec.text);
+        case 'overlay_dismissed':
+            return checkOverlayDismissed(adapter);
+        case 'screenshot_stable':
+            return checkScreenshotStable(adapter, spec.threshold ?? 0.01);
+        case 'any_change':
+            // 'any_change' is a soft postcondition — we just assume the action did something.
+            // The action-verifier handles real change detection via AKTree diff.
+            return { passed: true, reason: 'any_change always passes (action verifier handles real detection)' };
+        case 'always':
+            return { passed: true, reason: 'always passes' };
+        default:
+            return { passed: false, reason: `unknown postcondition type: ${spec.type}` };
+    }
+}
+// ── Individual checks ───────────────────────────────────────────────
+async function checkRouteMatches(adapter, pattern) {
+    const url = await adapter.getCurrentUrl();
+    try {
+        const { pathname, search } = new URL(url);
+        const fullPath = pathname + search;
+        // Support glob-like patterns: * matches anything, ** matches path segments
+        const regexStr = pattern
+            .replace(/\*\*/g, '.*')
+            .replace(/\*/g, '[^/]*')
+            .replace(/\?/g, '[^/]');
+        const regex = new RegExp(`^${regexStr}$`);
+        if (regex.test(fullPath) || regex.test(pathname)) {
+            return { passed: true, reason: `URL "${fullPath}" matches pattern "${pattern}"` };
+        }
+        return { passed: false, reason: `URL "${fullPath}" does not match pattern "${pattern}"` };
+    }
+    catch {
+        return { passed: false, reason: `invalid URL "${url}" or pattern "${pattern}"` };
+    }
+}
+async function checkElementVisible(adapter, selector) {
+    // Primary check: use Playwright waitFor (fast, reliable)
+    try {
+        const found = await adapter.waitFor({ selector, state: 'visible', timeoutMs: 2000 });
+        if (found) {
+            return { passed: true, reason: `element "${selector}" is visible (Playwright)` };
+        }
+    }
+    catch {
+        // Fall through to AKTree check
+    }
+    // Fallback: check AKTree
+    try {
+        const tree = await adapter.getAKTree();
+        if (hasVisibleNodeWithSelector(tree, selector)) {
+            return { passed: true, reason: `element "${selector}" is visible in AKTree` };
+        }
+        const serialized = serializeAKTree(tree);
+        if (serialized.includes(selector.replace(/[[\]"]/g, ''))) {
+            return { passed: true, reason: `element pattern "${selector}" found in serialized AKTree` };
+        }
+        return { passed: false, reason: `element "${selector}" not visible` };
+    }
+    catch {
+        return { passed: false, reason: `element "${selector}" not verifiable (AKTree unavailable)` };
+    }
+}
+async function checkElementAbsent(adapter, selector) {
+    // Use Playwright: if waitFor fails (element not found), it's absent = good
+    try {
+        const found = await adapter.waitFor({ selector, state: 'visible', timeoutMs: 1000 });
+        if (found) {
+            return { passed: false, reason: `element "${selector}" is still visible` };
+        }
+        return { passed: true, reason: `element "${selector}" is absent` };
+    }
+    catch {
+        return { passed: true, reason: `element "${selector}" is absent` };
+    }
+}
+async function checkTextContains(adapter, selector, expectedText) {
+    try {
+        const tree = await adapter.getAKTree();
+        const node = findNodeBySelector(tree, selector);
+        if (!node) {
+            return { passed: false, reason: `element "${selector}" not found for text check` };
+        }
+        const nodeText = (node.label || '') + (node.value || '');
+        if (nodeText.includes(expectedText)) {
+            return { passed: true, reason: `element "${selector}" contains "${expectedText}"` };
+        }
+        return { passed: false, reason: `element "${selector}" text "${nodeText}" does not contain "${expectedText}"` };
+    }
+    catch (err) {
+        return { passed: false, reason: `error checking text: ${err}` };
+    }
+}
+async function checkOverlayDismissed(adapter) {
+    try {
+        const tree = await adapter.getAKTree();
+        // Check if any overlays are reported in the tree
+        if (tree.overlays.length === 0) {
+            return { passed: true, reason: 'no overlays detected' };
+        }
+        // Check if remaining overlays are blocking
+        const blocking = tree.overlays.filter(o => o.blocksInteraction);
+        if (blocking.length === 0) {
+            return { passed: true, reason: 'overlays present but none blocking interaction' };
+        }
+        return { passed: false, reason: `${blocking.length} blocking overlay(s) still present` };
+    }
+    catch {
+        // If AKTree is unavailable (e.g. page.evaluate failure), assume overlays are dismissed.
+        // The overlay dismissal itself ran; we just can't verify via AKTree.
+        return { passed: true, reason: 'overlay check skipped (AKTree unavailable), assuming dismissed' };
+    }
+}
+let lastScreenshotHash = null;
+async function checkScreenshotStable(adapter, threshold) {
+    try {
+        const screenshot = await adapter.takeScreenshot();
+        const currentHash = simpleHash(screenshot);
+        if (lastScreenshotHash === null) {
+            lastScreenshotHash = currentHash;
+            // Wait and take another screenshot
+            await sleep(500);
+            const screenshot2 = await adapter.takeScreenshot();
+            const hash2 = simpleHash(screenshot2);
+            lastScreenshotHash = null;
+            if (currentHash === hash2) {
+                return { passed: true, reason: 'consecutive screenshots are identical' };
+            }
+            return { passed: false, reason: 'consecutive screenshots differ (page still changing)' };
+        }
+        // Compare with previous
+        if (currentHash === lastScreenshotHash) {
+            lastScreenshotHash = null;
+            return { passed: true, reason: 'screenshot matches previous' };
+        }
+        lastScreenshotHash = currentHash;
+        return { passed: false, reason: 'screenshot changed from previous check' };
+    }
+    catch (err) {
+        lastScreenshotHash = null;
+        return { passed: false, reason: `error checking screenshot stability: ${err}` };
+    }
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+function hasVisibleNodeWithSelector(tree, selector) {
+    // Walk the AKTree looking for a visible node whose sourceRef matches the selector
+    function walk(node) {
+        if (node.visible && node.sourceRef && matchesSelectorHeuristic(node.sourceRef, selector)) {
+            return true;
+        }
+        return node.children.some(walk);
+    }
+    return walk(tree.root);
+}
+function findNodeBySelector(tree, selector) {
+    function walk(node) {
+        if (node.sourceRef && matchesSelectorHeuristic(node.sourceRef, selector)) {
+            return node;
+        }
+        for (const child of node.children) {
+            const found = walk(child);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    return walk(tree.root);
+}
+/**
+ * Heuristic match between an AKTree sourceRef and a CSS-like selector.
+ * Not a full CSS selector engine — handles common patterns:
+ * - Tag name: "h1", "button"
+ * - ID: "#my-id"
+ * - data-testid: [data-testid="x"]
+ * - Class: ".my-class"
+ */
+function matchesSelectorHeuristic(sourceRef, selector) {
+    const lower = sourceRef.toLowerCase();
+    const selectorLower = selector.toLowerCase();
+    // data-testid match
+    const testIdMatch = selector.match(/\[data-testid=["'](.+?)["']\]/);
+    if (testIdMatch) {
+        return lower.includes(`data-testid="${testIdMatch[1]}"`);
+    }
+    // ID match
+    if (selector.startsWith('#')) {
+        return lower.includes(`id="${selector.slice(1)}"`) || lower.includes(`#${selector.slice(1)}`);
+    }
+    // Tag name match
+    if (/^[a-z][a-z0-9]*$/i.test(selector)) {
+        return lower.startsWith(`<${selectorLower}`) || lower.includes(`<${selectorLower} `);
+    }
+    // Fallback: contains
+    return lower.includes(selectorLower);
+}
+function simpleHash(buffer) {
+    // Fast non-crypto hash for screenshot comparison
+    let hash = 0;
+    const step = Math.max(1, Math.floor(buffer.length / 10000));
+    for (let i = 0; i < buffer.length; i += step) {
+        hash = ((hash << 5) - hash + buffer[i]) | 0;
+    }
+    return hash.toString(36);
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=postcondition.js.map

package/dist/v2/program-patcher.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Capture Agent — Program Patcher
+ *
+ * Applies healer patches to compiled programs.
+ * Patches are applied in-memory during the run, and propagated to
+ * the server ONLY after a fully successful run.
+ */
+import type { ExecutionProgram, HealerPatch } from './types.js';
+/**
+ * Applies a healer patch to a program in-place.
+ * The original opcode at the given index is replaced by the healer's output.
+ * If the healer produced multiple opcodes, subsequent steps are shifted.
+ *
+ * Returns the modified program (same reference, mutated).
+ */
+export declare function applyPatch(program: ExecutionProgram, patch: HealerPatch): ExecutionProgram;
+/**
+ * Applies all patches from a successful run to a program.
+ * Patches are applied in reverse index order to avoid shifting issues.
+ */
+export declare function applyAllPatches(program: ExecutionProgram, patches: HealerPatch[]): ExecutionProgram;
+/**
+ * Creates a deep clone of a program for safe patching.
+ */
+export declare function cloneProgram(program: ExecutionProgram): ExecutionProgram;

package/dist/v2/program-patcher.js

@@ -0,0 +1,44 @@
+/**
+ * Capture Agent — Program Patcher
+ *
+ * Applies healer patches to compiled programs.
+ * Patches are applied in-memory during the run, and propagated to
+ * the server ONLY after a fully successful run.
+ */
+/**
+ * Applies a healer patch to a program in-place.
+ * The original opcode at the given index is replaced by the healer's output.
+ * If the healer produced multiple opcodes, subsequent steps are shifted.
+ *
+ * Returns the modified program (same reference, mutated).
+ */
+export function applyPatch(program, patch) {
+    const { opcodeIndex, replacementOpcodes } = patch;
+    if (opcodeIndex < 0 || opcodeIndex >= program.steps.length) {
+        throw new Error(`patch index ${opcodeIndex} out of bounds (program has ${program.steps.length} steps)`);
+    }
+    // Replace the failed opcode with the replacement(s)
+    program.steps.splice(opcodeIndex, 1, ...replacementOpcodes);
+    // Bump version
+    program.programVersion++;
+    return program;
+}
+/**
+ * Applies all patches from a successful run to a program.
+ * Patches are applied in reverse index order to avoid shifting issues.
+ */
+export function applyAllPatches(program, patches) {
+    // Sort patches by index descending to apply from end to start
+    const sorted = [...patches].sort((a, b) => b.opcodeIndex - a.opcodeIndex);
+    for (const patch of sorted) {
+        applyPatch(program, patch);
+    }
+    return program;
+}
+/**
+ * Creates a deep clone of a program for safe patching.
+ */
+export function cloneProgram(program) {
+    return JSON.parse(JSON.stringify(program));
+}
+//# sourceMappingURL=program-patcher.js.map

package/dist/v2/recovery-chain.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 type { ExecutionOpcode, RuntimeAdapter } from './types.js';
+import type { RecoveryChain as IRecoveryChain, RecoveryAttemptResult, RecoveryAttemptOptions } from './opcode-runner.js';
+import { type HealerLLMProvider } from './llm-healer.js';
+export interface RecoveryChainOptions {
+    /** Selector memory: stepSignature -> known-good selectors */
+    selectorMemory?: Record<string, string[]>;
+    /** LLM provider for the healer (optional, disables healer if not provided) */
+    llmProvider?: HealerLLMProvider;
+    /** Max healer invocations per run. Default: 3 */
+    maxHealerInvocations?: number;
+    /** Full program steps for healer context */
+    programSteps?: ExecutionOpcode[];
+}
+export declare class RecoveryChainImpl implements IRecoveryChain {
+    private healer;
+    private selectorMemory;
+    private programSteps;
+    constructor(options?: RecoveryChainOptions);
+    attempt(failedOpcode: ExecutionOpcode, opcodeIndex: number, adapter: RuntimeAdapter, options?: RecoveryAttemptOptions): Promise<RecoveryAttemptResult>;
+}