browser-use 0.2.0 → 0.3.0

package/dist/agent/service.js

@@ -2,54 +2,63 @@ import path from 'node:path';
 import fs from 'node:fs';
 import os from 'node:os';
 import process from 'node:process';
+import { createHash } from 'node:crypto';
 import { config as loadEnv } from 'dotenv';
 import { z } from 'zod';
 import { createLogger } from '../logging-config.js';
 import { CONFIG } from '../config.js';
 import { EventBus } from '../event-bus.js';
-import { uuid7str, SignalHandler, get_browser_use_version } from '../utils.js';
+import { uuid7str, SignalHandler, get_browser_use_version, check_latest_browser_use_version, sanitize_surrogates, } from '../utils.js';
 import { Controller as DefaultController } from '../controller/service.js';
 import { FileSystem as AgentFileSystem, DEFAULT_FILE_SYSTEM_PATH, } from '../filesystem/file-system.js';
-import { SystemPrompt } from './prompts.js';
+import { SystemPrompt, get_ai_step_system_prompt, get_ai_step_user_prompt, get_rerun_summary_message, get_rerun_summary_prompt, } from './prompts.js';
 import { MessageManager } from './message-manager/service.js';
 import { BrowserStateHistory } from '../browser/views.js';
 import { BrowserSession } from '../browser/session.js';
 import { BrowserProfile, DEFAULT_BROWSER_PROFILE } from '../browser/profile.js';
-import { InsecureSensitiveDataError } from '../exceptions.js';
 import { HistoryTreeProcessor } from '../dom/history-tree-processor/service.js';
 import { DOMHistoryElement } from '../dom/history-tree-processor/view.js';
-import { UserMessage } from '../llm/messages.js';
-import { ActionResult, AgentHistory, AgentHistoryList, AgentOutput, AgentState, AgentStepInfo, AgentError, StepMetadata, ActionModel, } from './views.js';
+import { DEFAULT_INCLUDE_ATTRIBUTES, } from '../dom/views.js';
+import { extractCleanMarkdownFromHtml } from '../dom/markdown-extractor.js';
+import { ChatBrowserUse } from '../llm/browser-use/chat.js';
+import { ModelProviderError, ModelRateLimitError } from '../llm/exceptions.js';
+import { AssistantMessage, ContentPartTextParam, SystemMessage, UserMessage, } from '../llm/messages.js';
+import { getLlmByName } from '../llm/models.js';
+import { ActionResult, AgentHistory, AgentHistoryList, AgentOutput, AgentState, AgentStepInfo, AgentError, StepMetadata, ActionModel, PlanItem, defaultMessageCompactionSettings, normalizeMessageCompactionSettings, } from './views.js';
+import { detect_variables_in_history, substitute_in_dict, } from './variable-detector.js';
 import { CreateAgentOutputFileEvent, CreateAgentSessionEvent, CreateAgentTaskEvent, CreateAgentStepEvent, UpdateAgentTaskEvent, } from './cloud-events.js';
 import { create_history_gif } from './gif.js';
 import { ScreenshotService } from '../screenshots/service.js';
 import { productTelemetry } from '../telemetry/service.js';
 import { AgentTelemetryEvent } from '../telemetry/views.js';
 import { TokenCost } from '../tokens/service.js';
+import { construct_judge_messages, construct_simple_judge_messages, } from './judge.js';
+import { CloudSkillService, MissingCookieException, build_skill_parameters_schema, get_skill_slug, } from '../skills/index.js';
 loadEnv();
 const logger = createLogger('browser_use.agent');
+const URL_PATTERN = /https?:\/\/[^\s<>"']+|www\.[^\s<>"']+|[^\s<>"']+\.[a-z]{2,}(?:\/[^\s<>"']*)?/gi;
 export const log_response = (response, registry, logInstance = logger) => {
     if (response.current_state.thinking) {
-        logInstance.info(`💡 Thinking:\n${response.current_state.thinking}`);
+        logInstance.debug(`💡 Thinking:\n${response.current_state.thinking}`);
     }
     const evalGoal = response.current_state.evaluation_previous_goal;
     if (evalGoal) {
-        let emoji = '❔';
-        if (evalGoal.toLowerCase().includes('success'))
-            emoji = '👍';
-        else if (evalGoal.toLowerCase().includes('failure'))
-            emoji = '⚠️';
-        logInstance.info(`${emoji} Eval: ${evalGoal}`);
+        if (evalGoal.toLowerCase().includes('success')) {
+            logInstance.info(`  \x1b[32m👍 Eval: ${evalGoal}\x1b[0m`);
+        }
+        else if (evalGoal.toLowerCase().includes('failure')) {
+            logInstance.info(`  \x1b[31m⚠️ Eval: ${evalGoal}\x1b[0m`);
+        }
+        else {
+            logInstance.info(`  ❔ Eval: ${evalGoal}`);
+        }
     }
     if (response.current_state.memory) {
-        logInstance.info(`🧠 Memory: ${response.current_state.memory}`);
+        logInstance.info(`  🧠 Memory: ${response.current_state.memory}`);
     }
     const nextGoal = response.current_state.next_goal;
     if (nextGoal) {
-        logInstance.info(`🎯 Next goal: ${nextGoal}\n`);
-    }
-    else {
-        logInstance.info('');
+        logInstance.info(`  \x1b[34m🎯 Next goal: ${nextGoal}\x1b[0m`);
     }
 };
 class AsyncMutex {
@@ -98,28 +107,64 @@ const ensureDir = (target) => {
         fs.mkdirSync(target, { recursive: true });
     }
 };
+const resolve_agent_llm = (llm) => {
+    if (llm) {
+        return llm;
+    }
+    const defaultLlmName = CONFIG.DEFAULT_LLM.trim();
+    if (defaultLlmName) {
+        return getLlmByName(defaultLlmName);
+    }
+    return new ChatBrowserUse();
+};
+const get_model_timeout = (llm) => {
+    const modelName = String(llm?.model ?? '').toLowerCase();
+    if (modelName.includes('gemini')) {
+        if (modelName.includes('3-pro')) {
+            return 90;
+        }
+        return 75;
+    }
+    if (modelName.includes('groq')) {
+        return 30;
+    }
+    if (modelName.includes('o3') ||
+        modelName.includes('claude') ||
+        modelName.includes('sonnet') ||
+        modelName.includes('deepseek')) {
+        return 90;
+    }
+    return 75;
+};
 const defaultAgentOptions = () => ({
     use_vision: true,
-    use_vision_for_planner: false,
+    include_recent_events: false,
+    sample_images: null,
+    llm_screenshot_size: null,
     save_conversation_path: null,
     save_conversation_path_encoding: 'utf-8',
     max_failures: 3,
-    retry_delay: 10,
+    directly_open_url: true,
     override_system_message: null,
     extend_system_message: null,
-    validate_output: false,
     generate_gif: false,
     available_file_paths: [],
     include_attributes: undefined,
-    max_actions_per_step: 10,
+    max_actions_per_step: 5,
     use_thinking: true,
     flash_mode: false,
+    use_judge: true,
+    ground_truth: null,
     max_history_items: null,
     page_extraction_llm: null,
-    planner_llm: null,
-    planner_interval: 1,
-    is_planner_reasoning: false,
-    extend_planner_system_message: null,
+    fallback_llm: null,
+    judge_llm: null,
+    skill_ids: null,
+    skills: null,
+    skill_service: null,
+    enable_planning: true,
+    planning_replan_on_stall: 3,
+    planning_exploration_limit: 5,
     context: null,
     source: null,
     file_system_path: null,
@@ -129,33 +174,68 @@ const defaultAgentOptions = () => ({
     display_files_in_done_text: true,
     include_tool_call_examples: false,
     session_attachment_mode: 'copy',
-    allow_insecure_sensitive_data: false,
     vision_detail_level: 'auto',
-    llm_timeout: 60,
+    llm_timeout: null,
     step_timeout: 180,
+    final_response_after_failure: true,
+    message_compaction: true,
+    loop_detection_window: 20,
+    loop_detection_enabled: true,
+    _url_shortening_limit: 25,
 });
 const AgentLLMOutputSchema = z.object({
     thinking: z.string().optional().nullable(),
     evaluation_previous_goal: z.string().optional().nullable(),
     memory: z.string().optional().nullable(),
     next_goal: z.string().optional().nullable(),
+    current_plan_item: z.number().int().optional().nullable(),
+    plan_update: z.array(z.string()).optional().nullable(),
     action: z
         .array(z.record(z.string(), z.any()))
         .optional()
         .nullable()
         .default([]),
 });
+const DoneOnlyLLMOutputSchema = AgentLLMOutputSchema.extend({
+    action: z
+        .array(z.object({
+        done: z.object({}).passthrough(),
+    }))
+        .optional()
+        .nullable()
+        .default([]),
+});
+const SimpleJudgeSchema = z.object({
+    is_correct: z.boolean(),
+    reason: z.string().optional().default(''),
+});
+const JudgeSchema = z.object({
+    reasoning: z.string().optional().nullable().default(''),
+    verdict: z.boolean(),
+    failure_reason: z.string().optional().nullable().default(''),
+    impossible_task: z.boolean().optional().default(false),
+    reached_captcha: z.boolean().optional().default(false),
+});
 const AgentLLMOutputFormat = AgentLLMOutputSchema;
 AgentLLMOutputFormat.schema = AgentLLMOutputSchema;
+const DoneOnlyLLMOutputFormat = DoneOnlyLLMOutputSchema;
+DoneOnlyLLMOutputFormat.schema = DoneOnlyLLMOutputSchema;
+const SimpleJudgeOutputFormat = SimpleJudgeSchema;
+SimpleJudgeOutputFormat.schema = SimpleJudgeSchema;
+const JudgeOutputFormat = JudgeSchema;
+JudgeOutputFormat.schema = JudgeSchema;
 export class Agent {
     static _sharedSessionStepLocks = new Map();
     static DEFAULT_AGENT_DATA_DIR = path.join(process.cwd(), DEFAULT_FILE_SYSTEM_PATH);
     browser_session = null;
     llm;
+    judge_llm;
     unfiltered_actions;
     initial_actions;
+    initial_url = null;
     register_new_step_callback;
     register_done_callback;
+    register_should_stop_callback;
     register_external_agent_status_raise_error_callback;
     context;
     telemetry;
@@ -176,6 +256,7 @@ export class Agent {
         promise: Promise.resolve(),
     };
     output_model_schema;
+    extraction_schema;
     id;
     task_id;
     session_id;
@@ -203,61 +284,176 @@ export class Agent {
     AgentOutput = AgentOutput;
     DoneActionModel = ActionModel;
     DoneAgentOutput = AgentOutput;
+    _fallback_llm = null;
+    _using_fallback_llm = false;
+    _original_llm = null;
+    _url_shortening_limit = 25;
+    skill_service = null;
+    _skills_registered = false;
     constructor(params) {
-        const { task, llm, page = null, browser = null, browser_context = null, browser_profile = null, browser_session = null, controller = null, sensitive_data = null, initial_actions = null, register_new_step_callback = null, register_done_callback = null, register_external_agent_status_raise_error_callback = null, output_model_schema = null, use_vision = true, save_conversation_path = null, save_conversation_path_encoding = 'utf-8', max_failures = 3, retry_delay = 10, override_system_message = null, extend_system_message = null, validate_output = false, generate_gif = false, available_file_paths = [], include_attributes, max_actions_per_step = 10, use_thinking = true, flash_mode = false, max_history_items = null, page_extraction_llm = null, context = null, source = null, file_system_path = null, task_id = null, cloud_sync = null, calculate_cost = false, display_files_in_done_text = true, include_tool_call_examples = false, vision_detail_level = 'auto', session_attachment_mode = 'copy', allow_insecure_sensitive_data = false, llm_timeout = 60, step_timeout = 180, } = { ...defaultAgentOptions(), ...params };
-        if (!llm) {
-            throw new Error('Invalid llm, must be provided');
-        }
-        const effectivePageExtractionLlm = page_extraction_llm ?? llm;
-        this.llm = llm;
+        const { task, llm, page = null, browser = null, browser_context = null, browser_profile = null, browser_session = null, tools = null, controller = null, sensitive_data = null, initial_actions = null, directly_open_url = true, register_new_step_callback = null, register_done_callback = null, register_should_stop_callback = null, register_external_agent_status_raise_error_callback = null, output_model_schema = null, extraction_schema = null, use_vision = true, include_recent_events = false, sample_images = null, llm_screenshot_size = null, save_conversation_path = null, save_conversation_path_encoding = 'utf-8', max_failures = 3, override_system_message = null, extend_system_message = null, generate_gif = false, available_file_paths = [], include_attributes, max_actions_per_step = 5, use_thinking = true, flash_mode = false, use_judge = true, ground_truth = null, max_history_items = null, page_extraction_llm = null, fallback_llm = null, judge_llm = null, skill_ids = null, skills = null, skill_service = null, enable_planning = true, planning_replan_on_stall = 3, planning_exploration_limit = 5, context = null, source = null, file_system_path = null, task_id = null, cloud_sync = null, calculate_cost = false, display_files_in_done_text = true, include_tool_call_examples = false, vision_detail_level = 'auto', session_attachment_mode = 'copy', llm_timeout = null, step_timeout = 180, final_response_after_failure = true, message_compaction = true, loop_detection_window = 20, loop_detection_enabled = true, _url_shortening_limit = 25, } = { ...defaultAgentOptions(), ...params };
+        const resolvedLlm = resolve_agent_llm(llm);
+        const effectivePageExtractionLlm = page_extraction_llm ?? resolvedLlm;
+        const effectiveJudgeLlm = judge_llm ?? resolvedLlm;
+        const effectiveFlashMode = flash_mode || resolvedLlm?.provider === 'browser-use';
+        const effectiveEnablePlanning = effectiveFlashMode
+            ? false
+            : enable_planning;
+        const effectiveLlmTimeout = typeof llm_timeout === 'number'
+            ? llm_timeout
+            : get_model_timeout(resolvedLlm);
+        const normalizedMessageCompaction = this._normalizeMessageCompactionSetting(message_compaction);
+        let resolvedLlmScreenshotSize = llm_screenshot_size ?? null;
+        if (resolvedLlmScreenshotSize !== null) {
+            if (!Array.isArray(resolvedLlmScreenshotSize) ||
+                resolvedLlmScreenshotSize.length !== 2) {
+                throw new Error('llm_screenshot_size must be a tuple of [width, height]');
+            }
+            const [width, height] = resolvedLlmScreenshotSize;
+            if (!Number.isInteger(width) || !Number.isInteger(height)) {
+                throw new Error('llm_screenshot_size dimensions must be integers');
+            }
+            if (width < 100 || height < 100) {
+                throw new Error('llm_screenshot_size dimensions must be at least 100 pixels');
+            }
+            logger.info(`LLM screenshot resizing enabled: ${width}x${height}`);
+        }
+        if (resolvedLlmScreenshotSize == null) {
+            const modelName = String(resolvedLlm?.model ?? '');
+            if (modelName.startsWith('claude-sonnet')) {
+                resolvedLlmScreenshotSize = [1400, 850];
+                logger.info('Auto-configured LLM screenshot size for Claude Sonnet: 1400x850');
+            }
+        }
+        this.llm = resolvedLlm;
+        this.judge_llm = effectiveJudgeLlm;
+        this._fallback_llm = fallback_llm;
+        this._using_fallback_llm = false;
+        this._original_llm = resolvedLlm;
+        this._url_shortening_limit = Math.max(0, Math.trunc(_url_shortening_limit));
         this.id = task_id || uuid7str();
         this.task_id = this.id;
         this.session_id = uuid7str();
-        this.task = task;
-        this.output_model_schema = output_model_schema ?? null;
-        this.sensitive_data = sensitive_data;
         this.available_file_paths = available_file_paths || [];
-        this.controller = (controller ??
+        if (tools && controller) {
+            throw new Error('Cannot specify both "tools" and "controller". Use "tools" only.');
+        }
+        const resolvedController = (tools ??
+            controller ??
             new DefaultController({
+                exclude_actions: use_vision !== 'auto' ? ['screenshot'] : [],
                 display_files_in_done_text,
             }));
-        this.initial_actions = initial_actions
-            ? this._convertInitialActions(initial_actions)
+        const toolsOutputModel = this._getToolsOutputModelSchema(resolvedController);
+        let resolvedOutputModelSchema = output_model_schema ?? null;
+        if (resolvedOutputModelSchema &&
+            toolsOutputModel &&
+            resolvedOutputModelSchema !== toolsOutputModel) {
+            this.logger.warning(`output_model_schema (${this._getOutputModelSchemaName(resolvedOutputModelSchema)}) differs from Tools output_model (${this._getOutputModelSchemaName(toolsOutputModel)}). Using Agent output_model_schema.`);
+        }
+        else if (!resolvedOutputModelSchema && toolsOutputModel) {
+            resolvedOutputModelSchema = toolsOutputModel;
+        }
+        this.output_model_schema = resolvedOutputModelSchema;
+        this.extraction_schema = extraction_schema ?? null;
+        if (!this.extraction_schema && this.output_model_schema) {
+            this.extraction_schema =
+                this._getOutputModelSchemaPayload(this.output_model_schema) ?? null;
+        }
+        this.task = this._enhanceTaskWithSchema(task, this.output_model_schema);
+        this.sensitive_data = sensitive_data;
+        this.controller = resolvedController;
+        const setCoordinateClicking = this.controller
+            ?.set_coordinate_clicking;
+        if (typeof setCoordinateClicking === 'function') {
+            const modelName = String(this.llm?.model ?? '').toLowerCase();
+            const supportsCoordinateClicking = [
+                'claude-sonnet-4',
+                'claude-opus-4',
+                'gemini-3-pro',
+                'browser-use/',
+            ].some((pattern) => modelName.includes(pattern));
+            setCoordinateClicking.call(this.controller, supportsCoordinateClicking);
+        }
+        const structuredOutputActionSchema = this._resolveStructuredOutputActionSchema(this.output_model_schema);
+        if (structuredOutputActionSchema) {
+            this.controller.use_structured_output_action(structuredOutputActionSchema);
+        }
+        if (skills && skill_ids) {
+            throw new Error('Cannot specify both "skills" and "skill_ids". Use "skills" only.');
+        }
+        const resolvedSkillIds = skills ?? skill_ids;
+        if (skill_service) {
+            this.skill_service = skill_service;
+        }
+        else if (resolvedSkillIds && resolvedSkillIds.length > 0) {
+            this.skill_service = new CloudSkillService({
+                skill_ids: resolvedSkillIds,
+            });
+        }
+        if (use_vision !== 'auto') {
+            const excludeAction = this.controller?.exclude_action;
+            if (typeof excludeAction === 'function') {
+                excludeAction.call(this.controller, 'screenshot');
+            }
+            else {
+                this.controller.registry.exclude_action?.('screenshot');
+            }
+        }
+        let resolvedInitialActions = initial_actions;
+        const hasFollowUpState = Boolean(params.injected_agent_state?.follow_up_task);
+        if (directly_open_url &&
+            !hasFollowUpState &&
+            !resolvedInitialActions?.length) {
+            const extractedUrl = this._extract_start_url(task);
+            if (extractedUrl) {
+                this.initial_url = extractedUrl;
+                this.logger.info(`🔗 Found URL in task: ${extractedUrl}, adding as initial action...`);
+                resolvedInitialActions = [
+                    { go_to_url: { url: extractedUrl, new_tab: false } },
+                ];
+            }
+        }
+        this.initial_actions = resolvedInitialActions
+            ? this._convertInitialActions(resolvedInitialActions)
             : null;
         this.register_new_step_callback = register_new_step_callback;
         this.register_done_callback = register_done_callback;
+        this.register_should_stop_callback = register_should_stop_callback;
         this.register_external_agent_status_raise_error_callback =
             register_external_agent_status_raise_error_callback;
         this.context = context;
         this.agent_directory = Agent.DEFAULT_AGENT_DATA_DIR;
         this.settings = {
             use_vision,
+            include_recent_events,
             vision_detail_level,
-            use_vision_for_planner: false,
             save_conversation_path,
             save_conversation_path_encoding,
             max_failures,
-            retry_delay,
-            validate_output,
             generate_gif,
             override_system_message,
             extend_system_message,
-            include_attributes: include_attributes ?? ['title', 'type', 'name'],
+            include_attributes: include_attributes ?? [...DEFAULT_INCLUDE_ATTRIBUTES],
             max_actions_per_step,
             use_thinking,
-            flash_mode,
+            flash_mode: effectiveFlashMode,
+            use_judge,
+            ground_truth,
             max_history_items,
             page_extraction_llm: effectivePageExtractionLlm,
-            planner_llm: null,
-            planner_interval: 1,
-            is_planner_reasoning: false,
-            extend_planner_system_message: null,
+            enable_planning: effectiveEnablePlanning,
+            planning_replan_on_stall,
+            planning_exploration_limit,
             calculate_cost,
             include_tool_call_examples,
             session_attachment_mode,
-            allow_insecure_sensitive_data,
-            llm_timeout,
+            llm_timeout: effectiveLlmTimeout,
             step_timeout,
+            final_response_after_failure,
+            message_compaction: normalizedMessageCompaction,
+            loop_detection_window,
+            loop_detection_enabled,
         };
         this.token_cost_service = new TokenCost(calculate_cost);
         if (calculate_cost) {
@@ -265,9 +461,14 @@ export class Agent {
                 this.logger.debug(`Failed to initialize token cost service: ${error.message}`);
             });
         }
-        this.token_cost_service.register_llm(llm);
+        this.token_cost_service.register_llm(resolvedLlm);
         this.token_cost_service.register_llm(effectivePageExtractionLlm);
+        this.token_cost_service.register_llm(effectiveJudgeLlm);
+        if (normalizedMessageCompaction?.compaction_llm) {
+            this.token_cost_service.register_llm(normalizedMessageCompaction.compaction_llm);
+        }
         this.state = params.injected_agent_state || new AgentState();
+        this.state.loop_detector.window_size = this.settings.loop_detection_window;
         this.history = new AgentHistoryList([], null);
         this.telemetry = productTelemetry;
         this._file_system_path = file_system_path;
@@ -282,15 +483,20 @@ export class Agent {
             browser_profile,
             browser_session,
         });
+        if (this.browser_session) {
+            this.browser_session.llm_screenshot_size = resolvedLlmScreenshotSize;
+        }
         this.has_downloads_path = Boolean(this.browser_session?.browser_profile?.downloads_path);
         if (this.has_downloads_path) {
             this._last_known_downloads = [];
-            this.logger.info('📁 Initialized download tracking for agent');
+            this.logger.debug('📁 Initialized download tracking for agent');
         }
-        this.system_prompt_class = new SystemPrompt(this.controller.registry.get_prompt_description(), this.settings.max_actions_per_step, this.settings.override_system_message, this.settings.extend_system_message, this.settings.use_thinking, this.settings.flash_mode);
-        this._message_manager = new MessageManager(task, this.system_prompt_class.get_system_message(), this.file_system, this.state.message_manager_state, this.settings.use_thinking, this.settings.include_attributes, sensitive_data ?? undefined, this.settings.max_history_items, this.settings.vision_detail_level, this.settings.include_tool_call_examples);
+        this.system_prompt_class = new SystemPrompt(this.settings.max_actions_per_step, this.settings.override_system_message, this.settings.extend_system_message, this.settings.use_thinking, this.settings.flash_mode, String(this.llm?.provider ?? '').toLowerCase() === 'anthropic', String(this.llm?.model ?? '')
+            .toLowerCase()
+            .includes('browser-use/'), String(this.llm?.model ?? ''));
+        this._message_manager = new MessageManager(this.task, this.system_prompt_class.get_system_message(), this.file_system, this.state.message_manager_state, this.settings.use_thinking, this.settings.include_attributes, sensitive_data ?? undefined, this.settings.max_history_items, this.settings.vision_detail_level, this.settings.include_tool_call_examples, this.settings.include_recent_events, sample_images ?? null, resolvedLlmScreenshotSize);
         this.unfiltered_actions = this.controller.registry.get_prompt_description();
-        this.eventbus = new EventBus(`Agent_${String(this.id).slice(-4)}`);
+        this.eventbus = new EventBus(this._buildEventBusName());
         this.enable_cloud_sync = CONFIG.BROWSER_USE_CLOUD_SYNC;
         if (this.enable_cloud_sync || cloud_sync) {
             this.cloud_sync = cloud_sync ?? null;
@@ -313,11 +519,33 @@ export class Agent {
         // Model-specific vision handling
         this._handleModelSpecificVision();
     }
+    _normalizeMessageCompactionSetting(messageCompaction) {
+        if (messageCompaction == null) {
+            return null;
+        }
+        if (typeof messageCompaction === 'boolean') {
+            return normalizeMessageCompactionSettings({
+                ...defaultMessageCompactionSettings(),
+                enabled: messageCompaction,
+            });
+        }
+        return normalizeMessageCompactionSettings({
+            ...defaultMessageCompactionSettings(),
+            ...messageCompaction,
+        });
+    }
     _createSessionIdWithAgentSuffix() {
         const suffix = this.id.slice(-4);
         const generated = uuid7str();
         return `${generated.slice(0, -4)}${suffix}`;
     }
+    _buildEventBusName() {
+        let agentIdSuffix = String(this.id).slice(-4).replace(/-/g, '_');
+        if (agentIdSuffix && /^\d/.test(agentIdSuffix)) {
+            agentIdSuffix = `a${agentIdSuffix}`;
+        }
+        return `Agent_${agentIdSuffix}`;
+    }
     _copyBrowserProfile(profile) {
         const source = profile ?? DEFAULT_BROWSER_PROFILE;
         const clonedConfig = typeof structuredClone === 'function'
@@ -525,20 +753,6 @@ export class Agent {
             id: this._createSessionIdWithAgentSuffix(),
         }));
     }
-    _sleep_blocking(ms) {
-        if (ms <= 0) {
-            return;
-        }
-        if (typeof SharedArrayBuffer === 'function' && Atomics?.wait) {
-            const lock = new Int32Array(new SharedArrayBuffer(4));
-            Atomics.wait(lock, 0, 0, ms);
-            return;
-        }
-        const end = Date.now() + ms;
-        while (Date.now() < end) {
-            // Intentional busy-wait fallback for runtimes without Atomics.wait.
-        }
-    }
     /**
      * Convert dictionary-based actions to ActionModel instances
      */
@@ -563,8 +777,16 @@ export class Agent {
                 }
                 // Validate parameters using Zod schema
                 const validatedParams = paramModel.parse(params);
+                if (!validatedParams ||
+                    typeof validatedParams !== 'object' ||
+                    Array.isArray(validatedParams)) {
+                    this.logger.warning(`⚠️ Parsed params for action "${actionName}" are not an object, skipping`);
+                    continue;
+                }
                 // Create action with validated parameters
-                convertedActions.push({ [actionName]: validatedParams });
+                convertedActions.push({
+                    [actionName]: validatedParams,
+                });
             }
             catch (error) {
                 this.logger.error(`❌ Failed to validate initial action "${actionName}": ${error}`);
@@ -585,9 +807,10 @@ export class Agent {
             this.logger.warning('⚠️ DeepSeek models do not support use_vision=True yet. Setting use_vision=False for now...');
             this.settings.use_vision = false;
         }
-        // Handle XAI (Grok) models
-        if (modelName.includes('grok') && this.settings.use_vision) {
-            this.logger.warning('⚠️ XAI models do not support use_vision=True yet. Setting use_vision=False for now...');
+        // Handle XAI models that currently do not support vision
+        if ((modelName.includes('grok-3') || modelName.includes('grok-code')) &&
+            this.settings.use_vision) {
+            this.logger.warning('⚠️ This XAI model does not support use_vision=True yet. Setting use_vision=False for now...');
             this.settings.use_vision = false;
         }
     }
@@ -624,20 +847,9 @@ export class Agent {
             : Boolean(allowedDomainsConfig);
         // If no allowed_domains are configured, show a security warning
         if (!hasAllowedDomains) {
-            if (!this.settings.allow_insecure_sensitive_data) {
-                throw new InsecureSensitiveDataError();
-            }
-            this.logger.error('⚠️⚠️⚠️ Agent(sensitive_data=••••••••) was provided but BrowserSession(allowed_domains=[...]) is not locked down! ⚠️⚠️⚠️\n' +
+            this.logger.warning('⚠️ Agent(sensitive_data=••••••••) was provided but Browser(allowed_domains=[...]) is not locked down! ⚠️\n' +
                 '          ☠️ If the agent visits a malicious website and encounters a prompt-injection attack, your sensitive_data may be exposed!\n\n' +
-                '             https://docs.browser-use.com/customize/browser-settings#restrict-urls\n' +
-                'Waiting 10 seconds before continuing... Press [Ctrl+C] to abort.');
-            // Check if we're in an interactive shell (TTY)
-            if (process.stdin.isTTY) {
-                // Block startup for 10 seconds to match Python warning behavior.
-                // User can still abort process with Ctrl+C.
-                this._sleep_blocking(10_000);
-            }
-            this.logger.warning('‼️ Continuing with insecure settings because allow_insecure_sensitive_data=true is enabled.');
+                '   \n');
         }
         // If we're using domain-specific credentials, validate domain patterns
         else if (hasDomainSpecificCredentials) {
@@ -686,7 +898,7 @@ export class Agent {
             try {
                 this.file_system = AgentFileSystem.from_state_sync(this.state.file_system_state);
                 this._file_system_path = this.state.file_system_state.base_dir;
-                this.logger.info(`💾 File system restored from state to: ${this._file_system_path}`);
+                this.logger.debug(`💾 File system restored from state to: ${this._file_system_path}`);
                 const timestamp = Date.now();
                 this.agent_directory = path.join(os.tmpdir(), `browser_use_agent_${this.id}_${timestamp}`);
                 ensureDir(this.agent_directory);
@@ -698,7 +910,10 @@ export class Agent {
                 throw error;
             }
         }
-        const baseDir = file_system_path ?? path.join(Agent.DEFAULT_AGENT_DATA_DIR, this.task_id);
+        const timestamp = Date.now();
+        this.agent_directory = path.join(os.tmpdir(), `browser_use_agent_${this.id}_${timestamp}`);
+        ensureDir(this.agent_directory);
+        const baseDir = file_system_path ?? this.agent_directory;
         ensureDir(baseDir);
         try {
             this.file_system = new AgentFileSystem(baseDir);
@@ -709,17 +924,14 @@ export class Agent {
             this.logger.error(`💾 Failed to initialize file system: ${message}`);
             throw error;
         }
-        const timestamp = Date.now();
-        this.agent_directory = path.join(os.tmpdir(), `browser_use_agent_${this.id}_${timestamp}`);
-        ensureDir(this.agent_directory);
         this.state.file_system_state = this.file_system.get_state();
-        this.logger.info(`💾 File system path: ${this._file_system_path}`);
+        this.logger.debug(`💾 File system path: ${this._file_system_path}`);
         return this.file_system;
     }
     _setScreenshotService() {
         try {
             this.screenshot_service = new ScreenshotService(this.agent_directory);
-            this.logger.info(`📸 Screenshot service initialized in: ${path.join(this.agent_directory, 'screenshots')}`);
+            this.logger.debug(`📸 Screenshot service initialized in: ${path.join(this.agent_directory, 'screenshots')}`);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -729,8 +941,20 @@ export class Agent {
     }
     get logger() {
         if (!this._logger) {
-            const browserSessionId = (this.browser_session && this.browser_session.id) || this.id;
-            this._logger = createLogger(`browser_use.Agent🅰 ${this.task_id.slice(-4)} on 🆂 ${String(browserSessionId).slice(-4)}`);
+            const taskIdSuffix = typeof this.task_id === 'string' && this.task_id.length
+                ? this.task_id.slice(-4)
+                : '----';
+            const browserSessionSuffix = typeof this.browser_session?.id === 'string'
+                ? this.browser_session.id.slice(-4)
+                : typeof this.id === 'string'
+                    ? this.id.slice(-4)
+                    : '----';
+            const focusTargetSuffixRaw = this.browser_session
+                ?.agent_focus_target_id;
+            const focusTargetSuffix = typeof focusTargetSuffixRaw === 'string' && focusTargetSuffixRaw.length
+                ? focusTargetSuffixRaw.slice(-2)
+                : '--';
+            this._logger = createLogger(`browser_use.Agent🅰 ${taskIdSuffix} ⇢ 🅑 ${browserSessionSuffix} 🅣 ${focusTargetSuffix}`);
         }
         return this._logger;
     }
@@ -770,6 +994,12 @@ export class Agent {
         }
         return this.browser_session.browser_profile;
     }
+    get is_using_fallback_llm() {
+        return this._using_fallback_llm;
+    }
+    get current_llm_model() {
+        return typeof this.llm?.model === 'string' ? this.llm.model : 'unknown';
+    }
     /**
      * Add a new task to the agent, keeping the same task_id as tasks are continuous
      */
@@ -778,6 +1008,210 @@ export class Agent {
         // The task continues with new instructions, it doesn't end and start a new one
         this.task = newTask;
         this._message_manager.add_new_task(newTask);
+        this.state.follow_up_task = true;
+        this.state.stopped = false;
+        this.state.paused = false;
+        this.eventbus = new EventBus(this._buildEventBusName());
+    }
+    _enhanceTaskWithSchema(task, outputModelSchema) {
+        if (!outputModelSchema) {
+            return task;
+        }
+        try {
+            const schemaPayload = this._getOutputModelSchemaPayload(outputModelSchema);
+            if (schemaPayload == null) {
+                return task;
+            }
+            const schemaJson = JSON.stringify(schemaPayload, null, 2);
+            if (!schemaJson) {
+                return task;
+            }
+            const schemaName = typeof outputModelSchema?.name === 'string'
+                ? outputModelSchema.name
+                : 'StructuredOutput';
+            return `${task}\nExpected output format: ${schemaName}\n${schemaJson}`;
+        }
+        catch (error) {
+            this.logger.debug(`Could not parse output schema for task enhancement: ${error instanceof Error ? error.message : String(error)}`);
+            return task;
+        }
+    }
+    _getOutputModelSchemaPayload(outputModelSchema) {
+        if (outputModelSchema instanceof z.ZodType) {
+            try {
+                const schema = z.toJSONSchema(outputModelSchema);
+                return schema && typeof schema === 'object'
+                    ? schema
+                    : null;
+            }
+            catch {
+                return null;
+            }
+        }
+        if (typeof outputModelSchema.model_json_schema === 'function') {
+            const schema = outputModelSchema.model_json_schema();
+            return schema && typeof schema === 'object'
+                ? schema
+                : null;
+        }
+        if (outputModelSchema.schema != null) {
+            const schemaCandidate = outputModelSchema.schema;
+            const schema = (() => {
+                if (schemaCandidate instanceof z.ZodType) {
+                    return z.toJSONSchema(schemaCandidate);
+                }
+                if (typeof schemaCandidate?.toJSON === 'function') {
+                    return schemaCandidate.toJSON();
+                }
+                return schemaCandidate;
+            })();
+            return schema && typeof schema === 'object'
+                ? schema
+                : null;
+        }
+        return null;
+    }
+    _getToolsOutputModelSchema(tools) {
+        const getOutputModel = tools?.get_output_model;
+        if (typeof getOutputModel !== 'function') {
+            return null;
+        }
+        const outputModel = getOutputModel.call(tools);
+        return outputModel == null
+            ? null
+            : outputModel;
+    }
+    _getOutputModelSchemaName(outputModelSchema) {
+        const explicitName = typeof outputModelSchema?.name === 'string'
+            ? outputModelSchema.name
+            : null;
+        if (explicitName && explicitName.trim().length > 0) {
+            return explicitName;
+        }
+        const ctorName = outputModelSchema?.constructor?.name;
+        return typeof ctorName === 'string' && ctorName.trim().length > 0
+            ? ctorName
+            : 'StructuredOutput';
+    }
+    _resolveStructuredOutputActionSchema(outputModelSchema) {
+        if (!outputModelSchema) {
+            return null;
+        }
+        if (outputModelSchema instanceof z.ZodType) {
+            return outputModelSchema;
+        }
+        const schemaCandidate = outputModelSchema?.schema;
+        if (schemaCandidate instanceof z.ZodType) {
+            return schemaCandidate;
+        }
+        return null;
+    }
+    _extract_start_url(taskText) {
+        const taskWithoutEmails = taskText.replace(/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, '');
+        const urlPatterns = [
+            /https?:\/\/[^\s<>"']+/g,
+            /(?:www\.)?[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*\.[a-zA-Z]{2,}(?:\/[^\s<>"']*)?/g,
+        ];
+        const excludedExtensions = new Set([
+            'pdf',
+            'doc',
+            'docx',
+            'xls',
+            'xlsx',
+            'ppt',
+            'pptx',
+            'odt',
+            'ods',
+            'odp',
+            'txt',
+            'md',
+            'csv',
+            'json',
+            'xml',
+            'yaml',
+            'yml',
+            'zip',
+            'rar',
+            '7z',
+            'tar',
+            'gz',
+            'bz2',
+            'xz',
+            'jpg',
+            'jpeg',
+            'png',
+            'gif',
+            'bmp',
+            'svg',
+            'webp',
+            'ico',
+            'mp3',
+            'mp4',
+            'avi',
+            'mkv',
+            'mov',
+            'wav',
+            'flac',
+            'ogg',
+            'py',
+            'js',
+            'css',
+            'java',
+            'cpp',
+            'bib',
+            'bibtex',
+            'tex',
+            'latex',
+            'cls',
+            'sty',
+            'exe',
+            'msi',
+            'dmg',
+            'pkg',
+            'deb',
+            'rpm',
+            'iso',
+            'polynomial',
+        ]);
+        const excludedWords = ['never', 'dont', "don't", 'not'];
+        const foundUrls = [];
+        for (const pattern of urlPatterns) {
+            for (const match of taskWithoutEmails.matchAll(pattern)) {
+                const original = match[0];
+                const startIndex = match.index ?? 0;
+                let url = original.replace(/[.,;:!?()[\]]+$/g, '');
+                const lowerUrl = url.toLowerCase();
+                let shouldExclude = false;
+                for (const ext of excludedExtensions) {
+                    if (lowerUrl.includes(`.${ext}`)) {
+                        shouldExclude = true;
+                        break;
+                    }
+                }
+                if (shouldExclude) {
+                    this.logger.debug(`Excluding URL with file extension from auto-navigation: ${url}`);
+                    continue;
+                }
+                const contextStart = Math.max(0, startIndex - 20);
+                const contextText = taskWithoutEmails
+                    .slice(contextStart, startIndex)
+                    .toLowerCase();
+                if (excludedWords.some((word) => contextText.includes(word))) {
+                    this.logger.debug(`Excluding URL with word in excluded words from auto-navigation: ${url} (context: "${contextText.trim()}")`);
+                    continue;
+                }
+                if (!url.startsWith('http://') && !url.startsWith('https://')) {
+                    url = `https://${url}`;
+                }
+                foundUrls.push(url);
+            }
+        }
+        const uniqueUrls = Array.from(new Set(foundUrls));
+        if (uniqueUrls.length > 1) {
+            this.logger.debug(`Multiple URLs found (${foundUrls.length}), skipping directly_open_url to avoid ambiguity`);
+            return null;
+        }
+        return uniqueUrls.length === 1 ? uniqueUrls[0] : null;
     }
     /**
      * Take a step and return whether the task is done and valid
@@ -786,7 +1220,11 @@ export class Agent {
     async takeStep(stepInfo) {
         await this._step(stepInfo ?? null);
         if (this.history.is_done()) {
+            await this._run_simple_judge();
             await this.log_completion();
+            if (this.settings.use_judge) {
+                await this._judge_and_log();
+            }
             if (this.register_done_callback) {
                 await this.register_done_callback(this.history);
             }
@@ -917,6 +1355,173 @@ export class Agent {
             this.DoneAgentOutput = AgentOutput.type_with_custom_actions_no_thinking(this.DoneActionModel);
         }
     }
+    async _register_skills_as_actions() {
+        if (!this.skill_service || this._skills_registered) {
+            return;
+        }
+        const skills = await this.skill_service.get_all_skills();
+        if (!skills.length) {
+            this.logger.warning('No skills loaded from SkillService');
+            return;
+        }
+        this.logger.info(`🔧 Registering ${skills.length} skill action(s)...`);
+        for (const skill of skills) {
+            const slug = get_skill_slug(skill, skills);
+            const paramSchema = build_skill_parameters_schema(skill.parameters, {
+                exclude_cookies: true,
+            });
+            const description = `${skill.description} (Skill: "${skill.title}")`;
+            this.controller.registry.action(description, {
+                param_model: paramSchema,
+                action_name: slug,
+            })(async (params, { browser_session }) => {
+                if (!this.skill_service) {
+                    return new ActionResult({ error: 'SkillService not initialized' });
+                }
+                if (!browser_session ||
+                    typeof browser_session.get_cookies !== 'function') {
+                    return new ActionResult({
+                        error: 'Skill execution requires an active BrowserSession.',
+                    });
+                }
+                try {
+                    const cookiesRaw = await browser_session.get_cookies();
+                    const cookies = Array.isArray(cookiesRaw)
+                        ? cookiesRaw
+                            .map((cookie) => {
+                            const record = cookie && typeof cookie === 'object'
+                                ? cookie
+                                : null;
+                            const name = record && typeof record.name === 'string'
+                                ? record.name
+                                : null;
+                            const value = record && typeof record.value === 'string'
+                                ? record.value
+                                : '';
+                            return name ? { name, value } : null;
+                        })
+                            .filter((cookie) => cookie != null)
+                        : [];
+                    const result = await this.skill_service.execute_skill({
+                        skill_id: skill.id,
+                        parameters: params ?? {},
+                        cookies,
+                    });
+                    if (!result.success) {
+                        return new ActionResult({
+                            error: result.error ?? 'Skill execution failed',
+                        });
+                    }
+                    const rendered = typeof result.result === 'string'
+                        ? result.result
+                        : JSON.stringify(result.result ?? {});
+                    return new ActionResult({
+                        extracted_content: rendered,
+                        long_term_memory: rendered,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof MissingCookieException) {
+                        return new ActionResult({
+                            error: `Missing cookies (${error.cookie_name}): ${error.cookie_description}`,
+                        });
+                    }
+                    const message = error instanceof Error
+                        ? `${error.name}: ${error.message}`
+                        : String(error);
+                    return new ActionResult({
+                        error: `Skill execution error: ${message}`,
+                    });
+                }
+            });
+        }
+        this._skills_registered = true;
+        this._setup_action_models();
+        if (this.initial_actions?.length) {
+            const actionDicts = this.initial_actions.map((action) => typeof action?.model_dump === 'function'
+                ? action.model_dump({ exclude_unset: true })
+                : action);
+            this.initial_actions = this._convertInitialActions(actionDicts);
+        }
+        this.logger.info(`✓ Registered ${skills.length} skill actions`);
+    }
+    async _get_unavailable_skills_info() {
+        if (!this.skill_service || !this.browser_session) {
+            return '';
+        }
+        try {
+            const skills = await this.skill_service.get_all_skills();
+            if (!skills.length) {
+                return '';
+            }
+            const currentCookies = await this.browser_session.get_cookies();
+            const cookieNames = new Set();
+            if (Array.isArray(currentCookies)) {
+                for (const cookie of currentCookies) {
+                    if (!cookie || typeof cookie !== 'object') {
+                        continue;
+                    }
+                    const name = typeof cookie.name === 'string'
+                        ? String(cookie.name)
+                        : '';
+                    if (name) {
+                        cookieNames.add(name);
+                    }
+                }
+            }
+            const unavailableSkills = [];
+            for (const skill of skills) {
+                const cookieParams = skill.parameters.filter((param) => param.type === 'cookie');
+                if (!cookieParams.length) {
+                    continue;
+                }
+                const missingCookies = [];
+                for (const cookieParam of cookieParams) {
+                    const isRequired = cookieParam.required !== false;
+                    if (isRequired && !cookieNames.has(cookieParam.name)) {
+                        missingCookies.push({
+                            name: cookieParam.name,
+                            description: cookieParam.description || 'No description provided',
+                        });
+                    }
+                }
+                if (missingCookies.length) {
+                    unavailableSkills.push({
+                        id: skill.id,
+                        title: skill.title,
+                        description: skill.description,
+                        missing_cookies: missingCookies,
+                    });
+                }
+            }
+            if (!unavailableSkills.length) {
+                return '';
+            }
+            const lines = [
+                'Unavailable Skills (missing required cookies):',
+            ];
+            for (const skillInfo of unavailableSkills) {
+                const skillObj = skills.find((entry) => entry.id === skillInfo.id);
+                const slug = skillObj
+                    ? get_skill_slug(skillObj, skills)
+                    : skillInfo.title;
+                lines.push('');
+                lines.push(`  • ${slug} ("${skillInfo.title}")`);
+                lines.push(`    Description: ${skillInfo.description}`);
+                lines.push('    Missing cookies:');
+                for (const cookie of skillInfo.missing_cookies) {
+                    lines.push(`      - ${cookie.name}: ${cookie.description}`);
+                }
+            }
+            return lines.join('\n');
+        }
+        catch (error) {
+            this.logger.error(`Error getting unavailable skills info: ${error instanceof Error
+                ? `${error.name}: ${error.message}`
+                : String(error)}`);
+            return '';
+        }
+    }
     /**
      * Update action models with page-specific actions
      * Called during each step to filter actions based on current page context
@@ -949,7 +1554,37 @@ export class Agent {
             this.DoneAgentOutput = AgentOutput.type_with_custom_actions_no_thinking(this.DoneActionModel);
         }
     }
-    async run(max_steps = 100, on_step_start = null, on_step_end = null) {
+    async _execute_initial_actions() {
+        if (!this.initial_actions?.length || this.state.follow_up_task) {
+            return;
+        }
+        this.logger.debug(`⚡ Executing ${this.initial_actions.length} initial actions...`);
+        const result = await this.multi_act(this.initial_actions);
+        if (result.length > 0 && this.initial_url && result[0]?.long_term_memory) {
+            result[0].long_term_memory = `Found initial url and automatically loaded it. ${result[0].long_term_memory}`;
+        }
+        this.state.last_result = result;
+        const modelOutput = this.settings.flash_mode
+            ? new this.AgentOutput({
+                evaluation_previous_goal: null,
+                memory: 'Initial navigation',
+                next_goal: null,
+                action: this.initial_actions,
+            })
+            : new this.AgentOutput({
+                evaluation_previous_goal: 'Start',
+                memory: null,
+                next_goal: 'Initial navigation',
+                action: this.initial_actions,
+            });
+        const timestamp = Date.now() / 1000;
+        const metadata = new StepMetadata(timestamp, timestamp, 0, null);
+        const stateHistory = new BrowserStateHistory(this.initial_url ?? '', 'Initial Actions', [], Array(this.initial_actions.length).fill(null), null);
+        this.history.add_item(new AgentHistory(modelOutput, result, stateHistory, metadata, null));
+        this.logger.debug('📝 Saved initial actions to history as step 0');
+        this.logger.debug('✅ Initial actions completed');
+    }
+    async run(max_steps = 500, on_step_start = null, on_step_end = null) {
         let agent_run_error = null;
         this._force_exit_telemetry_logged = false;
         const signal_handler = new SignalHandler({
@@ -964,61 +1599,76 @@ export class Agent {
         });
         signal_handler.register();
         try {
-            this._log_agent_run();
+            await this._log_agent_run();
             this.logger.debug(`🔧 Agent setup: Task ID ${this.task_id.slice(-4)}, Session ID ${this.session_id.slice(-4)}, Browser Session ID ${this.browser_session?.id?.slice?.(-4) ?? 'None'}`);
             this._session_start_time = Date.now() / 1000;
             this._task_start_time = this._session_start_time;
-            this.logger.debug('📡 Dispatching CreateAgentSessionEvent...');
-            this.eventbus.dispatch(CreateAgentSessionEvent.fromAgent(this));
+            if (!this.state.session_initialized) {
+                this.logger.debug('📡 Dispatching CreateAgentSessionEvent...');
+                this.eventbus.dispatch(CreateAgentSessionEvent.fromAgent(this));
+                this.state.session_initialized = true;
+            }
             this.logger.debug('📡 Dispatching CreateAgentTaskEvent...');
             this.eventbus.dispatch(CreateAgentTaskEvent.fromAgent(this));
-            if (this.initial_actions?.length) {
-                this.logger.debug(`⚡ Executing ${this.initial_actions.length} initial actions...`);
-                const result = await this.multi_act(this.initial_actions, {
-                    check_for_new_elements: false,
-                });
-                this.state.last_result = result;
-                this.logger.debug('✅ Initial actions completed');
+            if (!this.state.stopped) {
+                await this.browser_session?.start();
+            }
+            await this._register_skills_as_actions();
+            try {
+                await this._execute_initial_actions();
+            }
+            catch (error) {
+                if (error?.name !== 'InterruptedError') {
+                    throw error;
+                }
             }
-            this.logger.debug(`🔄 Starting main execution loop with max ${max_steps} steps...`);
-            for (let step = 0; step < max_steps; step += 1) {
+            this.logger.debug(`🔄 Starting main execution loop with max ${max_steps} steps (currently at step ${this.state.n_steps})...`);
+            while (this.state.n_steps <= max_steps) {
+                const currentStep = this.state.n_steps - 1;
                 if (this.state.paused) {
-                    this.logger.debug(`⏸️ Step ${step}: Agent paused, waiting to resume...`);
+                    this.logger.debug(`⏸️ Step ${this.state.n_steps}: Agent paused, waiting to resume...`);
                     await this.wait_until_resumed();
                     signal_handler.reset();
                 }
-                if (this.state.consecutive_failures >= this.settings.max_failures) {
+                if (this.state.consecutive_failures >= this._max_total_failures()) {
                     this.logger.error(`❌ Stopping due to ${this.settings.max_failures} consecutive failures`);
                     agent_run_error = `Stopped due to ${this.settings.max_failures} consecutive failures`;
                     break;
                 }
-                if (this.state.stopped) {
-                    this.logger.info('🛑 Agent stopped');
-                    agent_run_error = 'Agent stopped programmatically';
-                    break;
+                try {
+                    await this._raise_if_stopped_or_paused();
                 }
-                if (this.register_external_agent_status_raise_error_callback) {
-                    const shouldRaise = await this.register_external_agent_status_raise_error_callback();
-                    if (shouldRaise) {
-                        agent_run_error = 'Agent stopped due to external request';
+                catch (error) {
+                    if (error?.name === 'InterruptedError') {
+                        if (this.state.paused) {
+                            continue;
+                        }
+                        if (this.state.stopped) {
+                            this.logger.info('🛑 Agent stopped');
+                            agent_run_error = 'Agent stopped programmatically';
+                        }
+                        else {
+                            agent_run_error = 'Agent stopped due to external request';
+                        }
                         break;
                     }
+                    throw error;
                 }
                 if (on_step_start) {
                     await on_step_start(this);
                 }
-                this.logger.debug(`🚶 Starting step ${step + 1}/${max_steps}...`);
-                const step_info = new AgentStepInfo(step, max_steps);
+                this.logger.debug(`🚶 Starting step ${currentStep + 1}/${max_steps}...`);
+                const step_info = new AgentStepInfo(currentStep, max_steps);
                 const stepAbortController = new AbortController();
                 try {
                     await this._executeWithTimeout(this._step(step_info, stepAbortController.signal), this.settings.step_timeout ?? 0, () => stepAbortController.abort());
-                    this.logger.debug(`✅ Completed step ${step + 1}/${max_steps}`);
+                    this.logger.debug(`✅ Completed step ${currentStep + 1}/${max_steps}`);
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
                     const isTimeout = error instanceof ExecutionTimeoutError;
                     if (isTimeout) {
-                        const timeoutMessage = `Step ${step + 1} timed out after ${this.settings.step_timeout} seconds`;
+                        const timeoutMessage = `Step ${currentStep + 1} timed out after ${this.settings.step_timeout} seconds`;
                         this.logger.error(`⏰ ${timeoutMessage}`);
                         this.state.consecutive_failures += 1;
                         this.state.last_result = [
@@ -1030,11 +1680,11 @@ export class Agent {
                         agent_run_error = timeoutMessage;
                         break;
                     }
-                    this.logger.error(`❌ Unhandled step error at step ${step + 1}: ${message}`);
+                    this.logger.error(`❌ Unhandled step error at step ${currentStep + 1}: ${message}`);
                     this.state.consecutive_failures += 1;
                     this.state.last_result = [
                         new ActionResult({
-                            error: message || `Unhandled step error at step ${step + 1}`,
+                            error: message || `Unhandled step error at step ${currentStep + 1}`,
                         }),
                     ];
                 }
@@ -1042,8 +1692,12 @@ export class Agent {
                     await on_step_end(this);
                 }
                 if (this.history.is_done()) {
-                    this.logger.debug(`🎯 Task completed after ${step + 1} steps!`);
+                    this.logger.debug(`🎯 Task completed after ${currentStep + 1} steps!`);
+                    await this._run_simple_judge();
                     await this.log_completion();
+                    if (this.settings.use_judge) {
+                        await this._judge_and_log();
+                    }
                     if (this.register_done_callback) {
                         const maybePromise = this.register_done_callback(this.history);
                         if (maybePromise &&
@@ -1053,16 +1707,18 @@ export class Agent {
                     }
                     break;
                 }
-                if (step === max_steps - 1) {
-                    agent_run_error = 'Failed to complete task in maximum steps';
-                    this.history.add_item(new AgentHistory(null, [
-                        new ActionResult({
-                            error: agent_run_error,
-                            include_in_memory: true,
-                        }),
-                    ], new BrowserStateHistory('', '', [], [], null), null));
-                    this.logger.info(`❌ ${agent_run_error}`);
-                }
+            }
+            if (this.state.n_steps > max_steps &&
+                !this.history.is_done() &&
+                !agent_run_error) {
+                agent_run_error = 'Failed to complete task in maximum steps';
+                this.history.add_item(new AgentHistory(null, [
+                    new ActionResult({
+                        error: agent_run_error,
+                        include_in_memory: true,
+                    }),
+                ], new BrowserStateHistory('', '', [], [], null), null));
+                this.logger.info(`❌ ${agent_run_error}`);
             }
             this.logger.debug('📊 Collecting usage summary...');
             this.history.usage =
@@ -1175,10 +1831,12 @@ export class Agent {
         this._throwIfAborted(signal);
         await this._restore_shared_pinned_tab_if_needed();
         this._throwIfAborted(signal);
+        this._log_first_step_startup();
         this.logger.debug(`🌐 Step ${this.state.n_steps}: Getting browser state...`);
         const browser_state_summary = await this.browser_session.get_browser_state_with_recovery?.({
             cache_clickable_elements_hashes: true,
-            include_screenshot: this.settings.use_vision,
+            include_screenshot: true,
+            include_recent_events: this.settings.include_recent_events,
             signal,
         });
         this._throwIfAborted(signal);
@@ -1191,11 +1849,33 @@ export class Agent {
         this._throwIfAborted(signal);
         await this._updateActionModelsForPage(current_page);
         const page_filtered_actions = this.controller.registry.get_prompt_description(current_page);
+        let unavailable_skills_info = null;
+        if (this.skill_service) {
+            unavailable_skills_info = await this._get_unavailable_skills_info();
+        }
         this.logger.debug(`💬 Step ${this.state.n_steps}: Creating state messages for context...`);
-        this._message_manager.create_state_messages(browser_state_summary, this.state.last_model_output, this.state.last_result, step_info, this.settings.use_vision, page_filtered_actions || null, this.sensitive_data ?? null, this.available_file_paths);
+        this._message_manager.prepare_step_state(browser_state_summary, this.state.last_model_output, this.state.last_result, step_info, this.sensitive_data ?? null);
+        await this._maybe_compact_messages(step_info);
+        this._message_manager.create_state_messages(browser_state_summary, this.state.last_model_output, this.state.last_result, step_info, this.settings.use_vision, page_filtered_actions || null, this.sensitive_data ?? null, this.available_file_paths, this.settings.include_recent_events, this._render_plan_description(), unavailable_skills_info, true);
+        this._inject_budget_warning(step_info);
+        this._inject_replan_nudge();
+        this._inject_exploration_nudge();
+        this._update_loop_detector_page_state(browser_state_summary);
+        this._inject_loop_detection_nudge();
         await this._handle_final_step(step_info);
+        await this._handle_failure_limit_recovery();
         return browser_state_summary;
     }
+    async _maybe_compact_messages(step_info = null) {
+        const settings = this.settings.message_compaction;
+        if (!settings || !settings.enabled) {
+            return;
+        }
+        const compactionLlm = settings.compaction_llm ??
+            this.settings.page_extraction_llm ??
+            this.llm;
+        await this._message_manager.maybe_compact_messages(compactionLlm, settings, step_info);
+    }
     async _storeScreenshotForStep(browser_state_summary) {
         this._current_screenshot_path = null;
         if (!this.screenshot_service || !browser_state_summary?.screenshot) {
@@ -1224,7 +1904,7 @@ export class Agent {
         }
         catch (error) {
             if (error instanceof ExecutionTimeoutError) {
-                throw new Error(`LLM call timed out after ${this.settings.llm_timeout} seconds. Keep your thinking and output short.`);
+                throw new Error(`LLM call timed out after ${this.settings.llm_timeout} seconds. Keep your thinking and output short.`, { cause: error });
             }
             throw error;
         }
@@ -1256,32 +1936,51 @@ export class Agent {
             throw new Error('BrowserSession is not set up');
         }
         await this._check_and_update_downloads('after executing actions');
-        this.state.consecutive_failures = 0;
+        if (this.state.last_model_output) {
+            this._update_plan_from_model_output(this.state.last_model_output);
+        }
+        this._update_loop_detector_actions();
+        const lastResult = this.state.last_result;
+        if (lastResult && lastResult.length === 1 && lastResult[0]?.error) {
+            this.state.consecutive_failures += 1;
+            this.logger.debug(`🔄 Step ${this.state.n_steps}: Consecutive failures: ${this.state.consecutive_failures}`);
+            return;
+        }
+        if (this.state.consecutive_failures > 0) {
+            this.state.consecutive_failures = 0;
+            this.logger.debug(`🔄 Step ${this.state.n_steps}: Consecutive failures reset to: ${this.state.consecutive_failures}`);
+        }
+        if (lastResult &&
+            lastResult.length > 0 &&
+            lastResult[lastResult.length - 1]?.is_done) {
+            const finalResult = lastResult[lastResult.length - 1];
+            const success = Boolean(finalResult.success);
+            const renderedContent = typeof finalResult.extracted_content === 'string'
+                ? finalResult.extracted_content
+                : String(finalResult.extracted_content ?? '');
+            if (success) {
+                this.logger.info(`\n📄 \x1b[32m Final Result:\x1b[0m \n${renderedContent}\n\n`);
+            }
+            else {
+                this.logger.info(`\n📄 \x1b[31m Final Result:\x1b[0m \n${renderedContent}\n\n`);
+            }
+            const attachments = Array.isArray(finalResult.attachments)
+                ? finalResult.attachments
+                : [];
+            const totalAttachments = attachments.length;
+            for (let i = 0; i < attachments.length; i++) {
+                const suffix = totalAttachments > 1 ? String(i + 1) : '';
+                this.logger.info(`👉 Attachment${suffix ? ` ${suffix}` : ''}: ${attachments[i]}`);
+            }
+        }
     }
     async multi_act(actions, options = {}) {
-        const { check_for_new_elements = true, signal = null } = options;
+        const { signal = null } = options;
         const results = [];
         if (!this.browser_session) {
             throw new Error('BrowserSession is not set up');
         }
         await this._restore_shared_pinned_tab_if_needed();
-        // ==================== Selector Map Caching ====================
-        // Check if any action uses an index, if so cache the selector map
-        let cached_selector_map = {};
-        let cached_path_hashes = new Set();
-        for (const action of actions) {
-            const actionName = Object.keys(action)[0];
-            const actionParams = action[actionName];
-            const index = actionParams?.index;
-            if (index !== null && index !== undefined) {
-                cached_selector_map =
-                    (await this.browser_session.get_selector_map?.()) || {};
-                cached_path_hashes = new Set(Object.values(cached_selector_map)
-                    .map((e) => e?.hash?.branch_path_hash)
-                    .filter(Boolean));
-                break;
-            }
-        }
         // ==================== Execute Actions ====================
         for (let i = 0; i < actions.length; i++) {
             this._throwIfAborted(signal);
@@ -1295,50 +1994,8 @@ export class Agent {
                 this.logger.info(msg);
                 break;
             }
-            // ==================== Index Change & New Element Detection ====================
+            // ==================== Wait Between Actions ====================
             if (i > 0) {
-                const currentIndex = actionParams?.index;
-                if (currentIndex !== null && currentIndex !== undefined) {
-                    this._throwIfAborted(signal);
-                    // Get new browser state after previous action
-                    const new_browser_state_summary = await this.browser_session.get_browser_state_with_recovery?.({
-                        cache_clickable_elements_hashes: false,
-                        include_screenshot: false,
-                        signal,
-                    });
-                    const new_selector_map = new_browser_state_summary?.selector_map || {};
-                    // Detect index change after previous action
-                    const orig_target = cached_selector_map[currentIndex];
-                    const orig_target_hash = orig_target?.hash?.branch_path_hash || null;
-                    const new_target = new_selector_map[currentIndex];
-                    const new_target_hash = new_target?.hash?.branch_path_hash || null;
-                    if (orig_target_hash !== new_target_hash) {
-                        const msg = `Element index changed after action ${i} / ${actions.length}, because page changed.`;
-                        this.logger.info(msg);
-                        results.push(new ActionResult({
-                            extracted_content: msg,
-                            include_in_memory: true,
-                            long_term_memory: msg,
-                        }));
-                        break;
-                    }
-                    // Check for new elements on the page
-                    const new_path_hashes = new Set(Object.values(new_selector_map)
-                        .map((e) => e?.hash?.branch_path_hash)
-                        .filter(Boolean));
-                    // Check if new elements appeared (new_path_hashes is not a subset of cached_path_hashes)
-                    const has_new_elements = Array.from(new_path_hashes).some((hash) => !cached_path_hashes.has(hash));
-                    if (check_for_new_elements && has_new_elements) {
-                        const msg = `Something new appeared after action ${i} / ${actions.length}, following actions are NOT executed and should be retried.`;
-                        this.logger.info(msg);
-                        results.push(new ActionResult({
-                            extracted_content: msg,
-                            include_in_memory: true,
-                            long_term_memory: msg,
-                        }));
-                        break;
-                    }
-                }
                 // Wait between actions
                 const wait_time = this.browser_session?.browser_profile
                     ?.wait_between_actions || 0;
@@ -1350,9 +2007,15 @@ export class Agent {
             try {
                 this._throwIfAborted(signal);
                 await this._raise_if_stopped_or_paused();
+                const preActionPage = await this.browser_session.get_current_page?.();
+                const preActionUrl = typeof preActionPage?.url === 'function' ? preActionPage.url() : '';
+                const preActionFocusTargetId = this.browser_session.agent_focus_target_id ??
+                    this.browser_session.active_tab?.page_id ??
+                    null;
                 const actResult = await this.controller.registry.execute_action(actionName, actionParams, {
                     browser_session: this.browser_session,
                     page_extraction_llm: this.settings.page_extraction_llm,
+                    extraction_schema: this.extraction_schema,
                     sensitive_data: this.sensitive_data,
                     available_file_paths: this.available_file_paths,
                     file_system: this.file_system,
@@ -1369,6 +2032,24 @@ export class Agent {
                     this._capture_shared_pinned_tab();
                     break;
                 }
+                const registeredAction = this.controller.registry.get_action?.(actionName);
+                const terminatesSequence = Boolean(registeredAction?.terminates_sequence);
+                if (terminatesSequence) {
+                    this.logger.info(`Action "${actionName}" terminates sequence - skipping ${actions.length - i - 1} remaining action(s)`);
+                    this._capture_shared_pinned_tab();
+                    break;
+                }
+                const postActionPage = await this.browser_session.get_current_page?.();
+                const postActionUrl = typeof postActionPage?.url === 'function' ? postActionPage.url() : '';
+                const postActionFocusTargetId = this.browser_session.agent_focus_target_id ??
+                    this.browser_session.active_tab?.page_id ??
+                    null;
+                if (postActionUrl !== preActionUrl ||
+                    postActionFocusTargetId !== preActionFocusTargetId) {
+                    this.logger.info(`Page changed after "${actionName}" - skipping ${actions.length - i - 1} remaining action(s)`);
+                    this._capture_shared_pinned_tab();
+                    break;
+                }
                 this._capture_shared_pinned_tab();
             }
             catch (error) {
@@ -1380,102 +2061,723 @@ export class Agent {
         }
         return results;
     }
-    async rerun_history(history, options = {}) {
-        const { max_retries = 3, skip_failures = true, delay_between_actions = 2, signal = null, } = options;
-        this._throwIfAborted(signal);
-        if (this.initial_actions?.length) {
-            const initialResult = await this.multi_act(this.initial_actions, {
-                signal,
+    async _generate_rerun_summary(originalTask, results, summaryLlm = null, signal = null) {
+        if (!this.browser_session) {
+            return new ActionResult({
+                is_done: true,
+                success: false,
+                extracted_content: 'Rerun completed without an active browser session.',
+                long_term_memory: 'Rerun completed without an active browser session.',
             });
-            this.state.last_result = initialResult;
         }
-        const results = [];
-        for (let index = 0; index < history.history.length; index++) {
-            this._throwIfAborted(signal);
-            const historyItem = history.history[index];
-            const goal = historyItem.model_output?.current_state?.next_goal ?? '';
-            this.logger.info(`Replaying step ${index + 1}/${history.history.length}: goal: ${goal}`);
-            const actions = historyItem.model_output?.action ?? [];
-            const hasValidAction = actions.length && !actions.every((action) => action == null);
-            if (!historyItem.model_output || !hasValidAction) {
-                this.logger.warning(`Step ${index + 1}: No action to replay, skipping`);
-                results.push(new ActionResult({ error: 'No action to replay' }));
-                continue;
-            }
-            let attempt = 0;
-            while (attempt < max_retries) {
-                this._throwIfAborted(signal);
-                try {
-                    const stepResult = await this._execute_history_step(historyItem, delay_between_actions, signal);
-                    results.push(...stepResult);
-                    break;
-                }
-                catch (error) {
-                    if (signal?.aborted ||
-                        (error instanceof Error && error.name === 'AbortError')) {
-                        throw this._createAbortError();
-                    }
-                    attempt += 1;
-                    if (attempt === max_retries) {
-                        const message = `Step ${index + 1} failed after ${max_retries} attempts: ${error.message ?? error}`;
-                        this.logger.error(message);
-                        const failure = new ActionResult({ error: message });
-                        results.push(failure);
-                        if (!skip_failures) {
-                            throw new Error(message);
-                        }
-                    }
-                    else {
-                        this.logger.warning(`Step ${index + 1} failed (attempt ${attempt}/${max_retries}), retrying...`);
-                        await this._sleep(delay_between_actions, signal);
-                    }
-                }
-            }
+        let screenshotB64 = null;
+        try {
+            screenshotB64 = await this.browser_session.take_screenshot(false);
+        }
+        catch (error) {
+            this.logger.warning(`Failed to capture screenshot for rerun summary: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const errorCount = results.filter((result) => Boolean(result.error)).length;
+        const successCount = results.length - errorCount;
+        const prompt = get_rerun_summary_prompt(originalTask, results.length, successCount, errorCount);
+        const message = get_rerun_summary_message(prompt, screenshotB64);
+        const llm = summaryLlm ?? this.llm;
+        const parser = {
+            parse: (input) => z
+                .object({
+                summary: z.string(),
+                success: z.boolean(),
+                completion_status: z.enum(['complete', 'partial', 'failed']),
+            })
+                .parse(JSON.parse(input)),
+        };
+        try {
+            const response = await llm.ainvoke([message], parser, {
+                signal: signal ?? undefined,
+            });
+            const summary = response.completion;
+            if (!summary ||
+                typeof summary !== 'object' ||
+                typeof summary.summary !== 'string' ||
+                typeof summary.success !== 'boolean' ||
+                !['complete', 'partial', 'failed'].includes(String(summary.completion_status))) {
+                throw new Error('Structured rerun summary response did not match expected schema');
+            }
+            this.logger.info(`Rerun Summary: ${summary.summary}`);
+            this.logger.info(`Rerun Status: ${summary.completion_status} (success=${summary.success})`);
+            return new ActionResult({
+                is_done: true,
+                success: summary.success,
+                extracted_content: summary.summary,
+                long_term_memory: `Rerun completed with status: ${summary.completion_status}. ${summary.summary.slice(0, 100)}`,
+            });
+        }
+        catch (structuredError) {
+            this.logger.debug(`Structured rerun summary failed: ${structuredError instanceof Error
+                ? structuredError.message
+                : String(structuredError)}, falling back to text response`);
+        }
+        try {
+            const response = await llm.ainvoke([message], undefined, {
+                signal: signal ?? undefined,
+            });
+            const summaryText = typeof response.completion === 'string'
+                ? response.completion
+                : JSON.stringify(response.completion);
+            const completionStatus = errorCount === 0 ? 'complete' : successCount > 0 ? 'partial' : 'failed';
+            return new ActionResult({
+                is_done: true,
+                success: errorCount === 0,
+                extracted_content: summaryText,
+                long_term_memory: `Rerun completed with status: ${completionStatus}. ${summaryText.slice(0, 100)}`,
+            });
+        }
+        catch (error) {
+            this.logger.warning(`Failed to generate rerun summary: ${error instanceof Error ? error.message : String(error)}`);
+            return new ActionResult({
+                is_done: true,
+                success: errorCount === 0,
+                extracted_content: `Rerun completed: ${successCount}/${results.length} steps succeeded`,
+                long_term_memory: `Rerun completed: ${successCount} steps succeeded, ${errorCount} errors`,
+            });
         }
-        return results;
     }
-    async _execute_history_step(historyItem, delaySeconds, signal = null) {
-        this._throwIfAborted(signal);
+    async _execute_ai_step(query, includeScreenshot = false, extractLinks = false, aiStepLlm = null, signal = null) {
         if (!this.browser_session) {
-            throw new Error('BrowserSession is not set up');
-        }
-        const browser_state_summary = await this.browser_session.get_browser_state_with_recovery?.({
-            cache_clickable_elements_hashes: false,
-            include_screenshot: false,
-            signal,
-        });
-        if (!browser_state_summary || !historyItem.model_output) {
-            throw new Error('Invalid browser state or model output');
+            return new ActionResult({
+                error: 'AI step failed: BrowserSession missing',
+            });
         }
-        const interactedElements = historyItem.state?.interacted_element ?? [];
-        const updatedActions = [];
-        for (let actionIndex = 0; actionIndex < historyItem.model_output.action.length; actionIndex++) {
-            this._throwIfAborted(signal);
-            const originalAction = historyItem.model_output.action[actionIndex];
-            if (!originalAction) {
-                continue;
+        const llm = aiStepLlm ?? this.llm;
+        let content;
+        let statsSummary;
+        let currentUrl = '';
+        try {
+            const page = await this.browser_session.get_current_page?.();
+            if (!page || typeof page.content !== 'function') {
+                throw new Error('No page available for markdown extraction');
             }
-            const updatedAction = await this._update_action_indices(this._coerceHistoryElement(interactedElements[actionIndex]), originalAction, browser_state_summary);
+            if (typeof page.url === 'function') {
+                currentUrl = page.url();
+            }
+            const html = (await page.content()) || '';
+            const extracted = extractCleanMarkdownFromHtml(html, {
+                extract_links: extractLinks,
+            });
+            content = extracted.content;
+            const contentStats = extracted.stats;
+            statsSummary = `Content processed: ${contentStats.original_html_chars.toLocaleString()} HTML chars -> ${contentStats.initial_markdown_chars.toLocaleString()} initial markdown -> ${contentStats.final_filtered_chars.toLocaleString()} filtered markdown`;
+            if (contentStats.filtered_chars_removed > 0) {
+                statsSummary += ` (filtered ${contentStats.filtered_chars_removed.toLocaleString()} chars of noise)`;
+            }
+        }
+        catch (error) {
+            const name = error instanceof Error ? error.name : 'Error';
+            const message = error instanceof Error ? error.message : String(error);
+            return new ActionResult({
+                error: `Could not extract clean markdown: ${name}: ${message}`,
+            });
+        }
+        const safeContent = sanitize_surrogates(content);
+        const safeQuery = sanitize_surrogates(query);
+        const systemPrompt = get_ai_step_system_prompt();
+        const userPrompt = get_ai_step_user_prompt(safeQuery, statsSummary, safeContent);
+        let screenshotB64 = null;
+        if (includeScreenshot) {
+            try {
+                screenshotB64 =
+                    (await this.browser_session.take_screenshot?.(false)) ?? null;
+            }
+            catch (error) {
+                this.logger.warning(`Failed to capture screenshot for ai_step: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        const userMessage = screenshotB64
+            ? get_rerun_summary_message(userPrompt, screenshotB64)
+            : new UserMessage(userPrompt);
+        try {
+            const response = await llm.ainvoke([new SystemMessage(systemPrompt), userMessage], undefined, { signal: signal ?? undefined });
+            const completion = typeof response.completion === 'string'
+                ? response.completion
+                : JSON.stringify(response.completion);
+            const extractedContent = `<url>\n${currentUrl}\n</url>\n<query>\n${safeQuery}\n</query>\n<result>\n${completion}\n</result>`;
+            const maxMemoryLength = 1000;
+            if (extractedContent.length < maxMemoryLength) {
+                return new ActionResult({
+                    extracted_content: extractedContent,
+                    include_extracted_content_only_once: false,
+                    long_term_memory: extractedContent,
+                });
+            }
+            if (!this.file_system) {
+                return new ActionResult({
+                    extracted_content: extractedContent,
+                    include_extracted_content_only_once: false,
+                    long_term_memory: extractedContent.slice(0, maxMemoryLength),
+                });
+            }
+            const fileName = await this.file_system.save_extracted_content(extractedContent);
+            return new ActionResult({
+                extracted_content: extractedContent,
+                include_extracted_content_only_once: true,
+                long_term_memory: `Query: ${query}\nContent in ${fileName} and once in <read_state>.`,
+            });
+        }
+        catch (error) {
+            this.logger.warning(`Failed to execute AI step: ${error instanceof Error ? error.message : String(error)}`);
+            return new ActionResult({
+                error: `AI step failed: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
+    async rerun_history(history, options = {}) {
+        const { max_retries = 3, skip_failures = false, delay_between_actions = 2, max_step_interval = 45, wait_for_elements = false, summary_llm = null, ai_step_llm = null, signal = null, } = options;
+        this._throwIfAborted(signal);
+        // Mirror python c011 behavior: rerun should not emit create-session events.
+        this.state.session_initialized = true;
+        const results = [];
+        let previousItem = null;
+        let previousStepSucceeded = false;
+        try {
+            await this.browser_session?.start();
+            for (let index = 0; index < history.history.length; index++) {
+                this._throwIfAborted(signal);
+                const historyItem = history.history[index];
+                const goal = historyItem.model_output?.current_state?.next_goal ?? '';
+                const stepNumber = historyItem.metadata?.step_number ?? index;
+                const stepName = stepNumber === 0 ? 'Initial actions' : `Step ${stepNumber}`;
+                const savedInterval = historyItem.metadata?.step_interval;
+                let stepDelay = delay_between_actions;
+                let delaySource = `using default delay=${this._formatDelaySeconds(stepDelay)}`;
+                if (typeof savedInterval === 'number' &&
+                    Number.isFinite(savedInterval)) {
+                    stepDelay = Math.min(savedInterval, max_step_interval);
+                    if (savedInterval > max_step_interval) {
+                        delaySource = `capped to ${this._formatDelaySeconds(stepDelay)} (saved was ${savedInterval.toFixed(1)}s)`;
+                    }
+                    else {
+                        delaySource = `using saved step_interval=${this._formatDelaySeconds(stepDelay)}`;
+                    }
+                }
+                this.logger.info(`Replaying ${stepName} (${index + 1}/${history.history.length}) [${delaySource}]: ${goal}`);
+                const actions = historyItem.model_output?.action ?? [];
+                const hasValidAction = actions.length && !actions.every((action) => action == null);
+                if (!historyItem.model_output || !hasValidAction) {
+                    this.logger.warning(`${stepName}: No action to replay, skipping`);
+                    results.push(new ActionResult({ error: 'No action to replay' }));
+                    continue;
+                }
+                const originalErrors = Array.isArray(historyItem.result)
+                    ? historyItem.result
+                        .map((result) => result?.error)
+                        .filter((error) => typeof error === 'string')
+                    : [];
+                if (originalErrors.length && skip_failures) {
+                    const firstError = originalErrors[0] ?? 'unknown';
+                    const preview = firstError.length > 100
+                        ? `${firstError.slice(0, 100)}...`
+                        : firstError;
+                    this.logger.warning(`${stepName}: Original step had error(s), skipping (skip_failures=true): ${preview}`);
+                    results.push(new ActionResult({
+                        error: `Skipped - original step had error: ${preview}`,
+                    }));
+                    continue;
+                }
+                if (this._is_redundant_retry_step(historyItem, previousItem, previousStepSucceeded)) {
+                    this.logger.info(`${stepName}: Skipping redundant retry (previous step already succeeded with same element)`);
+                    results.push(new ActionResult({
+                        extracted_content: 'Skipped - redundant retry of previous step',
+                        include_in_memory: false,
+                    }));
+                    continue;
+                }
+                let attempt = 0;
+                let stepSucceeded = false;
+                let menuReopened = false;
+                while (attempt < max_retries) {
+                    this._throwIfAborted(signal);
+                    try {
+                        const stepResult = ai_step_llm != null
+                            ? await this._execute_history_step(historyItem, stepDelay, signal, wait_for_elements, ai_step_llm)
+                            : await this._execute_history_step(historyItem, stepDelay, signal, wait_for_elements);
+                        results.push(...stepResult);
+                        stepSucceeded = true;
+                        break;
+                    }
+                    catch (error) {
+                        const errorMessage = error instanceof Error ? error.message : String(error);
+                        if (signal?.aborted ||
+                            (error instanceof Error && error.name === 'AbortError')) {
+                            throw this._createAbortError();
+                        }
+                        attempt += 1;
+                        if (!menuReopened &&
+                            errorMessage.includes('Could not find matching element') &&
+                            previousItem &&
+                            this._is_menu_opener_step(previousItem)) {
+                            const currentElement = this._coerceHistoryElement(historyItem.state?.interacted_element?.[0]);
+                            if (this._is_menu_item_element(currentElement)) {
+                                this.logger.info('Dropdown may have closed. Attempting to re-open by re-executing previous step...');
+                                const reopened = await this._reexecute_menu_opener(previousItem, signal, ai_step_llm);
+                                if (reopened) {
+                                    menuReopened = true;
+                                    attempt -= 1;
+                                    stepDelay = 0.5;
+                                    this.logger.info('Dropdown re-opened, retrying element match...');
+                                    continue;
+                                }
+                            }
+                        }
+                        if (attempt === max_retries) {
+                            const message = `${stepName} failed after ${max_retries} attempts: ${errorMessage}`;
+                            this.logger.error(message);
+                            const failure = new ActionResult({ error: message });
+                            results.push(failure);
+                            if (!skip_failures) {
+                                throw new Error(message, { cause: error });
+                            }
+                        }
+                        else {
+                            const retryDelay = Math.min(5 * 2 ** Math.max(attempt - 1, 0), 30);
+                            this.logger.warning(`${stepName} failed (attempt ${attempt}/${max_retries}), retrying in ${retryDelay}s...`);
+                            await this._sleep(retryDelay, signal);
+                        }
+                    }
+                }
+                previousItem = historyItem;
+                previousStepSucceeded = stepSucceeded;
+            }
+            const summaryResult = await this._generate_rerun_summary(this.task, results, summary_llm, signal);
+            results.push(summaryResult);
+            return results;
+        }
+        finally {
+            await this.close();
+        }
+    }
+    async _execute_history_step(historyItem, delaySeconds, signal = null, wait_for_elements = false, ai_step_llm = null) {
+        this._throwIfAborted(signal);
+        if (!this.browser_session) {
+            throw new Error('BrowserSession is not set up');
+        }
+        await this._sleep(delaySeconds, signal);
+        const interactedElements = historyItem.state?.interacted_element ?? [];
+        let browser_state_summary = null;
+        if (wait_for_elements) {
+            const needsElementMatching = this._historyStepNeedsElementMatching(historyItem, interactedElements);
+            if (needsElementMatching) {
+                const minElements = this._countExpectedElementsFromHistory(historyItem);
+                if (minElements > 0) {
+                    browser_state_summary = await this._waitForMinimumElements(minElements, 15, 1, signal);
+                }
+            }
+        }
+        if (!browser_state_summary) {
+            browser_state_summary =
+                await this.browser_session.get_browser_state_with_recovery?.({
+                    cache_clickable_elements_hashes: false,
+                    include_screenshot: false,
+                    signal,
+                });
+        }
+        if (!browser_state_summary || !historyItem.model_output) {
+            throw new Error('Invalid browser state or model output');
+        }
+        const results = [];
+        const pendingActions = [];
+        for (let actionIndex = 0; actionIndex < historyItem.model_output.action.length; actionIndex++) {
+            this._throwIfAborted(signal);
+            const originalAction = historyItem.model_output.action[actionIndex];
+            if (!originalAction) {
+                continue;
+            }
+            const actionPayload = typeof originalAction?.model_dump === 'function'
+                ? originalAction.model_dump({ exclude_unset: true })
+                : originalAction;
+            const actionName = Object.keys(actionPayload ?? {})[0] ?? null;
+            if (actionName &&
+                ['extract', 'extract_structured_data', 'extract_content'].includes(actionName)) {
+                if (pendingActions.length > 0) {
+                    this._throwIfAborted(signal);
+                    const batchActions = [...pendingActions];
+                    pendingActions.length = 0;
+                    const batchResults = await this.multi_act(batchActions, { signal });
+                    results.push(...batchResults);
+                }
+                const params = actionPayload[actionName] ?? {};
+                const query = typeof params.query === 'string' ? params.query : '';
+                const extractLinks = Boolean(params.extract_links);
+                this.logger.info(`Using AI step for extract action: ${query.slice(0, 50)}...`);
+                const aiResult = await this._execute_ai_step(query, false, extractLinks, ai_step_llm, signal);
+                results.push(aiResult);
+                continue;
+            }
+            const updatedAction = await this._update_action_indices(this._coerceHistoryElement(interactedElements[actionIndex]), originalAction, browser_state_summary);
             if (!updatedAction) {
-                throw new Error(`Could not find matching element ${actionIndex} in current page`);
+                const historicalElement = this._coerceHistoryElement(interactedElements[actionIndex]);
+                const selectorCount = Object.keys(browser_state_summary.selector_map ?? {}).length;
+                throw new Error(`Could not find matching element for action ${actionIndex} in current page.\n` +
+                    `  Looking for: ${this._formatHistoryElementForError(historicalElement)}\n` +
+                    `  Page has ${selectorCount} interactive elements.\n` +
+                    '  Tried: EXACT hash → STABLE hash → XPATH → AX_NAME → ATTRIBUTE matching');
             }
             if (typeof updatedAction?.model_dump === 'function') {
-                updatedActions.push(updatedAction.model_dump({ exclude_unset: true }));
+                pendingActions.push(updatedAction.model_dump({ exclude_unset: true }));
             }
             else {
-                updatedActions.push(updatedAction);
+                pendingActions.push(updatedAction);
             }
         }
-        this._throwIfAborted(signal);
-        const result = await this.multi_act(updatedActions, { signal });
-        await this._sleep(delaySeconds, signal);
-        return result;
+        if (pendingActions.length > 0) {
+            this._throwIfAborted(signal);
+            const batchActions = [...pendingActions];
+            pendingActions.length = 0;
+            const batchResults = await this.multi_act(batchActions, { signal });
+            results.push(...batchResults);
+        }
+        return results;
+    }
+    _historyStepNeedsElementMatching(historyItem, interactedElements) {
+        const actions = historyItem.model_output?.action ?? [];
+        for (let index = 0; index < actions.length; index++) {
+            const action = actions[index];
+            if (!action) {
+                continue;
+            }
+            const payload = typeof action.model_dump === 'function'
+                ? action.model_dump({ exclude_unset: true })
+                : action;
+            const actionName = Object.keys(payload ?? {})[0] ?? null;
+            if (!actionName) {
+                continue;
+            }
+            if ([
+                'click',
+                'input',
+                'input_text',
+                'hover',
+                'select_option',
+                'select_dropdown_option',
+                'drag_and_drop',
+            ].includes(actionName)) {
+                const historicalElement = this._coerceHistoryElement(interactedElements[index] ?? null);
+                if (historicalElement) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    _countExpectedElementsFromHistory(historyItem) {
+        if (!historyItem.model_output?.action?.length) {
+            return 0;
+        }
+        let maxIndex = -1;
+        for (const action of historyItem.model_output.action) {
+            const index = this._extractActionIndex(action);
+            if (index != null) {
+                maxIndex = Math.max(maxIndex, index);
+            }
+        }
+        if (maxIndex < 0) {
+            return 0;
+        }
+        return Math.min(maxIndex + 1, 50);
+    }
+    async _waitForMinimumElements(minElements, timeoutSeconds = 30, pollIntervalSeconds = 1, signal = null) {
+        if (!this.browser_session) {
+            return null;
+        }
+        const start = Date.now();
+        let lastCount = 0;
+        let lastState = null;
+        while ((Date.now() - start) / 1000 < timeoutSeconds) {
+            this._throwIfAborted(signal);
+            const state = await this.browser_session.get_browser_state_with_recovery?.({
+                cache_clickable_elements_hashes: false,
+                include_screenshot: false,
+                signal,
+            });
+            lastState = state ?? null;
+            const currentCount = Object.keys(state?.selector_map ?? {}).length;
+            if (currentCount >= minElements) {
+                this.logger.debug(`Page has ${currentCount} interactive elements (needed ${minElements}), proceeding`);
+                return state;
+            }
+            if (currentCount !== lastCount) {
+                const remaining = Math.max(0, timeoutSeconds - (Date.now() - start) / 1000);
+                this.logger.debug(`Waiting for elements: ${currentCount}/${minElements} (timeout in ${remaining.toFixed(1)}s)`);
+                lastCount = currentCount;
+            }
+            await this._sleep(pollIntervalSeconds, signal);
+        }
+        this.logger.warning(`Timeout waiting for ${minElements} elements, proceeding with ${lastCount} elements`);
+        return lastState;
+    }
+    _extractActionIndex(action) {
+        if (action && typeof action.get_index === 'function') {
+            const index = action.get_index();
+            if (typeof index === 'number' && Number.isFinite(index)) {
+                return index;
+            }
+        }
+        if (!action || typeof action !== 'object') {
+            return null;
+        }
+        const modelDump = typeof action.model_dump === 'function'
+            ? action.model_dump()
+            : action;
+        if (!modelDump ||
+            typeof modelDump !== 'object' ||
+            Array.isArray(modelDump)) {
+            return null;
+        }
+        const actionName = Object.keys(modelDump)[0];
+        if (!actionName) {
+            return null;
+        }
+        const params = modelDump[actionName];
+        const index = params?.index;
+        return typeof index === 'number' && Number.isFinite(index) ? index : null;
+    }
+    _extractActionType(action) {
+        if (!action || typeof action !== 'object') {
+            return null;
+        }
+        const modelDump = typeof action.model_dump === 'function'
+            ? action.model_dump()
+            : action;
+        if (!modelDump ||
+            typeof modelDump !== 'object' ||
+            Array.isArray(modelDump)) {
+            return null;
+        }
+        const actionName = Object.keys(modelDump)[0];
+        return actionName ?? null;
+    }
+    _sameHistoryElement(current, previous) {
+        if (!current || !previous) {
+            return false;
+        }
+        if (current.element_hash &&
+            previous.element_hash &&
+            current.element_hash === previous.element_hash) {
+            return true;
+        }
+        if (current.stable_hash &&
+            previous.stable_hash &&
+            current.stable_hash === previous.stable_hash) {
+            return true;
+        }
+        if (current.xpath && previous.xpath && current.xpath === previous.xpath) {
+            return true;
+        }
+        if (current.tag_name &&
+            previous.tag_name &&
+            current.tag_name === previous.tag_name) {
+            for (const key of ['name', 'id', 'aria-label']) {
+                const currentValue = current.attributes?.[key];
+                const previousValue = previous.attributes?.[key];
+                if (currentValue &&
+                    previousValue &&
+                    String(currentValue) === String(previousValue)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    _is_redundant_retry_step(currentItem, previousItem, previousStepSucceeded) {
+        if (!previousItem || !previousStepSucceeded) {
+            return false;
+        }
+        const currentActions = currentItem.model_output?.action ?? [];
+        const previousActions = previousItem.model_output?.action ?? [];
+        if (!currentActions.length || !previousActions.length) {
+            return false;
+        }
+        const currentActionType = this._extractActionType(currentActions[0]);
+        const previousActionType = this._extractActionType(previousActions[0]);
+        if (!currentActionType || currentActionType !== previousActionType) {
+            return false;
+        }
+        const currentElement = this._coerceHistoryElement(currentItem.state?.interacted_element?.[0]);
+        const previousElement = this._coerceHistoryElement(previousItem.state?.interacted_element?.[0]);
+        if (!this._sameHistoryElement(currentElement, previousElement)) {
+            return false;
+        }
+        this.logger.debug(`Detected redundant retry on same element with action "${currentActionType}"`);
+        return true;
+    }
+    _is_menu_opener_step(historyItem) {
+        const element = this._coerceHistoryElement(historyItem?.state?.interacted_element?.[0]);
+        if (!element) {
+            return false;
+        }
+        const attrs = element.attributes ?? {};
+        if (['true', 'menu', 'listbox'].includes(String(attrs['aria-haspopup']))) {
+            return true;
+        }
+        if (attrs['data-gw-click'] === 'toggleSubMenu') {
+            return true;
+        }
+        if (String(attrs.class ?? '').includes('expand-button')) {
+            return true;
+        }
+        if (attrs.role === 'menuitem' &&
+            ['false', 'true'].includes(String(attrs['aria-expanded']))) {
+            return true;
+        }
+        if (attrs.role === 'button' &&
+            ['false', 'true'].includes(String(attrs['aria-expanded']))) {
+            return true;
+        }
+        return false;
+    }
+    _is_menu_item_element(element) {
+        if (!element) {
+            return false;
+        }
+        const attrs = element.attributes ?? {};
+        const role = String(attrs.role ?? '');
+        if ([
+            'menuitem',
+            'option',
+            'menuitemcheckbox',
+            'menuitemradio',
+            'treeitem',
+        ].includes(role)) {
+            return true;
+        }
+        const className = String(attrs.class ?? '');
+        if (className.includes('gw-action--inner')) {
+            return true;
+        }
+        if (className.toLowerCase().includes('menuitem')) {
+            return true;
+        }
+        if (element.ax_name && element.ax_name.trim()) {
+            const lowered = className.toLowerCase();
+            if (['dropdown', 'popup', 'menu', 'submenu', 'action'].some((needle) => lowered.includes(needle))) {
+                return true;
+            }
+        }
+        return false;
+    }
+    async _reexecute_menu_opener(openerItem, signal = null, aiStepLlm = null) {
+        try {
+            this.logger.info('Re-opening dropdown/menu by re-executing previous step...');
+            await this._execute_history_step(openerItem, 0.5, signal, false, aiStepLlm);
+            await this._sleep(0.3, signal);
+            return true;
+        }
+        catch (error) {
+            this.logger.warning(`Failed to re-open dropdown: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    }
+    _formatHistoryElementForError(element) {
+        if (!element) {
+            return '<no element recorded>';
+        }
+        const parts = [`<${element.tag_name || 'unknown'}>`];
+        for (const key of ['name', 'id', 'aria-label', 'type']) {
+            const value = element.attributes?.[key];
+            if (typeof value === 'string' && value.trim()) {
+                parts.push(`${key}="${value}"`);
+            }
+        }
+        if (element.xpath) {
+            const xpath = element.xpath.length > 60
+                ? `...${element.xpath.slice(-57)}`
+                : element.xpath;
+            parts.push(`xpath="${xpath}"`);
+        }
+        if (element.element_hash) {
+            parts.push(`hash=${element.element_hash}`);
+        }
+        if (element.stable_hash) {
+            parts.push(`stable_hash=${element.stable_hash}`);
+        }
+        return parts.join(' ');
     }
     async _update_action_indices(historicalElement, action, browserStateSummary) {
-        if (!historicalElement || !browserStateSummary?.element_tree) {
+        if (!historicalElement || !browserStateSummary?.selector_map) {
             return action;
         }
-        const currentNode = HistoryTreeProcessor.find_history_element_in_tree(historicalElement, browserStateSummary.element_tree);
+        const selectorMap = browserStateSummary.selector_map ?? {};
+        if (!Object.keys(selectorMap).length) {
+            return action;
+        }
+        let matchLevel = null;
+        let currentNode = null;
+        if (historicalElement.element_hash) {
+            for (const node of Object.values(selectorMap)) {
+                const nodeHash = HistoryTreeProcessor.compute_element_hash(node);
+                if (nodeHash === historicalElement.element_hash) {
+                    currentNode = node;
+                    matchLevel = 'EXACT';
+                    break;
+                }
+            }
+        }
+        if (!currentNode && historicalElement.stable_hash) {
+            for (const node of Object.values(selectorMap)) {
+                const stableHash = HistoryTreeProcessor.compute_stable_hash(node);
+                if (stableHash === historicalElement.stable_hash) {
+                    currentNode = node;
+                    matchLevel = 'STABLE';
+                    this.logger.info('Element matched at STABLE hash fallback');
+                    break;
+                }
+            }
+        }
+        if (!currentNode && historicalElement.xpath) {
+            for (const node of Object.values(selectorMap)) {
+                if (node?.xpath === historicalElement.xpath) {
+                    currentNode = node;
+                    matchLevel = 'XPATH';
+                    this.logger.info(`Element matched at XPATH fallback: ${historicalElement.xpath}`);
+                    break;
+                }
+            }
+        }
+        if (!currentNode && historicalElement.ax_name) {
+            const tagName = historicalElement.tag_name?.toLowerCase();
+            const targetAxName = historicalElement.ax_name;
+            for (const node of Object.values(selectorMap)) {
+                const nodeAxName = HistoryTreeProcessor.get_accessible_name(node);
+                if (node?.tag_name?.toLowerCase() === tagName &&
+                    typeof nodeAxName === 'string' &&
+                    nodeAxName === targetAxName) {
+                    currentNode = node;
+                    matchLevel = 'AX_NAME';
+                    this.logger.info(`Element matched at AX_NAME fallback: ${targetAxName}`);
+                    break;
+                }
+            }
+        }
+        if (!currentNode && historicalElement.attributes) {
+            const tagName = historicalElement.tag_name?.toLowerCase();
+            for (const attrKey of ['name', 'id', 'aria-label']) {
+                const attrValue = historicalElement.attributes[attrKey];
+                if (!attrValue) {
+                    continue;
+                }
+                for (const node of Object.values(selectorMap)) {
+                    if (node?.tag_name?.toLowerCase() === tagName &&
+                        node?.attributes?.[attrKey] === attrValue) {
+                        currentNode = node;
+                        matchLevel = 'ATTRIBUTE';
+                        this.logger.info(`Element matched via ${attrKey} attribute fallback: ${attrValue}`);
+                        break;
+                    }
+                }
+                if (currentNode) {
+                    break;
+                }
+            }
+        }
         if (!currentNode || currentNode.highlight_index == null) {
             return null;
         }
@@ -1483,18 +2785,25 @@ export class Agent {
         if (currentIndex !== currentNode.highlight_index &&
             typeof action?.set_index === 'function') {
             action.set_index(currentNode.highlight_index);
-            this.logger.info(`Element moved in DOM, updated index from ${currentIndex} to ${currentNode.highlight_index}`);
+            this.logger.info(`Element moved in DOM, updated index from ${currentIndex} to ${currentNode.highlight_index} (matched at ${matchLevel ?? 'UNKNOWN'} level)`);
         }
         return action;
     }
     async load_and_rerun(history_file = null, options = {}) {
+        const { variables = null, ...rerunOptions } = options;
         const target = history_file ?? 'AgentHistory.json';
         const history = AgentHistoryList.load_from_file(target, this.AgentOutput);
-        return this.rerun_history(history, options);
+        const substitutedHistory = variables
+            ? this._substitute_variables_in_history(history, variables)
+            : history;
+        return this.rerun_history(substitutedHistory, rerunOptions);
+    }
+    detect_variables() {
+        return detect_variables_in_history(this.history);
     }
     save_history(file_path = null) {
         const target = file_path ?? 'AgentHistory.json';
-        this.history.save_to_file(target);
+        this.history.save_to_file(target, this.sensitive_data ?? null);
     }
     _coerceHistoryElement(element) {
         if (!element) {
@@ -1504,7 +2813,69 @@ export class Agent {
             return element;
         }
         const payload = element;
-        return new DOMHistoryElement(payload.tag_name ?? '', payload.xpath ?? '', payload.highlight_index ?? null, payload.entire_parent_branch_path ?? [], payload.attributes ?? {}, payload.shadow_root ?? false, payload.css_selector ?? null, payload.page_coordinates ?? null, payload.viewport_coordinates ?? null, payload.viewport_info ?? null);
+        return new DOMHistoryElement(payload.tag_name ?? '', payload.xpath ?? '', payload.highlight_index ?? null, payload.entire_parent_branch_path ?? [], payload.attributes ?? {}, payload.shadow_root ?? false, payload.css_selector ?? null, payload.page_coordinates ?? null, payload.viewport_coordinates ?? null, payload.viewport_info ?? null, payload.element_hash != null ? String(payload.element_hash) : null, payload.stable_hash != null ? String(payload.stable_hash) : null, payload.ax_name != null ? String(payload.ax_name) : null);
+    }
+    _substitute_variables_in_history(history, variables) {
+        const detectedVars = detect_variables_in_history(history);
+        const valueReplacements = {};
+        for (const [varName, newValue] of Object.entries(variables)) {
+            const detected = detectedVars[varName];
+            if (!detected) {
+                this.logger.warning(`Variable "${varName}" not found in history, skipping substitution`);
+                continue;
+            }
+            valueReplacements[detected.original_value] = newValue;
+        }
+        if (!Object.keys(valueReplacements).length) {
+            this.logger.info('No variables to substitute');
+            return history;
+        }
+        const clonedHistory = this._clone_history_for_substitution(history);
+        let substitutionCount = 0;
+        for (const historyItem of clonedHistory.history) {
+            if (!historyItem.model_output?.action?.length) {
+                continue;
+            }
+            for (let actionIndex = 0; actionIndex < historyItem.model_output.action.length; actionIndex += 1) {
+                const action = historyItem.model_output.action[actionIndex];
+                const actionPayload = typeof action.model_dump === 'function'
+                    ? action.model_dump()
+                    : action;
+                if (!actionPayload ||
+                    typeof actionPayload !== 'object' ||
+                    Array.isArray(actionPayload)) {
+                    continue;
+                }
+                substitutionCount += substitute_in_dict(actionPayload, valueReplacements);
+                const ActionCtor = action?.constructor;
+                if (typeof ActionCtor === 'function') {
+                    historyItem.model_output.action[actionIndex] = new ActionCtor(actionPayload);
+                }
+                else {
+                    historyItem.model_output.action[actionIndex] = actionPayload;
+                }
+            }
+        }
+        this.logger.info(`Substituted ${substitutionCount} value(s) in ${Object.keys(valueReplacements).length} variable type(s) in history`);
+        return clonedHistory;
+    }
+    _clone_history_for_substitution(history) {
+        const payload = history.toJSON();
+        const historyItems = (payload.history ?? []).map((entry) => {
+            const modelOutput = entry.model_output
+                ? this.AgentOutput.fromJSON(entry.model_output)
+                : null;
+            const result = (entry.result ?? []).map((item) => new ActionResult(item));
+            const interacted = Array.isArray(entry.state?.interacted_element)
+                ? entry.state.interacted_element.map((element) => this._coerceHistoryElement(element))
+                : [];
+            const state = new BrowserStateHistory(entry.state?.url ?? '', entry.state?.title ?? '', entry.state?.tabs ?? [], interacted, entry.state?.screenshot_path ?? null);
+            const metadata = entry.metadata
+                ? new StepMetadata(entry.metadata.step_start_time, entry.metadata.step_end_time, entry.metadata.step_number, entry.metadata.step_interval ?? null)
+                : null;
+            return new AgentHistory(modelOutput, result, state, metadata, entry.state_message ?? null);
+        });
+        return new AgentHistoryList(historyItems, history.usage ?? null);
     }
     _createAbortError() {
         const error = new Error('Operation aborted');
@@ -1528,6 +2899,12 @@ export class Agent {
         signal.addEventListener('abort', handleAbort, { once: true });
         return () => signal.removeEventListener('abort', handleAbort);
     }
+    _formatDelaySeconds(delaySeconds) {
+        if (delaySeconds < 1) {
+            return `${Math.round(delaySeconds * 1000)}ms`;
+        }
+        return `${delaySeconds.toFixed(1)}s`;
+    }
     async _sleep(seconds, signal = null) {
         if (seconds <= 0) {
             return;
@@ -1595,28 +2972,37 @@ export class Agent {
             await this._closePromise;
             return;
         }
-        const browser_session = this.browser_session;
-        if (!browser_session) {
-            return;
-        }
         this._closePromise = (async () => {
-            this._release_browser_session_claim(browser_session);
-            if (this._has_any_browser_session_attachments(browser_session)) {
-                this.logger.debug('Skipping BrowserSession shutdown because other attached Agents are still active.');
-                return;
-            }
-            this._cleanup_shared_session_step_lock_if_unused(browser_session);
+            const browser_session = this.browser_session;
             try {
-                if (typeof browser_session.stop === 'function') {
-                    await browser_session.stop();
-                }
-                else if (typeof browser_session.close === 'function') {
-                    await browser_session.close();
+                if (browser_session) {
+                    this._release_browser_session_claim(browser_session);
+                    if (this._has_any_browser_session_attachments(browser_session)) {
+                        this.logger.debug('Skipping BrowserSession shutdown because other attached Agents are still active.');
+                    }
+                    else {
+                        this._cleanup_shared_session_step_lock_if_unused(browser_session);
+                        if (typeof browser_session.stop === 'function') {
+                            await browser_session.stop();
+                        }
+                        else if (typeof browser_session.close === 'function') {
+                            await browser_session.close();
+                        }
+                    }
                 }
             }
             catch (error) {
                 this.logger.error(`Error during agent cleanup: ${error instanceof Error ? error.message : String(error)}`);
             }
+            if (this.skill_service &&
+                typeof this.skill_service.close === 'function') {
+                try {
+                    await this.skill_service.close();
+                }
+                catch (error) {
+                    this.logger.error(`Error during skill service cleanup: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
         })();
         await this._closePromise;
     }
@@ -1700,15 +3086,43 @@ export class Agent {
         };
         return { trace, trace_details };
     }
-    _log_agent_run() {
-        this.logger.info(`🧠 Starting agent for task: ${this.task}`);
+    async _log_agent_run() {
+        this.logger.info(`\x1b[34m🎯 Task: ${this.task}\x1b[0m`);
+        this.logger.debug(`🤖 Browser-Use Library Version ${this.version} (${this.source})`);
+        if (CONFIG.BROWSER_USE_VERSION_CHECK &&
+            process.env.NODE_ENV !== 'test' &&
+            !process.env.VITEST) {
+            const latestVersion = await check_latest_browser_use_version();
+            if (latestVersion && latestVersion !== this.version) {
+                this.logger.info(`📦 Newer version available: ${latestVersion} (current: ${this.version}). Upgrade with: npm install browser-use@${latestVersion}`);
+            }
+        }
     }
-    _raise_if_stopped_or_paused() {
+    _createInterruptedError(message = '') {
+        const interruptedError = new Error(message);
+        interruptedError.name = 'InterruptedError';
+        return interruptedError;
+    }
+    async _raise_if_stopped_or_paused() {
+        if (this.register_should_stop_callback) {
+            const shouldStop = await this.register_should_stop_callback();
+            if (shouldStop) {
+                this.logger.info('External callback requested stop');
+                this.state.stopped = true;
+                throw this._createInterruptedError();
+            }
+        }
+        if (this.register_external_agent_status_raise_error_callback) {
+            const shouldRaise = await this.register_external_agent_status_raise_error_callback();
+            if (shouldRaise) {
+                throw this._createInterruptedError();
+            }
+        }
         if (this.state.stopped) {
-            throw new Error('Agent stopped');
+            throw this._createInterruptedError('Agent stopped');
         }
         if (this.state.paused) {
-            throw new Error('Agent paused');
+            throw this._createInterruptedError('Agent paused');
         }
     }
     async _handle_post_llm_processing(browser_state_summary, input_messages, _actions = []) {
@@ -1726,159 +3140,40 @@ export class Agent {
             }, null, 2), this.settings.save_conversation_path_encoding);
         }
     }
-    /**
-     * Handle all types of errors that can occur during a step
-     * Implements comprehensive error categorization with:
-     * - Validation error hints
-     * - Rate limit auto-retry
-     * - Parse error guidance
-     * - Token limit warnings
-     * - Network error detection
-     * - Browser error handling
-     * - LLM-specific errors
-     */
+    /** Handle all types of errors that can occur during a step (python c011 parity). */
     async _handle_step_error(error) {
+        if (error?.name === 'InterruptedError') {
+            const message = error.message
+                ? `The agent was interrupted mid-step - ${error.message}`
+                : 'The agent was interrupted mid-step';
+            this.logger.warning(message);
+            return;
+        }
         const include_trace = this.logger.level === 'debug';
-        let error_msg = AgentError.format_error(error, include_trace);
-        const prefix = `❌ Result failed ${this.state.consecutive_failures + 1}/${this.settings.max_failures} times:\n `;
+        const error_msg = AgentError.format_error(error, include_trace);
+        const maxTotalFailures = this._max_total_failures();
+        const prefix = `❌ Result failed ${this.state.consecutive_failures + 1}/${maxTotalFailures} times: `;
         this.state.consecutive_failures += 1;
-        // 1. Handle Validation Errors (Pydantic/Zod)
-        if (error.name === 'ValidationError' ||
-            error.name === 'ZodError' ||
-            error instanceof TypeError) {
-            this.logger.error(`${prefix}${error_msg}`);
-            // Add context hint for validation errors
-            if (error_msg.includes('Max token limit reached') ||
-                error_msg.includes('token')) {
-                error_msg +=
-                    '\n\n💡 Hint: Your response was too long. Keep your thinking and output concise.';
+        const isFinalFailure = this.state.consecutive_failures >= maxTotalFailures;
+        const isParseError = error_msg.includes('Could not parse response') ||
+            error_msg.includes('tool_use_failed');
+        if (isParseError) {
+            const parseLog = `Model: ${this.llm.model} failed`;
+            if (isFinalFailure) {
+                this.logger.error(parseLog);
             }
             else {
-                error_msg +=
-                    '\n\n💡 Hint: Your output format was invalid. Please follow the exact schema structure required for actions.';
+                this.logger.warning(parseLog);
             }
         }
-        // 2. Handle Interrupted Errors
-        else if (error.message.includes('interrupted') ||
-            error.message.includes('abort') ||
-            error.message.includes('InterruptedError')) {
-            error_msg = `The agent was interrupted mid-step${error.message ? ` - ${error.message}` : ''}`;
-            this.logger.error(`${prefix}${error_msg}`);
-        }
-        // 3. Handle Parse Errors
-        else if (error_msg.includes('Could not parse') ||
-            error_msg.includes('tool_use_failed') ||
-            error_msg.includes('Failed to parse')) {
-            this.logger.debug(`Model: ${this.llm.model} failed to parse response`);
-            error_msg +=
-                '\n\n💡 Hint: Return a valid JSON object with the required fields.';
-            this.logger.error(`${prefix}${error_msg}`);
-        }
-        // 4. Handle Rate Limit Errors (OpenAI, Anthropic, Google)
-        else if (this._isRateLimitError(error, error_msg)) {
-            this.logger.warning(`${prefix}${error_msg}`);
-            this.logger.warning(`⏳ Rate limit detected, waiting ${this.settings.retry_delay}s before retrying...`);
-            // Auto-retry: wait before continuing
-            await this._sleep(this.settings.retry_delay);
-            error_msg += `\n\n⏳ Retrying after ${this.settings.retry_delay}s delay...`;
-        }
-        // 5. Handle Network Errors
-        else if (this._isNetworkError(error, error_msg)) {
-            this.logger.error(`${prefix}${error_msg}`);
-            error_msg +=
-                '\n\n🌐 Network error detected. Please check your internet connection and try again.';
-        }
-        // 6. Handle Browser Errors
-        else if (this._isBrowserError(error, error_msg)) {
-            this.logger.error(`${prefix}${error_msg}`);
-            error_msg +=
-                '\n\n🌍 Browser error detected. The page may have crashed or become unresponsive.';
-        }
-        // 7. Handle Timeout Errors
-        else if (this._isTimeoutError(error, error_msg)) {
+        if (isFinalFailure) {
             this.logger.error(`${prefix}${error_msg}`);
-            error_msg +=
-                '\n\n⏱️ Timeout error. The operation took too long to complete.';
         }
-        // 8. Handle All Other Errors
         else {
-            this.logger.error(`${prefix}${error_msg}`);
+            this.logger.warning(`${prefix}${error_msg}`);
         }
         this.state.last_result = [new ActionResult({ error: error_msg })];
     }
-    /**
-     * Check if an error is a network error
-     */
-    _isNetworkError(error, error_msg) {
-        const networkPatterns = [
-            'ECONNREFUSED',
-            'ENOTFOUND',
-            'ETIMEDOUT',
-            'ECONNRESET',
-            'network error',
-            'Network Error',
-            'fetch failed',
-            'socket hang up',
-            'getaddrinfo',
-        ];
-        return networkPatterns.some((pattern) => error_msg.includes(pattern) || error.message.includes(pattern));
-    }
-    /**
-     * Check if an error is a browser/Playwright error
-     */
-    _isBrowserError(error, error_msg) {
-        const browserPatterns = [
-            'Target page',
-            'Page crashed',
-            'Browser closed',
-            'Context closed',
-            'Frame detached',
-            'Execution context',
-            'Navigation failed',
-            'Protocol error',
-        ];
-        return browserPatterns.some((pattern) => error_msg.includes(pattern) || error.message.includes(pattern));
-    }
-    /**
-     * Check if an error is a timeout error
-     */
-    _isTimeoutError(error, error_msg) {
-        const timeoutPatterns = [
-            'timeout',
-            'Timeout',
-            'timed out',
-            'time limit exceeded',
-            'deadline exceeded',
-        ];
-        return timeoutPatterns.some((pattern) => error_msg.toLowerCase().includes(pattern.toLowerCase()));
-    }
-    /**
-     * Check if an error is a rate limit error from various LLM providers
-     */
-    _isRateLimitError(error, error_msg) {
-        // Check error class name
-        const errorClassName = error.constructor.name;
-        if (errorClassName === 'RateLimitError' ||
-            errorClassName === 'ResourceExhausted') {
-            return true;
-        }
-        // Check error message patterns
-        const rateLimitPatterns = [
-            'rate_limit_exceeded',
-            'rate limit exceeded',
-            'RateLimitError',
-            'RESOURCE_EXHAUSTED',
-            'ResourceExhausted',
-            'tokens per minute',
-            'TPM',
-            'requests per minute',
-            'RPM',
-            'quota exceeded',
-            'too many requests',
-            '429',
-        ];
-        return rateLimitPatterns.some((pattern) => error_msg.toLowerCase().includes(pattern.toLowerCase()));
-    }
     async _finalize(browser_state_summary) {
         const step_end_time = Date.now() / 1000;
         this._enforceDoneOnlyForCurrentStep = false;
@@ -1886,8 +3181,15 @@ export class Agent {
             return;
         }
         if (browser_state_summary) {
-            const metadata = new StepMetadata(this.step_start_time, step_end_time, this.state.n_steps);
-            await this._make_history_item(this.state.last_model_output, browser_state_summary, this.state.last_result, metadata);
+            let stepInterval = null;
+            if (this.history.history.length > 0) {
+                const lastMetadata = this.history.history.at(-1)?.metadata;
+                if (lastMetadata) {
+                    stepInterval = Math.max(0, lastMetadata.step_end_time - lastMetadata.step_start_time);
+                }
+            }
+            const metadata = new StepMetadata(this.step_start_time, step_end_time, this.state.n_steps, stepInterval);
+            await this._make_history_item(this.state.last_model_output, browser_state_summary, this.state.last_result, metadata, this._message_manager.last_state_message_text);
         }
         this._log_step_completion_summary(this.step_start_time, this.state.last_result);
         this.save_file_system_state();
@@ -1904,14 +3206,388 @@ export class Agent {
         const isLastStep = Boolean(step_info && step_info.is_last_step());
         this._enforceDoneOnlyForCurrentStep = isLastStep;
         if (isLastStep) {
-            const message = 'Now comes your last step. Use only the "done" action now. No other actions - so here your action sequence must have length 1.\n' +
-                'If the task is not yet fully finished as requested by the user, set success in "done" to false! E.g. if not all steps are fully completed.\n' +
-                'If the task is fully finished, set success in "done" to true.\n' +
+            const message = 'You reached max_steps - this is your last step. Your only tool available is the "done" tool. No other tool is available. All other tools which you see in history or examples are not available.\n' +
+                'If the task is not yet fully finished as requested by the user, set success in "done" to false! E.g. if not all steps are fully completed. Else success to true.\n' +
                 'Include everything you found out for the ultimate task in the done text.';
             this._message_manager._add_context_message(new UserMessage(message));
-            this.logger.info('⚠️ Approaching last step. Enforcing done-only action.');
+            this.logger.debug('Last step finishing up');
+        }
+    }
+    _max_total_failures() {
+        return (this.settings.max_failures +
+            Number(this.settings.final_response_after_failure));
+    }
+    async _handle_failure_limit_recovery() {
+        if (!this.settings.final_response_after_failure ||
+            this.state.consecutive_failures < this.settings.max_failures) {
+            return;
+        }
+        const message = `You failed ${this.settings.max_failures} times. Therefore we terminate the agent.\n` +
+            'Your only tool available is the "done" tool. No other tool is available. All other tools which you see in history or examples are not available.\n' +
+            'If the task is not yet fully finished as requested by the user, set success in "done" to false! E.g. if not all steps are fully completed. Else success to true.\n' +
+            'Include everything you found out for the ultimate task in the done text.';
+        this._message_manager._add_context_message(new UserMessage(message));
+        this._enforceDoneOnlyForCurrentStep = true;
+        this.logger.debug('Force done action, because we reached max_failures.');
+    }
+    _update_plan_from_model_output(modelOutput) {
+        if (!this.settings.enable_planning) {
+            return;
+        }
+        if (Array.isArray(modelOutput.plan_update)) {
+            this.state.plan = modelOutput.plan_update.map((stepText) => new PlanItem({
+                text: stepText,
+                status: 'pending',
+            }));
+            this.state.current_plan_item_index = 0;
+            this.state.plan_generation_step = this.state.n_steps;
+            if (this.state.plan.length > 0) {
+                this.state.plan[0].status = 'current';
+            }
+            this.logger.info(`📋 Plan updated with ${this.state.plan.length} steps`);
+            return;
+        }
+        if (typeof modelOutput.current_plan_item !== 'number' ||
+            !this.state.plan ||
+            this.state.plan.length === 0) {
+            return;
+        }
+        const oldIndex = this.state.current_plan_item_index;
+        const newIndex = Math.max(0, Math.min(modelOutput.current_plan_item, this.state.plan.length - 1));
+        for (let i = oldIndex; i < newIndex; i += 1) {
+            if (this.state.plan[i] &&
+                (this.state.plan[i].status === 'current' ||
+                    this.state.plan[i].status === 'pending')) {
+                this.state.plan[i].status = 'done';
+            }
+        }
+        if (this.state.plan[newIndex]) {
+            this.state.plan[newIndex].status = 'current';
+        }
+        this.state.current_plan_item_index = newIndex;
+    }
+    _render_plan_description() {
+        if (!this.settings.enable_planning || !this.state.plan) {
+            return null;
+        }
+        const markers = {
+            done: '[x]',
+            current: '[>]',
+            pending: '[ ]',
+            skipped: '[-]',
+        };
+        return this.state.plan
+            .map((step, index) => `${markers[step.status] ?? '[ ]'} ${index}: ${step.text}`)
+            .join('\n');
+    }
+    _inject_replan_nudge() {
+        if (!this.settings.enable_planning || !this.state.plan) {
+            return;
+        }
+        if (this.settings.planning_replan_on_stall <= 0) {
+            return;
+        }
+        if (this.state.consecutive_failures < this.settings.planning_replan_on_stall) {
+            return;
+        }
+        const message = 'REPLAN SUGGESTED: You have failed ' +
+            `${this.state.consecutive_failures} consecutive times. ` +
+            'Your current plan may need revision. ' +
+            'Output a new `plan_update` with revised steps to recover.';
+        this.logger.info(`📋 Replan nudge injected after ${this.state.consecutive_failures} consecutive failures`);
+        this._message_manager._add_context_message(new UserMessage(message));
+    }
+    _inject_exploration_nudge() {
+        if (!this.settings.enable_planning || this.state.plan) {
+            return;
+        }
+        if (this.settings.planning_exploration_limit <= 0) {
+            return;
+        }
+        if (this.state.n_steps < this.settings.planning_exploration_limit) {
+            return;
+        }
+        const message = 'PLANNING NUDGE: You have taken ' +
+            `${this.state.n_steps} steps without creating a plan. ` +
+            'If the task is complex, output a `plan_update` with clear todo items now. ' +
+            'If the task is already done or nearly done, call `done` instead.';
+        this.logger.info(`📋 Exploration nudge injected after ${this.state.n_steps} steps without a plan`);
+        this._message_manager._add_context_message(new UserMessage(message));
+    }
+    _inject_loop_detection_nudge() {
+        if (!this.settings.loop_detection_enabled) {
+            return;
+        }
+        const nudge = this.state.loop_detector.get_nudge_message();
+        if (!nudge) {
+            return;
+        }
+        this.logger.info(`🔁 Loop detection nudge injected (repetition=${this.state.loop_detector.max_repetition_count}, stagnation=${this.state.loop_detector.consecutive_stagnant_pages})`);
+        this._message_manager._add_context_message(new UserMessage(nudge));
+    }
+    _update_loop_detector_actions() {
+        if (!this.settings.loop_detection_enabled ||
+            !this.state.last_model_output) {
+            return;
+        }
+        const exemptActions = new Set(['wait', 'done', 'go_back']);
+        for (const action of this.state.last_model_output.action) {
+            const actionData = typeof action?.model_dump === 'function'
+                ? action.model_dump()
+                : action;
+            if (!actionData || typeof actionData !== 'object') {
+                continue;
+            }
+            const actionName = Object.keys(actionData)[0] ?? 'unknown';
+            if (exemptActions.has(actionName)) {
+                continue;
+            }
+            const rawParams = actionData[actionName];
+            const params = rawParams && typeof rawParams === 'object' && !Array.isArray(rawParams)
+                ? rawParams
+                : {};
+            this.state.loop_detector.record_action(actionName, params);
         }
     }
+    _update_loop_detector_page_state(browser_state_summary) {
+        if (!this.settings.loop_detection_enabled) {
+            return;
+        }
+        const url = browser_state_summary.url ?? '';
+        const elementCount = browser_state_summary.selector_map
+            ? Object.keys(browser_state_summary.selector_map).length
+            : 0;
+        const domText = (() => {
+            try {
+                return (browser_state_summary.element_tree?.clickable_elements_to_string?.() ??
+                    '');
+            }
+            catch {
+                return '';
+            }
+        })();
+        this.state.loop_detector.record_page_state(url, domText, elementCount);
+    }
+    _inject_budget_warning(step_info = null) {
+        if (!step_info) {
+            return;
+        }
+        const stepsUsed = step_info.step_number + 1;
+        const budgetRatio = stepsUsed / step_info.max_steps;
+        if (budgetRatio < 0.75 || step_info.is_last_step()) {
+            return;
+        }
+        const stepsRemaining = step_info.max_steps - stepsUsed;
+        const pct = Math.floor(budgetRatio * 100);
+        const message = `BUDGET WARNING: You have used ${stepsUsed}/${step_info.max_steps} steps ` +
+            `(${pct}%). ${stepsRemaining} steps remaining. ` +
+            'If the task cannot be completed in the remaining steps, prioritize: ' +
+            '(1) consolidate your results (save to files if the file system is in use), ' +
+            '(2) call done with what you have. ' +
+            'Partial results are far more valuable than exhausting all steps with nothing saved.';
+        this.logger.info(`Step budget warning: ${stepsUsed}/${step_info.max_steps} (${pct}%)`);
+        this._message_manager._add_context_message(new UserMessage(message));
+    }
+    async _run_simple_judge() {
+        const lastHistoryItem = this.history.history[this.history.history.length - 1];
+        if (!lastHistoryItem || !lastHistoryItem.result.length) {
+            return;
+        }
+        const lastResult = lastHistoryItem.result[lastHistoryItem.result.length - 1];
+        if (!lastResult.is_done || !lastResult.success) {
+            return;
+        }
+        const messages = construct_simple_judge_messages({
+            task: this.task,
+            final_result: this.history.final_result() ?? '',
+        });
+        try {
+            const response = await this.llm.ainvoke(messages, SimpleJudgeOutputFormat);
+            const parsed = this._parseCompletionPayload(response.completion);
+            if (typeof parsed?.is_correct !== 'boolean') {
+                this.logger.debug('Simple judge response missing boolean is_correct; skipping override.');
+                return;
+            }
+            const isCorrect = parsed.is_correct;
+            const reason = typeof parsed?.reason === 'string' && parsed.reason.trim()
+                ? parsed.reason.trim()
+                : 'Task requirements not fully met';
+            if (!isCorrect) {
+                this.logger.info(`⚠️  Simple judge overriding success to failure: ${reason}`);
+                lastResult.success = false;
+                const note = `[Simple judge: ${reason}]`;
+                if (lastResult.extracted_content) {
+                    lastResult.extracted_content += `\n\n${note}`;
+                }
+                else {
+                    lastResult.extracted_content = note;
+                }
+            }
+        }
+        catch (error) {
+            this.logger.warning(`Simple judge failed with error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async _judge_trace() {
+        const messages = construct_judge_messages({
+            task: this.task,
+            final_result: this.history.final_result() ?? '',
+            agent_steps: this.history.agent_steps(),
+            screenshot_paths: this.history
+                .screenshot_paths()
+                .filter((value) => typeof value === 'string'),
+            max_images: 10,
+            ground_truth: this.settings.ground_truth,
+            use_vision: this.settings.use_vision,
+        });
+        try {
+            const invokeOptions = this.judge_llm?.provider === 'browser-use'
+                ? { request_type: 'judge' }
+                : undefined;
+            const response = await this.judge_llm.ainvoke(messages, JudgeOutputFormat, invokeOptions);
+            const parsed = this._parseCompletionPayload(response.completion);
+            const validation = JudgeSchema.safeParse(parsed);
+            if (!validation.success) {
+                this.logger.warning('Judge trace response did not match expected schema; skipping judgement.');
+                return null;
+            }
+            return validation.data;
+        }
+        catch (error) {
+            this.logger.warning(`Judge trace failed: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+    async _judge_and_log() {
+        const lastHistoryItem = this.history.history[this.history.history.length - 1];
+        if (!lastHistoryItem || !lastHistoryItem.result.length) {
+            return;
+        }
+        const lastResult = lastHistoryItem.result[lastHistoryItem.result.length - 1];
+        if (!lastResult.is_done) {
+            return;
+        }
+        const judgement = await this._judge_trace();
+        lastResult.judgement = judgement;
+        if (!judgement) {
+            return;
+        }
+        if (lastResult.success === true && judgement.verdict === true) {
+            return;
+        }
+        let judgeLog = '\n';
+        if (lastResult.success === true && judgement.verdict === false) {
+            judgeLog += '⚠️  Agent reported success but judge thinks task failed\n';
+        }
+        judgeLog += `⚖️  Judge Verdict: ${judgement.verdict ? 'PASS' : 'FAIL'}\n`;
+        if (judgement.failure_reason) {
+            judgeLog += `   Failure Reason: ${judgement.failure_reason}\n`;
+        }
+        if (judgement.reached_captcha) {
+            judgeLog += '   Captcha Detected: Agent encountered captcha challenges\n';
+            judgeLog +=
+                '   Use Browser Use Cloud for stealth browser infra: https://docs.browser-use.com/customize/browser/remote\n';
+        }
+        if (judgement.reasoning) {
+            judgeLog += `   ${judgement.reasoning}\n`;
+        }
+        this.logger.info(judgeLog);
+    }
+    _replace_urls_in_text(text) {
+        const replacedUrls = {};
+        const shortenedText = text.replace(URL_PATTERN, (originalUrl) => {
+            const queryStart = originalUrl.indexOf('?');
+            const fragmentStart = originalUrl.indexOf('#');
+            let afterPathStart = originalUrl.length;
+            if (queryStart !== -1) {
+                afterPathStart = Math.min(afterPathStart, queryStart);
+            }
+            if (fragmentStart !== -1) {
+                afterPathStart = Math.min(afterPathStart, fragmentStart);
+            }
+            const baseUrl = originalUrl.slice(0, afterPathStart);
+            const afterPath = originalUrl.slice(afterPathStart);
+            if (afterPath.length <= this._url_shortening_limit) {
+                return originalUrl;
+            }
+            const truncatedAfterPath = afterPath.slice(0, this._url_shortening_limit);
+            const shortHash = createHash('md5')
+                .update(afterPath, 'utf8')
+                .digest('hex')
+                .slice(0, 7);
+            const shortened = `${baseUrl}${truncatedAfterPath}...${shortHash}`;
+            if (shortened.length >= originalUrl.length) {
+                return originalUrl;
+            }
+            replacedUrls[shortened] = originalUrl;
+            return shortened;
+        });
+        return [shortenedText, replacedUrls];
+    }
+    _process_messages_and_replace_long_urls_shorter_ones(inputMessages) {
+        const urlsReplaced = {};
+        for (const message of inputMessages) {
+            if (!message || typeof message !== 'object') {
+                continue;
+            }
+            const role = message.role;
+            const isUserOrAssistant = message instanceof UserMessage ||
+                message instanceof AssistantMessage ||
+                role === 'user' ||
+                role === 'assistant';
+            if (!isUserOrAssistant) {
+                continue;
+            }
+            if (typeof message.content === 'string') {
+                const [updated, replaced] = this._replace_urls_in_text(message.content);
+                message.content = updated;
+                Object.assign(urlsReplaced, replaced);
+                continue;
+            }
+            if (!Array.isArray(message.content)) {
+                continue;
+            }
+            for (const part of message.content) {
+                if (!part || typeof part !== 'object') {
+                    continue;
+                }
+                const isTextPart = part instanceof ContentPartTextParam || part.type === 'text';
+                if (!isTextPart || typeof part.text !== 'string') {
+                    continue;
+                }
+                const [updated, replaced] = this._replace_urls_in_text(part.text);
+                part.text = updated;
+                Object.assign(urlsReplaced, replaced);
+            }
+        }
+        return urlsReplaced;
+    }
+    _replace_shortened_urls_in_string(text, urlReplacements) {
+        let result = text;
+        for (const [shortenedUrl, originalUrl] of Object.entries(urlReplacements)) {
+            result = result.split(shortenedUrl).join(originalUrl);
+        }
+        return result;
+    }
+    _replace_shortened_urls_in_value(value, urlReplacements) {
+        if (typeof value === 'string') {
+            return this._replace_shortened_urls_in_string(value, urlReplacements);
+        }
+        if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i += 1) {
+                value[i] = this._replace_shortened_urls_in_value(value[i], urlReplacements);
+            }
+            return value;
+        }
+        if (!value || typeof value !== 'object') {
+            return value;
+        }
+        for (const [key, nested] of Object.entries(value)) {
+            value[key] =
+                this._replace_shortened_urls_in_value(nested, urlReplacements);
+        }
+        return value;
+    }
     _parseCompletionPayload(rawCompletion) {
         let parsedCompletion = rawCompletion;
         if (typeof parsedCompletion === 'string') {
@@ -1931,7 +3607,7 @@ export class Agent {
                 parsedCompletion = JSON.parse(jsonText);
             }
             catch (error) {
-                throw new Error(`Failed to parse LLM completion as JSON: ${String(error)}`);
+                throw new Error(`Failed to parse LLM completion as JSON: ${String(error)}`, { cause: error });
             }
         }
         if (!parsedCompletion || typeof parsedCompletion !== 'object') {
@@ -1958,13 +3634,38 @@ export class Agent {
         });
     }
     async _get_model_output_with_retry(messages, signal = null) {
+        const urlReplacements = this._process_messages_and_replace_long_urls_shorter_ones(messages);
         const invokeAndParse = async (inputMessages) => {
             this._throwIfAborted(signal);
-            const completion = await this.llm.ainvoke(inputMessages, AgentLLMOutputFormat, { signal: signal ?? undefined });
+            const outputFormat = this._enforceDoneOnlyForCurrentStep
+                ? DoneOnlyLLMOutputFormat
+                : AgentLLMOutputFormat;
+            const completion = await this.llm.ainvoke(inputMessages, outputFormat, {
+                signal: signal ?? undefined,
+                session_id: this.session_id,
+            });
             this._throwIfAborted(signal);
-            return this._parseCompletionPayload(completion.completion);
+            const parsed = this._parseCompletionPayload(completion.completion);
+            if (Object.keys(urlReplacements).length) {
+                this._replace_shortened_urls_in_value(parsed, urlReplacements);
+            }
+            return parsed;
+        };
+        const invokeAndParseWithFallback = async (inputMessages) => {
+            try {
+                return await invokeAndParse(inputMessages);
+            }
+            catch (error) {
+                if ((error instanceof ModelRateLimitError ||
+                    error instanceof ModelProviderError) &&
+                    this._try_switch_to_fallback_llm(error)) {
+                    this._throwIfAborted(signal);
+                    return await invokeAndParse(inputMessages);
+                }
+                throw error;
+            }
         };
-        let parsed_completion = await invokeAndParse(messages);
+        let parsed_completion = await invokeAndParseWithFallback(messages);
         let rawAction = Array.isArray(parsed_completion?.action)
             ? parsed_completion.action
             : [];
@@ -1972,8 +3673,8 @@ export class Agent {
         if (this._isModelActionMissing(rawAction)) {
             this._throwIfAborted(signal);
             this.logger.warning('Model returned empty action. Retrying...');
-            const clarificationMessage = new UserMessage('You forgot to return an action. Please respond only with a valid JSON action according to the expected format.');
-            parsed_completion = await invokeAndParse([
+            const clarificationMessage = new UserMessage('You forgot to return an action. Please respond with a valid JSON action according to the expected schema with your assessment and next actions.');
+            parsed_completion = await invokeAndParseWithFallback([
                 ...messages,
                 clarificationMessage,
             ]);
@@ -1994,18 +3695,70 @@ export class Agent {
         }
         const action = this._validateAndNormalizeActions(rawAction);
         const toNullableString = (value) => typeof value === 'string' ? value : null;
-        const AgentOutputModel = this.AgentOutput ?? AgentOutput;
+        const toNullableNumber = (value) => typeof value === 'number' && Number.isFinite(value)
+            ? Math.trunc(value)
+            : null;
+        const toNullablePlanUpdate = (value) => Array.isArray(value)
+            ? value.filter((item) => typeof item === 'string')
+            : null;
+        const AgentOutputModel = this._enforceDoneOnlyForCurrentStep
+            ? (this.DoneAgentOutput ?? this.AgentOutput ?? AgentOutput)
+            : (this.AgentOutput ?? AgentOutput);
         return new AgentOutputModel({
             thinking: toNullableString(parsed_completion?.thinking),
             evaluation_previous_goal: toNullableString(parsed_completion?.evaluation_previous_goal),
             memory: toNullableString(parsed_completion?.memory),
             next_goal: toNullableString(parsed_completion?.next_goal),
+            current_plan_item: toNullableNumber(parsed_completion?.current_plan_item),
+            plan_update: toNullablePlanUpdate(parsed_completion?.plan_update),
             action,
         });
     }
+    _try_switch_to_fallback_llm(error) {
+        if (this._using_fallback_llm) {
+            this.logger.warning(`⚠️ Fallback LLM also failed (${error.name}: ${error.message}), no more fallbacks available`);
+            return false;
+        }
+        const retryableStatusCodes = new Set([401, 402, 429, 500, 502, 503, 504]);
+        const statusCode = typeof error.statusCode === 'number' ? error.statusCode : null;
+        const isRetryable = error instanceof ModelRateLimitError ||
+            (statusCode != null && retryableStatusCodes.has(statusCode));
+        if (!isRetryable) {
+            return false;
+        }
+        if (!this._fallback_llm) {
+            this.logger.warning(`⚠️ LLM error (${error.name}: ${error.message}) but no fallback_llm configured`);
+            return false;
+        }
+        this._log_fallback_switch(error, this._fallback_llm);
+        this.llm = this._fallback_llm;
+        this._using_fallback_llm = true;
+        this.token_cost_service.register_llm(this._fallback_llm);
+        return true;
+    }
+    _log_fallback_switch(error, fallback) {
+        const originalModel = typeof this._original_llm?.model === 'string'
+            ? this._original_llm.model
+            : 'unknown';
+        const fallbackModel = typeof fallback?.model === 'string' ? fallback.model : 'unknown';
+        const errorType = error.name || 'Error';
+        const statusCode = typeof error.statusCode === 'number' ? error.statusCode : 'N/A';
+        this.logger.warning(`⚠️ Primary LLM (${originalModel}) failed with ${errorType} (status=${statusCode}), switching to fallback LLM (${fallbackModel})`);
+    }
     _validateAndNormalizeActions(actions) {
         const normalizedActions = [];
         const registryActions = this.controller.registry.get_all_actions();
+        const actionAliases = {
+            navigate: 'go_to_url',
+            input: 'input_text',
+            switch: 'switch_tab',
+            close: 'close_tab',
+            extract: 'extract_structured_data',
+            find_text: 'scroll_to_text',
+            dropdown_options: 'get_dropdown_options',
+            select_dropdown: 'select_dropdown_option',
+            replace_file: 'replace_file_str',
+        };
         const availableNames = new Set();
         const modelForStep = this._enforceDoneOnlyForCurrentStep
             ? this.DoneActionModel
@@ -2040,19 +3793,28 @@ export class Agent {
             if (keys.length !== 1) {
                 throw new Error(`Invalid action at index ${i}: expected exactly one action key, got ${keys.length}`);
             }
-            const actionName = keys[0];
+            const requestedActionName = keys[0];
+            let actionName = requestedActionName;
+            if (!availableNames.has(actionName)) {
+                const aliasTarget = actionAliases[requestedActionName];
+                if (aliasTarget && availableNames.has(aliasTarget)) {
+                    actionName = aliasTarget;
+                }
+            }
             if (!availableNames.has(actionName)) {
                 const available = Array.from(availableNames).sort().join(', ');
-                throw new Error(`Action '${actionName}' is not available on the current page. Available actions: ${available}`);
+                throw new Error(`Action '${requestedActionName}' is not available on the current page. Available actions: ${available}`);
             }
             const actionInfo = registryActions.get(actionName);
             if (!actionInfo) {
-                throw new Error(`Action '${actionName}' is not registered`);
+                throw new Error(`Action '${requestedActionName}' is not registered`);
             }
-            const rawParams = (actionObject[actionName] ?? {});
+            const rawParams = (actionObject[requestedActionName] ??
+                actionObject[actionName] ??
+                {});
             const paramsResult = actionInfo.paramSchema.safeParse(rawParams);
             if (!paramsResult.success) {
-                throw new Error(`Invalid parameters for action '${actionName}': ${paramsResult.error.message}`);
+                throw new Error(`Invalid parameters for action '${requestedActionName}': ${paramsResult.error.message}`);
             }
             normalizedActions.push(new modelForStep({
                 [actionName]: paramsResult.data,
@@ -2089,9 +3851,14 @@ export class Agent {
             }
         }
         catch (error) {
+            const errorType = error instanceof Error
+                ? error.name || 'Error'
+                : typeof error === 'object' && error !== null
+                    ? (error.constructor?.name ?? 'Error')
+                    : 'Error';
             const message = error instanceof Error ? error.message : String(error);
             const errorContext = context ? ` ${context}` : '';
-            this.logger.debug(`📁 Failed to check for downloads${errorContext}: ${message}`);
+            this.logger.debug(`📁 Failed to check for downloads${errorContext}: ${errorType}: ${message}`);
         }
     }
     _update_available_file_paths(downloads) {
@@ -2112,16 +3879,24 @@ export class Agent {
             }
         }
         else {
-            this.logger.info(`📁 No new downloads detected (tracking ${existing.length} files)`);
+            this.logger.debug(`📁 No new downloads detected (tracking ${existing.length} files)`);
         }
     }
     _log_step_context(current_page, browser_state_summary) {
-        const url = typeof current_page?.url === 'function' ? current_page.url() : '';
+        const url = browser_state_summary?.url ?? '';
         const url_short = url.length > 50 ? `${url.slice(0, 50)}...` : url;
         const interactive_count = browser_state_summary?.selector_map
             ? Object.keys(browser_state_summary.selector_map).length
             : 0;
-        this.logger.info(`📍 Step ${this.state.n_steps}: Evaluating page with ${interactive_count} interactive elements on: ${url_short}`);
+        this.logger.info('\n');
+        this.logger.info(`📍 Step ${this.state.n_steps}:`);
+        this.logger.debug(`Evaluating page with ${interactive_count} interactive elements on: ${url_short}`);
+    }
+    _log_first_step_startup() {
+        if (this.history.history.length !== 0) {
+            return;
+        }
+        this.logger.info(`Starting a browser-use agent with version ${this.version}, with provider=${this.llm.provider ?? 'unknown'} and model=${this.llm.model}`);
     }
     _log_step_completion_summary(step_start_time, result) {
         if (!result.length) {
@@ -2159,6 +3934,22 @@ export class Agent {
         });
         const final_result = this.history.final_result();
         const final_result_str = final_result != null ? JSON.stringify(final_result) : null;
+        const judgement_data = this.history.judgement();
+        const judge_verdict = judgement_data && typeof judgement_data.verdict === 'boolean'
+            ? judgement_data.verdict
+            : null;
+        const judge_reasoning = judgement_data && typeof judgement_data.reasoning === 'string'
+            ? judgement_data.reasoning
+            : null;
+        const judge_failure_reason = judgement_data && typeof judgement_data.failure_reason === 'string'
+            ? judgement_data.failure_reason
+            : null;
+        const judge_reached_captcha = judgement_data && typeof judgement_data.reached_captcha === 'boolean'
+            ? judgement_data.reached_captcha
+            : null;
+        const judge_impossible_task = judgement_data && typeof judgement_data.impossible_task === 'boolean'
+            ? judgement_data.impossible_task
+            : null;
         let cdpHost = null;
         const cdpUrl = this.browser_session?.cdp_url;
         if (typeof cdpUrl === 'string' && cdpUrl) {
@@ -2170,39 +3961,42 @@ export class Agent {
                 cdpHost = cdpUrl;
             }
         }
-        const plannerModel = this.settings?.planner_llm &&
-            typeof this.settings.planner_llm === 'object'
-            ? (this.settings.planner_llm.model ?? null)
-            : null;
         this.telemetry.capture(new AgentTelemetryEvent({
             task: this.task,
             model: this.llm.model,
             model_provider: this.llm.provider ?? 'unknown',
-            planner_llm: plannerModel,
             max_steps: max_steps,
             max_actions_per_step: this.settings.max_actions_per_step,
             use_vision: this.settings.use_vision,
-            use_validation: this.settings.validate_output,
             version: this.version,
             source: this.source,
             cdp_url: cdpHost,
+            agent_type: null,
             action_errors: this.history.errors(),
             action_history: action_history_data,
             urls_visited: this.history.urls(),
             steps: this.state.n_steps,
             total_input_tokens: token_summary.prompt_tokens ?? 0,
+            total_output_tokens: token_summary.completion_tokens ?? 0,
+            prompt_cached_tokens: token_summary.prompt_cached_tokens ?? 0,
+            total_tokens: token_summary.total_tokens ?? 0,
             total_duration_seconds: this.history.total_duration_seconds(),
             success: this.history.is_successful(),
             final_result_response: final_result_str,
             error_message: agent_run_error,
+            judge_verdict,
+            judge_reasoning,
+            judge_failure_reason,
+            judge_reached_captcha,
+            judge_impossible_task,
         }));
     }
-    async _make_history_item(model_output, browser_state_summary, result, metadata) {
+    async _make_history_item(model_output, browser_state_summary, result, metadata, state_message = null) {
         const interacted_elements = model_output
             ? AgentHistory.get_interacted_element(model_output, browser_state_summary.selector_map)
             : [];
         const state = new BrowserStateHistory(browser_state_summary.url, browser_state_summary.title, browser_state_summary.tabs, interacted_elements, this._current_screenshot_path);
-        this.history.add_item(new AgentHistory(model_output, result, state, metadata));
+        this.history.add_item(new AgentHistory(model_output, result, state, metadata, state_message));
     }
     save_file_system_state() {
         if (!this.file_system) {