browser-use 0.4.0 → 0.6.0

package/dist/browser/session.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { isIP } from 'node:net';
-import { execFile } from 'node:child_process';
+import { execFile, execFileSync, } from 'node:child_process';
 import { promisify } from 'node:util';
 import { createLogger } from '../logging-config.js';
 import { match_url_with_domain_pattern, uuid7str } from '../utils.js';
@@ -10,13 +10,14 @@ import { EventBus, } from '../event-bus.js';
 import { async_playwright, } from './types.js';
 import { BrowserProfile, CHROME_DOCKER_ARGS, DEFAULT_BROWSER_PROFILE, } from './profile.js';
 import { BrowserStateSummary, BrowserError, URLNotAllowedError, } from './views.js';
-import { AgentFocusChangedEvent, BrowserConnectedEvent, BrowserLaunchEvent, BrowserStartEvent, BrowserStoppedEvent, BrowserStopEvent, DialogOpenedEvent, DownloadProgressEvent, DownloadStartedEvent, FileDownloadedEvent, TabClosedEvent, TabCreatedEvent, } from './events.js';
+import { AgentFocusChangedEvent, BrowserConnectedEvent, BrowserErrorEvent, BrowserLaunchEvent, BrowserReconnectedEvent, BrowserReconnectingEvent, BrowserStartEvent, BrowserStoppedEvent, BrowserStopEvent, DialogOpenedEvent, DownloadProgressEvent, DownloadStartedEvent, FileDownloadedEvent, TabClosedEvent, TabCreatedEvent, } from './events.js';
 import { DOMElementNode, DOMState } from '../dom/views.js';
 import { normalize_url } from './utils.js';
 import { DomService } from '../dom/service.js';
 import { showDVDScreensaver, showSpinner, withDVDScreensaver, } from './dvd-screensaver.js';
 import { SessionManager } from './session-manager.js';
 import { AboutBlankWatchdog } from './watchdogs/aboutblank-watchdog.js';
+import { CaptchaWatchdog, } from './watchdogs/captcha-watchdog.js';
 import { CDPSessionWatchdog } from './watchdogs/cdp-session-watchdog.js';
 import { CrashWatchdog } from './watchdogs/crash-watchdog.js';
 import { DefaultActionWatchdog } from './watchdogs/default-action-watchdog.js';
@@ -31,6 +32,147 @@ import { ScreenshotWatchdog } from './watchdogs/screenshot-watchdog.js';
 import { SecurityWatchdog } from './watchdogs/security-watchdog.js';
 import { StorageStateWatchdog } from './watchdogs/storage-state-watchdog.js';
 const execFileAsync = promisify(execFile);
+const PLAYWRIGHT_OPTION_KEY_OVERRIDES = {
+    extra_http_headers: 'extraHTTPHeaders',
+};
+const EMPTY_DOM_RETRY_DELAY_MS = 250;
+const REMOTE_RECONNECT_DELAYS_MS = [1000, 2000, 4000];
+const REMOTE_RECONNECT_ATTEMPT_TIMEOUT_MS = 15_000;
+const cloneBrowserProfileConfig = (profile) => typeof structuredClone === 'function'
+    ? structuredClone(profile.config)
+    : JSON.parse(JSON.stringify(profile.config));
+const detectSystemChromeVariant = (executablePath) => {
+    const normalizedPath = String(executablePath ?? '')
+        .trim()
+        .toLowerCase();
+    if (!normalizedPath) {
+        return 'chrome';
+    }
+    if (normalizedPath.includes('chromium')) {
+        return 'chromium';
+    }
+    if (normalizedPath.includes('chrome canary') ||
+        normalizedPath.includes('chrome sxs')) {
+        return 'chrome-canary';
+    }
+    if (normalizedPath.includes('google-chrome-beta')) {
+        return 'chrome-beta';
+    }
+    if (normalizedPath.includes('google-chrome-unstable')) {
+        return 'chrome-unstable';
+    }
+    return 'chrome';
+};
+export const systemChrome = {
+    findExecutable() {
+        if (process.platform === 'darwin') {
+            const candidates = [
+                '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+                '/Applications/Chromium.app/Contents/MacOS/Chromium',
+                '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+            ];
+            return candidates.find((candidate) => fs.existsSync(candidate)) ?? null;
+        }
+        if (process.platform === 'linux') {
+            const commands = [
+                'google-chrome',
+                'google-chrome-stable',
+                'google-chrome-beta',
+                'google-chrome-unstable',
+                'chromium',
+                'chromium-browser',
+            ];
+            for (const command of commands) {
+                try {
+                    const resolved = execFileSync('which', [command], {
+                        encoding: 'utf8',
+                        stdio: ['ignore', 'pipe', 'ignore'],
+                    }).trim();
+                    if (resolved) {
+                        return resolved;
+                    }
+                }
+                catch {
+                    // Ignore missing commands and try the next candidate.
+                }
+            }
+            return null;
+        }
+        if (process.platform === 'win32') {
+            const candidates = [
+                path.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+                path.join(process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+                path.join(process.env.LOCALAPPDATA ?? '', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+                path.join(process.env.LOCALAPPDATA ?? '', 'Google', 'Chrome SxS', 'Application', 'chrome.exe'),
+                path.join(process.env.LOCALAPPDATA ?? '', 'Chromium', 'Application', 'chrome.exe'),
+                path.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'Chromium', 'Application', 'chrome.exe'),
+                path.join(process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)', 'Chromium', 'Application', 'chrome.exe'),
+            ];
+            return candidates.find((candidate) => fs.existsSync(candidate)) ?? null;
+        }
+        return null;
+    },
+    getUserDataDir(executablePath = systemChrome.findExecutable()) {
+        const variant = detectSystemChromeVariant(executablePath);
+        if (process.platform === 'darwin') {
+            const applicationSupportDir = path.join(os.homedir(), 'Library', 'Application Support');
+            if (variant === 'chromium') {
+                return path.join(applicationSupportDir, 'Chromium');
+            }
+            if (variant === 'chrome-canary') {
+                return path.join(applicationSupportDir, 'Google', 'Chrome Canary');
+            }
+            return path.join(applicationSupportDir, 'Google', 'Chrome');
+        }
+        if (process.platform === 'linux') {
+            if (variant === 'chromium') {
+                return path.join(os.homedir(), '.config', 'chromium');
+            }
+            if (variant === 'chrome-beta') {
+                return path.join(os.homedir(), '.config', 'google-chrome-beta');
+            }
+            if (variant === 'chrome-unstable') {
+                return path.join(os.homedir(), '.config', 'google-chrome-unstable');
+            }
+            return path.join(os.homedir(), '.config', 'google-chrome');
+        }
+        if (process.platform === 'win32') {
+            const localAppData = process.env.LOCALAPPDATA ?? path.join(os.homedir(), 'AppData', 'Local');
+            if (variant === 'chromium') {
+                return path.join(localAppData, 'Chromium', 'User Data');
+            }
+            if (variant === 'chrome-canary') {
+                return path.join(localAppData, 'Google', 'Chrome SxS', 'User Data');
+            }
+            return path.join(localAppData, 'Google', 'Chrome', 'User Data');
+        }
+        return null;
+    },
+    listProfiles(userDataDir = systemChrome.getUserDataDir()) {
+        if (!userDataDir) {
+            return [];
+        }
+        const localStatePath = path.join(userDataDir, 'Local State');
+        if (!fs.existsSync(localStatePath)) {
+            return [];
+        }
+        try {
+            const raw = fs.readFileSync(localStatePath, 'utf8');
+            const localState = JSON.parse(raw);
+            const infoCache = localState.profile?.info_cache ?? {};
+            return Object.entries(infoCache)
+                .map(([directory, info]) => ({
+                directory,
+                name: info?.name || directory,
+                email: info?.user_name || '',
+            }))
+                .sort((left, right) => left.directory.localeCompare(right.directory));
+        }
+        catch {
+            return [];
+        }
+    },
+};
 const createEmptyDomState = () => {
     const root = new DOMElementNode(true, null, 'html', '/html[1]', {}, []);
     return new DOMState(root, {});
@@ -77,11 +219,18 @@ export class BrowserSession {
     _maxRecentEvents = 100;
     _watchdogs = new Set();
     _defaultWatchdogsAttached = false;
+    _captchaWatchdog = null;
+    RECONNECT_WAIT_TIMEOUT = 54;
+    _reconnecting = false;
+    _reconnectTask = null;
+    _reconnectWaitPromise = Promise.resolve();
+    _resolveReconnectWait = null;
+    _intentionalStop = false;
+    _disconnectAwareBrowser = null;
+    _browserDisconnectHandler = null;
     constructor(init = {}) {
         const sourceProfileConfig = init.browser_profile
-            ? typeof structuredClone === 'function'
-                ? structuredClone(init.browser_profile.config)
-                : JSON.parse(JSON.stringify(init.browser_profile.config))
+            ? cloneBrowserProfileConfig(init.browser_profile)
             : (init.profile ?? {});
         this.browser_profile = new BrowserProfile(sourceProfileConfig);
         this.id = init.id ?? uuid7str();
@@ -121,12 +270,56 @@ export class BrowserSession {
         this._attachDialogHandler(this.agent_current_page);
         this._recordRecentEvent('session_initialized', { url: this.currentUrl });
     }
+    static from_system_chrome(init = {}) {
+        const executablePath = systemChrome.findExecutable();
+        if (!executablePath) {
+            throw new Error('Chrome not found. Please install Chrome or use BrowserSession with an explicit executable_path.\n' +
+                'Expected locations:\n' +
+                '  macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome\n' +
+                '  Linux: /usr/bin/google-chrome or /usr/bin/chromium\n' +
+                '  Windows: C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe');
+        }
+        const userDataDir = systemChrome.getUserDataDir(executablePath);
+        if (!userDataDir) {
+            throw new Error('Could not detect Chrome profile directory for your platform.\n' +
+                'Expected locations:\n' +
+                '  macOS: ~/Library/Application Support/Google/Chrome\n' +
+                '  Linux: ~/.config/google-chrome\n' +
+                '  Windows: %LocalAppData%\\Google\\Chrome\\User Data');
+        }
+        const availableProfiles = systemChrome.listProfiles(userDataDir);
+        const selectedProfileDirectory = init.profile_directory ?? availableProfiles[0]?.directory ?? 'Default';
+        if (typeof init.profile_directory === 'undefined' && availableProfiles[0]) {
+            createLogger('browser_use.browser.session').info(`Auto-selected Chrome profile: ${availableProfiles[0].name} (${availableProfiles[0].directory})`);
+        }
+        const sourceProfileConfig = init.browser_profile
+            ? cloneBrowserProfileConfig(init.browser_profile)
+            : (init.profile ?? {});
+        const { browser_profile: _browserProfile, profile: _profile, profile_directory: _profileDirectory, ...sessionInit } = init;
+        return new BrowserSession({
+            ...sessionInit,
+            browser_profile: new BrowserProfile({
+                ...sourceProfileConfig,
+                executable_path: executablePath,
+                user_data_dir: userDataDir,
+                profile_directory: selectedProfileDirectory,
+            }),
+        });
+    }
+    static list_chrome_profiles() {
+        const executablePath = systemChrome.findExecutable();
+        const userDataDir = systemChrome.getUserDataDir(executablePath);
+        return systemChrome.listProfiles(userDataDir);
+    }
     attach_watchdog(watchdog) {
         if (this._watchdogs.has(watchdog)) {
             return;
         }
         watchdog.attach_to_session();
         this._watchdogs.add(watchdog);
+        if (watchdog instanceof CaptchaWatchdog) {
+            this._captchaWatchdog = watchdog;
+        }
     }
     attach_watchdogs(watchdogs) {
         for (const watchdog of watchdogs) {
@@ -139,12 +332,16 @@ export class BrowserSession {
         }
         watchdog.detach_from_session();
         this._watchdogs.delete(watchdog);
+        if (watchdog === this._captchaWatchdog) {
+            this._captchaWatchdog = null;
+        }
     }
     detach_all_watchdogs() {
         for (const watchdog of [...this._watchdogs]) {
             this.detach_watchdog(watchdog);
         }
         this._defaultWatchdogsAttached = false;
+        this._captchaWatchdog = null;
     }
     get_watchdogs() {
         return [...this._watchdogs];
@@ -179,6 +376,10 @@ export class BrowserSession {
             new StorageStateWatchdog({ browser_session: this }),
             new DefaultActionWatchdog({ browser_session: this }),
         ];
+        if (this.browser_profile.config.captcha_solver) {
+            this._captchaWatchdog = new CaptchaWatchdog({ browser_session: this });
+            watchdogs.push(this._captchaWatchdog);
+        }
         const configuredHarPath = this.browser_profile.config.record_har_path;
         if (typeof configuredHarPath === 'string' &&
             configuredHarPath.trim().length > 0) {
@@ -187,6 +388,9 @@ export class BrowserSession {
         this.attach_watchdogs(watchdogs);
         this._defaultWatchdogsAttached = true;
     }
+    async wait_if_captcha_solving(timeoutSeconds) {
+        return (this._captchaWatchdog?.wait_if_captcha_solving(timeoutSeconds) ?? null);
+    }
     _formatTabId(pageId) {
         const normalized = Number.isFinite(pageId) && pageId >= 0 ? Math.floor(pageId) : 0;
         return String(normalized).padStart(4, '0').slice(-4);
@@ -400,6 +604,118 @@ export class BrowserSession {
         this._attachDialogHandler(page);
         this.agent_current_page = page ?? null;
     }
+    async _syncCurrentTabFromPage(page) {
+        if (!page) {
+            return;
+        }
+        let resolvedUrl = null;
+        try {
+            const rawUrl = page.url();
+            if (typeof rawUrl === 'string' && rawUrl.trim()) {
+                resolvedUrl = normalize_url(rawUrl);
+                this.currentUrl = resolvedUrl;
+            }
+        }
+        catch {
+            // Ignore transient URL read failures.
+        }
+        let resolvedTitle = null;
+        if (typeof page.title === 'function') {
+            try {
+                const title = await page.title();
+                if (typeof title === 'string' && title.trim()) {
+                    resolvedTitle = title;
+                }
+            }
+            catch {
+                // Ignore transient title read failures.
+            }
+        }
+        if (!resolvedTitle) {
+            resolvedTitle = resolvedUrl ?? this.currentTitle ?? this.currentUrl;
+        }
+        this.currentTitle = resolvedTitle;
+        const currentTab = this._tabs[this.currentTabIndex];
+        if (currentTab) {
+            if (resolvedUrl) {
+                currentTab.url = resolvedUrl;
+            }
+            currentTab.title = resolvedTitle;
+            this._syncSessionManagerFromTabs();
+        }
+    }
+    _syncTabsWithBrowserPages() {
+        const pages = this.browser_context?.pages?.() ?? [];
+        if (!pages.length) {
+            return;
+        }
+        const nextTabs = [];
+        const nextTabPages = new Map();
+        const usedPageIds = new Set();
+        const knownPageMappings = Array.from(this.tabPages.entries());
+        for (const page of pages) {
+            this._attachDialogHandler(page ?? null);
+            let pageId = null;
+            for (const [candidateId, candidatePage] of knownPageMappings) {
+                if (candidatePage === page && !usedPageIds.has(candidateId)) {
+                    pageId = candidateId;
+                    break;
+                }
+            }
+            if (pageId === null) {
+                pageId = this._tabCounter++;
+            }
+            usedPageIds.add(pageId);
+            const existingTab = this._tabs.find((tab) => tab.page_id === pageId);
+            const tab = existingTab
+                ? { ...existingTab }
+                : this._createTabInfo({
+                    page_id: pageId,
+                    url: 'about:blank',
+                    title: 'about:blank',
+                });
+            try {
+                const rawUrl = page.url();
+                if (typeof rawUrl === 'string' && rawUrl.trim()) {
+                    tab.url = normalize_url(rawUrl);
+                }
+            }
+            catch {
+                // Keep existing tab url when page url is not readable.
+            }
+            if (!existingTab || !tab.title || tab.title === 'about:blank') {
+                tab.title = tab.url;
+            }
+            nextTabs.push(tab);
+            nextTabPages.set(pageId, page);
+        }
+        if (!nextTabs.length) {
+            return;
+        }
+        this._tabs = nextTabs;
+        this.tabPages = nextTabPages;
+        const activePage = this.agent_current_page && pages.includes(this.agent_current_page)
+            ? this.agent_current_page
+            : (pages[0] ?? null);
+        if (activePage) {
+            const activeIndex = this._tabs.findIndex((tab) => this.tabPages.get(tab.page_id) === activePage);
+            if (activeIndex !== -1) {
+                this.currentTabIndex = activeIndex;
+            }
+        }
+        if (this.currentTabIndex < 0 || this.currentTabIndex >= this._tabs.length) {
+            this.currentTabIndex = Math.max(0, this._tabs.length - 1);
+        }
+        const activeTab = this._tabs[this.currentTabIndex] ?? null;
+        if (activeTab) {
+            this.currentUrl = activeTab.url;
+            this.currentTitle = activeTab.title || activeTab.url;
+            this.agent_current_page = this.tabPages.get(activeTab.page_id) ?? null;
+            this.human_current_page =
+                this.human_current_page ?? this.agent_current_page;
+        }
+        this._syncSessionManagerFromTabs();
+    }
     _captureClosedPopupMessage(dialogType, message) {
         const normalizedType = String(dialogType || 'alert').trim() || 'alert';
         const normalizedMessage = String(message || '').trim();
@@ -600,6 +916,65 @@ export class BrowserSession {
     get is_stopping() {
         return this._stoppingPromise !== null;
     }
+    get is_reconnecting() {
+        return this._reconnecting;
+    }
+    get should_gate_watchdog_events() {
+        return Boolean(this.initialized ||
+            this.browser ||
+            this.browser_context ||
+            this.cdp_url ||
+            this.wss_url ||
+            this._reconnecting);
+    }
+    get is_cdp_connected() {
+        try {
+            if (this.browser) {
+                const browser = this.browser;
+                if (typeof browser.isConnected === 'function' &&
+                    !browser.isConnected()) {
+                    return false;
+                }
+            }
+            if (this.browser_context) {
+                const contextBrowser = this.browser_context.browser?.();
+                if (contextBrowser &&
+                    typeof contextBrowser.isConnected === 'function' &&
+                    !contextBrowser.isConnected()) {
+                    return false;
+                }
+                return true;
+            }
+            return Boolean(this.browser);
+        }
+        catch {
+            return false;
+        }
+    }
+    async wait_for_reconnect(timeoutSeconds = this.RECONNECT_WAIT_TIMEOUT) {
+        if (!this._reconnecting) {
+            return;
+        }
+        const timeoutMs = Number.isFinite(timeoutSeconds) && timeoutSeconds > 0
+            ? timeoutSeconds * 1000
+            : this.RECONNECT_WAIT_TIMEOUT * 1000;
+        let timeoutHandle = null;
+        try {
+            await Promise.race([
+                this._reconnectWaitPromise,
+                new Promise((_, reject) => {
+                    timeoutHandle = setTimeout(() => {
+                        reject(new Error(`Reconnection wait timed out after ${Math.round(timeoutMs / 1000)}s`));
+                    }, timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+        }
+    }
     claim_agent(agentId, mode = 'exclusive') {
         if (!agentId) {
             return false;
@@ -785,11 +1160,276 @@ export class BrowserSession {
             if (convertedValue === undefined) {
                 continue;
             }
-            const normalizedKey = rawKey.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+            const normalizedKey = PLAYWRIGHT_OPTION_KEY_OVERRIDES[rawKey] ??
+                rawKey.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
             result[normalizedKey] = convertedValue;
         }
         return result;
     }
+    async set_extra_headers(headers) {
+        const normalizedHeaders = Object.fromEntries(Object.entries(headers)
+            .map(([key, value]) => [String(key).trim(), String(value)])
+            .filter(([key]) => key.length > 0));
+        if (!this.browser_context ||
+            Object.keys(normalizedHeaders).length === 0 ||
+            typeof this.browser_context.setExtraHTTPHeaders !== 'function') {
+            return;
+        }
+        await this.browser_context.setExtraHTTPHeaders(normalizedHeaders);
+    }
+    async _applyConfiguredExtraHttpHeaders() {
+        const configuredHeaders = this.browser_profile.config.extra_http_headers;
+        if (!configuredHeaders || Object.keys(configuredHeaders).length === 0) {
+            return;
+        }
+        await this.set_extra_headers(configuredHeaders);
+    }
+    _usesRemoteBrowserConnection() {
+        return Boolean(this.cdp_url || this.wss_url);
+    }
+    async _connectToConfiguredBrowser(playwright) {
+        const connectOptions = this._toPlaywrightOptions(this.browser_profile.kwargs_for_connect());
+        if (this.cdp_url) {
+            return await playwright.chromium.connectOverCDP(this.cdp_url, connectOptions ?? {});
+        }
+        if (this.wss_url) {
+            return await playwright.chromium.connect(this.wss_url, connectOptions ?? {});
+        }
+        throw new Error('Cannot connect to a remote browser without cdp_url or wss_url');
+    }
+    async _ensureBrowserContextFromBrowser(browser) {
+        const existingContexts = (typeof browser?.contexts === 'function' ? browser.contexts() : []) ?? [];
+        if (existingContexts.length > 0) {
+            return existingContexts[0] ?? null;
+        }
+        if (typeof browser?.newContext === 'function') {
+            const contextOptions = this._toPlaywrightOptions(this.browser_profile.kwargs_for_new_context());
+            return await browser.newContext(contextOptions ?? {});
+        }
+        return null;
+    }
+    _beginReconnectWait() {
+        this._reconnectWaitPromise = new Promise((resolve) => {
+            this._resolveReconnectWait = resolve;
+        });
+    }
+    _endReconnectWait() {
+        this._resolveReconnectWait?.();
+        this._resolveReconnectWait = null;
+        this._reconnectWaitPromise = Promise.resolve();
+    }
+    _detachRemoteDisconnectHandler() {
+        if (!this._disconnectAwareBrowser || !this._browserDisconnectHandler) {
+            this._disconnectAwareBrowser = null;
+            this._browserDisconnectHandler = null;
+            return;
+        }
+        if (typeof this._disconnectAwareBrowser.off === 'function') {
+            this._disconnectAwareBrowser.off('disconnected', this._browserDisconnectHandler);
+        }
+        else if (typeof this._disconnectAwareBrowser.removeListener === 'function') {
+            this._disconnectAwareBrowser.removeListener('disconnected', this._browserDisconnectHandler);
+        }
+        this._disconnectAwareBrowser = null;
+        this._browserDisconnectHandler = null;
+    }
+    _attachRemoteDisconnectHandler(browser) {
+        this._detachRemoteDisconnectHandler();
+        if (!this._usesRemoteBrowserConnection()) {
+            return;
+        }
+        const browserWithEvents = browser;
+        if (!browserWithEvents || typeof browserWithEvents.on !== 'function') {
+            return;
+        }
+        const onDisconnected = () => {
+            this._handleUnexpectedRemoteDisconnect();
+        };
+        browserWithEvents.on('disconnected', onDisconnected);
+        this._disconnectAwareBrowser = browserWithEvents;
+        this._browserDisconnectHandler = onDisconnected;
+    }
+    _handleUnexpectedRemoteDisconnect() {
+        if (this._intentionalStop ||
+            this._reconnecting ||
+            !this._usesRemoteBrowserConnection()) {
+            return;
+        }
+        this.logger.warning('Remote browser connection closed unexpectedly; attempting to reconnect');
+        this._recordRecentEvent('browser_disconnected', {
+            url: this.currentUrl,
+        });
+        const reconnectTask = this._auto_reconnect();
+        this._reconnectTask = reconnectTask;
+        void reconnectTask.finally(() => {
+            if (this._reconnectTask === reconnectTask) {
+                this._reconnectTask = null;
+            }
+        });
+    }
+    async _restorePagesAfterReconnect(preferredUrl, preferredTabIndex) {
+        if (!this.browser_context) {
+            this.agent_current_page = null;
+            this.human_current_page = null;
+            return;
+        }
+        let pages = this.browser_context.pages?.() ?? [];
+        if (!pages.length && typeof this.browser_context.newPage === 'function') {
+            const createdPage = await this.browser_context.newPage();
+            if (createdPage) {
+                pages = this.browser_context.pages?.() ?? [createdPage];
+            }
+        }
+        this.tabPages = new Map();
+        this.agent_current_page = null;
+        this.human_current_page = null;
+        this._syncTabsWithBrowserPages();
+        if (!pages.length) {
+            this.currentTabIndex = 0;
+            this.currentUrl = normalize_url(preferredUrl ?? 'about:blank');
+            this.currentTitle = this.currentUrl;
+            if (!this._tabs.length) {
+                this._tabs = [
+                    this._createTabInfo({
+                        page_id: this._tabCounter++,
+                        url: this.currentUrl,
+                        title: this.currentTitle,
+                    }),
+                ];
+            }
+            this._syncSessionManagerFromTabs();
+            return;
+        }
+        const normalizedPreferredUrl = typeof preferredUrl === 'string' && preferredUrl.trim().length > 0
+            ? normalize_url(preferredUrl)
+            : null;
+        const pageByUrl = normalizedPreferredUrl == null
+            ? null
+            : (pages.find((page) => {
+                try {
+                    return normalize_url(page.url()) === normalizedPreferredUrl;
+                }
+                catch {
+                    return false;
+                }
+            }) ?? null);
+        const clampedIndex = preferredTabIndex >= 0 && preferredTabIndex < pages.length
+            ? preferredTabIndex
+            : 0;
+        const nextPage = pageByUrl ?? pages[clampedIndex] ?? pages[0] ?? null;
+        const nextTabIndex = nextPage
+            ? this._tabs.findIndex((tab) => this.tabPages.get(tab.page_id) === nextPage)
+            : -1;
+        if (nextTabIndex >= 0) {
+            this.currentTabIndex = nextTabIndex;
+        }
+        this._setActivePage(nextPage);
+        this.human_current_page = nextPage;
+        await this._syncCurrentTabFromPage(nextPage);
+    }
+    async reconnect(options = {}) {
+        if (!this._usesRemoteBrowserConnection()) {
+            throw new Error('Cannot reconnect without a remote browser connection');
+        }
+        const preferredUrl = typeof options.preferred_url === 'string'
+            ? options.preferred_url
+            : this.currentUrl;
+        const preferredTabIndex = typeof options.preferred_tab_index === 'number'
+            ? options.preferred_tab_index
+            : this.currentTabIndex;
+        this._detachRemoteDisconnectHandler();
+        this.cachedBrowserState = null;
+        this.currentPageLoadingStatus = null;
+        this.browser = null;
+        this.browser_context = null;
+        this.agent_current_page = null;
+        this.human_current_page = null;
+        this._dialogHandlersAttached = new WeakSet();
+        this.session_manager.clear();
+        const playwright = this.playwright ?? (await async_playwright());
+        this.playwright = playwright;
+        this.browser = await this._connectToConfiguredBrowser(playwright);
+        this.ownsBrowserResources = false;
+        this.browser_context = await this._ensureBrowserContextFromBrowser(this.browser);
+        await this._applyConfiguredExtraHttpHeaders();
+        await this._restorePagesAfterReconnect(preferredUrl, preferredTabIndex);
+        this._attachRemoteDisconnectHandler(this.browser);
+        this.initialized = true;
+        this._recordRecentEvent('browser_reconnected', {
+            url: this.currentUrl,
+        });
+    }
+    async _auto_reconnect(maxAttempts = 3) {
+        if (this._reconnecting || !this._usesRemoteBrowserConnection()) {
+            return;
+        }
+        this._reconnecting = true;
+        this._beginReconnectWait();
+        const startTime = Date.now();
+        const preferredUrl = this.currentUrl;
+        const preferredTabIndex = this.currentTabIndex;
+        try {
+            await this.event_bus.dispatch(new BrowserStoppedEvent({
+                reason: 'connection_lost',
+            }));
+            for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+                if (this._intentionalStop) {
+                    return;
+                }
+                await this.event_bus.dispatch(new BrowserReconnectingEvent({
+                    cdp_url: this.cdp_url ?? this.wss_url ?? 'remote',
+                    attempt,
+                    max_attempts: maxAttempts,
+                }));
+                try {
+                    await Promise.race([
+                        this.reconnect({
+                            preferred_url: preferredUrl,
+                            preferred_tab_index: preferredTabIndex,
+                        }),
+                        new Promise((_, reject) => {
+                            setTimeout(() => {
+                                reject(new Error(`Reconnect attempt timed out after ${Math.round(REMOTE_RECONNECT_ATTEMPT_TIMEOUT_MS / 1000)}s`));
+                            }, REMOTE_RECONNECT_ATTEMPT_TIMEOUT_MS);
+                        }),
+                    ]);
+                    if (this._intentionalStop) {
+                        return;
+                    }
+                    await this.event_bus.dispatch(new BrowserConnectedEvent({
+                        cdp_url: this.cdp_url ?? this.wss_url ?? 'remote',
+                    }));
+                    await this.event_bus.dispatch(new BrowserReconnectedEvent({
+                        cdp_url: this.cdp_url ?? this.wss_url ?? 'remote',
+                        attempt,
+                        downtime_seconds: (Date.now() - startTime) / 1000,
+                    }));
+                    return;
+                }
+                catch (error) {
+                    this.logger.warning(`Reconnect attempt ${attempt}/${maxAttempts} failed: ${error.message}`);
+                    if (attempt >= maxAttempts) {
+                        break;
+                    }
+                    const delayMs = REMOTE_RECONNECT_DELAYS_MS[attempt - 1] ??
+                        REMOTE_RECONNECT_DELAYS_MS[REMOTE_RECONNECT_DELAYS_MS.length - 1];
+                    await new Promise((resolve) => setTimeout(resolve, delayMs));
+                }
+            }
+            await this.event_bus.dispatch(new BrowserErrorEvent({
+                error_type: 'ReconnectionFailed',
+                message: `Failed to reconnect after ${maxAttempts} attempts (${((Date.now() - startTime) / 1000).toFixed(1)}s)`,
+                details: {
+                    cdp_url: this.cdp_url ?? this.wss_url ?? 'remote',
+                    max_attempts: maxAttempts,
+                },
+            }));
+        }
+        finally {
+            this._reconnecting = false;
+            this._endReconnectWait();
+        }
+    }
     _isSandboxLaunchError(error) {
         const message = error instanceof Error ? error.message : String(error);
         return (/no usable sandbox/i.test(message) ||
@@ -846,6 +1486,7 @@ export class BrowserSession {
     }
     async start() {
         this.attach_default_watchdogs();
+        this._intentionalStop = false;
         if (this.initialized) {
             return this;
         }
@@ -878,12 +1519,11 @@ export class BrowserSession {
                 const playwright = this.playwright ?? (await async_playwright());
                 this.playwright = playwright;
                 if (this.cdp_url) {
-                    this.browser = await playwright.chromium.connectOverCDP(this.cdp_url);
+                    this.browser = await this._connectToConfiguredBrowser(playwright);
                     this.ownsBrowserResources = false;
                 }
                 else if (this.wss_url) {
-                    const connectOptions = this._toPlaywrightOptions(this.browser_profile.kwargs_for_connect());
-                    this.browser = await playwright.chromium.connect(this.wss_url, connectOptions ?? {});
+                    this.browser = await this._connectToConfiguredBrowser(playwright);
                     this.ownsBrowserResources = false;
                 }
                 else {
@@ -905,14 +1545,11 @@ export class BrowserSession {
             if (existingContexts.length > 0) {
                 this.browser_context = existingContexts[0] ?? null;
             }
-            else if (typeof this.browser?.newContext === 'function') {
-                const contextOptions = this._toPlaywrightOptions(this.browser_profile.kwargs_for_new_context());
-                this.browser_context = await this.browser.newContext(contextOptions ?? {});
-            }
             else {
-                this.browser_context = null;
+                this.browser_context = await this._ensureBrowserContextFromBrowser(this.browser);
             }
         }
+        await this._applyConfiguredExtraHttpHeaders();
         await ensurePage();
         if (!this.human_current_page ||
             this.human_current_page.isClosed?.()) {
@@ -938,6 +1575,7 @@ export class BrowserSession {
         this.initialized = true;
         this._recordRecentEvent('browser_started', { url: this.currentUrl });
         this.logger.debug(`Started ${this.describe()} with profile ${this.browser_profile.toString()}`);
+        this._attachRemoteDisconnectHandler(this.browser);
         await this.event_bus.dispatch(new BrowserConnectedEvent({
             cdp_url: this.cdp_url ?? this.wss_url ?? 'playwright',
         }));
@@ -964,7 +1602,7 @@ export class BrowserSession {
         // Connect to browser via CDP
         try {
             const playwright = await import('playwright');
-            const browser = await playwright.chromium.connectOverCDP(cdpUrl);
+            const browser = await this._connectToConfiguredBrowser(playwright);
             this.browser = browser;
             this.playwright = playwright;
             // Get or create context
@@ -975,6 +1613,7 @@ export class BrowserSession {
             else {
                 this.browser_context = (await browser.newContext());
             }
+            await this._applyConfiguredExtraHttpHeaders();
             // Get or create page
             if (!this.browser_context) {
                 throw new Error('Browser context not available');
@@ -991,6 +1630,7 @@ export class BrowserSession {
             }
             // We don't own this browser since we're connecting to existing one
             this.ownsBrowserResources = false;
+            this._attachRemoteDisconnectHandler(this.browser);
             this.initialized = true;
             this.logger.info(`Successfully connected to browser PID ${browserPid}`);
         }
@@ -1025,6 +1665,11 @@ export class BrowserSession {
     }
     async _shutdown_browser_session() {
         this.initialized = false;
+        this._intentionalStop = true;
+        this._reconnecting = false;
+        this._endReconnectWait();
+        this._reconnectTask = null;
+        this._detachRemoteDisconnectHandler();
         this.attachedAgentId = null;
         this.attachedSharedAgentIds.clear();
         const closeWithTimeout = async (label, operation, timeoutMs = 3000) => {
@@ -1101,7 +1746,7 @@ export class BrowserSession {
         else {
             try {
                 const domService = new DomService(page, this.logger);
-                domState = await this._withAbort(domService.get_clickable_elements(), signal);
+                domState = await this._withAbort(domService.get_clickable_elements(this.browser_profile.highlight_elements, -1, this.browser_profile.viewport_expansion), signal);
             }
             catch (error) {
                 if (this._isAbortError(error)) {
@@ -1110,6 +1755,29 @@ export class BrowserSession {
                 this.logger.debug(`Failed to build DOM tree: ${error.message}`);
                 domState = createEmptyDomState();
             }
+            const liveUrl = typeof page.url === 'function'
+                ? normalize_url(page.url())
+                : this.currentUrl;
+            const shouldRetryEmptyDom = Object.keys(domState.selector_map).length === 0 &&
+                !this._is_new_tab_page(liveUrl) &&
+                !liveUrl.toLowerCase().endsWith('.pdf');
+            if (shouldRetryEmptyDom) {
+                this.logger.debug(`Empty DOM detected for ${liveUrl}; retrying once`);
+                await this._waitWithAbort(EMPTY_DOM_RETRY_DELAY_MS, signal);
+                try {
+                    const retryDomService = new DomService(page, this.logger);
+                    const retriedDomState = await this._withAbort(retryDomService.get_clickable_elements(this.browser_profile.highlight_elements, -1, this.browser_profile.viewport_expansion), signal);
+                    if (Object.keys(retriedDomState.selector_map).length > 0) {
+                        domState = retriedDomState;
+                    }
+                }
+                catch (error) {
+                    if (this._isAbortError(error)) {
+                        throw error;
+                    }
+                    this.logger.debug(`Retry after empty DOM failed: ${error.message}`);
+                }
+            }
         }
         let screenshot = null;
         if (options.include_screenshot && page?.screenshot) {
@@ -1176,6 +1844,9 @@ export class BrowserSession {
             }
         }
         const pendingNetworkRequests = await this._getPendingNetworkRequests(page);
+        if (page) {
+            await this._syncCurrentTabFromPage(page);
+        }
         if (pageInfo &&
             Number.isFinite(pageInfo.viewport_width) &&
             Number.isFinite(pageInfo.viewport_height)) {
@@ -1225,6 +1896,7 @@ export class BrowserSession {
         return summary;
     }
     async get_current_page() {
+        this._syncTabsWithBrowserPages();
         if (this.agent_current_page) {
             return this.agent_current_page;
         }
@@ -1275,6 +1947,7 @@ export class BrowserSession {
         this._throwIfAborted(signal);
         this._assert_url_allowed(url);
         const normalized = normalize_url(url);
+        let completedUrl = normalized;
         const waitUntil = options.wait_until ?? 'domcontentloaded';
         const timeoutMs = typeof options.timeout_ms === 'number' &&
             Number.isFinite(options.timeout_ms)
@@ -1294,6 +1967,7 @@ export class BrowserSession {
                 await this._withAbort(page.goto(normalized, gotoOptions), signal);
                 const finalUrl = page.url();
                 this._assert_url_allowed(finalUrl);
+                completedUrl = normalize_url(finalUrl);
                 await this._waitForStableNetwork(page, signal);
             }
             catch (error) {
@@ -1309,16 +1983,24 @@ export class BrowserSession {
             }
         }
         this._throwIfAborted(signal);
-        this.currentUrl = normalized;
-        this.currentTitle = normalized;
-        this.historyStack.push(normalized);
-        if (this._tabs[this.currentTabIndex]) {
-            this._tabs[this.currentTabIndex].url = normalized;
-            this._tabs[this.currentTabIndex].title = normalized;
+        if (page) {
+            await this._syncCurrentTabFromPage(page);
+            completedUrl = this.currentUrl || completedUrl;
+        }
+        else {
+            this.currentUrl = normalized;
+            this.currentTitle = normalized;
+            if (this._tabs[this.currentTabIndex]) {
+                this._tabs[this.currentTabIndex].url = normalized;
+                this._tabs[this.currentTabIndex].title = normalized;
+            }
+            this._syncSessionManagerFromTabs();
+        }
+        if (this.historyStack[this.historyStack.length - 1] !== completedUrl) {
+            this.historyStack.push(completedUrl);
         }
-        this._syncSessionManagerFromTabs();
         this._setActivePage(page ?? null);
-        this._recordRecentEvent('navigation_completed', { url: normalized });
+        this._recordRecentEvent('navigation_completed', { url: completedUrl });
         this.cachedBrowserState = null;
         return this.agent_current_page;
     }
@@ -1327,11 +2009,14 @@ export class BrowserSession {
         this._throwIfAborted(signal);
         this._assert_url_allowed(url);
         const normalized = normalize_url(url);
+        let completedUrl = normalized;
         const waitUntil = options.wait_until ?? 'domcontentloaded';
         const timeoutMs = typeof options.timeout_ms === 'number' &&
             Number.isFinite(options.timeout_ms)
             ? Math.max(0, options.timeout_ms)
             : null;
+        const previousTabIndex = this.currentTabIndex;
+        const previousTab = this._tabs[this.currentTabIndex] ?? null;
         const newTab = this._createTabInfo({
             page_id: this._tabCounter++,
             url: normalized,
@@ -1342,11 +2027,6 @@ export class BrowserSession {
         this.currentUrl = normalized;
         this.currentTitle = normalized;
         this.historyStack.push(normalized);
-        this._recordRecentEvent('tab_created', {
-            url: normalized,
-            page_id: newTab.page_id,
-            tab_id: newTab.tab_id,
-        });
         let page = null;
         try {
             page =
@@ -1362,6 +2042,7 @@ export class BrowserSession {
                 await this._withAbort(page.goto(normalized, gotoOptions), signal);
                 const finalUrl = page.url();
                 this._assert_url_allowed(finalUrl);
+                completedUrl = normalize_url(finalUrl);
                 await this._waitForStableNetwork(page, signal);
             }
         }
@@ -1369,29 +2050,82 @@ export class BrowserSession {
             if (this._isAbortError(error)) {
                 throw error;
             }
+            const message = error.message ?? 'Failed to open new tab';
             this._recordRecentEvent('tab_navigation_failed', {
                 url: normalized,
                 page_id: newTab.page_id,
                 tab_id: newTab.tab_id,
-                error_message: error.message ?? 'Failed to open new tab',
+                error_message: message,
             });
-            this.logger.debug(`Failed to open new tab via Playwright: ${error.message}`);
+            this.logger.debug(`Failed to open new tab via Playwright: ${message}`);
+            if (page?.close) {
+                try {
+                    await page.close();
+                }
+                catch {
+                    // Ignore best-effort tab close failures during rollback.
+                }
+            }
+            this._tabs = this._tabs.filter((tab) => tab.page_id !== newTab.page_id);
+            this.tabPages.delete(newTab.page_id);
+            if (this.historyStack[this.historyStack.length - 1] === normalized) {
+                this.historyStack.pop();
+            }
+            if (this._tabs.length > 0) {
+                let restoredIndex = previousTab
+                    ? this._tabs.findIndex((tab) => tab.page_id === previousTab.page_id)
+                    : -1;
+                if (restoredIndex === -1) {
+                    restoredIndex = Math.min(previousTabIndex, this._tabs.length - 1);
+                }
+                this.currentTabIndex = Math.max(0, restoredIndex);
+                const restoredTab = this._tabs[this.currentTabIndex];
+                this.currentUrl = restoredTab.url;
+                this.currentTitle = restoredTab.title;
+                const restoredPage = this.tabPages.get(restoredTab.page_id) ?? null;
+                this._setActivePage(restoredPage);
+                await this._syncCurrentTabFromPage(restoredPage);
+            }
+            else {
+                this.currentTabIndex = 0;
+                this.currentUrl = 'about:blank';
+                this.currentTitle = 'about:blank';
+                this._setActivePage(null);
+            }
+            this._syncSessionManagerFromTabs();
+            this.cachedBrowserState = null;
+            throw new BrowserError(message);
         }
         this.tabPages.set(newTab.page_id, page);
         this._syncSessionManagerFromTabs();
         this._setActivePage(page);
+        if (page) {
+            await this._syncCurrentTabFromPage(page);
+            completedUrl = this.currentUrl || completedUrl;
+        }
+        if (this.historyStack[this.historyStack.length - 1] === normalized) {
+            this.historyStack[this.historyStack.length - 1] = completedUrl;
+        }
+        else if (this.historyStack[this.historyStack.length - 1] !== completedUrl) {
+            this.historyStack.push(completedUrl);
+        }
         this.currentPageLoadingStatus = null;
         if (!this.human_current_page) {
             this.human_current_page = page;
         }
+        this._recordRecentEvent('tab_created', {
+            url: completedUrl,
+            page_id: newTab.page_id,
+            tab_id: newTab.tab_id,
+        });
         this._recordRecentEvent('tab_ready', {
-            url: normalized,
+            url: completedUrl,
             page_id: newTab.page_id,
             tab_id: newTab.tab_id,
         });
         await this.event_bus.dispatch(new TabCreatedEvent({
             target_id: newTab.target_id ?? newTab.tab_id ?? 'unknown_target',
-            url: normalized,
+            url: completedUrl,
         }));
         this.cachedBrowserState = null;
         return this.agent_current_page;
@@ -1434,6 +2168,7 @@ export class BrowserSession {
     async switch_to_tab(identifier, options = {}) {
         const signal = options.signal ?? null;
         this._throwIfAborted(signal);
+        this._syncTabsWithBrowserPages();
         const index = this._resolveTabIndex(identifier);
         const tab = index >= 0 ? (this._tabs[index] ?? null) : null;
         if (!tab) {
@@ -1473,6 +2208,7 @@ export class BrowserSession {
         return page;
     }
     async close_tab(identifier) {
+        this._syncTabsWithBrowserPages();
         const index = this._resolveTabIndex(identifier);
         if (index < 0 || index >= this._tabs.length) {
             throw new Error(`Tab '${identifier}' does not exist`);
@@ -1887,31 +2623,34 @@ export class BrowserSession {
     async go_back(options = {}) {
         const signal = options.signal ?? null;
         this._throwIfAborted(signal);
-        if (this.historyStack.length <= 1) {
+        const page = await this._withAbort(this.get_current_page(), signal);
+        if (!page?.goBack) {
             return;
         }
-        const page = await this._withAbort(this.get_current_page(), signal);
-        if (page?.goBack) {
-            try {
-                await this._withAbort(page.goBack(), signal);
-            }
-            catch (error) {
-                if (this._isAbortError(error)) {
-                    throw error;
-                }
-                this.logger.debug(`Failed to navigate back: ${error.message}`);
+        const previousUrl = this.currentUrl;
+        try {
+            await this._withAbort(page.goBack(), signal);
+        }
+        catch (error) {
+            if (this._isAbortError(error)) {
+                throw error;
             }
+            this.logger.debug(`Failed to navigate back: ${error.message}`);
         }
         this._throwIfAborted(signal);
-        this.historyStack.pop();
-        const previous = this.historyStack[this.historyStack.length - 1];
-        this.currentUrl = previous;
-        this.currentTitle = previous;
-        if (this._tabs[this.currentTabIndex]) {
-            this._tabs[this.currentTabIndex].url = previous;
-            this._tabs[this.currentTabIndex].title = previous;
+        await this._syncCurrentTabFromPage(page);
+        const currentUrl = this.currentUrl;
+        if (currentUrl && currentUrl !== previousUrl) {
+            const existingIndex = this.historyStack.lastIndexOf(currentUrl);
+            if (existingIndex !== -1) {
+                this.historyStack = this.historyStack.slice(0, existingIndex + 1);
+            }
+            else if (this.historyStack[this.historyStack.length - 1] !== currentUrl) {
+                this.historyStack.push(currentUrl);
+            }
         }
-        this._recordRecentEvent('navigation_back', { url: previous });
+        this.cachedBrowserState = null;
+        this._recordRecentEvent('navigation_back', { url: currentUrl });
     }
     async get_dom_element_by_index(_index, options = {}) {
         const selectorMap = await this.get_selector_map(options);
@@ -2123,6 +2862,13 @@ export class BrowserSession {
             await performClick();
         }
         await this._waitForLoad(page, 5000, signal);
+        if (page) {
+            await this._syncCurrentTabFromPage(page);
+            if (this.historyStack[this.historyStack.length - 1] !== this.currentUrl) {
+                this.historyStack.push(this.currentUrl);
+            }
+        }
+        this.cachedBrowserState = null;
         return null;
     }
     async _waitForLoad(page, timeout = 5000, signal = null) {
@@ -2435,11 +3181,12 @@ export class BrowserSession {
     }
     // ==================== Screenshots ====================
     /**
-     * Take a screenshot of the current page
+     * Take a screenshot of the current page.
      * @param full_page Whether to capture the full scrollable page
+     * @param clip Optional clip region for partial screenshots
      * @returns Base64 encoded PNG screenshot
      */
-    async take_screenshot(full_page = false) {
+    async take_screenshot(full_page = false, clip = null) {
         const page = await this.get_current_page();
         if (!page) {
             throw new Error('No page available for screenshot');
@@ -2470,11 +3217,21 @@ export class BrowserSession {
             // Create CDP session for the screenshot
             cdp_session = await this.get_or_create_cdp_session(page);
             // Capture screenshot via CDP
-            const screenshot_response = await cdp_session.send('Page.captureScreenshot', {
-                captureBeyondViewport: false,
+            const screenshotParams = {
+                captureBeyondViewport: full_page,
                 fromSurface: true,
                 format: 'png',
-            });
+            };
+            if (clip) {
+                screenshotParams.clip = {
+                    x: clip.x,
+                    y: clip.y,
+                    width: clip.width,
+                    height: clip.height,
+                    scale: 1,
+                };
+            }
+            const screenshot_response = await cdp_session.send('Page.captureScreenshot', screenshotParams);
             const screenshot_b64 = screenshot_response.data;
             if (!screenshot_b64) {
                 throw new Error(`CDP returned empty screenshot data for page ${url}`);
@@ -2548,22 +3305,34 @@ export class BrowserSession {
         if (!this.browser_context) {
             return [];
         }
+        this._syncTabsWithBrowserPages();
         const tabs_info = [];
-        const pages = this.browser_context.pages();
-        for (let page_id = 0; page_id < pages.length; page_id++) {
-            const page = pages[page_id];
-            const tab_id = this._tabs.find((tab) => tab.page_id === page_id)?.tab_id ??
-                this._formatTabId(page_id);
-            this._attachDialogHandler(page ?? null);
+        for (const tab of this._tabs) {
+            const page_id = tab.page_id;
+            const page = this.tabPages.get(page_id) ?? null;
+            const tab_id = tab.tab_id || this._formatTabId(page_id);
+            if (!tab.tab_id) {
+                tab.tab_id = tab_id;
+            }
+            this._attachDialogHandler(page);
+            let currentUrl = tab.url;
+            if (page?.url) {
+                try {
+                    currentUrl = normalize_url(page.url());
+                }
+                catch {
+                    // Keep tab url fallback when page url is unavailable.
+                }
+            }
             // Skip chrome:// pages and new tab pages
-            const isNewTab = page.url() === 'about:blank' ||
-                page.url().startsWith('chrome://newtab');
-            if (isNewTab || page.url().startsWith('chrome://')) {
+            const isNewTab = currentUrl === 'about:blank' ||
+                currentUrl.startsWith('chrome://newtab');
+            if (isNewTab || currentUrl.startsWith('chrome://')) {
                 if (isNewTab) {
                     tabs_info.push({
                         page_id,
                         tab_id,
-                        url: page.url(),
+                        url: currentUrl,
                         title: 'ignore this tab and do not use it',
                     });
                 }
@@ -2571,28 +3340,31 @@ export class BrowserSession {
                     tabs_info.push({
                         page_id,
                         tab_id,
-                        url: page.url(),
-                        title: page.url(),
+                        url: currentUrl,
+                        title: currentUrl,
                     });
                 }
                 continue;
             }
             // Normal pages - try to get title with timeout
             try {
+                if (!page?.title) {
+                    throw new Error('page_title_unavailable');
+                }
                 const titlePromise = page.title();
                 const timeoutPromise = new Promise((_, reject) => {
                     setTimeout(() => reject(new Error('timeout')), 2000);
                 });
                 const title = await Promise.race([titlePromise, timeoutPromise]);
-                tabs_info.push({ page_id, tab_id, url: page.url(), title });
+                tabs_info.push({ page_id, tab_id, url: currentUrl, title });
             }
             catch (error) {
-                this.logger.debug(`⚠️ Failed to get tab info for tab #${page_id}: ${page.url()} (using fallback title)`);
+                this.logger.debug(`⚠️ Failed to get tab info for tab #${page_id}: ${currentUrl} (using fallback title)`);
                 if (isNewTab) {
                     tabs_info.push({
                         page_id,
                         tab_id,
-                        url: page.url(),
+                        url: currentUrl,
                         title: 'ignore this tab and do not use it',
                     });
                 }
@@ -2600,8 +3372,8 @@ export class BrowserSession {
                     tabs_info.push({
                         page_id,
                         tab_id,
-                        url: page.url(),
-                        title: page.url(), // Use URL as fallback title
+                        url: currentUrl,
+                        title: tab.title || currentUrl,
                     });
                 }
             }
@@ -2966,6 +3738,15 @@ export class BrowserSession {
         }
         return [host, `www.${host}`];
     }
+    _setEntryMatchesUrl(domains, hostVariant, hostAlt, protocol) {
+        const matchedHost = domains.has(hostVariant) || domains.has(hostAlt);
+        if (!matchedHost) {
+            return false;
+        }
+        // Set-optimized entries are exact hostnames without explicit schemes,
+        // so keep parity with pattern matching default: https-only.
+        return protocol.toLowerCase() === 'https:';
+    }
     /**
      * Check if page is displaying a PDF
      */
@@ -3258,7 +4039,7 @@ export class BrowserSession {
             ((Array.isArray(allowedDomains) && allowedDomains.length > 0) ||
                 (allowedDomains instanceof Set && allowedDomains.size > 0))) {
             if (allowedDomains instanceof Set) {
-                if (allowedDomains.has(hostVariant) || allowedDomains.has(hostAlt)) {
+                if (this._setEntryMatchesUrl(allowedDomains, hostVariant, hostAlt, parsed.protocol)) {
                     return null;
                 }
             }
@@ -3281,8 +4062,7 @@ export class BrowserSession {
             ((Array.isArray(prohibitedDomains) && prohibitedDomains.length > 0) ||
                 (prohibitedDomains instanceof Set && prohibitedDomains.size > 0))) {
             if (prohibitedDomains instanceof Set) {
-                if (prohibitedDomains.has(hostVariant) ||
-                    prohibitedDomains.has(hostAlt)) {
+                if (this._setEntryMatchesUrl(prohibitedDomains, hostVariant, hostAlt, parsed.protocol)) {
                     return 'in_prohibited_domains';
                 }
             }
@@ -3405,57 +4185,31 @@ export class BrowserSession {
         // Check if downloads are enabled
         const downloads_path = this.browser_profile.downloads_path;
         if (downloads_path) {
+            fs.mkdirSync(downloads_path, { recursive: true });
+            // Try to detect file download.
+            const download_promise = page.waitForEvent('download', {
+                timeout: 5000,
+            });
+            // Click failures should bubble to the caller.
             try {
-                // Try to detect file download
-                const download_promise = page.waitForEvent('download', {
-                    timeout: 5000,
-                });
-                // Perform the click
                 await element_handle.click();
-                // Wait for download or timeout
-                const download = await download_promise;
-                // Save the downloaded file
-                const suggested_filename = download.suggestedFilename();
-                const unique_filename = await BrowserSession.get_unique_filename(downloads_path, suggested_filename);
-                const download_path = path.join(downloads_path, unique_filename);
-                const download_guid = uuid7str();
-                const download_url = typeof download.url === 'function'
-                    ? download.url()
-                    : (this.currentUrl ?? '');
-                await this.event_bus.dispatch(new DownloadStartedEvent({
-                    guid: download_guid,
-                    url: download_url,
-                    suggested_filename,
-                    auto_download: false,
-                }));
-                await download.saveAs(download_path);
-                this.logger.info(`⬇️ Downloaded file to: ${download_path}`);
-                const stats = fs.existsSync(download_path)
-                    ? fs.statSync(download_path)
-                    : null;
-                await this.event_bus.dispatch(new DownloadProgressEvent({
-                    guid: download_guid,
-                    received_bytes: stats?.size ?? 0,
-                    total_bytes: stats?.size ?? 0,
-                    state: 'completed',
-                }));
-                const fileDownloadedResult = await this.event_bus.dispatch(new FileDownloadedEvent({
-                    guid: download_guid,
-                    url: download_url,
-                    path: download_path,
-                    file_name: unique_filename,
-                    file_size: stats?.size ?? 0,
-                    file_type: path.extname(unique_filename).replace('.', '') || null,
-                    mime_type: null,
-                    auto_download: false,
-                }));
-                if (fileDownloadedResult.handler_results.length === 0) {
-                    this.add_downloaded_file(download_path);
-                }
-                return download_path;
             }
             catch (error) {
-                // No download triggered, treat as normal click
+                void download_promise.catch(() => undefined);
+                throw error;
+            }
+            let download;
+            try {
+                download = await download_promise;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const isDownloadTimeout = error instanceof Error &&
+                    (error.name === 'TimeoutError' ||
+                        message.toLowerCase().includes('timeout'));
+                if (!isDownloadTimeout) {
+                    throw error;
+                }
                 this.logger.debug('No download triggered within timeout. Checking navigation...');
                 try {
                     await page.waitForLoadState();
@@ -3463,7 +4217,47 @@ export class BrowserSession {
                 catch (e) {
                     this.logger.warning(`Navigation check failed: ${e.message}`);
                 }
+                return null;
             }
+            // Save the downloaded file.
+            const suggested_filename = download.suggestedFilename();
+            const unique_filename = await BrowserSession.get_unique_filename(downloads_path, suggested_filename);
+            const download_path = path.join(downloads_path, unique_filename);
+            const download_guid = uuid7str();
+            const download_url = typeof download.url === 'function'
+                ? download.url()
+                : (this.currentUrl ?? '');
+            await this.event_bus.dispatch(new DownloadStartedEvent({
+                guid: download_guid,
+                url: download_url,
+                suggested_filename,
+                auto_download: false,
+            }));
+            await download.saveAs(download_path);
+            this.logger.info(`⬇️ Downloaded file to: ${download_path}`);
+            const stats = fs.existsSync(download_path)
+                ? fs.statSync(download_path)
+                : null;
+            await this.event_bus.dispatch(new DownloadProgressEvent({
+                guid: download_guid,
+                received_bytes: stats?.size ?? 0,
+                total_bytes: stats?.size ?? 0,
+                state: 'completed',
+            }));
+            const fileDownloadedResult = await this.event_bus.dispatch(new FileDownloadedEvent({
+                guid: download_guid,
+                url: download_url,
+                path: download_path,
+                file_name: unique_filename,
+                file_size: stats?.size ?? 0,
+                file_type: path.extname(unique_filename).replace('.', '') || null,
+                mime_type: null,
+                auto_download: false,
+            }));
+            if (fileDownloadedResult.handler_results.length === 0) {
+                this.add_downloaded_file(download_path);
+            }
+            return download_path;
         }
         else {
             // No downloads path configured, just click
@@ -3481,15 +4275,33 @@ export class BrowserSession {
         }
         try {
             await page.evaluate(() => {
-                // Remove all elements with browser-use highlight class
+                const pageWindow = window;
+                const cleanupFunctions = Array.isArray(pageWindow._highlightCleanupFunctions)
+                    ? pageWindow._highlightCleanupFunctions
+                    : [];
+                for (const cleanupFn of cleanupFunctions) {
+                    try {
+                        if (typeof cleanupFn === 'function') {
+                            cleanupFn();
+                        }
+                    }
+                    catch {
+                        // Ignore callback cleanup failures.
+                    }
+                }
+                pageWindow._highlightCleanupFunctions = [];
+                const containers = document.querySelectorAll('#playwright-highlight-container');
+                containers.forEach((element) => element.remove());
+                const labels = document.querySelectorAll('.playwright-highlight-label');
+                labels.forEach((element) => element.remove());
+                // Backward compatibility with legacy selectors.
                 const highlights = document.querySelectorAll('.browser-use-highlight');
-                highlights.forEach((el) => el.remove());
-                // Remove inline highlight styles
+                highlights.forEach((element) => element.remove());
                 const styled = document.querySelectorAll('[style*="browser-use"]');
-                styled.forEach((el) => {
-                    if (el.style) {
-                        el.style.outline = '';
-                        el.style.border = '';
+                styled.forEach((element) => {
+                    if (element.style) {
+                        element.style.outline = '';
+                        element.style.border = '';
                     }
                 });
             });