@mastra/agent-browser 0.0.0-studio-deploy-20260404184540 → 0.0.0-studio-cli-20260504022012

package/CHANGELOG.md

@@ -1,11 +1,66 @@
 # @mastra/agent-browser
 
-## 0.0.0-studio-deploy-20260404184540
+## 0.0.0-studio-cli-20260504022012
 
 ### Patch Changes
 
-- Updated dependencies [[`e133cc7`](https://github.com/mastra-ai/mastra/commit/e133cc73c2a73d90a39ad73f724e9cb492466b41), [`c55b527`](https://github.com/mastra-ai/mastra/commit/c55b52758a31368b2077b0dbbc3badfe4063f560), [`e133cc7`](https://github.com/mastra-ai/mastra/commit/e133cc73c2a73d90a39ad73f724e9cb492466b41), [`e133cc7`](https://github.com/mastra-ai/mastra/commit/e133cc73c2a73d90a39ad73f724e9cb492466b41), [`7eb2596`](https://github.com/mastra-ai/mastra/commit/7eb25960d607e07468c9a10c5437abd2deaf1e9a)]:
-  - @mastra/core@0.0.0-studio-deploy-20260404184540
+- Updated dependencies [[`6dcd65f`](https://github.com/mastra-ai/mastra/commit/6dcd65f2a34069e6dc43ba35f1d11119b9b40bef), [`c05c9a1`](https://github.com/mastra-ai/mastra/commit/c05c9a13230988cef6d438a62f37760f31927bc7), [`e24aacb`](https://github.com/mastra-ai/mastra/commit/e24aacba07bd66f5d95b636dc24016fca26b52cf), [`1c2dda8`](https://github.com/mastra-ai/mastra/commit/1c2dda805fbfccc0abf55d4cb20cc34402dc3f0c), [`c721164`](https://github.com/mastra-ai/mastra/commit/c7211643f7ac861f83b19a3757cc921487fc9d75), [`1b55954`](https://github.com/mastra-ai/mastra/commit/1b559541c1e08a10e49d01ffc51a634dfc37a286), [`5adc55e`](https://github.com/mastra-ai/mastra/commit/5adc55e63407be8ee977914957d68bcc2a075ceb), [`70017d7`](https://github.com/mastra-ai/mastra/commit/70017d72ab741b5d7040e2a15c251a317782e39e), [`e4942bc`](https://github.com/mastra-ai/mastra/commit/e4942bc7fdc903572f7d84f26d5e15f9d39c763d)]:
+  - @mastra/core@0.0.0-studio-cli-20260504022012
+
+## 0.2.1
+
+### Patch Changes
+
+- Standardize `headless` default to `true` across all browser providers. Each provider now resolves `headless` once in its constructor and passes it to the thread manager via the base class getter, removing duplicate fallback logic. ([#15696](https://github.com/mastra-ai/mastra/pull/15696))
+
+- Fixed `browser_evaluate` so expression scripts now return their computed value instead of `undefined` (for example, `document.querySelectorAll('a').length`). ([#15689](https://github.com/mastra-ai/mastra/pull/15689))
+
+- Updated dependencies [[`733bf53`](https://github.com/mastra-ai/mastra/commit/733bf53d9352aedd3ef38c3d501edb275b65b43c), [`5405b3b`](https://github.com/mastra-ai/mastra/commit/5405b3b35325c5b8fb34fc7ac109bd2feb7bb6fe), [`45e29cb`](https://github.com/mastra-ai/mastra/commit/45e29cb5b5737f3083eb3852db02b944b9cf37ed), [`750b4d3`](https://github.com/mastra-ai/mastra/commit/750b4d3d8231f92e769b2c485921ac5a8ca639b9), [`c321127`](https://github.com/mastra-ai/mastra/commit/c3211275fc195de9ad1ead2746b354beb8eae6e8), [`a07bcef`](https://github.com/mastra-ai/mastra/commit/a07bcefea77c03d6d322caad973dca49b4b15fa1), [`696694e`](https://github.com/mastra-ai/mastra/commit/696694e00f29241a25dd1a1b749afa06c3a626b4), [`b084a80`](https://github.com/mastra-ai/mastra/commit/b084a800db0f82d62e1fc3d6e3e3480da1ba5a53), [`82b7a96`](https://github.com/mastra-ai/mastra/commit/82b7a964169636c1d1e0c694fc892a213b0179d5), [`df97812`](https://github.com/mastra-ai/mastra/commit/df97812bd949dcafeb074b80ecab501724b49c3b), [`8bbe360`](https://github.com/mastra-ai/mastra/commit/8bbe36042af7fc4be0244dffd8913f6795179421), [`f6b8ba8`](https://github.com/mastra-ai/mastra/commit/f6b8ba8dbf533b7a8db90c72b6805ddc804a3a72), [`a07bcef`](https://github.com/mastra-ai/mastra/commit/a07bcefea77c03d6d322caad973dca49b4b15fa1)]:
+  - @mastra/core@1.28.0
+
+## 0.2.1-alpha.1
+
+### Patch Changes
+
+- Standardize `headless` default to `true` across all browser providers. Each provider now resolves `headless` once in its constructor and passes it to the thread manager via the base class getter, removing duplicate fallback logic. ([#15696](https://github.com/mastra-ai/mastra/pull/15696))
+
+- Updated dependencies [[`750b4d3`](https://github.com/mastra-ai/mastra/commit/750b4d3d8231f92e769b2c485921ac5a8ca639b9)]:
+  - @mastra/core@1.28.0-alpha.1
+
+## 0.2.1-alpha.0
+
+### Patch Changes
+
+- Fixed `browser_evaluate` so expression scripts now return their computed value instead of `undefined` (for example, `document.querySelectorAll('a').length`). ([#15689](https://github.com/mastra-ai/mastra/pull/15689))
+
+- Updated dependencies [[`733bf53`](https://github.com/mastra-ai/mastra/commit/733bf53d9352aedd3ef38c3d501edb275b65b43c), [`5405b3b`](https://github.com/mastra-ai/mastra/commit/5405b3b35325c5b8fb34fc7ac109bd2feb7bb6fe), [`c321127`](https://github.com/mastra-ai/mastra/commit/c3211275fc195de9ad1ead2746b354beb8eae6e8), [`a07bcef`](https://github.com/mastra-ai/mastra/commit/a07bcefea77c03d6d322caad973dca49b4b15fa1), [`b084a80`](https://github.com/mastra-ai/mastra/commit/b084a800db0f82d62e1fc3d6e3e3480da1ba5a53), [`82b7a96`](https://github.com/mastra-ai/mastra/commit/82b7a964169636c1d1e0c694fc892a213b0179d5), [`df97812`](https://github.com/mastra-ai/mastra/commit/df97812bd949dcafeb074b80ecab501724b49c3b), [`8bbe360`](https://github.com/mastra-ai/mastra/commit/8bbe36042af7fc4be0244dffd8913f6795179421), [`f6b8ba8`](https://github.com/mastra-ai/mastra/commit/f6b8ba8dbf533b7a8db90c72b6805ddc804a3a72), [`a07bcef`](https://github.com/mastra-ai/mastra/commit/a07bcefea77c03d6d322caad973dca49b4b15fa1)]:
+  - @mastra/core@1.28.0-alpha.0
+
+## 0.2.0
+
+### Minor Changes
+
+- Added `storageState` option and `exportStorageState()` method for lightweight auth persistence (cookies and localStorage). Also kills orphaned Chrome child processes on close to prevent zombies. ([#15194](https://github.com/mastra-ai/mastra/pull/15194))
+
+### Patch Changes
+
+- AgentBrowser with default thread scope now initializes correctly. Previously, calling launch() followed by getPage() would throw "Browser not launched" when no explicit thread ID was provided. ([#15285](https://github.com/mastra-ai/mastra/pull/15285))
+
+- Updated dependencies [[`87df955`](https://github.com/mastra-ai/mastra/commit/87df955c028660c075873fd5d74af28233ce32eb), [`8fad147`](https://github.com/mastra-ai/mastra/commit/8fad14759804179c8e080ce4d9dec6ef1a808b31), [`582644c`](https://github.com/mastra-ai/mastra/commit/582644c4a87f83b4f245a84d72b9e8590585012e), [`cbdf3e1`](https://github.com/mastra-ai/mastra/commit/cbdf3e12b3d0c30a6e5347be658e2009648c130a), [`8fe46d3`](https://github.com/mastra-ai/mastra/commit/8fe46d354027f3f0f0846e64219772348de106dd), [`18c67db`](https://github.com/mastra-ai/mastra/commit/18c67dbb9c9ebc26f26f65f7d3ff836e5691ef46), [`4ba3bb1`](https://github.com/mastra-ai/mastra/commit/4ba3bb1e465ad2ddaba3bbf2bc47e0faec32985e), [`5d84914`](https://github.com/mastra-ai/mastra/commit/5d84914e0e520c642a40329b210b413fcd139898), [`8dcc77e`](https://github.com/mastra-ai/mastra/commit/8dcc77e78a5340f5848f74b9e9f1b3da3513c1f5), [`aa67fc5`](https://github.com/mastra-ai/mastra/commit/aa67fc59ee8a5eeff1f23eb05970b8d7a536c8ff), [`fd2f314`](https://github.com/mastra-ai/mastra/commit/fd2f31473d3449b6b97e837ef8641264377f41a7), [`fa8140b`](https://github.com/mastra-ai/mastra/commit/fa8140bcd4251d2e3ac85fdc5547dfc4f372b5be), [`190f452`](https://github.com/mastra-ai/mastra/commit/190f45258b0640e2adfc8219fa3258cdc5b8f071), [`e80fead`](https://github.com/mastra-ai/mastra/commit/e80fead1412cc0d1b2f7d6a1ce5017d9e0098ff7), [`0287b64`](https://github.com/mastra-ai/mastra/commit/0287b644a5c3272755cf3112e71338106664103b), [`7e7bf60`](https://github.com/mastra-ai/mastra/commit/7e7bf606886bf374a6f9d4ca9b09dd83d0533372), [`184907d`](https://github.com/mastra-ai/mastra/commit/184907d775d8609c03c26e78ccaf37315f3aa287), [`075e91a`](https://github.com/mastra-ai/mastra/commit/075e91a4549baf46ad7a42a6a8ac8dfa78cc09e6), [`0c4cd13`](https://github.com/mastra-ai/mastra/commit/0c4cd131931c04ac5405373c932a242dbe88edd6), [`b16a753`](https://github.com/mastra-ai/mastra/commit/b16a753d5748440248d7df82e29bb987a9c8386c)]:
+  - @mastra/core@1.25.0
+
+## 0.2.0-alpha.0
+
+### Minor Changes
+
+- Added `storageState` option and `exportStorageState()` method for lightweight auth persistence (cookies and localStorage). Also kills orphaned Chrome child processes on close to prevent zombies. ([#15194](https://github.com/mastra-ai/mastra/pull/15194))
+
+### Patch Changes
+
+- AgentBrowser with default thread scope now initializes correctly. Previously, calling launch() followed by getPage() would throw "Browser not launched" when no explicit thread ID was provided. ([#15285](https://github.com/mastra-ai/mastra/pull/15285))
+
+- Updated dependencies [[`cbdf3e1`](https://github.com/mastra-ai/mastra/commit/cbdf3e12b3d0c30a6e5347be658e2009648c130a), [`8fe46d3`](https://github.com/mastra-ai/mastra/commit/8fe46d354027f3f0f0846e64219772348de106dd), [`18c67db`](https://github.com/mastra-ai/mastra/commit/18c67dbb9c9ebc26f26f65f7d3ff836e5691ef46), [`8dcc77e`](https://github.com/mastra-ai/mastra/commit/8dcc77e78a5340f5848f74b9e9f1b3da3513c1f5), [`aa67fc5`](https://github.com/mastra-ai/mastra/commit/aa67fc59ee8a5eeff1f23eb05970b8d7a536c8ff), [`fa8140b`](https://github.com/mastra-ai/mastra/commit/fa8140bcd4251d2e3ac85fdc5547dfc4f372b5be), [`190f452`](https://github.com/mastra-ai/mastra/commit/190f45258b0640e2adfc8219fa3258cdc5b8f071), [`7e7bf60`](https://github.com/mastra-ai/mastra/commit/7e7bf606886bf374a6f9d4ca9b09dd83d0533372), [`184907d`](https://github.com/mastra-ai/mastra/commit/184907d775d8609c03c26e78ccaf37315f3aa287), [`0c4cd13`](https://github.com/mastra-ai/mastra/commit/0c4cd131931c04ac5405373c932a242dbe88edd6), [`b16a753`](https://github.com/mastra-ai/mastra/commit/b16a753d5748440248d7df82e29bb987a9c8386c)]:
+  - @mastra/core@1.25.0-alpha.3
 
 ## 0.1.0
 

package/README.md

@@ -0,0 +1,138 @@
+# @mastra/agent-browser
+
+Deterministic browser automation for Mastra agents using [agent-browser](https://github.com/vercel-labs/agent-browser).
+
+## Installation
+
+```bash
+npm install @mastra/agent-browser
+```
+
+## Usage
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { AgentBrowser } from '@mastra/agent-browser';
+
+// Create an AgentBrowser instance
+const browser = new AgentBrowser({
+  headless: true,
+});
+
+// Create an agent with the browser
+const agent = new Agent({
+  name: 'web-agent',
+  instructions: `You are a web automation assistant.
+Use browser_snapshot to see the page structure,
+then interact with elements using their refs (e.g., @e5).`,
+  model: 'openai/gpt-5.4',
+  browser,
+});
+
+// Use the agent to browse the web
+const result = await agent.generate('Go to example.com and click the first link');
+```
+
+## Configuration
+
+```typescript
+const browser = new AgentBrowser({
+  // Run headless (default: true)
+  headless: true,
+
+  // Viewport dimensions
+  viewport: { width: 1280, height: 720 },
+
+  // Default timeout for operations in ms (default: 30000)
+  timeout: 30000,
+
+  // CDP URL for connecting to existing browser
+  cdpUrl: 'ws://localhost:9222',
+
+  // Browser instance scope
+  // Default: 'thread' for local launch, 'shared' when cdpUrl is provided
+  // 'thread': Each thread gets its own browser
+  // 'shared': All threads share one browser
+  scope: 'thread',
+
+  // Screencast settings for Studio
+  screencast: {
+    enabled: true,
+    format: 'jpeg',
+    quality: 80,
+  },
+});
+```
+
+## Tools
+
+AgentBrowser exposes 15 deterministic tools using accessibility tree refs:
+
+### Core Tools
+
+- **browser_goto** - Navigate to a URL
+- **browser_snapshot** - Get accessibility tree with element refs (@e1, @e2, etc.)
+- **browser_click** - Click an element by ref
+- **browser_type** - Type text into an element
+- **browser_press** - Press keyboard keys
+- **browser_select** - Select option from dropdown
+- **browser_scroll** - Scroll the page or element
+- **browser_close** - Close the browser
+
+### Extended Tools
+
+- **browser_hover** - Hover over an element
+- **browser_back** - Go back in browser history
+- **browser_dialog** - Handle browser dialogs (alert, confirm, prompt)
+- **browser_wait** - Wait for element state changes
+- **browser_tabs** - Manage browser tabs (list, new, switch, close)
+- **browser_drag** - Drag and drop elements
+
+### Escape Hatch
+
+- **browser_evaluate** - Execute JavaScript in the page context
+
+## How Refs Work
+
+AgentBrowser uses accessibility tree refs for precise element targeting:
+
+1. Call `browser_snapshot` to get the page structure with refs
+2. Find the element you want to interact with
+3. Use its ref with other tools
+
+```text
+[document] Example Page
+  [banner]
+    [link @e1] Home
+    [link @e2] About
+  [main]
+    [textbox @e3] Search...
+    [button @e4] Submit
+```
+
+```typescript
+// Type in the search box
+{ tool: "browser_type", input: { ref: "@e3", text: "mastra" } }
+
+// Click submit
+{ tool: "browser_click", input: { ref: "@e4" } }
+```
+
+## Comparison with StagehandBrowser
+
+| Feature     | AgentBrowser             | StagehandBrowser             |
+| ----------- | ------------------------ | ---------------------------- |
+| Approach    | Deterministic refs (@e1) | Natural language             |
+| Token cost  | Low                      | Higher (LLM calls)           |
+| Speed       | Fast                     | Slower                       |
+| Reliability | High (exact refs)        | Variable (AI interpretation) |
+| Best for    | Structured workflows     | Unknown/dynamic pages        |
+
+## Documentation
+
+- [agent-browser guide](https://mastra.ai/docs/browser/agent-browser) - Usage guide
+- [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser) - API reference
+
+## License
+
+Apache-2.0

package/dist/index.cjs

@@ -36,8 +36,11 @@ var AgentBrowserThreadManager = class extends browser.ThreadManager {
     if (this.scope === "thread") {
       const manager = new agentBrowser.BrowserManager();
       const launchOptions = {
-        headless: this.browserConfig.headless ?? true,
-        viewport: this.browserConfig.viewport
+        headless: this.browserConfig.headless,
+        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);
@@ -218,7 +221,9 @@ var dragInputSchema = zod.z.object({
   }
 });
 var evaluateInputSchema = zod.z.object({
-  script: zod.z.string().describe("JavaScript code to execute"),
+  script: zod.z.string().describe(
+    "JavaScript expression to evaluate in the browser and return the result. Do not use `return` \u2014 write a bare expression like `document.title` or `1 + 1`. For async code, wrap in an async IIFE: `(async () => { ... })()`."
+  ),
   arg: zod.z.unknown().optional().describe("Argument to pass to the script (JSON-serializable)")
 });
 var browserSchemas = {
@@ -491,12 +496,36 @@ 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 extends browser.MastraBrowser {
   id;
   name = "AgentBrowser";
   provider = "vercel-labs/agent-browser";
   defaultTimeout = 3e4;
+  /** Pending PID lookups — awaited in disconnect handlers to avoid racing. */
+  pidLookups = /* @__PURE__ */ new Set();
   constructor(config = {}) {
     super(config);
     this.id = `agent-browser-${Date.now()}`;
@@ -506,7 +535,7 @@ var AgentBrowser = class extends browser.MastraBrowser {
     const effectiveScope = config.cdpUrl ? config.scope ?? "shared" : config.scope ?? "thread";
     this.threadManager = new AgentBrowserThreadManager({
       scope: effectiveScope,
-      browserConfig: config,
+      browserConfig: { ...config, headless: this.headless },
       resolveCdpUrl: this.resolveCdpUrl.bind(this),
       logger: this.logger,
       // When a new thread session is created, notify listeners so screencast can start
@@ -534,11 +563,11 @@ var AgentBrowser = class 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);
     }
   }
@@ -570,8 +599,11 @@ var AgentBrowser = class extends browser.MastraBrowser {
     this.sharedManager = new agentBrowser.BrowserManager();
     const localConfig = this.config;
     const launchOptions = {
-      headless: localConfig.headless ?? true,
-      viewport: localConfig.viewport
+      headless: this.headless,
+      viewport: localConfig.viewport,
+      profile: localConfig.profile,
+      executablePath: localConfig.executablePath,
+      storageState: localConfig.storageState
     };
     if (localConfig.cdpUrl) {
       launchOptions.cdpUrl = await this.resolveCdpUrl(localConfig.cdpUrl);
@@ -586,11 +618,15 @@ var AgentBrowser = class extends browser.MastraBrowser {
    */
   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) {
@@ -609,6 +645,8 @@ var AgentBrowser = class 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();
@@ -692,11 +730,17 @@ var AgentBrowser = class 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) {
@@ -886,6 +930,25 @@ var AgentBrowser = class extends browser.MastraBrowser {
       return 0;
     }
   }
+  /**
+   * 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)
+   */
+  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
   // ---------------------------------------------------------------------------
@@ -1402,8 +1465,7 @@ var AgentBrowser = class extends browser.MastraBrowser {
   async evaluate(input, threadId) {
     try {
       const page = await this.getPage(threadId);
-      const wrappedScript = `(async () => { ${input.script} })()`;
-      const result = await page.evaluate(wrappedScript);
+      const result = await page.evaluate(input.script);
       return {
         success: true,
         result,
@@ -1564,6 +1626,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;