@mastra/agent-browser 0.3.0-alpha.1 → 0.3.1-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @mastra/agent-browser
 
+## 0.3.1-alpha.0
+
+### Patch Changes
+
+- Fixed browser state reporting to identify when the agent or user closed the browser or changed the active URL. ([#17631](https://github.com/mastra-ai/mastra/pull/17631))
+
+- Updated dependencies [[`2bccba4`](https://github.com/mastra-ai/mastra/commit/2bccba4c03cadc815c2d54cbf4dd43a922140a8d), [`2bccba4`](https://github.com/mastra-ai/mastra/commit/2bccba4c03cadc815c2d54cbf4dd43a922140a8d), [`f2ab060`](https://github.com/mastra-ai/mastra/commit/f2ab060162bea81505fda553e2cee29c1979fd04), [`5d302c8`](https://github.com/mastra-ai/mastra/commit/5d302c8eda1a6ac74eab5e442c4f64db6cc97a06)]:
+  - @mastra/core@1.42.0-alpha.1
+
+## 0.3.0
+
+### Minor Changes
+
+- Add `waitUntil` support to `browser_click`, `browser_press`, and `browser_select`. When provided, the tool waits for the page to reach the given load state (`load`, `domcontentloaded`, or `networkidle`) after the action completes, preventing the next `browser_snapshot` from capturing stale DOM when the interaction triggers navigation. The parameter is optional and behaviour is unchanged when omitted. ([#17426](https://github.com/mastra-ai/mastra/pull/17426))
+
+  Usage example:
+
+  ```ts
+  await browser_click({ ref: '@e1', waitUntil: 'domcontentloaded', timeout: 5000 });
+  ```
+
+  Fixes #17397.
+
+- Added extensibility hooks for custom browser providers (e.g. Firecrawl Browser Sandbox). ([#15724](https://github.com/mastra-ai/mastra/pull/15724))
+  - New `createThreadManager` config option to inject a custom thread manager factory
+  - Exported `AgentBrowserThreadManager` class and related types (`AgentBrowserSession`, `AgentBrowserThreadManagerConfig`, `CreateAgentBrowserThreadManager`)
+  - Changed several internal members from `private` to `protected` to support subclassing
+
+### Patch Changes
+
+- Updated dependencies [[`fa63872`](https://github.com/mastra-ai/mastra/commit/fa6387280954e6b667bec5714b55ba082bc627ff), [`d779de3`](https://github.com/mastra-ai/mastra/commit/d779de3cd9d2e7ed8110547190e2f15e786a0e41), [`1750c97`](https://github.com/mastra-ai/mastra/commit/1750c975d6179fbf6db2813b15229d4f8f23fc55), [`9283971`](https://github.com/mastra-ai/mastra/commit/928397157009b4aef4d5fdf3a0a273cb371beb55), [`f07b646`](https://github.com/mastra-ai/mastra/commit/f07b64604ab7d25391179790b7fd4823df9e2dff), [`d8838ae`](https://github.com/mastra-ai/mastra/commit/d8838ae80b69780361693d27098f7f6684af12fe), [`40f9297`](https://github.com/mastra-ai/mastra/commit/40f9297003b921c62373d3e8d3a4bda76c9f6de3), [`19a8658`](https://github.com/mastra-ai/mastra/commit/19a86589c788ef48bb6c1b0612cc82a201857379), [`850af77`](https://github.com/mastra-ai/mastra/commit/850af7779cb87c350804488734544a5b1843de25), [`0f0d1ba`](https://github.com/mastra-ai/mastra/commit/0f0d1ba67bfcb2204e571401662f1eceefc03357), [`a18775a`](https://github.com/mastra-ai/mastra/commit/a18775a693172546ee2378d39b67d4e32895b251), [`1baf2d1`](https://github.com/mastra-ai/mastra/commit/1baf2d152c6881338ff8f114633d5316fe13dd15), [`8c31bcd`](https://github.com/mastra-ai/mastra/commit/8c31bcdb00e597880d5939b1b7d7566fbe5dacae), [`0e32507`](https://github.com/mastra-ai/mastra/commit/0e32507962cdfa5569b7bda5bc6fb3dd34e40b03), [`95b14cd`](https://github.com/mastra-ai/mastra/commit/95b14cdd820e86d97ac05fe568424c513a252e31), [`07c3de7`](https://github.com/mastra-ai/mastra/commit/07c3de7f7bc418beccaea3b5e6b7f7cdda79d492), [`0bf2d93`](https://github.com/mastra-ai/mastra/commit/0bf2d932d20e2936f2d9abb8c0a86e24fbc97ec6), [`7b0d34c`](https://github.com/mastra-ai/mastra/commit/7b0d34cfe4a2fce22ac86ae17404685ff67a2ddb), [`a659a77`](https://github.com/mastra-ai/mastra/commit/a659a779bdebe3a52a518c56d2260592d0240fe0), [`aa36be2`](https://github.com/mastra-ai/mastra/commit/aa36be23aa513b7dc53cb8ca16b7fab8f20e43ad), [`3332be9`](https://github.com/mastra-ai/mastra/commit/3332be9701ecd77aba840959d9a1d1ce7aef02d3), [`212c635`](https://github.com/mastra-ai/mastra/commit/212c635203e61d036ab41db8ff86c3893dc795b3), [`d8838ae`](https://github.com/mastra-ai/mastra/commit/d8838ae80b69780361693d27098f7f6684af12fe), [`9aa5a73`](https://github.com/mastra-ai/mastra/commit/9aa5a73e7e110f6e9365eec69364a33d5f03bb56), [`f73c789`](https://github.com/mastra-ai/mastra/commit/f73c789e8ef21561580395d2c410119cab5848c8), [`8bd16da`](https://github.com/mastra-ai/mastra/commit/8bd16da73a4cb874d739373643dbd6a6e7f88684), [`c8630f8`](https://github.com/mastra-ai/mastra/commit/c8630f80d4f40cb5d22e60ab162b618b1907167a), [`94dfef6`](https://github.com/mastra-ai/mastra/commit/94dfef6e2bf19a88467ea3940afcbce88a433f0f), [`47f71dc`](https://github.com/mastra-ai/mastra/commit/47f71dc6fbcbd12d71e21a979e676e20a02bd77d), [`50ceae2`](https://github.com/mastra-ai/mastra/commit/50ceae270878e2f8fb2b2c6c2faab09df0007c8a), [`a122f79`](https://github.com/mastra-ai/mastra/commit/a122f79427ae225ec79c7b2ed46278da48d04b17), [`8cdde58`](https://github.com/mastra-ai/mastra/commit/8cdde5875bbba6702d9df226f2b20232b8d75d6c), [`3a081c1`](https://github.com/mastra-ai/mastra/commit/3a081c1255c5ae8c99f6dad91cc612934ef6f2bd), [`49f8abc`](https://github.com/mastra-ai/mastra/commit/49f8abce8258e4f2f87bd326acfbdb641264a47c), [`847ff1e`](https://github.com/mastra-ai/mastra/commit/847ff1e0d94368d94b2e173e4e0908e115568ef3), [`0c1ed1d`](https://github.com/mastra-ai/mastra/commit/0c1ed1d00c7d87b5ac99ca95896211a2fa9189fa), [`259d409`](https://github.com/mastra-ai/mastra/commit/259d409a514174299dbde1ff5e1121209b3ba850), [`9e16c68`](https://github.com/mastra-ai/mastra/commit/9e16c6818b6485ccb43df28aba6f3a2219d28662), [`cefca33`](https://github.com/mastra-ai/mastra/commit/cefca33ae666e69810c935fedf95a929c173d1d7), [`d00e8c5`](https://github.com/mastra-ai/mastra/commit/d00e8c50daebe5bce5bf2f48bde39c86fc3d2fe4), [`36fa7e2`](https://github.com/mastra-ai/mastra/commit/36fa7e24d14e58a1eb46147097b32f583e5b8775), [`87e9774`](https://github.com/mastra-ai/mastra/commit/87e97741c1e493cd6d62f478eb810b49bda4d57c), [`65a72e7`](https://github.com/mastra-ai/mastra/commit/65a72e70c25eedea8ff985a6624b96be2850236b), [`fe9eacd`](https://github.com/mastra-ai/mastra/commit/fe9eacd9545a0a9d64aad31c9fa90294a425289e), [`4c02027`](https://github.com/mastra-ai/mastra/commit/4c020277235eaa6b1dc957c90ad0639eef213992), [`0f77241`](https://github.com/mastra-ai/mastra/commit/0f7724108806703799a8ba80ad0f09414afd5066), [`849efb9`](https://github.com/mastra-ai/mastra/commit/849efb9fca6dc976589c1f90a303fea618769109), [`92ff509`](https://github.com/mastra-ai/mastra/commit/92ff5098ef8a990438ca038077021a5f7541ec1d), [`3fce5e7`](https://github.com/mastra-ai/mastra/commit/3fce5e70d011d289043e75003ef3336ed4aa43c3), [`a763592`](https://github.com/mastra-ai/mastra/commit/a763592c3db46963ef1011cfe16fe372816e775e), [`db79c86`](https://github.com/mastra-ai/mastra/commit/db79c86c60723d57e02f9636ca2611bd4515f194), [`6855012`](https://github.com/mastra-ai/mastra/commit/685501247cc4717506f3e89beed03509d63a5370), [`80c7737`](https://github.com/mastra-ai/mastra/commit/80c7737e32d7917b5f356957d67c169d01744fd3), [`7fef31c`](https://github.com/mastra-ai/mastra/commit/7fef31c0d2a6d362a43a647a8a4f6ab893758a23), [`7fef31c`](https://github.com/mastra-ai/mastra/commit/7fef31c0d2a6d362a43a647a8a4f6ab893758a23), [`3f1cf47`](https://github.com/mastra-ai/mastra/commit/3f1cf476f74c1e4cc2df908837e05853a5347e31)]:
+  - @mastra/core@1.38.0
+
 ## 0.3.0-alpha.1
 
 ### Minor Changes

package/dist/index.cjs

@@ -316,13 +316,16 @@ function createCloseTool(browser) {
     inputSchema: closeInputSchema,
     execute: async (_input, { agent }) => {
       const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
       if (browser.getScope() !== "shared") {
         if (!threadId) {
           throw new Error("browser_close requires agent.threadId when browser scope is not shared");
         }
+        browser.markBrowserCloseReason("agent", threadId);
         await browser.closeThreadSession(threadId);
         return { success: true, hint: "Thread's browser session closed. A new session will be created on next use." };
       }
+      browser.markBrowserCloseReason("agent");
       await browser.close();
       return { success: true, hint: "Browser closed. It will be re-launched automatically on next use." };
     }
@@ -573,6 +576,8 @@ var AgentBrowser = class extends browser.MastraBrowser {
   defaultTimeout = 3e4;
   /** Pending PID lookups — awaited in disconnect handlers to avoid racing. */
   pidLookups = /* @__PURE__ */ new Set();
+  pendingCloseReasons = /* @__PURE__ */ new Map();
+  activeUrlChangeSources = /* @__PURE__ */ new Map();
   browserConfig;
   constructor(config = {}) {
     super(config);
@@ -641,6 +646,8 @@ var AgentBrowser = class extends browser.MastraBrowser {
   // Lifecycle
   // ---------------------------------------------------------------------------
   async doLaunch() {
+    this.pendingCloseReasons.clear();
+    this.activeUrlChangeSources.clear();
     const scope = this.threadManager.getScope();
     if (scope === "thread") {
       this.sharedManager = new agentBrowser.BrowserManager();
@@ -677,6 +684,7 @@ var AgentBrowser = class extends browser.MastraBrowser {
       const handleDisconnect = () => {
         if (disconnectHandled) return;
         disconnectHandled = true;
+        this.rememberClosedBrowserState(manager, "user");
         void pidLookup.catch(() => void 0).then(() => this.handleBrowserDisconnected());
       };
       const context = manager.getContext();
@@ -706,6 +714,14 @@ var AgentBrowser = class extends browser.MastraBrowser {
     }
     this.sharedManager = null;
   }
+  async closeThreadSession(threadId) {
+    const manager = this.threadManager.getExistingManagerForThread(threadId);
+    if (manager) {
+      const state = this.getBrowserStateForManager(manager, threadId);
+      if (state) this.threadManager.updateBrowserState(threadId, state);
+    }
+    await super.closeThreadSession(threadId);
+  }
   /**
    * Check if the browser is still alive by verifying the page is connected.
    * Called by base class ensureReady() to detect externally closed browsers.
@@ -756,6 +772,32 @@ var AgentBrowser = class extends browser.MastraBrowser {
   // ---------------------------------------------------------------------------
   // Helpers
   // ---------------------------------------------------------------------------
+  browserStateKey(threadId) {
+    return threadId ?? this.getCurrentThread() ?? browser.DEFAULT_THREAD_ID;
+  }
+  markBrowserCloseReason(reason, threadId) {
+    this.pendingCloseReasons.set(this.browserStateKey(threadId), reason);
+  }
+  markActiveUrlChangeSource(source, url, threadId) {
+    this.activeUrlChangeSources.set(this.browserStateKey(threadId), { url, source });
+  }
+  getCloseReason(threadId) {
+    return this.pendingCloseReasons.get(this.browserStateKey(threadId)) ?? this.pendingCloseReasons.get(browser.DEFAULT_THREAD_ID);
+  }
+  getActiveUrlChangeSource(activeUrl, threadId) {
+    const entry = this.activeUrlChangeSources.get(this.browserStateKey(threadId));
+    return entry && entry.url === activeUrl ? entry.source : void 0;
+  }
+  rememberClosedBrowserState(manager, reason, threadId) {
+    const state = this.getBrowserStateForManager(manager, threadId);
+    if (!state || state.tabs.length === 0) return;
+    const closedState = { ...state, closeReason: this.getCloseReason(threadId) ?? reason };
+    if (threadId) {
+      this.threadManager.updateBrowserState(threadId, closedState);
+    } else {
+      this.lastBrowserState = closedState;
+    }
+  }
   /**
    * Get the page for the current thread.
    * Uses thread scope if enabled, otherwise returns the shared page.
@@ -798,6 +840,7 @@ var AgentBrowser = class extends browser.MastraBrowser {
       const handleDisconnect = () => {
         if (disconnectHandled) return;
         disconnectHandled = true;
+        this.rememberClosedBrowserState(manager, "user", threadId);
         void pidLookup.catch(() => void 0).then(() => this.handleThreadBrowserDisconnected(threadId));
       };
       const context = manager.getContext();
@@ -929,12 +972,12 @@ var AgentBrowser = class extends browser.MastraBrowser {
    * Get the current browser state (all tabs and active tab index).
    */
   async getBrowserState(threadId) {
-    if (!this.isBrowserRunning()) {
+    if (!this.isBrowserRunning(threadId)) {
       return null;
     }
     try {
       const manager = await this.getManagerForThread(threadId);
-      return this.getBrowserStateForManager(manager);
+      return this.getBrowserStateForManager(manager, threadId);
     } catch {
       return null;
     }
@@ -947,22 +990,32 @@ var AgentBrowser = class extends browser.MastraBrowser {
     const effectiveThreadId = threadId ?? this.getCurrentThread() ?? browser.DEFAULT_THREAD_ID;
     const manager = this.threadManager.getExistingManagerForThread(effectiveThreadId);
     if (!manager) return null;
-    return this.getBrowserStateForManager(manager);
+    return this.getBrowserStateForManager(manager, effectiveThreadId);
   }
   /**
    * Get browser state from a specific manager instance.
    */
-  getBrowserStateForManager(manager) {
+  getBrowserStateForManager(manager, threadId) {
     try {
+      const stateKey = this.browserStateKey(threadId);
       const pages = manager.getPages();
       const activeIndex = manager.getActiveIndex();
       const tabs = pages.map((page) => ({
         url: page.url()
       }));
-      return {
+      const activeUrl = tabs[activeIndex]?.url;
+      const previousState = this.threadManager.getSavedBrowserState(stateKey) ?? this.lastBrowserState;
+      const previousUrl = previousState?.tabs[previousState.activeTabIndex]?.url;
+      const activeUrlChangeSource = this.getActiveUrlChangeSource(activeUrl, stateKey) ?? (previousUrl && activeUrl !== previousUrl ? "user" : void 0);
+      const state = {
         tabs,
-        activeTabIndex: activeIndex
+        activeTabIndex: activeIndex,
+        ...this.getCloseReason(stateKey) ? { closeReason: this.getCloseReason(stateKey) } : {},
+        ...activeUrlChangeSource ? { activeUrlChangeSource } : {}
       };
+      this.threadManager.updateBrowserState(stateKey, state);
+      this.lastBrowserState = state;
+      return state;
     } catch {
       return null;
     }
@@ -1017,9 +1070,11 @@ var AgentBrowser = class extends browser.MastraBrowser {
         timeout: input.timeout ?? this.defaultTimeout,
         waitUntil: input.waitUntil ?? "domcontentloaded"
       });
+      const url = page.url();
+      this.markActiveUrlChangeSource("agent", url, threadId);
       return {
         success: true,
-        url: page.url(),
+        url,
         title: await page.title(),
         hint: "Take a snapshot to see interactive elements and get refs."
       };
@@ -1306,9 +1361,11 @@ var AgentBrowser = class extends browser.MastraBrowser {
     try {
       const page = await this.getPage(threadId);
       await page.goBack({ timeout: this.defaultTimeout });
+      const url = page.url();
+      this.markActiveUrlChangeSource("agent", url, threadId);
       return {
         success: true,
-        url: page.url(),
+        url,
         title: await page.title(),
         hint: "Take a new snapshot to see the previous page."
       };
@@ -1439,6 +1496,7 @@ var AgentBrowser = class extends browser.MastraBrowser {
           if (input.url) {
             const page = await this.getPage(threadId);
             await page.goto(input.url);
+            this.markActiveUrlChangeSource("agent", page.url(), threadId);
           }
           this.updateSessionBrowserState(threadId);
           return {
@@ -1459,6 +1517,7 @@ var AgentBrowser = class extends browser.MastraBrowser {
           await this.reconnectScreencastForThread(threadId, "tab switch");
           const page = browser.getPage();
           const pageUrl = page.url();
+          this.markActiveUrlChangeSource("agent", pageUrl, threadId);
           const streamKey = this.getStreamKey(threadId);
           const stream = this.activeScreencastStreams.get(streamKey);
           if (pageUrl && stream?.isActive()) {