agent-browser 0.17.1 → 0.19.0

package/dist/browser.js

@@ -12,7 +12,7 @@ import { getEncryptionKey, isEncryptedPayload, decryptData, ENCRYPTION_KEY_ENV,
  * Can be overridden via the AGENT_BROWSER_DEFAULT_TIMEOUT environment variable.
  * Default is 25s, which is below the CLI's 30s IPC read timeout to ensure
  * Playwright errors are returned before the CLI gives up with EAGAIN.
- * CDP and recording contexts use a shorter fixed timeout (10s) and are not affected.
+ * Recording contexts use a shorter fixed timeout (10s) and are not affected.
  */
 export function getDefaultTimeout() {
     const envValue = process.env.AGENT_BROWSER_DEFAULT_TIMEOUT;
@@ -24,12 +24,32 @@ export function getDefaultTimeout() {
     }
     return 25000;
 }
+/**
+ * Handles boolean env vars and parsing (e.g., "true", "1", "false", "0"),
+ * with a default value if not set or invalid
+ */
+export function parseBooleanEnvVar(name, defaultValue) {
+    const truthyVals = ['1', 'true'];
+    const falsyVals = ['0', 'false'];
+    if (!Object.hasOwn(process.env, name)) {
+        return defaultValue;
+    }
+    const param = process.env[name].toLowerCase();
+    if (truthyVals.includes(param)) {
+        return true;
+    }
+    if (falsyVals.includes(param)) {
+        return false;
+    }
+    return defaultValue;
+}
 /**
  * Manages the Playwright browser lifecycle with multiple tabs/windows
  */
 export class BrowserManager {
     browser = null;
     cdpEndpoint = null; // stores port number or full URL
+    resolvedWsUrl = null;
     isPersistentContext = false;
     browserbaseSessionId = null;
     browserbaseApiKey = null;
@@ -37,6 +57,7 @@ export class BrowserManager {
     browserUseApiKey = null;
     kernelSessionId = null;
     kernelApiKey = null;
+    browserlessStopUrl = null;
     contexts = [];
     pages = [];
     activePageIndex = 0;
@@ -53,6 +74,17 @@ export class BrowserManager {
     colorScheme = null;
     downloadPath = null;
     allowedDomains = [];
+    inspectServer = null;
+    stopInspectServer() {
+        if (this.inspectServer) {
+            this.inspectServer.stop();
+            this.inspectServer = null;
+        }
+    }
+    setInspectServer(server) {
+        this.stopInspectServer();
+        this.inspectServer = server;
+    }
     /**
      * Set the persistent color scheme preference.
      * Applied automatically to all new pages and contexts.
@@ -94,6 +126,19 @@ export class BrowserManager {
     isLaunched() {
         return this.browser !== null || this.isPersistentContext;
     }
+    getCdpUrl() {
+        if (this.resolvedWsUrl)
+            return this.resolvedWsUrl;
+        if (this.cdpEndpoint?.startsWith('ws://') || this.cdpEndpoint?.startsWith('wss://')) {
+            return this.cdpEndpoint;
+        }
+        try {
+            return this.browser?.wsEndpoint?.() ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Get enhanced snapshot with refs and cache the ref map
      */
@@ -312,6 +357,40 @@ export class BrowserManager {
             this.activeFrame = frame;
         }
     }
+    /**
+     * Navigate the active page to a URL and return the resolved URL + title.
+     * If the browser is launched but all pages have been closed, a new page is
+     * created automatically before navigating (stale-session recovery).
+     */
+    async navigate(url, options = {}) {
+        this.checkDomainAllowed(url);
+        await this.ensurePage();
+        if (options.headers && Object.keys(options.headers).length > 0) {
+            await this.setScopedHeaders(url, options.headers);
+        }
+        const page = this.getPage();
+        await page.goto(url, {
+            waitUntil: options.waitUntil ?? 'load',
+        });
+        return {
+            url: page.url(),
+            title: await page.title(),
+        };
+    }
+    /**
+     * Get the active page URL.
+     */
+    async getUrl() {
+        await this.ensurePage();
+        return this.getPage().url();
+    }
+    /**
+     * Get the active page title.
+     */
+    async getTitle() {
+        await this.ensurePage();
+        return this.getPage().title();
+    }
     /**
      * Switch back to main frame
      */
@@ -719,12 +798,17 @@ export class BrowserManager {
      * Close a Browserbase session via API
      */
     async closeBrowserbaseSession(sessionId, apiKey) {
-        await fetch(`https://api.browserbase.com/v1/sessions/${sessionId}`, {
-            method: 'DELETE',
+        const response = await fetch(`https://api.browserbase.com/v1/sessions/${sessionId}`, {
+            method: 'POST',
             headers: {
+                'Content-Type': 'application/json',
                 'X-BB-API-Key': apiKey,
             },
+            body: JSON.stringify({ status: 'REQUEST_RELEASE' }),
         });
+        if (!response.ok) {
+            throw new Error(`Failed to close Browserbase session: ${response.statusText}`);
+        }
     }
     /**
      * Close a Browser Use session via API
@@ -746,35 +830,43 @@ export class BrowserManager {
      * Close a Kernel session via API
      */
     async closeKernelSession(sessionId, apiKey) {
+        const headers = {};
+        if (apiKey) {
+            headers['Authorization'] = `Bearer ${apiKey}`;
+        }
         const response = await fetch(`https://api.onkernel.com/browsers/${sessionId}`, {
             method: 'DELETE',
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-            },
+            headers,
         });
         if (!response.ok) {
             throw new Error(`Failed to close Kernel session: ${response.statusText}`);
         }
     }
+    /**
+     * Close a Browserless session via its stop URL
+     */
+    async closeBrowserlessSession(stopUrl) {
+        const response = await fetch(stopUrl, {
+            method: 'DELETE',
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to close Browserless session: ${response.statusText}`);
+        }
+    }
     /**
      * Connect to Browserbase remote browser via CDP.
-     * Requires BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID environment variables.
+     * Requires BROWSERBASE_API_KEY environment variable.
      */
     async connectToBrowserbase() {
         const browserbaseApiKey = process.env.BROWSERBASE_API_KEY;
-        const browserbaseProjectId = process.env.BROWSERBASE_PROJECT_ID;
-        if (!browserbaseApiKey || !browserbaseProjectId) {
-            throw new Error('BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID are required when using browserbase as a provider');
+        if (!browserbaseApiKey) {
+            throw new Error('BROWSERBASE_API_KEY is required when using browserbase as a provider');
         }
         const response = await fetch('https://api.browserbase.com/v1/sessions', {
             method: 'POST',
             headers: {
-                'Content-Type': 'application/json',
                 'X-BB-API-Key': browserbaseApiKey,
             },
-            body: JSON.stringify({
-                projectId: browserbaseProjectId,
-            }),
         });
         if (!response.ok) {
             throw new Error(`Failed to create Browserbase session: ${response.statusText}`);
@@ -794,7 +886,7 @@ export class BrowserManager {
             this.browserbaseSessionId = session.id;
             this.browserbaseApiKey = browserbaseApiKey;
             this.browser = browser;
-            context.setDefaultTimeout(10000);
+            context.setDefaultTimeout(getDefaultTimeout());
             this.contexts.push(context);
             this.setupContextTracking(context);
             await this.ensureDomainFilter(context);
@@ -815,12 +907,14 @@ export class BrowserManager {
      * Returns the profile object if successful.
      */
     async findOrCreateKernelProfile(profileName, apiKey) {
+        const headers = {};
+        if (apiKey) {
+            headers['Authorization'] = `Bearer ${apiKey}`;
+        }
         // First, try to get the existing profile
         const getResponse = await fetch(`https://api.onkernel.com/profiles/${encodeURIComponent(profileName)}`, {
             method: 'GET',
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-            },
+            headers,
         });
         if (getResponse.ok) {
             // Profile exists, return it
@@ -834,7 +928,7 @@ export class BrowserManager {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
-                Authorization: `Bearer ${apiKey}`,
+                ...headers,
             },
             body: JSON.stringify({ name: profileName }),
         });
@@ -845,13 +939,13 @@ export class BrowserManager {
     }
     /**
      * Connect to Kernel remote browser via CDP.
-     * Requires KERNEL_API_KEY environment variable.
+     * Uses KERNEL_API_KEY environment variable for authentication when set.
+     * When running inside environments with external credential injection
+     * (e.g. Vercel Sandbox credentials brokering), the API key can be omitted
+     * and auth headers will be injected at the network layer.
      */
     async connectToKernel() {
         const kernelApiKey = process.env.KERNEL_API_KEY;
-        if (!kernelApiKey) {
-            throw new Error('KERNEL_API_KEY is required when using kernel as a provider');
-        }
         // Find or create profile if KERNEL_PROFILE_NAME is set
         const profileName = process.env.KERNEL_PROFILE_NAME;
         let profileConfig;
@@ -864,12 +958,15 @@ export class BrowserManager {
                 },
             };
         }
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (kernelApiKey) {
+            headers['Authorization'] = `Bearer ${kernelApiKey}`;
+        }
         const response = await fetch('https://api.onkernel.com/browsers', {
             method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${kernelApiKey}`,
-            },
+            headers,
             body: JSON.stringify({
                 // Kernel browsers are headful by default with stealth mode available
                 // The user can configure these via environment variables if needed
@@ -911,7 +1008,7 @@ export class BrowserManager {
                 page = pages[0] ?? (await context.newPage());
             }
             this.kernelSessionId = session.session_id;
-            this.kernelApiKey = kernelApiKey;
+            this.kernelApiKey = kernelApiKey ?? null;
             this.browser = browser;
             context.setDefaultTimeout(getDefaultTimeout());
             this.contexts.push(context);
@@ -994,6 +1091,82 @@ export class BrowserManager {
             throw error;
         }
     }
+    /**
+     * Connect to Browserless remote browser via CDP.
+     * Requires BROWSERLESS_API_KEY environment variable.
+     */
+    async connectToBrowserless() {
+        const browserlessToken = process.env.BROWSERLESS_API_KEY;
+        if (!browserlessToken) {
+            throw new Error('BROWSERLESS_API_KEY is required when using browserless as a provider');
+        }
+        const supportedBrowsers = ['chromium', 'chrome'];
+        const apiUrl = process.env.BROWSERLESS_API_URL || 'https://production-sfo.browserless.io';
+        const browserType = process.env.BROWSERLESS_BROWSER_TYPE || 'chromium';
+        const ttl = parseInt(process.env.BROWSERLESS_TTL || '300000', 10);
+        const stealth = parseBooleanEnvVar('BROWSERLESS_STEALTH', true);
+        if (!supportedBrowsers.includes(browserType)) {
+            throw new Error(`BROWSERLESS_BROWSER_TYPE "${browserType}" is not supported. Only ${supportedBrowsers.join(', ')} are allowed.`);
+        }
+        const response = await fetch(`${apiUrl}/session?token=${encodeURIComponent(browserlessToken)}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                ttl,
+                stealth,
+                browser: browserType,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to create Browserless session: ${response.statusText}`);
+        }
+        let session;
+        try {
+            session = (await response.json());
+        }
+        catch (error) {
+            throw new Error(`Failed to parse Browserless session response: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!session.connect || !session.stop) {
+            throw new Error(`Invalid Browserless session response: missing ${!session.connect ? 'connect' : 'stop'}`);
+        }
+        const browser = await chromium.connectOverCDP(session.connect).catch(() => {
+            throw new Error('Failed to connect to Browserless session via CDP');
+        });
+        try {
+            const contexts = browser.contexts();
+            let context;
+            let page;
+            if (contexts.length === 0) {
+                context = await browser.newContext();
+                page = await context.newPage();
+            }
+            else {
+                context = contexts[0];
+                const pages = context.pages();
+                page = pages[0] ?? (await context.newPage());
+            }
+            this.browser = browser;
+            this.browserlessStopUrl = session.stop;
+            context.setDefaultTimeout(getDefaultTimeout());
+            this.contexts.push(context);
+            this.setupContextTracking(context);
+            await this.ensureDomainFilter(context);
+            await this.sanitizeExistingPages([page]);
+            this.pages.push(page);
+            this.activePageIndex = 0;
+            this.setupPageTracking(page);
+        }
+        catch (error) {
+            await this.closeBrowserlessSession(session.stop).catch((sessionError) => {
+                console.error('Failed to close Browserless session during cleanup:', sessionError);
+            });
+            this.browserlessStopUrl = null;
+            throw error;
+        }
+    }
     /**
      * Launch the browser with the specified options
      * If already launched, this is a no-op (browser stays open)
@@ -1080,6 +1253,10 @@ export class BrowserManager {
             await this.connectToKernel();
             return;
         }
+        if (provider === 'browserless') {
+            await this.connectToBrowserless();
+            return;
+        }
         if (this.downloadPath) {
             const resolved = path.resolve(this.downloadPath);
             const stat = statSync(resolved, { throwIfNoEntry: false });
@@ -1174,6 +1351,7 @@ export class BrowserManager {
                 ...(this.downloadPath && { downloadsPath: this.downloadPath }),
             });
             this.cdpEndpoint = null;
+            this.resolvedWsUrl = null;
             // Check for auto-load state file (supports encrypted files)
             let storageState = options.storageState ? options.storageState : undefined;
             if (!storageState && options.autoStateFilePath) {
@@ -1265,17 +1443,17 @@ export class BrowserManager {
         }
         else if (/^\d+$/.test(cdpEndpoint)) {
             // Numeric string - treat as port number (handles JSON serialization quirks)
-            cdpUrl = `http://localhost:${cdpEndpoint}`;
+            cdpUrl = `http://127.0.0.1:${cdpEndpoint}`;
         }
         else {
             // Unknown format - still try as port for backward compatibility
-            cdpUrl = `http://localhost:${cdpEndpoint}`;
+            cdpUrl = `http://127.0.0.1:${cdpEndpoint}`;
         }
         const browser = await chromium
             .connectOverCDP(cdpUrl, { timeout: options?.timeout })
             .catch(() => {
             throw new Error(`Failed to connect via CDP to ${cdpUrl}. ` +
-                (cdpUrl.includes('localhost')
+                (cdpUrl.includes('127.0.0.1')
                     ? `Make sure the app is running with --remote-debugging-port=${cdpEndpoint}`
                     : 'Make sure the remote browser is accessible and the URL is correct.'));
         });
@@ -1293,8 +1471,26 @@ export class BrowserManager {
             // All validation passed - commit state
             this.browser = browser;
             this.cdpEndpoint = cdpEndpoint;
+            let resolvedWs = null;
+            try {
+                resolvedWs = browser.wsEndpoint?.() ?? null;
+            }
+            catch (err) {
+                console.error('[inspect] wsEndpoint() failed:', err);
+            }
+            if (!resolvedWs && (cdpUrl.startsWith('http://') || cdpUrl.startsWith('https://'))) {
+                try {
+                    const resp = await fetch(`${cdpUrl}/json/version`);
+                    const info = await resp.json();
+                    resolvedWs = info.webSocketDebuggerUrl ?? null;
+                }
+                catch (err) {
+                    console.error('[inspect] /json/version fetch failed:', err);
+                }
+            }
+            this.resolvedWsUrl = resolvedWs;
             for (const context of contexts) {
-                context.setDefaultTimeout(10000);
+                context.setDefaultTimeout(getDefaultTimeout());
                 this.contexts.push(context);
                 this.setupContextTracking(context);
                 await this.ensureDomainFilter(context);
@@ -1510,7 +1706,7 @@ export class BrowserManager {
      * Create a new tab in the current context
      */
     async newTab() {
-        if (!this.browser || this.contexts.length === 0) {
+        if (!this.isLaunched() || this.contexts.length === 0) {
             throw new Error('Browser not launched');
         }
         // Invalidate CDP session since we're switching to a new page
@@ -1530,7 +1726,9 @@ export class BrowserManager {
      */
     async newWindow(viewport) {
         if (!this.browser) {
-            throw new Error('Browser not launched');
+            throw new Error(this.isPersistentContext
+                ? 'newWindow is not supported in extension (persistent context) mode'
+                : 'Browser not launched');
         }
         const context = await this.browser.newContext({
             viewport: viewport === undefined ? { width: 1280, height: 720 } : viewport,
@@ -1931,8 +2129,8 @@ export class BrowserManager {
         this.recordingTempDir = path.join(os.tmpdir(), `agent-browser-recording-${session}-${Date.now()}`);
         mkdirSync(this.recordingTempDir, { recursive: true });
         this.recordingOutputPath = outputPath;
-        // Create a new context with video recording enabled and restored state
-        const viewport = { width: 1280, height: 720 };
+        // Reuse the active page viewport when available so recording matches the current layout.
+        const viewport = currentPage?.viewportSize() ?? { width: 1280, height: 720 };
         this.recordingContext = await this.browser.newContext({
             viewport,
             recordVideo: {
@@ -2045,6 +2243,7 @@ export class BrowserManager {
      * Close the browser and clean up
      */
     async close() {
+        this.stopInspectServer();
         // Stop recording if active (saves video)
         if (this.recordingContext) {
             await this.stopRecording();
@@ -2089,12 +2288,18 @@ export class BrowserManager {
             });
             this.browser = null;
         }
-        else if (this.kernelSessionId && this.kernelApiKey) {
-            await this.closeKernelSession(this.kernelSessionId, this.kernelApiKey).catch((error) => {
+        else if (this.kernelSessionId) {
+            await this.closeKernelSession(this.kernelSessionId, this.kernelApiKey ?? undefined).catch((error) => {
                 console.error('Failed to close Kernel session:', error);
             });
             this.browser = null;
         }
+        else if (this.browserlessStopUrl) {
+            await this.closeBrowserlessSession(this.browserlessStopUrl).catch((error) => {
+                console.error('Failed to close Browserless session:', error);
+            });
+            this.browser = null;
+        }
         else if (this.cdpEndpoint !== null) {
             // CDP: only disconnect, don't close external app's pages
             if (this.browser) {
@@ -2118,12 +2323,14 @@ export class BrowserManager {
         this.pages = [];
         this.contexts = [];
         this.cdpEndpoint = null;
+        this.resolvedWsUrl = null;
         this.browserbaseSessionId = null;
         this.browserbaseApiKey = null;
         this.browserUseSessionId = null;
         this.browserUseApiKey = null;
         this.kernelSessionId = null;
         this.kernelApiKey = null;
+        this.browserlessStopUrl = null;
         this.isPersistentContext = false;
         this.activePageIndex = 0;
         this.colorScheme = null;