agent-web-interface 4.3.0 → 4.5.0

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

@@ -0,0 +1,33 @@
+/**
+ * Browser Session Config
+ *
+ * Defines the browser configuration that agents can specify per session.
+ * Each session can independently choose to launch a new browser or connect
+ * to an existing one, with its own headless/headed preference.
+ *
+ * Env var AWI_CDP_URL overrides to connect to an existing CDP endpoint.
+ *
+ * @module browser/browser-session-config
+ */
+/**
+ * Per-session browser configuration.
+ *
+ * Agents pass browser preferences via the `navigate` tool's optional parameters.
+ * If not provided, sensible defaults are used (launch, headed, persistent profile).
+ */
+export interface BrowserSessionConfig {
+    /** Run browser in headless mode. Default: false */
+    headless?: boolean;
+    /** Use an isolated temp profile instead of persistent. Default: false */
+    isolated?: boolean;
+    /** Auto-connect to Chrome 144+ via DevToolsActivePort */
+    autoConnect?: boolean;
+}
+/**
+ * Returns sensible default browser configuration.
+ *
+ * Launch a headed Chrome with a persistent profile — the most common
+ * configuration for interactive browser automation.
+ */
+export declare function defaultBrowserConfig(): BrowserSessionConfig;
+//# sourceMappingURL=browser-session-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"browser-session-config.d.ts","sourceRoot":"","sources":["../../../src/browser/browser-session-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,yDAAyD;IACzD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,oBAAoB,CAK3D"}

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

@@ -0,0 +1,24 @@
+/**
+ * Browser Session Config
+ *
+ * Defines the browser configuration that agents can specify per session.
+ * Each session can independently choose to launch a new browser or connect
+ * to an existing one, with its own headless/headed preference.
+ *
+ * Env var AWI_CDP_URL overrides to connect to an existing CDP endpoint.
+ *
+ * @module browser/browser-session-config
+ */
+/**
+ * Returns sensible default browser configuration.
+ *
+ * Launch a headed Chrome with a persistent profile — the most common
+ * configuration for interactive browser automation.
+ */
+export function defaultBrowserConfig() {
+    return {
+        headless: false,
+        isolated: false,
+    };
+}
+//# sourceMappingURL=browser-session-config.js.map

package/dist/src/browser/browser-session-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-session-config.js","sourceRoot":"","sources":["../../../src/browser/browser-session-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAmBH;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,QAAQ,EAAE,KAAK;QACf,QAAQ,EAAE,KAAK;KAChB,CAAC;AACJ,CAAC"}

package/dist/src/browser/connection-utils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Connection Utilities
+ *
+ * Utility functions for browser connection management:
+ * - Error message extraction
+ * - URL validation
+ * - Chrome DevTools port discovery
+ * - CDP connection constants
+ */
+/** Default CDP port for browser automation */
+export declare const DEFAULT_CDP_PORT = 9223;
+/** Default CDP host */
+export declare const DEFAULT_CDP_HOST = "127.0.0.1";
+/** Default connection timeout in ms (30s to handle slow networks and remote browsers) */
+export declare const DEFAULT_CONNECTION_TIMEOUT = 30000;
+/**
+ * Extract a meaningful error message from any thrown value.
+ * Exported for testing.
+ */
+export declare function extractErrorMessage(error: unknown): string;
+/**
+ * Validates that a URL is a valid HTTP/HTTPS endpoint URL.
+ *
+ * @param urlString - URL string to validate
+ * @returns true if valid http(s) URL
+ */
+export declare function isValidHttpUrl(urlString: string): boolean;
+/**
+ * Validates that a URL is a valid WebSocket endpoint URL.
+ *
+ * @param urlString - URL string to validate
+ * @returns true if valid ws(s) URL
+ */
+export declare function isValidWsUrl(urlString: string): boolean;
+/**
+ * Get the default Chrome user data directory for the current platform
+ */
+export declare function getDefaultChromeUserDataDir(): string;
+/**
+ * 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
+ */
+export declare function readDevToolsActivePort(userDataDir: string): Promise<string>;
+//# sourceMappingURL=connection-utils.d.ts.map

package/dist/src/browser/connection-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-utils.d.ts","sourceRoot":"","sources":["../../../src/browser/connection-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,8CAA8C;AAC9C,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,uBAAuB;AACvB,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAC5C,yFAAyF;AACzF,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAsB1D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAOzD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAOvD;AAED;;GAEG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,CAYpD;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA+BjF"}

package/dist/src/browser/connection-utils.js

@@ -0,0 +1,129 @@
+/**
+ * Connection Utilities
+ *
+ * Utility functions for browser connection management:
+ * - Error message extraction
+ * - URL validation
+ * - Chrome DevTools port discovery
+ * - CDP connection constants
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** Default CDP port for browser automation */
+export const DEFAULT_CDP_PORT = 9223;
+/** Default CDP host */
+export const DEFAULT_CDP_HOST = '127.0.0.1';
+/** Default connection timeout in ms (30s to handle slow networks and remote browsers) */
+export const DEFAULT_CONNECTION_TIMEOUT = 30000;
+/**
+ * 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);
+}
+/**
+ * Validates that a URL is a valid HTTP/HTTPS endpoint URL.
+ *
+ * @param urlString - URL string to validate
+ * @returns true if valid http(s) URL
+ */
+export 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
+ */
+export function isValidWsUrl(urlString) {
+    try {
+        const url = new URL(urlString);
+        return url.protocol === 'ws:' || url.protocol === 'wss:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get the default Chrome user data directory for the current platform
+ */
+export 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
+ */
+export 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;
+    }
+}
+//# sourceMappingURL=connection-utils.js.map

package/dist/src/browser/connection-utils.js.map

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

package/dist/src/browser/ensure-browser.d.ts

@@ -2,38 +2,23 @@
  * Lazy Browser Initialization
  *
  * Ensures a browser is ready before tool execution.
- * If no browser is running, launches or connects based on CLI configuration.
+ * If no browser is running, launches or connects based on session configuration.
+ *
+ * When a persistent profile is in use and Chrome is already running (from a
+ * previous session or another agent), reconnects via DevToolsActivePort instead
+ * of failing on the profile lock.
+ *
+ * CDP endpoint can be set via AWI_CDP_URL env var (http or ws) to connect
+ * to an existing browser instead of launching.
  */
 import type { SessionManager } from './session-manager.js';
-/**
- * Options for lazy browser initialization.
- */
-export interface EnsureBrowserOptions {
-    /** Run browser in headless mode (default: false) */
-    headless?: boolean;
-    /** Use isolated temp profile (default: false) */
-    isolated?: boolean;
-    /** HTTP endpoint URL for connecting to existing browser */
-    browserUrl?: string;
-    /** WebSocket endpoint URL for connecting to existing browser */
-    wsEndpoint?: string;
-    /** Auto-connect to Chrome 144+ via DevToolsActivePort */
-    autoConnect?: boolean;
-    /** Chrome user data directory */
-    userDataDir?: string;
-    /** Chrome channel */
-    channel?: 'chrome' | 'chrome-canary' | 'chrome-beta' | 'chrome-dev';
-    /** Path to Chrome executable */
-    executablePath?: string;
-}
+import type { BrowserSessionConfig } from './browser-session-config.js';
 /**
  * Ensure browser is ready for tool execution.
  *
  * If browser is already running, returns immediately.
- * Otherwise, launches or connects based on provided options.
- *
- * @param session - SessionManager instance
- * @param options - Configuration options from CLI
+ * Otherwise, launches or connects based on provided config.
+ * Set AWI_CDP_URL env var to connect to an existing CDP endpoint.
  */
-export declare function ensureBrowserReady(session: SessionManager, options: EnsureBrowserOptions): Promise<void>;
+export declare function ensureBrowserReady(session: SessionManager, config: BrowserSessionConfig): Promise<void>;
 //# sourceMappingURL=ensure-browser.d.ts.map

package/dist/src/browser/ensure-browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ensure-browser.d.ts","sourceRoot":"","sources":["../../../src/browser/ensure-browser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAK3D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,yDAAyD;IACzD,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,qBAAqB;IACrB,OAAO,CAAC,EAAE,QAAQ,GAAG,eAAe,GAAG,aAAa,GAAG,YAAY,CAAC;IAEpE,gCAAgC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AASD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAwCf"}
+{"version":3,"file":"ensure-browser.d.ts","sourceRoot":"","sources":["../../../src/browser/ensure-browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AASxE;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CA6Df"}

package/dist/src/browser/ensure-browser.js

@@ -2,64 +2,131 @@
  * Lazy Browser Initialization
  *
  * Ensures a browser is ready before tool execution.
- * If no browser is running, launches or connects based on CLI configuration.
+ * If no browser is running, launches or connects based on session configuration.
+ *
+ * When a persistent profile is in use and Chrome is already running (from a
+ * previous session or another agent), reconnects via DevToolsActivePort instead
+ * of failing on the profile lock.
+ *
+ * CDP endpoint can be set via AWI_CDP_URL env var (http or ws) to connect
+ * to an existing browser instead of launching.
  */
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_USER_DATA_DIR } from './session-manager.js';
+import { extractErrorMessage } from './connection-utils.js';
 import { getLogger } from '../shared/services/logging.service.js';
 const logger = getLogger();
-/**
- * Determine if we should connect to an existing browser vs launch new one.
- */
-function shouldConnect(options) {
-    return !!(options.browserUrl ?? options.wsEndpoint ?? options.autoConnect);
-}
+/** Short timeout for reconnect attempts — these are fast pre-checks, not full connections */
+const RECONNECT_TIMEOUT_MS = 5000;
 /**
  * Ensure browser is ready for tool execution.
  *
  * If browser is already running, returns immediately.
- * Otherwise, launches or connects based on provided options.
- *
- * @param session - SessionManager instance
- * @param options - Configuration options from CLI
+ * Otherwise, launches or connects based on provided config.
+ * Set AWI_CDP_URL env var to connect to an existing CDP endpoint.
  */
-export async function ensureBrowserReady(session, options) {
-    // Fast path: browser already running
+export async function ensureBrowserReady(session, config) {
     if (session.isRunning()) {
         return;
     }
-    const mode = shouldConnect(options) ? 'connect' : 'launch';
-    logger.info('Lazy browser initialization triggered', { mode });
-    try {
-        if (shouldConnect(options)) {
-            // Connect to existing browser
+    const inFlightPromise = session.connectionPromise;
+    if (session.connectionState === 'connecting' && inFlightPromise) {
+        logger.info('Awaiting in-flight browser connection');
+        await inFlightPromise;
+        return;
+    }
+    // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string must be falsy
+    const cdpUrl = process.env.AWI_CDP_URL?.trim() || undefined;
+    const shouldConnect = !!(cdpUrl ?? config.autoConnect);
+    if (shouldConnect) {
+        logger.info('Lazy browser initialization triggered', { mode: 'connect' });
+        try {
             await session.connect({
-                browserURL: options.browserUrl,
-                browserWSEndpoint: options.wsEndpoint,
-                autoConnect: options.autoConnect,
-                userDataDir: options.userDataDir,
+                endpointUrl: cdpUrl,
+                autoConnect: config.autoConnect,
             });
+            logger.info('Browser initialized successfully', { mode: 'connect' });
         }
-        else {
-            // Launch new browser
-            await session.launch({
-                headless: options.headless ?? false,
-                isolated: options.isolated ?? false,
-                userDataDir: options.userDataDir,
-                channel: options.channel,
-                executablePath: options.executablePath,
+        catch (error) {
+            logger.error('Browser initialization failed', error instanceof Error ? error : undefined, {
+                mode: 'connect',
             });
+            throw error;
         }
-        logger.info('Browser initialized successfully', { mode });
+        return;
+    }
+    // Launch mode — try reconnecting to an existing browser first (persistent profiles only)
+    const profileDir = config.isolated ? undefined : DEFAULT_USER_DATA_DIR;
+    if (profileDir && (await hasPortFile(profileDir)) && (await tryReconnect(session, profileDir))) {
+        return;
+    }
+    // Launch a new browser
+    logger.info('Lazy browser initialization triggered', { mode: 'launch' });
+    try {
+        await session.launch({
+            headless: config.headless ?? false,
+            isolated: config.isolated ?? false,
+        });
+        logger.info('Browser initialized successfully', { mode: 'launch' });
     }
     catch (error) {
+        // Another process may have grabbed the profile between our reconnect attempt
+        // and launch (race condition). Try reconnecting one more time.
+        if (profileDir && isProfileLockError(error) && (await tryReconnect(session, profileDir))) {
+            return;
+        }
         logger.error('Browser initialization failed', error instanceof Error ? error : undefined, {
-            mode,
-            browserUrl: options.browserUrl,
-            wsEndpoint: options.wsEndpoint,
-            autoConnect: options.autoConnect,
-            headless: options.headless,
-            userDataDir: options.userDataDir,
+            mode: 'launch',
+            headless: config.headless,
         });
         throw error;
     }
 }
+/**
+ * Check if DevToolsActivePort file exists in the profile directory.
+ * Used to skip the reconnect attempt entirely on cold starts where
+ * Chrome has never run, avoiding wasted I/O.
+ */
+async function hasPortFile(profileDir) {
+    try {
+        await fs.promises.access(path.join(profileDir, 'DevToolsActivePort'), fs.constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Attempt to reconnect to an existing Chrome via its DevToolsActivePort file.
+ * Returns true on success. On failure, returns false.
+ * Uses a short timeout since this is a fast pre-check, not a full connection attempt.
+ */
+async function tryReconnect(session, profileDir) {
+    try {
+        await session.connect({
+            autoConnect: true,
+            userDataDir: profileDir,
+            ownedReconnect: true,
+            timeout: RECONNECT_TIMEOUT_MS,
+        });
+        logger.info('Reconnected to existing browser');
+        return true;
+    }
+    catch (error) {
+        logger.warning('Reconnect to existing browser failed', {
+            error: extractErrorMessage(error),
+        });
+        return false;
+    }
+}
+/**
+ * Detect Chrome profile-lock errors from Puppeteer.
+ * Matches against Puppeteer's error text which includes "already running for <path>"
+ * when the SingletonLock file prevents a second Chrome instance.
+ */
+function isProfileLockError(error) {
+    const msg = extractErrorMessage(error);
+    return /already running for|already in use|SingletonLock/i.test(msg);
+}
 //# sourceMappingURL=ensure-browser.js.map

package/dist/src/browser/ensure-browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"ensure-browser.js","sourceRoot":"","sources":["../../../src/browser/ensure-browser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AAElE,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;AA+B3B;;GAEG;AACH,SAAS,aAAa,CAAC,OAA6B;IAClD,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAuB,EACvB,OAA6B;IAE7B,qCAAqC;IACrC,IAAI,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;QACxB,OAAO;IACT,CAAC;IAED,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC3D,MAAM,CAAC,IAAI,CAAC,uCAAuC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/D,IAAI,CAAC;QACH,IAAI,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,8BAA8B;YAC9B,MAAM,OAAO,CAAC,OAAO,CAAC;gBACpB,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,iBAAiB,EAAE,OAAO,CAAC,UAAU;gBACrC,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,WAAW,EAAE,OAAO,CAAC,WAAW;aACjC,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,qBAAqB;YACrB,MAAM,OAAO,CAAC,MAAM,CAAC;gBACnB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,KAAK;gBACnC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,KAAK;gBACnC,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,cAAc,EAAE,OAAO,CAAC,cAAc;aACvC,CAAC,CAAC;QACL,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,kCAAkC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EAAE;YACxF,IAAI;YACJ,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC,CAAC;QACH,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"ensure-browser.js","sourceRoot":"","sources":["../../../src/browser/ensure-browser.ts"],"names":[],"mappings":"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"}

package/dist/src/browser/index.d.ts

@@ -4,5 +4,8 @@
  * Exports for browser lifecycle management.
  */
 export { PageRegistry, type PageHandle } from './page-registry.js';
-export { SessionManager, type LaunchOptions, type ConnectOptions, type ConnectionState, type ConnectionStateChangeEvent, } from './session-manager.js';
+export { SessionManager } from './session-manager.js';
+export type { ChromeChannel, LaunchOptions, ConnectOptions, ConnectionState, ConnectionStateChangeEvent, } from './session-manager.types.js';
+export { CHROME_CHANNELS } from './session-manager.types.js';
+export { extractErrorMessage } from './connection-utils.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,0BAA0B,GAChC,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,aAAa,EACb,aAAa,EACb,cAAc,EACd,eAAe,EACf,0BAA0B,GAC3B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/src/browser/index.js

@@ -4,5 +4,7 @@
  * Exports for browser lifecycle management.
  */
 export { PageRegistry } from './page-registry.js';
-export { SessionManager, } from './session-manager.js';
+export { SessionManager } from './session-manager.js';
+export { CHROME_CHANNELS } from './session-manager.types.js';
+export { extractErrorMessage } from './connection-utils.js';
 //# sourceMappingURL=index.js.map

package/dist/src/browser/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAmB,MAAM,oBAAoB,CAAC;AACnE,OAAO,EACL,cAAc,GAKf,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAmB,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAQtD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC"}