@mastra/agent-browser 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# @mastra/agent-browser
+
+## 0.1.0
+
+### Minor Changes
+
+- Add browser automation support with screencast streaming, input injection, and thread isolation ([#14938](https://github.com/mastra-ai/mastra/pull/14938))
+
+  **New Features:**
+  - Browser tools for web automation (navigate, click, type, scroll, extract, etc.)
+  - Real-time screencast streaming via WebSocket
+  - Mouse and keyboard input injection
+  - Thread-scoped browser isolation (`scope: 'thread'`)
+  - State persistence and restoration across sessions
+  - Support for cloud providers (Browserbase, Browser-Use, Browserless)
+
+  **Configuration:**
+
+  ```typescript
+  import { AgentBrowser } from '@mastra/agent-browser';
+
+  const browser = new AgentBrowser({
+    headless: true,
+    scope: 'thread', // Each thread gets isolated browser
+    viewport: { width: 1280, height: 720 },
+  });
+
+  const agent = mastra.getAgent('my-agent', { browser });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`cb15509`](https://github.com/mastra-ai/mastra/commit/cb15509b58f6a83e11b765c945082afc027db972), [`81e4259`](https://github.com/mastra-ai/mastra/commit/81e425939b4ceeb4f586e9b6d89c3b1c1f2d2fe7), [`951b8a1`](https://github.com/mastra-ai/mastra/commit/951b8a1b5ef7e1474c59dc4f2b9fc1a8b1e508b6), [`80c5668`](https://github.com/mastra-ai/mastra/commit/80c5668e365470d3a96d3e953868fd7a643ff67c), [`3d478c1`](https://github.com/mastra-ai/mastra/commit/3d478c1e13f17b80f330ac49d7aa42ef929b93ff), [`2b4ea10`](https://github.com/mastra-ai/mastra/commit/2b4ea10b053e4ea1ab232d536933a4a3c4cba999), [`a0544f0`](https://github.com/mastra-ai/mastra/commit/a0544f0a1e6bd52ac12676228967c1938e43648d), [`6039f17`](https://github.com/mastra-ai/mastra/commit/6039f176f9c457304825ff1df8c83b8e457376c0), [`06b928d`](https://github.com/mastra-ai/mastra/commit/06b928dfc2f5630d023467476cc5919dfa858d0a), [`6a8d984`](https://github.com/mastra-ai/mastra/commit/6a8d9841f2933456ee1598099f488d742b600054), [`c8c86aa`](https://github.com/mastra-ai/mastra/commit/c8c86aa1458017fbd1c0776fdc0c520d129df8a6)]:
+  - @mastra/core@1.22.0
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- Add browser automation support with screencast streaming, input injection, and thread isolation ([#14938](https://github.com/mastra-ai/mastra/pull/14938))
+
+  **New Features:**
+  - Browser tools for web automation (navigate, click, type, scroll, extract, etc.)
+  - Real-time screencast streaming via WebSocket
+  - Mouse and keyboard input injection
+  - Thread-scoped browser isolation (`scope: 'thread'`)
+  - State persistence and restoration across sessions
+  - Support for cloud providers (Browserbase, Browser-Use, Browserless)
+
+  **Configuration:**
+
+  ```typescript
+  import { AgentBrowser } from '@mastra/agent-browser';
+
+  const browser = new AgentBrowser({
+    headless: true,
+    scope: 'thread', // Each thread gets isolated browser
+    viewport: { width: 1280, height: 720 },
+  });
+
+  const agent = mastra.getAgent('my-agent', { browser });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`cb15509`](https://github.com/mastra-ai/mastra/commit/cb15509b58f6a83e11b765c945082afc027db972), [`80c5668`](https://github.com/mastra-ai/mastra/commit/80c5668e365470d3a96d3e953868fd7a643ff67c), [`3d478c1`](https://github.com/mastra-ai/mastra/commit/3d478c1e13f17b80f330ac49d7aa42ef929b93ff), [`6039f17`](https://github.com/mastra-ai/mastra/commit/6039f176f9c457304825ff1df8c83b8e457376c0), [`06b928d`](https://github.com/mastra-ai/mastra/commit/06b928dfc2f5630d023467476cc5919dfa858d0a), [`6a8d984`](https://github.com/mastra-ai/mastra/commit/6a8d9841f2933456ee1598099f488d742b600054)]:
+  - @mastra/core@1.22.0-alpha.2

package/LICENSE.md

@@ -0,0 +1,30 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

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.
@@ -69,7 +52,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 +60,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 +100,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 +115,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"),
@@ -562,30 +492,18 @@ function createAgentBrowserTools(browser) {
 }
 
 // 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__";
   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 +520,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.
    */
@@ -626,7 +544,7 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
   }
   /**
    * 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,33 +557,17 @@ 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,
@@ -674,15 +576,15 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
     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 {
       let disconnectHandled = false;
       const handleDisconnect = () => {
@@ -710,10 +612,10 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
     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 +624,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 +669,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;
     }
   }
   /**
@@ -819,15 +714,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 +837,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.
    */
@@ -990,29 +886,6 @@ var AgentBrowser = class _AgentBrowser extends browser.MastraBrowser {
       return 0;
     }
   }
-  /**
-   * Update the browser state in the thread session.
-   * Called on navigation, tab open/close to keep state fresh.
-   */
-  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 {
-    }
-  }
   // ---------------------------------------------------------------------------
   // 1. browser_goto - Navigate to URL
   // ---------------------------------------------------------------------------
@@ -1435,10 +1308,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 +1334,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 +1430,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 +1452,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 +1471,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);