autokap 1.0.5 → 1.0.7

package/dist/agent.js

@@ -0,0 +1,4511 @@
+import OpenAI from 'openai';
+import { describeObservationChange } from './browser.js';
+import { agentTools } from './tools.js';
+import { buildSystemPrompt, buildStableAnchorUserMessage, buildIterationUserMessage, buildVerificationMessage, buildVisionObserverPrompt, } from './prompts.js';
+import { logger, emitScreenshot, emitReasoningDelta } from './logger.js';
+import { extractStepUsage } from './llm-usage.js';
+import { hasManualMultiProviderOrder, resolvePromptCacheStrategy } from './prompt-cache.js';
+import { dismissCookiesAndWidgets } from './cookie-dismiss.js';
+import { describeSecurityTarget, evaluateActionSecurity } from './security.js';
+import { getPostHog, DISTINCT_ID } from './posthog.js';
+import { isAbortError, sleepWithAbort, throwIfAborted } from './abort.js';
+import { evaluateRequestedLanguageState, evaluateRequestedThemeState, performDeterministicSessionRepair, } from './session-profile.js';
+import { resolveActionCredentialArgs, sanitizeCredentialParams, } from './credential-templates.js';
+import { callVisionCapableModel, VisionModelUnsupportedError, } from './vision-model.js';
+import { createHash } from 'crypto';
+/**
+ * Converts a screenshot buffer to an image URL for LLM messages.
+ * Uses the provided uploader (Supabase storage → HTTPS URL) when available,
+ * falls back to a base64 data URI for compatibility.
+ */
+async function makeImageUrl(buffer, mimeType, uploadImage) {
+    if (uploadImage) {
+        try {
+            return await uploadImage(buffer, mimeType);
+        }
+        catch {
+            // fall through to base64
+        }
+    }
+    return `data:${mimeType};base64,${buffer.toString('base64')}`;
+}
+function computeScreenshotFingerprint(buffer) {
+    return createHash('sha1').update(buffer).digest('hex');
+}
+function summarizeVariantManifestForPlanner(manifest) {
+    if (!manifest)
+        return '';
+    const parts = [
+        `expected=${manifest.expectedPageIds.join(',') || 'main'}`,
+        `current=${manifest.currentPageId ?? 'main'}`,
+        manifest.currentPageIdentity ? `identity=${manifest.currentPageIdentity.summary}` : '',
+        `completed=${manifest.completedPages.join(',') || 'none'}`,
+        `remaining=${manifest.remainingPages.join(',') || 'none'}`,
+        manifest.lastCheckpointId ? `checkpoint=${manifest.lastCheckpointId}` : '',
+    ];
+    if (manifest.captureStatuses) {
+        parts.push(`statuses=${Object.entries(manifest.captureStatuses)
+            .slice(0, 6)
+            .map(([pageId, status]) => `${pageId}:${status}`)
+            .join('|') || 'none'}`);
+    }
+    if (manifest.previousValidatedCaptures.length > 0) {
+        parts.push(`validated=${manifest.previousValidatedCaptures
+            .slice(-3)
+            .map((capture) => `${capture.pageId}${capture.identity ? `[${capture.identity.summary}]` : ''}:${capture.assessment.slice(0, 80)}`)
+            .join(' | ')}`);
+    }
+    return parts.join('; ');
+}
+function summarizeCaptureCursorForPlanner(config) {
+    if (!config.captureCursor)
+        return '';
+    return [
+        `page=${config.captureCursor.pageId}`,
+        `target=${config.captureCursor.targetId}`,
+        `phase=${config.captureCursor.phase}`,
+        `resume=${config.captureCursor.resumeFromActionIndex}`,
+        config.captureCursor.lastVerifiedCheckpointId
+            ? `checkpoint=${config.captureCursor.lastVerifiedCheckpointId}`
+            : '',
+    ].filter(Boolean).join('; ');
+}
+function summarizeRepairTicketForPlanner(config) {
+    if (!config.activeRepairTicket)
+        return '';
+    const ticket = config.activeRepairTicket;
+    return [
+        `ticket=${ticket.id}`,
+        `cause=${ticket.cause}`,
+        `status=${ticket.status}`,
+        `summary=${ticket.summary}`,
+        ticket.expectedState.lang ? `lang=${ticket.expectedState.lang}` : '',
+        ticket.expectedState.theme ? `theme=${ticket.expectedState.theme}` : '',
+        ticket.expectedState.authState ? `auth=${ticket.expectedState.authState}` : '',
+        ticket.expectedState.url ? `url=${ticket.expectedState.url}` : '',
+        ticket.expectedState.pageId ? `page=${ticket.expectedState.pageId}` : '',
+    ].filter(Boolean).join('; ');
+}
+function findDuplicateVariantCapture(manifest, fingerprint) {
+    if (!manifest?.currentPageId)
+        return null;
+    const duplicate = manifest.previousValidatedCaptures.find((capture) => capture.pageId !== manifest.currentPageId
+        && capture.fingerprint
+        && capture.fingerprint === fingerprint);
+    return duplicate?.pageId ?? null;
+}
+const PRESET_EDITOR_RE = /\b(edit[_ -]?preset|preset[_ -]editor|preset[_ -]edit|preset[_ -]form)\b/i;
+const PRESET_CONTEXT_RE = /\bpreset\b/i;
+const CONFIGURATION_RE = /\b(edit|editor|config|configuration|configure|settings|modify|modifier|form)\b/i;
+const EDITOR_PROMPT_RE = /\b(additional instructions|instructions suppl[eé]mentaires|continue with ai|continuer avec l['’]ia)\b/i;
+const DIALOG_TARGET_RE = /\b(modal|dialog|drawer|popup)\b/i;
+const GALLERY_ROUTE_RE = /\/(gallery|captures?|screenshots?)\b/i;
+const SETTINGS_ROUTE_RE = /\/settings\b/i;
+const GALLERY_SURFACE_RE = /\b(gallery|galerie|captures?|screenshots?|thumbnail|thumbnails|miniatures?)\b/i;
+const GALLERY_DETAIL_PROMPT_RE = /\b(first (?:image|screenshot|result|card)|open the first|click on the first|after clicking|individual screenshots?|detail view|detailed view|subsequent page|premier resultat|premier résultat|captures individuelles?)\b/i;
+const GALLERY_OVERVIEW_CONTROL_RE = /\b(filter by preset|filtrer par preset|rechercher|search|filter|preset)\b/i;
+const GALLERY_GROUP_CARD_RE = /\b(download all|tout telecharger|tout télécharger|\d+\s*(?:screenshots?|captures?(?: d['’]ecran| d’écran)?))\b/i;
+const SETTINGS_SURFACE_RE = /\b(settings|param[eè]tres|project name|team members|billing|workspace settings|general settings)\b/i;
+const TEMPLATE_GALLERY_MARKERS = [
+    'new preset',
+    'nouveau preset',
+    'search templates',
+    'rechercher des templates',
+    'start from scratch',
+    'partir de zéro',
+    'homepage hero',
+    'pricing page',
+    'mobile responsive',
+    'dark mode showcase',
+    'multi-language',
+    'feature showcase',
+    'marketing',
+    'responsive',
+    'video',
+];
+const MODAL_GENERIC_SUBJECT_TOKENS = new Set([
+    'modal',
+    'dialog',
+    'drawer',
+    'popup',
+    'overlay',
+    'preset',
+    'presets',
+    'template',
+    'templates',
+    'selection',
+    'select',
+    'choose',
+    'details',
+    'detail',
+    'configuration',
+    'config',
+    'gallery',
+    'captures',
+    'screenshots',
+    'settings',
+    'editor',
+]);
+const MODAL_CONFIGURATION_SURFACE_RE = /\b(additional instructions|instructions supplementaires|continue with ai|continuer avec (?:l )?ia|ai prompt|prompt ia)\b/i;
+function normalizeEvidenceText(value) {
+    return value
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, ' ')
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim();
+}
+function tokenizeEvidenceText(value) {
+    return normalizeEvidenceText(value)
+        .split(/\s+/g)
+        .map(part => part.trim())
+        .filter(part => part.length >= 3);
+}
+function countDialogSubjectTokenMatches(params) {
+    const strongTokens = params.subjectTokens.filter(token => token.length >= 4 && !MODAL_GENERIC_SUBJECT_TOKENS.has(token));
+    if (strongTokens.length === 0)
+        return 0;
+    const evidenceTokens = new Set(tokenizeEvidenceText(`${params.visibleText} ${params.currentUrl}`));
+    return strongTokens.filter(token => evidenceTokens.has(normalizeEvidenceText(token))).length;
+}
+function hasExpectedDialogSurface(params) {
+    const normalizedVisibleText = normalizeEvidenceText(params.visibleText);
+    const selectionSurfaceScore = TEMPLATE_GALLERY_MARKERS.filter(marker => normalizedVisibleText.includes(normalizeEvidenceText(marker))).length
+        + (/\b(template|templates|modele|modeles|picker|selection)\b/i.test(normalizedVisibleText) ? 1 : 0);
+    const configurationSurfaceScore = selectionSurfaceScore
+        + (MODAL_CONFIGURATION_SURFACE_RE.test(normalizedVisibleText) ? 2 : 0);
+    const subjectTokenMatches = countDialogSubjectTokenMatches({
+        subjectTokens: params.identity.subjectTokens,
+        visibleText: params.visibleText,
+        currentUrl: params.currentUrl,
+    });
+    if (params.identity.kind === 'modal_selection') {
+        return selectionSurfaceScore > 0 || subjectTokenMatches > 0;
+    }
+    if (params.identity.kind === 'modal_configuration') {
+        return configurationSurfaceScore > 0 || subjectTokenMatches > 0;
+    }
+    return true;
+}
+function inferGallerySubstateFailure(params) {
+    if (!GALLERY_DETAIL_PROMPT_RE.test(params.context)) {
+        return null;
+    }
+    const normalizedVisibleText = normalizeEvidenceText(params.visibleText);
+    const stillShowsOverviewControls = GALLERY_OVERVIEW_CONTROL_RE.test(normalizedVisibleText);
+    const stillShowsGroupedCollections = GALLERY_GROUP_CARD_RE.test(normalizedVisibleText);
+    if (stillShowsOverviewControls && stillShowsGroupedCollections) {
+        return 'Expected the opened gallery result/details view, but the gallery overview/filter controls are still visible.';
+    }
+    return null;
+}
+export function inferVariantIdentityFailure(params) {
+    const pageId = (params.pageId || '').toLowerCase();
+    const prompt = params.prompt.toLowerCase();
+    const context = `${pageId} ${prompt}`;
+    const visibleText = params.visibleText.toLowerCase();
+    const identity = params.pageIdentity ?? null;
+    const galleryMarkerCount = TEMPLATE_GALLERY_MARKERS.filter((marker) => visibleText.includes(marker)).length;
+    const hasMultipleKnownTemplates = ['homepage hero', 'pricing page', 'mobile responsive', 'dark mode showcase', 'multi-language', 'feature showcase']
+        .filter((marker) => visibleText.includes(marker))
+        .length >= 2;
+    const looksLikeTemplateGallery = galleryMarkerCount >= 3
+        || (visibleText.includes('new preset') && hasMultipleKnownTemplates)
+        || (visibleText.includes('nouveau preset') && hasMultipleKnownTemplates);
+    const expectsPresetEditor = identity?.dedicatedRoute
+        || identity?.kind === 'editor_route'
+        || (!identity
+            && (PRESET_EDITOR_RE.test(context)
+                || (PRESET_CONTEXT_RE.test(context) && CONFIGURATION_RE.test(context))
+                || (EDITOR_PROMPT_RE.test(context) && !DIALOG_TARGET_RE.test(context))));
+    const expectsDialogTarget = identity?.dialogTarget ?? false;
+    const expectsGalleryTarget = identity?.kind === 'gallery';
+    const onPresetEditorRoute = /\/projects\/[^/]+\/presets\/[^/?#]+/i.test(params.currentUrl) || /\/presets\/[^/?#]+/i.test(params.currentUrl);
+    const onGalleryRoute = GALLERY_ROUTE_RE.test(params.currentUrl);
+    const onSettingsRoute = SETTINGS_ROUTE_RE.test(params.currentUrl);
+    const gallerySurfaceScore = TEMPLATE_GALLERY_MARKERS
+        .filter((marker) => marker === 'new preset' || marker === 'nouveau preset')
+        .reduce((score, marker) => score + (visibleText.includes(marker) ? 1 : 0), 0)
+        + (GALLERY_SURFACE_RE.test(visibleText) ? 2 : 0);
+    const settingsSurfaceScore = SETTINGS_SURFACE_RE.test(visibleText) ? 2 : 0;
+    if (expectsDialogTarget) {
+        if (params.dialogCount === 0) {
+            return 'Expected a dialog/modal capture target, but no dialog is currently open.';
+        }
+        if (identity && !hasExpectedDialogSurface({
+            identity,
+            visibleText,
+            currentUrl: params.currentUrl,
+        })) {
+            return identity.kind === 'modal_configuration'
+                ? 'Expected the configured modal state, but the current dialog content does not match the requested template/details view.'
+                : 'Expected the template picker modal, but the current dialog content does not match the requested selection state.';
+        }
+        return null;
+    }
+    if (expectsGalleryTarget) {
+        const expectsDetailView = GALLERY_DETAIL_PROMPT_RE.test(context);
+        if (!expectsDetailView && params.dialogCount > 0) {
+            return 'Expected the gallery overview, but a dialog/modal is still open on top of the page.';
+        }
+        if (onSettingsRoute || (settingsSurfaceScore > 0 && !onGalleryRoute && gallerySurfaceScore === 0)) {
+            return 'Expected the gallery overview, but the page still looks like settings or another non-gallery section.';
+        }
+        const gallerySubstateFailure = inferGallerySubstateFailure({ context, visibleText });
+        if (gallerySubstateFailure)
+            return gallerySubstateFailure;
+        return null;
+    }
+    if (!expectsPresetEditor)
+        return null;
+    if (looksLikeTemplateGallery) {
+        return 'Expected the preset editor page, but the template gallery/sidebar is still visible.';
+    }
+    if (params.dialogCount > 0) {
+        return 'Expected the preset editor page, but a dialog/modal is still open on top of the page.';
+    }
+    if (PRESET_CONTEXT_RE.test(context) && !onPresetEditorRoute) {
+        return 'Expected the preset editor page, but the browser is not on a preset editor route.';
+    }
+    return null;
+}
+// OAuth guard: block clicks on OAuth elements when credentials are provided
+const OAUTH_TEXT_RE = /\b(google|apple|microsoft|github|facebook|twitter|linkedin|sso)\b/i;
+const OAUTH_HREF_RE = /google\.com|apple\.com|microsoft\.com|github\.com|facebook\.com|twitter\.com|linkedin\.com|auth0\.com|oauth/i;
+const HIDDEN_PASSWORD_GIVE_UP_RE = /\b(password (is )?missing|missing password|mot de passe manquant|password unavailable|no password provided)\b/i;
+const GENERIC_PASSWORD_INPUT_RE = /^(password|your password|motdepasse|mot de passe|password123|secret)$/i;
+function isOAuthElement(el) {
+    return OAUTH_TEXT_RE.test(el.text) || OAUTH_TEXT_RE.test(el.ariaLabel || '') || OAUTH_HREF_RE.test(el.href || '');
+}
+function isPasswordFieldTarget(args, interactiveElements) {
+    const byIndex = args.index !== undefined
+        ? interactiveElements.find((el) => el.index === args.index)
+        : null;
+    const bySelector = !byIndex && typeof args.selector === 'string'
+        ? interactiveElements.find((el) => el.selector === args.selector)
+        : null;
+    const target = byIndex ?? bySelector;
+    if (!target)
+        return false;
+    const haystack = `${target.inputType || ''} ${target.text || ''} ${target.ariaLabel || ''} ${target.selector}`.toLowerCase();
+    return target.inputType === 'password' || /\b(password|mot de passe|passcode)\b/i.test(haystack);
+}
+function createClient(apiKey) {
+    return new OpenAI({
+        baseURL: 'https://openrouter.ai/api/v1',
+        apiKey,
+        defaultHeaders: {
+            'HTTP-Referer': 'https://github.com/screenshot-agent',
+            'X-Title': 'Screenshot Agent',
+        },
+    });
+}
+/** Check if a model is a Grok model (xAI). These models have broken streaming tool calls via OpenRouter. */
+function isGrokModel(model) {
+    const normalized = model.toLowerCase();
+    return normalized.includes('grok') || normalized.startsWith('x-ai/');
+}
+/** Check if a model supports OpenRouter's reasoning/thinking parameter. */
+function supportsReasoning(model) {
+    return isGrokModel(model);
+}
+/** Build the reasoning body fragment for OpenRouter requests. */
+function reasoningBody(model, effort) {
+    if (!effort || effort === 'off')
+        return {};
+    if (!supportsReasoning(model))
+        return {};
+    return { reasoning: { effort } };
+}
+/** Spread into OpenRouter request bodies to inject provider routing preferences for a given model. */
+function providerBody(model, prefsMap) {
+    const prefs = prefsMap?.[model];
+    // Enforce Zero Data Retention on all requests (GDPR compliance)
+    return { provider: { ...prefs, zdr: true } };
+}
+let _reasoningMessageCounter = 0;
+/**
+ * Parse tool calls from XML content emitted by models that don't support native tool_calls
+ * streaming (e.g., MiniMax M2.5 via OpenRouter). Supports two formats:
+ * - <minimax:tool_call><invoke name="X"><parameter name="Y">Z</parameter></invoke></minimax:tool_call>
+ * - <tool_code>function_name\n{"arg": "value"}</tool_code>
+ */
+function parseXmlToolCalls(content, completionId) {
+    const results = [];
+    // Format 1: <minimax:tool_call><invoke name="..."><parameter name="...">...</parameter></invoke></minimax:tool_call>
+    const minimaxRe = /<minimax:tool_call>([\s\S]*?)<\/minimax:tool_call>/gi;
+    for (const match of content.matchAll(minimaxRe)) {
+        const block = match[1];
+        const invokeRe = /<invoke\s+name="([^"]+)">([\s\S]*?)<\/invoke>/gi;
+        for (const invokeMatch of block.matchAll(invokeRe)) {
+            const name = invokeMatch[1];
+            const paramsBlock = invokeMatch[2];
+            const args = {};
+            const paramRe = /<parameter\s+name="([^"]+)">([\s\S]*?)<\/parameter>/gi;
+            for (const paramMatch of paramsBlock.matchAll(paramRe)) {
+                args[paramMatch[1]] = paramMatch[2].trim();
+            }
+            results.push({
+                id: `xml-${completionId || Date.now()}-${results.length}`,
+                type: 'function',
+                function: { name, arguments: JSON.stringify(args) },
+            });
+        }
+    }
+    // Format 2: <tool_code>function_name\n{"arg": "value"}</tool_code>
+    if (results.length === 0) {
+        const toolCodeRe = /<tool_code>([\s\S]*?)<\/tool_code>/gi;
+        for (const match of content.matchAll(toolCodeRe)) {
+            const inner = match[1].trim();
+            const newlineIdx = inner.indexOf('\n');
+            if (newlineIdx > 0) {
+                const name = inner.slice(0, newlineIdx).trim();
+                const argsStr = inner.slice(newlineIdx + 1).trim();
+                results.push({
+                    id: `xml-${completionId || Date.now()}-${results.length}`,
+                    type: 'function',
+                    function: { name, arguments: argsStr },
+                });
+            }
+        }
+    }
+    return results;
+}
+async function callWithRetry(client, params, maxRetries = 3, signal, providerPreferences, reasoningEffort) {
+    // Grok models have broken streaming tool calls via OpenRouter — the provider
+    // silently drops tool_calls from SSE deltas, resulting in 0 tool calls received
+    // despite the model producing them. Use non-streaming for these models.
+    const useStreaming = !isGrokModel(params.model);
+    let messagesToUse = params.messages;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        throwIfAborted(signal, 'Agent run cancelled.');
+        try {
+            let content = '';
+            let toolCalls = [];
+            let finishReason = null;
+            let completionId = '';
+            let model = params.model;
+            let chunkCount = 0;
+            const usageData = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
+            if (useStreaming) {
+                // Streaming path for most models
+                const stream = await client.chat.completions.create({ ...params, messages: messagesToUse, stream: true, ...providerBody(params.model, providerPreferences), ...reasoningBody(params.model, reasoningEffort) }, { signal });
+                const toolCallBuffers = new Map();
+                const messageId = `reasoning-${++_reasoningMessageCounter}`;
+                for await (const chunk of stream) {
+                    chunkCount++;
+                    if (chunk.id)
+                        completionId = chunk.id;
+                    if (chunk.model)
+                        model = chunk.model;
+                    if (chunk.usage) {
+                        usageData.prompt_tokens = chunk.usage.prompt_tokens ?? 0;
+                        usageData.completion_tokens = chunk.usage.completion_tokens ?? 0;
+                        usageData.total_tokens = chunk.usage.total_tokens ?? 0;
+                    }
+                    const delta = chunk.choices?.[0]?.delta;
+                    if (!delta)
+                        continue;
+                    if (chunk.choices[0].finish_reason) {
+                        finishReason = chunk.choices[0].finish_reason;
+                    }
+                    if (delta.content) {
+                        content += delta.content;
+                        emitReasoningDelta(delta.content, messageId);
+                    }
+                    if (delta.tool_calls) {
+                        for (const tc of delta.tool_calls) {
+                            const existing = toolCallBuffers.get(tc.index);
+                            if (existing) {
+                                if (tc.function?.name)
+                                    existing.name = tc.function.name;
+                                if (tc.id)
+                                    existing.id = tc.id;
+                                if (tc.function?.arguments)
+                                    existing.arguments += tc.function.arguments;
+                            }
+                            else {
+                                toolCallBuffers.set(tc.index, {
+                                    id: tc.id || `tc-${completionId || `gen-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`}-${tc.index}`,
+                                    name: tc.function?.name || '',
+                                    arguments: tc.function?.arguments || '',
+                                });
+                            }
+                        }
+                    }
+                }
+                toolCalls = Array.from(toolCallBuffers.entries())
+                    .sort(([a], [b]) => a - b)
+                    .filter(([, tc]) => tc.name.trim().length > 0)
+                    .map(([, tc]) => ({
+                    id: tc.id,
+                    type: 'function',
+                    function: { name: tc.name, arguments: tc.arguments },
+                }));
+            }
+            else {
+                // Non-streaming path for models with broken streaming (e.g. Grok via OpenRouter)
+                const nonStreamStart = Date.now();
+                logger.info('Réflexion en cours…');
+                const response = await client.chat.completions.create({ ...params, messages: messagesToUse, stream: false, ...providerBody(params.model, providerPreferences), ...reasoningBody(params.model, reasoningEffort) }, { signal });
+                logger.debug(`LLM response received in ${Date.now() - nonStreamStart}ms (model: ${params.model})`);
+                completionId = response.id ?? '';
+                model = response.model ?? params.model;
+                finishReason = response.choices?.[0]?.finish_reason ?? null;
+                content = response.choices?.[0]?.message?.content ?? '';
+                if (response.usage) {
+                    usageData.prompt_tokens = response.usage.prompt_tokens ?? 0;
+                    usageData.completion_tokens = response.usage.completion_tokens ?? 0;
+                    usageData.total_tokens = response.usage.total_tokens ?? 0;
+                }
+                if (response.choices?.[0]?.message?.tool_calls) {
+                    toolCalls = response.choices[0].message.tool_calls
+                        .filter((tc) => tc.type === 'function' && 'function' in tc)
+                        .map((tc) => ({
+                        id: tc.id,
+                        type: 'function',
+                        function: { name: tc.function.name, arguments: tc.function.arguments },
+                    }));
+                }
+                chunkCount = 1;
+            }
+            // Some models (e.g., MiniMax M2.5) return tool calls as XML in the content
+            // field instead of using the native tool_calls streaming delta. Parse them.
+            if (toolCalls.length === 0 && content) {
+                const xmlParsed = parseXmlToolCalls(content, completionId);
+                if (xmlParsed.length > 0) {
+                    toolCalls.push(...xmlParsed);
+                    content = '';
+                    logger.debug(`Parsed ${xmlParsed.length} tool call(s) from XML content (model: ${model})`);
+                }
+            }
+            // If the model returned no tool calls, log diagnostics and retry with coercion.
+            const hasSubstantiveContent = content ? /[a-zA-Z]{3,}/.test(content) : false;
+            if (toolCalls.length === 0 && attempt < maxRetries && (hasSubstantiveContent || !content)) {
+                logger.info(`Model ${model} returned no usable tool calls (attempt ${attempt}/${maxRetries}). `
+                    + `Diagnostics: chunks=${chunkCount}, finish_reason=${finishReason}, `
+                    + `content_length=${content.length}, `
+                    + `usage=${JSON.stringify(usageData)}, content_preview=${JSON.stringify(content.slice(0, 500) || '(empty)')}`);
+                if (content) {
+                    messagesToUse = [
+                        ...params.messages,
+                        { role: 'assistant', content },
+                        {
+                            role: 'user',
+                            content: 'You must call one of the available tools. Do not respond with text — select the most appropriate tool and call it now.',
+                        },
+                    ];
+                }
+                else {
+                    messagesToUse = [
+                        ...params.messages,
+                        {
+                            role: 'user',
+                            content: 'You must call one of the available tools. Do not respond with text — select the most appropriate tool and call it now.',
+                        },
+                    ];
+                }
+                continue;
+            }
+            if (toolCalls.length === 0 && content && !hasSubstantiveContent) {
+                logger.info(`Model ${model} returned non-substantive content (${content.length} chars), skipping coercion retry. Preview: ${JSON.stringify(content.slice(0, 200))}`);
+            }
+            const result = {
+                id: completionId,
+                object: 'chat.completion',
+                created: Math.floor(Date.now() / 1000),
+                model,
+                choices: [{
+                        index: 0,
+                        message: {
+                            role: 'assistant',
+                            content: toolCalls.length > 0 ? null : (content || null),
+                            tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
+                            refusal: null,
+                        },
+                        finish_reason: (finishReason || 'stop'),
+                        logprobs: null,
+                    }],
+                usage: usageData,
+            };
+            return result;
+        }
+        catch (err) {
+            if (isAbortError(err)) {
+                throw err;
+            }
+            const error = err;
+            if (error.status === 429 && attempt < maxRetries) {
+                const delay = Math.pow(2, attempt) * 1000;
+                logger.info(`Rate limited, retrying in ${delay}ms...`);
+                await sleepWithAbort(delay, signal);
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw new Error('Max retries exceeded');
+}
+async function callTextOnlyWithRetry(client, params, maxRetries = 3, signal) {
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        throwIfAborted(signal, 'Agent run cancelled.');
+        try {
+            return await client.chat.completions.create({ ...params, stream: false }, { signal });
+        }
+        catch (err) {
+            if (isAbortError(err)) {
+                throw err;
+            }
+            const error = err;
+            if (error.status === 429 && attempt < maxRetries) {
+                const delay = Math.pow(2, attempt) * 1000;
+                logger.info(`Rate limited, retrying in ${delay}ms...`);
+                await sleepWithAbort(delay, signal);
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw new Error('Max retries exceeded');
+}
+function extractUsage(response, stepNumber, stepType, modelRequested, imagesInPrompt) {
+    return extractStepUsage(response, {
+        stepNumber,
+        stepType,
+        modelRequested,
+        imagesInPrompt,
+    });
+}
+function mergeUsage(primary, secondary) {
+    if (!primary)
+        return secondary;
+    if (!secondary)
+        return primary;
+    return {
+        ...secondary,
+        stepNumber: primary.stepNumber,
+        stepType: primary.stepType,
+        modelRequested: primary.modelRequested,
+        imagesInPrompt: Math.max(primary.imagesInPrompt, secondary.imagesInPrompt),
+        promptTokens: (primary.promptTokens ?? 0) + (secondary.promptTokens ?? 0),
+        completionTokens: (primary.completionTokens ?? 0) + (secondary.completionTokens ?? 0),
+        totalTokens: (primary.totalTokens ?? 0) + (secondary.totalTokens ?? 0),
+        cacheReadTokens: (primary.cacheReadTokens ?? 0) + (secondary.cacheReadTokens ?? 0),
+        cacheWriteTokens: (primary.cacheWriteTokens ?? 0) + (secondary.cacheWriteTokens ?? 0),
+    };
+}
+function extractAssistantText(content) {
+    if (typeof content === 'string')
+        return content.trim();
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .map((part) => {
+        if (typeof part === 'string')
+            return part;
+        return typeof part.text === 'string' ? part.text : '';
+    })
+        .join('\n')
+        .trim();
+}
+export function inferDeterministicReadyDecision(params) {
+    const parsedAssessment = parseVerificationDecisionText(params.assessment);
+    const pageLooksStable = params.observation.readyState !== 'loading';
+    const hasBlockingDialog = params.observation.dialogCount > 0;
+    const hasLoadingIndicators = params.observation.loadingIndicatorCount > 0;
+    const onExpectedOrigin = urlsRoughlyMatch(params.targetUrl, params.observation.url)
+        || urlsRoughlyMatch(params.observation.url, params.targetUrl);
+    // Dialog presence is no longer a hard rejection — the LLM sees the screenshot
+    // and can judge whether the dialog is the intended capture target or an obstruction.
+    if (hasLoadingIndicators) {
+        return { verified: false, reason: `Loading indicators still visible (${params.observation.loadingIndicatorCount}).` };
+    }
+    if (parsedAssessment?.verified && pageLooksStable && onExpectedOrigin && params.allowSuccess !== false) {
+        return { verified: true };
+    }
+    return null;
+}
+function hasHardVariantMismatch(config, bundle) {
+    if (config.currentLang) {
+        const languageState = evaluateRequestedLanguageState({
+            currentUrl: bundle.url,
+            requestedLang: config.currentLang,
+            signals: bundle.pageSignals,
+        });
+        if (!languageState.active && !languageState.ambiguous && languageState.confidence === 'high') {
+            return true;
+        }
+    }
+    if (config.currentTheme) {
+        const themeState = evaluateRequestedThemeState({
+            requestedTheme: config.currentTheme,
+            signals: bundle.pageSignals,
+        });
+        if (!themeState.active && !themeState.ambiguous && themeState.confidence === 'high') {
+            return true;
+        }
+    }
+    return false;
+}
+export function inferManifestReadyDecision(params) {
+    const manifest = params.config.variantManifest;
+    const identity = manifest?.currentPageIdentity;
+    if (!manifest?.currentPageId || !identity)
+        return null;
+    if (!(identity.dialogTarget || identity.kind === 'gallery'))
+        return null;
+    const parsedAssessment = parseVerificationDecisionText(params.assessment);
+    if (!parsedAssessment?.verified)
+        return null;
+    const pageLooksStable = params.observation.readyState !== 'loading'
+        && params.observation.loadingIndicatorCount === 0;
+    const onExpectedOrigin = urlsRoughlyMatch(params.config.url, params.bundle.url)
+        || urlsRoughlyMatch(params.bundle.url, params.config.url);
+    if (!pageLooksStable || !onExpectedOrigin || hasHardVariantMismatch(params.config, params.bundle)) {
+        return null;
+    }
+    if (identity.dialogTarget) {
+        const visibleText = [
+            params.bundle.pageSignals.title,
+            params.bundle.pageSignals.headings.join(' '),
+            params.bundle.pageSignals.navLabels.join(' '),
+            params.bundle.pageSignals.visibleText,
+        ].filter(Boolean).join(' ');
+        const strongSubjectTokens = identity.subjectTokens.filter(token => token.length >= 4 && !MODAL_GENERIC_SUBJECT_TOKENS.has(token));
+        const subjectTokenMatches = countDialogSubjectTokenMatches({
+            subjectTokens: identity.subjectTokens,
+            visibleText,
+            currentUrl: params.bundle.url,
+        });
+        const dialogSurfaceMatches = hasExpectedDialogSurface({
+            identity,
+            visibleText,
+            currentUrl: params.bundle.url,
+        });
+        if (!dialogSurfaceMatches || (strongSubjectTokens.length > 0 && subjectTokenMatches === 0)) {
+            return {
+                verified: false,
+                reason: identity.kind === 'modal_configuration'
+                    ? 'Expected the configured modal state, but the open dialog does not match the requested content.'
+                    : 'Expected the requested dialog/modal target, but the open dialog content does not match it.',
+            };
+        }
+    }
+    return { verified: true };
+}
+/**
+ * Page-signal deterministic verification: accepts when ALL of the following hold:
+ *  1. Assessment text parses as positive (caller already believes ready)
+ *  2. inferVariantIdentityFailure finds no identity mismatch
+ *  3. No loading indicators, readyState === 'complete'
+ *  4. No hard variant (lang/theme) mismatch
+ *  5. No unexpected dialog blocking the page (unless dialog is the target)
+ *
+ * Returns { verified: true } when confident, null when inconclusive (→ LLM).
+ * NEVER returns { verified: false } — absence of evidence is not evidence of absence.
+ */
+export function inferPageSignalReadyDecision(params) {
+    // Require a positive assessment from the caller
+    const parsedAssessment = parseVerificationDecisionText(params.assessment);
+    if (!parsedAssessment?.verified)
+        return null;
+    // Require page stability — no loading or transitional state
+    if (params.observation.readyState !== 'complete')
+        return null;
+    if (params.observation.loadingIndicatorCount > 0)
+        return null;
+    // Require URL origin match
+    if (!urlsRoughlyMatch(params.config.url, params.bundle.url)
+        && !urlsRoughlyMatch(params.bundle.url, params.config.url)) {
+        return null;
+    }
+    // Reject if hard variant mismatch (wrong lang or theme with high confidence)
+    if (hasHardVariantMismatch(params.config, params.bundle))
+        return null;
+    // Require no identity failure — if inferVariantIdentityFailure flagged something,
+    // we cannot accept deterministically (the page content doesn't match expectations)
+    if (params.identityFailure)
+        return null;
+    // Reject if an unexpected dialog is open (unless the target IS a dialog)
+    const expectsDialog = params.config.variantManifest?.currentPageIdentity?.dialogTarget;
+    if (params.observation.dialogCount > 0 && !expectsDialog)
+        return null;
+    return { verified: true };
+}
+function summarizeVerificationDiagnostics(config, bundle) {
+    const result = {};
+    if (config.currentLang) {
+        const languageState = evaluateRequestedLanguageState({
+            currentUrl: bundle.url,
+            requestedLang: config.currentLang,
+            signals: bundle.pageSignals,
+        });
+        const status = languageState.active
+            ? 'match'
+            : languageState.ambiguous
+                ? 'ambiguous'
+                : 'mismatch';
+        result.lang = `${status}/${languageState.confidence}: ${languageState.reasons.join('; ') || 'no_language_signal'}`;
+    }
+    if (config.currentTheme) {
+        const themeState = evaluateRequestedThemeState({
+            requestedTheme: config.currentTheme,
+            signals: bundle.pageSignals,
+        });
+        const status = themeState.active
+            ? 'match'
+            : themeState.ambiguous
+                ? 'ambiguous'
+                : 'mismatch';
+        result.theme = `${status}/${themeState.confidence}: ${themeState.reasons.join('; ') || 'no_theme_signal'}`;
+    }
+    return result;
+}
+function buildLanguagePreflightVerificationFailureReason(params) {
+    const requestedLang = params.requestedLang?.trim().toLowerCase();
+    const requestedTheme = params.requestedTheme;
+    if ((!requestedLang && !requestedTheme) || !params.signals) {
+        return 'Language preflight failed: unable to confirm the requested fixed UI variant.';
+    }
+    const failures = [];
+    if (requestedLang) {
+        const languageState = evaluateRequestedLanguageState({
+            currentUrl: params.currentUrl,
+            requestedLang,
+            signals: params.signals,
+        });
+        if (!languageState.active || languageState.ambiguous) {
+            if (languageState.reasons.length > 0) {
+                failures.push(`requested "${requestedLang}", detected "${languageState.detected ?? 'unknown'}" (${languageState.reasons.join('; ')})`);
+            }
+            else {
+                failures.push(`requested "${requestedLang}", but the fixed app UI is still not confirmed in that language`);
+            }
+        }
+    }
+    if (requestedTheme) {
+        const themeState = evaluateRequestedThemeState({
+            requestedTheme,
+            signals: params.signals,
+        });
+        if (!themeState.active || themeState.ambiguous) {
+            if (themeState.reasons.length > 0) {
+                failures.push(`theme requested "${requestedTheme}", detected "${themeState.detected ?? 'unknown'}" (${themeState.reasons.join('; ')})`);
+            }
+            else {
+                failures.push(`theme "${requestedTheme}" is still not confirmed`);
+            }
+        }
+    }
+    if (failures.length === 0) {
+        return '';
+    }
+    return `Language preflight failed: ${failures.join(' | ')}.`;
+}
+function isTechnicalVerificationFailureReason(reason) {
+    if (!reason)
+        return false;
+    return /\b(timeout|timed out|parser|transport|stale verification snapshot|captureverificationbundle|invalid json|json parse|response format|temporary|network error|connection reset|econnreset|service unavailable)\b/i.test(reason);
+}
+const ACTION_OBSERVATION_TIMEOUT_MS = 2500;
+const VERIFICATION_SCREENSHOT_TIMEOUT_MS = 5000;
+const VERIFICATION_BUNDLE_TIMEOUT_MS = 8000;
+const ACTION_DIAGNOSTIC_WAIT_MS = 200;
+class AgentStepTimeoutError extends Error {
+    timeoutMs;
+    stepLabel;
+    constructor(stepLabel, timeoutMs) {
+        super(`Timed out after ${timeoutMs}ms while ${stepLabel}.`);
+        this.name = 'AgentStepTimeoutError';
+        this.stepLabel = stepLabel;
+        this.timeoutMs = timeoutMs;
+    }
+}
+function isAgentStepTimeoutError(error) {
+    return error instanceof AgentStepTimeoutError;
+}
+async function withAgentStepTimeout(work, params) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new AgentStepTimeoutError(params.stepLabel, params.timeoutMs));
+        }, params.timeoutMs);
+        void work()
+            .then((result) => {
+            clearTimeout(timer);
+            resolve(result);
+        })
+            .catch((error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+async function withOptionalAgentStepTimeout(work, params) {
+    try {
+        return await withAgentStepTimeout(work, params);
+    }
+    catch (error) {
+        if (isAgentStepTimeoutError(error)) {
+            throw error;
+        }
+        return null;
+    }
+}
+function getActionExecutionTimeoutMs(action, args) {
+    switch (action) {
+        case 'navigate_to':
+            return 25000;
+        case 'click':
+        case 'safe_expand':
+        case 'select_option':
+            return 5000;
+        case 'type_text':
+        case 'press_key':
+        case 'scroll':
+        case 'scroll_to_element':
+        case 'resize_viewport':
+        case 'dismiss_overlays':
+        case 'hover':
+            return 3500;
+        case 'wait':
+            return Math.min(6000, Math.max(1000, Number(args.milliseconds ?? 1000) + 1000));
+        default:
+            return 3500;
+    }
+}
+function buildActionTimeoutMessage(stage, action, timeoutMs) {
+    return `Action timeout during ${stage} (${action}, ${timeoutMs}ms)`;
+}
+function buildVerificationTimeoutMessage(stage, timeoutMs) {
+    return `Verification timeout during ${stage} (${timeoutMs}ms).`;
+}
+function logActionProgress(action, stage) {
+    logger.debug(`Action progress: ${action} -> ${stage}`);
+}
+function getDiagnosticRecoveryFailureMessage(stage, action, timeoutMs, options = {}) {
+    const prefix = buildActionTimeoutMessage(stage, action, timeoutMs);
+    if (options.recoveryError) {
+        return `${prefix}; ${options.recoveryError}`;
+    }
+    if (stage === 'browser execution') {
+        return `${prefix}; state may be partially changed.`;
+    }
+    if (options.afterChanged) {
+        return `${prefix}; diagnostic recovery could not confirm a stable post-action state.`;
+    }
+    return `${prefix}; no reliable state change detected.`;
+}
+async function performActionDiagnosticRecovery(browser, action, before) {
+    logActionProgress(action, 'diagnostic recovery');
+    try {
+        await withAgentStepTimeout(() => browser.dismissOverlays(), {
+            stepLabel: `${action} diagnostic dismissOverlays`,
+            timeoutMs: getActionExecutionTimeoutMs('dismiss_overlays', {}),
+        });
+        await withAgentStepTimeout(() => browser.wait(ACTION_DIAGNOSTIC_WAIT_MS), {
+            stepLabel: `${action} diagnostic wait`,
+            timeoutMs: getActionExecutionTimeoutMs('wait', { milliseconds: ACTION_DIAGNOSTIC_WAIT_MS }),
+        });
+        const after = await withAgentStepTimeout(() => browser.captureObservation(), {
+            stepLabel: `${action} diagnostic captureObservation`,
+            timeoutMs: ACTION_OBSERVATION_TIMEOUT_MS,
+        });
+        if (!before) {
+            return {
+                reaction: null,
+                error: 'baseline observation was unavailable, so diagnostic recovery could not compare page state.',
+            };
+        }
+        return {
+            reaction: describeObservationChange(before, after),
+        };
+    }
+    catch (error) {
+        if (isAgentStepTimeoutError(error)) {
+            return {
+                reaction: null,
+                error: `${buildActionTimeoutMessage('diagnostic recovery', action, error.timeoutMs)}.`,
+            };
+        }
+        return {
+            reaction: null,
+            error: `diagnostic recovery failed: ${error.message}`,
+        };
+    }
+}
+async function deterministicReadyObservationCheck(params) {
+    logger.debug('Verification progress: captureObservation');
+    try {
+        const observation = await withAgentStepTimeout(() => params.browser.captureObservation(), {
+            stepLabel: 'verification captureObservation',
+            timeoutMs: ACTION_OBSERVATION_TIMEOUT_MS,
+        });
+        return inferDeterministicReadyDecision({
+            observation,
+            assessment: params.assessment,
+            targetUrl: params.config.url,
+            skipDialogCheck: params.skipDialogCheck,
+            allowSuccess: params.allowSuccess,
+        });
+    }
+    catch (error) {
+        if (isAgentStepTimeoutError(error)) {
+            return {
+                verified: false,
+                reason: buildVerificationTimeoutMessage('captureObservation', error.timeoutMs),
+            };
+        }
+        return null;
+    }
+}
+/**
+ * Fast-path optimization: extract a PASS/FAIL verdict from LLM text output
+ * using keyword matching, avoiding a separate LLM call when the signal is clear.
+ *
+ * Returns null when uncertain — the caller MUST fall back to an LLM vision call.
+ * Do not add more patterns here; expand LLM fallback coverage instead.
+ */
+export function parseVerificationDecisionText(content) {
+    const normalized = content.replace(/\s+/g, ' ').trim();
+    if (!normalized)
+        return null;
+    const upper = normalized.toUpperCase();
+    if (upper === 'PASS' || upper.startsWith('PASS ')) {
+        return { verified: true };
+    }
+    if (upper.startsWith('FAIL:')) {
+        return { verified: false, reason: normalized.slice(5).trim() || 'Verification failed' };
+    }
+    if (upper.startsWith('FAIL ')) {
+        return { verified: false, reason: normalized.slice(5).trim() || 'Verification failed' };
+    }
+    if (/^PASS\b/i.test(normalized)) {
+        return { verified: true };
+    }
+    if (/^FAIL\b/i.test(normalized)) {
+        return { verified: false, reason: normalized.replace(/^FAIL\b[:\s-]*/i, '').trim() || 'Verification failed' };
+    }
+    const positiveSignals = [
+        /\bready to capture\b/i,
+        /\bready for capture\b/i,
+        /\bcapture can proceed\b/i,
+        /\bpage (?:is|looks|appears)? ?clean\b/i,
+        /\bpage est propre\b/i,
+        /\bpage propre\b/i,
+        /\bno (?:overlay|overlays|banner|banners|spinner|spinners|modal|modals|popup|popups)\b/i,
+        /\baucun(?:e)? (?:overlay|banni[eè]re|spinner|modal|popup|widget)\b/i,
+        /\bsans overlay\b/i,
+        /\bfully loaded\b/i,
+        /\bcompl[eè]tement charg[ée]\b/i,
+        /\bchargement (?:est )?termin[ée]\b/i,
+        /\ball elements visible\b/i,
+        /\btous les [ée]l[ée]ments visibles\b/i,
+        /\bmatches (?:the )?(?:user request|request)\b/i,
+        /\bcorrespond(?: parfaitement)? [àa] la demande\b/i,
+        /\bpr[êe]te? pour la capture\b/i,
+    ];
+    const negativeSignals = [
+        /\bnot ready\b/i,
+        /\bpas pr[êe]te?\b/i,
+        /\bnot clean\b/i,
+        /\bpas propre\b/i,
+        /\bwrong page\b/i,
+        /\bmauvaise page\b/i,
+        /\bstill visible\b/i,
+        /\bencore visible\b/i,
+        /\btoujours visible\b/i,
+        /\bstill loading\b/i,
+        /\bencore en chargement\b/i,
+        /\bspinner visible\b/i,
+        /\bcookie banner visible\b/i,
+        /\bbanni[eè]re cookie visible\b/i,
+        /\boverlay present\b/i,
+        /\bmodal visible\b/i,
+        /\bpopup visible\b/i,
+        /\bcropped\b/i,
+        /\bcut off\b/i,
+        /\bpartially visible\b/i,
+        /\btronqu[ée]\b/i,
+        /\bcoup[ée]\b/i,
+        /\bpartiellement visible\b/i,
+        /\bneeds fixing\b/i,
+        /\bmust be fixed\b/i,
+        /\b[àa] corriger\b/i,
+    ];
+    const positiveCount = positiveSignals.filter((pattern) => pattern.test(normalized)).length;
+    const hasNegativeSignal = negativeSignals.some((pattern) => pattern.test(normalized));
+    if (positiveCount >= 1 && !hasNegativeSignal) {
+        return { verified: true };
+    }
+    if (hasNegativeSignal && positiveCount === 0) {
+        return { verified: false, reason: normalized.slice(0, 160) };
+    }
+    return null;
+}
+function parseWaitDurationMs(content) {
+    const normalized = content.toLowerCase();
+    const msMatch = normalized.match(/(\d{2,5})\s*(ms|millisecond|milliseconds)/i);
+    if (msMatch) {
+        return Math.min(5000, Math.max(300, Number(msMatch[1])));
+    }
+    const secMatch = normalized.match(/(\d{1,2}(?:[.,]\d+)?)\s*(s|sec|secs|second|seconds|seconde|secondes)/i);
+    if (secMatch) {
+        const seconds = Number(secMatch[1].replace(',', '.'));
+        if (!Number.isNaN(seconds)) {
+            return Math.min(5000, Math.max(300, Math.round(seconds * 1000)));
+        }
+    }
+    return 1000;
+}
+/** Known tool names for validating embedded JSON tool calls in text. */
+const KNOWN_TOOL_NAMES = new Set([
+    'click', 'type_text', 'select_option', 'scroll', 'press_key',
+    'dismiss_overlays', 'wait', 'search_text', 'navigate_to',
+    'resize_viewport', 'take_screenshot', 'ready_to_capture',
+    'give_up', 'begin_subgoal', 'note', 'capture_by_selector',
+]);
+/**
+ * Try to extract a tool call embedded as JSON in the model's text output.
+ * Some models emit tool calls as plain text in the response content instead of
+ * using the structured tool_calls array, especially during streaming or format confusion:
+ *   {"name": "click", "arguments": {"index": 5, "reason": "..."}}
+ * This function gracefully recovers from such cases.
+ */
+function parseEmbeddedToolCall(text) {
+    // Pattern 1: JSON object with "name" and "arguments" keys
+    const jsonMatch = text.match(/\{[^{}]*"name"\s*:\s*"(\w+)"[^{}]*"arguments"\s*:\s*(\{[^}]+\})/s);
+    if (jsonMatch) {
+        const [, name, argsStr] = jsonMatch;
+        if (KNOWN_TOOL_NAMES.has(name)) {
+            try {
+                const args = JSON.parse(argsStr);
+                return { name: name, args };
+            }
+            catch { /* ignore */ }
+        }
+    }
+    // Pattern 2: function-call-like syntax: toolName({...})
+    const funcMatch = text.match(/\b(\w+)\s*\(\s*(\{[\s\S]*?\})\s*\)/);
+    if (funcMatch) {
+        const [, name, argsStr] = funcMatch;
+        if (KNOWN_TOOL_NAMES.has(name)) {
+            try {
+                const args = JSON.parse(argsStr);
+                return { name: name, args };
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return null;
+}
+export function inferActionFromAssistantText(content) {
+    const normalized = content.replace(/\s+/g, ' ').trim();
+    if (!normalized)
+        return null;
+    // Try to extract an embedded tool call from the text (some models emit
+    // tool calls as plain text in content instead of structured tool_calls).
+    const embedded = parseEmbeddedToolCall(normalized);
+    if (embedded) {
+        logger.debug(`Recovered embedded tool call from text: ${embedded.name}`);
+        return embedded;
+    }
+    const verificationDecision = parseVerificationDecisionText(normalized);
+    if (verificationDecision?.verified) {
+        return {
+            name: 'ready_to_capture',
+            args: { assessment: normalized.slice(0, 800) },
+        };
+    }
+    if (verificationDecision && !verificationDecision.verified) {
+        return {
+            name: 'give_up',
+            args: { reason: verificationDecision.reason ?? normalized.slice(0, 400) },
+        };
+    }
+    const lower = normalized.toLowerCase();
+    if ((/\bwait\b/.test(lower) || /\battend/.test(lower))
+        && (/\bsettle\b/.test(lower) || /\bcharg/.test(lower) || /\bload/.test(lower) || /\bnavigation\b/.test(lower))) {
+        return {
+            name: 'wait',
+            args: {
+                milliseconds: parseWaitDurationMs(normalized),
+                reason: 'assistant_text_fallback',
+            },
+        };
+    }
+    return null;
+}
+/**
+ * In dual-model mode, extract a text observation from a screenshot via the cheap vision model.
+ * Returns the observation text and usage, or null if visionModel is not configured.
+ */
+async function getVisionObservation(client, config, screenshot, context, stepNumber) {
+    if (!config.visionModel)
+        return null;
+    const screenshotUrl = await makeImageUrl(screenshot, 'image/jpeg', config.uploadImage);
+    const videoGuidance = config.runMode === 'video_navigation_preflight'
+        ? ' For video navigation preflight, explicitly say whether the screenshot is the EXACT pre-recording start state. Call out generic /home or dashboard states, unopened projects/sections/dialogs, and wrong fixed UI language/theme in the chrome.'
+        : '';
+    const messages = [
+        {
+            role: 'system',
+            content: 'You are a page state observer for screenshot verification. Describe the current page concisely: layout, visible content, overlays, loading state, and whether the page actually matches the requested target.'
+                + videoGuidance,
+        },
+        { role: 'user', content: [
+                { type: 'image_url', image_url: { url: screenshotUrl } },
+                { type: 'text', text: context },
+            ] },
+    ];
+    try {
+        const result = await client.chat.completions.create({ model: config.visionModel, messages, max_tokens: 300, stream: false, ...providerBody(config.visionModel, config.providerPreferences) }, { signal: config.abortSignal });
+        const content = result.choices?.[0]?.message?.content?.trim() ?? '';
+        const usage = extractUsage(result, stepNumber, 'verification', config.visionModel, 1);
+        return { observation: content, usage };
+    }
+    catch (err) {
+        if (isAbortError(err))
+            throw err;
+        logger.error(`Vision observer for verification failed: ${err.message}`);
+        return null; // Fall through to mono-model path
+    }
+}
+function buildVerificationVisionContext(params) {
+    const parts = [
+        'Describe this page for verification.',
+        `User request: ${params.config.prompt}`,
+        `Agent assessment: ${params.assessment}`,
+        params.pageContext.currentUrl ? `Current URL: ${params.pageContext.currentUrl}` : null,
+        params.pageContext.pageTitle ? `Current page title: ${params.pageContext.pageTitle}` : null,
+        params.config.currentLang ? `Expected language: ${params.config.currentLang}` : null,
+        params.config.currentTheme ? `Expected theme: ${params.config.currentTheme}` : null,
+    ].filter(Boolean);
+    if (params.config.runMode === 'video_navigation_preflight') {
+        parts.push('Verification target: exact pre-recording start state.', 'Explicitly say if the page is still only a generic home/dashboard/list state instead of the requested project/section/dialog.', 'Explicitly call out wrong fixed app chrome language/theme if buttons, navigation, headings, or breadcrumbs do not match the requested variant.');
+    }
+    return parts.join('\n');
+}
+/**
+ * Strip image_url parts from ChatCompletionContentPart[] and prepend a text observation.
+ */
+function replaceImagesWithObservation(parts, observation) {
+    const textParts = parts.filter(p => p.type !== 'image_url');
+    return [
+        { type: 'text', text: `Page observation (from vision model):\n${observation}` },
+        ...textParts,
+    ];
+}
+async function fallbackVerifyScreenshotJson(client, config, modelState, screenshot, assessment, pageContext, stepNumber, pageFingerprint, precomputedVisionObs) {
+    const verificationTarget = config.runMode === 'video_navigation_preflight'
+        ? 'exact pre-recording start state'
+        : 'requested page';
+    // Dual-model mode: reuse precomputed observation or call vision observer
+    const visionObs = precomputedVisionObs !== undefined
+        ? precomputedVisionObs
+        : await getVisionObservation(client, config, screenshot, buildVerificationVisionContext({
+            config,
+            pageContext,
+            assessment,
+        }), stepNumber);
+    const screenshotUrl = visionObs ? '' : await makeImageUrl(screenshot, 'image/jpeg', config.uploadImage);
+    const rawParts = buildVerificationMessage({
+        userPrompt: config.prompt,
+        screenshotUrl,
+        previousAssessment: assessment,
+        runMode: config.runMode,
+        currentLang: config.currentLang,
+        currentTheme: config.currentTheme,
+        pageContext,
+        runHints: config.runHints,
+        variantManifest: config.variantManifest,
+    });
+    const userContent = visionObs ? replaceImagesWithObservation(rawParts, visionObs.observation) : rawParts;
+    const fallbackMessages = [
+        {
+            role: 'system',
+            content: `You are a screenshot quality inspector. Respond with a JSON object: { "ready": true } if the screenshot is clean, fully loaded, and matches the ${verificationTarget}. Otherwise respond with { "ready": false, "reason": "<short explanation>" }. Output ONLY valid JSON, nothing else.`,
+        },
+        { role: 'user', content: userContent },
+    ];
+    if (visionObs) {
+        // Text-only call — no vision fallback needed
+        const result = await client.chat.completions.create({ model: modelState.active, messages: fallbackMessages, max_tokens: 256, response_format: { type: 'json_object' }, stream: false, ...providerBody(modelState.active, config.providerPreferences) }, { signal: config.abortSignal });
+        const primaryUsage = extractUsage(result, stepNumber, 'verification', modelState.active, 0);
+        const usage = visionObs.usage ? mergeUsage(visionObs.usage, primaryUsage) : primaryUsage;
+        const content = extractAssistantText(result.choices?.[0]?.message?.content);
+        if (!content || !content.trim()) {
+            logger.debug('Verification JSON fallback (dual-model) returned empty response — trying plain-text fallback');
+            return fallbackVerifyScreenshotText(client, config, modelState, screenshot, assessment, stepNumber, pageFingerprint, visionObs);
+        }
+        try {
+            const json = JSON.parse(content);
+            if (json.ready === true) {
+                logger.success('Qualité du screenshot vérifiée');
+                return { verified: true, usage, matchedPageId: config.variantManifest?.currentPageId ?? null, pageFingerprint, mode: 'text_fallback' };
+            }
+            const reason = (typeof json.reason === 'string' && json.reason.trim()) || 'Verification failed';
+            logger.ai(`Problème de vérification : ${reason}`);
+            return { verified: false, reason, usage, blockingReason: reason, pageFingerprint, mode: 'text_fallback' };
+        }
+        catch {
+            const snippet = (content || '').trim().slice(0, 160);
+            return { verified: false, reason: `Verification fallback returned invalid JSON: ${snippet}`, usage, blockingReason: `Verification fallback returned invalid JSON: ${snippet}`, pageFingerprint, mode: 'text_fallback' };
+        }
+    }
+    // Mono-model mode: send image directly with vision fallback
+    const fallbackResult = await callVisionCapableModel({
+        primaryModel: modelState.active,
+        fallbackModel: modelState.active === config.model ? config.fallbackModel : undefined,
+        onFallbackActivated: (model, reason) => {
+            modelState.active = model;
+            logger.info(`Vision fallback activated for JSON verification: ${model} (reason: ${reason})`);
+        },
+        callModel: (model) => client.chat.completions.create({
+            model,
+            messages: fallbackMessages,
+            max_tokens: 256,
+            response_format: { type: 'json_object' },
+            stream: false,
+            ...providerBody(model, config.providerPreferences),
+        }, { signal: config.abortSignal }),
+    });
+    modelState.active = fallbackResult.model;
+    const usage = extractUsage(fallbackResult.result, stepNumber, 'verification', fallbackResult.model, 1);
+    // Some models return tool_calls even when no tools are provided — check before parsing content
+    const fallbackToolCall = fallbackResult.result.choices?.[0]?.message?.tool_calls?.[0];
+    if (fallbackToolCall && 'function' in fallbackToolCall) {
+        if (fallbackToolCall.function.name === 'ready_to_capture') {
+            logger.success('Qualité du screenshot vérifiée');
+            return { verified: true, usage, matchedPageId: config.variantManifest?.currentPageId ?? null, pageFingerprint, mode: 'text_fallback' };
+        }
+        if (fallbackToolCall.function.name === 'give_up') {
+            const tcArgs = JSON.parse(fallbackToolCall.function.arguments);
+            const reason = (typeof tcArgs.reason === 'string' && tcArgs.reason.trim()) || 'Verification failed';
+            logger.ai(`Problème de vérification : ${reason}`);
+            return { verified: false, reason, usage, blockingReason: reason, pageFingerprint, mode: 'text_fallback' };
+        }
+    }
+    const content = extractAssistantText(fallbackResult.result.choices?.[0]?.message?.content);
+    // Guard against empty responses — some models don't support response_format:json_object.
+    // Fall through to a plain-text verification call as a last resort.
+    if (!content || !content.trim()) {
+        logger.debug('Verification JSON fallback returned empty response — trying plain-text fallback');
+        return fallbackVerifyScreenshotText(client, config, modelState, screenshot, assessment, stepNumber, pageFingerprint);
+    }
+    try {
+        const json = JSON.parse(content);
+        const ready = json.ready === true;
+        if (ready) {
+            logger.success('Qualité du screenshot vérifiée');
+            return {
+                verified: true,
+                usage,
+                matchedPageId: config.variantManifest?.currentPageId ?? null,
+                pageFingerprint,
+                mode: 'text_fallback',
+            };
+        }
+        const reason = (typeof json.reason === 'string' && json.reason.trim()) || 'Verification failed';
+        logger.ai(`Problème de vérification : ${reason}`);
+        return {
+            verified: false,
+            reason,
+            usage,
+            blockingReason: reason,
+            pageFingerprint,
+            mode: 'text_fallback',
+        };
+    }
+    catch {
+        // JSON parsing failed — treat as verification failure
+        const snippet = (content || '').trim().slice(0, 160);
+        logger.debug(`Verification JSON fallback returned invalid JSON: ${snippet}`);
+        return {
+            verified: false,
+            reason: snippet ? `Verification fallback returned invalid JSON: ${snippet}` : 'Verification returned no valid decision',
+            usage,
+            blockingReason: snippet ? `Verification fallback returned invalid JSON: ${snippet}` : 'Verification returned no valid decision',
+            pageFingerprint,
+            mode: 'text_fallback',
+        };
+    }
+}
+async function fallbackVerifyScreenshotText(client, config, modelState, screenshot, assessment, stepNumber, pageFingerprint, precomputedVisionObs) {
+    const verificationTarget = config.runMode === 'video_navigation_preflight'
+        ? 'exact pre-recording start state'
+        : 'requested page';
+    const verifyPromptText = `Requested page: ${config.prompt.slice(0, 300)}\nAgent assessment: ${assessment.slice(0, 300)}\nIs this screenshot at the ${verificationTarget}?`;
+    // Dual-model mode: reuse precomputed observation or call vision observer
+    const visionObs = precomputedVisionObs !== undefined
+        ? precomputedVisionObs
+        : await getVisionObservation(client, config, screenshot, verifyPromptText, stepNumber);
+    if (visionObs) {
+        try {
+            const messages = [
+                {
+                    role: 'system',
+                    content: `You are a screenshot quality inspector. Reply with exactly one word: READY if the page is clean, fully loaded, and matches the ${verificationTarget}. Otherwise reply NOT_READY followed by a colon and a short reason. Example: "NOT_READY: cookie banner visible". Output nothing else.`,
+                },
+                { role: 'user', content: `Page observation (from vision model):\n${visionObs.observation}\n\n${verifyPromptText}` },
+            ];
+            const result = await client.chat.completions.create({ model: modelState.active, messages, max_tokens: 64, stream: false, ...providerBody(modelState.active, config.providerPreferences) }, { signal: config.abortSignal });
+            const primaryUsage = extractUsage(result, stepNumber, 'verification', modelState.active, 0);
+            const usage = visionObs.usage ? mergeUsage(visionObs.usage, primaryUsage) : primaryUsage;
+            const content = extractAssistantText(result.choices?.[0]?.message?.content);
+            if (!content || !content.trim()) {
+                return { verified: false, reason: 'Verification model returned empty response', usage, blockingReason: 'Verification model returned empty response', pageFingerprint, mode: 'text_fallback' };
+            }
+            const normalized = content.trim().toUpperCase();
+            if (normalized === 'READY' || normalized.startsWith('READY')) {
+                logger.success('Qualité du screenshot vérifiée');
+                return { verified: true, usage, matchedPageId: config.variantManifest?.currentPageId ?? null, pageFingerprint, mode: 'text_fallback' };
+            }
+            const notReadyMatch = content.match(/NOT[_\s-]?READY\s*[:\-—]\s*(.*)/i);
+            const reason = notReadyMatch?.[1]?.trim() || content.trim().slice(0, 200);
+            logger.ai(`Problème de vérification : ${reason}`);
+            return { verified: false, reason, usage, blockingReason: reason, pageFingerprint, mode: 'text_fallback' };
+        }
+        catch (err) {
+            if (isAbortError(err))
+                throw err;
+            logger.error(`Verification text fallback (dual-model) call failed: ${err.message}`);
+            return { verified: false, reason: 'Verification text fallback call failed', usage: null, blockingReason: 'Verification text fallback call failed', pageFingerprint, mode: 'text_fallback' };
+        }
+    }
+    // Mono-model mode: send image directly with vision fallback
+    const screenshotUrl = await makeImageUrl(screenshot, 'image/jpeg', config.uploadImage);
+    const messages = [
+        {
+            role: 'system',
+            content: `You are a screenshot quality inspector. Reply with exactly one word: READY if the screenshot is clean, fully loaded, and matches the ${verificationTarget}. Otherwise reply NOT_READY followed by a colon and a short reason. Example: "NOT_READY: cookie banner visible". Output nothing else.`,
+        },
+        {
+            role: 'user',
+            content: [
+                { type: 'image_url', image_url: { url: screenshotUrl } },
+                { type: 'text', text: verifyPromptText },
+            ],
+        },
+    ];
+    try {
+        const result = await callVisionCapableModel({
+            primaryModel: modelState.active,
+            fallbackModel: modelState.active === config.model ? config.fallbackModel : undefined,
+            onFallbackActivated: (model, reason) => {
+                modelState.active = model;
+                logger.info(`Vision fallback activated for text verification: ${model} (reason: ${reason})`);
+            },
+            callModel: (model) => client.chat.completions.create({
+                model,
+                messages,
+                max_tokens: 64,
+                stream: false,
+                ...providerBody(model, config.providerPreferences),
+            }, { signal: config.abortSignal }),
+        });
+        modelState.active = result.model;
+        const usage = extractUsage(result.result, stepNumber, 'verification', result.model, 1);
+        const content = extractAssistantText(result.result.choices?.[0]?.message?.content);
+        if (!content || !content.trim()) {
+            logger.debug('Verification text fallback returned empty response');
+            return { verified: false, reason: 'Verification model returned empty response', usage, blockingReason: 'Verification model returned empty response', pageFingerprint, mode: 'text_fallback' };
+        }
+        const normalized = content.trim().toUpperCase();
+        if (normalized === 'READY' || normalized.startsWith('READY')) {
+            logger.success('Qualité du screenshot vérifiée');
+            return { verified: true, usage, matchedPageId: config.variantManifest?.currentPageId ?? null, pageFingerprint, mode: 'text_fallback' };
+        }
+        const notReadyMatch = content.match(/NOT[_\s-]?READY\s*[:\-—]\s*(.*)/i);
+        const reason = notReadyMatch?.[1]?.trim() || content.trim().slice(0, 200);
+        logger.ai(`Problème de vérification : ${reason}`);
+        return { verified: false, reason, usage, blockingReason: reason, pageFingerprint, mode: 'text_fallback' };
+    }
+    catch (err) {
+        if (isAbortError(err))
+            throw err;
+        logger.error(`Verification text fallback call failed: ${err.message}`);
+        return { verified: false, reason: 'Verification text fallback call failed', usage: null, blockingReason: 'Verification text fallback call failed', pageFingerprint, mode: 'text_fallback' };
+    }
+}
+async function performBrowserAction(browser, action, args) {
+    const dismissPageOverlays = async () => {
+        if (typeof browser.dismissOverlays === 'function') {
+            await browser.dismissOverlays();
+            return;
+        }
+        await dismissCookiesAndWidgets(browser.currentPage);
+    };
+    switch (action) {
+        case 'click':
+        case 'safe_expand': {
+            const hoverOnly = args.hover_only === true || action === 'safe_expand';
+            // Replay actions may need force:true to bypass pointer-event interception
+            // (e.g., after dark theme switch, <html class="dark"> intercepts events briefly)
+            const forceClick = args.__forceClick === true;
+            if (args.index !== undefined) {
+                if (hoverOnly) {
+                    await browser.hoverByIndex(args.index);
+                }
+                else {
+                    await browser.clickByIndex(args.index);
+                }
+            }
+            else if (args.selector) {
+                if (hoverOnly) {
+                    await browser.hoverBySelector(args.selector);
+                }
+                else {
+                    await browser.clickBySelector(args.selector, { force: forceClick });
+                }
+            }
+            else if (args.x !== undefined && args.y !== undefined) {
+                if (hoverOnly) {
+                    await browser.hoverByCoordinates(args.x, args.y);
+                }
+                else {
+                    await browser.clickByCoordinates(args.x, args.y);
+                }
+            }
+            else {
+                throw new Error('click requires index, selector, or x/y coordinates');
+            }
+            return;
+        }
+        case 'hover':
+            if (args.index !== undefined) {
+                await browser.hoverByIndex(args.index);
+            }
+            else if (args.selector) {
+                await browser.hoverBySelector(args.selector);
+            }
+            else if (args.x !== undefined && args.y !== undefined) {
+                await browser.hoverByCoordinates(args.x, args.y);
+            }
+            else {
+                throw new Error('hover requires index, selector, or x/y coordinates');
+            }
+            return;
+        case 'type_text':
+            await browser.typeText(args.text, {
+                index: args.index,
+                selector: args.selector,
+                clearFirst: args.clearFirst,
+            });
+            return;
+        case 'select_option':
+            await browser.selectOption({
+                index: args.index,
+                selector: args.selector,
+                optionLabel: args.optionLabel,
+                optionValue: args.optionValue,
+                optionIndex: args.optionIndex,
+            });
+            return;
+        case 'scroll':
+            if (args.index !== undefined) {
+                await browser.scrollElementIntoView(args.index, {
+                    align: args.align,
+                    margin: args.margin,
+                });
+            }
+            else {
+                await browser.scroll(args.direction, args.amount, args.selector);
+            }
+            return;
+        case 'scroll_to_element':
+            await browser.scrollElementIntoView(args.index, {
+                align: args.align,
+                margin: args.margin,
+            });
+            return;
+        case 'press_key':
+            await browser.pressKey(args.key);
+            return;
+        case 'navigate_to':
+            await browser.navigateTo(args.url);
+            await dismissPageOverlays();
+            return;
+        case 'wait':
+            await browser.wait(Math.min(args.milliseconds || 1000, 5000));
+            return;
+        case 'resize_viewport':
+            await browser.resizeViewport(args.width, args.height);
+            await browser.wait(500);
+            await dismissPageOverlays();
+            return;
+        case 'dismiss_overlays':
+            await browser.dismissOverlays();
+            return;
+        default:
+            throw new Error(`Unknown action: ${action}`);
+    }
+}
+export async function executeAction(browser, action, args) {
+    let before = null;
+    let reaction = null;
+    let outcome;
+    let stateChanged;
+    logActionProgress(action, 'capturing baseline observation');
+    try {
+        before = await withAgentStepTimeout(() => browser.captureObservation(), {
+            stepLabel: `${action} baseline captureObservation`,
+            timeoutMs: ACTION_OBSERVATION_TIMEOUT_MS,
+        });
+    }
+    catch (error) {
+        if (isAgentStepTimeoutError(error)) {
+            logger.info(`${buildActionTimeoutMessage('baseline observation', action, error.timeoutMs)}; continuing without baseline.`);
+            before = null;
+        }
+        else {
+            logger.info(`Action progress: ${action} -> baseline observation unavailable (${error.message})`);
+            before = null;
+        }
+    }
+    const authSubmitAction = isLikelyAuthenticationSubmitAction(action, args, before);
+    const reactionOptions = getReactionOptions(action, args, authSubmitAction);
+    logActionProgress(action, 'executing browser action');
+    try {
+        await withAgentStepTimeout(() => performBrowserAction(browser, action, args), {
+            stepLabel: `${action} browser execution`,
+            timeoutMs: getActionExecutionTimeoutMs(action, args),
+        });
+    }
+    catch (error) {
+        if (isAgentStepTimeoutError(error)) {
+            const recovery = await performActionDiagnosticRecovery(browser, action, before);
+            if (recovery.reaction?.changed) {
+                return {
+                    success: true,
+                    outcome: `${buildActionTimeoutMessage('browser execution', action, error.timeoutMs)}; recovered via diagnostic observation: ${recovery.reaction.summary}`,
+                    stateChanged: true,
+                };
+            }
+            return {
+                success: false,
+                error: getDiagnosticRecoveryFailureMessage('browser execution', action, error.timeoutMs, { afterChanged: recovery.reaction?.changed, recoveryError: recovery.error }),
+            };
+        }
+        return { success: false, error: enrichErrorMessage(error.message) };
+    }
+    if (before) {
+        logActionProgress(action, 'waiting for page reaction');
+        try {
+            reaction = await withAgentStepTimeout(() => browser.waitForPageReaction(before, reactionOptions), {
+                stepLabel: `${action} post-action waitForPageReaction`,
+                timeoutMs: reactionOptions.timeoutMs + 1200,
+            });
+        }
+        catch (error) {
+            if (isAgentStepTimeoutError(error)) {
+                const recovery = await performActionDiagnosticRecovery(browser, action, before);
+                if (recovery.reaction?.changed) {
+                    return {
+                        success: true,
+                        outcome: `${buildActionTimeoutMessage('post-action reaction', action, error.timeoutMs)}; recovered via diagnostic observation: ${recovery.reaction.summary}`,
+                        stateChanged: true,
+                    };
+                }
+                return {
+                    success: false,
+                    error: getDiagnosticRecoveryFailureMessage('post-action reaction', action, error.timeoutMs, { afterChanged: recovery.reaction?.changed, recoveryError: recovery.error }),
+                };
+            }
+            logger.info(`Action progress: ${action} -> page reaction unavailable (${error.message})`);
+            reaction = null;
+        }
+    }
+    if (reaction) {
+        outcome = reaction.summary;
+        stateChanged = reaction.changed;
+        if (action !== 'navigate_to' && reaction.before.url !== reaction.after.url) {
+            // Only attempt overlay dismissal when the new page signals possible overlays
+            // (dialogs, loading indicators, or expanded elements). Skipping saves 1-3.5s per navigation.
+            const hasOverlaySignals = reaction.after.dialogCount > 0
+                || reaction.after.loadingIndicatorCount > 0
+                || reaction.after.expandedCount > 0;
+            if (hasOverlaySignals) {
+                logActionProgress(action, 'post-navigation cleanup');
+                try {
+                    const cleanup = await withAgentStepTimeout(() => browser.dismissOverlays(), {
+                        stepLabel: `${action} post-navigation dismissOverlays`,
+                        timeoutMs: getActionExecutionTimeoutMs('dismiss_overlays', {}),
+                    });
+                    if (cleanup.dismissed) {
+                        const cleanupReaction = await withAgentStepTimeout(() => browser.waitForPageReaction(reaction.after, {
+                            timeoutMs: 1200,
+                            settleMs: 200,
+                        }), {
+                            stepLabel: `${action} post-navigation waitForPageReaction`,
+                            timeoutMs: 2400,
+                        }).catch(() => null);
+                        outcome = cleanupReaction
+                            ? `${reaction.summary}; cleanup: ${cleanupReaction.summary}; page cleanup reapplied after navigation.`
+                            : `${reaction.summary}; page cleanup reapplied after navigation.`;
+                        stateChanged = reaction.changed || cleanupReaction?.changed || stateChanged;
+                    }
+                    else {
+                        outcome = `${reaction.summary}; page cleanup checked after navigation.`;
+                    }
+                }
+                catch (error) {
+                    if (isAgentStepTimeoutError(error)) {
+                        outcome = `${reaction.summary}; post-navigation cleanup timed out after ${error.timeoutMs}ms.`;
+                    }
+                    else {
+                        outcome = `${reaction.summary}; post-navigation cleanup skipped: ${error.message}`;
+                    }
+                }
+            }
+        }
+    }
+    return { success: true, outcome, stateChanged };
+}
+function enrichErrorMessage(message) {
+    const msg = message.toLowerCase();
+    if (msg.includes('timeout') && (msg.includes('element') || msg.includes('selector') || msg.includes('locator'))) {
+        return `${message}. HINT: Element not found or not interactable. Try search_text to locate it, scroll to reveal it, or use a different element/approach.`;
+    }
+    if (msg.includes('not visible') || msg.includes('hidden') || msg.includes('display: none')) {
+        return `${message}. HINT: Element is hidden. It may be inside a collapsed menu or behind an overlay. Try safe_expand on a parent trigger, or dismiss_overlays first.`;
+    }
+    if (msg.includes('outside') && msg.includes('viewport')) {
+        return `${message}. HINT: Element is outside the viewport. Use scroll_to_element to bring it into view first.`;
+    }
+    if (msg.includes('navigation') && msg.includes('timeout')) {
+        return `${message}. HINT: Page load timed out. The site may be slow. Try wait(2000) and then continue.`;
+    }
+    if (msg.includes('resolved to 0') || msg.includes('no element') || msg.includes('strict mode')) {
+        return `${message}. HINT: CSS selector matched nothing or too many elements. Use element index instead, or search_text to find the element.`;
+    }
+    if (msg.includes('intercept') || msg.includes('other element would receive')) {
+        return `${message}. HINT: Another element is covering the target (overlay, banner, or modal). Use dismiss_overlays or press_key("Escape") first.`;
+    }
+    return message;
+}
+async function verifyScreenshot(client, config, modelState, browser, assessment, stepNumber, options) {
+    throwIfAborted(config.abortSignal, 'Agent verification cancelled.');
+    logger.info('Vérification de la qualité du screenshot…');
+    let verificationBundle;
+    try {
+        verificationBundle = await withAgentStepTimeout(() => browser.captureVerificationBundle(), {
+            stepLabel: 'verification captureVerificationBundle',
+            timeoutMs: VERIFICATION_BUNDLE_TIMEOUT_MS,
+        });
+        logger.debug(`Verification snapshot ready [${verificationBundle.coherenceKey}] @ ${verificationBundle.url}`);
+    }
+    catch (error) {
+        if (isAgentStepTimeoutError(error)) {
+            const reason = buildVerificationTimeoutMessage('captureVerificationBundle', error.timeoutMs);
+            logger.ai(`Problème de vérification : ${reason}`);
+            return {
+                verified: false,
+                reason,
+                usage: null,
+                blockingReason: reason,
+                mode: 'deterministic',
+            };
+        }
+        const reason = error.message;
+        logger.ai(`Problème de vérification : ${reason}`);
+        return {
+            verified: false,
+            reason,
+            usage: null,
+            blockingReason: reason,
+            mode: 'deterministic',
+        };
+    }
+    if (config.runMode === 'language_preflight') {
+        try {
+            const reason = buildLanguagePreflightVerificationFailureReason({
+                requestedLang: config.currentLang,
+                requestedTheme: config.currentTheme,
+                currentUrl: verificationBundle.url,
+                signals: verificationBundle.pageSignals,
+            });
+            if (!reason) {
+                logger.success('Qualité du screenshot vérifiée');
+                return {
+                    verified: true,
+                    usage: null,
+                    matchedPageId: config.variantManifest?.currentPageId ?? null,
+                    mode: 'deterministic',
+                };
+            }
+            logger.ai(`Problème de vérification : ${reason}`);
+            return {
+                verified: false,
+                reason,
+                usage: null,
+                blockingReason: reason,
+                mode: 'deterministic',
+            };
+        }
+        catch (error) {
+            const reason = error.message;
+            logger.ai(`Problème de vérification : ${reason}`);
+            return {
+                verified: false,
+                reason,
+                usage: null,
+                blockingReason: reason,
+                mode: 'deterministic',
+            };
+        }
+    }
+    const allowDeterministicSuccess = options?.allowDeterministicSuccess
+        ?? (!config.variantManifest?.currentPageId
+            && (config.variantManifest?.previousValidatedCaptures.length ?? 0) === 0);
+    {
+        const deterministicCheck = inferDeterministicReadyDecision({
+            observation: verificationBundle.observation,
+            assessment,
+            targetUrl: config.url,
+            skipDialogCheck: options?.skipDialogCheck,
+            allowSuccess: allowDeterministicSuccess,
+        });
+        if (deterministicCheck?.verified) {
+            // For video navigation preflight, also check that we're not on a generic dashboard.
+            // The deterministic check may pass on /home when the assessment mentions the project,
+            // but the agent hasn't actually navigated into it.
+            const isGenericDashboard = config.runMode === 'video_navigation_preflight'
+                && verificationBundle.url
+                && /^\/(home|dashboard|app)?\/?$/.test(new URL(verificationBundle.url).pathname);
+            if (isGenericDashboard) {
+                logger.ai('Problème de vérification : la page est un dashboard générique, le projet/section demandé n\'est pas encore ouvert.');
+                return {
+                    verified: false,
+                    reason: 'Still on generic dashboard (/home). Navigate into the specific project/section before calling ready_to_capture.',
+                    usage: null,
+                    blockingReason: 'generic_dashboard',
+                    pageFingerprint: computeScreenshotFingerprint(verificationBundle.screenshot),
+                    mode: 'deterministic',
+                };
+            }
+            logger.success('Qualité du screenshot vérifiée');
+            return {
+                verified: true,
+                usage: null,
+                matchedPageId: config.variantManifest?.currentPageId ?? null,
+                pageFingerprint: computeScreenshotFingerprint(verificationBundle.screenshot),
+                mode: 'deterministic',
+            };
+        }
+        if (deterministicCheck && !deterministicCheck.verified) {
+            logger.ai(`Problème de vérification : ${deterministicCheck.reason}`);
+            return {
+                verified: false,
+                reason: deterministicCheck.reason,
+                usage: null,
+                blockingReason: deterministicCheck.reason,
+                pageFingerprint: computeScreenshotFingerprint(verificationBundle.screenshot),
+                mode: 'deterministic',
+            };
+        }
+    }
+    const screenshotBuf = verificationBundle.screenshot;
+    const pageFingerprint = computeScreenshotFingerprint(screenshotBuf);
+    const duplicateOfPageId = findDuplicateVariantCapture(config.variantManifest, pageFingerprint);
+    if (duplicateOfPageId) {
+        const reason = `Duplicate capture detected: current page matches previously validated page "${duplicateOfPageId}". Reach a distinct state for "${config.variantManifest?.currentPageId ?? 'current'}" before capturing.`;
+        logger.ai(`Problème de vérification : ${reason}`);
+        return {
+            verified: false,
+            reason,
+            usage: null,
+            duplicateOfPageId,
+            blockingReason: reason,
+            pageFingerprint,
+            mode: 'vision',
+        };
+    }
+    const pageSignals = verificationBundle.pageSignals;
+    const latestObservation = verificationBundle.observation;
+    // Content-based identity checks are advisory — the LLM sees the screenshot
+    // and can judge correctly, so we pass these as hints instead of hard rejections.
+    const identityHint = config.runMode === 'video_navigation_preflight' && !config.variantManifest?.currentPageIdentity
+        ? null
+        : inferVariantIdentityFailure({
+            pageId: config.variantManifest?.currentPageId ?? null,
+            prompt: config.prompt,
+            currentUrl: verificationBundle.url,
+            visibleText: [
+                pageSignals.title,
+                pageSignals.headings.join(' '),
+                pageSignals.navLabels.join(' '),
+                pageSignals.visibleText,
+            ].filter(Boolean).join(' '),
+            dialogCount: latestObservation.dialogCount,
+            pageIdentity: config.variantManifest?.currentPageIdentity,
+        });
+    if (identityHint) {
+        logger.debug(`Identity hint for LLM verification: ${identityHint}`);
+    }
+    const variantMismatchHint = config.runMode === 'video_navigation_preflight'
+        ? buildLanguagePreflightVerificationFailureReason({
+            requestedLang: config.currentLang,
+            requestedTheme: config.currentTheme,
+            currentUrl: verificationBundle.url,
+            signals: verificationBundle.pageSignals,
+        }) || null
+        : null;
+    if (variantMismatchHint) {
+        logger.debug(`Variant hint for LLM verification: ${variantMismatchHint}`);
+    }
+    // Manifest-aware deterministic check — only trust its ACCEPT decisions.
+    // Rejections based on content analysis are passed to the LLM as hints.
+    const manifestReadyDecision = inferManifestReadyDecision({
+        observation: latestObservation,
+        assessment,
+        config,
+        bundle: verificationBundle,
+    });
+    if (manifestReadyDecision?.verified) {
+        logger.success('Qualité du screenshot vérifiée');
+        return {
+            verified: true,
+            usage: null,
+            matchedPageId: config.variantManifest?.currentPageId ?? null,
+            pageFingerprint,
+            mode: 'deterministic',
+        };
+    }
+    // Manifest rejection is downgraded to an advisory hint for the LLM
+    const manifestHint = manifestReadyDecision && !manifestReadyDecision.verified
+        ? manifestReadyDecision.reason
+        : null;
+    if (manifestHint) {
+        logger.debug(`Manifest hint for LLM verification: ${manifestHint}`);
+    }
+    // Page-signal deterministic check: combine assessment parse, identity check,
+    // stability, variant match, and dialog absence into a single accept gate.
+    // Never rejects — only accepts or returns null (inconclusive → LLM).
+    const pageSignalDecision = inferPageSignalReadyDecision({
+        observation: latestObservation,
+        assessment,
+        config,
+        bundle: verificationBundle,
+        identityFailure: identityHint,
+    });
+    if (pageSignalDecision?.verified) {
+        logger.success('Qualité du screenshot vérifiée');
+        return {
+            verified: true,
+            usage: null,
+            matchedPageId: config.variantManifest?.currentPageId ?? null,
+            pageFingerprint,
+            mode: 'deterministic',
+        };
+    }
+    // Dialog presence hint — let the LLM judge whether the dialog is the intended
+    // capture target or an obstruction, rather than making a deterministic call.
+    const dialogHint = latestObservation.dialogCount > 0
+        ? `A dialog/modal is currently open (${latestObservation.dialogCount}). Judge whether this dialog is the intended capture target or an unwanted overlay blocking the page.`
+        : null;
+    const pageContext = {
+        currentUrl: verificationBundle.url,
+        pageTitle: verificationBundle.title,
+    };
+    const verificationDiagnostics = summarizeVerificationDiagnostics(config, verificationBundle);
+    const verificationTools = agentTools.filter(t => ['ready_to_capture', 'give_up'].includes(t.function.name));
+    // Dual-model mode: use vision observer to describe the page, then text-only primary model
+    const visionObs = await getVisionObservation(client, config, screenshotBuf, buildVerificationVisionContext({
+        config,
+        pageContext,
+        assessment,
+    }), stepNumber);
+    const screenshotUrl = visionObs ? '' : await makeImageUrl(screenshotBuf, 'image/jpeg', config.uploadImage);
+    const rawParts = buildVerificationMessage({
+        userPrompt: config.prompt,
+        screenshotUrl,
+        previousAssessment: assessment,
+        runMode: config.runMode,
+        currentLang: config.currentLang,
+        currentTheme: config.currentTheme,
+        pageContext,
+        runHints: config.runHints,
+        variantManifest: config.variantManifest,
+        verificationDiagnostics,
+        identityHints: [identityHint, manifestHint, dialogHint, variantMismatchHint].filter(Boolean),
+    });
+    const userContent = visionObs ? replaceImagesWithObservation(rawParts, visionObs.observation) : rawParts;
+    const systemPrompt = config.runMode === 'video_navigation_preflight'
+        ? 'You are a video navigation verification inspector. You MUST respond by calling exactly one tool — do NOT reply with text.\n'
+            + '- Call ready_to_capture ONLY if the screenshot shows the EXACT pre-recording start state.\n'
+            + '- Reject generic /home or dashboard states when the requested project, section, tab, or dialog is not actually open yet.\n'
+            + '- Reject if the fixed app chrome is in the wrong language or theme.\n'
+            + '- Reject if overlays, popups, spinners, or unrelated dialogs remain.\n'
+            + '- Call give_up with a short reason for any mismatch or uncertainty.\n'
+            + 'Pick one tool and call it now.'
+        : 'You are a screenshot quality inspector. You MUST respond by calling exactly one tool — do NOT reply with text.\n'
+            + '- Call ready_to_capture if the screenshot is clean, fully loaded, free of overlays/spinners, and matches the user request.\n'
+            + '- Call give_up with a reason if there are issues (overlays, wrong page, loading state, etc.).\n'
+            + 'Pick one tool and call it now.';
+    const messages = [
+        {
+            role: 'system',
+            content: systemPrompt,
+        },
+        { role: 'user', content: userContent },
+    ];
+    try {
+        let visionResult;
+        if (visionObs) {
+            // Text-only call — no vision fallback needed
+            logger.info('Vérification de la capture…');
+            const result = await callWithRetry(client, {
+                model: modelState.active,
+                messages,
+                tools: verificationTools,
+                tool_choice: 'required',
+                max_tokens: 1024,
+            }, 3, config.abortSignal, config.providerPreferences);
+            visionResult = { result, model: modelState.active, fellBack: false };
+        }
+        else {
+            // Mono-model mode: send image directly with vision fallback
+            logger.info('Vérification de la capture…');
+            visionResult = await callVisionCapableModel({
+                primaryModel: modelState.active,
+                fallbackModel: modelState.active === config.model ? config.fallbackModel : undefined,
+                onFallbackActivated: (model, reason) => {
+                    modelState.active = model;
+                    logger.debug(`Vision fallback activated for verification: ${model} (reason: ${reason})`);
+                },
+                callModel: (model) => callWithRetry(client, {
+                    model,
+                    messages,
+                    tools: verificationTools,
+                    tool_choice: 'required',
+                    max_tokens: 1024,
+                }, 3, config.abortSignal, config.providerPreferences),
+            });
+        }
+        const response = visionResult.result;
+        if (visionResult.model && visionResult.model !== modelState.active) {
+            logger.debug(`OpenRouter model substitution detected: requested "${modelState.active}", got "${visionResult.model}"`);
+        }
+        modelState.active = visionResult.model;
+        const primaryUsage = extractUsage(response, stepNumber, 'verification', visionResult.model, visionObs ? 0 : 1);
+        // Merge vision observer usage if dual-model mode was used
+        const usage = visionObs?.usage ? mergeUsage(visionObs.usage, primaryUsage) : primaryUsage;
+        const toolCall = response.choices?.[0]?.message?.tool_calls?.[0];
+        const assistantText = extractAssistantText(response.choices?.[0]?.message?.content);
+        if (toolCall && 'function' in toolCall) {
+            if (toolCall.function.name === 'ready_to_capture') {
+                logger.success('Qualité du screenshot vérifiée');
+                return {
+                    verified: true,
+                    usage,
+                    matchedPageId: config.variantManifest?.currentPageId ?? null,
+                    pageFingerprint,
+                    mode: 'vision',
+                };
+            }
+            if (toolCall.function.name === 'give_up') {
+                const args = JSON.parse(toolCall.function.arguments);
+                logger.ai(`Problème de vérification : ${args.reason}`);
+                return {
+                    verified: false,
+                    reason: args.reason,
+                    usage,
+                    blockingReason: args.reason,
+                    pageFingerprint,
+                    mode: 'vision',
+                };
+            }
+        }
+        // No tool call found — try to extract a verdict from the assistant's text response
+        // before falling back to a separate JSON verification call.
+        if (assistantText) {
+            const textDecision = parseVerificationDecisionText(assistantText);
+            if (textDecision?.verified) {
+                logger.success('Qualité du screenshot vérifiée');
+                return {
+                    verified: true,
+                    usage,
+                    matchedPageId: config.variantManifest?.currentPageId ?? null,
+                    pageFingerprint,
+                    mode: 'text_fallback',
+                };
+            }
+            if (textDecision && !textDecision.verified) {
+                const reason = textDecision.reason ?? assistantText.slice(0, 400);
+                logger.ai(`Problème de vérification : ${reason}`);
+                return {
+                    verified: false,
+                    reason,
+                    usage,
+                    blockingReason: reason,
+                    pageFingerprint,
+                    mode: 'text_fallback',
+                };
+            }
+        }
+        // For models that generally support tool use well, skip the JSON fallback
+        // (which costs an extra LLM call) and go straight to the cheaper text fallback.
+        // The JSON fallback is only useful for models that support response_format but not tool_choice.
+        const modelLower = (modelState.active || '').toLowerCase();
+        const hasReliableToolUse = /claude|gpt-4|gemini|sonnet|opus|haiku/.test(modelLower);
+        if (hasReliableToolUse) {
+            logger.debug(`Verification returned no tool call from reliable model; skipping JSON fallback, trying text fallback directly. Model text: ${(assistantText || '(empty)').slice(0, 300)}`);
+            return fallbackVerifyScreenshotText(client, config, modelState, screenshotBuf, assessment, stepNumber, pageFingerprint, visionObs);
+        }
+        logger.debug(`Verification returned no structured tool call; retrying with JSON fallback. Model text: ${(assistantText || '(empty)').slice(0, 300)}`);
+        const fallback = await fallbackVerifyScreenshotJson(client, config, modelState, screenshotBuf, assessment, pageContext, stepNumber, pageFingerprint, visionObs);
+        return {
+            ...fallback,
+            usage: mergeUsage(usage, fallback.usage),
+        };
+    }
+    catch (err) {
+        if (isAbortError(err)) {
+            throw err;
+        }
+        logger.error(`Verification call failed: ${err.message}`);
+        return {
+            verified: false,
+            reason: err.message,
+            usage: null,
+            fatal: err instanceof VisionModelUnsupportedError,
+            blockingReason: err.message,
+            mode: 'vision',
+        };
+    }
+}
+export async function verifyCaptureReadiness(browser, config, apiKey, options = {}) {
+    const client = createClient(apiKey);
+    const modelState = { active: config.model };
+    return verifyScreenshot(client, config, modelState, browser, options.assessment ?? 'Preflight readiness check for a carried-over page state.', options.stepNumber ?? 1);
+}
+// Meta-actions that don't interact with the browser — excluded from stuck/no-effect detection
+const META_ACTIONS = new Set(['note', 'begin_subgoal', 'ready_to_capture']);
+const BOOTSTRAP_ACTIONS = new Set(['dismiss_overlays', 'wait']);
+function isNoEffectAction(action) {
+    return (action.success === false
+        || action.stateChanged === false
+        || action.outcome === 'No visible state change detected after the action.');
+}
+function isBootstrapStabilizationAction(action) {
+    if (BOOTSTRAP_ACTIONS.has(action.action))
+        return true;
+    return action.action === 'press_key' && String(action.params.key || '').toLowerCase() === 'escape';
+}
+function hasMeaningfulBrowserAction(actionHistory) {
+    return actionHistory.some((action) => !META_ACTIONS.has(action.action) && !isBootstrapStabilizationAction(action));
+}
+function buildRecoveryActionSignature(action) {
+    const parts = [action.action];
+    if (typeof action.params.selector === 'string' && action.params.selector.trim()) {
+        parts.push(`selector:${action.params.selector.trim()}`);
+    }
+    else if (action.params.index !== undefined) {
+        parts.push(`index:${String(action.params.index)}`);
+    }
+    else if (typeof action.params.url === 'string' && action.params.url.trim()) {
+        parts.push(`url:${action.params.url.trim().slice(0, 160)}`);
+    }
+    else if (action.params.x !== undefined && action.params.y !== undefined) {
+        parts.push(`xy:${String(action.params.x)},${String(action.params.y)}`);
+    }
+    if (typeof action.params.optionLabel === 'string' && action.params.optionLabel.trim()) {
+        parts.push(`optionLabel:${action.params.optionLabel.trim()}`);
+    }
+    else if (typeof action.params.optionValue === 'string' && action.params.optionValue.trim()) {
+        parts.push(`optionValue:${action.params.optionValue.trim()}`);
+    }
+    if (typeof action.params.key === 'string' && action.params.key.trim()) {
+        parts.push(`key:${action.params.key.trim()}`);
+    }
+    return parts.join('|');
+}
+function urlsRoughlyMatch(expectedUrl, currentUrl) {
+    if (!expectedUrl || !currentUrl)
+        return false;
+    try {
+        const expected = new URL(expectedUrl);
+        const current = new URL(currentUrl);
+        if (expected.origin !== current.origin)
+            return false;
+        // Exact pathname match, or current is a sub-path with a '/' separator.
+        // e.g., /products matches /products/123 but NOT /products-edit.
+        const expectedPath = expected.pathname || '/';
+        const currentPath = current.pathname || '/';
+        if (currentPath === expectedPath)
+            return true;
+        if (currentPath.startsWith(expectedPath) && (expectedPath.endsWith('/') || currentPath[expectedPath.length] === '/')) {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return currentUrl === expectedUrl;
+    }
+}
+function normalizeGuardPageUrl(value) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        return '';
+    try {
+        const parsed = new URL(value);
+        return `${parsed.origin}${parsed.pathname}`.replace(/\/$/, '') || parsed.origin;
+    }
+    catch {
+        return value.trim().replace(/\/$/, '');
+    }
+}
+function buildClickGuardAnchor(params) {
+    const parts = [];
+    if (typeof params.selector === 'string' && params.selector.trim()) {
+        parts.push(`selector:${params.selector.trim()}`);
+    }
+    if (params.index !== undefined) {
+        parts.push(`index:${String(params.index)}`);
+    }
+    if (typeof params.elementLabel === 'string' && params.elementLabel.trim()) {
+        parts.push(`label:${params.elementLabel.trim().toLowerCase()}`);
+    }
+    if (typeof params.href === 'string' && params.href.trim()) {
+        parts.push(`href:${normalizeGuardPageUrl(params.href)}`);
+    }
+    return parts.length > 0 ? parts.join('|') : null;
+}
+function buildClickGuardSignature(params, currentUrl) {
+    const anchor = buildClickGuardAnchor(params);
+    if (!anchor)
+        return null;
+    const pageKey = normalizeGuardPageUrl(params.preActionUrl ?? params.postActionUrl ?? currentUrl);
+    return `click|${pageKey}|${anchor}`;
+}
+function getPostActionDelayMs(action, execResult, options = {}) {
+    if (!execResult.success)
+        return 0;
+    if (options.authSubmitAction) {
+        return execResult.stateChanged ? 1200 : 700;
+    }
+    switch (action) {
+        case 'navigate_to':
+        case 'wait':
+        case 'resize_viewport':
+        case 'dismiss_overlays':
+            return 0;
+        case 'scroll':
+        case 'scroll_to_element':
+            return execResult.stateChanged ? 90 : 0;
+        case 'type_text':
+            return 60;
+        case 'click':
+        case 'safe_expand':
+        case 'select_option':
+        case 'press_key':
+        case 'hover':
+            return execResult.stateChanged ? 120 : 40;
+        default:
+            return 80;
+    }
+}
+export function getLivePreviewScreenshot(pageState) {
+    return pageState.cleanScreenshot ?? pageState.screenshot;
+}
+const LOGIN_URL_RE = /\b(login|log-in|signin|sign-in|auth|session|connexion|connect)\b/i;
+const LOGIN_FIELD_RE = /\b(password|mot de passe|passcode|otp|verification.?code)\b/i;
+const LOGIN_CLICK_RE = /\b(login|log-in|signin|sign-in|auth|session|connexion|connect|password|mot de passe|passcode|otp|verification.?code|email|e-mail)\b/i;
+const AUTH_SUBMIT_RE = /\b(continue|next|submit|verify|unlock|access|enter|continuer|suivant|soumettre|verifier|v[eé]rifier|acc[eé]der|entrer)\b/i;
+const INTERNAL_AUTOMATION_SELECTOR_RE = /\[data-ak-[^\]]+\]|data-ak-interactive-index/i;
+function getActionLabelHaystack(args) {
+    return [
+        args.selector,
+        args.elementLabel,
+        args.href,
+        args.text,
+        args.reason,
+    ]
+        .filter((value) => typeof value === 'string' && value.trim().length > 0)
+        .join(' ');
+}
+function observationLooksLikeAuthSurface(observation) {
+    if (!observation)
+        return false;
+    const haystack = [observation.url, observation.title, observation.textSample]
+        .filter(Boolean)
+        .join(' ');
+    return LOGIN_URL_RE.test(haystack) || LOGIN_FIELD_RE.test(haystack) || LOGIN_CLICK_RE.test(haystack);
+}
+function isLikelyAuthenticationSubmitAction(action, args, before) {
+    const haystack = getActionLabelHaystack(args);
+    if (action === 'click') {
+        if (LOGIN_CLICK_RE.test(haystack))
+            return true;
+        if (AUTH_SUBMIT_RE.test(haystack) && observationLooksLikeAuthSurface(before))
+            return true;
+    }
+    if (action === 'press_key' && args.key === 'Enter' && observationLooksLikeAuthSurface(before)) {
+        return true;
+    }
+    return false;
+}
+function getReactionOptions(action, args, authSubmitAction) {
+    if (authSubmitAction) {
+        return { timeoutMs: 4200, settleMs: 550, idleGraceMs: 1400 };
+    }
+    switch (action) {
+        case 'navigate_to':
+            return { timeoutMs: 3200, settleMs: 450 };
+        case 'click':
+        case 'safe_expand':
+        case 'select_option':
+        case 'press_key':
+            return { timeoutMs: 2400, settleMs: 350 };
+        case 'hover':
+        case 'scroll':
+        case 'scroll_to_element':
+        case 'resize_viewport':
+        case 'dismiss_overlays':
+            return { timeoutMs: 1600, settleMs: 250 };
+        case 'type_text':
+            return { timeoutMs: 1400, settleMs: 250 };
+        case 'wait':
+            return {
+                timeoutMs: Math.min(2200, Math.max(800, Number(args.milliseconds ?? 1000) + 400)),
+                settleMs: 250,
+            };
+        default:
+            return { timeoutMs: 1800, settleMs: 300 };
+    }
+}
+function containsInternalAutomationSelector(selector) {
+    return typeof selector === 'string' && INTERNAL_AUTOMATION_SELECTOR_RE.test(selector);
+}
+function replayActionRequiresAnchor(action) {
+    return [
+        'click',
+        'type_text',
+        'select_option',
+        'scroll',
+        'safe_expand',
+        'hover',
+        'scroll_to_element',
+    ].includes(action.action);
+}
+function hasReplayAnchor(params) {
+    if (typeof params.selector === 'string' && params.selector.trim().length > 0 && !containsInternalAutomationSelector(params.selector)) {
+        return true;
+    }
+    if (typeof params.index === 'number') {
+        return true;
+    }
+    if (typeof params.x === 'number' && typeof params.y === 'number') {
+        return true;
+    }
+    if (typeof params.href === 'string' && params.href.trim().length > 0) {
+        return true;
+    }
+    if (typeof params.elementLabel === 'string' && params.elementLabel.trim().length > 0) {
+        return true;
+    }
+    return false;
+}
+export function analyzeReplayCandidate(recordedActions, params = {}) {
+    const replayable = compactReplayActions(recordedActions, {
+        currentUrl: params.currentUrl,
+        targetUrl: params.targetUrl,
+        currentViewport: params.currentViewport,
+        isAuthenticated: params.isAuthenticated,
+    });
+    if (replayable.length === 0) {
+        return {
+            replayableActions: [],
+            skipReason: 'no replayable actions remain after filtering bootstrap/auth steps',
+        };
+    }
+    const currentDialogCount = params.currentDialogCount ?? null;
+    const pageIdentity = params.pageIdentity ?? null;
+    if (!pageIdentity?.dialogTarget
+        && (pageIdentity?.dedicatedRoute || pageIdentity?.kind === 'editor_route')
+        && (currentDialogCount ?? 0) > 0) {
+        return {
+            replayableActions: [],
+            skipReason: 'a dialog/modal is still open, but the target expects the underlying page/editor route',
+        };
+    }
+    const sanitized = [];
+    for (const action of replayable) {
+        if (replayActionRequiresAnchor(action) && !hasReplayAnchor(action.params)) {
+            if (sanitized.length === 0) {
+                return {
+                    replayableActions: [],
+                    skipReason: `the first replay action "${action.action}" has no reusable selector, coordinates, href, or label anchor`,
+                };
+            }
+            continue;
+        }
+        sanitized.push(action);
+    }
+    if (sanitized.length === 0) {
+        return {
+            replayableActions: [],
+            skipReason: 'no replayable actions remain after removing non-reusable interaction steps',
+        };
+    }
+    // Validate that the first action's expected starting URL matches the current browser URL.
+    // This prevents replaying actions recorded from page A when the browser is on page B.
+    const firstActionPreUrl = typeof sanitized[0].params.preActionUrl === 'string' ? sanitized[0].params.preActionUrl : null;
+    if (firstActionPreUrl && params.currentUrl) {
+        if (!urlsRoughlyMatch(firstActionPreUrl, params.currentUrl) && !urlsRoughlyMatch(params.currentUrl, firstActionPreUrl)) {
+            return {
+                replayableActions: [],
+                skipReason: `browser is on ${params.currentUrl} but recorded actions expect to start from ${firstActionPreUrl}`,
+            };
+        }
+    }
+    return {
+        replayableActions: sanitized,
+        skipReason: null,
+    };
+}
+function normalizeReplayText(value) {
+    return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+/**
+ * Compute word-token overlap ratio between two strings.
+ * Used for cross-language replay matching: "Filter by preset" and "Filtrer par preset"
+ * share the token "preset", yielding a non-zero overlap even across translations.
+ * Only considers tokens with length > 2 to skip noise words.
+ */
+function computeTokenOverlap(a, b) {
+    if (!a || !b)
+        return 0;
+    const tokensA = new Set(a.split(/\s+/).filter(t => t.length > 2));
+    const tokensB = new Set(b.split(/\s+/).filter(t => t.length > 2));
+    if (tokensA.size === 0 || tokensB.size === 0)
+        return 0;
+    let overlap = 0;
+    for (const token of tokensA) {
+        if (tokensB.has(token))
+            overlap++;
+    }
+    return overlap / Math.max(tokensA.size, tokensB.size);
+}
+function findElementForPoint(interactiveElements, x, y) {
+    const matches = interactiveElements
+        .filter((element) => {
+        const box = element.boundingBox;
+        return !!box
+            && x >= box.x
+            && x <= box.x + box.width
+            && y >= box.y
+            && y <= box.y + box.height;
+    })
+        .sort((a, b) => {
+        const aArea = (a.boundingBox?.width ?? Number.MAX_SAFE_INTEGER) * (a.boundingBox?.height ?? Number.MAX_SAFE_INTEGER);
+        const bArea = (b.boundingBox?.width ?? Number.MAX_SAFE_INTEGER) * (b.boundingBox?.height ?? Number.MAX_SAFE_INTEGER);
+        return aArea - bArea;
+    });
+    return matches[0] ?? null;
+}
+export function matchRecordedActionToElement(action, interactiveElements) {
+    // 1. Exact stable selector match (highest confidence — language-independent)
+    if (typeof action.params.selector === 'string' && !containsInternalAutomationSelector(action.params.selector)) {
+        const exactSelectorMatch = interactiveElements.find((element) => element.selector === action.params.selector);
+        if (exactSelectorMatch) {
+            return exactSelectorMatch;
+        }
+    }
+    // 2. Fuzzy scoring — all signals contribute to a composite score.
+    //    Coordinates are NO LONGER an early-return path; they participate in scoring
+    //    so that a strong label/href match isn't overridden by a stale coordinate hit.
+    const desiredHref = normalizeReplayText(action.params.href);
+    const desiredLabel = normalizeReplayText(action.params.elementLabel);
+    const desiredSelector = normalizeReplayText(action.params.selector);
+    const desiredTag = normalizeReplayText(action.params.elementTag);
+    const desiredRole = normalizeReplayText(action.params.elementRole);
+    const recordedCx = action.params.elementCx;
+    const recordedCy = action.params.elementCy;
+    let best = null;
+    for (const element of interactiveElements) {
+        let score = 0;
+        const elementText = normalizeReplayText(element.text);
+        const elementAria = normalizeReplayText(element.ariaLabel);
+        const elementHref = normalizeReplayText(element.href);
+        const elementSelector = normalizeReplayText(element.selector);
+        // --- Selector match (language-independent, very stable) ---
+        if (desiredSelector && !containsInternalAutomationSelector(desiredSelector) && elementSelector === desiredSelector) {
+            score += 900;
+        }
+        // --- href match (language-independent, very stable) ---
+        if (desiredHref) {
+            if (elementHref === desiredHref)
+                score += 700;
+            else if (elementHref && urlsRoughlyMatch(elementHref, desiredHref))
+                score += 550;
+        }
+        // --- Label match (language-dependent, tiered confidence) ---
+        if (desiredLabel) {
+            if (elementText === desiredLabel || elementAria === desiredLabel) {
+                score += 450;
+            }
+            else if ((elementText && (elementText.includes(desiredLabel) || desiredLabel.includes(elementText)))
+                || (elementAria && (elementAria.includes(desiredLabel) || desiredLabel.includes(elementAria)))) {
+                score += 260;
+            }
+            else {
+                // Cross-language token overlap: "filter by preset" ↔ "filtrer par preset" share "preset"
+                const textOverlap = computeTokenOverlap(desiredLabel, elementText);
+                const ariaOverlap = computeTokenOverlap(desiredLabel, elementAria);
+                const bestOverlap = Math.max(textOverlap, ariaOverlap);
+                if (bestOverlap >= 0.3) {
+                    score += Math.round(200 * bestOverlap);
+                }
+            }
+        }
+        // --- Structural match: tag + role (language-independent) ---
+        // Stronger weight so it can serve as a tiebreaker for fuzzy label matches.
+        if (desiredTag && desiredTag === element.tag.toLowerCase()) {
+            score += 50;
+            if (desiredRole && desiredRole === element.role.toLowerCase()) {
+                score += 60;
+            }
+        }
+        // --- Bounding box proximity (layout-dependent but language-independent) ---
+        if (recordedCx !== undefined && recordedCy !== undefined && element.boundingBox) {
+            const elCx = element.boundingBox.x + element.boundingBox.width / 2;
+            const elCy = element.boundingBox.y + element.boundingBox.height / 2;
+            const dist = Math.sqrt((elCx - recordedCx) ** 2 + (elCy - recordedCy) ** 2);
+            if (dist < 50)
+                score += 80;
+            else if (dist < 120)
+                score += 40;
+        }
+        // --- Legacy coordinate match (weakest signal — layout shift can misfire) ---
+        if (typeof action.params.x === 'number' && typeof action.params.y === 'number' && element.boundingBox) {
+            const box = element.boundingBox;
+            if (action.params.x >= box.x
+                && action.params.x <= box.x + box.width
+                && action.params.y >= box.y
+                && action.params.y <= box.y + box.height) {
+                score += 60;
+            }
+        }
+        if (score <= 0)
+            continue;
+        if (!best || score > best.score) {
+            best = { element, score };
+        }
+    }
+    // Require a minimum confidence threshold to avoid false positives.
+    // A score < 65 means the match is based on very weak signals only (e.g., coordinates
+    // alone = 60) — too risky to replay. Token overlap alone (≥66) or structural signals
+    // combined with coordinates are sufficient.
+    if (best && best.score < 65) {
+        return null;
+    }
+    return best?.element ?? null;
+}
+function hasExecutableReplayArgs(action, params) {
+    const hasStableSelector = typeof params.selector === 'string'
+        && params.selector.trim().length > 0
+        && !containsInternalAutomationSelector(params.selector);
+    const hasIndex = typeof params.index === 'number';
+    const hasCoordinates = typeof params.x === 'number' && typeof params.y === 'number';
+    switch (action) {
+        case 'click':
+        case 'safe_expand':
+        case 'hover':
+            return hasStableSelector || hasIndex || hasCoordinates;
+        case 'type_text':
+            return typeof params.text === 'string' && (hasStableSelector || hasIndex);
+        case 'select_option':
+            return ((typeof params.optionLabel === 'string'
+                || typeof params.optionValue === 'string'
+                || typeof params.optionIndex === 'number')
+                && (hasStableSelector || hasIndex));
+        case 'scroll':
+            return hasIndex || hasStableSelector || typeof params.direction === 'string';
+        case 'scroll_to_element':
+            return hasIndex;
+        case 'navigate_to':
+            return typeof params.url === 'string' && params.url.trim().length > 0;
+        case 'resize_viewport':
+            return typeof params.width === 'number' && typeof params.height === 'number';
+        case 'press_key':
+            return typeof params.key === 'string' && params.key.trim().length > 0;
+        case 'wait':
+        case 'dismiss_overlays':
+            return true;
+        default:
+            return false;
+    }
+}
+export function resolveReplayActionArgs(action, interactiveElements) {
+    const replayArgs = { ...action.params };
+    if (hasExecutableReplayArgs(action.action, replayArgs)) {
+        return { args: replayArgs, reason: null };
+    }
+    const matchedElement = matchRecordedActionToElement(action, interactiveElements);
+    if (matchedElement) {
+        if (action.action === 'click'
+            || action.action === 'safe_expand'
+            || action.action === 'hover'
+            || action.action === 'type_text'
+            || action.action === 'select_option'
+            || action.action === 'scroll'
+            || action.action === 'scroll_to_element') {
+            replayArgs.index = matchedElement.index;
+            delete replayArgs.selector;
+            delete replayArgs.x;
+            delete replayArgs.y;
+        }
+    }
+    if (replayArgs.selector && replayArgs.index !== undefined) {
+        delete replayArgs.index;
+    }
+    if (hasExecutableReplayArgs(action.action, replayArgs)) {
+        return { args: replayArgs, reason: null };
+    }
+    const anchors = [
+        typeof action.params.selector === 'string' ? action.params.selector : null,
+        typeof action.params.href === 'string' ? action.params.href : null,
+        typeof action.params.elementLabel === 'string' ? action.params.elementLabel : null,
+    ].filter((value) => !!value && value.trim().length > 0);
+    const anchorSummary = anchors.length > 0 ? anchors.join(' / ').slice(0, 160) : 'no replay anchor';
+    return {
+        args: null,
+        reason: `replay action "${action.action}" could not be resolved on the current page (${anchorSummary})`,
+    };
+}
+function isExplicitLoginAction(action) {
+    if (action.action === 'navigate_to' && typeof action.params.url === 'string' && LOGIN_URL_RE.test(action.params.url)) {
+        return true;
+    }
+    if (action.action === 'type_text' && typeof action.params.selector === 'string' && LOGIN_FIELD_RE.test(action.params.selector)) {
+        return true;
+    }
+    if (action.action === 'type_text' && typeof action.params.text === 'string' && /\{\{credential\./i.test(action.params.text)) {
+        return true;
+    }
+    if (action.action === 'click') {
+        const haystack = [
+            action.params.selector,
+            action.params.elementLabel,
+            action.params.href,
+        ]
+            .filter((value) => typeof value === 'string')
+            .join(' ');
+        if (LOGIN_CLICK_RE.test(haystack)) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasRecentExplicitLoginAction(previousActions) {
+    return previousActions.slice(-3).some(isExplicitLoginAction);
+}
+function isLoginAction(action, previousActions = []) {
+    if (isExplicitLoginAction(action)) {
+        return true;
+    }
+    if (action.action === 'click') {
+        const haystack = [
+            action.params.selector,
+            action.params.elementLabel,
+            action.params.href,
+        ]
+            .filter((value) => typeof value === 'string')
+            .join(' ');
+        if (AUTH_SUBMIT_RE.test(haystack) && hasRecentExplicitLoginAction(previousActions)) {
+            return true;
+        }
+    }
+    if (action.action === 'press_key'
+        && action.params.key === 'Enter'
+        && hasRecentExplicitLoginAction(previousActions)) {
+        return true;
+    }
+    return false;
+}
+export function compactReplayActions(recordedActions, params = {}) {
+    let replayable = recordedActions.filter(a => REPLAYABLE_ACTIONS.includes(a.action));
+    // When the session is already authenticated, strip login-related actions
+    if (params.isAuthenticated) {
+        const authAwareReplayable = replayable;
+        replayable = authAwareReplayable.filter((action, index) => !isLoginAction(action, authAwareReplayable.slice(0, index)));
+    }
+    let startIndex = 0;
+    while (startIndex < replayable.length) {
+        const action = replayable[startIndex];
+        if (action.action === 'wait') {
+            startIndex += 1;
+            continue;
+        }
+        if (action.action === 'dismiss_overlays') {
+            startIndex += 1;
+            continue;
+        }
+        if (action.action === 'resize_viewport'
+            && params.currentViewport
+            && Number(action.params.width) === params.currentViewport.width
+            && Number(action.params.height) === params.currentViewport.height) {
+            startIndex += 1;
+            continue;
+        }
+        if (action.action === 'navigate_to'
+            && typeof action.params.url === 'string'
+            && (urlsRoughlyMatch(action.params.url, params.currentUrl)
+                || urlsRoughlyMatch(action.params.url, params.targetUrl))) {
+            startIndex += 1;
+            continue;
+        }
+        break;
+    }
+    return replayable.slice(startIndex);
+}
+export function countRecentNoEffectActions(actionHistory) {
+    let count = 0;
+    for (let index = actionHistory.length - 1; index >= 0; index -= 1) {
+        const action = actionHistory[index];
+        // Skip meta-actions: note/begin_subgoal always have stateChanged=false but are not stuck indicators.
+        if (META_ACTIONS.has(action.action))
+            continue;
+        if (isNoEffectAction(action)) {
+            count += 1;
+            continue;
+        }
+        break;
+    }
+    return count;
+}
+export function shouldTriggerRecovery(actionHistory) {
+    // Only consider browser actions for recovery detection (exclude meta-actions like note/begin_subgoal)
+    const browserActions = actionHistory.filter(a => !META_ACTIONS.has(a.action));
+    if (browserActions.length < 2)
+        return false;
+    if (!hasMeaningfulBrowserAction(browserActions))
+        return false;
+    const last = browserActions[browserActions.length - 1];
+    const previous = browserActions[browserActions.length - 2];
+    const sameFailureSignature = !last.success
+        && !previous.success
+        && buildRecoveryActionSignature(last) === buildRecoveryActionSignature(previous)
+        && String(last.error || '').slice(0, 120) === String(previous.error || '').slice(0, 120);
+    // Detect A→B→A→B oscillation: last 4 browser actions form a repeating 2-cycle
+    if (browserActions.length >= 4) {
+        const [a, b, c, d] = browserActions.slice(-4);
+        const sigA = buildRecoveryActionSignature(a);
+        const sigB = buildRecoveryActionSignature(b);
+        const sigC = buildRecoveryActionSignature(c);
+        const sigD = buildRecoveryActionSignature(d);
+        if ([a, b, c, d].every(isNoEffectAction)
+            && sigA === sigC
+            && sigB === sigD
+            && sigA !== sigB) {
+            return true;
+        }
+    }
+    return sameFailureSignature || countRecentNoEffectActions(actionHistory) >= 2;
+}
+function getMeaningfulBrowserActions(actionHistory) {
+    return actionHistory.filter(action => !META_ACTIONS.has(action.action) && !isBootstrapStabilizationAction(action));
+}
+function countDistinctActionSignatures(actionHistory) {
+    return new Set(getMeaningfulBrowserActions(actionHistory).map(action => buildRecoveryActionSignature(action))).size;
+}
+const HARD_GIVE_UP_RE = /\b(5xx|500\b|404\b|page not found|not found|http error|server error|js crash|javascript crash|browser crashed|connection refused|dns|net::|ssl|certificate|blank page|white page|no content|infinite spinner)\b/i;
+const RECOVERABLE_GIVE_UP_RE = /\b(verification|ready_to_capture|dialog|modal|overlay|gallery|editor|route|navigation|assistant|conversation|wrong page|duplicate capture|capture target)\b/i;
+export function inferPrematureGiveUpCorrection(params) {
+    const reason = params.reason.trim();
+    const lastVerificationFailure = params.lastVerificationFailure?.trim();
+    if (HARD_GIVE_UP_RE.test(reason) || (lastVerificationFailure && HARD_GIVE_UP_RE.test(lastVerificationFailure))) {
+        return null;
+    }
+    // Detect verification contradiction: 3+ recent ready_to_capture failures with 2+ distinct
+    // reasons means the validators are cycling between irreconcilable states — allow give_up.
+    const recentCaptureFailures = params.actionHistory
+        .filter(a => a.action === 'ready_to_capture' && !a.success && a.error)
+        .slice(-6);
+    if (recentCaptureFailures.length >= 3) {
+        const distinctReasons = new Set(recentCaptureFailures.map(a => (a.error || '').replace(/^Verification failed:\s*/i, '').trim().slice(0, 120)));
+        if (distinctReasons.size >= 2 && distinctReasons.size <= 3) {
+            return null;
+        }
+    }
+    // If the agent has accumulated many consecutive no-effect actions, the objective
+    // is likely unreachable — allow give_up to avoid burning the remaining budget.
+    if (countRecentNoEffectActions(params.actionHistory) >= 8) {
+        return null;
+    }
+    if (lastVerificationFailure && RECOVERABLE_GIVE_UP_RE.test(lastVerificationFailure)) {
+        return `Do not give up yet. The last verification failure is still recoverable: ${lastVerificationFailure}. Try a materially different navigation or repair step first.`;
+    }
+    const meaningfulActions = getMeaningfulBrowserActions(params.actionHistory);
+    const distinctActionCount = countDistinctActionSignatures(params.actionHistory);
+    const hasTriedEnoughStrategies = meaningfulActions.length >= 4 && distinctActionCount >= 3;
+    const nearingBudget = params.iteration >= Math.max(6, params.maxIterations - 2);
+    if (!hasTriedEnoughStrategies && !nearingBudget) {
+        return 'Do not give up yet. You have not tried enough materially different actions. Change strategy before giving up.';
+    }
+    if (RECOVERABLE_GIVE_UP_RE.test(reason) && !nearingBudget) {
+        return 'Do not give up yet. The current issue still looks recoverable. Try a different navigation, search, or repair approach first.';
+    }
+    return null;
+}
+const REPEAT_GUARD_ACTIONS = new Set([
+    'click',
+    'safe_expand',
+    'hover',
+    'select_option',
+    'press_key',
+]);
+export function inferRepeatedActionGuard(params) {
+    // Guard 0: navigate-back detection — block navigating to a URL the agent just left
+    if (params.action === 'navigate_to' && typeof params.args.url === 'string' && params.currentUrl) {
+        const targetUrl = params.args.url.replace(/\/$/, '');
+        const recentNavigations = params.actionHistory
+            .filter(a => !META_ACTIONS.has(a.action) && a.success !== false)
+            .slice(-5);
+        // Check if we navigated AWAY from the target URL recently (within last 5 actions)
+        const justLeftTarget = recentNavigations.some(a => a.action === 'navigate_to'
+            && typeof a.params.url === 'string'
+            && !urlsRoughlyMatch(a.params.url, targetUrl)
+            && a.params.previousUrl
+            && urlsRoughlyMatch(String(a.params.previousUrl), targetUrl));
+        // Also check: are we trying to navigate to the same URL we're already on?
+        if (urlsRoughlyMatch(params.currentUrl, targetUrl)) {
+            return 'WARNING: You are already on this URL. No navigation needed. Focus on interacting with the current page instead.';
+        }
+        // Simpler check: did the last successful click/navigation bring us away from target? Going back suggests confusion.
+        // EXCEPTION: if the agent has recent no-effect actions, it's stuck and legitimately trying
+        // a different approach (e.g., navigating to the correct page). Don't block recovery navigation.
+        const recentAllActions = params.actionHistory
+            .filter(a => !META_ACTIONS.has(a.action))
+            .slice(-4);
+        const hasRecentNoEffect = recentAllActions.some(a => isNoEffectAction(a));
+        if (!hasRecentNoEffect) {
+            const recentUrls = recentNavigations
+                .filter(a => typeof a.params.href === 'string' || typeof a.params.url === 'string')
+                .slice(-3)
+                .map(a => String(a.params.href || a.params.url || '').replace(/\/$/, ''));
+            const wasRecentlyOnTarget = recentUrls.some(url => urlsRoughlyMatch(url, targetUrl));
+            if (wasRecentlyOnTarget && !urlsRoughlyMatch(params.currentUrl, targetUrl)) {
+                return `WARNING: You just navigated away from ${targetUrl} — going back suggests you are confused about the goal. Re-read the <task>/<goal> and <variant_manifest> carefully. If you need a modal, open it from the current page instead of navigating back.`;
+            }
+        }
+    }
+    if (!REPEAT_GUARD_ACTIONS.has(params.action))
+        return null;
+    const recentBrowserActions = params.actionHistory
+        .filter(action => !META_ACTIONS.has(action.action))
+        .slice(-2);
+    if (recentBrowserActions.length < 2)
+        return null;
+    // Guard 1: exact same action signature repeated with no effect
+    const candidateSignature = buildRecoveryActionSignature({
+        iteration: 0,
+        action: params.action,
+        params: params.args,
+        success: false,
+    });
+    const candidateClickSignature = params.action === 'click'
+        ? buildClickGuardSignature(params.args, params.currentUrl)
+        : null;
+    const repeatedNoEffect = recentBrowserActions.every(action => isNoEffectAction(action)
+        && (candidateClickSignature && action.action === 'click'
+            ? buildClickGuardSignature(action.params, params.currentUrl) === candidateClickSignature
+            : buildRecoveryActionSignature(action) === candidateSignature));
+    if (repeatedNoEffect) {
+        return 'BLOCKED: The previous attempts on this same target had no effect. Try a different control, search_text, scrolling, or a repair step instead of repeating it.';
+    }
+    // Guard 2: consecutive failed/blocked browser actions (different targets) —
+    // the agent is thrashing without making progress. Triggers after 4+ recent failures.
+    const recentActions = params.actionHistory
+        .filter(action => !META_ACTIONS.has(action.action))
+        .slice(-4);
+    if (recentActions.length >= 4 && recentActions.every(a => isNoEffectAction(a))) {
+        return 'BLOCKED: The last 4 browser actions all failed or had no visible effect. You are stuck. Step back and reconsider: verify the current URL, check if you are on the right page, try navigate_to to reach the correct page, or call give_up if this capture is impossible.';
+    }
+    // Guard 3: same element clicked 3+ times in recent history (regardless of effect).
+    // Catches multi-select dropdown toggling where each click "succeeds" but makes no progress.
+    if (params.action === 'click') {
+        const candidateClickSignature = buildClickGuardSignature(params.args, params.currentUrl);
+        if (candidateClickSignature) {
+            const candidateTarget = String((typeof params.args.elementLabel === 'string' && params.args.elementLabel.trim())
+                ? params.args.elementLabel
+                : params.args.selector ?? params.args.index ?? 'this target');
+            const recentClicks = params.actionHistory
+                .filter(a => a.action === 'click' && !META_ACTIONS.has(a.action))
+                .slice(-6);
+            const sameTargetCount = recentClicks.filter(a => buildClickGuardSignature(a.params, params.currentUrl) === candidateClickSignature).length;
+            if (sameTargetCount >= 3) {
+                return `BLOCKED: You have clicked "${candidateTarget}" ${sameTargetCount} times recently without progress. This is likely a toggle/multi-select control. Press Escape to close any open dropdown, then look for a DIFFERENT button (e.g., an edit/settings icon) to achieve your goal.`;
+            }
+        }
+    }
+    return null;
+}
+function normalizeSubgoalName(value) {
+    return value.trim().toLowerCase();
+}
+export function findReusableWorkflow(workflowCache, subgoalName) {
+    const normalizedSubgoal = normalizeSubgoalName(subgoalName);
+    if (!normalizedSubgoal)
+        return null;
+    let fuzzyMatch = null;
+    for (let index = workflowCache.length - 1; index >= 0; index -= 1) {
+        const candidate = workflowCache[index];
+        if (candidate.selectors.length === 0)
+            continue;
+        const normalizedCandidate = normalizeSubgoalName(candidate.subgoalName);
+        if (!normalizedCandidate)
+            continue;
+        if (normalizedCandidate === normalizedSubgoal)
+            return candidate;
+        if (!fuzzyMatch
+            && (normalizedCandidate.includes(normalizedSubgoal) || normalizedSubgoal.includes(normalizedCandidate))) {
+            fuzzyMatch = candidate;
+        }
+    }
+    return fuzzyMatch;
+}
+/**
+ * Replace base64 image content in older conversation messages with a text placeholder.
+ * Keeps only the most recent `keepRecentImages` user messages that contain screenshots.
+ * This dramatically reduces token cost on long agent runs (40-60% savings).
+ */
+function compressOldScreenshots(messages, keepRecentImages = 3) {
+    let imageCount = 0;
+    for (let i = messages.length - 1; i >= 1; i--) {
+        const msg = messages[i];
+        if (msg.role !== 'user' || !Array.isArray(msg.content))
+            continue;
+        const content = msg.content;
+        const hasImage = content.some(p => p.type === 'image_url');
+        if (!hasImage)
+            continue;
+        imageCount++;
+        if (imageCount <= keepRecentImages)
+            continue;
+        // Replace image_url parts with a compact text placeholder
+        msg.content = content.map(p => p.type === 'image_url'
+            ? { type: 'text', text: '[screenshot removed — older context]' }
+            : p);
+    }
+}
+/**
+ * Strip <page_dom>...</page_dom> blocks from old user messages to reduce token count.
+ * Keeps the DOM in the most recent `keepRecentWithDom` user messages intact.
+ * Only modifies text content parts — images and other types are left untouched.
+ */
+function compressOldDomBlocks(messages, keepRecentWithDom = 6, preservedPrefixMessages = 1) {
+    const PAGE_DOM_RE = /<page_dom>[\s\S]*?<\/page_dom>/g;
+    const PLACEHOLDER = '<page_dom>[older context — see current iteration for latest DOM]</page_dom>';
+    let domMessageCount = 0;
+    for (let i = messages.length - 1; i >= preservedPrefixMessages; i--) {
+        const msg = messages[i];
+        if (msg.role !== 'user')
+            continue;
+        const contentArr = Array.isArray(msg.content) ? msg.content : null;
+        const hasDom = contentArr
+            ? contentArr.some(p => typeof p === 'object' && 'text' in p && typeof p.text === 'string' && PAGE_DOM_RE.test(p.text))
+            : typeof msg.content === 'string' && PAGE_DOM_RE.test(msg.content);
+        // Reset regex lastIndex after test
+        PAGE_DOM_RE.lastIndex = 0;
+        if (!hasDom)
+            continue;
+        domMessageCount++;
+        if (domMessageCount <= keepRecentWithDom)
+            continue;
+        // Replace DOM block with compact placeholder
+        if (contentArr) {
+            for (const part of contentArr) {
+                if (typeof part === 'object' && 'text' in part && typeof part.text === 'string') {
+                    PAGE_DOM_RE.lastIndex = 0;
+                    part.text = part.text.replace(PAGE_DOM_RE, PLACEHOLDER);
+                }
+            }
+        }
+        else if (typeof msg.content === 'string') {
+            PAGE_DOM_RE.lastIndex = 0;
+            msg.content = msg.content.replace(PAGE_DOM_RE, PLACEHOLDER);
+        }
+    }
+}
+/**
+ * Trim the conversation thread to avoid context window overflow.
+ * Always preserves the first `preservedPrefixMessages` entries, then the last maxMessages messages.
+ * Also compresses old screenshots and DOM blocks to save tokens.
+ */
+export function trimConversationHistory(messages, maxMessages = 48, preservedPrefixMessages = 1) {
+    // Compress old screenshots before trimming to maximise token savings
+    compressOldScreenshots(messages, 1);
+    // Strip <page_dom> from older user messages — the current DOM is always available
+    compressOldDomBlocks(messages, 6, preservedPrefixMessages);
+    if (messages.length <= maxMessages + preservedPrefixMessages)
+        return;
+    const preservedPrefix = messages.slice(0, preservedPrefixMessages);
+    const recent = messages.slice(-(maxMessages));
+    messages.splice(0, messages.length, ...preservedPrefix, ...recent);
+}
+/**
+ * Format a tool result message for the conversation thread.
+ * This is what the LLM sees after each action — it replaces the old action history mechanism.
+ */
+function formatToolResult(name, args, execResult, elements) {
+    if (!execResult.success) {
+        return `FAILED: ${execResult.error || 'Unknown error'}`;
+    }
+    // Prefix with no-effect warning when the action succeeded but nothing visibly changed.
+    // This helps the model detect when its action didn't produce the intended result
+    // and avoid retrying the same ineffective approach (Anthropic best practice).
+    const noEffectPrefix = execResult.stateChanged === false && name !== 'wait' && name !== 'note' && name !== 'begin_subgoal'
+        ? 'NO_EFFECT: '
+        : '';
+    // Enrich result with element label when clicking by index
+    if ((name === 'click' || name === 'type_text' || name === 'select_option' || name === 'scroll') && args.index !== undefined) {
+        const el = elements.find(e => e.index === args.index);
+        const label = el ? (el.text || el.ariaLabel || el.inputType || el.tag) : '';
+        const labelStr = label ? ` "${label}"` : '';
+        return execResult.outcome
+            ? `${noEffectPrefix}[${args.index}]${labelStr}: ${execResult.outcome}`
+            : `${noEffectPrefix}[${args.index}]${labelStr}: ok`;
+    }
+    return `${noEffectPrefix}${execResult.outcome || 'ok'}`;
+}
+async function callPlanner(client, prompt, url, firstScreenshot, options) {
+    try {
+        const isReplanning = (options.completedMilestones ?? 0) > 0;
+        const systemContent = isReplanning
+            ? `You are a web navigation planner. Given a screenshot of the current page and a goal, output the REMAINING steps (3–5 steps) needed to complete the workflow. ${options.completedMilestones} milestone(s) have already been captured. Focus on what still needs to be done. Never propose blocked actions such as "Continue with AI", AI/generate/create buttons, logout/sign out, billing/purchase flows, save/submit/publish actions, or other account-changing/destructive steps unless the goal explicitly is the login screen. No preamble — just the numbered steps.`
+            : 'You are a web navigation planner. Given a screenshot of the starting page and a goal, output a concise numbered action plan (3–7 steps) to achieve the goal. This plan is a rough guide — the agent will adapt if the actual page differs from expectations. Be specific about what to click or navigate, but acknowledge that labels and layouts may differ. Never propose blocked actions such as "Continue with AI", AI/generate/create buttons, logout/sign out, billing/purchase flows, save/submit/publish actions, or other account-changing/destructive steps unless the goal explicitly is the login screen. No preamble — just the numbered steps.';
+        const userGuidanceText = options.userGuidance && options.userGuidance.length > 0
+            ? `\n\n⚠️ USER OVERRIDE — the operator has provided explicit guidance that MUST take priority over any previous plan:\n${options.userGuidance.map((g, i) => `  ${i + 1}. ${g}`).join('\n')}\nYour new plan MUST follow this guidance. If the guidance contradicts the previous plan, discard the previous plan entirely.`
+            : '';
+        const failedAttemptsText = options.failedAttemptsSummary
+            ? `\n\n⚠️ PREVIOUS ATTEMPTS FAILED — the agent already tried these approaches and they did NOT work:\n${options.failedAttemptsSummary}\nDo NOT repeat these failed approaches. The agent may be on the WRONG PAGE — check if navigating to a different section/page is needed first.`
+            : '';
+        const goalText = `Goal: ${prompt}\nCurrent URL: ${url}${options.lang ? `\nTarget language: ${options.lang}` : ''}${options.theme ? `\nTarget theme: ${options.theme}` : ''}${options.currentObjective ? `\nCurrent objective: ${options.currentObjective}` : ''}${options.captureCursorSummary ? `\nCapture cursor: ${options.captureCursorSummary}` : ''}${options.remainingCaptureQueue && options.remainingCaptureQueue.length > 0 ? `\nRemaining capture queue: ${options.remainingCaptureQueue.join(', ')}` : ''}${options.repairTicketSummary ? `\nActive repair ticket: ${options.repairTicketSummary}\nUse repair steps only to unblock the current cursor, then resume the same capture.` : ''}${options.authState === 'authenticated' ? '\nAuthenticated browser state is already active. Do NOT plan login, OAuth, or sign-in steps again unless the explicit goal is the login screen or the screenshot clearly shows a login screen.' : ''}${options.handoffContextSummary ? `\nLive handoff context: ${options.handoffContextSummary}\nContinue from the carried-over page state before deciding to navigate.` : ''}${options.handoffNavigationHints && options.handoffNavigationHints.length > 0 ? `\nLikely next controls from the carried-over state: ${options.handoffNavigationHints.join(' | ')}` : ''}${options.variantManifestSummary ? `\nVariant manifest: ${options.variantManifestSummary}\nThe next steps must satisfy the current page id specifically and avoid duplicating already completed pages.` : ''}${failedAttemptsText}${userGuidanceText}\nForbidden planning actions: Continue with AI, generate/create with AI, logout/sign out, billing/purchase, save/submit/publish, or other mutating/account-changing steps unless the explicit goal is the login screen.\nIf a blocked control is visible, plan the safe alternative route instead.\n\nWrite the ${isReplanning ? 'remaining' : 'numbered action'} plan.`;
+        // Dual-model mode: use cheap vision model to describe the page, then text-only primary model
+        if (options.visionModel) {
+            const screenshotUrl = await makeImageUrl(firstScreenshot, 'image/jpeg', options.uploadImage);
+            const observerMessages = [
+                { role: 'system', content: 'You are a page state observer. Describe the current page layout, visible elements, and navigation options concisely. Focus on what a planner needs to know to navigate the page.' },
+                { role: 'user', content: [
+                        { type: 'image_url', image_url: { url: screenshotUrl } },
+                        { type: 'text', text: `Describe this page for a navigation planner. URL: ${url}` },
+                    ] },
+            ];
+            const observerResult = await client.chat.completions.create({ model: options.visionModel, messages: observerMessages, max_tokens: 300, stream: false, ...providerBody(options.visionModel, options.providerPreferences) }, { signal: options.signal });
+            const observation = observerResult.choices?.[0]?.message?.content?.trim() ?? '';
+            const observerUsage = extractUsage(observerResult, options.stepCounter ?? 0, 'agent_iteration', options.visionModel, 1);
+            const planningMessages = [
+                { role: 'system', content: systemContent },
+                { role: 'user', content: `Page observation:\n${observation}\n\n${goalText}` },
+            ];
+            const planResult = await client.chat.completions.create({ model: options.model, messages: planningMessages, max_tokens: 256, ...providerBody(options.model, options.providerPreferences) }, { signal: options.signal });
+            const plan = planResult.choices?.[0]?.message?.content?.trim() ?? null;
+            const planUsage = extractUsage(planResult, (options.stepCounter ?? 0) + 1, 'agent_iteration', options.model, 0);
+            // Return the primary model's usage; observer usage is tracked separately via usageLog at the call site
+            return { plan, usage: planUsage ?? observerUsage, model: options.model };
+        }
+        // Mono-model mode: send image directly to the primary model (with vision fallback)
+        const screenshotUrl = await makeImageUrl(firstScreenshot, 'image/jpeg', options.uploadImage);
+        const planningMessages = [
+            {
+                role: 'system',
+                content: systemContent,
+            },
+            {
+                role: 'user',
+                content: [
+                    { type: 'image_url', image_url: { url: screenshotUrl } },
+                    { type: 'text', text: goalText },
+                ],
+            },
+        ];
+        const plannerResult = await callVisionCapableModel({
+            primaryModel: options.model,
+            fallbackModel: options.fallbackModel,
+            onFallbackActivated: (m, reason) => logger.debug(`Planning vision fallback activated: ${m} (reason: ${reason})`),
+            callModel: (model) => client.chat.completions.create({
+                model,
+                messages: planningMessages,
+                max_tokens: 256,
+                ...providerBody(model, options.providerPreferences),
+            }, { signal: options.signal }),
+        });
+        const plan = plannerResult.result.choices?.[0]?.message?.content?.trim() ?? null;
+        const usage = extractUsage(plannerResult.result, options.stepCounter ?? 0, 'agent_iteration', plannerResult.model, 1);
+        return { plan, usage, model: plannerResult.model };
+    }
+    catch (err) {
+        if (!isAbortError(err)) {
+            const modelTried = options.fallbackModel
+                ? `${options.model} → ${options.fallbackModel}`
+                : options.model;
+            logger.debug(`Planning call failed (non-fatal) [${modelTried}]: ${err.message}`);
+        }
+        return { plan: null, usage: null };
+    }
+}
+function resolveActionOrigin(config) {
+    if (config.runMode === 'language_preflight')
+        return 'preflight';
+    if (config.runMode === 'repair' || config.currentObjective === 'repair')
+        return 'repair_subplan';
+    return 'main_plan';
+}
+function appendActionHistory(actionHistory, config, action) {
+    actionHistory.push({
+        ...action,
+        origin: action.origin ?? resolveActionOrigin(config),
+        phase: action.phase ?? config.captureCursor?.phase,
+        checkpointId: action.checkpointId !== undefined
+            ? action.checkpointId
+            : config.captureCursor?.lastVerifiedCheckpointId ?? null,
+    });
+}
+/**
+ * Build a compact trajectory log from action history.
+ * Re-injected every iteration to preserve action context across conversation trimming.
+ * Format: +* iter: action [index] "reason"  (+ success, - fail, * state changed)
+ * Capped at the last 30 actions to avoid unbounded token growth.
+ * Meta-actions (note, begin_subgoal) are rendered compactly to reduce noise.
+ */
+/**
+ * Module-level cache so the OpenRouter model list is fetched at most once per process.
+ * key = model id, value = supports cache_control
+ */
+const cachingCapabilityCache = new Map();
+/**
+ * Checks whether a model supports explicit prompt caching via cache_control by
+ * inspecting its `pricing.input_cache_read` field in the OpenRouter models API.
+ * Results are memoised for the lifetime of the process.
+ */
+async function modelSupportsCaching(model, apiKey) {
+    if (cachingCapabilityCache.has(model))
+        return cachingCapabilityCache.get(model);
+    try {
+        const res = await fetch('https://openrouter.ai/api/v1/models', {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const body = await res.json();
+        for (const m of body.data ?? []) {
+            const supported = Number(m.pricing?.input_cache_read ?? 0) > 0;
+            cachingCapabilityCache.set(m.id, supported);
+        }
+        return cachingCapabilityCache.get(model) ?? false;
+    }
+    catch (err) {
+        logger.info(`Could not detect caching support for ${model}: ${err.message}. Disabling cache_control.`);
+        return false;
+    }
+}
+function buildTrajectoryLog(actionHistory) {
+    if (actionHistory.length === 0)
+        return '';
+    return actionHistory.slice(-25).map(a => {
+        const status = a.success ? '+' : '-';
+        const changed = a.stateChanged ? '*' : ' ';
+        // Meta-actions: show their name/content inline without index/reason noise
+        if (a.action === 'begin_subgoal')
+            return `   ${a.iteration}: [subgoal: ${String(a.params.name ?? '').slice(0, 30)}]`;
+        if (a.action === 'note')
+            return `   ${a.iteration}: [note]`;
+        const target = a.params.index !== undefined ? ` [${a.params.index}]` : '';
+        const reason = a.params.reason ? ` "${String(a.params.reason).slice(0, 30)}"` : '';
+        return `${status}${changed} ${a.iteration}: ${a.action}${target}${reason}`;
+    }).join('\n');
+}
+/**
+ * Build a compact summary of recent failed/no-effect actions for the planner.
+ * Helps the planner understand what was already tried so it doesn't repeat the same mistakes.
+ */
+function buildFailedAttemptsSummary(actionHistory) {
+    const recent = actionHistory.slice(-12);
+    const failed = recent.filter(a => !a.success || a.stateChanged === false).filter(a => a.action !== 'note' && a.action !== 'begin_subgoal' && a.action !== 'wait');
+    if (failed.length === 0)
+        return undefined;
+    return failed.map(a => {
+        const target = a.params.elementLabel
+            ? `"${String(a.params.elementLabel).slice(0, 40)}"`
+            : a.params.index !== undefined
+                ? `[${a.params.index}]`
+                : a.params.query
+                    ? `"${String(a.params.query).slice(0, 40)}"`
+                    : '';
+        const outcome = !a.success
+            ? `FAILED: ${(a.error || 'unknown').slice(0, 60)}`
+            : 'NO EFFECT';
+        return `- ${a.action} ${target} → ${outcome}`;
+    }).join('\n');
+}
+/**
+ * Call a cheap vision model to extract a structured text observation from a screenshot.
+ * Used in dual-model mode: the vision model describes the page, the text model reasons.
+ * Returns a concise text description (~200-300 tokens) that replaces images in the main context.
+ */
+async function callVisionObserver(client, visionModel, screenshot, pageState, config, stepCounter) {
+    const screenshotUrl = await makeImageUrl(screenshot, 'image/jpeg', config.uploadImage);
+    const messages = [
+        {
+            role: 'system',
+            content: 'You are a page state observer for a web navigation agent. Describe the current page concisely and factually. Output ONLY the structured observation — no commentary.',
+        },
+        {
+            role: 'user',
+            content: buildVisionObserverPrompt({
+                screenshotUrl,
+                currentUrl: config.url,
+                interactiveElements: pageState.interactiveElements,
+                userGoal: config.prompt,
+                currentLang: config.currentLang,
+                currentTheme: config.currentTheme,
+                currentPageId: config.variantManifest?.currentPageId ?? undefined,
+                pageIdentitySummary: config.variantManifest?.currentPageIdentity?.summary ?? undefined,
+                currentObjective: config.currentObjective,
+            }),
+        },
+    ];
+    try {
+        const result = await client.chat.completions.create({ model: visionModel, messages, max_tokens: 300, stream: false, ...providerBody(visionModel, config.providerPreferences) }, { signal: config.abortSignal });
+        const content = result.choices?.[0]?.message?.content?.trim() ?? '';
+        const usage = extractUsage(result, stepCounter, 'agent_iteration', visionModel, 1);
+        return { observation: content, usage };
+    }
+    catch (err) {
+        if (isAbortError(err))
+            throw err;
+        logger.error(`Vision observer call failed: ${err.message}`);
+        return { observation: '', usage: null };
+    }
+}
+export async function runAgent(browser, config, apiKey) {
+    const client = createClient(apiKey);
+    const modelState = { active: config.model };
+    const actionHistory = [];
+    const workflowScreenshots = [];
+    const usageLog = [];
+    let stepCounter = 0;
+    const hasCredentials = !!(config.credentials?.email || config.credentials?.password);
+    let usedDeterministicRecovery = false;
+    const userGuidanceMessages = [];
+    let lastVerificationFailure;
+    let lastVerificationResult;
+    let consecutiveDialogFailures = 0;
+    let consecutiveVerificationFailures = 0;
+    let consecutiveTechnicalVerificationFailures = 0;
+    let rejectedGiveUps = 0;
+    let lastReplanIteration = 0; // Cooldown: skip replanning if we just replanned
+    // Working memory: persistent notes stored by the agent via the `note` tool
+    // Re-injected into every prompt to survive conversation trimming (Agent-E / HiAgent pattern)
+    const agentNotes = [];
+    // Hierarchical working memory (HiAgent pattern):
+    // Subgoals organize notes into named phases; completed subgoals are archived as 1-line summaries
+    let currentSubgoal = null;
+    const completedSubgoals = [];
+    // AWM within-run: cache of selectors that worked per subgoal for cross-subgoal hints
+    const workflowCache = [];
+    // Index in actionHistory where the current subgoal started (for scoped AWM extraction)
+    let subgoalStartIndex = 0;
+    // Screenshot hash history for visual loop detection
+    // Tracks MD5 hashes of recent screenshots to detect when the agent is stuck on the same page
+    const screenshotHashHistory = [];
+    // Multi-turn conversation thread — persisted across all iterations
+    // The LLM naturally sees its own history without us reconstructing context each time
+    const cacheLayoutV2Enabled = process.env.SCREENSHOT_AGENT_CACHE_LAYOUT_V2 === '1';
+    const promptCacheStrategy = resolvePromptCacheStrategy(config.model, {
+        enableGeminiExplicitBreakpoints: process.env.SCREENSHOT_AGENT_GEMINI_EXPLICIT_CACHE_BREAKPOINTS === '1',
+    });
+    const systemPromptText = buildSystemPrompt({ reasoningLocale: config.reasoningLocale });
+    const supportsCache = promptCacheStrategy === 'explicit_breakpoints'
+        && await modelSupportsCaching(config.model, apiKey);
+    const systemMessage = supportsCache
+        ? {
+            role: 'system',
+            content: [{ type: 'text', text: systemPromptText, cache_control: { type: 'ephemeral' } }],
+        }
+        : { role: 'system', content: systemPromptText };
+    const conversationMessages = [systemMessage];
+    if (hasManualMultiProviderOrder(config.providerPreferences?.[config.model])) {
+        logger.info(`[cache] ${config.model} uses a multi-provider provider.order override; OpenRouter sticky prompt caching may be reduced.`);
+    }
+    // Pre-loop planning: take an initial screenshot and generate a step-by-step plan
+    // This gives the agent direction before it starts acting, reducing aimless exploration.
+    // Skip planning when the agent is already on the target URL — the capture-first rule
+    // will make it call ready_to_capture immediately, so planning is wasted.
+    const currentUrl = browser.currentPage.url();
+    const alreadyOnTarget = urlsRoughlyMatch(config.url, currentUrl);
+    const planningScreenshot = alreadyOnTarget ? null : await browser.takeScreenshotForAI().catch(() => null);
+    let taskPlan = null;
+    if (planningScreenshot) {
+        const plannerResult = await callPlanner(client, config.prompt, currentUrl, planningScreenshot, {
+            model: modelState.active,
+            fallbackModel: config.fallbackModel,
+            visionModel: config.visionModel,
+            lang: config.currentLang,
+            theme: config.currentTheme,
+            currentObjective: config.currentObjective,
+            captureCursorSummary: summarizeCaptureCursorForPlanner(config),
+            repairTicketSummary: summarizeRepairTicketForPlanner(config),
+            remainingCaptureQueue: config.remainingCaptureQueue,
+            authState: config.handoffContext?.authState ?? config.sessionProfile?.authState,
+            handoffContextSummary: config.handoffContext?.summary,
+            handoffNavigationHints: config.handoffContext?.navigationHints,
+            variantManifestSummary: summarizeVariantManifestForPlanner(config.variantManifest),
+            signal: config.abortSignal,
+            uploadImage: config.uploadImage,
+            stepCounter: ++stepCounter,
+            providerPreferences: config.providerPreferences,
+        });
+        taskPlan = plannerResult.plan;
+        if (plannerResult.usage)
+            usageLog.push(plannerResult.usage);
+        if (plannerResult.model && plannerResult.model !== modelState.active) {
+            modelState.active = plannerResult.model;
+        }
+        if (taskPlan) {
+            logger.info(`Task plan generated:\n${taskPlan}`);
+        }
+    }
+    if (cacheLayoutV2Enabled) {
+        const anchorPrompt = buildStableAnchorUserMessage({
+            userPrompt: config.prompt,
+            credentials: config.credentials,
+            currentLang: config.currentLang,
+            currentTheme: config.currentTheme,
+            langInstructions: config.langInstructions,
+            themeInstructions: config.themeInstructions,
+            viewports: config.viewports,
+            runHints: config.runHints,
+            selectorMemory: config.selectorMemory,
+            sessionProfile: config.sessionProfile,
+            handoffContext: config.handoffContext,
+            variantManifest: config.variantManifest,
+        });
+        // Mark the last content part of the anchor with cache_control so Anthropic's
+        // prompt caching covers both the system message and the stable anchor.
+        const anchorContent = supportsCache
+            ? anchorPrompt.content.map((part, idx, arr) => idx === arr.length - 1 && part.type === 'text'
+                ? { ...part, cache_control: { type: 'ephemeral' } }
+                : part)
+            : anchorPrompt.content;
+        conversationMessages.push({ role: 'user', content: anchorContent });
+    }
+    // DOM fingerprint tracking: skip sending full DOM when page hasn't changed
+    let lastDomFingerprint = null;
+    for (let iteration = 1; iteration <= config.maxIterations; iteration++) {
+        throwIfAborted(config.abortSignal, 'Agent run cancelled.');
+        // Check for user guidance (pause & guide)
+        let guidanceReceivedThisIteration = false;
+        if (config.guidanceCallback) {
+            const guidance = await config.guidanceCallback();
+            if (guidance) {
+                logger.info(`Indication reçue : ${guidance}`);
+                userGuidanceMessages.push(guidance);
+                guidanceReceivedThisIteration = true;
+            }
+        }
+        // 1. Capture current page state
+        // Pre-compute whether vision will likely be auto-triggered this iteration.
+        // When vision is not needed, skip the expensive SoM annotation (sharp compositing).
+        const preNoEffectCount = countRecentNoEffectActions(actionHistory);
+        const likelyNeedsVision = preNoEffectCount >= 2 || (preNoEffectCount >= 1 && screenshotHashHistory.length >= 3);
+        const pageState = await browser.getPageState({ skipAnnotation: !likelyNeedsVision });
+        // Stream live screenshot to the web UI
+        emitScreenshot(getLivePreviewScreenshot(pageState).toString('base64'));
+        // Visual loop detection: track screenshot hashes to detect when the agent is stuck.
+        // Use a larger sample (first 32KB) for more robust detection — small samples miss
+        // subtle layout differences while being too sensitive to viewport size changes.
+        const sampleSize = Math.min(32768, pageState.screenshot.length);
+        const screenshotHash = createHash('md5').update(pageState.screenshot.subarray(0, sampleSize)).digest('hex');
+        // Also track a URL-based hash to catch navigation loops where the page content
+        // is near-identical but the viewport or minor rendering differences change the image hash.
+        const urlHash = createHash('md5').update(browser.currentPage.url()).digest('hex').slice(0, 8);
+        const compositeKey = `${urlHash}:${screenshotHash}`;
+        screenshotHashHistory.push(compositeKey);
+        if (screenshotHashHistory.length > 8)
+            screenshotHashHistory.shift();
+        const hashOccurrences = screenshotHashHistory.filter(h => h === compositeKey).length;
+        // Also check URL-only loops: same URL appearing 4+ times indicates stuck navigation
+        const urlOccurrences = screenshotHashHistory.filter(h => h.startsWith(urlHash + ':')).length;
+        const isVisualLoop = hashOccurrences >= 3 || urlOccurrences >= 5;
+        // Deterministic session repair when stuck (fast, no LLM cost)
+        if (config.enableDeterministicRecovery !== false && shouldTriggerRecovery(actionHistory) && config.selectorMemory) {
+            logger.info('Tentative de récupération automatique…');
+            const repair = await performDeterministicSessionRepair(browser, {
+                startUrl: config.url,
+                requestedLang: config.currentLang,
+                requestedTheme: config.currentTheme,
+                credentials: config.credentials,
+                profile: config.sessionProfile,
+                selectorMemory: config.selectorMemory,
+            }).catch(() => null);
+            if (repair?.repaired) {
+                usedDeterministicRecovery = true;
+                const outcome = `Deterministic recovery succeeded via ${repair.pathUsed ?? 'selector memory'}.`;
+                appendActionHistory(actionHistory, config, {
+                    iteration,
+                    action: 'wait',
+                    params: { reason: 'deterministic_repair' },
+                    success: true,
+                    outcome,
+                    stateChanged: true,
+                    origin: 'deterministic',
+                    phase: 'recover',
+                });
+                logger.success('Récupération automatique réussie');
+                continue;
+            }
+            if (repair?.pathUsed)
+                usedDeterministicRecovery = true;
+        }
+        // Dynamic replanning: triggered by stuck detection OR user guidance.
+        // User guidance bypasses the cooldown and immediately forces a replan so the
+        // agent does not waste iterations following an obsolete plan.
+        const replanCooldownMet = iteration - lastReplanIteration >= 3;
+        const isStuckEnoughToReplan = countRecentNoEffectActions(actionHistory) >= 3;
+        const shouldReplan = guidanceReceivedThisIteration
+            || (replanCooldownMet && (isVisualLoop || (isStuckEnoughToReplan && iteration > 3)));
+        if (shouldReplan) {
+            lastReplanIteration = iteration;
+            logger.info('Régénération du plan d\'action…');
+            const replanScreenshot = await browser.takeScreenshot();
+            const stuckReplan = await callPlanner(client, config.prompt, browser.currentPage.url(), replanScreenshot, {
+                model: modelState.active,
+                fallbackModel: config.fallbackModel,
+                visionModel: config.visionModel,
+                lang: config.currentLang,
+                theme: config.currentTheme,
+                currentObjective: config.currentObjective,
+                captureCursorSummary: summarizeCaptureCursorForPlanner(config),
+                repairTicketSummary: summarizeRepairTicketForPlanner(config),
+                remainingCaptureQueue: config.remainingCaptureQueue,
+                variantManifestSummary: summarizeVariantManifestForPlanner(config.variantManifest),
+                completedMilestones: workflowScreenshots.length || 1,
+                signal: config.abortSignal,
+                uploadImage: config.uploadImage,
+                stepCounter: ++stepCounter,
+                providerPreferences: config.providerPreferences,
+                userGuidance: userGuidanceMessages.length > 0 ? userGuidanceMessages : undefined,
+                failedAttemptsSummary: buildFailedAttemptsSummary(actionHistory),
+            }).catch(() => ({ plan: null, usage: null }));
+            if (stuckReplan.usage)
+                usageLog.push(stuckReplan.usage);
+            if (stuckReplan.model && stuckReplan.model !== modelState.active) {
+                modelState.active = stuckReplan.model;
+            }
+            if (stuckReplan.plan) {
+                taskPlan = stuckReplan.plan;
+                logger.info(`Nouveau plan d'action :\n${stuckReplan.plan}`);
+            }
+        }
+        // 2. Build observation and add to conversation thread
+        // First iteration: includes full task context (prompt, session, memory, instructions)
+        // Subsequent iterations: compact page-state-only observation
+        //
+        // Dual-model mode: when visionModel is set, call the cheap vision model to extract
+        // a text observation, then pass that to the main text model (no images in main context).
+        // Mono-model mode: send images directly as before.
+        // DOM-first: the main model receives the simplified DOM as primary context.
+        // Vision analysis is available on-demand via the analyze_screenshot tool.
+        // Auto-trigger: inject a vision observation when the agent is genuinely stuck.
+        // Only fires on repeated no-effect actions or visual loops — NOT on every iteration
+        // after a verification failure (lastVerificationFailure is already in the text context).
+        // Skip vision when a replan or user guidance just happened — the agent has fresh direction.
+        let visionObservationText;
+        const noEffectCount = countRecentNoEffectActions(actionHistory);
+        const justReplanned = shouldReplan; // replan happened this iteration — let the agent try the new plan first
+        const shouldAutoTriggerVision = !justReplanned
+            && !guidanceReceivedThisIteration
+            && (noEffectCount >= 2 || (isVisualLoop && noEffectCount >= 1));
+        if (shouldAutoTriggerVision) {
+            const visionModel = config.visionModel || modelState.active;
+            logger.info('Analyse visuelle de la page…');
+            const visionResult = await callVisionObserver(client, visionModel, pageState.screenshot, pageState, config, ++stepCounter);
+            if (visionResult.usage)
+                usageLog.push(visionResult.usage);
+            visionObservationText = visionResult.observation || undefined;
+            if (visionObservationText) {
+                logger.debug(`Auto-triggered vision (stuck=${noEffectCount}, visualLoop=${isVisualLoop}, verifyFail=${!!lastVerificationFailure}): ${visionObservationText.slice(0, 200)}`);
+                // If vision says the page matches the target and we're stuck, add a strong capture hint
+                const matchLine = visionObservationText.split('\n').find(l => /^MATCH:/i.test(l.trim()));
+                if (matchLine && /\b(yes|oui)\b/i.test(matchLine) && (noEffectCount >= 2 || isVisualLoop)) {
+                    visionObservationText += config.runMode === 'video_navigation_preflight'
+                        ? '\n\n⚠️ VISION SUGGESTS THE PAGE IS CLOSE TO THE GOAL. Before calling ready_to_capture, confirm that the EXACT pre-recording start state is visible now: the requested project/section/dialog must already be open, and the recorded interaction must not be done yet.'
+                        : '\n\n⚠️ VISION CONFIRMS PAGE MATCHES TARGET. You are stuck clicking without progress. Call ready_to_capture NOW — the current state is likely what you need to capture.';
+                }
+            }
+        }
+        // DOM-first: skip images in the main iteration prompt.
+        // The simplified DOM + interactive elements provide page context.
+        // Vision is available on-demand via analyze_screenshot tool.
+        const screenshotUrl = undefined;
+        const cleanScreenshotUrl = undefined;
+        // DOM skip: compute triple fingerprint (DOM + element count + current URL).
+        // If identical to last iteration, send a compact placeholder instead of full DOM.
+        // Safety net: always send full DOM on iteration 1, every 4th iteration, and when stuck.
+        const currentDomFingerprint = createHash('sha1')
+            .update(pageState.simplifiedDOM || '')
+            .update(String(pageState.interactiveElements.length))
+            .update(browser.currentPage.url())
+            .digest('hex');
+        const noEffectCountForDom = countRecentNoEffectActions(actionHistory);
+        const domUnchanged = iteration > 1
+            && iteration % 4 !== 0
+            && noEffectCountForDom === 0
+            && lastDomFingerprint !== null
+            && currentDomFingerprint === lastDomFingerprint;
+        lastDomFingerprint = currentDomFingerprint;
+        const iterationPrompt = buildIterationUserMessage({
+            userPrompt: config.prompt,
+            cleanScreenshotUrl,
+            screenshotUrl: screenshotUrl || '',
+            visionObservation: visionObservationText,
+            simplifiedDOM: domUnchanged ? undefined : (pageState.simplifiedDOM || undefined),
+            domUnchanged,
+            accessibilityTree: pageState.accessibilityTree,
+            interactiveElements: pageState.interactiveElements,
+            screenshotsTaken: workflowScreenshots,
+            iteration,
+            maxIterations: config.maxIterations,
+            credentials: config.credentials,
+            currentLang: config.currentLang,
+            currentTheme: config.currentTheme,
+            langInstructions: config.langInstructions,
+            themeInstructions: config.themeInstructions,
+            viewports: config.viewports,
+            runHints: config.runHints,
+            selectorMemory: config.selectorMemory,
+            sessionProfile: config.sessionProfile,
+            hasCredentials,
+            salienceCompressionEnabled: config.enableSalienceCompression !== false,
+            viewport: browser.currentPage.viewportSize() ?? config.viewport,
+            currentUrl: browser.currentPage.url(),
+            scrollInfo: pageState.scrollInfo,
+            agentNotes: agentNotes.length > 0 ? [...agentNotes] : undefined,
+            currentSubgoal: currentSubgoal ?? undefined,
+            completedSubgoals: completedSubgoals.length > 0 ? [...completedSubgoals] : undefined,
+            trajectoryLog: buildTrajectoryLog(actionHistory) || undefined,
+            handoffContext: iteration <= 3 ? config.handoffContext : undefined,
+            variantManifest: config.variantManifest,
+            variantReference: config.variantReference,
+            currentObjective: config.currentObjective,
+            captureCursor: config.captureCursor,
+            activeRepairTicket: config.activeRepairTicket,
+            remainingCaptureQueue: config.remainingCaptureQueue,
+            stuckLoopWarning: (shouldTriggerRecovery(actionHistory) || isVisualLoop)
+                ? (() => {
+                    const currentPageUrl = browser.currentPage.url();
+                    const targetUrl = config.url;
+                    // Detect wrong-page: if current URL path is completely different from target,
+                    // the agent is likely on the wrong page and needs to navigate first.
+                    let wrongPageHint = '';
+                    try {
+                        const currentPath = new URL(currentPageUrl).pathname;
+                        const targetPath = new URL(targetUrl).pathname;
+                        // If paths share no common segments beyond '/', flag it
+                        const currentSegments = currentPath.split('/').filter(Boolean);
+                        const targetSegments = targetPath.split('/').filter(Boolean);
+                        const commonSegments = currentSegments.filter(s => targetSegments.includes(s));
+                        if (currentSegments.length > 0 && targetSegments.length > 0 && commonSegments.length === 0) {
+                            wrongPageHint = ` ⚠️ WRONG PAGE: you are on ${currentPath} but the target is ${targetPath}. Navigate to the correct page FIRST before trying to interact with elements.`;
+                        }
+                    }
+                    catch { /* ignore URL parse errors */ }
+                    if (config.runMode === 'video_navigation_preflight') {
+                        return `STUCK: recent actions were ineffective${isVisualLoop ? ' (page appears visually unchanged)' : ''}.${wrongPageHint} BEFORE trying more actions, CHECK: is the browser on the EXACT pre-recording start state? The requested project/section/dialog must already be open, and the recorded interaction must not have been executed yet. Only then call ready_to_capture. Otherwise, continue the missing preparation step.`;
+                    }
+                    return `STUCK: recent actions were ineffective${isVisualLoop ? ' (page appears visually unchanged)' : ''}.${wrongPageHint} BEFORE trying more actions, CHECK: does the current page state ALREADY match the capture target? If a modal/panel/overlay is open that matches what you need to capture, call ready_to_capture NOW instead of clicking more things. If not, close any open dropdown/popover (press Escape) and try a completely different approach.`;
+                })()
+                : undefined,
+            taskPlan: taskPlan ?? undefined,
+            lastVerificationFailure,
+            userGuidance: userGuidanceMessages.length > 0 ? [...userGuidanceMessages] : undefined,
+            expansionLevel: Math.min(3, Math.max(0, countRecentNoEffectActions(actionHistory) - 1)),
+            isFirstIteration: iteration === 1,
+            cacheLayoutV2: cacheLayoutV2Enabled,
+            failedAttemptsSummary: buildFailedAttemptsSummary(actionHistory),
+        });
+        conversationMessages.push({ role: 'user', content: iterationPrompt.content });
+        // Trim thread to avoid context window overflow
+        trimConversationHistory(conversationMessages, 24, cacheLayoutV2Enabled ? 2 : 1);
+        // 3. Call OpenRouter with full conversation thread
+        let response;
+        try {
+            throwIfAborted(config.abortSignal, 'Agent run cancelled.');
+            const visionResult = await callVisionCapableModel({
+                primaryModel: modelState.active,
+                fallbackModel: modelState.active === config.model ? config.fallbackModel : undefined,
+                onFallbackActivated: (model, reason) => {
+                    modelState.active = model;
+                    logger.debug(`Vision fallback activated: ${model} (reason: ${reason})`);
+                },
+                callModel: (model) => callWithRetry(client, {
+                    model,
+                    messages: conversationMessages,
+                    tools: agentTools,
+                    tool_choice: 'required',
+                    max_tokens: 2048,
+                }, 3, config.abortSignal, config.providerPreferences, config.reasoningEffort),
+            });
+            response = visionResult.result;
+            if (visionResult.model && visionResult.model !== modelState.active) {
+                logger.debug(`OpenRouter model substitution detected: requested "${modelState.active}", got "${visionResult.model}"`);
+            }
+            modelState.active = visionResult.model;
+            const imagesInPrompt = iterationPrompt.content.filter((part) => 'type' in part && part.type === 'image_url').length;
+            const stepUsage = extractUsage(response, ++stepCounter, 'agent_iteration', visionResult.model, imagesInPrompt);
+            const systemContent = conversationMessages[0].content;
+            stepUsage.systemPromptChars = typeof systemContent === 'string' ? systemContent.length : 0;
+            stepUsage.toolSchemaChars = JSON.stringify(agentTools).length;
+            const userContent = iterationPrompt.content;
+            stepUsage.userPayloadChars = Array.isArray(userContent)
+                ? userContent.reduce((sum, part) => sum + ('text' in part && typeof part.text === 'string' ? part.text.length : 0), 0)
+                : typeof userContent === 'string' ? userContent.length : 0;
+            stepUsage.accessibilityChars = pageState.accessibilityTree.length;
+            stepUsage.interactiveElementCount = pageState.interactiveElements.length;
+            stepUsage.actionHistoryCount = actionHistory.length;
+            stepUsage.elementsChars = iterationPrompt.metrics.elementsChars;
+            stepUsage.sessionSummaryChars = iterationPrompt.metrics.sessionSummaryChars;
+            stepUsage.selectorMemoryChars = iterationPrompt.metrics.selectorMemoryChars;
+            stepUsage.agentContextChars = iterationPrompt.metrics.agentContextChars;
+            stepUsage.profileValidationStatus = config.sessionProfile?.validationStatus;
+            stepUsage.repairPathUsed = usedDeterministicRecovery ? 'deterministic_repair' : 'llm_full';
+            usageLog.push(stepUsage);
+            // Log per-iteration cache efficiency so cache behavior is visible in runtime logs.
+            if (stepUsage.cacheReadTokens) {
+                const hitPct = stepUsage.promptTokens
+                    ? Math.round((stepUsage.cacheReadTokens / stepUsage.promptTokens) * 100)
+                    : 0;
+                logger.debug(`[cache] iter ${iteration}: ${stepUsage.cacheReadTokens} cached / ${stepUsage.promptTokens ?? '?'} total (${hitPct}% hit rate)`);
+            }
+            if (stepUsage.reasoningTokens) {
+                logger.debug(`[reasoning] iter ${iteration}: ${stepUsage.reasoningTokens} reasoning tokens`);
+            }
+        }
+        catch (err) {
+            if (isAbortError(err))
+                throw err;
+            logger.error(`API call failed at iteration ${iteration}: ${err.message}`);
+            if (err instanceof VisionModelUnsupportedError) {
+                getPostHog().capture({
+                    distinctId: config.analyticsId ?? DISTINCT_ID,
+                    event: 'agent_gave_up',
+                    properties: {
+                        url: config.url,
+                        model: modelState.active,
+                        theme: config.currentTheme,
+                        lang: config.currentLang,
+                        reason: err.message,
+                        iterations: iteration,
+                        total_tokens: usageLog.reduce((s, u) => s + (u.totalTokens ?? 0), 0),
+                    },
+                });
+                return {
+                    success: false,
+                    screenshotPath: null,
+                    screenshots: workflowScreenshots,
+                    iterations: iteration,
+                    actions: actionHistory,
+                    assessment: err.message,
+                    diagnostic: {
+                        screenshot: pageState.screenshot,
+                        url: browser.currentPage.url(),
+                        interactiveElements: pageState.interactiveElements,
+                        accessibilityTreeSnippet: pageState.accessibilityTree.slice(0, 5000),
+                        giveUpReason: err.message,
+                    },
+                    usage: usageLog,
+                    runtimeStrategy: 'full_llm',
+                    deterministicRecoveryUsed: usedDeterministicRecovery,
+                    evaluatorUsed: false,
+                };
+            }
+            appendActionHistory(actionHistory, config, {
+                iteration,
+                action: 'wait',
+                params: { reason: 'API error' },
+                success: false,
+                error: err.message,
+            });
+            continue;
+        }
+        // 4. Extract tool calls and add assistant message to conversation thread
+        const message = response.choices?.[0]?.message;
+        let toolCalls = message?.tool_calls;
+        const assistantText = extractAssistantText(message?.content);
+        if (assistantText) {
+            logger.ai(assistantText);
+        }
+        // Always add the assistant's response to keep the conversation coherent
+        conversationMessages.push({
+            role: 'assistant',
+            content: message?.content ?? null,
+            tool_calls: toolCalls,
+        });
+        if (!toolCalls || toolCalls.length === 0) {
+            const inferredAction = assistantText ? inferActionFromAssistantText(assistantText) : null;
+            if (inferredAction) {
+                logger.debug(`No tool calls at iteration ${iteration}; inferred ${inferredAction.name} from assistant text.`);
+                toolCalls = [
+                    {
+                        id: `synthetic-${iteration}-0`,
+                        type: 'function',
+                        function: {
+                            name: inferredAction.name,
+                            arguments: JSON.stringify(inferredAction.args),
+                        },
+                    },
+                ];
+            }
+            else {
+                logger.error(`No tool calls at iteration ${iteration}, skipping. Model: ${modelState.active}. Response: ${assistantText?.slice(0, 400) || '(empty)'}`);
+                continue;
+            }
+        }
+        // 5. Execute each tool call and add results to conversation thread
+        for (const toolCall of toolCalls) {
+            throwIfAborted(config.abortSignal, 'Agent run cancelled.');
+            if (!('function' in toolCall))
+                continue;
+            const name = toolCall.function.name;
+            let args;
+            try {
+                args = JSON.parse(toolCall.function.arguments);
+            }
+            catch {
+                logger.error(`Invalid JSON in tool arguments: ${toolCall.function.arguments}`);
+                conversationMessages.push({
+                    role: 'tool',
+                    tool_call_id: toolCall.id,
+                    content: 'ERROR: Invalid JSON in tool arguments.',
+                });
+                continue;
+            }
+            args = resolveActionCredentialArgs(name, args, config.credentials);
+            if (name === 'type_text'
+                && config.credentials?.password
+                && typeof args.text === 'string'
+                && GENERIC_PASSWORD_INPUT_RE.test(args.text.trim())
+                && isPasswordFieldTarget(args, pageState.interactiveElements)) {
+                args.text = config.credentials.password;
+            }
+            // Log the agent's reasoning before executing
+            const reasoning = args.reason || args.reasoning || args.assessment;
+            if (reasoning)
+                logger.ai(reasoning);
+            // Enrich log args with element label
+            const logArgs = sanitizeCredentialParams({ ...args }, config.credentials);
+            delete logArgs.reason;
+            if ((name === 'click' || name === 'type_text' || name === 'select_option' || name === 'scroll') && args.index !== undefined) {
+                const el = pageState.interactiveElements.find(e => e.index === args.index);
+                if (el) {
+                    const label = el.text || el.ariaLabel || el.inputType || el.tag;
+                    if (label)
+                        logArgs.elementLabel = label;
+                }
+            }
+            logger.action(iteration, config.maxIterations, name, logArgs, { lang: config.currentLang, theme: config.currentTheme });
+            // --- begin_subgoal (hierarchical working memory + AWM within-run) ---
+            if (name === 'begin_subgoal') {
+                const subgoalName = String(args.name ?? 'step').slice(0, 40);
+                const progressSummary = String(args.progress_summary ?? '').slice(0, 120);
+                // AWM: extract selectors from the CURRENT subgoal only (scoped by subgoalStartIndex)
+                if (currentSubgoal) {
+                    const successfulSelectors = Array.from(new Set(actionHistory
+                        .slice(subgoalStartIndex)
+                        .filter(a => a.success && a.stateChanged && typeof a.params.selector === 'string')
+                        .map(a => String(a.params.selector)))).slice(0, 8);
+                    if (successfulSelectors.length > 0) {
+                        workflowCache.push({ subgoalName: currentSubgoal, actionSummary: progressSummary, selectors: successfulSelectors });
+                    }
+                    // Archive current subgoal with its summary
+                    if (agentNotes.length > 0 || progressSummary) {
+                        completedSubgoals.push({ name: currentSubgoal, summary: progressSummary || `${agentNotes.length} note(s)` });
+                    }
+                }
+                // Start new subgoal: clear working notes and advance scope index
+                currentSubgoal = subgoalName;
+                agentNotes.length = 0;
+                subgoalStartIndex = actionHistory.length; // scope future AWM extraction to this subgoal
+                // AWM: inject selector hints from a similar past subgoal into the new subgoal's notes
+                const similarWorkflow = findReusableWorkflow(workflowCache, subgoalName);
+                if (similarWorkflow && similarWorkflow.selectors.length > 0) {
+                    agentNotes.push(`Selectors that worked for previous subgoal "${similarWorkflow.subgoalName}": ${similarWorkflow.selectors.slice(0, 4).join(', ')}`);
+                }
+                appendActionHistory(actionHistory, config, { iteration, action: 'begin_subgoal', params: args, success: true, outcome: `subgoal_started:${subgoalName}`, stateChanged: false });
+                conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: `Subgoal "${subgoalName}" started. Working memory cleared.` });
+                continue;
+            }
+            // --- note (working memory) ---
+            if (name === 'note') {
+                const content = String(args.content ?? '').slice(0, 120);
+                agentNotes.push(content);
+                appendActionHistory(actionHistory, config, { iteration, action: 'note', params: args, success: true, outcome: 'note_recorded', stateChanged: false });
+                conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: 'Note recorded.' });
+                continue;
+            }
+            // Element index validation: catch hallucinated indices before browser execution
+            if (['click', 'type_text', 'select_option', 'scroll'].includes(name)
+                && args.index !== undefined
+                && args.selector === undefined) {
+                const idx = args.index;
+                const exists = pageState.interactiveElements.some(el => el.index === idx);
+                if (!exists) {
+                    const visibleIds = pageState.interactiveElements
+                        .filter(el => el.visible)
+                        .slice(0, 12)
+                        .map(el => `[${el.index}]`)
+                        .join(' ');
+                    const msg = `Element [${idx}] not found in current page. Visible: ${visibleIds}. Use search_text to locate by text, or scroll to reach off-screen elements.`;
+                    logger.error(msg);
+                    appendActionHistory(actionHistory, config, { iteration, action: name, params: args, success: false, error: `index_not_found:${idx}`, stateChanged: false });
+                    conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: msg });
+                    continue;
+                }
+            }
+            // Security check
+            const securityDecision = evaluateActionSecurity(name, args, {
+                rootUrl: config.url,
+                currentUrl: browser.currentPage.url(),
+                credentials: config.credentials,
+                interactiveElements: pageState.interactiveElements,
+                currentLang: config.currentLang,
+                currentTheme: config.currentTheme,
+                runMode: config.runMode,
+                currentObjective: config.currentObjective,
+                activeRepairCause: config.activeRepairTicket?.cause ?? null,
+            });
+            if (!securityDecision.allowed) {
+                const targetLabel = describeSecurityTarget(securityDecision.target);
+                const blockMsg = `BLOCKED: ${securityDecision.reason} (${targetLabel})`;
+                logger.error(blockMsg);
+                appendActionHistory(actionHistory, config, { iteration, action: name, params: args, success: false, error: securityDecision.reason });
+                conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: blockMsg });
+                break;
+            }
+            // --- search_text ---
+            if (name === 'search_text') {
+                const query = args.query || '';
+                logger.info(`Recherche de "${query}" sur la page`);
+                const results = await browser.searchText(query);
+                const viewport = browser.currentPage.viewportSize();
+                // Cross-reference search results with interactive elements to provide clickable indices.
+                // When a search result overlaps spatially with an interactive element, include its index
+                // so the agent can `click index=N` instead of using stale coordinates.
+                const interactiveElements = pageState.interactiveElements;
+                const resultText = results.length > 0
+                    ? results.map((r, i) => {
+                        const cx = Math.round(r.boundingBox.x + r.boundingBox.width / 2);
+                        const cy = Math.round(r.boundingBox.y + r.boundingBox.height / 2);
+                        // Find matching interactive element: same selector, or bounding box overlap
+                        const matchingElement = interactiveElements.find(el => {
+                            if (el.selector && r.selector && el.selector === r.selector)
+                                return true;
+                            if (r.container?.selector && el.selector === r.container.selector)
+                                return true;
+                            // Spatial overlap: search result center is inside interactive element bounds
+                            const bb = el.boundingBox;
+                            if (bb) {
+                                return cx >= bb.x && cx <= bb.x + bb.width && cy >= bb.y && cy <= bb.y + bb.height;
+                            }
+                            return false;
+                        });
+                        const indexHint = matchingElement ? ` ⇒ click index=${matchingElement.index}` : '';
+                        const flags = [
+                            r.clickable ? 'clickable' : 'not-clickable',
+                            r.visibilityState === 'full' ? 'fully-visible' : r.visibilityState === 'partial' ? 'partially-visible' : 'off-screen',
+                        ].join(', ');
+                        const hrefInfo = r.href ? ` href="${r.href}"` : '';
+                        const selectorInfo = r.selector ? ` sel="${r.selector}"` : '';
+                        // For off-screen elements, coordinates will be stale after scrolling.
+                        // Guide the agent to scroll first, then use the selector or re-search.
+                        const isOffScreen = r.visibilityState !== 'full' && r.visibilityState !== 'partial';
+                        let scrollHint = '';
+                        if (viewport && r.visibilityState !== 'full') {
+                            if (r.boundingBox.y < 0) {
+                                scrollHint = ` scroll up about ${Math.abs(r.boundingBox.y) + 24}px first`;
+                            }
+                            else if (r.boundingBox.y + r.boundingBox.height > viewport.height) {
+                                const delta = r.boundingBox.y + r.boundingBox.height - Math.max(48, viewport.height - 96);
+                                scrollHint = ` scroll down about ${Math.max(80, Math.round(delta))}px first`;
+                            }
+                        }
+                        const clickTarget = isOffScreen
+                            ? `(${flags})${scrollHint} — after scrolling, use selector="${r.selector}" or re-search to get updated coordinates`
+                            : `→ click x=${cx} y=${cy} (${flags})`;
+                        const containerInfo = r.container
+                            ? `\n     ↳ container: <${r.container.tag}> ${r.container.boundingBox.width}x${r.container.boundingBox.height} (${r.container.reason}) sel="${r.container.selector}"`
+                            : '';
+                        return `  ${i}. <${r.tag}> role="${r.role}" "${r.text}"${hrefInfo}${selectorInfo} ${clickTarget}${indexHint}${containerInfo}`;
+                    }).join('\n')
+                    : '  (no matches found)';
+                logger.debug(`Search results:\n${resultText}`);
+                const searchResult = results.length === 0
+                    ? `No elements found matching "${query}". Try a different search term, or scroll to reveal more content.`
+                    : `Found ${results.length} match(es). For visible elements: click by x/y coordinates or by selector. For off-screen elements: scroll first, then click by selector or re-search.\n${resultText}`;
+                appendActionHistory(actionHistory, config, { iteration, action: 'search_text', params: { query }, success: results.length > 0, error: searchResult });
+                conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: searchResult });
+                break; // Next iteration will show updated page state
+            }
+            if (name === 'analyze_screenshot') {
+                const reason = args.reason || 'visual check';
+                logger.info('Analyse visuelle de la page…');
+                const freshScreenshot = await browser.takeScreenshotForAI();
+                const visionModel = config.visionModel || modelState.active;
+                const visionResult = await callVisionObserver(client, visionModel, freshScreenshot, pageState, config, ++stepCounter);
+                if (visionResult.usage)
+                    usageLog.push(visionResult.usage);
+                const observation = visionResult.observation || 'Unable to analyze screenshot.';
+                logger.debug(`Visual analysis: ${observation.slice(0, 200)}`);
+                appendActionHistory(actionHistory, config, {
+                    iteration, action: 'analyze_screenshot', params: { reason },
+                    success: !!visionResult.observation, outcome: observation.slice(0, 120),
+                });
+                conversationMessages.push({
+                    role: 'tool', tool_call_id: toolCall.id,
+                    content: `Visual analysis:\n${observation}`,
+                });
+                break;
+            }
+            // --- take_screenshot ---
+            if (name === 'take_screenshot') {
+                throwIfAborted(config.abortSignal, 'Agent run cancelled.');
+                const label = args.label || `Screenshot ${workflowScreenshots.length + 1}`;
+                const assessment = args.assessment || '';
+                logger.info(`Prise du screenshot : "${label}"`);
+                const screenshotBuffer = await browser.takeScreenshot();
+                workflowScreenshots.push({ index: workflowScreenshots.length, iteration, label, buffer: screenshotBuffer, path: null });
+                appendActionHistory(actionHistory, config, { iteration, action: 'take_screenshot', params: { label, assessment }, success: true });
+                logger.success(`Screenshot #${workflowScreenshots.length} capturé : "${label}"`);
+                // Dynamic replanning: after each milestone, refine the plan for remaining steps
+                // This is the "soft Planner/Executor split" — the planner re-focuses on what's left
+                const replanResult = await callPlanner(client, config.prompt, browser.currentPage.url(), screenshotBuffer, {
+                    model: modelState.active,
+                    fallbackModel: config.fallbackModel,
+                    visionModel: config.visionModel,
+                    lang: config.currentLang,
+                    theme: config.currentTheme,
+                    currentObjective: config.currentObjective,
+                    captureCursorSummary: summarizeCaptureCursorForPlanner(config),
+                    repairTicketSummary: summarizeRepairTicketForPlanner(config),
+                    remainingCaptureQueue: config.remainingCaptureQueue,
+                    variantManifestSummary: summarizeVariantManifestForPlanner(config.variantManifest),
+                    completedMilestones: workflowScreenshots.length,
+                    signal: config.abortSignal,
+                    uploadImage: config.uploadImage,
+                    stepCounter: ++stepCounter,
+                    providerPreferences: config.providerPreferences,
+                }).catch(() => ({ plan: null, usage: null }));
+                if (replanResult.usage)
+                    usageLog.push(replanResult.usage);
+                if (replanResult.model && replanResult.model !== modelState.active) {
+                    modelState.active = replanResult.model;
+                }
+                if (replanResult.plan) {
+                    taskPlan = replanResult.plan;
+                    logger.info(`Plan affiné après le screenshot #${workflowScreenshots.length} :\n${replanResult.plan}`);
+                }
+                conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: `Workflow screenshot "${label}" captured successfully. Continue with the next step.` });
+                break;
+            }
+            // --- ready_to_capture ---
+            if (name === 'ready_to_capture') {
+                throwIfAborted(config.abortSignal, 'Agent run cancelled.');
+                const assessment = args.assessment || 'Ready';
+                const forceFlag = args.force === true;
+                const expectsDialogTarget = config.variantManifest?.currentPageIdentity?.dialogTarget === true;
+                const expectsGalleryDetail = config.variantManifest?.currentPageIdentity?.kind === 'gallery'
+                    && GALLERY_DETAIL_PROMPT_RE.test(`${config.variantManifest?.currentPageId || ''} ${config.prompt}`.toLowerCase());
+                // Skip the deterministic dialog check when:
+                // 1. The agent explicitly sets force=true (dialog is the intended target)
+                // 2. The dialog check has already failed 2+ times consecutively (auto-bypass to vision)
+                // 3. The current capture intentionally targets a dialog/modal
+                // 4. The gallery prompt expects a detail view (which opens as a dialog)
+                // 5. The run is a language-only preflight
+                const skipDialogCheck = forceFlag
+                    || consecutiveDialogFailures >= 2
+                    || expectsDialogTarget
+                    || expectsGalleryDetail
+                    || config.runMode === 'language_preflight';
+                const verification = await verifyScreenshot(client, config, modelState, browser, assessment, ++stepCounter, {
+                    skipDialogCheck,
+                    allowDeterministicSuccess: !forceFlag && !config.variantManifest?.currentPageId,
+                });
+                const { verified, reason, usage: verifyUsage, fatal } = verification;
+                lastVerificationResult = verification;
+                if (verifyUsage)
+                    usageLog.push(verifyUsage);
+                if (fatal) {
+                    conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: `Verification error: ${reason || 'Fatal error'}` });
+                    return {
+                        success: false, screenshotPath: null, screenshots: workflowScreenshots, iterations: iteration,
+                        actions: actionHistory, assessment: reason || 'Verification failed',
+                        diagnostic: { screenshot: pageState.screenshot, url: browser.currentPage.url(), interactiveElements: pageState.interactiveElements, accessibilityTreeSnippet: pageState.accessibilityTree.slice(0, 5000), giveUpReason: reason || 'Verification failed' },
+                        usage: usageLog, runtimeStrategy: 'full_llm', deterministicRecoveryUsed: usedDeterministicRecovery, evaluatorUsed: false,
+                        verification,
+                    };
+                }
+                if (verified) {
+                    consecutiveDialogFailures = 0;
+                    consecutiveVerificationFailures = 0;
+                    consecutiveTechnicalVerificationFailures = 0;
+                    conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: 'Verification passed. Workflow complete.' });
+                    getPostHog().capture({
+                        distinctId: config.analyticsId ?? DISTINCT_ID,
+                        event: 'agent_run_succeeded',
+                        properties: {
+                            url: config.url, model: modelState.active, theme: config.currentTheme, lang: config.currentLang,
+                            iterations: iteration, workflow_screenshots: workflowScreenshots.length,
+                            total_tokens: usageLog.reduce((s, u) => s + (u.totalTokens ?? 0), 0),
+                            cache_read_tokens: usageLog.reduce((s, u) => s + (u.cacheReadTokens ?? 0), 0),
+                            cache_hit_rate: (() => {
+                                const prompt = usageLog.reduce((s, u) => s + (u.promptTokens ?? 0), 0);
+                                const cached = usageLog.reduce((s, u) => s + (u.cacheReadTokens ?? 0), 0);
+                                return prompt > 0 ? Math.round((cached / prompt) * 100) : 0;
+                            })(),
+                        },
+                    });
+                    return {
+                        success: true, screenshotPath: null, screenshots: workflowScreenshots, iterations: iteration,
+                        actions: actionHistory, assessment, usage: usageLog, runtimeStrategy: 'full_llm',
+                        deterministicRecoveryUsed: usedDeterministicRecovery, evaluatorUsed: false,
+                        verification,
+                    };
+                }
+                lastVerificationFailure = reason || 'Verification failed';
+                consecutiveVerificationFailures++;
+                if (isTechnicalVerificationFailureReason(lastVerificationFailure)) {
+                    consecutiveTechnicalVerificationFailures++;
+                }
+                else {
+                    consecutiveTechnicalVerificationFailures = 0;
+                }
+                // Bail-out: if verification has failed too many times in a row, auto-accept the capture.
+                // This prevents infinite loops when the verification model consistently fails to return
+                // structured decisions despite the page being visually correct.
+                const VERIFICATION_BAILOUT_THRESHOLD = 3;
+                if (consecutiveTechnicalVerificationFailures >= VERIFICATION_BAILOUT_THRESHOLD) {
+                    logger.info('Vérification ignorée après plusieurs échecs techniques — capture acceptée automatiquement.');
+                    consecutiveVerificationFailures = 0;
+                    consecutiveTechnicalVerificationFailures = 0;
+                    consecutiveDialogFailures = 0;
+                    appendActionHistory(actionHistory, config, { iteration, action: 'ready_to_capture', params: args, success: true, outcome: `Auto-accepted after ${VERIFICATION_BAILOUT_THRESHOLD} consecutive verification failures` });
+                    conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: 'Verification passed (bail-out after repeated failures). Workflow complete.' });
+                    return {
+                        success: true, screenshotPath: null, screenshots: workflowScreenshots, iterations: iteration,
+                        actions: actionHistory, assessment, usage: usageLog, runtimeStrategy: 'full_llm',
+                        deterministicRecoveryUsed: usedDeterministicRecovery, evaluatorUsed: false,
+                        verification: { ...verification, verified: true, mode: 'bailout' },
+                    };
+                }
+                // Track consecutive dialog-related failures so we auto-bypass on the next attempt
+                if (reason && reason.includes('Blocking dialog')) {
+                    consecutiveDialogFailures++;
+                }
+                else {
+                    consecutiveDialogFailures = 0;
+                }
+                appendActionHistory(actionHistory, config, { iteration, action: 'ready_to_capture', params: args, success: false, error: `Verification failed: ${lastVerificationFailure}` });
+                const hint = reason && reason.includes('Blocking dialog')
+                    ? ` A dialog/modal is blocking the page. Close it first by pressing Escape or clicking outside. If the dialog/modal IS the intended capture target mentioned in the task, call ready_to_capture again with force=true.`
+                    : verification.duplicateOfPageId
+                        ? ` The current screen duplicates page "${verification.duplicateOfPageId}". Reach the distinct page/state for "${config.variantManifest?.currentPageId ?? 'current'}" before capturing.`
+                        : '';
+                // After 2+ consecutive verification failures, regenerate the plan from current state
+                // so the agent gets fresh direction instead of retrying the same approach.
+                if (consecutiveVerificationFailures === 2 && iteration - lastReplanIteration >= 3) {
+                    lastReplanIteration = iteration;
+                    const replanScreenshot = await browser.takeScreenshot();
+                    const verificationReplan = await callPlanner(client, config.prompt, browser.currentPage.url(), replanScreenshot, {
+                        model: modelState.active,
+                        fallbackModel: config.fallbackModel,
+                        visionModel: config.visionModel,
+                        lang: config.currentLang,
+                        theme: config.currentTheme,
+                        currentObjective: config.currentObjective,
+                        captureCursorSummary: summarizeCaptureCursorForPlanner(config),
+                        remainingCaptureQueue: config.remainingCaptureQueue,
+                        variantManifestSummary: summarizeVariantManifestForPlanner(config.variantManifest),
+                        completedMilestones: workflowScreenshots.length || 1,
+                        signal: config.abortSignal,
+                        uploadImage: config.uploadImage,
+                        stepCounter: ++stepCounter,
+                        providerPreferences: config.providerPreferences,
+                    }).catch(() => ({ plan: null, usage: null }));
+                    if (verificationReplan.usage)
+                        usageLog.push(verificationReplan.usage);
+                    if (verificationReplan.model && verificationReplan.model !== modelState.active) {
+                        modelState.active = verificationReplan.model;
+                    }
+                    if (verificationReplan.plan) {
+                        taskPlan = verificationReplan.plan;
+                        logger.info(`Nouveau plan d'action après échec de vérification :\n${verificationReplan.plan}`);
+                    }
+                }
+                const loopHint = consecutiveTechnicalVerificationFailures >= 2
+                    ? ' IMPORTANT: Verification has failed multiple times due to technical validator issues. If the page is visually correct, you may retry ready_to_capture with force=true.'
+                    : '';
+                conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: `Verification failed: ${lastVerificationFailure}.${hint}${loopHint} Fix the issues (overlays, spinners, wrong page) and call ready_to_capture again.` });
+                break;
+            }
+            // --- give_up ---
+            if (name === 'give_up') {
+                const reason = args.reason || 'Unknown reason';
+                if (config.credentials?.password && HIDDEN_PASSWORD_GIVE_UP_RE.test(reason)) {
+                    const correction = 'The password is available in credentials but intentionally hidden from the prompt. Continue with the email/password login flow.';
+                    logger.debug(`Rejecting incorrect give_up: ${correction}`);
+                    appendActionHistory(actionHistory, config, { iteration, action: 'wait', params: { reason: 'hidden_password_available' }, success: false, error: `INVALID_GIVE_UP: ${reason}. ${correction}` });
+                    conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: `REJECTED: ${correction}` });
+                    break;
+                }
+                const prematureGiveUpCorrection = rejectedGiveUps < 2
+                    ? inferPrematureGiveUpCorrection({
+                        reason,
+                        actionHistory,
+                        lastVerificationFailure,
+                        iteration,
+                        maxIterations: config.maxIterations,
+                    })
+                    : null;
+                if (prematureGiveUpCorrection) {
+                    rejectedGiveUps += 1;
+                    logger.debug(`Rejecting premature give_up: ${prematureGiveUpCorrection}`);
+                    appendActionHistory(actionHistory, config, {
+                        iteration,
+                        action: 'wait',
+                        params: { reason: 'premature_give_up_rejected' },
+                        success: false,
+                        error: `INVALID_GIVE_UP: ${reason}. ${prematureGiveUpCorrection}`,
+                    });
+                    conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: `REJECTED: ${prematureGiveUpCorrection}` });
+                    break;
+                }
+                logger.error(`L'agent a abandonné : ${reason}`);
+                let diagnostic;
+                try {
+                    const diagScreenshot = await browser.takeScreenshot();
+                    diagnostic = { screenshot: diagScreenshot, url: browser.currentPage.url(), interactiveElements: pageState.interactiveElements, accessibilityTreeSnippet: pageState.accessibilityTree.slice(0, 5000), giveUpReason: reason };
+                }
+                catch {
+                    logger.error('Failed to capture diagnostic state');
+                }
+                conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: 'Acknowledged.' });
+                getPostHog().capture({
+                    distinctId: config.analyticsId ?? DISTINCT_ID,
+                    event: 'agent_gave_up',
+                    properties: {
+                        url: config.url, model: modelState.active, theme: config.currentTheme, lang: config.currentLang,
+                        reason, iterations: iteration,
+                        total_tokens: usageLog.reduce((s, u) => s + (u.totalTokens ?? 0), 0),
+                        cache_read_tokens: usageLog.reduce((s, u) => s + (u.cacheReadTokens ?? 0), 0),
+                        cache_hit_rate: (() => {
+                            const prompt = usageLog.reduce((s, u) => s + (u.promptTokens ?? 0), 0);
+                            const cached = usageLog.reduce((s, u) => s + (u.cacheReadTokens ?? 0), 0);
+                            return prompt > 0 ? Math.round((cached / prompt) * 100) : 0;
+                        })(),
+                    },
+                });
+                return {
+                    success: false, screenshotPath: null, screenshots: workflowScreenshots, iterations: iteration,
+                    actions: actionHistory, assessment: reason, diagnostic, usage: usageLog, runtimeStrategy: 'full_llm',
+                    deterministicRecoveryUsed: usedDeterministicRecovery, evaluatorUsed: false,
+                    verification: lastVerificationResult,
+                };
+            }
+            // --- OAuth guard ---
+            if (name === 'click' && hasCredentials) {
+                let blockedText = null;
+                if (args.index !== undefined) {
+                    const targetEl = pageState.interactiveElements.find(el => el.index === args.index);
+                    if (targetEl && isOAuthElement(targetEl))
+                        blockedText = targetEl.text;
+                }
+                if (!blockedText && args.selector) {
+                    const sel = args.selector.toLowerCase();
+                    const oauthEl = pageState.interactiveElements.find(el => isOAuthElement(el) && el.selector.toLowerCase() === sel);
+                    if (oauthEl)
+                        blockedText = oauthEl.text;
+                }
+                if (!blockedText && args.x !== undefined && args.y !== undefined) {
+                    const x = args.x;
+                    const y = args.y;
+                    const oauthEl = pageState.interactiveElements.find(el => {
+                        if (!isOAuthElement(el) || !el.boundingBox)
+                            return false;
+                        const bb = el.boundingBox;
+                        return x >= bb.x && x <= bb.x + bb.width && y >= bb.y && y <= bb.y + bb.height;
+                    });
+                    if (oauthEl)
+                        blockedText = oauthEl.text;
+                }
+                if (blockedText) {
+                    const blockMsg = `BLOCKED: OAuth element "${blockedText}". Look for the email/password login option instead.`;
+                    logger.error(`BLOCKED: click on OAuth element "${blockedText}" — use email login instead`);
+                    appendActionHistory(actionHistory, config, { iteration, action: 'click', params: args, success: false, error: blockMsg });
+                    conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: blockMsg });
+                    break;
+                }
+            }
+            // --- Regular browser actions ---
+            const repeatedActionGuard = inferRepeatedActionGuard({
+                actionHistory,
+                action: name,
+                args,
+                currentUrl: browser.currentPage.url(),
+            });
+            if (repeatedActionGuard) {
+                logger.debug(`Blocking repeated ineffective action: ${name}`);
+                appendActionHistory(actionHistory, config, {
+                    iteration,
+                    action: name,
+                    params: args,
+                    success: false,
+                    error: repeatedActionGuard,
+                    stateChanged: false,
+                });
+                conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: repeatedActionGuard });
+                break;
+            }
+            const execResult = await executeAction(browser, name, args);
+            throwIfAborted(config.abortSignal, 'Agent run cancelled.');
+            // Store in action history (for replay and telemetry)
+            const storedParams = sanitizeCredentialParams({ ...args }, config.credentials);
+            delete storedParams.reason;
+            if (name === 'click' || name === 'type_text' || name === 'select_option' || name === 'scroll') {
+                const resolvedElement = args.index !== undefined
+                    ? pageState.interactiveElements.find((element) => element.index === args.index)
+                    : (args.x !== undefined && args.y !== undefined)
+                        ? findElementForPoint(pageState.interactiveElements, args.x, args.y)
+                        : null;
+                if (resolvedElement) {
+                    if (!containsInternalAutomationSelector(resolvedElement.selector)) {
+                        storedParams.selector = resolvedElement.selector;
+                    }
+                    else {
+                        delete storedParams.selector;
+                    }
+                    if (resolvedElement.href)
+                        storedParams.href = resolvedElement.href;
+                    const label = resolvedElement.text || resolvedElement.ariaLabel || resolvedElement.inputType || resolvedElement.tag;
+                    if (label)
+                        storedParams.elementLabel = label;
+                    // Store structural metadata for cross-language replay matching
+                    storedParams.elementTag = resolvedElement.tag;
+                    storedParams.elementRole = resolvedElement.role;
+                    if (resolvedElement.boundingBox) {
+                        storedParams.elementCx = Math.round(resolvedElement.boundingBox.x + resolvedElement.boundingBox.width / 2);
+                        storedParams.elementCy = Math.round(resolvedElement.boundingBox.y + resolvedElement.boundingBox.height / 2);
+                    }
+                    delete storedParams.index;
+                    delete storedParams.x;
+                    delete storedParams.y;
+                }
+            }
+            // Record URLs for replay validation — allows detecting divergence
+            // when the same actions are replayed in a different language/variant.
+            storedParams.preActionUrl = browser.currentPage.url();
+            if (execResult.success && execResult.stateChanged && (name === 'click' || name === 'navigate_to')) {
+                storedParams.postActionUrl = browser.currentPage.url();
+            }
+            appendActionHistory(actionHistory, config, { iteration, action: name, params: storedParams, success: execResult.success, error: execResult.error, outcome: execResult.outcome, stateChanged: execResult.stateChanged });
+            // Add tool result to conversation thread — this is how the LLM learns what happened
+            const toolResultContent = formatToolResult(name, args, execResult, pageState.interactiveElements);
+            conversationMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: toolResultContent });
+            if (!execResult.success) {
+                logger.error(`Échec de l'action : ${execResult.error}`);
+            }
+            const postActionDelayMs = getPostActionDelayMs(name, execResult, {
+                authSubmitAction: isLikelyAuthenticationSubmitAction(name, args),
+            });
+            if (postActionDelayMs > 0) {
+                await browser.wait(postActionDelayMs);
+            }
+        }
+    }
+    // Max iterations exhausted
+    logger.error('Max iterations reached');
+    getPostHog().capture({
+        distinctId: config.analyticsId ?? DISTINCT_ID,
+        event: 'agent_max_iterations_reached',
+        properties: {
+            url: config.url,
+            model: modelState.active,
+            theme: config.currentTheme,
+            lang: config.currentLang,
+            max_iterations: config.maxIterations,
+            total_tokens: usageLog.reduce((s, u) => s + (u.totalTokens ?? 0), 0),
+            cache_read_tokens: usageLog.reduce((s, u) => s + (u.cacheReadTokens ?? 0), 0),
+            cache_hit_rate: (() => {
+                const prompt = usageLog.reduce((s, u) => s + (u.promptTokens ?? 0), 0);
+                const cached = usageLog.reduce((s, u) => s + (u.cacheReadTokens ?? 0), 0);
+                return prompt > 0 ? Math.round((cached / prompt) * 100) : 0;
+            })(),
+        },
+    });
+    return {
+        success: false,
+        screenshotPath: null,
+        screenshots: workflowScreenshots,
+        iterations: config.maxIterations,
+        actions: actionHistory,
+        assessment: 'Max iterations reached without completing the task.',
+        usage: usageLog,
+        runtimeStrategy: 'full_llm',
+        deterministicRecoveryUsed: usedDeterministicRecovery,
+        evaluatorUsed: false,
+        verification: lastVerificationResult,
+    };
+}
+/** Actions that can be safely replayed (no terminal or meta actions). */
+const REPLAYABLE_ACTIONS = [
+    'navigate_to', 'click', 'type_text', 'select_option', 'scroll',
+    'press_key', 'wait', 'resize_viewport', 'dismiss_overlays',
+    // Legacy aliases kept for replaying old recordings
+    'hover', 'safe_expand', 'scroll_to_element',
+];
+/**
+ * Replay a previous successful capture's recorded actions instead of running the full AI agent.
+ * Falls back to a full runAgent if replay fails or verification doesn't pass.
+ * Much cheaper than a full agent run: only 1 verification call vs. N agent iterations.
+ */
+export async function replayAgent(browser, config, apiKey, recordedActions, options = {}) {
+    const client = createClient(apiKey);
+    const modelState = { active: config.model };
+    const usageLog = [];
+    const allowFullAgentFallback = options.allowFullAgentFallback !== false;
+    const replayObservation = await browser.captureObservation().catch(() => null);
+    const replayAnalysis = analyzeReplayCandidate(recordedActions, {
+        currentUrl: browser.currentPage.url(),
+        targetUrl: config.url,
+        currentViewport: browser.currentPage.viewportSize(),
+        isAuthenticated: config.sessionProfile?.authState === 'authenticated',
+        currentDialogCount: replayObservation?.dialogCount ?? null,
+        pageIdentity: config.variantManifest?.currentPageIdentity ?? null,
+    });
+    const replayable = replayAnalysis.replayableActions;
+    if (replayAnalysis.skipReason) {
+        if (!allowFullAgentFallback) {
+            logger.error(`Replay skipped (${replayAnalysis.skipReason}), staying in replay-only mode`);
+            return {
+                success: false,
+                screenshotPath: null,
+                screenshots: [],
+                iterations: 0,
+                actions: recordedActions,
+                assessment: `Action replay skipped: ${replayAnalysis.skipReason}`,
+                diagnostic: {
+                    screenshot: await browser.takeScreenshot().catch(() => Buffer.alloc(0)),
+                    url: browser.currentPage.url(),
+                    interactiveElements: [],
+                    accessibilityTreeSnippet: '',
+                    giveUpReason: `Action replay skipped: ${replayAnalysis.skipReason}`,
+                },
+                usage: usageLog,
+                runtimeStrategy: 'action_replay',
+                deterministicRecoveryUsed: false,
+                evaluatorUsed: false,
+            };
+        }
+        logger.info(`Action replay skipped (${replayAnalysis.skipReason}), falling back to full agent run`);
+        if (!urlsRoughlyMatch(config.url, browser.currentPage.url())) {
+            await browser.navigateTo(config.url);
+        }
+        const fallback = await runAgent(browser, config, apiKey);
+        return {
+            ...fallback,
+            runtimeStrategy: 'action_replay_fallback',
+        };
+    }
+    logger.info(`Action replay: replaying ${replayable.length} actions...`);
+    try {
+        for (const recorded of replayable) {
+            throwIfAborted(config.abortSignal, 'Replay cancelled.');
+            // Pre-action URL validation: if the recorded action stored the URL it was
+            // executed from, verify the browser is on the same page before attempting it.
+            // Skip URL validation for actions that work regardless of URL (press_key, scroll, wait,
+            // dismiss_overlays) — these are often used between page transitions and don't depend
+            // on being on a specific URL.
+            const URL_INDEPENDENT_ACTIONS = new Set(['press_key', 'scroll', 'scroll_to_element', 'wait', 'dismiss_overlays', 'resize_viewport']);
+            const expectedPreUrl = typeof recorded.params.preActionUrl === 'string' ? recorded.params.preActionUrl : null;
+            if (expectedPreUrl && !URL_INDEPENDENT_ACTIONS.has(recorded.action)) {
+                const currentUrl = browser.currentPage.url();
+                if (!urlsRoughlyMatch(expectedPreUrl, currentUrl) && !urlsRoughlyMatch(currentUrl, expectedPreUrl)) {
+                    throw new Error(`Replay starting URL mismatch for "${recorded.action}": expected ${expectedPreUrl}, browser is on ${currentUrl}`);
+                }
+            }
+            const interactiveElements = replayActionRequiresAnchor(recorded)
+                ? await browser.getInteractiveElements().catch(() => [])
+                : [];
+            const resolvedReplayAction = resolveReplayActionArgs(recorded, interactiveElements);
+            if (!resolvedReplayAction.args) {
+                throw new Error(resolvedReplayAction.reason ?? `Action "${recorded.action}" cannot be replayed on the current page`);
+            }
+            const resolvedReplayArgs = resolveActionCredentialArgs(recorded.action, resolvedReplayAction.args, config.credentials);
+            // Force clicks during replay to bypass pointer-event interception
+            // (e.g., after dark theme switch, <html class="dark"> may briefly intercept events)
+            if (recorded.action === 'click' || recorded.action === 'safe_expand') {
+                resolvedReplayArgs.__forceClick = true;
+            }
+            const result = await executeAction(browser, recorded.action, resolvedReplayArgs);
+            throwIfAborted(config.abortSignal, 'Replay cancelled.');
+            if (!result.success) {
+                throw new Error(`Action "${recorded.action}" failed: ${result.error}`);
+            }
+            // Replay needs longer delays than live agent — the live agent adapts to
+            // page reactions but replay fires actions blindly. Use the full delay for
+            // state-changing clicks (page transitions, modals) to let async operations settle.
+            const baseDelay = getPostActionDelayMs(recorded.action, result, {
+                authSubmitAction: isLikelyAuthenticationSubmitAction(recorded.action, recorded.params),
+            });
+            const postActionDelayMs = result.stateChanged ? Math.max(baseDelay, 300) : baseDelay;
+            if (postActionDelayMs > 0) {
+                await browser.wait(postActionDelayMs);
+            }
+            // Validate intermediate URL: if the recorded action caused a navigation,
+            // verify the replay landed on a matching URL. This catches divergence early
+            // (e.g., a translated button click that navigates to a different page).
+            const expectedUrl = typeof recorded.params.postActionUrl === 'string' ? recorded.params.postActionUrl : null;
+            if (expectedUrl && result.stateChanged) {
+                const actualUrl = browser.currentPage.url();
+                if (!urlsRoughlyMatch(expectedUrl, actualUrl) && !urlsRoughlyMatch(actualUrl, expectedUrl)) {
+                    throw new Error(`Replay URL divergence after "${recorded.action}": expected ${expectedUrl}, got ${actualUrl}`);
+                }
+            }
+        }
+    }
+    catch (err) {
+        if (isAbortError(err)) {
+            throw err;
+        }
+        const replayError = err.message;
+        if (!allowFullAgentFallback) {
+            logger.error(`Replay failed (${replayError}), staying in replay-only mode`);
+            return {
+                success: false,
+                screenshotPath: null,
+                screenshots: [],
+                iterations: 0,
+                actions: recordedActions,
+                assessment: `Action replay failed: ${replayError}`,
+                diagnostic: {
+                    screenshot: await browser.takeScreenshot().catch(() => Buffer.alloc(0)),
+                    url: browser.currentPage.url(),
+                    interactiveElements: [],
+                    accessibilityTreeSnippet: '',
+                    giveUpReason: `Action replay failed: ${replayError}`,
+                },
+                usage: usageLog,
+                runtimeStrategy: 'action_replay',
+                deterministicRecoveryUsed: false,
+                evaluatorUsed: false,
+            };
+        }
+        logger.error(`Replay failed (${replayError}), falling back to full agent run`);
+        if (!urlsRoughlyMatch(config.url, browser.currentPage.url())) {
+            await browser.navigateTo(config.url);
+        }
+        const fallback = await runAgent(browser, config, apiKey);
+        return {
+            ...fallback,
+            runtimeStrategy: 'action_replay_fallback',
+        };
+    }
+    // One verification call to confirm the page state looks correct
+    logger.info('Replay done, verifying...');
+    throwIfAborted(config.abortSignal, 'Replay cancelled.');
+    const replayExpectsGalleryDetail = config.variantManifest?.currentPageIdentity?.kind === 'gallery'
+        && GALLERY_DETAIL_PROMPT_RE.test(`${config.variantManifest?.currentPageId || ''} ${config.prompt}`.toLowerCase());
+    const verification = await verifyScreenshot(client, config, modelState, browser, 'Page prepared via action replay', 1, {
+        skipDialogCheck: config.variantManifest?.currentPageIdentity?.dialogTarget
+            || replayExpectsGalleryDetail,
+    });
+    const { verified, reason, usage: verifyUsage, fatal } = verification;
+    if (verifyUsage)
+        usageLog.push(verifyUsage);
+    if (fatal) {
+        return {
+            success: false,
+            screenshotPath: null,
+            screenshots: [],
+            iterations: 0,
+            actions: recordedActions,
+            assessment: reason || 'Replay verification failed',
+            diagnostic: {
+                screenshot: await browser.takeScreenshot().catch(() => Buffer.alloc(0)),
+                url: browser.currentPage.url(),
+                interactiveElements: [],
+                accessibilityTreeSnippet: '',
+                giveUpReason: reason || 'Replay verification failed',
+            },
+            usage: usageLog,
+            runtimeStrategy: 'action_replay',
+            deterministicRecoveryUsed: false,
+            evaluatorUsed: false,
+            verification,
+        };
+    }
+    if (verified) {
+        logger.success('Action replay verified');
+        getPostHog().capture({
+            distinctId: config.analyticsId ?? DISTINCT_ID,
+            event: 'agent_run_succeeded',
+            properties: {
+                url: config.url,
+                model: modelState.active,
+                theme: config.currentTheme,
+                lang: config.currentLang,
+                iterations: 0,
+                replay: true,
+                total_tokens: usageLog.reduce((s, u) => s + (u.totalTokens ?? 0), 0),
+            },
+        });
+        return {
+            success: true,
+            screenshotPath: null,
+            screenshots: [],
+            iterations: 0,
+            actions: recordedActions,
+            assessment: 'Captured via action replay',
+            usage: usageLog,
+            runtimeStrategy: 'action_replay',
+            deterministicRecoveryUsed: false,
+            evaluatorUsed: false,
+            verification,
+        };
+    }
+    // Verification failed — reset and fall back to full agent run
+    if (!allowFullAgentFallback) {
+        logger.error(`Replay verification failed (${reason}), staying in replay-only mode`);
+        return {
+            success: false,
+            screenshotPath: null,
+            screenshots: [],
+            iterations: 0,
+            actions: recordedActions,
+            assessment: reason || 'Replay verification failed',
+            diagnostic: {
+                screenshot: await browser.takeScreenshot().catch(() => Buffer.alloc(0)),
+                url: browser.currentPage.url(),
+                interactiveElements: [],
+                accessibilityTreeSnippet: '',
+                giveUpReason: reason || 'Replay verification failed',
+            },
+            usage: usageLog,
+            runtimeStrategy: 'action_replay',
+            deterministicRecoveryUsed: false,
+            evaluatorUsed: false,
+            verification,
+        };
+    }
+    logger.error(`Replay verification failed (${reason}), falling back to full agent run`);
+    if (!urlsRoughlyMatch(config.url, browser.currentPage.url())) {
+        await browser.navigateTo(config.url);
+    }
+    const fallback = await runAgent(browser, config, apiKey);
+    return {
+        ...fallback,
+        runtimeStrategy: 'action_replay_fallback',
+    };
+}
+//# sourceMappingURL=agent.js.map