@mastra/stagehand 0.1.0 → 0.2.0-alpha.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Stagehand } from '@browserbasehq/stagehand';
-import { ThreadManager, ThreadSession, ThreadManagerConfig, BrowserConfigBase, BrowserScope, CdpUrlProvider, MastraBrowser, BrowserToolError, BrowserState, BrowserTabState, ScreencastOptions, ScreencastStream, MouseEventParams, KeyboardEventParams } from '@mastra/core/browser';
+import { ThreadManager, ThreadSession, ThreadManagerConfig, BrowserConfig, MastraBrowser, BrowserToolError, BrowserState, BrowserTabState, ScreencastOptions, ScreencastStream, MouseEventParams, KeyboardEventParams } from '@mastra/core/browser';
 import { Tool } from '@mastra/core/tools';
 import { z } from 'zod';
 
@@ -238,21 +238,22 @@ interface StagehandConfigExtensions {
      * Custom system prompt for AI operations (act, extract, observe)
      */
     systemPrompt?: string;
+    /**
+     * Whether to preserve the user data directory after the browser closes.
+     * By default, Stagehand may clean up temporary user data directories.
+     * Set to `true` to keep the profile data for future sessions.
+     *
+     * Only applicable when `profile` is provided.
+     *
+     * @default false
+     */
+    preserveUserDataDir?: boolean;
 }
 /**
- * Configuration for StagehandBrowser with compile-time enforcement of cdpUrl/scope compatibility.
- *
- * This type enforces that `cdpUrl` and `scope: 'thread'` cannot be used together:
- * - When `cdpUrl` is provided, `scope` must be `'shared'` or omitted
- * - When `scope: 'thread'` is used, `cdpUrl` must not be provided
+ * Configuration for StagehandBrowser.
+ * Extends the base BrowserConfig with Stagehand-specific options.
  */
-type StagehandBrowserConfig = (BrowserConfigBase & StagehandConfigExtensions & {
-    cdpUrl?: undefined;
-    scope?: BrowserScope;
-}) | (BrowserConfigBase & StagehandConfigExtensions & {
-    cdpUrl: CdpUrlProvider;
-    scope?: 'shared';
-});
+type StagehandBrowserConfig = BrowserConfig & StagehandConfigExtensions;
 /**
  * Action returned from observe()
  */
@@ -348,13 +349,20 @@ declare class StagehandBrowser extends MastraBrowser {
      * Set up close event listener for a shared Stagehand instance.
      * Listens to both context and page close events for robust detection.
      */
-    private setupCloseListenerForSharedScope;
     /**
-     * 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).
      */
-    private setupCloseListenerForThread;
+    private setupCloseListener;
     protected doClose(): Promise<void>;
+    handleBrowserDisconnected(): void;
+    protected handleThreadBrowserDisconnected(threadId: string): void;
+    closeThreadSession(threadId: string): Promise<void>;
+    private patchExitType;
     /**
      * Check if the browser is still alive by verifying the context and pages exist.
      * Called by base class ensureReady() to detect externally closed browsers.
@@ -496,6 +504,17 @@ declare class StagehandBrowser extends MastraBrowser {
     injectKeyboardEvent(event: KeyboardEventParams, threadId?: string): Promise<void>;
 }
 
+/**
+ * Extract the Chrome process PID from a Stagehand instance.
+ *
+ * Stagehand stores the chrome-launcher result in `state.chrome` after init.
+ * The PID is at `chrome.process?.pid ?? chrome.pid`. This isn't part of
+ * Stagehand's public API, so we access it via `as any`.
+ *
+ * Returns undefined if the PID can't be found (e.g. BROWSERBASE env, not yet init'd).
+ */
+declare function getStagehandChromePid(stagehand: Stagehand): number | undefined;
+
 /**
  * Stagehand Tool Constants
  */
@@ -521,4 +540,4 @@ type StagehandToolName = (typeof STAGEHAND_TOOLS)[keyof typeof STAGEHAND_TOOLS];
  */
 declare function createStagehandTools(browser: StagehandBrowser): Record<string, Tool<any, any>>;
 
-export { type ActInput, type ActResult, type CloseInput, type ExtractInput, type ExtractResult, type ModelConfiguration, type NavigateInput, type ObserveInput, type ObserveResult, STAGEHAND_TOOLS, type StagehandAction, StagehandBrowser, type StagehandBrowserConfig, type StagehandToolName, type TabsInput, actInputSchema, closeInputSchema, createStagehandTools, extractInputSchema, navigateInputSchema, observeInputSchema, stagehandSchemas, tabsInputSchema };
+export { type ActInput, type ActResult, type CloseInput, type ExtractInput, type ExtractResult, type ModelConfiguration, type NavigateInput, type ObserveInput, type ObserveResult, STAGEHAND_TOOLS, type StagehandAction, StagehandBrowser, type StagehandBrowserConfig, type StagehandToolName, type TabsInput, actInputSchema, closeInputSchema, createStagehandTools, extractInputSchema, getStagehandChromePid, navigateInputSchema, observeInputSchema, stagehandSchemas, tabsInputSchema };

package/dist/index.js

@@ -1,7 +1,9 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { Stagehand } from '@browserbasehq/stagehand';
 import { MastraBrowser, DEFAULT_THREAD_ID, ScreencastStreamImpl, ThreadManager } from '@mastra/core/browser';
 import { createTool } from '@mastra/core/tools';
 import { z } from 'zod';
+import { join } from 'path';
 
 // src/stagehand-browser.ts
 var StagehandThreadManager = class extends ThreadManager {
@@ -278,6 +280,30 @@ function createStagehandTools(browser) {
     [STAGEHAND_TOOLS.CLOSE]: createCloseTool(browser)
   };
 }
+function patchProfileExitType(profilePath, logger) {
+  if (!profilePath) return;
+  const prefsPath = join(profilePath, "Default", "Preferences");
+  try {
+    if (!existsSync(prefsPath)) return;
+    const prefs = JSON.parse(readFileSync(prefsPath, "utf-8"));
+    if (prefs?.profile?.exit_type === "Normal") return;
+    prefs.profile = prefs.profile || {};
+    prefs.profile.exit_type = "Normal";
+    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 MastraBrowser {
@@ -301,7 +327,7 @@ var StagehandBrowser = class extends 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);
       }
     });
   }
@@ -344,18 +370,27 @@ var StagehandBrowser = class extends MastraBrowser {
         stagehandOptions.projectId = config.projectId;
       }
     }
+    if (config.profile && !existsSync(config.profile)) {
+      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;
@@ -378,81 +413,54 @@ var StagehandBrowser = class extends 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 {
@@ -465,6 +473,23 @@ var StagehandBrowser = class extends 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.
@@ -1188,6 +1213,6 @@ var StagehandBrowser = class extends MastraBrowser {
   }
 };
 
-export { STAGEHAND_TOOLS, StagehandBrowser, actInputSchema, closeInputSchema, createStagehandTools, extractInputSchema, navigateInputSchema, observeInputSchema, stagehandSchemas, tabsInputSchema };
+export { STAGEHAND_TOOLS, StagehandBrowser, actInputSchema, closeInputSchema, createStagehandTools, extractInputSchema, getStagehandChromePid, navigateInputSchema, observeInputSchema, stagehandSchemas, tabsInputSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map