autokap 1.0.6 → 1.0.8

package/dist/v2/opcode-runner.js

@@ -0,0 +1,634 @@
+/**
+ * Capture Agent — Opcode Runner
+ *
+ * Deterministic execution engine for ExecutionProgram.
+ * Executes opcodes sequentially, verifies postconditions,
+ * delegates to recovery chain on failure, and respects circuit breaker.
+ */
+import { evaluatePostcondition } from './postcondition.js';
+import { ActionVerifier } from './action-verifier.js';
+import { CircuitBreaker } from './circuit-breaker.js';
+import { smartWaitForStability } from './smart-wait.js';
+import { verifyCaptureQuality } from './capture-verification.js';
+import { generateAltText } from './alt-text.js';
+/** No-op recovery chain for Phase 1 (deterministic-only execution) */
+export class NoOpRecoveryChain {
+    async attempt() {
+        return { recovered: false, reason: 'no recovery chain configured' };
+    }
+}
+// ── Main execution function ─────────────────────────────────────────
+export async function executeProgram(program, createAdapter, options = {}) {
+    const recoveryChain = options.recoveryChain ?? new NoOpRecoveryChain();
+    const startTime = Date.now();
+    const variantResults = [];
+    const healerPatches = [];
+    const telemetry = {
+        llmCallCount: 0,
+        llmCostEur: 0,
+        llmStepUsages: [],
+        totalOpcodes: 0,
+        recoveredOpcodes: 0,
+        failedOpcodes: 0,
+        healerInvocations: 0,
+        circuitBreakerTrips: 0,
+    };
+    for (const variant of program.variants) {
+        if (options.abortSignal?.aborted)
+            break;
+        options.onProgress?.({
+            type: 'variant_start',
+            variantId: variant.id,
+            message: `starting variant ${variant.id}`,
+        });
+        const variantResult = await executeVariant(program, variant, createAdapter, recoveryChain, telemetry, healerPatches, options);
+        variantResults.push(variantResult);
+        options.onProgress?.({
+            type: 'variant_end',
+            variantId: variant.id,
+            status: variantResult.success ? 'ok' : 'failed',
+            message: variantResult.success
+                ? `variant ${variant.id} completed`
+                : `variant ${variant.id} failed: ${variantResult.error}`,
+        });
+    }
+    const aborted = options.abortSignal?.aborted && variantResults.length < program.variants.length;
+    const success = !aborted && variantResults.length > 0 && variantResults.every(v => v.success);
+    return {
+        programId: program.presetId,
+        success,
+        variantResults,
+        telemetry,
+        healerPatches: success ? healerPatches : [], // Only propagate patches on success
+        totalDurationMs: Date.now() - startTime,
+        error: aborted ? 'aborted' : (success ? undefined : variantResults.find(v => !v.success)?.error),
+    };
+}
+// ── Variant execution ───────────────────────────────────────────────
+async function executeVariant(program, variant, createAdapter, recoveryChain, telemetry, healerPatches, options) {
+    const startTime = Date.now();
+    const breaker = new CircuitBreaker();
+    const verifier = new ActionVerifier();
+    const opcodeResults = [];
+    const artifacts = [];
+    const executionState = {};
+    let adapter = null;
+    try {
+        adapter = await createAdapter(variant);
+        for (let i = 0; i < program.steps.length; i++) {
+            if (options.abortSignal?.aborted) {
+                return {
+                    variantId: variant.id,
+                    success: false,
+                    opcodeResults,
+                    durationMs: Date.now() - startTime,
+                    artifacts,
+                    error: 'aborted',
+                };
+            }
+            // Check circuit breaker before starting
+            const breakerState = breaker.isTripped();
+            if (breakerState.tripped) {
+                telemetry.circuitBreakerTrips++;
+                options.onProgress?.({
+                    type: 'breaker_trip',
+                    variantId: variant.id,
+                    opcodeIndex: i,
+                    message: breakerState.reason,
+                });
+                return {
+                    variantId: variant.id,
+                    success: false,
+                    opcodeResults,
+                    durationMs: Date.now() - startTime,
+                    artifacts,
+                    error: `circuit breaker tripped: ${breakerState.reason}`,
+                };
+            }
+            const opcode = program.steps[i];
+            options.onProgress?.({
+                type: 'opcode_start',
+                variantId: variant.id,
+                opcodeIndex: i,
+                opcodeKind: opcode.kind,
+                message: opcode.description,
+            });
+            const result = await executeOpcode(opcode, i, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, artifacts, options, variant.id, executionState, program.artifactPlan, variant);
+            opcodeResults.push(result);
+            telemetry.totalOpcodes++;
+            if (result.status === 'recovered')
+                telemetry.recoveredOpcodes++;
+            if (result.status === 'failed')
+                telemetry.failedOpcodes++;
+            options.onProgress?.({
+                type: 'opcode_end',
+                variantId: variant.id,
+                opcodeIndex: i,
+                opcodeKind: opcode.kind,
+                status: result.status,
+                message: result.error ?? `${opcode.kind} ${result.status}`,
+            });
+            // Abort variant on fatal opcode failure
+            if (result.status === 'failed') {
+                return {
+                    variantId: variant.id,
+                    success: false,
+                    opcodeResults,
+                    durationMs: Date.now() - startTime,
+                    artifacts,
+                    error: `opcode ${i} (${opcode.kind}) failed: ${result.error}`,
+                };
+            }
+        }
+        return {
+            variantId: variant.id,
+            success: true,
+            opcodeResults,
+            durationMs: Date.now() - startTime,
+            artifacts,
+        };
+    }
+    catch (err) {
+        return {
+            variantId: variant.id,
+            success: false,
+            opcodeResults,
+            durationMs: Date.now() - startTime,
+            artifacts,
+            error: `unexpected error: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    finally {
+        if (adapter) {
+            try {
+                await adapter.close();
+            }
+            catch { /* ignore close errors */ }
+        }
+    }
+}
+// ── Single opcode execution ─────────────────────────────────────────
+async function executeOpcode(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, artifacts, options, variantId, executionState, artifactPlan, currentVariant) {
+    const startTime = Date.now();
+    const deadlineMs = startTime + opcode.timeoutMs;
+    const isInteraction = ['CLICK', 'TYPE', 'PRESS_KEY', 'SCROLL'].includes(opcode.kind);
+    // Track page context for circuit breaker
+    try {
+        const url = await adapter.getCurrentUrl();
+        breaker.setPage(url);
+    }
+    catch { /* ignore */ }
+    // Execute with timeout
+    try {
+        if (isInteraction) {
+            await verifier.captureBeforeState(adapter);
+        }
+        const actionBudgetMs = getRemainingTimeMs(deadlineMs);
+        if (actionBudgetMs <= 0) {
+            return handleFailure(opcode, index, adapter, breaker, recoveryChain, telemetry, healerPatches, options, variantId, startTime, deadlineMs, `timeout after ${opcode.timeoutMs}ms`);
+        }
+        const result = await withTimeout(() => executeOpcodeAction(opcode, index, adapter, artifacts, telemetry, currentVariant, executionState, artifactPlan, options), actionBudgetMs);
+        if (!result.success) {
+            return handleFailure(opcode, index, adapter, breaker, recoveryChain, telemetry, healerPatches, options, variantId, startTime, deadlineMs, result.error ?? 'action failed');
+        }
+        // Verify postcondition
+        const postconditionBudgetMs = getRemainingTimeMs(deadlineMs);
+        if (postconditionBudgetMs <= 0) {
+            return handleFailure(opcode, index, adapter, breaker, recoveryChain, telemetry, healerPatches, options, variantId, startTime, deadlineMs, `timeout after ${opcode.timeoutMs}ms`);
+        }
+        const postcondition = await evaluatePostcondition(adapter, withClampedPostconditionTimeout(opcode.postcondition, postconditionBudgetMs));
+        if (!postcondition.passed) {
+            return handleFailure(opcode, index, adapter, breaker, recoveryChain, telemetry, healerPatches, options, variantId, startTime, deadlineMs, `postcondition failed: ${postcondition.reason}`);
+        }
+        // Verify action had effect (for interaction opcodes)
+        if (isInteraction) {
+            const verification = await verifier.verifyAfterAction(adapter);
+            if (!verification.hadEffect && opcode.postcondition.type !== 'always' && opcode.postcondition.type !== 'any_change') {
+                return handleFailure(opcode, index, adapter, breaker, recoveryChain, telemetry, healerPatches, options, variantId, startTime, deadlineMs, `action had no effect: ${verification.summary}`);
+            }
+        }
+        breaker.recordSuccess(index);
+        return {
+            opcodeIndex: index,
+            kind: opcode.kind,
+            status: 'ok',
+            durationMs: Date.now() - startTime,
+            recoveryAttempts: 0,
+        };
+    }
+    catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        return handleFailure(opcode, index, adapter, breaker, recoveryChain, telemetry, healerPatches, options, variantId, startTime, deadlineMs, errorMsg);
+    }
+}
+// ── Failure handling with recovery ──────────────────────────────────
+async function handleFailure(opcode, index, adapter, breaker, recoveryChain, telemetry, healerPatches, options, variantId, startTime, deadlineMs, errorMsg) {
+    const breakerState = breaker.recordFailure(index, opcode.maxFailures);
+    if (breakerState.tripped) {
+        telemetry.circuitBreakerTrips++;
+        return {
+            opcodeIndex: index,
+            kind: opcode.kind,
+            status: 'failed',
+            durationMs: Date.now() - startTime,
+            recoveryAttempts: 0,
+            error: `${errorMsg} (circuit breaker: ${breakerState.reason})`,
+        };
+    }
+    const remainingTimeMs = getRemainingTimeMs(deadlineMs);
+    if (remainingTimeMs <= 0) {
+        return {
+            opcodeIndex: index,
+            kind: opcode.kind,
+            status: 'failed',
+            durationMs: Date.now() - startTime,
+            recoveryAttempts: 0,
+            error: `${errorMsg} (timeout after ${opcode.timeoutMs}ms)`,
+        };
+    }
+    // Attempt recovery
+    options.onProgress?.({
+        type: 'recovery',
+        variantId,
+        opcodeIndex: index,
+        opcodeKind: opcode.kind,
+        message: `recovering from: ${errorMsg}`,
+    });
+    const recovery = await recoveryChain.attempt(opcode, index, adapter, {
+        remainingTimeMs,
+        maxDeterministicRetries: Math.max(0, opcode.maxFailures - breakerState.opcodeFailures),
+    });
+    if (recovery.recovered) {
+        if (recovery.patch) {
+            healerPatches.push(recovery.patch);
+            telemetry.healerInvocations++;
+        }
+        breaker.recordSuccess(index);
+        return {
+            opcodeIndex: index,
+            kind: opcode.kind,
+            status: 'recovered',
+            durationMs: Date.now() - startTime,
+            recoveryAttempts: 1,
+            recoveryStrategy: recovery.strategy,
+        };
+    }
+    return {
+        opcodeIndex: index,
+        kind: opcode.kind,
+        status: 'failed',
+        durationMs: Date.now() - startTime,
+        recoveryAttempts: 1,
+        error: `${errorMsg} (recovery failed: ${recovery.reason})`,
+    };
+}
+// ── Opcode action dispatch ──────────────────────────────────────────
+async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, telemetry, currentVariant, executionState, artifactPlan, runOptions) {
+    try {
+        void artifactPlan;
+        switch (opcode.kind) {
+            case 'NAVIGATE':
+                await adapter.navigate(opcode.url);
+                break;
+            case 'DISMISS_OVERLAYS':
+                await adapter.dismissOverlays();
+                break;
+            case 'ASSERT_ROUTE':
+                return evaluateImmediateAssertion(await evaluatePostcondition(adapter, {
+                    type: 'route_matches',
+                    pattern: opcode.urlPattern,
+                    waitMs: 1,
+                }), 'ASSERT_ROUTE failed');
+            case 'ASSERT_SURFACE':
+                return evaluateSurfaceAssertion(adapter, opcode.selectors, opcode.matchAll);
+            case 'CLICK':
+                try {
+                    await adapter.click(opcode.selector);
+                }
+                catch (error) {
+                    if (!opcode.target || !adapter.clickByTarget)
+                        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 (!opcode.target || !adapter.typeByTarget)
+                        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': {
+                // WAIT_FOR supports both selector and semantic target
+                const waitSelector = opcode.selector;
+                if (waitSelector) {
+                    const found = await adapter.waitFor({
+                        selector: waitSelector,
+                        state: opcode.state,
+                        timeoutMs: opcode.timeoutMs,
+                    });
+                    if (!found) {
+                        return { success: false, error: `element "${waitSelector}" not found within timeout` };
+                    }
+                }
+                else if (opcode.target && adapter.waitForTarget) {
+                    const found = await adapter.waitForTarget({ target: opcode.target }, opcode.timeoutMs);
+                    if (!found) {
+                        return { success: false, error: `target "${opcode.target.text ?? opcode.target.role ?? 'unknown'}" not found within timeout` };
+                    }
+                }
+                else {
+                    return { success: false, error: 'WAIT_FOR needs a selector or target' };
+                }
+                break;
+            }
+            case 'SET_LOCALE':
+                return applyLocaleOpcode(opcode, adapter);
+            case 'SET_THEME':
+                return applyThemeOpcode(opcode, adapter);
+            case 'SCROLL':
+                if (opcode.targetSelector) {
+                    await adapter.scrollIntoView(opcode.targetSelector);
+                }
+                else if (opcode.target && adapter.scrollIntoViewByTarget) {
+                    await adapter.scrollIntoViewByTarget({ target: opcode.target });
+                }
+                else {
+                    await adapter.scroll(opcode.direction, opcode.amount);
+                }
+                break;
+            case 'CAPTURE_SCREENSHOT': {
+                await smartWaitForStability(adapter, { maxWaitMs: 5000 });
+                const captureUrl = await adapter.getCurrentUrl();
+                const takeBuffer = async () => {
+                    if (opcode.elementSelector && adapter.takeElementScreenshot) {
+                        return adapter.takeElementScreenshot(opcode.elementSelector);
+                    }
+                    if (opcode.elementSelector) {
+                        throw new Error(`element capture requires adapter support for selector "${opcode.elementSelector}"`);
+                    }
+                    return adapter.takeScreenshot();
+                };
+                let buffer = await takeBuffer();
+                if (runOptions?.llmConfig) {
+                    const verification = await verifyCaptureQuality(buffer, {
+                        expectedDescription: opcode.description,
+                        url: captureUrl,
+                        locale: currentVariant?.locale,
+                        theme: currentVariant?.theme,
+                    }, runOptions.llmConfig);
+                    if (verification.llmResult) {
+                        telemetry.llmCallCount++;
+                        telemetry.llmCostEur += verification.llmResult.costEur;
+                        telemetry.llmStepUsages.push({
+                            stepType: 'capture_verification',
+                            generationId: verification.llmResult.generationId,
+                            model: verification.llmResult.model,
+                            promptTokens: verification.llmResult.promptTokens,
+                            completionTokens: verification.llmResult.completionTokens,
+                        });
+                    }
+                    if (!verification.passed) {
+                        await smartWaitForStability(adapter, { maxWaitMs: 8000 });
+                        const retryBuffer = await takeBuffer();
+                        const retryVerification = await verifyCaptureQuality(retryBuffer, {
+                            expectedDescription: opcode.description,
+                            url: captureUrl,
+                            locale: currentVariant?.locale,
+                            theme: currentVariant?.theme,
+                        }, runOptions.llmConfig);
+                        if (retryVerification.llmResult) {
+                            telemetry.llmCallCount++;
+                            telemetry.llmCostEur += retryVerification.llmResult.costEur;
+                            telemetry.llmStepUsages.push({
+                                stepType: 'capture_verification',
+                                generationId: retryVerification.llmResult.generationId,
+                                model: retryVerification.llmResult.model,
+                                promptTokens: retryVerification.llmResult.promptTokens,
+                                completionTokens: retryVerification.llmResult.completionTokens,
+                            });
+                        }
+                        if (retryVerification.passed) {
+                            buffer = retryBuffer;
+                        }
+                    }
+                }
+                let altText;
+                if (runOptions?.llmConfig) {
+                    try {
+                        const altResult = await generateAltText(buffer, {
+                            description: opcode.description,
+                            url: captureUrl,
+                            locale: currentVariant?.locale,
+                            presetName: runOptions.presetName,
+                        }, runOptions.llmConfig);
+                        altText = altResult.altText;
+                        if (altResult.llmResult) {
+                            telemetry.llmCallCount++;
+                            telemetry.llmCostEur += altResult.llmResult.costEur;
+                            telemetry.llmStepUsages.push({
+                                stepType: 'alt_text_generation',
+                                generationId: altResult.llmResult.generationId,
+                                model: altResult.llmResult.model,
+                                promptTokens: altResult.llmResult.promptTokens,
+                                completionTokens: altResult.llmResult.completionTokens,
+                            });
+                        }
+                    }
+                    catch {
+                        // Alt text generation failed — non-fatal
+                    }
+                }
+                artifacts.push({
+                    mediaMode: 'screenshot',
+                    buffer,
+                    mimeType: 'image/png',
+                    captureType: opcode.elementSelector ? 'element' : 'fullpage',
+                    captureUrl,
+                    dimensions: currentVariant?.viewport,
+                    captureId: opcode.captureId,
+                    captureName: opcode.captureName ?? opcode.description,
+                    elementSelector: opcode.elementSelector,
+                    altText,
+                    stepDescription: opcode.description,
+                    stepIndex: opcodeIndex,
+                    variantId: currentVariant?.id,
+                });
+                break;
+            }
+            case 'BEGIN_CLIP':
+                if (executionState.activeClip) {
+                    return { success: false, error: 'cannot start a new clip before the previous one ends' };
+                }
+                executionState.activeClip = {
+                    clipId: opcode.clipId,
+                    clipName: opcode.clipName,
+                };
+                await adapter.beginRecording({ mediaMode: 'clip' });
+                break;
+            case 'END_CLIP': {
+                const clipIdentity = resolveClipIdentity(executionState.activeClip, opcode);
+                const recording = await adapter.endRecording();
+                executionState.activeClip = undefined;
+                artifacts.push({
+                    mediaMode: 'clip',
+                    buffer: recording.buffer,
+                    mimeType: recording.mimeType,
+                    durationMs: recording.durationMs,
+                    trimStartMs: recording.trimStartMs,
+                    dimensions: undefined,
+                    captureType: 'fullpage',
+                    captureUrl: await adapter.getCurrentUrl(),
+                    clipId: clipIdentity.clipId,
+                    clipName: clipIdentity.clipName,
+                    stepDescription: opcode.description,
+                    stepIndex: opcodeIndex,
+                    variantId: currentVariant?.id,
+                });
+                break;
+            }
+            default: {
+                const _exhaustive = opcode;
+                return { success: false, error: `unknown opcode kind: ${opcode.kind}` };
+            }
+        }
+        return { success: true };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+async function withTimeout(fn, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`timeout after ${timeoutMs}ms`)), timeoutMs);
+        fn()
+            .then(result => { clearTimeout(timer); resolve(result); })
+            .catch(err => { clearTimeout(timer); reject(err); });
+    });
+}
+function getRemainingTimeMs(deadlineMs) {
+    return Math.max(0, deadlineMs - Date.now());
+}
+function resolveClipIdentity(activeClip, opcode) {
+    if (activeClip?.clipId && opcode.clipId && activeClip.clipId !== opcode.clipId) {
+        throw new Error(`END_CLIP clipId "${opcode.clipId}" does not match active clip "${activeClip.clipId}"`);
+    }
+    return {
+        clipId: opcode.clipId ?? activeClip?.clipId,
+        clipName: opcode.clipName ?? activeClip?.clipName ?? opcode.description,
+    };
+}
+function withClampedPostconditionTimeout(spec, maxWaitMs) {
+    return {
+        ...spec,
+        waitMs: Math.max(1, Math.min(spec.waitMs ?? maxWaitMs, maxWaitMs)),
+    };
+}
+function evaluateImmediateAssertion(result, prefix) {
+    return result.passed
+        ? { success: true }
+        : { success: false, error: `${prefix}: ${result.reason}` };
+}
+async function evaluateSurfaceAssertion(adapter, selectors, matchAll) {
+    const checks = await Promise.all(selectors.map(async (selector) => ({
+        selector,
+        result: await evaluatePostcondition(adapter, {
+            type: 'element_visible',
+            selector,
+            waitMs: 1,
+        }),
+    })));
+    if (matchAll) {
+        const failed = checks.find((entry) => !entry.result.passed);
+        return failed
+            ? { success: false, error: `ASSERT_SURFACE failed for "${failed.selector}": ${failed.result.reason}` }
+            : { success: true };
+    }
+    if (checks.some((entry) => entry.result.passed)) {
+        return { success: true };
+    }
+    return {
+        success: false,
+        error: `ASSERT_SURFACE failed: none of the selectors matched (${selectors.join(', ')})`,
+    };
+}
+async function applyLocaleOpcode(opcode, adapter) {
+    if (opcode.method === 'browser_context') {
+        await adapter.setLocale(opcode.locale);
+        if (adapter.reloadPage) {
+            await adapter.reloadPage();
+        }
+        return { success: true };
+    }
+    if (opcode.method === 'ui_interaction') {
+        if (!opcode.selector) {
+            return { success: false, error: 'SET_LOCALE ui_interaction requires selector' };
+        }
+        await adapter.click(opcode.selector);
+        return { success: true };
+    }
+    if (!opcode.storageHints || opcode.storageHints.length === 0 || !adapter.writeStorageHint) {
+        return { success: false, error: 'SET_LOCALE storage mode requires storageHints and adapter storage support' };
+    }
+    const writes = await Promise.all(opcode.storageHints.map((hint) => adapter.writeStorageHint({
+        storage: hint.storage,
+        key: hint.key,
+        value: hint.value,
+        kind: 'locale',
+    })));
+    if (!writes.some(Boolean)) {
+        return { success: false, error: 'SET_LOCALE storage hints did not match any writable locale keys' };
+    }
+    if (adapter.reloadPage) {
+        await adapter.reloadPage();
+    }
+    return { success: true };
+}
+async function applyThemeOpcode(opcode, adapter) {
+    if (opcode.method === 'color_scheme') {
+        await adapter.setColorScheme(opcode.theme);
+        return { success: true };
+    }
+    if (opcode.method === 'ui_interaction') {
+        if (!opcode.selector) {
+            return { success: false, error: 'SET_THEME ui_interaction requires selector' };
+        }
+        await adapter.click(opcode.selector);
+        return { success: true };
+    }
+    if (!opcode.storageHints || opcode.storageHints.length === 0 || !adapter.writeStorageHint) {
+        return { success: false, error: 'SET_THEME storage mode requires storageHints and adapter storage support' };
+    }
+    const writes = await Promise.all(opcode.storageHints.map((hint) => adapter.writeStorageHint({
+        storage: hint.storage,
+        key: hint.key,
+        value: hint.value,
+        kind: 'theme',
+    })));
+    if (!writes.some(Boolean)) {
+        return { success: false, error: 'SET_THEME storage hints did not match any writable theme keys' };
+    }
+    if (adapter.reloadPage) {
+        await adapter.reloadPage();
+    }
+    return { success: true };
+}
+//# sourceMappingURL=opcode-runner.js.map

package/dist/v2/overlay-engine.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+import type { RuntimeAdapter } from './types.js';
+export interface OverlayDismissResult {
+    dismissed: boolean;
+    methods: string[];
+    overlaysFound: number;
+    overlaysRemaining: number;
+}
+/**
+ * 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 declare function dismissAllOverlays(adapter: RuntimeAdapter): Promise<OverlayDismissResult>;