browser-use 0.2.0 → 0.4.0

package/dist/browser/session.js

@@ -1,18 +1,36 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { exec } from 'node:child_process';
+import { isIP } from 'node:net';
+import { execFile } 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';
+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 } from './views.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 { 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';
-const execAsync = promisify(exec);
+import { SessionManager } from './session-manager.js';
+import { AboutBlankWatchdog } from './watchdogs/aboutblank-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';
+import { DOMWatchdog } from './watchdogs/dom-watchdog.js';
+import { DownloadsWatchdog } from './watchdogs/downloads-watchdog.js';
+import { HarRecordingWatchdog } from './watchdogs/har-recording-watchdog.js';
+import { LocalBrowserWatchdog } from './watchdogs/local-browser-watchdog.js';
+import { PermissionsWatchdog } from './watchdogs/permissions-watchdog.js';
+import { PopupsWatchdog } from './watchdogs/popups-watchdog.js';
+import { RecordingWatchdog } from './watchdogs/recording-watchdog.js';
+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 createEmptyDomState = () => {
     const root = new DOMElementNode(true, null, 'html', '/html[1]', {}, []);
     return new DOMState(root, {});
@@ -20,6 +38,8 @@ const createEmptyDomState = () => {
 export class BrowserSession {
     id;
     browser_profile;
+    event_bus;
+    session_manager;
     browser;
     browser_context;
     agent_current_page;
@@ -39,6 +59,8 @@ export class BrowserSession {
     currentTabIndex = 0;
     historyStack = [];
     downloaded_files = [];
+    llm_screenshot_size = null;
+    _original_viewport_size = null;
     ownsBrowserResources = true;
     _autoDownloadPdfs = true;
     tabPages = new Map();
@@ -48,6 +70,13 @@ export class BrowserSession {
     attachedAgentId = null;
     attachedSharedAgentIds = new Set();
     _stoppingPromise = null;
+    _closedPopupMessages = [];
+    _dialogHandlersAttached = new WeakSet();
+    _maxClosedPopupMessages = 20;
+    _recentEvents = [];
+    _maxRecentEvents = 100;
+    _watchdogs = new Set();
+    _defaultWatchdogsAttached = false;
     constructor(init = {}) {
         const sourceProfileConfig = init.browser_profile
             ? typeof structuredClone === 'function'
@@ -56,6 +85,8 @@ export class BrowserSession {
             : (init.profile ?? {});
         this.browser_profile = new BrowserProfile(sourceProfileConfig);
         this.id = init.id ?? uuid7str();
+        this.event_bus = new EventBus(`BrowserSession_${this.id.slice(-4)}`);
+        this.session_manager = new SessionManager();
         this.browser = init.browser ?? null;
         this.browser_context = init.browser_context ?? null;
         this.agent_current_page = init.page ?? null;
@@ -69,20 +100,122 @@ export class BrowserSession {
         this.downloaded_files = Array.isArray(init.downloaded_files)
             ? [...init.downloaded_files]
             : [];
+        this._closedPopupMessages = Array.isArray(init.closed_popup_messages)
+            ? [...init.closed_popup_messages]
+            : [];
         if (typeof init?.auto_download_pdfs === 'boolean') {
             this._autoDownloadPdfs = Boolean(init.auto_download_pdfs);
         }
+        const initialPageId = this._tabCounter++;
         this._tabs = [
-            {
-                page_id: this._tabCounter++,
+            this._createTabInfo({
+                page_id: initialPageId,
                 url: this.currentUrl,
                 title: this.currentTitle || this.currentUrl,
-                parent_page_id: null,
-            },
+            }),
         ];
         this.historyStack.push(this.currentUrl);
         this.ownsBrowserResources = this._determineOwnership();
         this.tabPages.set(this._tabs[0].page_id, this.agent_current_page ?? null);
+        this._syncSessionManagerFromTabs();
+        this._attachDialogHandler(this.agent_current_page);
+        this._recordRecentEvent('session_initialized', { url: this.currentUrl });
+    }
+    attach_watchdog(watchdog) {
+        if (this._watchdogs.has(watchdog)) {
+            return;
+        }
+        watchdog.attach_to_session();
+        this._watchdogs.add(watchdog);
+    }
+    attach_watchdogs(watchdogs) {
+        for (const watchdog of watchdogs) {
+            this.attach_watchdog(watchdog);
+        }
+    }
+    detach_watchdog(watchdog) {
+        if (!this._watchdogs.has(watchdog)) {
+            return;
+        }
+        watchdog.detach_from_session();
+        this._watchdogs.delete(watchdog);
+    }
+    detach_all_watchdogs() {
+        for (const watchdog of [...this._watchdogs]) {
+            this.detach_watchdog(watchdog);
+        }
+        this._defaultWatchdogsAttached = false;
+    }
+    get_watchdogs() {
+        return [...this._watchdogs];
+    }
+    async dispatch_browser_event(event, options = {}) {
+        return this.event_bus.dispatch_or_throw(event, options);
+    }
+    async launch() {
+        this.attach_default_watchdogs();
+        const dispatchResult = await this.dispatch_browser_event(new BrowserLaunchEvent());
+        const eventResult = dispatchResult.event.event_result;
+        return {
+            cdp_url: eventResult?.cdp_url ?? this.cdp_url ?? this.wss_url ?? 'playwright',
+        };
+    }
+    attach_default_watchdogs() {
+        if (this._defaultWatchdogsAttached) {
+            return;
+        }
+        const watchdogs = [
+            new LocalBrowserWatchdog({ browser_session: this }),
+            new CDPSessionWatchdog({ browser_session: this }),
+            new CrashWatchdog({ browser_session: this }),
+            new AboutBlankWatchdog({ browser_session: this }),
+            new PermissionsWatchdog({ browser_session: this }),
+            new PopupsWatchdog({ browser_session: this }),
+            new SecurityWatchdog({ browser_session: this }),
+            new DOMWatchdog({ browser_session: this }),
+            new ScreenshotWatchdog({ browser_session: this }),
+            new RecordingWatchdog({ browser_session: this }),
+            new DownloadsWatchdog({ browser_session: this }),
+            new StorageStateWatchdog({ browser_session: this }),
+            new DefaultActionWatchdog({ browser_session: this }),
+        ];
+        const configuredHarPath = this.browser_profile.config.record_har_path;
+        if (typeof configuredHarPath === 'string' &&
+            configuredHarPath.trim().length > 0) {
+            watchdogs.push(new HarRecordingWatchdog({ browser_session: this }));
+        }
+        this.attach_watchdogs(watchdogs);
+        this._defaultWatchdogsAttached = true;
+    }
+    _formatTabId(pageId) {
+        const normalized = Number.isFinite(pageId) && pageId >= 0 ? Math.floor(pageId) : 0;
+        return String(normalized).padStart(4, '0').slice(-4);
+    }
+    _createTabInfo({ page_id, url, title, parent_page_id = null, }) {
+        return {
+            page_id,
+            tab_id: this._formatTabId(page_id),
+            target_id: this._buildSyntheticTargetId(page_id),
+            url,
+            title,
+            parent_page_id,
+        };
+    }
+    _buildSyntheticTargetId(pageId) {
+        return `tab_${this.id.slice(-4)}_${this._formatTabId(pageId)}`;
+    }
+    _syncSessionManagerFromTabs() {
+        this.session_manager.sync_tabs(this._tabs, this.currentTabIndex, (page_id) => this._buildSyntheticTargetId(page_id));
+    }
+    async get_or_create_cdp_session(page = null) {
+        if (!this.browser_context?.newCDPSession) {
+            throw new Error('CDP sessions are not available for this browser context');
+        }
+        const targetPage = page ?? (await this.get_current_page());
+        if (!targetPage) {
+            throw new Error('No active page available to create CDP session');
+        }
+        return this.browser_context.newCDPSession(targetPage);
     }
     async _waitForStableNetwork(page, signal = null) {
         const pendingRequests = new Set();
@@ -262,9 +395,193 @@ export class BrowserSession {
         const currentTab = this._tabs[this.currentTabIndex];
         if (currentTab) {
             this.tabPages.set(currentTab.page_id, page ?? null);
+            this.session_manager.set_focused_target(currentTab.target_id ?? null);
         }
+        this._attachDialogHandler(page);
         this.agent_current_page = page ?? null;
     }
+    _captureClosedPopupMessage(dialogType, message) {
+        const normalizedType = String(dialogType || 'alert').trim() || 'alert';
+        const normalizedMessage = String(message || '').trim();
+        if (!normalizedMessage) {
+            return;
+        }
+        const formatted = `[${normalizedType}] ${normalizedMessage}`;
+        this._closedPopupMessages.push(formatted);
+        if (this._closedPopupMessages.length > this._maxClosedPopupMessages) {
+            this._closedPopupMessages.splice(0, this._closedPopupMessages.length - this._maxClosedPopupMessages);
+        }
+    }
+    _getClosedPopupMessagesSnapshot() {
+        return [...this._closedPopupMessages];
+    }
+    _recordRecentEvent(event_type, details = {}) {
+        const event = {
+            event_type: String(event_type || 'unknown').trim() || 'unknown',
+            timestamp: new Date().toISOString(),
+        };
+        if (typeof details.url === 'string' && details.url.trim()) {
+            event.url = details.url.trim();
+        }
+        if (typeof details.error_message === 'string' &&
+            details.error_message.trim()) {
+            event.error_message = details.error_message.trim();
+        }
+        if (typeof details.page_id === 'number' &&
+            Number.isFinite(details.page_id)) {
+            event.page_id = details.page_id;
+        }
+        if (typeof details.tab_id === 'string' && details.tab_id.trim()) {
+            event.tab_id = details.tab_id.trim();
+        }
+        this._recentEvents.push(event);
+        if (this._recentEvents.length > this._maxRecentEvents) {
+            this._recentEvents.splice(0, this._recentEvents.length - this._maxRecentEvents);
+        }
+    }
+    _getRecentEventsSummary(limit = 10) {
+        if (!this._recentEvents.length || limit <= 0) {
+            return null;
+        }
+        const events = this._recentEvents.slice(-limit);
+        return JSON.stringify(events);
+    }
+    _attachDialogHandler(page) {
+        if (!page || this._dialogHandlersAttached.has(page)) {
+            return;
+        }
+        const pageWithEvents = page;
+        if (typeof pageWithEvents.on !== 'function') {
+            return;
+        }
+        const handler = async (dialog) => {
+            try {
+                const dialogType = typeof dialog?.type === 'function' ? dialog.type() : 'alert';
+                const message = typeof dialog?.message === 'function' ? dialog.message() : '';
+                try {
+                    await this.event_bus.dispatch(new DialogOpenedEvent({
+                        dialog_type: dialogType,
+                        message: String(message ?? ''),
+                        url: this.currentUrl ?? 'about:blank',
+                        frame_id: null,
+                    }));
+                }
+                catch (error) {
+                    this.logger.debug(`Failed to dispatch DialogOpenedEvent: ${error.message}`);
+                }
+                this._captureClosedPopupMessage(dialogType, message);
+                this._recordRecentEvent('javascript_dialog_closed', {
+                    url: this.currentUrl,
+                    error_message: message
+                        ? `[${dialogType}] ${String(message).trim()}`
+                        : `[${dialogType}]`,
+                });
+                const shouldAccept = dialogType === 'alert' ||
+                    dialogType === 'confirm' ||
+                    dialogType === 'beforeunload';
+                if (shouldAccept && typeof dialog?.accept === 'function') {
+                    await dialog.accept();
+                }
+                else if (typeof dialog?.dismiss === 'function') {
+                    await dialog.dismiss();
+                }
+            }
+            catch (error) {
+                this.logger.debug(`Failed to auto-handle JavaScript dialog: ${error.message}`);
+            }
+        };
+        pageWithEvents.on('dialog', handler);
+        this._dialogHandlersAttached.add(page);
+    }
+    async _getPendingNetworkRequests(page) {
+        if (!page || typeof page.evaluate !== 'function') {
+            return [];
+        }
+        try {
+            const pending = await page.evaluate(() => {
+                const perf = window.performance;
+                if (!perf?.getEntriesByType) {
+                    return [];
+                }
+                const entries = perf.getEntriesByType('resource');
+                const now = perf.now?.() ?? Date.now();
+                const blockedPatterns = [
+                    'doubleclick',
+                    'analytics',
+                    'tracking',
+                    'metrics',
+                    'telemetry',
+                    'facebook.net',
+                    'hotjar',
+                    'clarity',
+                    'mixpanel',
+                    'segment',
+                    '/beacon/',
+                    '/collector/',
+                    '/telemetry/',
+                ];
+                const pendingRequests = [];
+                for (const entry of entries) {
+                    const responseEnd = typeof entry.responseEnd === 'number'
+                        ? entry.responseEnd
+                        : 0;
+                    if (responseEnd !== 0) {
+                        continue;
+                    }
+                    const url = String(entry.name ?? '');
+                    if (!url || url.startsWith('data:') || url.length > 500) {
+                        continue;
+                    }
+                    const lower = url.toLowerCase();
+                    if (blockedPatterns.some((pattern) => lower.includes(pattern))) {
+                        continue;
+                    }
+                    const startTime = typeof entry.startTime === 'number'
+                        ? entry.startTime
+                        : now;
+                    const loadingDuration = Math.max(0, now - startTime);
+                    if (loadingDuration > 10000) {
+                        continue;
+                    }
+                    const resourceType = String(entry.initiatorType ?? '').toLowerCase();
+                    if ((resourceType === 'img' ||
+                        resourceType === 'image' ||
+                        resourceType === 'font') &&
+                        loadingDuration > 3000) {
+                        continue;
+                    }
+                    pendingRequests.push({
+                        url,
+                        method: 'GET',
+                        loading_duration_ms: Math.round(loadingDuration),
+                        resource_type: resourceType || null,
+                    });
+                    if (pendingRequests.length >= 20) {
+                        break;
+                    }
+                }
+                return pendingRequests;
+            });
+            return Array.isArray(pending)
+                ? pending.map((entry) => ({
+                    url: String(entry.url ?? ''),
+                    method: typeof entry.method === 'string'
+                        ? entry.method
+                        : 'GET',
+                    loading_duration_ms: typeof entry.loading_duration_ms === 'number'
+                        ? entry.loading_duration_ms
+                        : 0,
+                    resource_type: typeof entry.resource_type === 'string'
+                        ? entry.resource_type
+                        : null,
+                }))
+                : [];
+        }
+        catch (error) {
+            this.logger.debug(`Failed to gather pending network requests: ${error.message}`);
+            return [];
+        }
+    }
     get tabs() {
         return this._tabs.slice();
     }
@@ -280,6 +597,9 @@ export class BrowserSession {
     get _owns_browser_resources() {
         return this.ownsBrowserResources;
     }
+    get is_stopping() {
+        return this._stoppingPromise !== null;
+    }
     claim_agent(agentId, mode = 'exclusive') {
         if (!agentId) {
             return false;
@@ -363,7 +683,11 @@ export class BrowserSession {
         return this.get_attached_agent_ids();
     }
     _determineOwnership() {
-        if (this.cdp_url || this.wss_url || this.browser || this.browser_context) {
+        if (this.cdp_url ||
+            this.wss_url ||
+            this.browser ||
+            this.browser_context ||
+            this.browser_pid) {
             return false;
         }
         return true;
@@ -521,9 +845,13 @@ export class BrowserSession {
         return this._logger;
     }
     async start() {
+        this.attach_default_watchdogs();
         if (this.initialized) {
             return this;
         }
+        await this.event_bus.dispatch(new BrowserStartEvent({
+            cdp_url: this.cdp_url,
+        }));
         const ensurePage = async () => {
             const current = this.agent_current_page;
             if (current && !current.isClosed?.()) {
@@ -608,7 +936,11 @@ 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()}`);
+        await this.event_bus.dispatch(new BrowserConnectedEvent({
+            cdp_url: this.cdp_url ?? this.wss_url ?? 'playwright',
+        }));
         return this;
     }
     /**
@@ -663,7 +995,7 @@ export class BrowserSession {
             this.logger.info(`Successfully connected to browser PID ${browserPid}`);
         }
         catch (error) {
-            throw new Error(`Failed to connect to browser PID ${browserPid}: ${error.message}`);
+            throw new Error(`Failed to connect to browser PID ${browserPid}: ${error.message}`, { cause: error });
         }
     }
     /**
@@ -743,13 +1075,18 @@ export class BrowserSession {
         this.playwright = null;
         this.cachedBrowserState = null;
         this._tabs = [];
+        this.session_manager.clear();
         this.downloaded_files = [];
+        this._closedPopupMessages = [];
+        this._dialogHandlersAttached = new WeakSet();
+        this._recentEvents = [];
     }
     async close() {
         await this.stop();
     }
     async get_browser_state_with_recovery(options = {}) {
         const signal = options.signal ?? null;
+        const includeRecentEvents = options.include_recent_events ?? false;
         this._throwIfAborted(signal);
         if (!this.initialized) {
             await this._withAbort(this.start(), signal);
@@ -796,8 +1133,6 @@ export class BrowserSession {
         let pageInfo = null;
         let pixelsAbove = 0;
         let pixelsBelow = 0;
-        let pixelsLeft = 0;
-        let pixelsRight = 0;
         if (page) {
             try {
                 const metrics = await this._withAbort(page.evaluate(() => {
@@ -818,8 +1153,8 @@ export class BrowserSession {
                 const viewportHeight = metrics.viewportHeight ?? 0;
                 const viewportWidth = metrics.viewportWidth ?? 0;
                 pixelsBelow = Math.max((metrics.pageHeight ?? 0) - (metrics.scrollY + viewportHeight), 0);
-                pixelsLeft = Math.max(metrics.scrollX ?? 0, 0);
-                pixelsRight = Math.max((metrics.pageWidth ?? 0) - (metrics.scrollX + viewportWidth), 0);
+                const pixelsLeft = Math.max(metrics.scrollX ?? 0, 0);
+                const pixelsRight = Math.max((metrics.pageWidth ?? 0) - (metrics.scrollX + viewportWidth), 0);
                 pageInfo = {
                     viewport_width: viewportWidth,
                     viewport_height: viewportHeight,
@@ -840,6 +1175,16 @@ export class BrowserSession {
                 this.logger.debug(`Failed to compute page metrics: ${error.message}`);
             }
         }
+        const pendingNetworkRequests = await this._getPendingNetworkRequests(page);
+        if (pageInfo &&
+            Number.isFinite(pageInfo.viewport_width) &&
+            Number.isFinite(pageInfo.viewport_height)) {
+            this._original_viewport_size = [
+                Math.floor(pageInfo.viewport_width),
+                Math.floor(pageInfo.viewport_height),
+            ];
+        }
+        const paginationButtons = DomService.detect_pagination_buttons(domState.selector_map);
         const summary = new BrowserStateSummary(domState, {
             url: this.currentUrl,
             title: this.currentTitle || this.currentUrl,
@@ -853,6 +1198,12 @@ export class BrowserSession {
                 : [],
             is_pdf_viewer: Boolean(this.currentUrl?.toLowerCase().endsWith('.pdf')),
             loading_status: this.currentPageLoadingStatus,
+            recent_events: includeRecentEvents
+                ? this._getRecentEventsSummary()
+                : null,
+            pending_network_requests: pendingNetworkRequests,
+            pagination_buttons: paginationButtons,
+            closed_popup_messages: this._getClosedPopupMessagesSnapshot(),
         });
         // Implement clickable element hash caching to detect new elements
         if (options.cache_clickable_elements_hashes && page) {
@@ -901,29 +1252,48 @@ export class BrowserSession {
     }
     _buildTabs() {
         if (!this._tabs.length) {
-            this._tabs.push({
-                page_id: this._tabCounter++,
+            const pageId = this._tabCounter++;
+            this._tabs.push(this._createTabInfo({
+                page_id: pageId,
                 url: this.currentUrl,
                 title: this.currentTitle || this.currentUrl,
-                parent_page_id: null,
-            });
+            }));
         }
         else {
             const tab = this._tabs[this.currentTabIndex];
+            if (tab && !tab.tab_id) {
+                tab.tab_id = this._formatTabId(tab.page_id);
+            }
             tab.url = this.currentUrl;
             tab.title = this.currentTitle || this.currentUrl;
         }
+        this._syncSessionManagerFromTabs();
         return this._tabs.slice();
     }
     async navigate_to(url, options = {}) {
         const signal = options.signal ?? null;
         this._throwIfAborted(signal);
+        this._assert_url_allowed(url);
         const normalized = normalize_url(url);
+        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;
+        this._recordRecentEvent('navigation_started', { url: normalized });
         const page = await this._withAbort(this.get_current_page(), signal);
         if (page?.goto) {
             try {
                 this.currentPageLoadingStatus = null;
-                await this._withAbort(page.goto(normalized, { waitUntil: 'domcontentloaded' }), signal);
+                const gotoOptions = {
+                    waitUntil,
+                };
+                if (timeoutMs !== null) {
+                    gotoOptions.timeout = timeoutMs;
+                }
+                await this._withAbort(page.goto(normalized, gotoOptions), signal);
+                const finalUrl = page.url();
+                this._assert_url_allowed(finalUrl);
                 await this._waitForStableNetwork(page, signal);
             }
             catch (error) {
@@ -931,6 +1301,10 @@ export class BrowserSession {
                     throw error;
                 }
                 const message = error.message ?? 'Navigation failed';
+                this._recordRecentEvent('navigation_failed', {
+                    url: normalized,
+                    error_message: message,
+                });
                 throw new BrowserError(message);
             }
         }
@@ -942,32 +1316,52 @@ export class BrowserSession {
             this._tabs[this.currentTabIndex].url = normalized;
             this._tabs[this.currentTabIndex].title = normalized;
         }
+        this._syncSessionManagerFromTabs();
         this._setActivePage(page ?? null);
+        this._recordRecentEvent('navigation_completed', { url: normalized });
         this.cachedBrowserState = null;
         return this.agent_current_page;
     }
     async create_new_tab(url, options = {}) {
         const signal = options.signal ?? null;
         this._throwIfAborted(signal);
+        this._assert_url_allowed(url);
         const normalized = normalize_url(url);
-        const newTab = {
+        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 newTab = this._createTabInfo({
             page_id: this._tabCounter++,
             url: normalized,
             title: normalized,
-            parent_page_id: null,
-        };
+        });
         this._tabs.push(newTab);
         this.currentTabIndex = this._tabs.length - 1;
         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 =
                 (await this._withAbort(this.browser_context?.newPage?.() ?? Promise.resolve(null), signal)) ?? null;
             if (page) {
                 this.currentPageLoadingStatus = null;
-                await this._withAbort(page.goto(normalized, { waitUntil: 'domcontentloaded' }), signal);
+                const gotoOptions = {
+                    waitUntil,
+                };
+                if (timeoutMs !== null) {
+                    gotoOptions.timeout = timeoutMs;
+                }
+                await this._withAbort(page.goto(normalized, gotoOptions), signal);
+                const finalUrl = page.url();
+                this._assert_url_allowed(finalUrl);
                 await this._waitForStableNetwork(page, signal);
             }
         }
@@ -975,18 +1369,56 @@ export class BrowserSession {
             if (this._isAbortError(error)) {
                 throw error;
             }
+            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',
+            });
             this.logger.debug(`Failed to open new tab via Playwright: ${error.message}`);
         }
         this.tabPages.set(newTab.page_id, page);
+        this._syncSessionManagerFromTabs();
         this._setActivePage(page);
         this.currentPageLoadingStatus = null;
         if (!this.human_current_page) {
             this.human_current_page = page;
         }
+        this._recordRecentEvent('tab_ready', {
+            url: normalized,
+            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,
+        }));
         this.cachedBrowserState = null;
         return this.agent_current_page;
     }
     _resolveTabIndex(identifier) {
+        if (typeof identifier === 'string') {
+            const normalized = identifier.trim();
+            if (!normalized) {
+                return -1;
+            }
+            if (normalized === '-1') {
+                return Math.max(0, this._tabs.length - 1);
+            }
+            const byTabId = this._tabs.findIndex((tab) => tab.tab_id === normalized);
+            if (byTabId !== -1) {
+                return byTabId;
+            }
+            const byTargetId = this._tabs.findIndex((tab) => tab.target_id === normalized);
+            if (byTargetId !== -1) {
+                return byTargetId;
+            }
+            const numeric = Number.parseInt(normalized, 10);
+            if (Number.isFinite(numeric)) {
+                return this._resolveTabIndex(numeric);
+            }
+            return -1;
+        }
         if (identifier === -1) {
             return Math.max(0, this._tabs.length - 1);
         }
@@ -1005,11 +1437,15 @@ export class BrowserSession {
         const index = this._resolveTabIndex(identifier);
         const tab = index >= 0 ? (this._tabs[index] ?? null) : null;
         if (!tab) {
-            throw new Error(`Tab index ${identifier} does not exist`);
+            throw new Error(`Tab '${identifier}' does not exist`);
+        }
+        if (!tab.tab_id) {
+            tab.tab_id = this._formatTabId(tab.page_id);
         }
         this.currentTabIndex = index;
         this.currentUrl = tab.url;
         this.currentTitle = tab.title;
+        this._syncSessionManagerFromTabs();
         const page = this.tabPages.get(tab.page_id) ?? null;
         this._setActivePage(page);
         if (page?.bringToFront) {
@@ -1024,15 +1460,27 @@ export class BrowserSession {
             }
         }
         await this._waitForLoad(page, 5000, signal);
+        this._recordRecentEvent('tab_switched', {
+            url: tab.url,
+            page_id: tab.page_id,
+            tab_id: tab.tab_id,
+        });
+        await this.event_bus.dispatch(new AgentFocusChangedEvent({
+            target_id: tab.target_id ?? tab.tab_id,
+            url: tab.url,
+        }));
         this.cachedBrowserState = null;
         return page;
     }
     async close_tab(identifier) {
         const index = this._resolveTabIndex(identifier);
         if (index < 0 || index >= this._tabs.length) {
-            throw new Error(`Tab index ${identifier} does not exist`);
+            throw new Error(`Tab '${identifier}' does not exist`);
         }
         const closingTab = this._tabs[index];
+        if (!closingTab.tab_id) {
+            closingTab.tab_id = this._formatTabId(closingTab.page_id);
+        }
         const closingPage = this.tabPages.get(closingTab.page_id) ?? null;
         if (closingPage?.close) {
             try {
@@ -1043,10 +1491,16 @@ export class BrowserSession {
             }
         }
         this.tabPages.delete(closingTab.page_id);
+        this._recordRecentEvent('tab_closed', {
+            url: closingTab.url,
+            page_id: closingTab.page_id,
+            tab_id: closingTab.tab_id,
+        });
         this._tabs.splice(index, 1);
         if (this.currentTabIndex >= this._tabs.length) {
             this.currentTabIndex = Math.max(0, this._tabs.length - 1);
         }
+        this._syncSessionManagerFromTabs();
         const tab = this._tabs[this.currentTabIndex] ?? null;
         const current = tab ? (this.tabPages.get(tab.page_id) ?? null) : null;
         this._setActivePage(current);
@@ -1056,12 +1510,379 @@ export class BrowserSession {
             const tab = this._tabs[this.currentTabIndex];
             this.currentUrl = tab.url;
             this.currentTitle = tab.title;
+            await this.event_bus.dispatch(new AgentFocusChangedEvent({
+                target_id: tab.target_id ?? tab.tab_id ?? 'unknown_target',
+                url: tab.url,
+            }));
         }
         else {
             this.currentUrl = 'about:blank';
             this.currentTitle = 'about:blank';
             this._setActivePage(null);
         }
+        await this.event_bus.dispatch(new TabClosedEvent({
+            target_id: closingTab.target_id ?? closingTab.tab_id,
+        }));
+    }
+    async wait(seconds, options = {}) {
+        const signal = options.signal ?? null;
+        this._throwIfAborted(signal);
+        const boundedSeconds = Math.max(Number(seconds) || 0, 0);
+        const delayMs = boundedSeconds * 1000;
+        if (delayMs <= 0) {
+            return;
+        }
+        await this._waitWithAbort(delayMs, signal);
+    }
+    async send_keys(keys, options = {}) {
+        const signal = options.signal ?? null;
+        this._throwIfAborted(signal);
+        const page = await this._withAbort(this.get_current_page(), signal);
+        const keyboard = page?.keyboard;
+        if (!keyboard) {
+            throw new BrowserError('Keyboard input is not available on the current page.');
+        }
+        try {
+            await this._withAbort(keyboard.press(keys), signal);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('Unknown key')) {
+                for (const char of keys) {
+                    await this._withAbort(keyboard.press(char), signal);
+                }
+                return;
+            }
+            throw error;
+        }
+    }
+    async click_coordinates(coordinate_x, coordinate_y, options = {}) {
+        const signal = options.signal ?? null;
+        this._throwIfAborted(signal);
+        const page = await this._withAbort(this.get_current_page(), signal);
+        if (!page?.mouse?.click) {
+            throw new BrowserError('Unable to perform coordinate click on the current page.');
+        }
+        await this._withAbort(page.mouse.click(coordinate_x, coordinate_y, {
+            button: options.button ?? 'left',
+        }), signal);
+    }
+    async scroll(direction, amount, options = {}) {
+        const signal = options.signal ?? null;
+        this._throwIfAborted(signal);
+        const normalizedAmount = Math.max(Math.floor(Math.abs(amount)), 0);
+        if (normalizedAmount === 0) {
+            return;
+        }
+        const page = await this._withAbort(this.get_current_page(), signal);
+        if (!page?.evaluate) {
+            throw new BrowserError('Unable to access current page for scrolling.');
+        }
+        const node = options.node ?? null;
+        if (node?.xpath) {
+            const scrolled = await this._withAbort(page.evaluate((payload) => {
+                const root = document.evaluate(payload.xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
+                if (!root) {
+                    return false;
+                }
+                const topDelta = payload.direction === 'up'
+                    ? -payload.amount
+                    : payload.direction === 'down'
+                        ? payload.amount
+                        : 0;
+                const leftDelta = payload.direction === 'left'
+                    ? -payload.amount
+                    : payload.direction === 'right'
+                        ? payload.amount
+                        : 0;
+                root.scrollBy({
+                    top: topDelta,
+                    left: leftDelta,
+                    behavior: 'auto',
+                });
+                return true;
+            }, { xpath: node.xpath, direction, amount: normalizedAmount }), signal);
+            if (scrolled) {
+                return;
+            }
+        }
+        if (direction === 'up' || direction === 'down') {
+            const pixels = direction === 'down' ? -normalizedAmount : normalizedAmount;
+            await this._withAbort(this._scrollContainer(pixels), signal);
+            return;
+        }
+        const horizontalDelta = direction === 'left' ? -normalizedAmount : normalizedAmount;
+        await this._withAbort(page.evaluate((x) => window.scrollBy(x, 0), horizontalDelta), signal);
+    }
+    async scroll_to_text(text, options = {}) {
+        const signal = options.signal ?? null;
+        this._throwIfAborted(signal);
+        const page = await this._withAbort(this.get_current_page(), signal);
+        if (!page?.evaluate) {
+            throw new BrowserError('Unable to access page for scrolling.');
+        }
+        const success = await this._withAbort(page.evaluate((payload) => {
+            const query = payload.text.toLowerCase();
+            const iterator = document.createNodeIterator(document.body, NodeFilter.SHOW_ELEMENT);
+            let node;
+            while ((node = iterator.nextNode())) {
+                const el = node;
+                if (!el || !el.textContent) {
+                    continue;
+                }
+                if (el.textContent.toLowerCase().includes(query)) {
+                    el.scrollIntoView({
+                        behavior: 'smooth',
+                        block: payload.direction === 'up' ? 'start' : 'center',
+                    });
+                    return true;
+                }
+            }
+            return false;
+        }, { text, direction: options.direction ?? 'down' }), signal);
+        if (!success) {
+            throw new BrowserError(`Text '${text}' not found on page`);
+        }
+    }
+    async get_dropdown_options(element_node, options = {}) {
+        const signal = options.signal ?? null;
+        this._throwIfAborted(signal);
+        const page = await this._withAbort(this.get_current_page(), signal);
+        if (!page?.evaluate) {
+            throw new BrowserError('Unable to evaluate dropdown options on current page.');
+        }
+        if (!element_node?.xpath) {
+            throw new BrowserError('DOM element does not include an XPath selector.');
+        }
+        const payload = await this._withAbort(page.evaluate(({ xpath }) => {
+            const element = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
+            if (!element)
+                return null;
+            if (element.tagName?.toLowerCase() === 'select') {
+                const options = Array.from(element.options).map((opt, index) => ({
+                    text: opt.textContent?.trim() ?? '',
+                    value: (opt.value ?? '').trim(),
+                    index,
+                }));
+                return { type: 'select', options };
+            }
+            const ariaRoles = new Set(['menu', 'listbox', 'combobox']);
+            const role = element.getAttribute('role');
+            if (role && ariaRoles.has(role)) {
+                const nodes = element.querySelectorAll('[role="menuitem"],[role="option"]');
+                const options = Array.from(nodes).map((node, index) => ({
+                    text: node.textContent?.trim() ?? '',
+                    value: node.textContent?.trim() ?? '',
+                    index,
+                }));
+                return { type: 'aria', options };
+            }
+            return null;
+        }, { xpath: element_node.xpath }), signal);
+        if (!payload || !Array.isArray(payload.options)) {
+            throw new BrowserError('No options found for the specified dropdown.');
+        }
+        const normalizedOptions = payload.options
+            .map((option, index) => ({
+            index: typeof option?.index === 'number' && Number.isFinite(option.index)
+                ? option.index
+                : index,
+            text: String(option?.text ?? ''),
+            value: String(option?.value ?? ''),
+        }))
+            .filter((option) => option.text.length > 0 || option.value.length > 0);
+        if (normalizedOptions.length === 0) {
+            throw new BrowserError('No options found for the specified dropdown.');
+        }
+        const formattedOptions = normalizedOptions.map((option) => `${option.index}: text=${JSON.stringify(option.text)}, value=${JSON.stringify(option.value)}`);
+        formattedOptions.push('Prefer exact text first; if needed select_dropdown_option also supports case-insensitive text/value matching.');
+        const message = formattedOptions.join('\n');
+        const indexForMemory = element_node.highlight_index ?? 'unknown';
+        return {
+            type: String(payload.type ?? 'unknown'),
+            options: JSON.stringify(normalizedOptions),
+            formatted_options: formattedOptions.join('\n'),
+            message,
+            short_term_memory: message,
+            long_term_memory: `Found dropdown options for index ${indexForMemory}.`,
+        };
+    }
+    async select_dropdown_option(element_node, text, options = {}) {
+        const signal = options.signal ?? null;
+        this._throwIfAborted(signal);
+        if (!element_node?.xpath) {
+            throw new BrowserError('DOM element does not include an XPath selector.');
+        }
+        const page = await this._withAbort(this.get_current_page(), signal);
+        if (!page) {
+            throw new BrowserError('No active page for selection.');
+        }
+        const formatAvailableOptions = (opts) => opts
+            .map((opt) => `  - [${opt.index}] text=${JSON.stringify(opt.text)} value=${JSON.stringify(opt.value)}`)
+            .join('\n');
+        const pageFrames = (() => {
+            const framesAccessor = page.frames;
+            if (typeof framesAccessor === 'function') {
+                try {
+                    const result = framesAccessor.call(page);
+                    return Array.isArray(result) ? result : [];
+                }
+                catch {
+                    return [];
+                }
+            }
+            return Array.isArray(framesAccessor) ? framesAccessor : [];
+        })();
+        for (const frame of pageFrames) {
+            try {
+                const typeInfo = await this._withAbort(frame.evaluate((xpath) => {
+                    const element = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
+                    if (!element)
+                        return { found: false };
+                    const tagName = element.tagName?.toLowerCase();
+                    const role = element.getAttribute?.('role');
+                    if (tagName === 'select')
+                        return { found: true, type: 'select' };
+                    if (role && ['menu', 'listbox', 'combobox'].includes(role))
+                        return { found: true, type: 'aria' };
+                    return { found: false };
+                }, element_node.xpath), signal);
+                if (!typeInfo?.found) {
+                    continue;
+                }
+                if (typeInfo.type === 'select') {
+                    const selection = await this._withAbort(frame.evaluate(({ xpath, optionText, }) => {
+                        const root = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
+                        if (!root || root.tagName?.toLowerCase() !== 'select') {
+                            return { found: false };
+                        }
+                        const options = Array.from(root.options).map((opt, index) => ({
+                            index,
+                            text: opt.textContent?.trim() ?? '',
+                            value: (opt.value ?? '').trim(),
+                        }));
+                        const targetRaw = optionText.trim();
+                        const targetLower = optionText.trim().toLowerCase();
+                        let matchedIndex = options.findIndex((opt) => opt.text === targetRaw || opt.value === targetRaw);
+                        if (matchedIndex < 0) {
+                            matchedIndex = options.findIndex((opt) => opt.text.trim().toLowerCase() === targetLower ||
+                                opt.value.trim().toLowerCase() === targetLower);
+                        }
+                        if (matchedIndex < 0) {
+                            return { found: true, success: false, options };
+                        }
+                        const matched = options[matchedIndex];
+                        root.value = matched.value;
+                        root.dispatchEvent(new Event('input', { bubbles: true }));
+                        root.dispatchEvent(new Event('change', { bubbles: true }));
+                        const selectedOption = root.selectedIndex >= 0
+                            ? root.options[root.selectedIndex]
+                            : null;
+                        const selectedText = selectedOption?.textContent?.trim() ?? '';
+                        const selectedValue = (root.value ?? '').trim();
+                        const selectedValueLower = selectedValue.trim().toLowerCase();
+                        const selectedTextLower = selectedText.trim().toLowerCase();
+                        const matchedValueLower = String(matched.value ?? '')
+                            .trim()
+                            .toLowerCase();
+                        const matchedTextLower = String(matched.text ?? '')
+                            .trim()
+                            .toLowerCase();
+                        const verified = selectedValueLower === matchedValueLower ||
+                            selectedTextLower === matchedTextLower;
+                        return {
+                            found: true,
+                            success: verified,
+                            options,
+                            selectedText,
+                            selectedValue,
+                            matched,
+                        };
+                    }, { xpath: element_node.xpath, optionText: text }), signal);
+                    if (selection?.found && selection.success) {
+                        const matchedText = selection.matched?.text ?? text;
+                        const matchedValue = selection.matched?.value ?? '';
+                        const msg = `Selected option ${matchedText} (${matchedValue})`;
+                        return {
+                            message: msg,
+                            short_term_memory: msg,
+                            long_term_memory: msg,
+                            matched_text: String(matchedText),
+                            matched_value: String(matchedValue),
+                        };
+                    }
+                    if (selection?.found) {
+                        const details = formatAvailableOptions(selection.options ?? []);
+                        throw new BrowserError(`Could not select option '${text}' for index ${element_node.highlight_index ?? 'unknown'}.\nAvailable options:\n${details}`);
+                    }
+                    continue;
+                }
+                const clicked = await this._withAbort(frame.evaluate(({ xpath, optionText }) => {
+                    const root = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
+                    if (!root)
+                        return false;
+                    const nodes = root.querySelectorAll('[role="menuitem"],[role="option"]');
+                    const options = Array.from(nodes).map((node, index) => ({
+                        index,
+                        text: node.textContent?.trim() ?? '',
+                        value: node.textContent?.trim() ?? '',
+                    }));
+                    const targetRaw = optionText.trim();
+                    const targetLower = optionText.trim().toLowerCase();
+                    let matchedIndex = options.findIndex((opt) => opt.text === targetRaw || opt.value === targetRaw);
+                    if (matchedIndex < 0) {
+                        matchedIndex = options.findIndex((opt) => opt.text.trim().toLowerCase() === targetLower ||
+                            opt.value.trim().toLowerCase() === targetLower);
+                    }
+                    if (matchedIndex < 0) {
+                        return { found: true, success: false, options };
+                    }
+                    nodes[matchedIndex].click();
+                    return {
+                        found: true,
+                        success: true,
+                        options,
+                        matched: options[matchedIndex],
+                    };
+                }, { xpath: element_node.xpath, optionText: text }), signal);
+                if (clicked?.found && clicked.success) {
+                    const matchedText = clicked.matched?.text ?? text;
+                    const msg = `Selected menu item ${matchedText}`;
+                    return {
+                        message: msg,
+                        short_term_memory: msg,
+                        long_term_memory: msg,
+                        matched_text: String(matchedText),
+                    };
+                }
+                if (clicked?.found) {
+                    const details = formatAvailableOptions(clicked.options ?? []);
+                    throw new BrowserError(`Could not select option '${text}' for index ${element_node.highlight_index ?? 'unknown'}.\nAvailable options:\n${details}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof BrowserError) {
+                    throw error;
+                }
+                continue;
+            }
+        }
+        throw new BrowserError(`Could not select option '${text}' for index ${element_node.highlight_index ?? 'unknown'}`);
+    }
+    async upload_file(element_node, file_path, options = {}) {
+        const signal = options.signal ?? null;
+        this._throwIfAborted(signal);
+        const locator = await this.get_locate_element(element_node);
+        if (!locator) {
+            throw new Error('Element not found');
+        }
+        if (!fs.existsSync(file_path)) {
+            throw new Error(`File does not exist: ${file_path}`);
+        }
+        const locatorWithUpload = locator;
+        if (typeof locatorWithUpload.setInputFiles !== 'function') {
+            throw new Error('Element does not support file upload');
+        }
+        await this._withAbort(locatorWithUpload.setInputFiles(file_path, { timeout: 5000 }), signal);
     }
     async go_back(options = {}) {
         const signal = options.signal ?? null;
@@ -1090,6 +1911,7 @@ export class BrowserSession {
             this._tabs[this.currentTabIndex].url = previous;
             this._tabs[this.currentTabIndex].title = previous;
         }
+        this._recordRecentEvent('navigation_back', { url: previous });
     }
     async get_dom_element_by_index(_index, options = {}) {
         const selectorMap = await this.get_selector_map(options);
@@ -1217,13 +2039,19 @@ export class BrowserSession {
     }
     async _input_text_element_node(node, text, options = {}) {
         const signal = options.signal ?? null;
+        const clear = options.clear ?? true;
         this._throwIfAborted(signal);
         const locator = await this.get_locate_element(node);
         if (!locator) {
             throw new Error('Element not found');
         }
         await this._withAbort(locator.click({ timeout: 5000 }), signal);
-        await this._withAbort(locator.fill(text, { timeout: 5000 }), signal);
+        if (clear) {
+            await this._withAbort(locator.fill(text, { timeout: 5000 }), signal);
+        }
+        else {
+            await this._withAbort(locator.type(text, { timeout: 5000 }), signal);
+        }
     }
     async _click_element_node(node, options = {}) {
         const signal = options.signal ?? null;
@@ -1242,15 +2070,46 @@ export class BrowserSession {
             await performClick();
             try {
                 const download = await this._withAbort(downloadPromise, signal);
+                const downloadGuid = uuid7str();
                 const suggested = typeof download.suggestedFilename === 'function'
                     ? download.suggestedFilename()
                     : 'download';
+                const downloadUrl = typeof download.url === 'function'
+                    ? download.url()
+                    : (this.currentUrl ?? '');
+                await this.event_bus.dispatch(new DownloadStartedEvent({
+                    guid: downloadGuid,
+                    url: downloadUrl,
+                    suggested_filename: suggested,
+                    auto_download: false,
+                }));
                 const uniqueFilename = await BrowserSession.get_unique_filename(downloadsDir, suggested);
                 const downloadPath = path.join(downloadsDir, uniqueFilename);
                 if (typeof download.saveAs === 'function') {
                     await download.saveAs(downloadPath);
                 }
-                this.add_downloaded_file(downloadPath);
+                const stats = fs.existsSync(downloadPath)
+                    ? fs.statSync(downloadPath)
+                    : null;
+                await this.event_bus.dispatch(new DownloadProgressEvent({
+                    guid: downloadGuid,
+                    received_bytes: stats?.size ?? 0,
+                    total_bytes: stats?.size ?? 0,
+                    state: 'completed',
+                }));
+                const fileDownloadedResult = await this.event_bus.dispatch(new FileDownloadedEvent({
+                    guid: downloadGuid,
+                    url: downloadUrl,
+                    path: downloadPath,
+                    file_name: uniqueFilename,
+                    file_size: stats?.size ?? 0,
+                    file_type: path.extname(uniqueFilename).replace('.', '') || null,
+                    mime_type: null,
+                    auto_download: false,
+                }));
+                if (fileDownloadedResult.handler_results.length === 0) {
+                    this.add_downloaded_file(downloadPath);
+                }
                 return downloadPath;
             }
             catch (error) {
@@ -1609,7 +2468,7 @@ export class BrowserSession {
         try {
             this.logger.debug(`📸 Taking ${full_page ? 'full-page' : 'viewport'} PNG screenshot via CDP: ${url}`);
             // Create CDP session for the screenshot
-            cdp_session = await this.browser_context.newCDPSession(page);
+            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,
@@ -1683,7 +2542,7 @@ export class BrowserSession {
     // ==================== P2 Additional Functions ====================
     /**
      * Get information about all open tabs
-     * @returns Array of tab information including page_id, url, and title
+     * @returns Array of tab information including page_id, tab_id, url, and title
      */
     async get_tabs_info() {
         if (!this.browser_context) {
@@ -1693,6 +2552,9 @@ export class BrowserSession {
         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);
             // Skip chrome:// pages and new tab pages
             const isNewTab = page.url() === 'about:blank' ||
                 page.url().startsWith('chrome://newtab');
@@ -1700,6 +2562,7 @@ export class BrowserSession {
                 if (isNewTab) {
                     tabs_info.push({
                         page_id,
+                        tab_id,
                         url: page.url(),
                         title: 'ignore this tab and do not use it',
                     });
@@ -1707,6 +2570,7 @@ export class BrowserSession {
                 else {
                     tabs_info.push({
                         page_id,
+                        tab_id,
                         url: page.url(),
                         title: page.url(),
                     });
@@ -1720,13 +2584,14 @@ export class BrowserSession {
                     setTimeout(() => reject(new Error('timeout')), 2000);
                 });
                 const title = await Promise.race([titlePromise, timeoutPromise]);
-                tabs_info.push({ page_id, url: page.url(), title });
+                tabs_info.push({ page_id, tab_id, url: page.url(), title });
             }
             catch (error) {
                 this.logger.debug(`⚠️ Failed to get tab info for tab #${page_id}: ${page.url()} (using fallback title)`);
                 if (isNewTab) {
                     tabs_info.push({
                         page_id,
+                        tab_id,
                         url: page.url(),
                         title: 'ignore this tab and do not use it',
                     });
@@ -1734,6 +2599,7 @@ export class BrowserSession {
                 else {
                     tabs_info.push({
                         page_id,
+                        tab_id,
                         url: page.url(),
                         title: page.url(), // Use URL as fallback title
                     });
@@ -1800,9 +2666,9 @@ export class BrowserSession {
      * @param include_screenshot - Include screenshot in state summary
      * @returns BrowserStateSummary with current page state
      */
-    async get_state_summary(cache_clickable_elements_hashes = true, include_screenshot = true) {
+    async get_state_summary(cache_clickable_elements_hashes = true, include_screenshot = true, include_recent_events = false) {
         this.logger.debug('🔄 Starting get_state_summary...');
-        const updated_state = await this._get_updated_state(-1, include_screenshot);
+        const updated_state = await this._get_updated_state(-1, include_screenshot, include_recent_events);
         // Implement clickable element hash caching to detect new elements
         if (cache_clickable_elements_hashes) {
             const page = await this.get_current_page();
@@ -1828,7 +2694,7 @@ export class BrowserSession {
      * Get minimal state summary without DOM processing, but with screenshot
      * Used when page is in error state or unresponsive
      */
-    async get_minimal_state_summary() {
+    async get_minimal_state_summary(include_recent_events = false) {
         try {
             const page = await this.get_current_page();
             const url = page ? page.url() : 'unknown';
@@ -1870,6 +2736,7 @@ export class BrowserSession {
                 height: 720,
             };
             const dom_state = new DOMState(minimal_element_tree, {});
+            this._original_viewport_size = [viewport.width, viewport.height];
             return new BrowserStateSummary(dom_state, {
                 url,
                 title,
@@ -1892,6 +2759,12 @@ export class BrowserSession {
                 browser_errors: ['Page in error state - minimal navigation available'],
                 is_pdf_viewer: false,
                 loading_status: this.currentPageLoadingStatus,
+                recent_events: include_recent_events
+                    ? this._getRecentEventsSummary()
+                    : null,
+                pending_network_requests: [],
+                pagination_buttons: [],
+                closed_popup_messages: this._getClosedPopupMessagesSnapshot(),
             });
         }
         catch (error) {
@@ -1904,7 +2777,7 @@ export class BrowserSession {
      * @param focus_element - Element index to focus on (default: -1)
      * @param include_screenshot - Whether to include screenshot
      */
-    async _get_updated_state(focus_element = -1, include_screenshot = true) {
+    async _get_updated_state(focus_element = -1, include_screenshot = true, include_recent_events = false) {
         const page = await this.get_current_page();
         if (!page) {
             throw new Error('No current page available');
@@ -1922,6 +2795,7 @@ export class BrowserSession {
                 height: 720,
             };
             const dom_state = new DOMState(minimal_element_tree, {});
+            this._original_viewport_size = [viewport.width, viewport.height];
             return new BrowserStateSummary(dom_state, {
                 url: page_url,
                 title: this._is_new_tab_page(page_url) ? 'New Tab' : 'Chrome Page',
@@ -1944,6 +2818,12 @@ export class BrowserSession {
                 browser_errors: [],
                 is_pdf_viewer: false,
                 loading_status: this.currentPageLoadingStatus,
+                recent_events: include_recent_events
+                    ? this._getRecentEventsSummary()
+                    : null,
+                pending_network_requests: [],
+                pagination_buttons: [],
+                closed_popup_messages: this._getClosedPopupMessagesSnapshot(),
             });
         }
         // Normal path for regular pages
@@ -1998,6 +2878,14 @@ export class BrowserSession {
         }
         // Get page info and scroll info
         const page_info = await this.get_page_info(page);
+        if (page_info &&
+            Number.isFinite(page_info.viewport_width) &&
+            Number.isFinite(page_info.viewport_height)) {
+            this._original_viewport_size = [
+                Math.floor(page_info.viewport_width),
+                Math.floor(page_info.viewport_height),
+            ];
+        }
         let pixels_above = 0;
         let pixels_below = 0;
         try {
@@ -2032,6 +2920,8 @@ export class BrowserSession {
         }
         // Check if PDF viewer
         const is_pdf_viewer = await this._is_pdf_viewer(page);
+        const pendingNetworkRequests = await this._getPendingNetworkRequests(page);
+        const paginationButtons = DomService.detect_pagination_buttons(content.selector_map);
         const browser_state = new BrowserStateSummary(content, {
             url: page_url,
             title,
@@ -2043,6 +2933,12 @@ export class BrowserSession {
             browser_errors,
             is_pdf_viewer,
             loading_status: this.currentPageLoadingStatus,
+            recent_events: include_recent_events
+                ? this._getRecentEventsSummary()
+                : null,
+            pending_network_requests: pendingNetworkRequests,
+            pagination_buttons: paginationButtons,
+            closed_popup_messages: this._getClosedPopupMessagesSnapshot(),
         });
         this.logger.debug('✅ get_state_summary completed successfully');
         return browser_state;
@@ -2053,7 +2949,22 @@ export class BrowserSession {
     _is_new_tab_page(url) {
         return (url === 'about:blank' ||
             url === 'about:newtab' ||
-            url === 'chrome://newtab/');
+            url === 'chrome://newtab/' ||
+            url === 'chrome://new-tab-page/' ||
+            url === 'chrome://new-tab-page');
+    }
+    _is_ip_address_host(hostname) {
+        const normalized = hostname.startsWith('[') && hostname.endsWith(']')
+            ? hostname.slice(1, -1)
+            : hostname;
+        return isIP(normalized) !== 0;
+    }
+    _get_domain_variants(hostname) {
+        const host = hostname.toLowerCase();
+        if (host.startsWith('www.')) {
+            return [host, host.slice(4)];
+        }
+        return [host, `www.${host}`];
     }
     /**
      * Check if page is displaying a PDF
@@ -2319,37 +3230,111 @@ export class BrowserSession {
      * Check if a URL is allowed based on allowed_domains configuration
      * @param url - URL to check
      */
-    _is_url_allowed(url) {
-        if (!this.browser_profile.allowed_domains ||
-            this.browser_profile.allowed_domains.length === 0) {
-            return true; // No restrictions if allowed_domains not configured
-        }
-        // Always allow new tab pages
+    _get_url_access_denial_reason(url) {
+        // Always allow new tab pages and browser-internal pages we intentionally use.
         if (this._is_new_tab_page(url)) {
-            return true;
+            return null;
         }
-        // Check against allowed domains
-        for (const allowed_domain of this.browser_profile.allowed_domains) {
-            try {
-                if (match_url_with_domain_pattern(url, allowed_domain, true)) {
-                    return true;
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return 'invalid_url';
+        }
+        if (parsed.protocol === 'data:' || parsed.protocol === 'blob:') {
+            return null;
+        }
+        if (!parsed.hostname) {
+            return 'missing_host';
+        }
+        const [hostVariant, hostAlt] = this._get_domain_variants(parsed.hostname);
+        if (this.browser_profile.block_ip_addresses &&
+            this._is_ip_address_host(parsed.hostname)) {
+            return 'ip_address_blocked';
+        }
+        const allowedDomains = this.browser_profile.allowed_domains;
+        if (allowedDomains &&
+            ((Array.isArray(allowedDomains) && allowedDomains.length > 0) ||
+                (allowedDomains instanceof Set && allowedDomains.size > 0))) {
+            if (allowedDomains instanceof Set) {
+                if (allowedDomains.has(hostVariant) || allowedDomains.has(hostAlt)) {
+                    return null;
                 }
             }
-            catch (error) {
-                this.logger.warning(`Invalid domain pattern: ${allowed_domain}`);
+            else {
+                for (const allowedDomain of allowedDomains) {
+                    try {
+                        if (match_url_with_domain_pattern(url, allowedDomain, true)) {
+                            return null;
+                        }
+                    }
+                    catch {
+                        this.logger.warning(`Invalid domain pattern: ${allowedDomain}`);
+                    }
+                }
+            }
+            return 'not_in_allowed_domains';
+        }
+        const prohibitedDomains = this.browser_profile.prohibited_domains;
+        if (prohibitedDomains &&
+            ((Array.isArray(prohibitedDomains) && prohibitedDomains.length > 0) ||
+                (prohibitedDomains instanceof Set && prohibitedDomains.size > 0))) {
+            if (prohibitedDomains instanceof Set) {
+                if (prohibitedDomains.has(hostVariant) ||
+                    prohibitedDomains.has(hostAlt)) {
+                    return 'in_prohibited_domains';
+                }
             }
+            else {
+                for (const prohibitedDomain of prohibitedDomains) {
+                    try {
+                        if (match_url_with_domain_pattern(url, prohibitedDomain, true)) {
+                            return 'in_prohibited_domains';
+                        }
+                    }
+                    catch {
+                        this.logger.warning(`Invalid domain pattern: ${prohibitedDomain}`);
+                    }
+                }
+            }
+        }
+        return null;
+    }
+    _is_url_allowed(url) {
+        return this._get_url_access_denial_reason(url) === null;
+    }
+    _formatDomainCollection(value) {
+        if (value instanceof Set) {
+            return JSON.stringify(Array.from(value));
+        }
+        return JSON.stringify(value ?? null);
+    }
+    _assert_url_allowed(url) {
+        const denialReason = this._get_url_access_denial_reason(url);
+        if (!denialReason) {
+            return;
+        }
+        this._recordRecentEvent('navigation_blocked', {
+            url,
+            error_message: denialReason,
+        });
+        if (denialReason === 'not_in_allowed_domains') {
+            throw new URLNotAllowedError(`URL ${url} is not in allowed_domains. Current allowed_domains: ${this._formatDomainCollection(this.browser_profile.allowed_domains)}`);
+        }
+        if (denialReason === 'in_prohibited_domains') {
+            throw new URLNotAllowedError(`URL ${url} is blocked by prohibited_domains. Current prohibited_domains: ${this._formatDomainCollection(this.browser_profile.prohibited_domains)}`);
         }
-        return false;
+        if (denialReason === 'ip_address_blocked') {
+            throw new URLNotAllowedError(`URL ${url} is blocked because block_ip_addresses=true`);
+        }
+        throw new URLNotAllowedError(`URL ${url} is not allowed (${denialReason})`);
     }
     /**
      * Navigate helper with URL validation
      */
     async navigate(url) {
-        // Validate URL is allowed
-        if (!this._is_url_allowed(url)) {
-            throw new Error(`URL ${url} is not in allowed_domains. ` +
-                `Current allowed_domains: ${JSON.stringify(this.browser_profile.allowed_domains)}`);
-        }
+        this._assert_url_allowed(url);
         await this.navigate_to(url);
     }
     /**
@@ -2389,11 +3374,18 @@ export class BrowserSession {
         if (!hasActiveResources) {
             return;
         }
-        this._stoppingPromise = this._shutdown_browser_session();
+        this._stoppingPromise = Promise.resolve().then(async () => {
+            await this.event_bus.dispatch(new BrowserStopEvent());
+            await this._shutdown_browser_session();
+        });
         try {
             await this._stoppingPromise;
+            this._recordRecentEvent('browser_stopped');
+            await this.event_bus.dispatch(new BrowserStoppedEvent());
         }
         finally {
+            this.detach_all_watchdogs();
+            await this.event_bus.stop();
             this._stoppingPromise = null;
         }
     }
@@ -2426,10 +3418,40 @@ export class BrowserSession {
                 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}`);
-                // Track the downloaded file
-                this.add_downloaded_file(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) {
@@ -2477,6 +3499,19 @@ export class BrowserSession {
         }
     }
     // region - Trace Recording
+    /**
+     * Start tracing on browser context if traces_dir is configured
+     * Note: Currently optional as it may cause performance issues in some cases
+     */
+    async start_trace_recording() {
+        await this._startContextTracing();
+    }
+    /**
+     * Save browser trace recording if active
+     */
+    async save_trace_recording() {
+        await this._saveTraceRecording();
+    }
     /**
      * Start tracing on browser context if traces_dir is configured
      * Note: Currently optional as it may cause performance issues in some cases
@@ -2493,6 +3528,7 @@ export class BrowserSession {
             }
             catch (error) {
                 this.logger.warning(`Failed to start tracing: ${error.message}`);
+                throw error;
             }
         }
     }
@@ -2519,6 +3555,7 @@ export class BrowserSession {
             }
             catch (error) {
                 this.logger.warning(`Failed to save trace recording: ${error.message}`);
+                throw error;
             }
         }
     }
@@ -2533,7 +3570,7 @@ export class BrowserSession {
     async _scrollWithCdpGesture(page, pixels) {
         try {
             // Use CDP to synthesize scroll gesture - works in all contexts including PDFs
-            const cdpSession = await this.browser_context.newCDPSession(page);
+            const cdpSession = await this.get_or_create_cdp_session(page);
             // Get viewport center for scroll origin
             const viewport = await page.evaluate(() => ({
                 width: window.innerWidth,
@@ -2705,7 +3742,7 @@ export class BrowserSession {
      * @returns A new BrowserSession instance with copied state
      */
     modelCopy() {
-        return new BrowserSession({
+        const copy = new BrowserSession({
             id: this.id,
             browser_profile: this.browser_profile,
             browser: this.browser,
@@ -2718,7 +3755,15 @@ export class BrowserSession {
             browser_pid: this.browser_pid,
             playwright: this.playwright,
             downloaded_files: [...this.downloaded_files],
+            closed_popup_messages: [...this._closedPopupMessages],
         });
+        copy.llm_screenshot_size = this.llm_screenshot_size
+            ? [...this.llm_screenshot_size]
+            : null;
+        copy._original_viewport_size = this._original_viewport_size
+            ? [...this._original_viewport_size]
+            : null;
+        return copy;
     }
     model_copy() {
         return this.modelCopy();
@@ -2767,7 +3812,7 @@ export class BrowserSession {
             try {
                 // Create CDP session from the clean page
                 const cdpSession = await Promise.race([
-                    this.browser_context.newCDPSession(tempPage),
+                    this.get_or_create_cdp_session(tempPage),
                     new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout creating CDP session')), 5000)),
                 ]);
                 try {
@@ -3233,6 +4278,16 @@ export class BrowserSession {
     }
     // endregion
     // region - Process Management
+    /**
+     * Normalize pid values before issuing process operations.
+     */
+    _normalizePid(pid) {
+        if (!Number.isSafeInteger(pid) || pid <= 0) {
+            this.logger.debug(`Skipping process operation for invalid pid: ${String(pid)}`);
+            return null;
+        }
+        return pid;
+    }
     /**
      * Kill all child processes spawned by this browser session
      */
@@ -3241,17 +4296,17 @@ export class BrowserSession {
             return;
         }
         this.logger.debug(`Killing ${this._childProcesses.size} child processes`);
-        for (const pid of this._childProcesses) {
+        for (const trackedPid of this._childProcesses) {
+            const pid = this._normalizePid(trackedPid);
+            if (!pid) {
+                continue;
+            }
             try {
-                // Try to kill the process
                 process.kill(pid, 'SIGTERM');
                 this.logger.debug(`Sent SIGTERM to process ${pid}`);
-                // Wait briefly and check if still alive
                 await new Promise((resolve) => setTimeout(resolve, 500));
                 try {
-                    // Check if process still exists
                     process.kill(pid, 0);
-                    // If we get here, process is still alive, force kill
                     process.kill(pid, 'SIGKILL');
                     this.logger.debug(`Sent SIGKILL to process ${pid}`);
                 }
@@ -3260,7 +4315,6 @@ export class BrowserSession {
                 }
             }
             catch (error) {
-                // Process doesn't exist or we don't have permission
                 this.logger.debug(`Could not kill process ${pid}: ${error.message}`);
             }
         }
@@ -3270,39 +4324,39 @@ export class BrowserSession {
      * Terminate the browser process and all its children
      */
     async _terminateBrowserProcess() {
-        if (!this.browser_pid) {
+        const browserPid = this._normalizePid(this.browser_pid);
+        if (!browserPid) {
             return;
         }
         try {
-            this.logger.debug(`Terminating browser process ${this.browser_pid}`);
-            // Platform-specific process tree termination
+            this.logger.debug(`Terminating browser process ${browserPid}`);
             if (process.platform === 'win32') {
-                // Windows: use taskkill to kill process tree
-                await execAsync(`taskkill /PID ${this.browser_pid} /T /F`).catch(() => {
+                await execFileAsync('taskkill', [
+                    '/PID',
+                    String(browserPid),
+                    '/T',
+                    '/F',
+                ]).catch(() => {
                     // Ignore errors if process already dead
                 });
             }
             else {
-                // Unix-like: kill process group
                 try {
-                    // Try to kill the process group
-                    process.kill(-this.browser_pid, 'SIGTERM');
+                    process.kill(-browserPid, 'SIGTERM');
                     await new Promise((resolve) => setTimeout(resolve, 1000));
-                    // Check if still alive and force kill if needed
                     try {
-                        process.kill(-this.browser_pid, 0);
-                        process.kill(-this.browser_pid, 'SIGKILL');
+                        process.kill(-browserPid, 0);
+                        process.kill(-browserPid, 'SIGKILL');
                     }
                     catch {
                         // Process is dead
                     }
                 }
                 catch {
-                    // Fallback to killing just the process
                     try {
-                        process.kill(this.browser_pid, 'SIGTERM');
+                        process.kill(browserPid, 'SIGTERM');
                         await new Promise((resolve) => setTimeout(resolve, 1000));
-                        process.kill(this.browser_pid, 'SIGKILL');
+                        process.kill(browserPid, 'SIGKILL');
                     }
                     catch {
                         // Process doesn't exist
@@ -3319,26 +4373,37 @@ export class BrowserSession {
      * Cross-platform implementation using ps on Unix-like systems and WMIC on Windows
      */
     async _getChildProcesses(pid) {
+        const normalizedPid = this._normalizePid(pid);
+        if (!normalizedPid) {
+            return [];
+        }
         try {
             if (process.platform === 'win32') {
-                // Windows: use WMIC
-                const { stdout } = await execAsync(`wmic process where (ParentProcessId=${pid}) get ProcessId`);
-                const pids = stdout
-                    .split('\n')
-                    .slice(1) // Skip header
-                    .map((line) => parseInt(line.trim(), 10))
-                    .filter((p) => !isNaN(p));
-                return pids;
-            }
-            else {
-                // Unix-like: use ps
-                const { stdout } = await execAsync(`ps -o pid= --ppid ${pid}`);
+                const { stdout } = await execFileAsync('wmic', [
+                    'process',
+                    'where',
+                    `ParentProcessId=${normalizedPid}`,
+                    'get',
+                    'ProcessId',
+                ]);
                 const pids = stdout
                     .split('\n')
+                    .slice(1)
                     .map((line) => parseInt(line.trim(), 10))
-                    .filter((p) => !isNaN(p));
+                    .filter((p) => Number.isFinite(p));
                 return pids;
             }
+            const { stdout } = await execFileAsync('ps', [
+                '-o',
+                'pid=',
+                '--ppid',
+                String(normalizedPid),
+            ]);
+            const pids = stdout
+                .split('\n')
+                .map((line) => parseInt(line.trim(), 10))
+                .filter((p) => Number.isFinite(p));
+            return pids;
         }
         catch {
             return [];
@@ -3348,13 +4413,19 @@ export class BrowserSession {
      * Track a child process
      */
     _trackChildProcess(pid) {
-        this._childProcesses.add(pid);
+        const normalizedPid = this._normalizePid(pid);
+        if (normalizedPid) {
+            this._childProcesses.add(normalizedPid);
+        }
     }
     /**
      * Untrack a child process
      */
     _untrackChildProcess(pid) {
-        this._childProcesses.delete(pid);
+        const normalizedPid = this._normalizePid(pid);
+        if (normalizedPid) {
+            this._childProcesses.delete(normalizedPid);
+        }
     }
     // region: Loading Animations
     /**