autokap 1.0.7 → 1.0.8

package/dist/openrouter-client.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Type-safe OpenRouter extensions for the OpenAI SDK.
+ *
+ * OpenRouter extends the standard chat completion API with fields like `provider`
+ * and `reasoning` that the official OpenAI types don't include. This module provides
+ * augmented types to avoid `as any` casts across the codebase.
+ */
+import type OpenAI from 'openai';
+import type { ChatCompletionCreateParamsNonStreaming } from 'openai/resources/chat/completions';
+/** OpenRouter provider routing preferences. */
+export interface OpenRouterProvider {
+    /** Zero Data Retention mode. */
+    zdr?: boolean;
+    /** Allow fallback providers. */
+    allow_fallbacks?: boolean;
+    /** Required providers (whitelist). */
+    require_parameters?: boolean;
+    /** Provider order preference. */
+    order?: string[];
+    /** Quantization preference. */
+    quantizations?: string[];
+    /** Additional provider preferences (model-specific). */
+    [key: string]: unknown;
+}
+/** OpenRouter reasoning configuration for extended thinking models. */
+export interface OpenRouterReasoning {
+    effort: 'none' | 'low' | 'medium' | 'high' | 'xhigh';
+}
+/** Chat completion params extended with OpenRouter-specific fields. */
+export type OpenRouterChatCompletionParams = ChatCompletionCreateParamsNonStreaming & {
+    provider?: OpenRouterProvider;
+    reasoning?: OpenRouterReasoning;
+};
+/**
+ * Create a chat completion with OpenRouter-specific fields.
+ * Wraps `client.chat.completions.create()` with proper typing.
+ */
+export declare function createOpenRouterCompletion(client: OpenAI, params: OpenRouterChatCompletionParams, options?: {
+    signal?: AbortSignal;
+}): Promise<OpenAI.Chat.Completions.ChatCompletion>;

package/dist/openrouter-client.js

@@ -0,0 +1,16 @@
+/**
+ * Type-safe OpenRouter extensions for the OpenAI SDK.
+ *
+ * OpenRouter extends the standard chat completion API with fields like `provider`
+ * and `reasoning` that the official OpenAI types don't include. This module provides
+ * augmented types to avoid `as any` casts across the codebase.
+ */
+/**
+ * Create a chat completion with OpenRouter-specific fields.
+ * Wraps `client.chat.completions.create()` with proper typing.
+ */
+export function createOpenRouterCompletion(client, params, options) {
+    // OpenRouter accepts these extra fields; we cast once here instead of 16 times
+    return client.chat.completions.create(params, options);
+}
+//# sourceMappingURL=openrouter-client.js.map

package/dist/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 './execution-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>;

package/dist/overlay-engine.js

@@ -0,0 +1,176 @@
+/**
+ * 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 snapshot = await readOverlaySnapshot(adapter);
+    if (!snapshot) {
+        return {
+            dismissed: methods.length > 0,
+            methods,
+            overlaysFound: 0,
+            overlaysRemaining: 0,
+        };
+    }
+    let tree = snapshot.tree;
+    let blocking = snapshot.blocking;
+    totalFound = snapshot.totalFound;
+    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);
+        snapshot = await readOverlaySnapshot(adapter);
+        if (snapshot && snapshot.blocking.length < blocking.length) {
+            methods.push('escape-key');
+        }
+        if (snapshot && snapshot.blocking.length === 0) {
+            return { dismissed: true, methods, overlaysFound: totalFound, overlaysRemaining: 0 };
+        }
+        if (snapshot) {
+            tree = snapshot.tree;
+            blocking = snapshot.blocking;
+        }
+    }
+    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
+    snapshot = await readOverlaySnapshot(adapter);
+    const finalBlocking = snapshot?.blocking ?? [];
+    return {
+        dismissed: methods.length > 0,
+        methods,
+        overlaysFound: totalFound,
+        overlaysRemaining: finalBlocking.length,
+    };
+}
+async function readOverlaySnapshot(adapter) {
+    try {
+        const tree = await adapter.getAKTree();
+        const blocking = tree.overlays.filter(o => o.blocksInteraction);
+        return {
+            tree,
+            blocking,
+            totalFound: tree.overlays.length,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+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/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 './execution-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/postcondition.js

@@ -0,0 +1,269 @@
+/**
+ * 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 (incl. slashes / empty),
+        // * matches a single path segment, ? matches one non-slash char.
+        // Tokenize in one pass so the `*` rewrite doesn't clobber the `*` produced
+        // by the `**` rewrite (e.g. `/home**` must compile to `^/home.*$`, not
+        // `^/home.[^/]*$` which would reject `/home` itself).
+        let regexStr = '';
+        for (let i = 0; i < pattern.length; i++) {
+            const ch = pattern[i];
+            if (ch === '*' && pattern[i + 1] === '*') {
+                regexStr += '.*';
+                i++;
+            }
+            else if (ch === '*') {
+                regexStr += '[^/]*';
+            }
+            else if (ch === '?') {
+                regexStr += '[^/]';
+            }
+            else if (/[.+^${}()|[\]\\]/.test(ch)) {
+                regexStr += `\\${ch}`;
+            }
+            else {
+                regexStr += ch;
+            }
+        }
+        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/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 './execution-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/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/prompts.d.ts

@@ -1,5 +1,5 @@
 import type { ChatCompletionContentPart } from 'openai/resources/chat/completions';
-import type { AgentConfig, AgentRunHint, CaptureCursor, CaptureObjective, CaptureHandoffContext, ExecutedAction, InteractiveElement, LoginCredentials, RepairTicket, VariantCaptureManifest, ValidatedSessionProfile, WorkflowScreenshot } from './types.js';
+import type { AgentConfig, AgentRunHint, CaptureCursor, CaptureObjective, CaptureHandoffContext, ExecutedAction, InteractiveElement, LoginCredentials, OverlayScopeSummary, RepairTicket, VariantCaptureManifest, ValidatedSessionProfile, WorkflowScreenshot } from './types.js';
 interface SystemPromptOptions {
     reasoningLocale?: string;
 }
@@ -29,6 +29,7 @@ export interface StableAnchorUserMessageParams {
 }
 export interface IterationUserMessageParams {
     userPrompt: string;
+    serializedAKTree: string;
     cleanScreenshotUrl?: string;
     screenshotUrl: string;
     /** In dual-model mode, the vision model's text observation replaces images. */
@@ -107,6 +108,10 @@ export interface IterationUserMessageParams {
     };
     /** Compact summary of recent failed actions — prevents the agent from repeating dead-end strategies. */
     failedAttemptsSummary?: string;
+    /** When true, the browser is already on the target URL — the agent should check and capture, not navigate. */
+    alreadyOnTarget?: boolean;
+    promptFingerprint?: string;
+    overlayScope?: OverlayScopeSummary | null;
 }
 export declare function buildStableAnchorUserMessage(params: StableAnchorUserMessageParams): {
     content: ChatCompletionContentPart[];
@@ -140,6 +145,7 @@ export declare function buildVisionObserverPrompt(params: {
     currentUrl: string;
     interactiveElements: InteractiveElement[];
     userGoal: string;
+    question?: string;
     currentLang?: string;
     currentTheme?: 'light' | 'dark';
     currentPageId?: string;
@@ -150,9 +156,7 @@ export declare function buildElementSystemPrompt(description: string): string;
 export declare function buildElementIterationMessage(params: {
     elementName: string;
     elementDescription: string;
-    accessibilityTree: string;
-    interactiveElements: InteractiveElement[];
-    simplifiedDOM?: string;
+    serializedAKTree: string;
     currentUrl: string;
     iteration: number;
     maxIterations: number;
@@ -161,7 +165,11 @@ export declare function buildElementIterationMessage(params: {
         width: number;
         height: number;
     };
-    forbiddenSearchQueries?: string[];
+    scrollInfo?: {
+        scrollY: number;
+        scrollHeight: number;
+        viewportHeight: number;
+    };
     screenshotUrl?: string;
 }): ChatCompletionContentPart[];
 export {};