browser-use 0.5.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);
@@ -492,7 +696,7 @@ export class BrowserSession {
         this.tabPages = nextTabPages;
         const activePage = this.agent_current_page && pages.includes(this.agent_current_page)
             ? this.agent_current_page
-            : pages[0] ?? null;
+            : (pages[0] ?? null);
         if (activePage) {
             const activeIndex = this._tabs.findIndex((tab) => this.tabPages.get(tab.page_id) === activePage);
             if (activeIndex !== -1) {
@@ -507,7 +711,8 @@ export class BrowserSession {
             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.human_current_page =
+                this.human_current_page ?? this.agent_current_page;
         }
         this._syncSessionManagerFromTabs();
     }
@@ -711,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;
@@ -896,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) ||
@@ -957,6 +1486,7 @@ export class BrowserSession {
     }
     async start() {
         this.attach_default_watchdogs();
+        this._intentionalStop = false;
         if (this.initialized) {
             return this;
         }
@@ -989,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 {
@@ -1016,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?.()) {
@@ -1049,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',
         }));
@@ -1075,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
@@ -1086,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');
@@ -1102,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}`);
         }
@@ -1136,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) => {
@@ -1221,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) {
@@ -2624,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');
@@ -2659,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', {
+            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}`);
@@ -2757,7 +3325,8 @@ export class BrowserSession {
                 }
             }
             // Skip chrome:// pages and new tab pages
-            const isNewTab = currentUrl === 'about:blank' || currentUrl.startsWith('chrome://newtab');
+            const isNewTab = currentUrl === 'about:blank' ||
+                currentUrl.startsWith('chrome://newtab');
             if (isNewTab || currentUrl.startsWith('chrome://')) {
                 if (isNewTab) {
                     tabs_info.push({
@@ -3636,7 +4205,8 @@ export class BrowserSession {
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 const isDownloadTimeout = error instanceof Error &&
-                    (error.name === 'TimeoutError' || message.toLowerCase().includes('timeout'));
+                    (error.name === 'TimeoutError' ||
+                        message.toLowerCase().includes('timeout'));
                 if (!isDownloadTimeout) {
                     throw error;
                 }
@@ -3654,7 +4224,9 @@ export class BrowserSession {
             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 ?? '');
+            const download_url = typeof download.url === 'function'
+                ? download.url()
+                : (this.currentUrl ?? '');
             await this.event_bus.dispatch(new DownloadStartedEvent({
                 guid: download_guid,
                 url: download_url,