@mastra/agent-browser 0.1.0-alpha.0 → 0.2.0-alpha.0

package/dist/index.cjs

@@ -7,12 +7,9 @@ var zod = require('zod');
 
 // src/agent-browser.ts
 var AgentBrowserThreadManager = class extends browser.ThreadManager {
-  sharedManager = null;
   browserConfig;
   resolveCdpUrl;
   onBrowserCreated;
-  /** Map of thread ID to dedicated browser manager (for 'thread' scope) */
-  threadBrowsers = /* @__PURE__ */ new Map();
   constructor(config) {
     super(config);
     this.browserConfig = config.browserConfig;
@@ -20,25 +17,11 @@ var AgentBrowserThreadManager = class extends browser.ThreadManager {
     this.onBrowserCreated = config.onBrowserCreated;
   }
   /**
-   * Set the shared browser manager (called after browser launch).
+   * Get the page for a specific thread, creating session if needed.
    */
-  setSharedManager(manager) {
-    this.sharedManager = manager;
-  }
-  /**
-   * Clear the shared browser manager (called when browser disconnects).
-   */
-  clearSharedManager() {
-    this.sharedManager = null;
-  }
-  /**
-   * Get the shared browser manager.
-   */
-  getSharedManager() {
-    if (!this.sharedManager) {
-      throw new Error("Browser not launched");
-    }
-    return this.sharedManager;
+  async getPageForThread(threadId) {
+    const manager = await this.getManagerForThread(threadId);
+    return manager.getPage();
   }
   /**
    * Create a new session for a thread.
@@ -54,7 +37,10 @@ var AgentBrowserThreadManager = class extends browser.ThreadManager {
       const manager = new agentBrowser.BrowserManager();
       const launchOptions = {
         headless: this.browserConfig.headless ?? true,
-        viewport: this.browserConfig.viewport
+        viewport: this.browserConfig.viewport,
+        profile: this.browserConfig.profile,
+        executablePath: this.browserConfig.executablePath,
+        storageState: this.browserConfig.storageState
       };
       if (this.browserConfig.cdpUrl && this.resolveCdpUrl) {
         launchOptions.cdpUrl = await this.resolveCdpUrl(this.browserConfig.cdpUrl);
@@ -69,7 +55,7 @@ var AgentBrowserThreadManager = class extends browser.ThreadManager {
         throw error;
       }
       session.manager = manager;
-      this.threadBrowsers.set(threadId, manager);
+      this.threadManagers.set(threadId, manager);
       try {
         if (savedState && savedState.tabs.length > 0) {
           this.logger?.debug?.(`Restoring browser state for thread ${threadId}: ${savedState.tabs.length} tabs`);
@@ -77,7 +63,7 @@ var AgentBrowserThreadManager = class extends browser.ThreadManager {
         }
         this.onBrowserCreated?.(manager, threadId);
       } catch (error) {
-        this.threadBrowsers.delete(threadId);
+        this.threadManagers.delete(threadId);
         session.manager = void 0;
         try {
           await manager.close();
@@ -117,13 +103,6 @@ var AgentBrowserThreadManager = class extends browser.ThreadManager {
       this.logger?.warn?.(`Failed to restore browser state: ${error}`);
     }
   }
-  /**
-   * Switch to an existing session.
-   * For 'thread' scope, no switching needed - each thread has its own manager.
-   * For 'shared' scope, nothing to switch.
-   */
-  async switchToSession(_session) {
-  }
   /**
    * Get the browser manager for a specific session.
    */
@@ -139,61 +118,15 @@ var AgentBrowserThreadManager = class extends browser.ThreadManager {
   async doDestroySession(session) {
     if (this.scope === "thread" && session.manager) {
       await session.manager.close();
-      this.threadBrowsers.delete(session.threadId);
     }
   }
   /**
    * Destroy all sessions (called during browser close).
+   * doDestroySession handles closing individual browser managers.
    */
   async destroyAllSessions() {
-    for (const [threadId, manager] of this.threadBrowsers) {
-      try {
-        await manager.close();
-      } catch {
-        this.logger?.debug?.(`Failed to close browser for thread: ${threadId}`);
-      }
-    }
-    this.threadBrowsers.clear();
     await super.destroyAllSessions();
   }
-  /**
-   * Check if any thread browsers are still running.
-   */
-  hasActiveThreadBrowsers() {
-    return this.threadBrowsers.size > 0;
-  }
-  /**
-   * Get the browser manager for an existing thread session without creating a new one.
-   * Returns null if no session exists for the thread.
-   */
-  getExistingManagerForThread(threadId) {
-    if (this.scope === "thread") {
-      return this.threadBrowsers.get(threadId) ?? null;
-    }
-    return this.sharedManager;
-  }
-  /**
-   * Clear all session tracking without closing browsers.
-   * Used when browsers have been externally closed and we just need to reset state.
-   */
-  clearAllSessions() {
-    this.threadBrowsers.clear();
-    this.sessions.clear();
-  }
-  /**
-   * Clear a specific thread's session without closing the browser.
-   * Used when a thread's browser has been externally closed.
-   * Preserves the browser state for potential restoration.
-   * @param threadId - The thread ID to clear
-   */
-  clearSession(threadId) {
-    const session = this.sessions.get(threadId);
-    if (session?.browserState) {
-      this.savedBrowserStates.set(threadId, session.browserState);
-    }
-    this.threadBrowsers.delete(threadId);
-    this.sessions.delete(threadId);
-  }
 };
 var gotoInputSchema = zod.z.object({
   url: zod.z.string().describe("The URL to navigate to"),
@@ -561,31 +494,43 @@ function createAgentBrowserTools(browser) {
   };
 }
 
+// src/utils.ts
+async function getBrowserPid(manager) {
+  try {
+    let browser = manager.getBrowser();
+    if (!browser) {
+      const ctx = manager.getContext();
+      browser = ctx?.browser?.() ?? null;
+    }
+    if (!browser) return void 0;
+    const cdp = await browser.newBrowserCDPSession();
+    try {
+      const info = await cdp.send("SystemInfo.getProcessInfo");
+      const browserProcess = info.processInfo?.find((p) => p.type === "browser");
+      return browserProcess?.id;
+    } finally {
+      await cdp.detach().catch(() => void 0);
+    }
+  } catch {
+    return void 0;
+  }
+}
+
 // src/agent-browser.ts
-var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
+var AgentBrowser = class extends browser.MastraBrowser {
   id;
   name = "AgentBrowser";
   provider = "vercel-labs/agent-browser";
-  /** Primary browser manager (for 'none' mode, also used as fallback) */
-  browserManager = null;
   defaultTimeout = 3e4;
-  /** Active screencast streams per thread (for triggering reconnects on tab changes) */
-  activeScreencastStreams = /* @__PURE__ */ new Map();
-  /** Default key for shared scope */
-  static SHARED_STREAM_KEY = "__shared__";
+  /** Pending PID lookups — awaited in disconnect handlers to avoid racing. */
+  pidLookups = /* @__PURE__ */ new Set();
   constructor(config = {}) {
     super(config);
     this.id = `agent-browser-${Date.now()}`;
     if (config.timeout) {
       this.defaultTimeout = config.timeout;
     }
-    let effectiveScope = config.scope ?? "thread";
-    if (config.cdpUrl && effectiveScope === "thread") {
-      this.logger.warn?.(
-        'Browser scope "thread" is not supported when connecting via cdpUrl. Falling back to "shared" (shared browser connection).'
-      );
-      effectiveScope = "shared";
-    }
+    const effectiveScope = config.cdpUrl ? config.scope ?? "shared" : config.scope ?? "thread";
     this.threadManager = new AgentBrowserThreadManager({
       scope: effectiveScope,
       browserConfig: config,
@@ -602,13 +547,13 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
     });
   }
   // ---------------------------------------------------------------------------
-  // Thread Isolation (delegated to ThreadManager)
+  // Thread Scope (delegated to ThreadManager)
   // ---------------------------------------------------------------------------
   /**
    * Ensure browser is ready and thread session exists.
    * Creates a new page/context for the current thread if needed.
    *
-   * For 'browser' isolation, we need to create the thread session BEFORE
+   * For 'thread' scope, we need to create the thread session BEFORE
    * calling super.ensureReady() because the base class's ensureReady() will
    * call checkBrowserAlive(), which needs at least one thread browser to exist.
    */
@@ -616,17 +561,17 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
     const scope = this.threadManager.getScope();
     const threadId = this.getCurrentThread();
     const existingSession = this.threadManager.hasSession(threadId);
-    if (scope === "thread" && threadId !== browser.DEFAULT_THREAD_ID && !existingSession) {
+    if (scope === "thread" && !existingSession) {
       await this.getManagerForThread(threadId);
     }
     await super.ensureReady();
-    if (scope === "thread" && threadId !== browser.DEFAULT_THREAD_ID && existingSession) {
+    if (scope === "thread" && existingSession) {
       await this.getManagerForThread(threadId);
     }
   }
   /**
    * Get the browser manager for the current thread.
-   * Delegates to ThreadManager for isolation handling.
+   * Delegates to ThreadManager for scope handling.
    */
   async getManagerForThread(threadId) {
     const effectiveThreadId = threadId ?? this.getCurrentThread();
@@ -639,56 +584,47 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
     }
     return this.threadManager.getManagerForThread(effectiveThreadId);
   }
-  /**
-   * Get the page for a specific thread.
-   * For thread-isolated modes, ensures we're on the correct context/page.
-   */
-  async getPageForThread(threadId) {
-    const manager = await this.getManagerForThread(threadId);
-    return manager.getPage();
-  }
-  /**
-   * Close a specific thread's browser session.
-   * Delegates to ThreadManager and notifies registered callbacks.
-   */
-  async closeThreadSession(threadId) {
-    await this.threadManager.destroySession(threadId);
-    this.notifyBrowserClosed(threadId);
-  }
   // ---------------------------------------------------------------------------
   // Lifecycle
   // ---------------------------------------------------------------------------
   async doLaunch() {
     const scope = this.threadManager.getScope();
     if (scope === "thread") {
-      this.browserManager = new agentBrowser.BrowserManager();
-      this.threadManager.setSharedManager(this.browserManager);
+      this.sharedManager = new agentBrowser.BrowserManager();
+      this.threadManager.setSharedManager(this.sharedManager);
       return;
     }
-    this.browserManager = new agentBrowser.BrowserManager();
+    this.sharedManager = new agentBrowser.BrowserManager();
     const localConfig = this.config;
     const launchOptions = {
       headless: localConfig.headless ?? true,
-      viewport: localConfig.viewport
+      viewport: localConfig.viewport,
+      profile: localConfig.profile,
+      executablePath: localConfig.executablePath,
+      storageState: localConfig.storageState
     };
     if (localConfig.cdpUrl) {
       launchOptions.cdpUrl = await this.resolveCdpUrl(localConfig.cdpUrl);
     }
-    await this.browserManager.launch(launchOptions);
-    this.threadManager.setSharedManager(this.browserManager);
-    this.setupCloseListenerForNoneIsolation(this.browserManager);
+    await this.sharedManager.launch(launchOptions);
+    this.threadManager.setSharedManager(this.sharedManager);
+    this.setupCloseListenerForSharedScope(this.sharedManager);
   }
   /**
-   * Set up close event listeners for 'none' isolation shared browser.
+   * Set up close event listeners for 'shared' scope browser.
    * This handles the case where the shared browser is closed externally.
    */
-  setupCloseListenerForNoneIsolation(manager) {
+  setupCloseListenerForSharedScope(manager) {
     try {
+      const pidLookup = getBrowserPid(manager).then((pid) => {
+        if (pid && this.sharedManager === manager) this.sharedBrowserPid = pid;
+      }).finally(() => this.pidLookups.delete(pidLookup));
+      this.pidLookups.add(pidLookup);
       let disconnectHandled = false;
       const handleDisconnect = () => {
         if (disconnectHandled) return;
         disconnectHandled = true;
-        this.handleBrowserDisconnected();
+        void pidLookup.catch(() => void 0).then(() => this.handleBrowserDisconnected());
       };
       const context = manager.getContext();
       if (context) {
@@ -707,13 +643,15 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
     }
   }
   async doClose() {
+    await Promise.allSettled([...this.pidLookups]);
+    this.pidLookups.clear();
     await this.threadManager.destroyAllSessions();
     this.setCurrentThread(void 0);
     const scope = this.threadManager.getScope();
-    if (scope === "shared" && this.browserManager) {
-      await this.browserManager.close();
+    if (scope === "shared" && this.sharedManager) {
+      await this.sharedManager.close();
     }
-    this.browserManager = null;
+    this.sharedManager = null;
   }
   /**
    * Check if the browser is still alive by verifying the page is connected.
@@ -722,13 +660,13 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
   async checkBrowserAlive() {
     const scope = this.threadManager.getScope();
     if (scope === "thread") {
-      return this.threadManager.hasActiveThreadBrowsers();
+      return this.threadManager.hasActiveThreadManagers();
     }
-    if (!this.browserManager) {
+    if (!this.sharedManager) {
       return false;
     }
     try {
-      const page = this.browserManager.getPage();
+      const page = this.sharedManager.getPage();
       const url = page.url();
       if (url && url !== "about:blank") {
         const state = await this.getBrowserState();
@@ -767,28 +705,21 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
   async getPage(explicitThreadId) {
     const scope = this.getScope();
     const threadId = explicitThreadId ?? this.getCurrentThread();
-    if (scope === "thread" || scope !== "shared" && threadId !== browser.DEFAULT_THREAD_ID) {
-      return this.getPageForThread(threadId);
+    if (scope === "thread") {
+      return this.threadManager.getPageForThread(threadId);
     }
-    if (!this.browserManager) throw new Error("Browser not launched");
-    return this.browserManager.getPage();
+    if (!this.sharedManager) throw new Error("Browser not launched");
+    return this.sharedManager.getPage();
   }
   /**
-   * Handle browser disconnection by clearing internal state.
-   * For 'thread' scope, only notifies the specific thread's callbacks.
-   * For 'shared' scope, notifies all callbacks.
+   * Get the active page for a thread (implements abstract method from base class).
+   * Returns null if no page is available, unlike getPage which throws.
    */
-  handleBrowserDisconnected() {
-    const scope = this.threadManager.getScope();
-    const threadId = this.getCurrentThread();
-    if (scope === "thread" && threadId !== browser.DEFAULT_THREAD_ID) {
-      this.threadManager.clearSession(threadId);
-      this.logger.debug?.(`Cleared browser session for thread: ${threadId}`);
-      this.notifyBrowserClosed(threadId);
-    } else {
-      this.browserManager = null;
-      this.threadManager.clearSharedManager();
-      super.handleBrowserDisconnected();
+  async getActivePage(threadId) {
+    try {
+      return await this.getPage(threadId);
+    } catch {
+      return null;
     }
   }
   /**
@@ -797,11 +728,17 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
    */
   setupCloseListenerForThread(manager, threadId) {
     try {
+      const pidLookup = getBrowserPid(manager).then((pid) => {
+        if (pid && this.threadManager?.getExistingManagerForThread(threadId) === manager) {
+          this.threadBrowserPids.set(threadId, pid);
+        }
+      }).finally(() => this.pidLookups.delete(pidLookup));
+      this.pidLookups.add(pidLookup);
       let disconnectHandled = false;
       const handleDisconnect = () => {
         if (disconnectHandled) return;
         disconnectHandled = true;
-        this.handleThreadBrowserDisconnected(threadId);
+        void pidLookup.catch(() => void 0).then(() => this.handleThreadBrowserDisconnected(threadId));
       };
       const context = manager.getContext();
       if (context) {
@@ -819,15 +756,6 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
     } catch {
     }
   }
-  /**
-   * Handle browser disconnection for a specific thread.
-   * Called when a thread's browser is closed externally.
-   */
-  handleThreadBrowserDisconnected(threadId) {
-    this.threadManager.clearSession(threadId);
-    this.logger.debug?.(`Cleared browser session for thread: ${threadId}`);
-    this.notifyBrowserClosed(threadId);
-  }
   /**
    * Create an error response from an exception.
    * Extends base class to add agent-browser specific error handling.
@@ -951,6 +879,16 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
       return null;
     }
   }
+  /**
+   * Get browser state for a thread (implements abstract method from base class).
+   * Sync version that uses existing manager lookup without creating sessions.
+   */
+  getBrowserStateForThread(threadId) {
+    const effectiveThreadId = threadId ?? this.getCurrentThread() ?? browser.DEFAULT_THREAD_ID;
+    const manager = this.threadManager.getExistingManagerForThread(effectiveThreadId);
+    if (!manager) return null;
+    return this.getBrowserStateForManager(manager);
+  }
   /**
    * Get browser state from a specific manager instance.
    */
@@ -991,27 +929,23 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
     }
   }
   /**
-   * Update the browser state in the thread session.
-   * Called on navigation, tab open/close to keep state fresh.
+   * Export the current browser session's storage state (cookies, localStorage) to a JSON file.
+   * This can later be loaded via the `storageState` config option to restore the session.
+   *
+   * @param path - File path to save the storage state JSON
+   * @param threadId - Optional thread ID (defaults to current thread)
    */
-  updateSessionBrowserState(threadId) {
-    try {
-      const effectiveThreadId = threadId ?? this.getCurrentThread() ?? browser.DEFAULT_THREAD_ID;
-      const scope = this.threadManager.getScope();
-      let manager = null;
-      if (scope === "thread") {
-        manager = this.threadManager.getExistingManagerForThread(effectiveThreadId);
-      } else {
-        manager = this.browserManager;
-      }
-      if (manager) {
-        const state = this.getBrowserStateForManager(manager);
-        if (state) {
-          this.threadManager.updateBrowserState(effectiveThreadId, state);
-        }
-      }
-    } catch {
+  async exportStorageState(path, threadId) {
+    const effectiveThreadId = threadId ?? this.getCurrentThread();
+    const manager = this.threadManager.getExistingManagerForThread(effectiveThreadId);
+    if (!manager) {
+      throw new Error("No browser is running. Launch a browser first before exporting storage state.");
+    }
+    const context = manager.getContext();
+    if (!context) {
+      throw new Error("Browser context not available");
     }
+    await context.storageState({ path });
   }
   // ---------------------------------------------------------------------------
   // 1. browser_goto - Navigate to URL
@@ -1435,10 +1369,10 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
             );
           }
           await browser.switchTo(input.index);
-          await this.reconnectScreencast("tab switch");
+          await this.reconnectScreencastForThread(threadId, "tab switch");
           const page = browser.getPage();
           const pageUrl = page.url();
-          const streamKey = this.getStreamKey(this.getCurrentThread());
+          const streamKey = this.getStreamKey(threadId);
           const stream = this.activeScreencastStreams.get(streamKey);
           if (pageUrl && stream?.isActive()) {
             stream.emitUrl(pageUrl);
@@ -1461,7 +1395,7 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
             );
           }
           await browser.closeTab(input.index);
-          await this.reconnectScreencast("tab close");
+          await this.reconnectScreencastForThread(threadId, "tab close");
           this.updateSessionBrowserState(threadId);
           const tabsList = await browser.listTabs?.() ?? [];
           return {
@@ -1557,47 +1491,15 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
   // ---------------------------------------------------------------------------
   // Screencast (for Studio live view)
   // ---------------------------------------------------------------------------
-  /**
-   * Get the stream key for a thread (or shared key for shared scope).
-   */
-  getStreamKey(threadId) {
-    return threadId || _AgentBrowser.SHARED_STREAM_KEY;
-  }
-  /**
-   * Trigger a screencast reconnect after tab changes.
-   * Called internally when tabs are switched or closed.
-   */
-  async reconnectScreencast(_reason) {
-    const threadId = this.getCurrentThread();
-    const streamKey = this.getStreamKey(threadId);
-    const stream = this.activeScreencastStreams.get(streamKey);
-    if (stream?.isActive()) {
-      await new Promise((resolve) => setTimeout(resolve, 150));
-      if (stream?.isActive()) {
-        try {
-          await stream.reconnect();
-          const manager = this.threadManager.getExistingManagerForThread(threadId) ?? this.browserManager;
-          const activePage = manager?.getPage();
-          if (activePage) {
-            const url = activePage.url();
-            if (url) {
-              stream.emitUrl(url);
-            }
-          }
-        } catch (err) {
-          console.error("[AgentBrowser] Failed to reconnect screencast:", err);
-        }
-      }
-    }
-  }
   async startScreencast(_options) {
-    const threadId = _options?.threadId;
+    const requestedThreadId = _options?.threadId;
+    const effectiveThreadId = this.getScope() === "thread" ? requestedThreadId ?? this.getCurrentThread() ?? browser.DEFAULT_THREAD_ID : requestedThreadId;
     let browserManager;
-    if (this.getScope() === "thread" && threadId) {
-      browserManager = await this.getManagerForThread(threadId);
+    if (this.getScope() === "thread") {
+      browserManager = await this.getManagerForThread(effectiveThreadId);
     } else {
-      if (!this.browserManager) throw new Error("Browser not launched");
-      browserManager = this.browserManager;
+      if (!this.sharedManager) throw new Error("Browser not launched");
+      browserManager = this.sharedManager;
     }
     const provider = {
       getCdpSession: async () => {
@@ -1611,7 +1513,7 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
       isBrowserRunning: () => browserManager.isLaunched()
     };
     const stream = new browser.ScreencastStreamImpl(provider, _options);
-    const streamKey = this.getStreamKey(threadId);
+    const streamKey = this.getStreamKey(effectiveThreadId);
     this.activeScreencastStreams.set(streamKey, stream);
     const context = browserManager.getContext();
     if (context) {
@@ -1630,7 +1532,7 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
         const onFrameNavigated = (frame) => {
           if (!frame.parentFrame()) {
             stream.emitUrl(frame.url());
-            this.updateSessionBrowserState(threadId);
+            this.updateSessionBrowserState(effectiveThreadId);
           }
         };
         page.on("framenavigated", onFrameNavigated);
@@ -1723,6 +1625,7 @@ exports.createAgentBrowserTools = createAgentBrowserTools;
 exports.dialogInputSchema = dialogInputSchema;
 exports.dragInputSchema = dragInputSchema;
 exports.evaluateInputSchema = evaluateInputSchema;
+exports.getBrowserPid = getBrowserPid;
 exports.gotoInputSchema = gotoInputSchema;
 exports.hoverInputSchema = hoverInputSchema;
 exports.pressInputSchema = pressInputSchema;