agent-web-interface 4.0.0

package/dist/src/browser/session-manager.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Session Manager
+ *
+ * Manages Puppeteer browser lifecycle with a single shared BrowserContext.
+ * All pages share cookies/storage within the context.
+ */
+import { type Page } from 'puppeteer-core';
+import { type PageHandle } from './page-registry.js';
+import type { ConnectionHealth } from '../state/health.types.js';
+/** Type alias for Puppeteer Page (exported for downstream use) */
+export type { Page };
+/**
+ * Connection state machine states
+ */
+export type ConnectionState = 'idle' | 'connecting' | 'connected' | 'disconnecting' | 'failed';
+/**
+ * Event emitted on connection state changes
+ */
+export interface ConnectionStateChangeEvent {
+    previousState: ConnectionState;
+    currentState: ConnectionState;
+    timestamp: Date;
+}
+/**
+ * Storage state for cookies and localStorage.
+ * Puppeteer doesn't have a built-in storageState type like Playwright.
+ */
+export interface StorageState {
+    cookies: {
+        name: string;
+        value: string;
+        domain: string;
+        path: string;
+        expires: number;
+        httpOnly: boolean;
+        secure: boolean;
+        sameSite?: 'Strict' | 'Lax' | 'None';
+    }[];
+    origins: {
+        origin: string;
+        localStorage: {
+            name: string;
+            value: string;
+        }[];
+    }[];
+}
+/**
+ * Options for launching a new browser
+ */
+export interface LaunchOptions {
+    /** Run browser in headless mode (default: false) */
+    headless?: boolean;
+    /** Viewport dimensions */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Chrome channel to use */
+    channel?: 'chrome' | 'chrome-canary' | 'chrome-beta' | 'chrome-dev';
+    /** Path to Chrome executable (overrides channel) */
+    executablePath?: string;
+    /** Use isolated temp profile instead of persistent (default: false) */
+    isolated?: boolean;
+    /** Directory for persistent browser profile (user data dir) */
+    userDataDir?: string;
+    /** Additional Chrome command-line arguments */
+    args?: string[];
+    /** Use pipe transport instead of WebSocket (default: true, more secure) */
+    pipe?: boolean;
+}
+/**
+ * Extract a meaningful error message from any thrown value.
+ * Exported for testing.
+ */
+export declare function extractErrorMessage(error: unknown): string;
+/**
+ * Options for connecting to an existing browser via CDP
+ */
+export interface ConnectOptions {
+    /** WebSocket endpoint URL (e.g., ws://localhost:9222/devtools/browser/...) */
+    browserWSEndpoint?: string;
+    /** HTTP endpoint URL for Puppeteer to discover WebSocket (e.g., http://localhost:9222) */
+    browserURL?: string;
+    /** CDP endpoint URL (legacy, converted to browserURL) */
+    endpointUrl?: string;
+    /** CDP host (default: 127.0.0.1) - used if no endpoint provided */
+    host?: string;
+    /** CDP port (default: 9223) - used if no endpoint provided */
+    port?: number;
+    /** Connection timeout in ms (default: 30000) */
+    timeout?: number;
+    /**
+     * Auto-connect to Chrome 144+ with UI-based remote debugging enabled.
+     * Reads DevToolsActivePort file from Chrome's user data directory.
+     * Requires user to enable remote debugging at chrome://inspect/#remote-debugging
+     */
+    autoConnect?: boolean;
+    /** Chrome user data directory for autoConnect (default: ~/.config/google-chrome on Linux) */
+    userDataDir?: string;
+}
+/**
+ * Manages browser lifecycle and page creation.
+ *
+ * Supports two modes:
+ * - launch(): Start a new browser instance
+ * - connect(): Connect to an existing browser via CDP
+ */
+export declare class SessionManager {
+    private browser;
+    private context;
+    private readonly registry;
+    private readonly logger;
+    private isExternalBrowser;
+    /** Connection state machine */
+    private _connectionState;
+    /** State change listeners */
+    private readonly stateChangeListeners;
+    /** Browser disconnect handler reference for cleanup */
+    private browserDisconnectHandler;
+    constructor();
+    /**
+     * Get current connection state
+     */
+    get connectionState(): ConnectionState;
+    /**
+     * Transition to a new connection state
+     */
+    private transitionTo;
+    /**
+     * Subscribe to connection state changes
+     */
+    onStateChange(listener: (event: ConnectionStateChangeEvent) => void): () => void;
+    /**
+     * Launch a new browser with optional configuration.
+     *
+     * @param options - Browser launch options
+     * @throws BrowserSessionError if browser is already running or connection in progress
+     */
+    launch(options?: LaunchOptions): Promise<void>;
+    /**
+     * 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 });
+     * ```
+     */
+    connect(options?: ConnectOptions): Promise<void>;
+    /**
+     * Get the number of pages in the browser context.
+     *
+     * @returns Number of pages, or 0 if browser not running
+     */
+    getPageCount(): Promise<number>;
+    /**
+     * 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
+     */
+    adoptPage(index?: number): Promise<PageHandle>;
+    /**
+     * 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
+     */
+    createPage(url?: string): Promise<PageHandle>;
+    /**
+     * Get a page handle by its ID
+     *
+     * @param page_id - The page identifier
+     * @returns PageHandle if found, undefined otherwise
+     */
+    getPage(page_id: string): PageHandle | undefined;
+    /**
+     * 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: string): void;
+    /**
+     * 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?: string): PageHandle | undefined;
+    /**
+     * 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
+     */
+    resolvePageOrCreate(page_id?: string): Promise<PageHandle>;
+    /**
+     * Close a page and its CDP session
+     *
+     * @param page_id - The page identifier
+     * @returns true if page was closed, false if not found
+     */
+    closePage(page_id: string): Promise<boolean>;
+    /**
+     * 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
+     */
+    navigateTo(page_id: string, url: string): Promise<void>;
+    /**
+     * Shutdown the browser session.
+     *
+     * For launched browsers: closes all pages, context, and browser.
+     * For connected browsers: disconnects but does NOT close the browser.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Check if browser is running
+     *
+     * @returns true if browser is active
+     */
+    isRunning(): boolean;
+    /**
+     * 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
+     */
+    getConnectionHealth(): Promise<ConnectionHealth>;
+    /**
+     * 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
+     */
+    rebindCdpSession(page_id: string): Promise<PageHandle>;
+    /**
+     * 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
+     */
+    saveStorageState(savePath?: string): Promise<StorageState>;
+    /**
+     * 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)
+     */
+    syncPages(): Promise<PageHandle[]>;
+    /**
+     * List all active pages
+     *
+     * @returns Array of PageHandle objects
+     */
+    listPages(): PageHandle[];
+    /**
+     * Get the page count
+     *
+     * @returns Number of active pages
+     */
+    pageCount(): number;
+    /**
+     * Setup browser event listeners for disconnect detection.
+     * Called after successful browser launch or connect.
+     */
+    private setupBrowserListeners;
+    /**
+     * Remove browser event listeners.
+     * Called during shutdown to prevent duplicate handling.
+     */
+    private removeBrowserListeners;
+    /**
+     * Setup tracking infrastructure for a page.
+     * Injects observation accumulator and attaches network tracker.
+     */
+    private setupPageTracking;
+}
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/src/browser/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../../src/browser/session-manager.ts"],"names":[],"mappings":"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"}