@mastra/stagehand 0.1.0 → 0.2.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @mastra/stagehand
 
+## 0.2.0-alpha.0
+
+### Minor Changes
+
+- Added automatic cleanup on browser close: patches `exit_type` to prevent restore dialogs, kills orphaned Chrome child processes, and uses CDP events for reliable disconnect detection in both shared and thread scope. ([#15194](https://github.com/mastra-ai/mastra/pull/15194))
+
+### Patch Changes
+
+- dependencies updates: ([#15209](https://github.com/mastra-ai/mastra/pull/15209))
+  - Updated dependency [`@browserbasehq/stagehand@^3.2.1` ↗︎](https://www.npmjs.com/package/@browserbasehq/stagehand/v/3.2.1) (from `^3.2.0`, in `dependencies`)
+- 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
 
 ### Minor Changes

package/README.md

@@ -11,12 +11,12 @@ npm install @mastra/stagehand
 ## Usage
 
 ```typescript
-import { Agent } from '@mastra/core';
+import { Agent } from '@mastra/core/agent';
 import { StagehandBrowser } from '@mastra/stagehand';
 
 // Create a Stagehand browser
 const browser = new StagehandBrowser({
-  model: 'openai/gpt-4o',
+  model: 'openai/gpt-5.4',
   headless: true,
 });
 
@@ -24,7 +24,7 @@ const browser = new StagehandBrowser({
 const agent = new Agent({
   name: 'web-agent',
   instructions: 'You are a helpful web assistant.',
-  model: { provider: 'openai', modelId: 'gpt-4o' },
+  model: 'openai/gpt-5.4',
   browser,
 });
 
@@ -39,17 +39,20 @@ const browser = new StagehandBrowser({
   // Environment: 'LOCAL' or 'BROWSERBASE'
   env: 'LOCAL',
 
-  // Model for AI operations (default: 'openai/gpt-4o')
-  model: 'openai/gpt-4o',
+  // Model for AI operations (default: 'openai/gpt-5.4')
+  model: 'openai/gpt-5.4',
   // Or with custom config:
   model: {
-    modelName: 'openai/gpt-4o',
+    modelName: 'gpt-5.4',
     apiKey: process.env.OPENAI_API_KEY,
   },
 
   // Run headless (default: true)
   headless: true,
 
+  // Viewport dimensions
+  viewport: { width: 1280, height: 720 },
+
   // CDP URL for connecting to existing browser
   cdpUrl: 'ws://localhost:9222',
 
@@ -57,8 +60,17 @@ const browser = new StagehandBrowser({
   apiKey: process.env.BROWSERBASE_API_KEY,
   projectId: process.env.BROWSERBASE_PROJECT_ID,
 
+  // Enable self-healing selectors (default: true)
+  selfHeal: true,
+
+  // DOM settle timeout in ms (default: 5000)
+  domSettleTimeout: 5000,
+
   // Logging verbosity (0: silent, 1: errors, 2: verbose)
   verbose: 1,
+
+  // Custom system prompt for AI operations
+  systemPrompt: 'Focus on finding interactive elements',
 });
 ```
 
@@ -68,25 +80,30 @@ StagehandBrowser exposes 6 AI-powered tools:
 
 ### Core AI Tools
 
-- **stagehand_act** - Perform actions using natural language
+- **stagehand_act** - Perform actions using natural language instructions
 - **stagehand_extract** - Extract structured data from pages
-- **stagehand_observe** - Discover actionable elements
+- **stagehand_observe** - Discover actionable elements on the page
 
 ### Navigation & State
 
 - **stagehand_navigate** - Navigate to a URL
-- **stagehand_screenshot** - Take screenshots
+- **stagehand_tabs** - List, switch, open, or close browser tabs
 - **stagehand_close** - Close the browser
 
 ## Comparison with AgentBrowser
 
-| Feature     | AgentBrowser                  | StagehandBrowser             |
-| ----------- | ----------------------------- | ---------------------------- |
-| Approach    | Deterministic refs ([ref=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        |
+| 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
+
+- [Stagehand guide](https://mastra.ai/docs/browser/stagehand) - Usage guide
+- [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser) - API reference
 
 ## License
 

package/dist/index.cjs

@@ -1,9 +1,11 @@
 'use strict';
 
+var fs = require('fs');
 var stagehand = require('@browserbasehq/stagehand');
 var browser = require('@mastra/core/browser');
 var tools = require('@mastra/core/tools');
 var zod = require('zod');
+var path = require('path');
 
 // src/stagehand-browser.ts
 var StagehandThreadManager = class extends browser.ThreadManager {
@@ -280,6 +282,30 @@ function createStagehandTools(browser) {
     [STAGEHAND_TOOLS.CLOSE]: createCloseTool(browser)
   };
 }
+function patchProfileExitType(profilePath, logger) {
+  if (!profilePath) return;
+  const prefsPath = path.join(profilePath, "Default", "Preferences");
+  try {
+    if (!fs.existsSync(prefsPath)) return;
+    const prefs = JSON.parse(fs.readFileSync(prefsPath, "utf-8"));
+    if (prefs?.profile?.exit_type === "Normal") return;
+    prefs.profile = prefs.profile || {};
+    prefs.profile.exit_type = "Normal";
+    fs.writeFileSync(prefsPath, JSON.stringify(prefs, null, 2), "utf-8");
+    logger?.debug?.(`Patched exit_type to Normal in ${prefsPath}`);
+  } catch {
+  }
+}
+function getStagehandChromePid(stagehand) {
+  try {
+    const state = stagehand.state;
+    if (state?.kind !== "LOCAL" || !state.chrome) return void 0;
+    const pid = state.chrome.process?.pid ?? state.chrome.pid;
+    return typeof pid === "number" && pid > 0 ? pid : void 0;
+  } catch {
+    return void 0;
+  }
+}
 
 // src/stagehand-browser.ts
 var StagehandBrowser = class extends browser.MastraBrowser {
@@ -303,7 +329,7 @@ var StagehandBrowser = class extends browser.MastraBrowser {
       },
       // When a new browser is created for a thread, set up close listener
       onBrowserCreated: (stagehand, threadId) => {
-        this.setupCloseListenerForThread(stagehand, threadId);
+        this.setupCloseListener(stagehand, () => this.handleThreadBrowserDisconnected(threadId), threadId);
       }
     });
   }
@@ -346,18 +372,27 @@ var StagehandBrowser = class extends browser.MastraBrowser {
         stagehandOptions.projectId = config.projectId;
       }
     }
+    if (config.profile && !fs.existsSync(config.profile)) {
+      fs.mkdirSync(config.profile, { recursive: true });
+    }
     if (config.cdpUrl && config.env !== "BROWSERBASE") {
       const resolvedUrl = await this.resolveCdpUrl(config.cdpUrl);
       const wsUrl = await this.resolveWebSocketUrl(resolvedUrl);
       stagehandOptions.localBrowserLaunchOptions = {
         cdpUrl: wsUrl,
         headless: config.headless,
-        viewport: config.viewport
+        viewport: config.viewport,
+        userDataDir: config.profile,
+        executablePath: config.executablePath,
+        preserveUserDataDir: config.preserveUserDataDir
       };
     } else if (config.env !== "BROWSERBASE") {
       stagehandOptions.localBrowserLaunchOptions = {
         headless: config.headless,
-        viewport: config.viewport
+        viewport: config.viewport,
+        userDataDir: config.profile,
+        executablePath: config.executablePath,
+        preserveUserDataDir: config.preserveUserDataDir
       };
     }
     return stagehandOptions;
@@ -380,81 +415,54 @@ var StagehandBrowser = class extends browser.MastraBrowser {
     }
     this.sharedManager = await this.createStagehandInstance();
     this.threadManager.setSharedManager(this.sharedManager);
-    this.setupCloseListenerForSharedScope(this.sharedManager);
+    this.setupCloseListener(this.sharedManager, () => this.handleBrowserDisconnected());
   }
   /**
    * Set up close event listener for a shared Stagehand instance.
    * Listens to both context and page close events for robust detection.
    */
-  setupCloseListenerForSharedScope(stagehand) {
-    let disconnectHandled = false;
-    const handleDisconnect = () => {
-      if (disconnectHandled) return;
-      disconnectHandled = true;
-      this.handleBrowserDisconnected();
-    };
-    try {
-      const context = stagehand.context;
-      if (!context) return;
-      const contextWithEvents = context;
-      if (contextWithEvents?.on) {
-        contextWithEvents.on("close", handleDisconnect);
-      }
-      const pages = context.pages?.() ?? [];
-      for (const page of pages) {
-        const pageWithEvents = page;
-        if (pageWithEvents?.on) {
-          pageWithEvents.on("close", () => {
-            const remainingPages = context.pages?.() ?? [];
-            if (remainingPages.length === 0) {
-              handleDisconnect();
-            }
-          });
-        }
-      }
-    } catch {
-    }
-  }
   /**
-   * Set up close event listener for a thread's Stagehand instance.
-   * Uses CDP Target.targetDestroyed events to detect when all pages are gone.
+   * Set up a CDP-based close listener for a Stagehand instance.
+   *
+   * Tracks page targets via CDP `Target.targetCreated` / `Target.targetDestroyed`.
+   * When all page targets are gone the `onDisconnect` callback fires. This is more
+   * reliable than Playwright's `context.close` / `page.close` events which don't
+   * fire when Chrome is killed externally (SIGTERM/SIGKILL).
    */
-  setupCloseListenerForThread(stagehand, threadId) {
+  setupCloseListener(stagehand, onDisconnect, threadId) {
+    const chromePid = getStagehandChromePid(stagehand);
+    if (chromePid != null) {
+      if (threadId) {
+        this.threadBrowserPids.set(threadId, chromePid);
+      } else {
+        this.sharedBrowserPid = chromePid;
+      }
+    }
     let disconnectHandled = false;
     const handleDisconnect = () => {
       if (disconnectHandled) return;
       disconnectHandled = true;
-      this.handleThreadBrowserDisconnected(threadId);
+      onDisconnect();
     };
     try {
       const stagehandAny = stagehand;
       const conn = stagehandAny.ctx?.conn;
-      if (!conn?.on) {
-        return;
-      }
+      if (!conn?.on) return;
       const pageTargets = /* @__PURE__ */ new Set();
       const context = stagehand.context;
       if (context) {
-        const pages = context.pages?.() ?? [];
-        for (const page of pages) {
-          const pageAny = page;
-          const targetId = pageAny._targetId ?? pageAny.targetId;
-          if (targetId) {
-            pageTargets.add(targetId);
-          }
+        for (const page of context.pages?.() ?? []) {
+          const targetId = page._targetId ?? page.targetId;
+          if (targetId) pageTargets.add(targetId);
         }
       }
       conn.on("Target.targetCreated", (params) => {
-        if (params.targetInfo.type === "page") {
-          pageTargets.add(params.targetInfo.targetId);
-        }
+        if (params.targetInfo.type === "page") pageTargets.add(params.targetInfo.targetId);
       });
       conn.on("Target.targetDestroyed", (params) => {
         if (pageTargets.has(params.targetId)) {
           pageTargets.delete(params.targetId);
-          if (pageTargets.size === 0) {
-            handleDisconnect();
-          }
+          if (pageTargets.size === 0) handleDisconnect();
         }
       });
     } catch {
@@ -467,6 +475,23 @@ var StagehandBrowser = class extends browser.MastraBrowser {
       this.sharedManager = null;
     }
     this.setCurrentThread(void 0);
+    this.patchExitType();
+  }
+  handleBrowserDisconnected() {
+    super.handleBrowserDisconnected();
+    this.patchExitType();
+  }
+  handleThreadBrowserDisconnected(threadId) {
+    super.handleThreadBrowserDisconnected(threadId);
+    this.patchExitType();
+  }
+  async closeThreadSession(threadId) {
+    await super.closeThreadSession(threadId);
+    this.patchExitType();
+  }
+  patchExitType() {
+    if (!this.config.profile) return;
+    patchProfileExitType(this.config.profile, this.logger);
   }
   /**
    * Check if the browser is still alive by verifying the context and pages exist.
@@ -1196,6 +1221,7 @@ exports.actInputSchema = actInputSchema;
 exports.closeInputSchema = closeInputSchema;
 exports.createStagehandTools = createStagehandTools;
 exports.extractInputSchema = extractInputSchema;
+exports.getStagehandChromePid = getStagehandChromePid;
 exports.navigateInputSchema = navigateInputSchema;
 exports.observeInputSchema = observeInputSchema;
 exports.stagehandSchemas = stagehandSchemas;