browser-use 0.2.0 → 0.3.0

package/dist/controller/service.js

@@ -1,14 +1,20 @@
-import fs from 'node:fs';
+import fs, { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { validate as validateJsonSchema } from '@cfworker/json-schema';
 import { ActionResult } from '../agent/views.js';
+import { ClickCoordinateEvent, ClickElementEvent, CloseTabEvent, GetDropdownOptionsEvent, GoBackEvent, NavigateToUrlEvent, ScrollEvent, ScrollToTextEvent, ScreenshotEvent, SelectDropdownOptionEvent, SendKeysEvent, SwitchTabEvent, TypeTextEvent, UploadFileEvent, WaitEvent, } from '../browser/events.js';
 import { BrowserError } from '../browser/views.js';
-import { FileSystem } from '../filesystem/file-system.js';
-import { ClickElementActionSchema, CloseTabActionSchema, DoneActionSchema, ExtractStructuredDataActionSchema, DropdownOptionsActionSchema, SelectDropdownActionSchema, GoToUrlActionSchema, InputTextActionSchema, NoParamsActionSchema, ReadFileActionSchema, ReplaceFileStrActionSchema, ScrollActionSchema, ScrollToTextActionSchema, SearchGoogleActionSchema, StructuredOutputActionSchema, SwitchTabActionSchema, UploadFileActionSchema, WaitActionSchema, WriteFileActionSchema, SendKeysActionSchema, SheetsRangeActionSchema, SheetsUpdateActionSchema, SheetsInputActionSchema, } from './views.js';
+import { chunkMarkdownByStructure, extractCleanMarkdownFromHtml, } from '../dom/markdown-extractor.js';
+import { extractPdfText, FileSystem } from '../filesystem/file-system.js';
+import { ClickElementActionIndexOnlySchema, ClickElementActionSchema, CloseTabActionSchema, DoneActionSchema, EvaluateActionSchema, ExtractStructuredDataActionSchema, FindElementsActionSchema, DropdownOptionsActionSchema, SelectDropdownActionSchema, GoToUrlActionSchema, InputTextActionSchema, NoParamsActionSchema, ReadLongContentActionSchema, ReadFileActionSchema, ReplaceFileStrActionSchema, ScrollActionSchema, ScrollToTextActionSchema, SearchActionSchema, SearchPageActionSchema, SearchGoogleActionSchema, ScreenshotActionSchema, StructuredOutputActionSchema, SwitchTabActionSchema, UploadFileActionSchema, WaitActionSchema, WriteFileActionSchema, SendKeysActionSchema, SheetsRangeActionSchema, SheetsUpdateActionSchema, SheetsInputActionSchema, } from './views.js';
 import { Registry } from './registry/service.js';
-import TurndownService from 'turndown';
-import { UserMessage } from '../llm/messages.js';
+import { SystemMessage, UserMessage } from '../llm/messages.js';
 import { createLogger } from '../logging-config.js';
-const DEFAULT_WAIT_OFFSET = 3;
-const MAX_WAIT_SECONDS = 10;
+import { sanitize_surrogates } from '../utils.js';
+import { findUnsupportedJsonSchemaKeyword, normalizeStructuredDataBySchema, } from '../tools/extraction/schema-utils.js';
+import { getClickDescription } from '../tools/utils.js';
+const DEFAULT_WAIT_OFFSET = 1;
+const MAX_WAIT_SECONDS = 30;
 const toActionEntries = (action) => {
     if (!action) {
         return [];
@@ -58,6 +64,13 @@ const waitWithSignal = async (timeoutMs, signal) => {
         }
     });
 };
+const dispatchBrowserEventIfAvailable = async (browser_session, event, fallback) => {
+    if (typeof browser_session?.dispatch_browser_event === 'function') {
+        const dispatchResult = await browser_session.dispatch_browser_event(event);
+        return dispatchResult?.event?.event_result ?? null;
+    }
+    return fallback();
+};
 const runWithTimeoutAndSignal = async (operation, timeoutMs, signal, timeoutMessage = 'Operation timed out') => {
     throwIfAborted(signal);
     if (timeoutMs <= 0) {
@@ -114,14 +127,33 @@ const runWithTimeoutAndSignal = async (operation, timeoutMs, signal, timeoutMess
         });
     });
 };
+const validateAndFixJavaScript = (code) => {
+    let fixedCode = code;
+    // Fix double-escaped quotes often produced in tool-argument JSON.
+    fixedCode = fixedCode.replace(/\\"/g, '"');
+    // Fix over-escaped regex tokens (e.g. \\d -> \d).
+    fixedCode = fixedCode.replace(/\\\\([dDsSwWbBnrtfv])/g, '\\$1');
+    fixedCode = fixedCode.replace(/\\\\([.*+?^${}()|[\]])/g, '\\$1');
+    // Convert brittle mixed-quote selectors/XPaths into template literals.
+    fixedCode = fixedCode.replace(/document\.evaluate\s*\(\s*"([^"]*)"\s*,/g, (_match, xpath) => `document.evaluate(\`${xpath}\`,`);
+    fixedCode = fixedCode.replace(/(querySelector(?:All)?)\s*\(\s*"([^"]*)"\s*\)/g, (_match, methodName, selector) => `${methodName}(\`${selector}\`)`);
+    fixedCode = fixedCode.replace(/\.closest\s*\(\s*"([^"]*)"\s*\)/g, (_match, selector) => `.closest(\`${selector}\`)`);
+    fixedCode = fixedCode.replace(/\.matches\s*\(\s*"([^"]*)"\s*\)/g, (_match, selector) => `.matches(\`${selector}\`)`);
+    return fixedCode;
+};
 export class Controller {
     registry;
     displayFilesInDoneText;
+    outputModel;
+    coordinateClickingEnabled;
+    clickActionHandler = null;
     logger;
     constructor(options = {}) {
         const { exclude_actions = [], output_model = null, display_files_in_done_text = true, } = options;
         this.registry = new Registry(exclude_actions);
         this.displayFilesInDoneText = display_files_in_done_text;
+        this.outputModel = output_model;
+        this.coordinateClickingEnabled = false;
         this.logger = createLogger('browser_use.controller');
         this.registerDefaultActions(output_model);
     }
@@ -131,15 +163,50 @@ export class Controller {
         this.registerElementActions();
         this.registerTabActions();
         this.registerContentActions();
+        this.registerExplorationActions();
         this.registerScrollActions();
         this.registerFileSystemActions();
+        this.registerUtilityActions();
         this.registerKeyboardActions();
         this.registerDropdownActions();
         this.registerSheetsActions();
     }
     registerNavigationActions() {
+        this.registry.action('Search the query on a web search engine (duckduckgo, google, or bing).', { param_model: SearchActionSchema, terminates_sequence: true })(async function search(params, { browser_session, signal }) {
+            if (!browser_session)
+                throw new Error('Browser session missing');
+            throwIfAborted(signal);
+            const requestedEngine = String(params.engine ?? 'duckduckgo');
+            const engine = requestedEngine.toLowerCase();
+            const encodedQuery = encodeURIComponent(params.query).replace(/%20/g, '+');
+            const searchUrlByEngine = {
+                duckduckgo: `https://duckduckgo.com/?q=${encodedQuery}`,
+                google: `https://www.google.com/search?q=${encodedQuery}&udm=14`,
+                bing: `https://www.bing.com/search?q=${encodedQuery}`,
+            };
+            const searchUrl = searchUrlByEngine[engine];
+            if (!searchUrl) {
+                return new ActionResult({
+                    error: `Unsupported search engine: ${requestedEngine}. Options: duckduckgo, google, bing`,
+                });
+            }
+            try {
+                await browser_session.navigate_to(searchUrl, { signal });
+                const memory = `Searched ${requestedEngine} for '${params.query}'`;
+                return new ActionResult({
+                    extracted_content: memory,
+                    long_term_memory: memory,
+                });
+            }
+            catch (error) {
+                return new ActionResult({
+                    error: `Failed to search ${requestedEngine} for "${params.query}": ${String(error?.message ?? error)}`,
+                });
+            }
+        });
         this.registry.action('Search the query in Google...', {
             param_model: SearchGoogleActionSchema,
+            terminates_sequence: true,
         })(async function search_google(params, { browser_session, signal }) {
             if (!browser_session)
                 throw new Error('Browser session missing');
@@ -160,9 +227,7 @@ export class Controller {
                 long_term_memory: `Searched Google for '${params.query}'`,
             });
         });
-        this.registry.action('Navigate to URL...', {
-            param_model: GoToUrlActionSchema,
-        })(async function go_to_url(params, { browser_session, signal }) {
+        const navigateImpl = async function (params, { browser_session, signal, }) {
             if (!browser_session)
                 throw new Error('Browser session missing');
             throwIfAborted(signal);
@@ -177,7 +242,7 @@ export class Controller {
                         long_term_memory: `Opened new tab with URL ${params.url}`,
                     });
                 }
-                await browser_session.navigate_to(params.url, { signal });
+                await dispatchBrowserEventIfAvailable(browser_session, new NavigateToUrlEvent({ url: params.url, new_tab: false }), () => browser_session.navigate_to(params.url, { signal }));
                 const msg = `🔗 Navigated to ${params.url}`;
                 return new ActionResult({
                     extracted_content: msg,
@@ -195,44 +260,181 @@ export class Controller {
                     'net::',
                 ];
                 if (networkFailures.some((needle) => errorMsg.includes(needle))) {
-                    const message = `Site unavailable: ${params.url} - ${errorMsg}`;
-                    throw new BrowserError(message);
+                    return new ActionResult({
+                        error: `Navigation failed - site unavailable: ${params.url}`,
+                    });
                 }
-                throw error;
+                if (error instanceof Error &&
+                    error.name === 'RuntimeError' &&
+                    errorMsg.includes('CDP client not initialized')) {
+                    return new ActionResult({
+                        error: `Browser connection error: ${errorMsg}`,
+                    });
+                }
+                return new ActionResult({
+                    error: `Navigation failed: ${errorMsg}`,
+                });
             }
+        };
+        this.registry.action('Navigate to URL...', {
+            param_model: GoToUrlActionSchema,
+            terminates_sequence: true,
+        })(async function go_to_url(params, { browser_session, signal }) {
+            return navigateImpl(params, { browser_session, signal });
         });
-        this.registry.action('Go back', { param_model: NoParamsActionSchema })(async function go_back(_params, { browser_session, signal }) {
+        this.registry.action('Navigate to URL...', {
+            param_model: GoToUrlActionSchema,
+            terminates_sequence: true,
+        })(async function navigate(params, { browser_session, signal }) {
+            return navigateImpl(params, { browser_session, signal });
+        });
+        this.registry.action('Go back', {
+            param_model: NoParamsActionSchema,
+            terminates_sequence: true,
+        })(async function go_back(_params, { browser_session, signal }) {
             if (!browser_session)
                 throw new Error('Browser session missing');
             throwIfAborted(signal);
-            await browser_session.go_back({ signal });
-            const msg = '🔙  Navigated back';
-            return new ActionResult({ extracted_content: msg });
+            try {
+                await dispatchBrowserEventIfAvailable(browser_session, new GoBackEvent(), () => browser_session.go_back({ signal }));
+                const memory = 'Navigated back';
+                return new ActionResult({ extracted_content: memory });
+            }
+            catch (error) {
+                return new ActionResult({
+                    error: `Failed to go back: ${String(error?.message ?? error)}`,
+                });
+            }
         });
-        this.registry.action('Wait for x seconds default 3 (max 10 seconds). This can be used to wait until the page is fully loaded.', { param_model: WaitActionSchema })(async function wait(params, { signal }) {
+        this.registry.action('Wait for x seconds.', {
+            param_model: WaitActionSchema,
+        })(async function wait(params, { signal, browser_session }) {
             const seconds = params.seconds ?? 3;
             const actualSeconds = Math.min(Math.max(seconds - DEFAULT_WAIT_OFFSET, 0), MAX_WAIT_SECONDS);
-            const msg = `🕒  Waiting for ${actualSeconds + DEFAULT_WAIT_OFFSET} seconds`;
+            const msg = `🕒 Waited for ${seconds} second${seconds === 1 ? '' : 's'}`;
             if (actualSeconds > 0) {
-                await waitWithSignal(actualSeconds * 1000, signal);
+                if (browser_session) {
+                    await dispatchBrowserEventIfAvailable(browser_session, new WaitEvent({
+                        seconds: actualSeconds,
+                        max_seconds: MAX_WAIT_SECONDS,
+                    }), () => waitWithSignal(actualSeconds * 1000, signal));
+                }
+                else {
+                    await waitWithSignal(actualSeconds * 1000, signal);
+                }
             }
-            return new ActionResult({ extracted_content: msg });
+            return new ActionResult({
+                extracted_content: msg,
+                long_term_memory: `Waited for ${seconds} second${seconds === 1 ? '' : 's'}`,
+            });
         });
     }
     registerElementActions() {
-        this.registry.action('Click element by index', {
-            param_model: ClickElementActionSchema,
-        })(async function click_element_by_index(params, { browser_session, signal }) {
+        const logger = this.logger;
+        const convertLlmCoordinatesToViewport = (llmX, llmY, browserSession) => {
+            const llmSize = browserSession?.llm_screenshot_size;
+            const viewportSize = browserSession?._original_viewport_size;
+            if (!Array.isArray(llmSize) ||
+                llmSize.length !== 2 ||
+                !Array.isArray(viewportSize) ||
+                viewportSize.length !== 2) {
+                return [llmX, llmY];
+            }
+            const [llmWidth, llmHeight] = llmSize.map((value) => Number(value));
+            const [viewportWidth, viewportHeight] = viewportSize.map((value) => Number(value));
+            if (!Number.isFinite(llmWidth) ||
+                !Number.isFinite(llmHeight) ||
+                !Number.isFinite(viewportWidth) ||
+                !Number.isFinite(viewportHeight) ||
+                llmWidth <= 0 ||
+                llmHeight <= 0 ||
+                viewportWidth <= 0 ||
+                viewportHeight <= 0) {
+                return [llmX, llmY];
+            }
+            const actualX = Math.floor((llmX / llmWidth) * viewportWidth);
+            const actualY = Math.floor((llmY / llmHeight) * viewportHeight);
+            logger.info(`🔄 Converting coordinates: LLM (${llmX}, ${llmY}) @ ${llmWidth}x${llmHeight} -> Viewport (${actualX}, ${actualY}) @ ${viewportWidth}x${viewportHeight}`);
+            return [actualX, actualY];
+        };
+        const clickImpl = async (params, { browser_session, signal }) => {
             if (!browser_session)
                 throw new Error('Browser session missing');
             throwIfAborted(signal);
-            const element = await browser_session.get_dom_element_by_index(params.index, { signal });
+            const collectTabIds = () => {
+                if (!Array.isArray(browser_session.tabs)) {
+                    return new Set();
+                }
+                return new Set(browser_session.tabs
+                    .map((tab) => tab?.page_id)
+                    .filter((pageId) => typeof pageId === 'number' && Number.isFinite(pageId)));
+            };
+            const detectNewTabNote = async (tabsBefore) => {
+                try {
+                    await waitWithSignal(50, signal);
+                    const tabsAfter = Array.isArray(browser_session.tabs)
+                        ? browser_session.tabs
+                        : [];
+                    const newTab = tabsAfter.find((tab) => {
+                        const pageId = tab?.page_id;
+                        return typeof pageId === 'number' && !tabsBefore.has(pageId);
+                    });
+                    if (!newTab) {
+                        return '';
+                    }
+                    const tabId = typeof newTab?.tab_id === 'string' && newTab.tab_id.trim()
+                        ? newTab.tab_id.trim()
+                        : String(newTab.page_id).padStart(4, '0').slice(-4);
+                    return `. Note: This opened a new tab (tab_id: ${tabId}) - switch to it if you need to interact with the new page.`;
+                }
+                catch {
+                    return '';
+                }
+            };
+            if (params.coordinate_x != null &&
+                params.coordinate_y != null &&
+                params.index == null) {
+                if (!this.coordinateClickingEnabled) {
+                    throw new BrowserError('Coordinate clicking is disabled for the current model. Provide an element index.');
+                }
+                const tabsBefore = collectTabIds();
+                const page = await browser_session.get_current_page();
+                if (!page?.mouse?.click) {
+                    throw new BrowserError('Unable to perform coordinate click on the current page.');
+                }
+                const [actualX, actualY] = convertLlmCoordinatesToViewport(params.coordinate_x, params.coordinate_y, browser_session);
+                await dispatchBrowserEventIfAvailable(browser_session, new ClickCoordinateEvent({
+                    coordinate_x: actualX,
+                    coordinate_y: actualY,
+                }), () => page.mouse.click(actualX, actualY));
+                const coordinateMessage = `🖱️ Clicked at coordinates (${params.coordinate_x}, ${params.coordinate_y})` +
+                    (await detectNewTabNote(tabsBefore));
+                return new ActionResult({
+                    extracted_content: coordinateMessage,
+                    include_in_memory: true,
+                    long_term_memory: coordinateMessage,
+                    metadata: {
+                        click_x: actualX,
+                        click_y: actualY,
+                    },
+                });
+            }
+            if (params.index == null) {
+                return new ActionResult({
+                    error: 'Must provide either index or both coordinate_x and coordinate_y',
+                });
+            }
+            const element = await browser_session.get_dom_element_by_index(params.index, {
+                signal,
+            });
             if (!element) {
-                throw new BrowserError(`Element index ${params.index} does not exist - retry or use alternative actions`);
+                const msg = `Element index ${params.index} not available - page may have changed. Try refreshing browser state.`;
+                logger.warning(`⚠️ ${msg}`);
+                return new ActionResult({
+                    extracted_content: msg,
+                });
             }
-            const initialTabs = Array.isArray(browser_session.tabs)
-                ? browser_session.tabs.length
-                : 0;
+            const tabsBefore = collectTabIds();
             if (browser_session.is_file_input?.(element)) {
                 const msg = `Index ${params.index} - has an element which opens file upload dialog.`;
                 return new ActionResult({
@@ -242,124 +444,430 @@ export class Controller {
                     long_term_memory: msg,
                 });
             }
-            const downloadPath = await browser_session._click_element_node(element, {
+            const downloadPath = await dispatchBrowserEventIfAvailable(browser_session, new ClickElementEvent({
+                node: element,
+                button: 'left',
+            }), () => browser_session._click_element_node(element, {
                 signal,
-            });
-            let msg = '';
+            }));
+            let msg;
             if (downloadPath) {
                 msg = `💾 Downloaded file to ${downloadPath}`;
             }
             else {
-                const snippet = element.get_all_text_till_next_clickable_element?.(2) ?? '';
-                msg = `🖱️  Clicked button with index ${params.index}: ${snippet}`;
-            }
-            if (Array.isArray(browser_session.tabs) &&
-                browser_session.tabs.length > initialTabs) {
-                msg += ' - New tab opened - switching to it';
-                await browser_session.switch_to_tab(-1, { signal });
+                let elementDescription = '';
+                if (typeof element?.tag_name === 'string' &&
+                    typeof element?.get_all_text_till_next_clickable_element ===
+                        'function') {
+                    try {
+                        elementDescription = getClickDescription(element);
+                    }
+                    catch {
+                        elementDescription = '';
+                    }
+                }
+                if (elementDescription) {
+                    msg = `🖱️ Clicked ${elementDescription}`;
+                }
+                else {
+                    const snippet = element.get_all_text_till_next_clickable_element?.(2) ?? '';
+                    msg = `🖱️ Clicked button with index ${params.index}: ${snippet}`;
+                }
             }
+            msg += await detectNewTabNote(tabsBefore);
             return new ActionResult({
                 extracted_content: msg,
                 include_in_memory: true,
                 long_term_memory: msg,
             });
-        });
-        this.registry.action('Click and input text into an input interactive element', { param_model: InputTextActionSchema })(async function input_text(params, { browser_session, has_sensitive_data, signal }) {
+        };
+        this.clickActionHandler = clickImpl;
+        this.registerClickActions();
+        const detectSensitiveKeyName = (value, sensitiveData) => {
+            if (!value || !sensitiveData) {
+                return null;
+            }
+            for (const [domainOrKey, content] of Object.entries(sensitiveData)) {
+                if (typeof content === 'string') {
+                    if (content === value) {
+                        return domainOrKey;
+                    }
+                    continue;
+                }
+                if (!content || typeof content !== 'object') {
+                    continue;
+                }
+                for (const [key, nestedValue] of Object.entries(content)) {
+                    if (nestedValue === value) {
+                        return key;
+                    }
+                }
+            }
+            return null;
+        };
+        const inputImpl = async function (params, { browser_session, has_sensitive_data, sensitive_data, signal, }) {
             if (!browser_session)
                 throw new Error('Browser session missing');
             throwIfAborted(signal);
             const element = await browser_session.get_dom_element_by_index(params.index, { signal });
             if (!element) {
-                throw new BrowserError(`Element index ${params.index} does not exist - retry or use alternative actions`);
+                const msg = `Element index ${params.index} not available - page may have changed. Try refreshing browser state.`;
+                logger.warning(`⚠️ ${msg}`);
+                return new ActionResult({
+                    extracted_content: msg,
+                });
             }
-            await browser_session._input_text_element_node(element, params.text, {
+            const isAutocompleteField = (node) => {
+                const attrs = node?.attributes ?? {};
+                const role = String(attrs.role ?? '').toLowerCase();
+                const ariaAutocomplete = String(attrs['aria-autocomplete'] ?? '').toLowerCase();
+                const hasDatalist = String(attrs.list ?? '').trim().length > 0;
+                return (role === 'combobox' ||
+                    (ariaAutocomplete !== '' && ariaAutocomplete !== 'none') ||
+                    hasDatalist);
+            };
+            const needsAutocompleteDelay = (node) => {
+                const attrs = node?.attributes ?? {};
+                const role = String(attrs.role ?? '').toLowerCase();
+                const ariaAutocomplete = String(attrs['aria-autocomplete'] ?? '').toLowerCase();
+                return (role === 'combobox' ||
+                    (ariaAutocomplete !== '' && ariaAutocomplete !== 'none'));
+            };
+            await dispatchBrowserEventIfAvailable(browser_session, new TypeTextEvent({
+                node: element,
+                text: params.text,
+                clear: params.clear ?? true,
+            }), () => browser_session._input_text_element_node(element, params.text, {
+                clear: params.clear,
                 signal,
-            });
-            const msg = has_sensitive_data
-                ? `⌨️  Input sensitive data into index ${params.index}`
-                : `⌨️  Input ${params.text} into index ${params.index}`;
+            }));
+            let actualValue = null;
+            try {
+                const locator = await browser_session.get_locate_element?.(element);
+                if (locator && typeof locator.inputValue === 'function') {
+                    const value = await locator.inputValue();
+                    actualValue = typeof value === 'string' ? value : null;
+                }
+            }
+            catch {
+                actualValue = null;
+            }
+            let msg = `⌨️  Input ${params.text} into index ${params.index}`;
+            if (has_sensitive_data) {
+                const sensitiveKeyName = detectSensitiveKeyName(params.text, sensitive_data ?? null);
+                msg = sensitiveKeyName
+                    ? `Typed ${sensitiveKeyName}`
+                    : 'Typed sensitive data';
+            }
+            if (!has_sensitive_data &&
+                actualValue != null &&
+                actualValue !== params.text) {
+                msg +=
+                    `\n⚠️ Note: the field's actual value '${actualValue}' differs from typed text '${params.text}'. ` +
+                        'The page may have reformatted or autocompleted your input.';
+            }
+            if (isAutocompleteField(element)) {
+                msg +=
+                    '\n💡 This is an autocomplete field. Wait for suggestions to appear, then click the correct suggestion instead of pressing Enter.';
+                if (needsAutocompleteDelay(element)) {
+                    await waitWithSignal(400, signal);
+                }
+            }
             return new ActionResult({
                 extracted_content: msg,
                 include_in_memory: true,
-                long_term_memory: `Input '${params.text}' into element ${params.index}.`,
+                long_term_memory: msg,
+            });
+        };
+        this.registry.action('Click and input text into an input interactive element', { param_model: InputTextActionSchema })(async function input_text(params, { browser_session, has_sensitive_data, sensitive_data, signal }) {
+            return inputImpl(params, {
+                browser_session,
+                has_sensitive_data,
+                sensitive_data,
+                signal,
+            });
+        });
+        this.registry.action('Click and input text into an input interactive element', { param_model: InputTextActionSchema })(async function input(params, { browser_session, has_sensitive_data, sensitive_data, signal }) {
+            return inputImpl(params, {
+                browser_session,
+                has_sensitive_data,
+                sensitive_data,
+                signal,
             });
         });
         this.registry.action('Upload file to interactive element with file path', {
             param_model: UploadFileActionSchema,
-        })(async function upload_file(params, { browser_session, available_file_paths, signal }) {
+        })(async function upload_file(params, { browser_session, available_file_paths, file_system, signal }) {
             if (!browser_session)
                 throw new Error('Browser session missing');
             throwIfAborted(signal);
-            if (!available_file_paths?.includes(params.path)) {
-                throw new BrowserError(`File path ${params.path} is not available`);
+            let uploadPath = params.path;
+            const isLocalBrowser = browser_session?.is_local !== false;
+            const allowedPaths = new Set(available_file_paths ?? []);
+            const downloadedFiles = Array.isArray(browser_session?.downloaded_files)
+                ? browser_session.downloaded_files
+                : [];
+            for (const downloadedPath of downloadedFiles) {
+                allowedPaths.add(downloadedPath);
             }
-            if (!fs.existsSync(params.path)) {
-                throw new BrowserError(`File ${params.path} does not exist`);
+            if (!allowedPaths.has(uploadPath)) {
+                const fsInstance = file_system ?? null;
+                const managedFile = fsInstance && typeof fsInstance.get_file === 'function'
+                    ? fsInstance.get_file(uploadPath)
+                    : null;
+                if (managedFile && fsInstance?.get_dir) {
+                    uploadPath = path.join(fsInstance.get_dir(), uploadPath);
+                }
+                else if (!isLocalBrowser) {
+                    // Remote browser paths may only exist on the remote runtime.
+                }
+                else {
+                    return new ActionResult({
+                        error: `File path ${params.path} is not available. To fix: add this file path to available_file_paths when creating the Agent.`,
+                    });
+                }
             }
-            const node = await browser_session.find_file_upload_element_by_index(params.index, 3, 3, { signal });
-            if (!node) {
-                throw new BrowserError(`No file upload element found at index ${params.index}`);
+            if (isLocalBrowser) {
+                if (!fs.existsSync(uploadPath)) {
+                    return new ActionResult({
+                        error: `File ${uploadPath} does not exist`,
+                    });
+                }
+                if (fs.statSync(uploadPath).size === 0) {
+                    return new ActionResult({
+                        error: `File ${uploadPath} is empty (0 bytes). The file may not have been saved correctly.`,
+                    });
+                }
+            }
+            let selectorMap = null;
+            if (typeof browser_session.get_selector_map === 'function') {
+                selectorMap = await browser_session.get_selector_map({ signal });
+                if (!(params.index in (selectorMap ?? {}))) {
+                    return new ActionResult({
+                        error: `Element with index ${params.index} does not exist.`,
+                    });
+                }
             }
-            const locator = await browser_session.get_locate_element(node);
-            if (!locator) {
-                throw new BrowserError(`No file upload element found at index ${params.index}`);
+            let node = await browser_session.find_file_upload_element_by_index(params.index, 3, 3, { signal });
+            if (!node &&
+                selectorMap &&
+                typeof browser_session.is_file_input === 'function') {
+                let currentScrollY = 0;
+                try {
+                    const page = await browser_session.get_current_page?.();
+                    if (page?.evaluate) {
+                        const evaluated = await page.evaluate(() => window.scrollY || window.pageYOffset || 0);
+                        const numeric = typeof evaluated === 'number' ? evaluated : Number(evaluated);
+                        if (Number.isFinite(numeric)) {
+                            currentScrollY = numeric;
+                        }
+                    }
+                }
+                catch {
+                    currentScrollY = 0;
+                }
+                let closest = null;
+                let minDistance = Number.POSITIVE_INFINITY;
+                for (const element of Object.values(selectorMap)) {
+                    if (!browser_session.is_file_input(element)) {
+                        continue;
+                    }
+                    const y = Number(element?.absolute_position?.y ?? 0);
+                    const distance = Number.isFinite(y)
+                        ? Math.abs(y - currentScrollY)
+                        : 0;
+                    if (!closest || distance < minDistance) {
+                        closest = element;
+                        minDistance = distance;
+                    }
+                }
+                if (closest) {
+                    node = closest;
+                }
             }
-            await locator.setInputFiles(params.path);
+            if (!node) {
+                throw new BrowserError('No file upload element found on the page');
+            }
+            await dispatchBrowserEventIfAvailable(browser_session, new UploadFileEvent({
+                node,
+                file_path: uploadPath,
+            }), async () => {
+                const locator = await browser_session.get_locate_element(node);
+                if (!locator) {
+                    throw new BrowserError('No file upload element found on the page');
+                }
+                await locator.setInputFiles(uploadPath);
+                return null;
+            });
             const msg = `📁 Successfully uploaded file to index ${params.index}`;
             return new ActionResult({
                 extracted_content: msg,
                 include_in_memory: true,
-                long_term_memory: `Uploaded file ${params.path} to element ${params.index}`,
+                long_term_memory: `Uploaded file ${uploadPath} to element ${params.index}`,
             });
         });
     }
+    registerClickActions() {
+        const clickActionHandler = this.clickActionHandler;
+        if (!clickActionHandler) {
+            return;
+        }
+        const removeAction = this.registry?.remove_action;
+        if (typeof removeAction === 'function') {
+            removeAction.call(this.registry, 'click');
+            removeAction.call(this.registry, 'click_element_by_index');
+        }
+        const registerIndexAlias = () => {
+            this.registry.action('Click element by index.', {
+                param_model: ClickElementActionIndexOnlySchema,
+                action_name: 'click_element_by_index',
+            })(async (params, ctx) => {
+                return await clickActionHandler(params, ctx);
+            });
+        };
+        if (this.coordinateClickingEnabled) {
+            this.registry.action('Click element by index or coordinates. Use coordinates only if the index is not available. Either provide coordinates or index.', {
+                param_model: ClickElementActionSchema,
+                action_name: 'click',
+            })(async (params, ctx) => {
+                return await clickActionHandler(params, ctx);
+            });
+            registerIndexAlias();
+            return;
+        }
+        this.registry.action('Click element by index.', {
+            param_model: ClickElementActionIndexOnlySchema,
+            action_name: 'click',
+        })(async (params, ctx) => {
+            return await clickActionHandler(params, ctx);
+        });
+        registerIndexAlias();
+    }
     registerTabActions() {
-        this.registry.action('Switch tab', { param_model: SwitchTabActionSchema })(async function switch_tab(params, ctx) {
-            const { browser_session, signal } = ctx;
+        const tabLogger = this.logger;
+        const resolveTabIdentifier = (params) => {
+            if (typeof params.tab_id === 'string' && params.tab_id.trim()) {
+                return params.tab_id.trim();
+            }
+            if (typeof params.page_id === 'number' &&
+                Number.isFinite(params.page_id)) {
+                return params.page_id;
+            }
+            return -1;
+        };
+        const formatTabId = (identifier, browser_session) => {
+            if (typeof identifier === 'string' && identifier.trim()) {
+                return identifier.trim();
+            }
+            const numericIdentifier = typeof identifier === 'number' && Number.isFinite(identifier)
+                ? Math.floor(identifier)
+                : -1;
+            if (numericIdentifier >= 0) {
+                const matchedTab = Array.isArray(browser_session?.tabs)
+                    ? browser_session.tabs.find((tab) => tab?.page_id === numericIdentifier)
+                    : null;
+                const matchedTabId = typeof matchedTab?.tab_id === 'string' && matchedTab.tab_id.trim()
+                    ? matchedTab.tab_id.trim()
+                    : null;
+                return (matchedTabId ?? String(numericIdentifier).padStart(4, '0').slice(-4));
+            }
+            return 'unknown';
+        };
+        const switchImpl = async function (params, { browser_session, signal, }) {
             if (!browser_session)
                 throw new Error('Browser session missing');
             throwIfAborted(signal);
-            await browser_session.switch_to_tab(params.page_id, { signal });
-            const page = await browser_session.get_current_page();
+            const identifier = resolveTabIdentifier(params);
+            const tabId = formatTabId(identifier, browser_session);
             try {
-                await page?.wait_for_load_state?.('domcontentloaded', {
-                    timeout: 5000,
+                const switchTargetId = identifier === -1 ? null : String(identifier).trim();
+                await dispatchBrowserEventIfAvailable(browser_session, new SwitchTabEvent({ target_id: switchTargetId }), () => browser_session.switch_to_tab(identifier, { signal }));
+                const page = await browser_session.get_current_page();
+                try {
+                    await page?.wait_for_load_state?.('domcontentloaded', {
+                        timeout: 5000,
+                    });
+                }
+                catch {
+                    /* ignore */
+                }
+                const memory = `Switched to tab #${tabId}`;
+                return new ActionResult({
+                    extracted_content: memory,
+                    long_term_memory: memory,
                 });
             }
-            catch {
-                /* ignore */
+            catch (error) {
+                tabLogger.warning(`Tab switch may have failed: ${error.message}`);
+                const memory = `Attempted to switch to tab #${tabId}`;
+                return new ActionResult({
+                    extracted_content: memory,
+                    long_term_memory: memory,
+                });
             }
-            const msg = `🔄  Switched to tab #${params.page_id} with url ${page?.url ?? ''}`;
-            return new ActionResult({
-                extracted_content: msg,
-                include_in_memory: true,
-                long_term_memory: `Switched to tab ${params.page_id}`,
-            });
+        };
+        this.registry.action('Switch tab', {
+            param_model: SwitchTabActionSchema,
+            terminates_sequence: true,
+        })(async function switch_tab(params, { browser_session, signal }) {
+            return switchImpl(params, { browser_session, signal });
         });
-        this.registry.action('Close an existing tab', {
-            param_model: CloseTabActionSchema,
-        })(async function close_tab(params, { browser_session, signal }) {
+        this.registry.action('Switch tab', {
+            param_model: SwitchTabActionSchema,
+            terminates_sequence: true,
+            action_name: 'switch',
+        })(async function switch_alias(params, { browser_session, signal }) {
+            return switchImpl(params, { browser_session, signal });
+        });
+        const closeImpl = async function (params, { browser_session, signal, }) {
             if (!browser_session)
                 throw new Error('Browser session missing');
             throwIfAborted(signal);
-            await browser_session.switch_to_tab(params.page_id, { signal });
-            const page = await browser_session.get_current_page();
-            const url = page?.url ?? '';
-            await page?.close?.();
-            const newPage = await browser_session.get_current_page();
-            const newIndex = browser_session.active_tab_index;
-            const msg = `❌  Closed tab #${params.page_id} with ${url}, now focused on tab #${newIndex} with url ${newPage?.url ?? ''}`;
-            return new ActionResult({
-                extracted_content: msg,
-                include_in_memory: true,
-                long_term_memory: `Closed tab ${params.page_id} with url ${url}, now focused on tab ${newIndex} with url ${newPage?.url ?? ''}.`,
-            });
+            const identifier = resolveTabIdentifier(params);
+            const closedTabId = formatTabId(identifier, browser_session);
+            try {
+                const resolvedCloseTargetId = identifier === -1
+                    ? (browser_session?.active_tab?.target_id ??
+                        browser_session?.active_tab?.tab_id ??
+                        null)
+                    : String(identifier).trim();
+                if (!resolvedCloseTargetId) {
+                    throw new Error('Could not resolve target tab to close');
+                }
+                await dispatchBrowserEventIfAvailable(browser_session, new CloseTabEvent({ target_id: resolvedCloseTargetId }), () => browser_session.close_tab(identifier));
+                const memory = `Closed tab #${closedTabId}`;
+                return new ActionResult({
+                    extracted_content: memory,
+                    long_term_memory: memory,
+                });
+            }
+            catch (error) {
+                tabLogger.warning(`Tab ${closedTabId} may already be closed: ${error.message}`);
+                const memory = `Tab #${closedTabId} closed (was already closed or invalid)`;
+                return new ActionResult({
+                    extracted_content: memory,
+                    long_term_memory: memory,
+                });
+            }
+        };
+        this.registry.action('Close an existing tab', {
+            param_model: CloseTabActionSchema,
+        })(async function close_tab(params, { browser_session, signal }) {
+            return closeImpl(params, { browser_session, signal });
+        });
+        this.registry.action('Close an existing tab', {
+            param_model: CloseTabActionSchema,
+        })(async function close(params, { browser_session, signal }) {
+            return closeImpl(params, { browser_session, signal });
         });
     }
     registerContentActions() {
-        this.registry.action('Extract structured, semantic data from the current webpage based on a textual query.', {
+        const registry = this.registry;
+        const contentLogger = this.logger;
+        const extractStructuredDescription = "LLM extracts structured data from page markdown. Use when: on right page, know what to extract, haven't called before on same page+query. Can't get interactive elements. Set extract_links=True for URLs. Use start_from_char if previous extraction was truncated to extract data further down the page.";
+        this.registry.action(extractStructuredDescription, {
             param_model: ExtractStructuredDataActionSchema,
-        })(async function extract_structured_data(params, { page, page_extraction_llm, file_system, signal }) {
+        })(async function extract_structured_data(params, { page, page_extraction_llm, extraction_schema, file_system, signal }) {
             throwIfAborted(signal);
             if (!page) {
                 throw new BrowserError('No active page available for extraction.');
@@ -368,105 +876,457 @@ export class Controller {
                 throw new BrowserError('page_extraction_llm is not configured.');
             }
             const fsInstance = file_system ?? new FileSystem(process.cwd(), false);
-            const html = await page.content?.();
-            if (!html) {
+            const pageHtml = await runWithTimeoutAndSignal(async () => {
+                const value = await page.content?.();
+                return typeof value === 'string' ? value : '';
+            }, 10000, signal, 'Page content extraction timed out');
+            if (!pageHtml) {
                 throw new BrowserError('Unable to extract page content.');
             }
-            const turndown = new TurndownService({
-                headingStyle: 'atx',
-                codeBlockStyle: 'fenced',
-            });
-            let rawHtml = html;
-            if (!params.extract_links) {
-                rawHtml = rawHtml.replace(/<a\b[^>]*>/gi, '').replace(/<\/a>/gi, '');
-            }
-            let content = turndown.turndown(rawHtml);
-            content = content.replace(/\n+/g, '\n');
-            // Manually append iframe text into the content so it's readable by the LLM (includes cross-origin iframes)
-            const frames = page.frames?.() || [];
+            let combinedHtml = pageHtml;
+            const frames = typeof page.frames === 'function'
+                ? page.frames()
+                : Array.isArray(page.frames)
+                    ? page.frames
+                    : [];
+            const currentUrl = (() => {
+                const pageUrlValue = page.url;
+                if (typeof pageUrlValue === 'function') {
+                    return String(pageUrlValue.call(page) ?? '');
+                }
+                return typeof pageUrlValue === 'string' ? pageUrlValue : '';
+            })();
             for (const iframe of frames) {
                 throwIfAborted(signal);
                 try {
-                    // Wait for iframe to load with aggressive timeout
                     await runWithTimeoutAndSignal(async () => {
                         await iframe.waitForLoadState?.('load');
-                    }, 2000, signal, 'Iframe load timeout');
+                    }, 1000, signal, 'Iframe load timeout');
                 }
                 catch (error) {
                     if (isAbortError(error)) {
                         throw error;
                     }
-                    // Ignore iframe load errors
-                }
-                const iframeUrl = iframe.url?.();
-                const pageUrl = page.url?.();
-                if (iframeUrl &&
-                    pageUrl &&
-                    iframeUrl !== pageUrl &&
-                    !iframeUrl.startsWith('data:') &&
-                    !iframeUrl.startsWith('about:')) {
-                    content += `\n\nIFRAME ${iframeUrl}:\n`;
-                    try {
-                        const iframeHtml = await runWithTimeoutAndSignal(async () => (await iframe.content?.()) ?? '', 2000, signal, 'Iframe content extraction timeout');
-                        const iframeMarkdown = turndown.turndown(iframeHtml || '');
-                        content += iframeMarkdown;
+                }
+                const iframeUrl = typeof iframe.url === 'function'
+                    ? iframe.url()
+                    : typeof iframe.url === 'string'
+                        ? iframe.url
+                        : '';
+                if (!iframeUrl ||
+                    iframeUrl === currentUrl ||
+                    iframeUrl.startsWith('data:') ||
+                    iframeUrl.startsWith('about:')) {
+                    continue;
+                }
+                try {
+                    const iframeHtml = await runWithTimeoutAndSignal(async () => {
+                        const value = await iframe.content?.();
+                        return typeof value === 'string' ? value : '';
+                    }, 2000, signal, 'Iframe content extraction timeout');
+                    if (!iframeHtml) {
+                        continue;
                     }
-                    catch (error) {
-                        if (isAbortError(error)) {
-                            throw error;
-                        }
-                        // Skip failed iframes
+                    combinedHtml += `\n<section><h2>IFRAME ${iframeUrl}</h2>${iframeHtml}</section>`;
+                }
+                catch (error) {
+                    if (isAbortError(error)) {
+                        throw error;
                     }
                 }
             }
-            // Replace multiple sequential \n with a single \n
-            content = content.replace(/\n+/g, '\n');
-            const maxChars = 30000;
-            if (content.length > maxChars) {
-                const head = content.slice(0, maxChars / 2);
-                const tail = content.slice(-maxChars / 2);
-                content = `${head}\n... left out the middle because it was too long ...\n${tail}`;
+            const extracted = extractCleanMarkdownFromHtml(combinedHtml, {
+                extract_links: params.extract_links,
+                method: 'page_content',
+                url: currentUrl || undefined,
+            });
+            let content = extracted.content;
+            const contentStats = extracted.stats;
+            const finalFilteredLength = contentStats.final_filtered_chars;
+            const startFromChar = Math.max(0, params.start_from_char ?? 0);
+            const maxChars = 100000;
+            const chunks = chunkMarkdownByStructure(content, maxChars, 5, startFromChar);
+            if (!chunks.length) {
+                return new ActionResult({
+                    error: `start_from_char (${startFromChar}) exceeds content length ${finalFilteredLength} characters.`,
+                });
+            }
+            const chunk = chunks[0];
+            content = chunk.content;
+            const wasTruncated = chunk.has_more;
+            if (chunk.overlap_prefix) {
+                content = `${chunk.overlap_prefix}\n${content}`;
+            }
+            if (startFromChar > 0) {
+                contentStats.started_from_char = startFromChar;
+            }
+            if (wasTruncated) {
+                contentStats.truncated_at_char = chunk.char_offset_end;
+                contentStats.next_start_char = chunk.char_offset_end;
+                contentStats.chunk_index = chunk.chunk_index;
+                contentStats.total_chunks = chunk.total_chunks;
+            }
+            const originalHtmlLength = contentStats.original_html_chars;
+            const initialMarkdownLength = contentStats.initial_markdown_chars;
+            const charsFiltered = contentStats.filtered_chars_removed;
+            let statsSummary = `Content processed: ${originalHtmlLength.toLocaleString()} HTML chars ` +
+                `→ ${initialMarkdownLength.toLocaleString()} initial markdown ` +
+                `→ ${finalFilteredLength.toLocaleString()} filtered markdown`;
+            if (startFromChar > 0) {
+                statsSummary += ` (started from char ${startFromChar.toLocaleString()})`;
+            }
+            if (wasTruncated &&
+                contentStats.next_start_char != null &&
+                contentStats.chunk_index != null &&
+                contentStats.total_chunks != null) {
+                const chunkInfo = `chunk ${contentStats.chunk_index + 1} of ${contentStats.total_chunks}, `;
+                statsSummary +=
+                    ` → ${content.length.toLocaleString()} final chars ` +
+                        `(${chunkInfo}use start_from_char=${contentStats.next_start_char} to continue)`;
+            }
+            else if (charsFiltered > 0) {
+                statsSummary += ` (filtered ${charsFiltered.toLocaleString()} chars of noise)`;
+            }
+            content = sanitize_surrogates(content);
+            const sanitizedQuery = sanitize_surrogates(params.query);
+            const parseJsonFromCompletion = (completion) => {
+                const trimmed = completion.trim();
+                const fencedMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+                const candidate = fencedMatch?.[1]?.trim() || trimmed;
+                return JSON.parse(candidate);
+            };
+            let effectiveOutputSchema = params.output_schema ?? extraction_schema;
+            if (effectiveOutputSchema != null) {
+                const unsupportedKeyword = findUnsupportedJsonSchemaKeyword(effectiveOutputSchema);
+                if (unsupportedKeyword) {
+                    contentLogger.warning(`Invalid output_schema, falling back to free-text extraction: unsupported keyword '${unsupportedKeyword}'`);
+                    effectiveOutputSchema = null;
+                }
+            }
+            const pageUrl = currentUrl || '';
+            const maxMemoryLength = 10000;
+            if (effectiveOutputSchema != null) {
+                const systemPrompt = `
+You are an expert at extracting structured data from the markdown of a webpage.
+
+<input>
+You will be given a query, a JSON Schema, and the markdown of a webpage that has been filtered to remove noise and advertising content.
+</input>
+
+<instructions>
+- Extract ONLY information present in the webpage. Do not guess or fabricate values.
+- Your response MUST conform to the provided JSON Schema exactly.
+- If a required field's value cannot be found on the page, use null (if the schema allows it) or an empty string / empty array as appropriate.
+- If the content was truncated, extract what is available from the visible portion.
+</instructions>`.trim();
+                const schemaJson = JSON.stringify(effectiveOutputSchema, null, 2);
+                const prompt = `<query>\n${sanitizedQuery}\n</query>\n\n` +
+                    `<output_schema>\n${schemaJson}\n</output_schema>\n\n` +
+                    `<content_stats>\n${statsSummary}\n</content_stats>\n\n` +
+                    `<webpage_content>\n${content}\n</webpage_content>`;
+                const response = await page_extraction_llm.ainvoke([new SystemMessage(systemPrompt), new UserMessage(prompt)], undefined, { signal: signal ?? undefined });
+                throwIfAborted(signal);
+                const completion = response?.completion;
+                const completionText = typeof completion === 'string'
+                    ? completion
+                    : JSON.stringify(completion ?? {});
+                let parsedResult;
+                try {
+                    parsedResult = parseJsonFromCompletion(completionText);
+                }
+                catch (error) {
+                    throw new BrowserError(`Structured extraction returned invalid JSON: ${error.message}`);
+                }
+                const schemaValidation = validateJsonSchema(parsedResult, effectiveOutputSchema);
+                if (!schemaValidation.valid) {
+                    const details = (schemaValidation.errors ?? [])
+                        .slice(0, 3)
+                        .map((item) => String(item?.error ?? '').trim())
+                        .filter(Boolean)
+                        .join('; ');
+                    const suffix = details ? `: ${details}` : '';
+                    throw new BrowserError(`Structured extraction result does not match output_schema${suffix}`);
+                }
+                const normalizedResult = normalizeStructuredDataBySchema(parsedResult, effectiveOutputSchema);
+                const resultJson = JSON.stringify(normalizedResult);
+                const extractedContent = `<url>\n${pageUrl}\n</url>\n` +
+                    `<query>\n${sanitizedQuery}\n</query>\n` +
+                    `<structured_result>\n${resultJson}\n</structured_result>`;
+                const extractionMeta = {
+                    data: normalizedResult,
+                    schema_used: effectiveOutputSchema,
+                    is_partial: wasTruncated,
+                    source_url: pageUrl,
+                    content_stats: contentStats,
+                };
+                const includeOnce = extractedContent.length >= maxMemoryLength;
+                const memory = includeOnce
+                    ? `Query: ${sanitizedQuery}\nContent in ${await fsInstance.save_extracted_content(extractedContent)} and once in <read_state>.`
+                    : extractedContent;
+                return new ActionResult({
+                    extracted_content: extractedContent,
+                    include_extracted_content_only_once: includeOnce,
+                    long_term_memory: memory,
+                    metadata: {
+                        structured_extraction: true,
+                        extraction_result: extractionMeta,
+                    },
+                });
             }
-            const prompt = `You convert websites into structured information. Extract information from this webpage based on the query. Focus only on content relevant to the query. If 
-1. The query is vague
-2. Does not make sense for the page
-3. Some/all of the information is not available
+            const systemPrompt = `
+You are an expert at extracting data from the markdown of a webpage.
 
-Explain the content of the page and that the requested information is not available in the page. Respond in JSON format.
-Query: ${params.query}
-Website:
-${content}`;
-            const extraction = await page_extraction_llm.ainvoke([new UserMessage(prompt)], undefined, { signal: signal ?? undefined });
+<input>
+You will be given a query and the markdown of a webpage that has been filtered to remove noise and advertising content.
+</input>
+
+<instructions>
+- You are tasked to extract information from the webpage that is relevant to the query.
+- You should ONLY use the information available in the webpage to answer the query. Do not make up information or provide guess from your own knowledge.
+- If the information relevant to the query is not available in the page, your response should mention that.
+- If the query asks for all items, products, etc., make sure to directly list all of them.
+- If the content was truncated and you need more information, note that the user can use start_from_char parameter to continue from where truncation occurred.
+</instructions>
+
+<output>
+- Your output should present ALL the information relevant to the query in a concise way.
+- Do not answer in conversational format - directly output the relevant information or that the information is unavailable.
+</output>`.trim();
+            const prompt = `<query>\n${sanitizedQuery}\n</query>\n\n` +
+                `<content_stats>\n${statsSummary}\n</content_stats>\n\n` +
+                `<webpage_content>\n${content}\n</webpage_content>`;
+            const response = await page_extraction_llm.ainvoke([new SystemMessage(systemPrompt), new UserMessage(prompt)], undefined, { signal: signal ?? undefined });
             throwIfAborted(signal);
-            const completion = extraction?.completion ?? '';
-            const extracted_content = `Page Link: ${page.url}\nQuery: ${params.query}\nExtracted Content:\n${completion}`;
-            let includeOnce = false;
-            let memory = extracted_content;
-            const MAX_MEMORY_SIZE = 600;
-            if (extracted_content.length > MAX_MEMORY_SIZE) {
-                const lines = extracted_content.split('\n');
-                let display = '';
-                let count = 0;
-                for (const line of lines) {
-                    if (display.length + line.length > MAX_MEMORY_SIZE)
-                        break;
-                    display += `${line}\n`;
-                    count += 1;
+            const completion = response?.completion;
+            const completionText = typeof completion === 'string'
+                ? completion
+                : JSON.stringify(completion ?? {});
+            const extractedContent = `<url>\n${pageUrl}\n</url>\n` +
+                `<query>\n${sanitizedQuery}\n</query>\n` +
+                `<result>\n${completionText}\n</result>`;
+            const includeOnce = extractedContent.length >= maxMemoryLength;
+            const memory = includeOnce
+                ? `Query: ${sanitizedQuery}\nContent in ${await fsInstance.save_extracted_content(extractedContent)} and once in <read_state>.`
+                : extractedContent;
+            return new ActionResult({
+                extracted_content: extractedContent,
+                include_extracted_content_only_once: includeOnce,
+                long_term_memory: memory,
+            });
+        });
+        this.registry.action(extractStructuredDescription, {
+            param_model: ExtractStructuredDataActionSchema,
+            action_name: 'extract',
+        })(async function extract(params, { browser_session, page_extraction_llm, extraction_schema, file_system, available_file_paths, sensitive_data, signal, }) {
+            return registry.execute_action('extract_structured_data', params, {
+                browser_session,
+                page_extraction_llm,
+                extraction_schema,
+                file_system,
+                available_file_paths,
+                sensitive_data,
+                signal,
+            });
+        });
+    }
+    registerExplorationActions() {
+        this.registry.action('Search page text for a pattern (like grep). Zero LLM cost and instant.', { param_model: SearchPageActionSchema })(async function search_page(params, { browser_session, signal }) {
+            if (!browser_session)
+                throw new Error('Browser session missing');
+            throwIfAborted(signal);
+            const page = await browser_session.get_current_page();
+            if (!page?.evaluate) {
+                throw new BrowserError('No active page for search_page.');
+            }
+            const searchResult = (await page.evaluate(({ pattern, regex, caseSensitive, contextChars, cssScope, maxResults, }) => {
+                const sourceNode = cssScope
+                    ? document.querySelector(cssScope)
+                    : document.body;
+                if (!sourceNode) {
+                    return {
+                        error: `CSS scope not found: ${cssScope}`,
+                        matches: [],
+                        total: 0,
+                    };
+                }
+                const sourceText = sourceNode.innerText ||
+                    sourceNode.textContent ||
+                    '';
+                if (!sourceText.trim()) {
+                    return {
+                        matches: [],
+                        total: 0,
+                    };
+                }
+                const safePattern = regex
+                    ? pattern
+                    : pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const flags = caseSensitive ? 'g' : 'gi';
+                let matcher;
+                try {
+                    matcher = new RegExp(safePattern, flags);
                 }
-                const saveResult = await fsInstance.save_extracted_content(extracted_content);
-                // NOTE: Do NOT mention file_system tag here as it misleads LLM to use read_file action
-                // The extracted content preview above is sufficient for most tasks
-                memory = `Extracted content from ${page.url}\n<query>${params.query}</query>\n<extracted_content>\n${display}${lines.length - count} more lines (auto-saved, no need to read)...\n</extracted_content>`;
-                includeOnce = true;
+                catch (error) {
+                    return {
+                        error: `Invalid regex pattern: ${String(error)}`,
+                        matches: [],
+                        total: 0,
+                    };
+                }
+                const matches = [];
+                let foundTotal = 0;
+                let m;
+                while ((m = matcher.exec(sourceText)) !== null) {
+                    foundTotal += 1;
+                    if (matches.length < Math.max(1, maxResults)) {
+                        const start = Math.max(0, m.index - Math.max(0, contextChars));
+                        const end = Math.min(sourceText.length, m.index + m[0].length + Math.max(0, contextChars));
+                        matches.push({
+                            position: m.index,
+                            match: m[0],
+                            snippet: sourceText.slice(start, end),
+                        });
+                    }
+                    if (m[0].length === 0) {
+                        matcher.lastIndex += 1;
+                    }
+                }
+                return {
+                    matches,
+                    total: foundTotal,
+                    truncated: foundTotal > matches.length,
+                };
+            }, {
+                pattern: params.pattern,
+                regex: params.regex,
+                caseSensitive: params.case_sensitive,
+                contextChars: params.context_chars,
+                cssScope: params.css_scope ?? null,
+                maxResults: params.max_results,
+            }));
+            if (!searchResult) {
+                return new ActionResult({ error: 'search_page returned no result' });
+            }
+            if (searchResult.error) {
+                return new ActionResult({
+                    error: `search_page: ${searchResult.error}`,
+                });
+            }
+            const total = searchResult.total ?? 0;
+            const matches = searchResult.matches ?? [];
+            if (total === 0 || !matches.length) {
+                const noMatchMessage = `No matches found for "${params.pattern}".`;
+                return new ActionResult({
+                    extracted_content: noMatchMessage,
+                    long_term_memory: `Searched page for "${params.pattern}": 0 matches found.`,
+                });
+            }
+            const lines = [
+                `Found ${total} matches for "${params.pattern}" in page text:`,
+            ];
+            for (let i = 0; i < matches.length; i += 1) {
+                const match = matches[i];
+                const compactSnippet = match.snippet.replace(/\s+/g, ' ').trim();
+                lines.push(`${i + 1}. [pos ${match.position}] "${match.match}" -> ${compactSnippet}`);
+            }
+            if (searchResult.truncated) {
+                lines.push(`... showing first ${matches.length} matches (increase max_results to see more).`);
+            }
+            const memory = `Searched page for "${params.pattern}": ${total} match${total === 1 ? '' : 'es'} found.`;
+            return new ActionResult({
+                extracted_content: lines.join('\n'),
+                long_term_memory: memory,
+            });
+        });
+        this.registry.action('Query DOM elements by CSS selector (like find). Zero LLM cost and instant.', { param_model: FindElementsActionSchema })(async function find_elements(params, { browser_session, signal }) {
+            if (!browser_session)
+                throw new Error('Browser session missing');
+            throwIfAborted(signal);
+            const page = await browser_session.get_current_page();
+            if (!page?.evaluate) {
+                throw new BrowserError('No active page for find_elements.');
+            }
+            const result = (await page.evaluate(({ selector, attributes, maxResults, includeText, }) => {
+                let elements;
+                try {
+                    elements = Array.from(document.querySelectorAll(selector));
+                }
+                catch (error) {
+                    return {
+                        error: `Invalid selector: ${String(error)}`,
+                        elements: [],
+                        total: 0,
+                    };
+                }
+                const selected = elements.slice(0, Math.max(1, maxResults));
+                const payload = selected.map((el, idx) => {
+                    const attrs = {};
+                    if (attributes?.length) {
+                        for (const attr of attributes) {
+                            const value = el.getAttribute(attr);
+                            if (value != null) {
+                                attrs[attr] = value;
+                            }
+                        }
+                    }
+                    return {
+                        index: idx + 1,
+                        tag: el.tagName.toLowerCase(),
+                        text: includeText
+                            ? (el.textContent || '').replace(/\s+/g, ' ').trim()
+                            : '',
+                        attributes: attrs,
+                    };
+                });
+                return {
+                    elements: payload,
+                    total: elements.length,
+                    truncated: elements.length > selected.length,
+                };
+            }, {
+                selector: params.selector,
+                attributes: params.attributes ?? null,
+                maxResults: params.max_results,
+                includeText: params.include_text,
+            }));
+            if (!result) {
+                return new ActionResult({ error: 'find_elements returned no result' });
+            }
+            if (result.error) {
+                return new ActionResult({ error: `find_elements: ${result.error}` });
+            }
+            const elements = result.elements ?? [];
+            const total = result.total ?? 0;
+            if (!elements.length) {
+                const msg = `No elements found for selector "${params.selector}".`;
+                return new ActionResult({
+                    extracted_content: msg,
+                    long_term_memory: msg,
+                });
+            }
+            const lines = [
+                `Found ${total} element${total === 1 ? '' : 's'} for selector "${params.selector}":`,
+            ];
+            for (const el of elements) {
+                const attrs = Object.entries(el.attributes || {})
+                    .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+                    .join(' ');
+                const text = params.include_text && el.text
+                    ? ` text=${JSON.stringify(el.text)}`
+                    : '';
+                lines.push(`${el.index}. <${el.tag}>${text}${attrs ? ` ${attrs}` : ''}`.trim());
+            }
+            if (result.truncated) {
+                lines.push(`... showing first ${elements.length} elements (increase max_results to see more).`);
             }
             return new ActionResult({
-                extracted_content,
-                include_extracted_content_only_once: includeOnce,
-                long_term_memory: memory,
+                extracted_content: lines.join('\n'),
+                long_term_memory: `Queried selector "${params.selector}" and found ${total} element${total === 1 ? '' : 's'}.`,
             });
         });
     }
     registerScrollActions() {
+        const registry = this.registry;
         const scrollLogger = this.logger; // Capture logger reference for use in named function
         // Define the scroll handler implementation (shared by multiple action names for LLM compatibility)
         const scrollImpl = async (params, { browser_session, signal }) => {
@@ -487,7 +1347,9 @@ ${content}`;
                     }
                     catch (error) {
                         if (i === retries - 1) {
-                            throw new Error(`Scroll failed due to an error: ${error}`);
+                            throw new Error(`Scroll failed due to an error: ${error}`, {
+                                cause: error,
+                            });
                         }
                         await waitWithSignal(1000, signal);
                     }
@@ -495,8 +1357,8 @@ ${content}`;
                 return 0;
             };
             const windowHeight = await getWindowHeight();
-            const scrollAmount = Math.floor(windowHeight * params.num_pages);
-            const pagesScrolled = params.num_pages;
+            const pagesScrolled = params.pages ?? params.num_pages ?? 1;
+            const scrollAmount = Math.floor(windowHeight * pagesScrolled);
             const dy = params.down ? scrollAmount : -scrollAmount;
             const direction = params.down ? 'down' : 'up';
             let scrollTarget = 'the page';
@@ -505,7 +1367,9 @@ ${content}`;
                 try {
                     const elementNode = await browser_session.get_dom_element_by_index(params.index, { signal });
                     if (!elementNode) {
-                        throw new Error(`Element index ${params.index} does not exist - retry or use alternative actions`);
+                        return new ActionResult({
+                            error: `Element index ${params.index} not found in browser state`,
+                        });
                     }
                     // Try direct container scrolling (no events that might close dropdowns)
                     const containerScrollJs = `
@@ -518,8 +1382,6 @@ ${content}`;
 								return { success: false, reason: 'Element not found by XPath' };
 							}
 
-							console.log('[SCROLL DEBUG] Starting direct container scroll for element:', targetElement.tagName);
-
 							// Try to find scrollable containers in the hierarchy (starting from element itself)
 							let currentElement = targetElement;
 							let scrollSuccess = false;
@@ -533,12 +1395,6 @@ ${content}`;
 								const hasScrollableY = /(auto|scroll|overlay)/.test(computedStyle.overflowY);
 								const canScrollVertically = currentElement.scrollHeight > currentElement.clientHeight;
 
-								console.log('[SCROLL DEBUG] Checking element:', currentElement.tagName,
-									'hasScrollableY:', hasScrollableY,
-									'canScrollVertically:', canScrollVertically,
-									'scrollHeight:', currentElement.scrollHeight,
-									'clientHeight:', currentElement.clientHeight);
-
 								if (hasScrollableY && canScrollVertically) {
 									const beforeScroll = currentElement.scrollTop;
 									const maxScroll = currentElement.scrollHeight - currentElement.clientHeight;
@@ -559,14 +1415,10 @@ ${content}`;
 									const afterScroll = currentElement.scrollTop;
 									const actualScrollDelta = afterScroll - beforeScroll;
 
-									console.log('[SCROLL DEBUG] Scroll attempt:', currentElement.tagName,
-										'before:', beforeScroll, 'after:', afterScroll, 'delta:', actualScrollDelta);
-
 									if (Math.abs(actualScrollDelta) > 0.5) {
 										scrollSuccess = true;
 										scrolledElement = currentElement;
 										scrollDelta = actualScrollDelta;
-										console.log('[SCROLL DEBUG] Successfully scrolled container:', currentElement.tagName, 'delta:', actualScrollDelta);
 										break;
 									}
 								}
@@ -592,7 +1444,6 @@ ${content}`;
 								};
 							} else {
 								// No container found or could scroll
-								console.log('[SCROLL DEBUG] No scrollable container found for element');
 								return {
 									success: false,
 									reason: 'No scrollable container found',
@@ -639,7 +1490,10 @@ ${content}`;
                 scrollTarget.includes('mouse wheel failed')) {
                 scrollLogger.debug(`🔄 Performing page-level scrolling. Reason: ${scrollTarget}`);
                 try {
-                    await browser_session._scrollContainer(dy);
+                    await dispatchBrowserEventIfAvailable(browser_session, new ScrollEvent({
+                        direction,
+                        amount: Math.abs(dy),
+                    }), () => browser_session._scrollContainer(dy));
                 }
                 catch (error) {
                     // Hard fallback: always works on root scroller
@@ -709,27 +1563,33 @@ ${content}`;
         })(async function scroll_to_text(params, { browser_session }) {
             if (!browser_session)
                 throw new Error('Browser session missing');
-            const page = await browser_session.get_current_page();
-            if (!page?.evaluate) {
-                throw new BrowserError('Unable to access page for scrolling.');
-            }
-            const success = await page.evaluate(({ text }) => {
-                const iterator = document.createNodeIterator(document.body, NodeFilter.SHOW_ELEMENT);
-                let node;
-                while ((node = iterator.nextNode())) {
-                    const el = node;
-                    if (!el || !el.textContent)
-                        continue;
-                    if (el.textContent.toLowerCase().includes(text.toLowerCase())) {
-                        el.scrollIntoView({ behavior: 'smooth', block: 'center' });
-                        return true;
+            await dispatchBrowserEventIfAvailable(browser_session, new ScrollToTextEvent({
+                text: params.text,
+                direction: 'down',
+            }), async () => {
+                const page = await browser_session.get_current_page();
+                if (!page?.evaluate) {
+                    throw new BrowserError('Unable to access page for scrolling.');
+                }
+                const success = await page.evaluate(({ text }) => {
+                    const iterator = document.createNodeIterator(document.body, NodeFilter.SHOW_ELEMENT);
+                    let node;
+                    while ((node = iterator.nextNode())) {
+                        const el = node;
+                        if (!el || !el.textContent)
+                            continue;
+                        if (el.textContent.toLowerCase().includes(text.toLowerCase())) {
+                            el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+                            return true;
+                        }
                     }
+                    return false;
+                }, { text: params.text });
+                if (!success) {
+                    throw new BrowserError(`Text '${params.text}' not found on page`);
                 }
-                return false;
-            }, { text: params.text });
-            if (!success) {
-                throw new BrowserError(`Text '${params.text}' not found on page`);
-            }
+                return null;
+            });
             const msg = `🔍  Scrolled to text: ${params.text}`;
             return new ActionResult({
                 extracted_content: msg,
@@ -737,18 +1597,49 @@ ${content}`;
                 long_term_memory: msg,
             });
         });
+        this.registry.action('Scroll to text.', {
+            param_model: ScrollToTextActionSchema,
+            action_name: 'find_text',
+        })(async function find_text(params, ctx) {
+            try {
+                return await registry.execute_action('scroll_to_text', params, ctx);
+            }
+            catch (error) {
+                if (isAbortError(error)) {
+                    throw error;
+                }
+                const msg = `Text '${params.text}' not found or not visible on page`;
+                return new ActionResult({
+                    extracted_content: msg,
+                    long_term_memory: `Tried scrolling to text '${params.text}' but it was not found`,
+                });
+            }
+        });
     }
     registerFileSystemActions() {
-        this.registry.action('Read file_name from file system', {
+        const registry = this.registry;
+        this.registry.action('Read the complete content of a file. Use this to view file contents before editing or to retrieve data from files. Supports text files (txt, md, json, csv, jsonl), documents (pdf, docx), and images (jpg, png).', {
             param_model: ReadFileActionSchema,
         })(async function read_file(params, { file_system, available_file_paths }) {
             const fsInstance = file_system ?? new FileSystem(process.cwd(), false);
             const allowed = Array.isArray(available_file_paths) &&
                 available_file_paths.includes(params.file_name);
-            const result = await fsInstance.read_file(params.file_name, allowed);
+            const structuredResult = typeof fsInstance.read_file_structured === 'function'
+                ? await fsInstance.read_file_structured(params.file_name, allowed)
+                : {
+                    message: await fsInstance.read_file(params.file_name, allowed),
+                    images: null,
+                };
+            const result = String(structuredResult?.message ?? '');
+            const images = Array.isArray(structuredResult?.images)
+                ? structuredResult.images
+                : null;
             const MAX_MEMORY_SIZE = 1000;
             let memory = result;
-            if (result.length > MAX_MEMORY_SIZE) {
+            if (images && images.length > 0) {
+                memory = `Read image file ${params.file_name}`;
+            }
+            else if (result.length > MAX_MEMORY_SIZE) {
                 const lines = result.split('\n');
                 let preview = '';
                 let used = 0;
@@ -764,12 +1655,373 @@ ${content}`;
             }
             return new ActionResult({
                 extracted_content: result,
-                include_in_memory: true,
                 long_term_memory: memory,
+                images,
                 include_extracted_content_only_once: true,
             });
         });
-        this.registry.action('Write content to file', {
+        this.registry.action('Intelligently read long content to find specific information. Works on current page (source="page") or files. For large content, uses search to identify relevant sections. Best for long articles, documents, or any content where you know what you are looking for.', { param_model: ReadLongContentActionSchema })(async function read_long_content(params, { browser_session, page_extraction_llm, available_file_paths, signal }) {
+            throwIfAborted(signal);
+            const goal = params.goal.trim();
+            const source = (params.source || 'page').trim();
+            const context = (params.context || '').trim();
+            const maxChars = 50000;
+            const chunkSize = 2000;
+            const fallbackSearchTerms = (() => {
+                const tokens = `${goal} ${context}`
+                    .toLowerCase()
+                    .match(/[a-z0-9][a-z0-9-]{2,}/g);
+                if (!tokens?.length) {
+                    return goal ? [goal] : ['content'];
+                }
+                return Array.from(new Set(tokens)).slice(0, 5);
+            })();
+            const extractSearchTerms = async () => {
+                const extractionLlm = page_extraction_llm;
+                if (!extractionLlm || typeof extractionLlm.ainvoke !== 'function') {
+                    return fallbackSearchTerms;
+                }
+                const prompt = `Extract 3-5 key search terms from this goal that would help find relevant sections.
+Return only the terms, one per line, no numbering or bullets.
+
+Goal: ${goal}
+
+Context: ${context}`;
+                try {
+                    const response = await runWithTimeoutAndSignal(async () => (await extractionLlm.ainvoke([new UserMessage(prompt)], undefined, { signal: signal ?? undefined })), 12000, signal, 'Timed out extracting search terms');
+                    const parsed = (response?.completion ?? '')
+                        .split('\n')
+                        .map((line) => line
+                        .trim()
+                        .replace(/^[-\d.)\s]+/, '')
+                        .trim())
+                        .filter(Boolean);
+                    const unique = Array.from(new Set(parsed)).slice(0, 5);
+                    return unique.length ? unique : fallbackSearchTerms;
+                }
+                catch (error) {
+                    if (isAbortError(error)) {
+                        throw error;
+                    }
+                    return fallbackSearchTerms;
+                }
+            };
+            const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const searchText = (value, pattern, contextChars = 100) => {
+                let regex;
+                try {
+                    regex = new RegExp(pattern, 'gi');
+                }
+                catch {
+                    regex = new RegExp(escapeRegExp(pattern), 'gi');
+                }
+                const matches = [];
+                let match = regex.exec(value);
+                while (match != null) {
+                    const start = Math.max(0, match.index - contextChars);
+                    const end = Math.min(value.length, match.index + match[0].length + contextChars);
+                    matches.push({
+                        position: match.index,
+                        snippet: value.slice(start, end),
+                    });
+                    if (!regex.global) {
+                        break;
+                    }
+                    match = regex.exec(value);
+                }
+                return matches;
+            };
+            const chunkContent = (value, size = chunkSize) => {
+                const chunks = [];
+                for (let start = 0; start < value.length; start += size) {
+                    chunks.push({
+                        start,
+                        end: Math.min(start + size, value.length),
+                        text: value.slice(start, start + size),
+                    });
+                }
+                return chunks;
+            };
+            const getCurrentPageUrl = (page) => {
+                const value = page?.url;
+                if (typeof value === 'function') {
+                    return String(value.call(page) ?? '');
+                }
+                return typeof value === 'string' ? value : '';
+            };
+            const readPdfByPage = async (filePath) => {
+                const buffer = await fsp.readFile(filePath);
+                try {
+                    const pdfParseModule = (await import('pdf-parse'));
+                    if (typeof pdfParseModule.PDFParse === 'function') {
+                        const Parser = pdfParseModule.PDFParse;
+                        const parser = new Parser({ data: buffer });
+                        try {
+                            let numPages = 0;
+                            try {
+                                const info = await parser.getInfo?.({ parsePageInfo: false });
+                                numPages = Number(info?.total ?? 0);
+                            }
+                            catch {
+                                numPages = 0;
+                            }
+                            if (!Number.isFinite(numPages) || numPages <= 0) {
+                                const full = await parser.getText();
+                                const text = typeof full?.text === 'string' ? full.text : '';
+                                return {
+                                    numPages: 1,
+                                    pageTexts: [text],
+                                    totalChars: text.length,
+                                };
+                            }
+                            const pageTexts = [];
+                            let totalChars = 0;
+                            for (let pageNumber = 1; pageNumber <= numPages; pageNumber += 1) {
+                                const pageResult = await parser.getText({
+                                    partial: [pageNumber],
+                                });
+                                const text = typeof pageResult?.text === 'string' ? pageResult.text : '';
+                                pageTexts.push(text);
+                                totalChars += text.length;
+                            }
+                            return {
+                                numPages,
+                                pageTexts,
+                                totalChars,
+                            };
+                        }
+                        finally {
+                            if (typeof parser.destroy === 'function') {
+                                await parser.destroy();
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Fall back to the compatibility parser.
+                }
+                const parsed = await extractPdfText(buffer);
+                const text = parsed.text ?? '';
+                return {
+                    numPages: Math.max(parsed.totalPages, 1),
+                    pageTexts: [text],
+                    totalChars: text.length,
+                };
+            };
+            try {
+                let content = '';
+                let sourceName = 'content';
+                if (source.toLowerCase() === 'page') {
+                    if (!browser_session) {
+                        throw new BrowserError('Browser session missing for page content.');
+                    }
+                    const page = await browser_session.get_current_page();
+                    if (!page?.content) {
+                        throw new BrowserError('No active page available to read content.');
+                    }
+                    const html = await page.content();
+                    const pageUrl = getCurrentPageUrl(page);
+                    const markdown = extractCleanMarkdownFromHtml(html || '', {
+                        extract_links: false,
+                        method: 'page_content',
+                        url: pageUrl || undefined,
+                    });
+                    content = markdown.content;
+                    sourceName = 'current page';
+                    if (!content) {
+                        return new ActionResult({
+                            extracted_content: 'Error: No page content available',
+                            long_term_memory: 'Failed to read page: no content',
+                        });
+                    }
+                }
+                else {
+                    const allowedPaths = new Set(Array.isArray(available_file_paths) ? available_file_paths : []);
+                    const downloadedFiles = Array.isArray(browser_session?.downloaded_files)
+                        ? browser_session.downloaded_files
+                        : [];
+                    for (const filePath of downloadedFiles) {
+                        allowedPaths.add(filePath);
+                    }
+                    if (!allowedPaths.has(source)) {
+                        const message = `Error: File path not in available_file_paths: ${source}. ` +
+                            'The user must add this path to available_file_paths when creating the Agent.';
+                        return new ActionResult({
+                            extracted_content: message,
+                            long_term_memory: `Failed to read: file path not allowed: ${source}`,
+                        });
+                    }
+                    if (!fs.existsSync(source)) {
+                        return new ActionResult({
+                            extracted_content: `Error: File not found: ${source}`,
+                            long_term_memory: 'Failed to read: file not found',
+                        });
+                    }
+                    const ext = path.extname(source).toLowerCase();
+                    sourceName = path.basename(source);
+                    if (ext === '.pdf') {
+                        const pdfData = await readPdfByPage(source);
+                        const numPages = pdfData.numPages;
+                        const pageTexts = pdfData.pageTexts;
+                        const totalChars = pdfData.totalChars;
+                        if (totalChars <= maxChars) {
+                            const contentParts = [];
+                            for (let pageIndex = 0; pageIndex < pageTexts.length; pageIndex += 1) {
+                                const pageText = pageTexts[pageIndex] ?? '';
+                                if (!pageText.trim()) {
+                                    continue;
+                                }
+                                contentParts.push(`--- Page ${pageIndex + 1} ---\n${pageText}`);
+                            }
+                            const allContent = contentParts.join('\n\n');
+                            return new ActionResult({
+                                extracted_content: `PDF: ${sourceName} (${numPages} pages)\n\n${allContent}`,
+                                long_term_memory: `Read ${sourceName} (${numPages} pages, ${totalChars.toLocaleString()} chars) for goal: ${goal.slice(0, 50)}`,
+                                include_extracted_content_only_once: true,
+                            });
+                        }
+                        const searchTerms = await extractSearchTerms();
+                        const pageScores = new Map();
+                        for (const term of searchTerms) {
+                            if (!term.trim()) {
+                                continue;
+                            }
+                            const pattern = new RegExp(escapeRegExp(term), 'i');
+                            for (let pageIndex = 0; pageIndex < pageTexts.length; pageIndex += 1) {
+                                const pageText = pageTexts[pageIndex] ?? '';
+                                if (pattern.test(pageText)) {
+                                    const pageNumber = pageIndex + 1;
+                                    pageScores.set(pageNumber, (pageScores.get(pageNumber) ?? 0) + 1);
+                                }
+                            }
+                        }
+                        const pagesToRead = [1];
+                        const sortedPages = Array.from(pageScores.entries()).sort((a, b) => b[1] - a[1]);
+                        for (const [pageNumber] of sortedPages) {
+                            if (!pagesToRead.includes(pageNumber)) {
+                                pagesToRead.push(pageNumber);
+                            }
+                        }
+                        const contentParts = [];
+                        let charsUsed = 0;
+                        const pagesIncluded = [];
+                        const pageOrder = Array.from(new Set(pagesToRead)).sort((a, b) => a - b);
+                        for (const pageNumber of pageOrder) {
+                            const pageText = pageTexts[pageNumber - 1] ?? '';
+                            const pageHeader = `--- Page ${pageNumber} ---\n`;
+                            const remaining = maxChars - charsUsed;
+                            if (remaining < pageHeader.length + 50) {
+                                break;
+                            }
+                            let pageContent = `${pageHeader}${pageText}`;
+                            if (pageContent.length > remaining) {
+                                const truncationSuffix = '\n[...truncated]';
+                                pageContent =
+                                    pageContent.slice(0, remaining - truncationSuffix.length) +
+                                        truncationSuffix;
+                            }
+                            contentParts.push(pageContent);
+                            charsUsed += pageContent.length;
+                            pagesIncluded.push(pageNumber);
+                        }
+                        const partialPdfContent = contentParts.join('\n\n');
+                        return new ActionResult({
+                            extracted_content: `PDF: ${sourceName} (${numPages} pages, showing ${pagesIncluded.length} relevant)\n\n` +
+                                partialPdfContent,
+                            long_term_memory: `Read ${sourceName} (${pagesIncluded.length} relevant pages of ${numPages}) ` +
+                                `for goal: ${goal.slice(0, 50)}`,
+                            include_extracted_content_only_once: true,
+                        });
+                    }
+                    const fileBuffer = await fsp.readFile(source);
+                    content = fileBuffer.toString('utf-8');
+                }
+                if (!content.trim()) {
+                    return new ActionResult({
+                        extracted_content: `Error: No readable content found in ${sourceName}`,
+                        long_term_memory: `Failed to read ${sourceName}: no content`,
+                    });
+                }
+                if (content.length <= maxChars) {
+                    return new ActionResult({
+                        extracted_content: `Content from ${sourceName} (${content.length.toLocaleString()} chars):\n\n${content}`,
+                        long_term_memory: `Read ${sourceName} (${content.length.toLocaleString()} chars) for goal: ${goal.slice(0, 50)}`,
+                        include_extracted_content_only_once: true,
+                    });
+                }
+                const searchTerms = await extractSearchTerms();
+                const chunks = chunkContent(content, chunkSize);
+                const chunkScores = new Map();
+                for (const term of searchTerms) {
+                    const matches = searchText(content, term);
+                    for (const match of matches) {
+                        for (let index = 0; index < chunks.length; index += 1) {
+                            const chunk = chunks[index];
+                            if (chunk &&
+                                chunk.start <= match.position &&
+                                match.position < chunk.end) {
+                                chunkScores.set(index, (chunkScores.get(index) ?? 0) + 1);
+                                break;
+                            }
+                        }
+                    }
+                }
+                if (!chunkScores.size) {
+                    const truncated = content.slice(0, maxChars);
+                    return new ActionResult({
+                        extracted_content: `Content from ${sourceName} (first ${maxChars.toLocaleString()} of ${content.length.toLocaleString()} chars):\n\n${truncated}`,
+                        long_term_memory: `Read ${sourceName} (truncated to ${maxChars.toLocaleString()} chars, no matches for search terms)`,
+                        include_extracted_content_only_once: true,
+                    });
+                }
+                const sortedChunks = Array.from(chunkScores.entries()).sort((a, b) => b[1] - a[1]);
+                const selectedIndices = new Set([0]);
+                for (const [chunkIndex] of sortedChunks) {
+                    selectedIndices.add(chunkIndex);
+                }
+                const resultParts = [];
+                let totalChars = 0;
+                const orderedIndices = Array.from(selectedIndices).sort((a, b) => a - b);
+                for (const index of orderedIndices) {
+                    const chunk = chunks[index];
+                    if (!chunk) {
+                        continue;
+                    }
+                    if (totalChars + chunk.text.length > maxChars) {
+                        break;
+                    }
+                    const previousIndex = index - 1;
+                    if (index > 0 && !selectedIndices.has(previousIndex)) {
+                        resultParts.push('\n[...]\n');
+                    }
+                    resultParts.push(chunk.text);
+                    totalChars += chunk.text.length;
+                }
+                const resultContent = resultParts.join('');
+                return new ActionResult({
+                    extracted_content: `Content from ${sourceName} (relevant sections, ${totalChars.toLocaleString()} of ${content.length.toLocaleString()} chars):\n\n` +
+                        resultContent,
+                    long_term_memory: `Read ${sourceName} (${selectedIndices.size} relevant sections of ${chunks.length}) ` +
+                        `for goal: ${goal.slice(0, 50)}`,
+                    include_extracted_content_only_once: true,
+                });
+            }
+            catch (error) {
+                if (isAbortError(error)) {
+                    throw error;
+                }
+                const errorMessage = `Error reading content: ${String(error.message ?? error)}`;
+                return new ActionResult({
+                    extracted_content: errorMessage,
+                    long_term_memory: errorMessage,
+                });
+            }
+        });
+        this.registry.action('Write content to a file. By default this OVERWRITES the entire file - use append=true to add to an existing file, or use replace_file for targeted edits within a file. ' +
+            'FILENAME RULES: Use only letters, numbers, underscores, hyphens, dots, parentheses. Spaces are auto-converted to hyphens. ' +
+            'SUPPORTED EXTENSIONS: .txt, .md, .json, .jsonl, .csv, .html, .xml, .pdf, .docx. ' +
+            'CANNOT write binary/image files (.png, .jpg, .mp4, etc.) - do not attempt to save screenshots as files. ' +
+            'For PDF files, write content in markdown format and it will be auto-converted to PDF.', {
             param_model: WriteFileActionSchema,
         })(async function write_file(params, { file_system }) {
             const fsInstance = file_system ?? new FileSystem(process.cwd(), false);
@@ -786,49 +2038,168 @@ ${content}`;
             const result = append
                 ? await fsInstance.append_file(params.file_name, content)
                 : await fsInstance.write_file(params.file_name, content);
-            const msg = `📝  ${result}`;
             return new ActionResult({
                 extracted_content: result,
-                include_in_memory: true,
                 long_term_memory: result,
             });
         });
-        this.registry.action('Replace text within an existing file', {
+        this.registry.action('Replace specific text within a file by searching for old_str and replacing with new_str. Use this for targeted edits like updating todo checkboxes or modifying specific lines without rewriting the entire file.', {
             param_model: ReplaceFileStrActionSchema,
         })(async function replace_file_str(params, { file_system }) {
             const fsInstance = file_system ?? new FileSystem(process.cwd(), false);
             const result = await fsInstance.replace_file_str(params.file_name, params.old_str, params.new_str);
             return new ActionResult({
                 extracted_content: result,
-                include_in_memory: true,
                 long_term_memory: result,
             });
         });
+        this.registry.action('Replace specific text within a file by searching for old_str and replacing with new_str. Use this for targeted edits like updating todo checkboxes or modifying specific lines without rewriting the entire file.', {
+            param_model: ReplaceFileStrActionSchema,
+            action_name: 'replace_file',
+        })(async function replace_file(params, ctx) {
+            return registry.execute_action('replace_file_str', params, ctx);
+        });
     }
-    registerKeyboardActions() {
-        this.registry.action('Send keys to the active page', {
-            param_model: SendKeysActionSchema,
-        })(async function send_keys(params, { browser_session }) {
+    registerUtilityActions() {
+        this.registry.action('Take a screenshot of the current viewport. If file_name is provided, saves to that file and returns the path. Otherwise, screenshot is included in the next browser_state observation.', { param_model: ScreenshotActionSchema })(async function screenshot(params, { browser_session, file_system, signal }) {
             if (!browser_session)
                 throw new Error('Browser session missing');
-            const page = await browser_session.get_current_page();
-            const keyboard = page?.keyboard;
-            if (!keyboard) {
-                throw new BrowserError('Keyboard input is not available on the current page.');
+            throwIfAborted(signal);
+            if (params.file_name) {
+                const screenshotB64 = await dispatchBrowserEventIfAvailable(browser_session, new ScreenshotEvent({
+                    full_page: false,
+                }), async () => (await browser_session.take_screenshot?.(false)) ?? null);
+                if (!screenshotB64) {
+                    return new ActionResult({
+                        error: 'Failed to capture screenshot.',
+                    });
+                }
+                const fsInstance = file_system ?? new FileSystem(process.cwd(), false);
+                let fileName = params.file_name;
+                if (!fileName.toLowerCase().endsWith('.png')) {
+                    fileName = `${fileName}.png`;
+                }
+                fileName = FileSystem.sanitize_filename(fileName);
+                const filePath = path.join(fsInstance.get_dir(), fileName);
+                await fsp.writeFile(filePath, Buffer.from(screenshotB64, 'base64'));
+                const msg = `📸 Saved screenshot to ${filePath}`;
+                return new ActionResult({
+                    extracted_content: msg,
+                    long_term_memory: msg,
+                    attachments: [filePath],
+                });
             }
-            try {
-                await keyboard.press(params.keys);
+            return new ActionResult({
+                extracted_content: 'Requested screenshot for next observation',
+                metadata: {
+                    include_screenshot: true,
+                },
+            });
+        });
+        this.registry.action('Execute browser JavaScript on the current page and return the result.', { param_model: EvaluateActionSchema })(async function evaluate(params, { browser_session, signal }) {
+            if (!browser_session)
+                throw new Error('Browser session missing');
+            throwIfAborted(signal);
+            const page = await browser_session.get_current_page();
+            if (!page?.evaluate) {
+                throw new BrowserError('No active page available for evaluate.');
             }
-            catch (error) {
-                if (error instanceof Error && error.message.includes('Unknown key')) {
-                    for (const char of params.keys) {
-                        await keyboard.press(char);
+            const validatedCode = validateAndFixJavaScript(params.code);
+            const payload = (await page.evaluate(async ({ code }) => {
+                const serialize = (value) => {
+                    if (value === undefined) {
+                        return null;
+                    }
+                    try {
+                        return JSON.parse(JSON.stringify(value));
                     }
+                    catch {
+                        return String(value);
+                    }
+                };
+                try {
+                    const raw = await Promise.resolve((0, eval)(code));
+                    return { ok: true, result: serialize(raw) };
                 }
-                else {
-                    throw error;
+                catch (error) {
+                    return {
+                        ok: false,
+                        error: error instanceof Error
+                            ? error.message
+                            : String(error ?? 'Unknown evaluate error'),
+                    };
+                }
+            }, { code: validatedCode }));
+            if (!payload) {
+                return new ActionResult({ error: 'evaluate returned no result' });
+            }
+            if (!payload.ok) {
+                const codePreview = validatedCode.length > 500
+                    ? `${validatedCode.slice(0, 500)}...`
+                    : validatedCode;
+                return new ActionResult({
+                    error: `JavaScript Execution Failed:\n` +
+                        `JavaScript execution error: ${payload.error ?? 'Unknown error'}\n\n` +
+                        `Validated Code (after quote fixing):\n${codePreview}`,
+                });
+            }
+            let rendered = typeof payload.result === 'string'
+                ? payload.result
+                : JSON.stringify(payload.result);
+            const imagePattern = /(data:image\/[^;]+;base64,[A-Za-z0-9+/=]+)/g;
+            const foundImages = rendered.match(imagePattern) ?? [];
+            let metadata = null;
+            if (foundImages.length > 0) {
+                metadata = { images: foundImages };
+                for (const imageData of foundImages) {
+                    rendered = rendered.split(imageData).join('[Image]');
                 }
             }
+            const maxChars = 20000;
+            if (rendered.length > maxChars) {
+                rendered = `${rendered.slice(0, maxChars - 50)}\n... [Truncated after 20000 characters]`;
+            }
+            const maxMemoryChars = 10000;
+            const includeExtractedContentOnlyOnce = rendered.length >= maxMemoryChars;
+            const longTermMemory = includeExtractedContentOnlyOnce
+                ? `JavaScript executed successfully, result length: ${rendered.length} characters.`
+                : rendered;
+            return new ActionResult({
+                extracted_content: rendered,
+                long_term_memory: longTermMemory,
+                include_extracted_content_only_once: includeExtractedContentOnlyOnce,
+                metadata,
+            });
+        });
+    }
+    registerKeyboardActions() {
+        this.registry.action('Send keys to the active page', {
+            param_model: SendKeysActionSchema,
+        })(async function send_keys(params, { browser_session }) {
+            if (!browser_session)
+                throw new Error('Browser session missing');
+            await dispatchBrowserEventIfAvailable(browser_session, new SendKeysEvent({ keys: params.keys }), async () => {
+                const page = await browser_session.get_current_page();
+                const keyboard = page?.keyboard;
+                if (!keyboard) {
+                    throw new BrowserError('Keyboard input is not available on the current page.');
+                }
+                try {
+                    await keyboard.press(params.keys);
+                }
+                catch (error) {
+                    if (error instanceof Error &&
+                        error.message.includes('Unknown key')) {
+                        for (const char of params.keys) {
+                            await keyboard.press(char);
+                        }
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+                return null;
+            });
             const msg = `⌨️  Sent keys: ${params.keys}`;
             return new ActionResult({
                 extracted_content: msg,
@@ -838,15 +2209,42 @@ ${content}`;
         });
     }
     registerDropdownActions() {
+        const registry = this.registry;
+        const dropdownLogger = this.logger;
+        const formatAvailableOptions = (options) => options
+            .map((opt) => `  - [${opt.index}] text=${JSON.stringify(opt.text)} value=${JSON.stringify(opt.value)}`)
+            .join('\n');
         this.registry.action('Get all options from a native dropdown or ARIA menu', { param_model: DropdownOptionsActionSchema })(async function get_dropdown_options(params, { browser_session, signal }) {
             if (!browser_session)
                 throw new Error('Browser session missing');
             throwIfAborted(signal);
-            const page = await browser_session.get_current_page();
             const domElement = await browser_session.get_dom_element_by_index(params.index, { signal });
             if (!domElement) {
-                throw new BrowserError(`Element index ${params.index} does not exist.`);
+                const msg = `Element index ${params.index} not available - page may have changed. Try refreshing browser state.`;
+                dropdownLogger.warning(`⚠️ ${msg}`);
+                return new ActionResult({
+                    extracted_content: msg,
+                });
+            }
+            if (typeof browser_session.dispatch_browser_event === 'function') {
+                const dispatchResult = await browser_session.dispatch_browser_event(new GetDropdownOptionsEvent({ node: domElement }));
+                const eventResult = dispatchResult?.event?.event_result;
+                const eventMessage = eventResult?.message ??
+                    eventResult?.short_term_memory ??
+                    eventResult?.formatted_options ??
+                    null;
+                if (eventMessage) {
+                    const memory = eventResult?.long_term_memory ??
+                        `Found dropdown options for index ${params.index}.`;
+                    return new ActionResult({
+                        extracted_content: eventMessage,
+                        include_in_memory: true,
+                        include_extracted_content_only_once: true,
+                        long_term_memory: memory,
+                    });
+                }
             }
+            const page = await browser_session.get_current_page();
             if (!page?.evaluate) {
                 throw new BrowserError('Unable to evaluate dropdown options on current page.');
             }
@@ -859,8 +2257,8 @@ ${content}`;
                     return null;
                 if (element.tagName?.toLowerCase() === 'select') {
                     const options = Array.from(element.options).map((opt, index) => ({
-                        text: opt.text,
-                        value: opt.value,
+                        text: opt.textContent?.trim() ?? '',
+                        value: (opt.value ?? '').trim(),
                         index,
                     }));
                     return { type: 'select', options };
@@ -881,8 +2279,8 @@ ${content}`;
             if (!payload || !payload.options?.length) {
                 throw new BrowserError('No options found for the specified dropdown.');
             }
-            const formatted = payload.options.map((opt) => `${opt.index}: text=${JSON.stringify(opt.text ?? '')}`);
-            formatted.push('Use the exact text string in select_dropdown_option');
+            const formatted = payload.options.map((opt) => `${opt.index}: text=${JSON.stringify(opt.text ?? '')}, value=${JSON.stringify(opt.value ?? '')}`);
+            formatted.push('Prefer exact text first; if needed select_dropdown_option also supports case-insensitive text/value matching.');
             const message = formatted.join('\n');
             return new ActionResult({
                 extracted_content: message,
@@ -891,17 +2289,49 @@ ${content}`;
                 long_term_memory: `Found dropdown options for index ${params.index}.`,
             });
         });
+        this.registry.action('Get all options from a native dropdown or ARIA menu', {
+            param_model: DropdownOptionsActionSchema,
+            action_name: 'dropdown_options',
+        })(async function dropdown_options(params, ctx) {
+            return registry.execute_action('get_dropdown_options', params, ctx);
+        });
         this.registry.action('Select dropdown option or ARIA menu item by text', {
             param_model: SelectDropdownActionSchema,
         })(async function select_dropdown_option(params, { browser_session, signal }) {
             if (!browser_session)
                 throw new Error('Browser session missing');
             throwIfAborted(signal);
-            const page = await browser_session.get_current_page();
             const domElement = await browser_session.get_dom_element_by_index(params.index, { signal });
+            if (!domElement) {
+                const msg = `Element index ${params.index} not available - page may have changed. Try refreshing browser state.`;
+                dropdownLogger.warning(`⚠️ ${msg}`);
+                return new ActionResult({
+                    extracted_content: msg,
+                });
+            }
             if (!domElement?.xpath) {
                 throw new BrowserError('DOM element does not include an XPath selector.');
             }
+            if (typeof browser_session.dispatch_browser_event === 'function') {
+                const dispatchResult = await browser_session.dispatch_browser_event(new SelectDropdownOptionEvent({
+                    node: domElement,
+                    text: params.text,
+                }));
+                const eventResult = dispatchResult?.event?.event_result;
+                const eventMessage = eventResult?.message ??
+                    eventResult?.short_term_memory ??
+                    eventResult?.matched_text ??
+                    null;
+                if (eventMessage) {
+                    const memory = eventResult?.long_term_memory ?? eventMessage;
+                    return new ActionResult({
+                        extracted_content: eventMessage,
+                        include_in_memory: true,
+                        long_term_memory: memory,
+                    });
+                }
+            }
+            const page = await browser_session.get_current_page();
             if (!page) {
                 throw new BrowserError('No active page for selection.');
             }
@@ -922,45 +2352,121 @@ ${content}`;
                     if (!typeInfo?.found)
                         continue;
                     if (typeInfo.type === 'select') {
-                        await frame
-                            .locator(domElement.xpath)
-                            .first()
-                            .select_option({ label: params.text });
-                        const msg = `Selected option ${params.text}`;
-                        return new ActionResult({
-                            extracted_content: msg,
-                            include_in_memory: true,
-                            long_term_memory: msg,
-                        });
+                        const selection = await frame.evaluate(({ xpath, text }) => {
+                            const root = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
+                            if (!root || root.tagName?.toLowerCase() !== 'select') {
+                                return { found: false };
+                            }
+                            const options = Array.from(root.options).map((opt, index) => ({
+                                index,
+                                text: opt.textContent?.trim() ?? '',
+                                value: (opt.value ?? '').trim(),
+                            }));
+                            const normalize = (value) => value.trim().toLowerCase();
+                            const targetRaw = text.trim();
+                            const targetLower = normalize(text);
+                            let matchedIndex = options.findIndex((opt) => opt.text === targetRaw || opt.value === targetRaw);
+                            if (matchedIndex < 0) {
+                                matchedIndex = options.findIndex((opt) => normalize(opt.text) === targetLower ||
+                                    normalize(opt.value) === targetLower);
+                            }
+                            if (matchedIndex < 0) {
+                                return { found: true, success: false, options };
+                            }
+                            const matched = options[matchedIndex];
+                            root.value = matched.value;
+                            root.dispatchEvent(new Event('input', { bubbles: true }));
+                            root.dispatchEvent(new Event('change', { bubbles: true }));
+                            const selectedOption = root.selectedIndex >= 0
+                                ? root.options[root.selectedIndex]
+                                : null;
+                            const selectedText = selectedOption?.textContent?.trim() ?? '';
+                            const selectedValue = (root.value ?? '').trim();
+                            const verified = normalize(selectedValue) === normalize(matched.value) ||
+                                normalize(selectedText) === normalize(matched.text);
+                            return {
+                                found: true,
+                                success: verified,
+                                options,
+                                selectedText,
+                                selectedValue,
+                                matched,
+                            };
+                        }, { xpath: domElement.xpath, text: params.text });
+                        if (selection?.found && selection.success) {
+                            const matchedText = selection.matched?.text ?? params.text;
+                            const matchedValue = selection.matched?.value ?? '';
+                            const msg = `Selected option ${matchedText} (${matchedValue})`;
+                            return new ActionResult({
+                                extracted_content: msg,
+                                include_in_memory: true,
+                                long_term_memory: msg,
+                            });
+                        }
+                        if (selection?.found) {
+                            const details = formatAvailableOptions(selection.options ?? []);
+                            throw new BrowserError(`Could not select option '${params.text}' for index ${params.index}.\nAvailable options:\n${details}`);
+                        }
+                        continue;
                     }
                     const clicked = await frame.evaluate(({ xpath, text }) => {
                         const root = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
                         if (!root)
                             return false;
                         const nodes = root.querySelectorAll('[role="menuitem"],[role="option"]');
-                        for (const node of Array.from(nodes)) {
-                            if (node.textContent?.trim() === text) {
-                                node.click();
-                                return true;
-                            }
+                        const options = Array.from(nodes).map((node, index) => ({
+                            index,
+                            text: node.textContent?.trim() ?? '',
+                            value: node.textContent?.trim() ?? '',
+                        }));
+                        const normalize = (value) => value.trim().toLowerCase();
+                        const targetRaw = text.trim();
+                        const targetLower = normalize(text);
+                        let matchedIndex = options.findIndex((opt) => opt.text === targetRaw || opt.value === targetRaw);
+                        if (matchedIndex < 0) {
+                            matchedIndex = options.findIndex((opt) => normalize(opt.text) === targetLower ||
+                                normalize(opt.value) === targetLower);
+                        }
+                        if (matchedIndex < 0) {
+                            return { found: true, success: false, options };
                         }
-                        return false;
+                        nodes[matchedIndex].click();
+                        return {
+                            found: true,
+                            success: true,
+                            options,
+                            matched: options[matchedIndex],
+                        };
                     }, { xpath: domElement.xpath, text: params.text });
-                    if (clicked) {
-                        const msg = `Selected menu item ${params.text}`;
+                    if (clicked?.found && clicked.success) {
+                        const matchedText = clicked.matched?.text ?? params.text;
+                        const msg = `Selected menu item ${matchedText}`;
                         return new ActionResult({
                             extracted_content: msg,
                             include_in_memory: true,
                             long_term_memory: msg,
                         });
                     }
+                    if (clicked?.found) {
+                        const details = formatAvailableOptions(clicked.options ?? []);
+                        throw new BrowserError(`Could not select option '${params.text}' for index ${params.index}.\nAvailable options:\n${details}`);
+                    }
                 }
                 catch (error) {
+                    if (error instanceof BrowserError) {
+                        throw error;
+                    }
                     continue;
                 }
             }
             throw new BrowserError(`Could not select option '${params.text}' for index ${params.index}`);
         });
+        this.registry.action('Select dropdown option or ARIA menu item by text', {
+            param_model: SelectDropdownActionSchema,
+            action_name: 'select_dropdown',
+        })(async function select_dropdown(params, ctx) {
+            return registry.execute_action('select_dropdown_option', params, ctx);
+        });
     }
     registerSheetsActions() {
         const gotoSheetsRange = this.gotoSheetsRange.bind(this);
@@ -1090,13 +2596,11 @@ ${content}`;
         if (outputModel) {
             const structuredSchema = StructuredOutputActionSchema(outputModel);
             this.registry.action('Complete task - with return text and success flag.', { param_model: structuredSchema })(async function done(params) {
-                const payload = { ...params.data };
-                for (const key of Object.keys(payload)) {
-                    const value = payload[key];
-                    if (value && typeof value === 'object' && 'value' in value) {
-                        payload[key] = value.value;
-                    }
-                }
+                const payload = params.data &&
+                    typeof params.data === 'object' &&
+                    !Array.isArray(params.data)
+                    ? params.data
+                    : {};
                 return new ActionResult({
                     is_done: true,
                     success: params.success,
@@ -1121,9 +2625,6 @@ ${content}`;
                 if (displayFilesInDoneText) {
                     let attachmentText = '';
                     for (const fileName of params.files_to_display) {
-                        if (fileName === 'todo.md') {
-                            continue;
-                        }
                         const content = fsInstance.display_file(fileName);
                         if (content) {
                             attachmentText += `\n\n${fileName}:\n${content}`;
@@ -1137,9 +2638,6 @@ ${content}`;
                 }
                 else {
                     for (const fileName of params.files_to_display) {
-                        if (fileName === 'todo.md') {
-                            continue;
-                        }
                         const content = fsInstance.display_file(fileName);
                         if (content) {
                             attachments.push(fileName);
@@ -1158,8 +2656,24 @@ ${content}`;
         });
     }
     use_structured_output_action(outputModel) {
+        this.outputModel = outputModel;
         this.registerDoneAction(outputModel);
     }
+    get_output_model() {
+        return this.outputModel;
+    }
+    exclude_action(actionName) {
+        this.registry.exclude_action(actionName);
+    }
+    set_coordinate_clicking(enabled) {
+        const resolved = Boolean(enabled);
+        if (resolved === this.coordinateClickingEnabled) {
+            return;
+        }
+        this.coordinateClickingEnabled = resolved;
+        this.registerClickActions();
+        this.logger.debug(`Coordinate clicking ${resolved ? 'enabled' : 'disabled'}`);
+    }
     action(description, options = {}) {
         return this.registry.action(description, options);
     }
@@ -1185,11 +2699,36 @@ ${content}`;
                 if (result == null) {
                     return new ActionResult();
                 }
-                return new ActionResult({ extracted_content: JSON.stringify(result) });
+                const resultType = result && typeof result === 'object'
+                    ? (result.constructor?.name ?? typeof result)
+                    : typeof result;
+                throw new Error(`Invalid action result type: ${resultType} of ${String(result)}`);
             }
             catch (error) {
+                if (error instanceof BrowserError) {
+                    if (error.long_term_memory != null) {
+                        if (error.short_term_memory != null) {
+                            return new ActionResult({
+                                extracted_content: error.short_term_memory,
+                                error: error.long_term_memory,
+                                include_extracted_content_only_once: true,
+                            });
+                        }
+                        return new ActionResult({
+                            error: error.long_term_memory,
+                        });
+                    }
+                    throw error;
+                }
+                const message = String(error?.message ?? error ?? '');
+                if (error instanceof Error &&
+                    message === `Error executing action ${actionName} due to timeout.`) {
+                    return new ActionResult({
+                        error: `${actionName} was not executed due to timeout.`,
+                    });
+                }
                 return new ActionResult({
-                    error: String(error?.message ?? error ?? ''),
+                    error: message,
                 });
             }
         }