agent-web-interface 4.0.0

package/dist/src/browser/session-manager.js

@@ -0,0 +1,964 @@
+/**
+ * Session Manager
+ *
+ * Manages Puppeteer browser lifecycle with a single shared BrowserContext.
+ * All pages share cookies/storage within the context.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import puppeteer, { TargetType, } from 'puppeteer-core';
+import { PuppeteerCdpClient } from '../cdp/puppeteer-cdp-client.js';
+import { PageRegistry } from './page-registry.js';
+import { getLogger } from '../shared/services/logging.service.js';
+import { BrowserSessionError } from '../shared/errors/browser-session.error.js';
+import { observationAccumulator } from '../observation/index.js';
+import { waitForNetworkQuiet, NAVIGATION_NETWORK_IDLE_TIMEOUT_MS } from './page-stabilization.js';
+import { getOrCreateTracker, removeTracker } from './page-network-tracker.js';
+/** Default user data directory for persistent browser profiles */
+const DEFAULT_USER_DATA_DIR = path.join(os.homedir(), '.cache', 'agent-web-interface', 'chrome-profile');
+/**
+ * Extract a meaningful error message from any thrown value.
+ * Exported for testing.
+ */
+export function extractErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message || error.name || 'Unknown Error';
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error && typeof error === 'object') {
+        // Check common error-like properties
+        const obj = error;
+        if (typeof obj.message === 'string')
+            return obj.message;
+        if (typeof obj.error === 'string')
+            return obj.error;
+        if (typeof obj.reason === 'string')
+            return obj.reason;
+        // Try to stringify, but handle circular refs
+        try {
+            const str = JSON.stringify(error);
+            return str !== '{}' ? str : `Unknown error object: ${Object.keys(obj).join(', ') || 'empty'}`;
+        }
+        catch {
+            return `Non-serializable error: ${Object.prototype.toString.call(error)}`;
+        }
+    }
+    return String(error);
+}
+/** Default CDP port for browser automation */
+const DEFAULT_CDP_PORT = 9223;
+/** Default CDP host */
+const DEFAULT_CDP_HOST = '127.0.0.1';
+/** Default connection timeout in ms (30s to handle slow networks and remote browsers) */
+const DEFAULT_CONNECTION_TIMEOUT = 30000;
+/**
+ * Get the default Chrome user data directory for the current platform
+ */
+function getDefaultChromeUserDataDir() {
+    const platform = os.platform();
+    const home = os.homedir();
+    switch (platform) {
+        case 'darwin':
+            return path.join(home, 'Library', 'Application Support', 'Google', 'Chrome');
+        case 'win32':
+            return path.join(home, 'AppData', 'Local', 'Google', 'Chrome', 'User Data');
+        default: // linux
+            return path.join(home, '.config', 'google-chrome');
+    }
+}
+/**
+ * Read the DevToolsActivePort file from Chrome's user data directory.
+ * Chrome 144+ writes this file when remote debugging is enabled via chrome://inspect/#remote-debugging
+ *
+ * @param userDataDir - Chrome user data directory
+ * @returns WebSocket URL for CDP connection
+ * @throws Error if file not found or invalid
+ */
+async function readDevToolsActivePort(userDataDir) {
+    const portFilePath = path.join(userDataDir, 'DevToolsActivePort');
+    try {
+        const content = await fs.promises.readFile(portFilePath, 'utf8');
+        const lines = content
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean);
+        if (lines.length < 2) {
+            throw new Error(`Invalid DevToolsActivePort content: ${content}`);
+        }
+        const [rawPort, wsPath] = lines;
+        const port = parseInt(rawPort, 10);
+        if (isNaN(port) || port < 1 || port > 65535) {
+            throw new Error(`Invalid port in DevToolsActivePort: ${rawPort}`);
+        }
+        return `ws://127.0.0.1:${port}${wsPath}`;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`DevToolsActivePort file not found at ${portFilePath}. ` +
+                'Make sure Chrome is running and remote debugging is enabled at chrome://inspect/#remote-debugging');
+        }
+        throw error;
+    }
+}
+/**
+ * Validates that a URL is a valid HTTP/HTTPS endpoint URL.
+ *
+ * @param urlString - URL string to validate
+ * @returns true if valid http(s) URL
+ */
+function isValidHttpUrl(urlString) {
+    try {
+        const url = new URL(urlString);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validates that a URL is a valid WebSocket endpoint URL.
+ *
+ * @param urlString - URL string to validate
+ * @returns true if valid ws(s) URL
+ */
+function isValidWsUrl(urlString) {
+    try {
+        const url = new URL(urlString);
+        return url.protocol === 'ws:' || url.protocol === 'wss:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Manages browser lifecycle and page creation.
+ *
+ * Supports two modes:
+ * - launch(): Start a new browser instance
+ * - connect(): Connect to an existing browser via CDP
+ */
+export class SessionManager {
+    browser = null;
+    context = null;
+    registry;
+    logger = getLogger();
+    isExternalBrowser = false;
+    /** Connection state machine */
+    _connectionState = 'idle';
+    /** State change listeners */
+    stateChangeListeners = new Set();
+    /** Browser disconnect handler reference for cleanup */
+    browserDisconnectHandler = null;
+    constructor() {
+        this.registry = new PageRegistry();
+    }
+    /**
+     * Get current connection state
+     */
+    get connectionState() {
+        return this._connectionState;
+    }
+    /**
+     * Transition to a new connection state
+     */
+    transitionTo(newState) {
+        const previousState = this._connectionState;
+        if (previousState === newState)
+            return;
+        this._connectionState = newState;
+        this.logger.debug('Connection state changed', { previousState, currentState: newState });
+        // Notify listeners
+        const event = {
+            previousState,
+            currentState: newState,
+            timestamp: new Date(),
+        };
+        for (const listener of this.stateChangeListeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                this.logger.error('State change listener error', error instanceof Error ? error : undefined);
+            }
+        }
+    }
+    /**
+     * Subscribe to connection state changes
+     */
+    onStateChange(listener) {
+        this.stateChangeListeners.add(listener);
+        return () => this.stateChangeListeners.delete(listener);
+    }
+    /**
+     * Launch a new browser with optional configuration.
+     *
+     * @param options - Browser launch options
+     * @throws BrowserSessionError if browser is already running or connection in progress
+     */
+    async launch(options = {}) {
+        if (this._connectionState !== 'idle' && this._connectionState !== 'failed') {
+            throw BrowserSessionError.invalidState(this._connectionState, 'launch');
+        }
+        this.transitionTo('connecting');
+        const { headless = true, viewport, channel = 'chrome', executablePath, isolated = false, userDataDir, args = [], pipe = true, } = options;
+        // Determine profile directory
+        let profileDir;
+        if (!isolated) {
+            profileDir = userDataDir ?? DEFAULT_USER_DATA_DIR;
+            await fs.promises.mkdir(profileDir, { recursive: true });
+        }
+        this.logger.info('Launching browser', {
+            headless,
+            viewport,
+            channel,
+            isolated,
+            hasPersistentProfile: !!profileDir,
+        });
+        let browser = null;
+        try {
+            // Build Chrome args
+            const chromeArgs = [
+                '--hide-crash-restore-bubble',
+                '--disable-background-timer-throttling',
+                '--disable-backgrounding-occluded-windows',
+                ...args,
+            ];
+            browser = await puppeteer.launch({
+                channel: executablePath ? undefined : channel,
+                executablePath,
+                headless,
+                userDataDir: profileDir,
+                defaultViewport: viewport ?? null,
+                pipe,
+                args: chromeArgs,
+            });
+            // Get the default context (first one)
+            this.context = browser.defaultBrowserContext();
+            this.browser = browser;
+            this.isExternalBrowser = false;
+            // Setup disconnect listener
+            this.setupBrowserListeners();
+            this.transitionTo('connected');
+            this.logger.info('Browser launched successfully');
+        }
+        catch (error) {
+            // Cleanup on failure - ignore close errors as browser may be in bad state
+            if (browser) {
+                await browser.close().catch(() => {
+                    /* Intentionally empty - cleanup is best-effort */
+                });
+            }
+            this.transitionTo('failed');
+            throw BrowserSessionError.connectionFailed(error instanceof Error ? error : new Error(extractErrorMessage(error)), { operation: 'launch' });
+        }
+    }
+    /**
+     * Connect to an existing browser via CDP.
+     *
+     * Use this to connect to any Chromium browser with remote debugging enabled.
+     *
+     * @param options - Connection options (browserWSEndpoint, browserURL, or autoConnect)
+     * @throws BrowserSessionError if browser is already running, connection in progress, or URL is invalid
+     *
+     * @example
+     * ```typescript
+     * // Connect to browser on default port
+     * await session.connect();
+     *
+     * // Connect to custom endpoint (HTTP - Puppeteer discovers WebSocket)
+     * await session.connect({ browserURL: 'http://localhost:9222' });
+     *
+     * // Connect via WebSocket directly
+     * await session.connect({ browserWSEndpoint: 'ws://localhost:9222/devtools/browser/...' });
+     *
+     * // Auto-connect to Chrome 144+ with UI-based remote debugging
+     * await session.connect({ autoConnect: true });
+     * ```
+     */
+    async connect(options = {}) {
+        if (this._connectionState !== 'idle' && this._connectionState !== 'failed') {
+            throw BrowserSessionError.invalidState(this._connectionState, 'connect');
+        }
+        const timeout = options.timeout ?? DEFAULT_CONNECTION_TIMEOUT;
+        let connectOptions;
+        let endpointForLogging;
+        // Determine connection method
+        if (options.autoConnect) {
+            // Chrome 144+ auto-connect via DevToolsActivePort
+            const userDataDir = options.userDataDir ?? getDefaultChromeUserDataDir();
+            try {
+                const wsEndpoint = await readDevToolsActivePort(userDataDir);
+                connectOptions = { browserWSEndpoint: wsEndpoint };
+                endpointForLogging = wsEndpoint;
+                this.logger.info('Auto-connect: found DevToolsActivePort', { userDataDir, wsEndpoint });
+            }
+            catch (error) {
+                throw BrowserSessionError.connectionFailed(error instanceof Error ? error : new Error(extractErrorMessage(error)), { operation: 'autoConnect', userDataDir });
+            }
+        }
+        else if (options.browserWSEndpoint) {
+            // Direct WebSocket connection
+            if (!isValidWsUrl(options.browserWSEndpoint)) {
+                throw BrowserSessionError.invalidUrl(options.browserWSEndpoint);
+            }
+            connectOptions = { browserWSEndpoint: options.browserWSEndpoint };
+            endpointForLogging = options.browserWSEndpoint;
+        }
+        else if (options.browserURL) {
+            // HTTP endpoint - Puppeteer discovers WebSocket
+            if (!isValidHttpUrl(options.browserURL)) {
+                throw BrowserSessionError.invalidUrl(options.browserURL);
+            }
+            connectOptions = { browserURL: options.browserURL };
+            endpointForLogging = options.browserURL;
+        }
+        else if (options.endpointUrl) {
+            // Legacy endpointUrl support - convert to appropriate option
+            if (isValidWsUrl(options.endpointUrl)) {
+                connectOptions = { browserWSEndpoint: options.endpointUrl };
+            }
+            else if (isValidHttpUrl(options.endpointUrl)) {
+                connectOptions = { browserURL: options.endpointUrl };
+            }
+            else {
+                throw BrowserSessionError.invalidUrl(options.endpointUrl);
+            }
+            endpointForLogging = options.endpointUrl;
+        }
+        else {
+            // Default: construct HTTP URL from host/port
+            const host = options.host ?? process.env.CEF_BRIDGE_HOST ?? DEFAULT_CDP_HOST;
+            const port = options.port ?? Number(process.env.CEF_BRIDGE_PORT ?? DEFAULT_CDP_PORT);
+            const browserURL = `http://${host}:${port}`;
+            connectOptions = { browserURL };
+            endpointForLogging = browserURL;
+        }
+        this.transitionTo('connecting');
+        this.logger.info('Connecting to browser via CDP', { endpoint: endpointForLogging, timeout });
+        let browser = null;
+        let timeoutId;
+        try {
+            // Connect with timeout
+            // targetFilter excludes chrome extension targets (service workers, background
+            // pages, extension tabs) that cause Puppeteer's ChromeTargetManager to hang
+            // during initialization. Chrome 144's UI-based remote debugging exposes
+            // extension targets in non-default browser contexts; Puppeteer's
+            // Target.setAutoAttach fails for those sessions (-32001), leaving them stuck
+            // in #targetIdsForInit so connect() never resolves.
+            // See: https://github.com/puppeteer/puppeteer/issues/11627
+            const connectionPromise = puppeteer.connect({
+                ...connectOptions,
+                defaultViewport: null,
+                targetFilter: (target) => {
+                    if (target.url().startsWith('chrome-extension://'))
+                        return false;
+                    if (target.type() === TargetType.SERVICE_WORKER)
+                        return false;
+                    if (target.type() === TargetType.BACKGROUND_PAGE)
+                        return false;
+                    return true;
+                },
+            });
+            const timeoutPromise = new Promise((_, reject) => {
+                timeoutId = setTimeout(() => {
+                    reject(BrowserSessionError.connectionTimeout(endpointForLogging, timeout));
+                }, timeout);
+            });
+            browser = await Promise.race([connectionPromise, timeoutPromise]);
+            // Get the default context (existing browser's context)
+            const contexts = browser.browserContexts();
+            if (contexts.length > 0) {
+                this.context = contexts[0];
+            }
+            else {
+                // If no context exists, use default (shouldn't normally happen)
+                this.context = browser.defaultBrowserContext();
+            }
+            this.browser = browser;
+            this.isExternalBrowser = true;
+            // Setup disconnect listener
+            this.setupBrowserListeners();
+            // Get page count for logging
+            const pages = await this.context.pages();
+            this.transitionTo('connected');
+            this.logger.info('Connected to browser successfully', {
+                contexts: contexts.length,
+                pages: pages.length,
+            });
+        }
+        catch (error) {
+            // Cleanup on failure - for external browsers, disconnect instead of close
+            if (browser) {
+                await browser.disconnect().catch(() => {
+                    /* Intentionally empty - cleanup is best-effort */
+                });
+            }
+            this.transitionTo('failed');
+            this.logger.error('Failed to connect', error instanceof Error ? error : undefined, {
+                endpoint: endpointForLogging,
+            });
+            // Re-throw BrowserSessionError as-is, wrap others
+            if (BrowserSessionError.isBrowserSessionError(error)) {
+                throw error;
+            }
+            throw BrowserSessionError.connectionFailed(error instanceof Error ? error : new Error(extractErrorMessage(error)), { endpointUrl: endpointForLogging });
+        }
+        finally {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    /**
+     * Get the number of pages in the browser context.
+     *
+     * @returns Number of pages, or 0 if browser not running
+     */
+    async getPageCount() {
+        if (!this.context) {
+            return 0;
+        }
+        const pages = await this.context.pages();
+        return pages.length;
+    }
+    /**
+     * Adopt an existing page from the connected browser.
+     *
+     * When connecting to an external browser, use this to
+     * register existing pages instead of creating new ones.
+     *
+     * This method is idempotent - calling it twice on the same page
+     * returns the existing handle without creating a new CDP session.
+     *
+     * @param index - Page index (default: 0 for first/active page)
+     * @returns PageHandle for the adopted page
+     * @throws Error if browser not connected or page index invalid
+     */
+    async adoptPage(index = 0) {
+        if (!this.context) {
+            throw new Error('Browser not running');
+        }
+        const pages = await this.context.pages();
+        if (index < 0 || index >= pages.length) {
+            throw new Error(`Invalid page index: ${index}. Browser has ${pages.length} pages.`);
+        }
+        const page = pages[index];
+        // Check if already adopted (idempotent behavior)
+        const existing = this.registry.findByPage(page);
+        if (existing) {
+            this.logger.debug('Page already adopted', { page_id: existing.page_id });
+            return existing;
+        }
+        const cdpSession = await page.createCDPSession();
+        const cdpClient = new PuppeteerCdpClient(cdpSession);
+        const handle = this.registry.register(page, cdpClient);
+        this.registry.updateMetadata(handle.page_id, { url: page.url() });
+        await this.setupPageTracking(page);
+        this.logger.debug('Adopted page', { page_id: handle.page_id, url: page.url() });
+        return handle;
+    }
+    /**
+     * Create a new page, optionally navigating to a URL
+     *
+     * @param url - Optional URL to navigate to
+     * @returns PageHandle for the new page
+     * @throws Error if browser not running
+     */
+    async createPage(url) {
+        if (!this.context) {
+            throw new Error('Browser not running');
+        }
+        const page = await this.context.newPage();
+        const cdpSession = await page.createCDPSession();
+        const cdpClient = new PuppeteerCdpClient(cdpSession);
+        const handle = this.registry.register(page, cdpClient);
+        this.logger.debug('Created page', { page_id: handle.page_id });
+        if (url) {
+            await page.goto(url, { waitUntil: 'domcontentloaded' });
+            this.registry.updateMetadata(handle.page_id, { url: page.url() });
+        }
+        await this.setupPageTracking(page);
+        return handle;
+    }
+    /**
+     * Get a page handle by its ID
+     *
+     * @param page_id - The page identifier
+     * @returns PageHandle if found, undefined otherwise
+     */
+    getPage(page_id) {
+        return this.registry.get(page_id);
+    }
+    /**
+     * Touch a page to mark it as most recently used.
+     *
+     * Call this on page access to update MRU tracking.
+     *
+     * @param page_id - The page identifier
+     */
+    touchPage(page_id) {
+        this.registry.touch(page_id);
+    }
+    /**
+     * Resolve page_id to a PageHandle.
+     *
+     * If page_id is provided, returns the specified page.
+     * If page_id is omitted, returns the most recently used page.
+     * Does NOT auto-create pages.
+     *
+     * @param page_id - Optional page identifier
+     * @returns PageHandle if found, undefined otherwise
+     */
+    resolvePage(page_id) {
+        if (page_id) {
+            return this.getPage(page_id);
+        }
+        return this.registry.getMostRecent();
+    }
+    /**
+     * Resolve page_id to a PageHandle, creating a new page if needed.
+     *
+     * If page_id is provided, returns the specified page (throws if not found).
+     * If page_id is omitted, returns the most recently used page or creates one.
+     *
+     * @param page_id - Optional page identifier
+     * @returns PageHandle for the resolved or created page
+     * @throws Error if page_id is provided but not found, or if browser not running
+     */
+    async resolvePageOrCreate(page_id) {
+        if (page_id) {
+            const handle = this.getPage(page_id);
+            if (!handle) {
+                throw new Error(`Page not found: ${page_id}`);
+            }
+            return handle;
+        }
+        return this.registry.getMostRecent() ?? (await this.createPage());
+    }
+    /**
+     * Close a page and its CDP session
+     *
+     * @param page_id - The page identifier
+     * @returns true if page was closed, false if not found
+     */
+    async closePage(page_id) {
+        const handle = this.registry.get(page_id);
+        if (!handle) {
+            return false;
+        }
+        // Cleanup network tracker before closing
+        removeTracker(handle.page);
+        try {
+            // Close CDP session first
+            await handle.cdp.close();
+        }
+        catch (error) {
+            this.logger.debug('Error closing CDP session', {
+                page_id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        try {
+            // Close the page
+            await handle.page.close();
+        }
+        catch (error) {
+            this.logger.debug('Error closing page', {
+                page_id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        // Remove from registry
+        this.registry.remove(page_id);
+        this.logger.debug('Closed page', { page_id });
+        return true;
+    }
+    /**
+     * Navigate a page to a URL
+     *
+     * Waits for both DOM ready and network idle to ensure the page is fully loaded.
+     * Network idle timeout is generous (5s) but never throws - pages with persistent
+     * connections (websockets, long-polling, analytics) may never reach idle.
+     *
+     * @param page_id - The page identifier
+     * @param url - URL to navigate to
+     * @throws Error if page not found or navigation fails
+     */
+    async navigateTo(page_id, url) {
+        const handle = this.registry.get(page_id);
+        if (!handle) {
+            throw new Error('Page not found');
+        }
+        try {
+            // Wait for DOM ready first (fast baseline)
+            await handle.page.goto(url, { waitUntil: 'domcontentloaded' });
+            // Mark navigation on tracker (bumps generation to ignore stale events)
+            const tracker = getOrCreateTracker(handle.page);
+            tracker.markNavigation();
+            // Then wait for network to settle (catches API calls)
+            const networkIdle = await waitForNetworkQuiet(handle.page, NAVIGATION_NETWORK_IDLE_TIMEOUT_MS);
+            if (!networkIdle) {
+                this.logger.debug('Network did not reach idle state', { page_id, url });
+            }
+            this.registry.updateMetadata(page_id, {
+                url: handle.page.url(),
+            });
+            // Re-inject observation accumulator (new document context)
+            await observationAccumulator.inject(handle.page);
+            this.logger.debug('Navigated page', { page_id, url });
+        }
+        catch (error) {
+            this.logger.error('Navigation failed', error instanceof Error ? error : undefined, {
+                page_id,
+                url,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Shutdown the browser session.
+     *
+     * For launched browsers: closes all pages, context, and browser.
+     * For connected browsers: disconnects but does NOT close the browser.
+     */
+    async shutdown() {
+        // Check if there's anything to shut down
+        if (!this.browser || this._connectionState === 'disconnecting') {
+            return;
+        }
+        this.transitionTo('disconnecting');
+        this.logger.info('Shutting down browser session', {
+            isExternalBrowser: this.isExternalBrowser,
+        });
+        // Remove browser disconnect listener to prevent duplicate handling
+        this.removeBrowserListeners();
+        // Close/detach all CDP sessions
+        const pages = this.registry.list();
+        for (const page of pages) {
+            try {
+                await page.cdp.close();
+            }
+            catch (err) {
+                // CDP session may already be closed
+                this.logger.debug('CDP session close failed during shutdown', {
+                    page_id: page.page_id,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        if (this.isExternalBrowser) {
+            // For external browser: just disconnect, don't close pages or browser
+            if (this.browser) {
+                // disconnect() is synchronous in Puppeteer
+                void this.browser.disconnect();
+            }
+            this.logger.info('Disconnected from external browser (not closing it)');
+        }
+        else {
+            // For launched browser: close everything
+            for (const page of pages) {
+                try {
+                    await page.page.close();
+                }
+                catch (err) {
+                    // Page may already be closed
+                    this.logger.debug('Page close failed during shutdown', {
+                        page_id: page.page_id,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            // Close browser (this closes all pages and contexts)
+            if (this.browser) {
+                try {
+                    await this.browser.close();
+                }
+                catch (err) {
+                    // Browser may already be closed
+                    this.logger.debug('Browser close failed during shutdown', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        }
+        this.browser = null;
+        this.context = null;
+        this.isExternalBrowser = false;
+        this.registry.clear();
+        this.transitionTo('idle');
+        this.logger.info('Browser session shutdown complete');
+    }
+    /**
+     * Check if browser is running
+     *
+     * @returns true if browser is active
+     */
+    isRunning() {
+        return this.browser?.connected ?? false;
+    }
+    /**
+     * Get connection health status.
+     *
+     * Goes beyond binary connected/not-connected to detect degraded CDP sessions:
+     * - 'healthy': Browser connected, all CDP sessions operational
+     * - 'degraded': Browser connected, but some CDP sessions dead (recoverable)
+     * - 'failed': Browser disconnected
+     *
+     * @returns Connection health status
+     */
+    async getConnectionHealth() {
+        if (this._connectionState !== 'connected' || !this.context) {
+            return 'failed';
+        }
+        const pages = this.registry.list();
+        if (pages.length === 0) {
+            return 'healthy';
+        }
+        const results = await Promise.all(pages.map(async (pageHandle) => {
+            // Check if page is closed using Puppeteer's isClosed() method
+            if (pageHandle.page.isClosed()) {
+                return false;
+            }
+            if (!pageHandle.cdp.isActive()) {
+                return false;
+            }
+            try {
+                await pageHandle.cdp.send('Page.getFrameTree', undefined);
+                return true;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                this.logger.warning('CDP probe failed', { page_id: pageHandle.page_id, error: message });
+                return false;
+            }
+        }));
+        return results.every(Boolean) ? 'healthy' : 'degraded';
+    }
+    /**
+     * Rebind CDP session for a page.
+     *
+     * Use when CDP session is dead but page is still valid.
+     * This creates a new CDP session and updates the registry.
+     *
+     * @param page_id - Page ID to rebind
+     * @returns New PageHandle with fresh CDP session
+     * @throws Error if page not found, page is closed, or browser context unavailable
+     */
+    async rebindCdpSession(page_id) {
+        const handle = this.registry.get(page_id);
+        if (!handle) {
+            throw new Error(`Page not found: ${page_id}`);
+        }
+        // Check if page is still accessible
+        if (handle.page.isClosed()) {
+            throw new Error(`Page is closed: ${page_id}`);
+        }
+        if (!this.context) {
+            throw new Error('Browser context not available');
+        }
+        // Close old CDP session (best effort)
+        try {
+            await handle.cdp.close();
+        }
+        catch (err) {
+            // May already be closed
+            this.logger.debug('Old CDP session close failed during rebind', {
+                page_id,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        // Create new CDP session (Puppeteer creates CDP from page, not context)
+        const cdpSession = await handle.page.createCDPSession();
+        const newCdp = new PuppeteerCdpClient(cdpSession);
+        // Update registry with new handle
+        const newHandle = {
+            ...handle,
+            cdp: newCdp,
+        };
+        this.registry.replace(page_id, newHandle);
+        this.logger.info('Rebound CDP session', { page_id });
+        return newHandle;
+    }
+    /**
+     * Save the current storage state (cookies, localStorage).
+     *
+     * Note: Puppeteer doesn't have built-in storageState like Playwright.
+     * This method collects cookies and localStorage manually.
+     *
+     * @param savePath - Optional file path to save state to. If not provided, returns the state object.
+     * @returns The storage state object
+     * @throws Error if browser not running
+     */
+    async saveStorageState(savePath) {
+        if (!this.context) {
+            throw new Error('Browser not running');
+        }
+        // Get cookies from all pages
+        const pages = await this.context.pages();
+        const allCookies = await Promise.all(pages.map((page) => page.cookies()));
+        const cookieSet = new Map();
+        // Deduplicate cookies by name+domain+path
+        for (const pageCookies of allCookies) {
+            for (const cookie of pageCookies) {
+                const key = `${cookie.name}|${cookie.domain}|${cookie.path}`;
+                cookieSet.set(key, {
+                    name: cookie.name,
+                    value: cookie.value,
+                    domain: cookie.domain,
+                    path: cookie.path,
+                    expires: cookie.expires,
+                    httpOnly: cookie.httpOnly ?? false,
+                    secure: cookie.secure ?? false,
+                    sameSite: (cookie.sameSite ?? undefined),
+                });
+            }
+        }
+        // Get localStorage from each origin
+        const originsMap = new Map();
+        for (const page of pages) {
+            try {
+                const url = page.url();
+                if (!url || url === 'about:blank')
+                    continue;
+                const origin = new URL(url).origin;
+                /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment */
+                const localStorage = await page.evaluate(() => {
+                    const storage = globalThis.localStorage;
+                    const items = [];
+                    for (let i = 0; i < storage.length; i++) {
+                        const key = storage.key(i);
+                        if (key) {
+                            items.push({ name: key, value: storage.getItem(key) ?? '' });
+                        }
+                    }
+                    return items;
+                });
+                /* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment */
+                originsMap.set(origin, localStorage);
+            }
+            catch (err) {
+                // Page may not be accessible
+                this.logger.debug('Failed to extract localStorage during storage state save', {
+                    url: page.url(),
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        const state = {
+            cookies: Array.from(cookieSet.values()),
+            origins: Array.from(originsMap.entries()).map(([origin, localStorage]) => ({
+                origin,
+                localStorage,
+            })),
+        };
+        if (savePath) {
+            await fs.promises.writeFile(savePath, JSON.stringify(state, null, 2));
+        }
+        return state;
+    }
+    /**
+     * Sync registry with actual browser pages.
+     *
+     * Adopts any browser pages not yet registered. This ensures the registry
+     * reflects the true state of the browser, especially after reconnection
+     * or when external tabs are opened.
+     *
+     * Note: This method does NOT remove stale/closed pages from the registry.
+     * Failed adoptions (e.g., CDP session errors) are logged as warnings but do not throw.
+     * Successfully synced pages have network tracking set up.
+     *
+     * @returns Array of all PageHandle objects after sync (includes previously registered pages)
+     */
+    async syncPages() {
+        if (!this.context) {
+            return this.registry.list();
+        }
+        const browserPages = await this.context.pages();
+        for (const page of browserPages) {
+            // Skip if already registered
+            if (this.registry.findByPage(page)) {
+                continue;
+            }
+            // Skip closed pages
+            if (page.isClosed()) {
+                continue;
+            }
+            // Adopt the unregistered page
+            try {
+                const cdpSession = await page.createCDPSession();
+                const cdpClient = new PuppeteerCdpClient(cdpSession);
+                const handle = this.registry.register(page, cdpClient);
+                this.registry.updateMetadata(handle.page_id, { url: page.url() });
+                await this.setupPageTracking(page);
+                this.logger.debug('Synced unregistered page', { page_id: handle.page_id, url: page.url() });
+            }
+            catch (err) {
+                this.logger.warning('Failed to sync page', {
+                    url: page.url(),
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return this.registry.list();
+    }
+    /**
+     * List all active pages
+     *
+     * @returns Array of PageHandle objects
+     */
+    listPages() {
+        return this.registry.list();
+    }
+    /**
+     * Get the page count
+     *
+     * @returns Number of active pages
+     */
+    pageCount() {
+        return this.registry.size();
+    }
+    /**
+     * Setup browser event listeners for disconnect detection.
+     * Called after successful browser launch or connect.
+     */
+    setupBrowserListeners() {
+        if (!this.browser)
+            return;
+        // Store reference for cleanup
+        this.browserDisconnectHandler = () => {
+            // Only handle if we're in connected state (not during intentional shutdown)
+            if (this._connectionState === 'connected') {
+                this.logger.warning('Browser disconnected unexpectedly');
+                this.browser = null;
+                this.context = null;
+                this.registry.clear();
+                this.transitionTo('failed');
+            }
+        };
+        this.browser.on('disconnected', this.browserDisconnectHandler);
+    }
+    /**
+     * Remove browser event listeners.
+     * Called during shutdown to prevent duplicate handling.
+     */
+    removeBrowserListeners() {
+        if (this.browser && this.browserDisconnectHandler) {
+            this.browser.off('disconnected', this.browserDisconnectHandler);
+            this.browserDisconnectHandler = null;
+        }
+    }
+    /**
+     * Setup tracking infrastructure for a page.
+     * Injects observation accumulator and attaches network tracker.
+     */
+    async setupPageTracking(page) {
+        await observationAccumulator.inject(page);
+        const tracker = getOrCreateTracker(page);
+        tracker.attach(page);
+        page.on('close', () => removeTracker(page));
+    }
+}
+//# sourceMappingURL=session-manager.js.map