@mastra/stagehand 0.1.0-alpha.0 → 0.1.0

package/dist/index.js

@@ -5,71 +5,27 @@ import { z } from 'zod';
 
 // src/stagehand-browser.ts
 var StagehandThreadManager = class extends ThreadManager {
-  sharedStagehand = null;
   sessions = /* @__PURE__ */ new Map();
   createStagehand;
   onBrowserCreated;
-  /** Map of thread ID to dedicated Stagehand instance (for 'thread' mode) */
-  threadStagehands = /* @__PURE__ */ new Map();
   constructor(config) {
     super(config);
     this.createStagehand = config.createStagehand;
     this.onBrowserCreated = config.onBrowserCreated;
   }
-  /**
-   * Set the shared Stagehand instance (called after browser launch).
-   */
-  setStagehand(instance) {
-    this.sharedStagehand = instance;
-  }
-  /**
-   * Clear the shared Stagehand instance (called when browser disconnects).
-   */
-  clearStagehand() {
-    this.sharedStagehand = null;
-  }
   /**
    * Set the factory function for creating new Stagehand instances.
-   * Required for 'browser' scope mode.
+   * Required for 'thread' scope mode.
    */
   setCreateStagehand(factory) {
     this.createStagehand = factory;
   }
   /**
-   * Get the shared Stagehand instance.
-   */
-  getSharedStagehand() {
-    if (!this.sharedStagehand) {
-      throw new Error("Stagehand not initialized");
-    }
-    return this.sharedStagehand;
-  }
-  /**
-   * Get the Stagehand instance for a specific thread.
-   * In 'shared' mode, returns the shared instance.
-   * In 'thread' mode, returns the thread's dedicated instance.
-   */
-  getStagehandForThread(threadId) {
-    if (this.scope === "thread") {
-      const session = this.sessions.get(threadId);
-      return session?.stagehand;
-    }
-    return this.sharedStagehand ?? void 0;
-  }
-  /**
-   * Get the Stagehand page for a thread.
-   * Returns the active page from the thread's Stagehand instance.
-   */
-  getPageForThread(threadId) {
-    const stagehand = this.getStagehandForThread(threadId);
-    return stagehand?.context?.activePage();
-  }
-  /**
-   * Get the shared manager - returns the active page or the Stagehand instance.
+   * Get the page for a specific thread, creating session if needed.
    */
-  getSharedManager() {
-    const stagehand = this.getSharedStagehand();
-    return stagehand.context.activePage() ?? stagehand;
+  async getPageForThread(threadId) {
+    const stagehand = await this.getManagerForThread(threadId);
+    return stagehand?.context?.activePage() ?? null;
   }
   /**
    * Create a new session for a thread.
@@ -88,7 +44,7 @@ var StagehandThreadManager = class extends ThreadManager {
       this.logger?.debug?.(`Creating dedicated Stagehand instance for thread ${threadId}`);
       const stagehand = await this.createStagehand();
       session.stagehand = stagehand;
-      this.threadStagehands.set(threadId, stagehand);
+      this.threadManagers.set(threadId, stagehand);
       if (savedState && savedState.tabs.length > 0) {
         this.logger?.debug?.(`Restoring browser state for thread ${threadId}: ${savedState.tabs.length} tabs`);
         await this.restoreBrowserState(stagehand, savedState);
@@ -127,18 +83,11 @@ var StagehandThreadManager = class extends ThreadManager {
     }
   }
   /**
-   * Switch to an existing session.
-   * For 'thread' mode, no switching needed - each thread has its own instance.
-   * For 'shared' mode, nothing to switch.
-   */
-  async switchToSession(_session) {
-  }
-  /**
-   * Get the manager for a specific session.
+   * Get the manager (Stagehand instance) for a specific session.
    */
   getManagerForSession(session) {
     if (this.scope === "thread" && session.stagehand) {
-      return session.stagehand.context.activePage() ?? session.stagehand;
+      return session.stagehand;
     }
     return this.getSharedManager();
   }
@@ -153,50 +102,14 @@ var StagehandThreadManager = class extends ThreadManager {
       } catch (error) {
         this.logger?.warn?.(`Failed to close Stagehand for thread ${session.threadId}: ${error}`);
       }
-      this.threadStagehands.delete(session.threadId);
     }
   }
   /**
-   * Clean up all thread sessions.
+   * Destroy all sessions (called during browser close).
+   * doDestroySession handles closing individual Stagehand instances.
    */
-  async destroyAll() {
-    for (const [threadId, stagehand] of this.threadStagehands) {
-      try {
-        await stagehand.close();
-      } catch {
-        this.logger?.debug?.(`Failed to close Stagehand for thread: ${threadId}`);
-      }
-    }
-    this.threadStagehands.clear();
-    this.sessions.clear();
-  }
-  /**
-   * Check if any thread Stagehands are still running.
-   */
-  hasActiveThreadStagehands() {
-    return this.threadStagehands.size > 0;
-  }
-  /**
-   * Clear all session tracking without closing browsers.
-   * Used when browsers have been externally closed and we just need to reset state.
-   */
-  clearAllSessions() {
-    this.threadStagehands.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.threadStagehands.delete(threadId);
-    this.sessions.delete(threadId);
+  async destroyAllSessions() {
+    await super.destroyAllSessions();
   }
 };
 var actInputSchema = z.object({
@@ -367,29 +280,18 @@ function createStagehandTools(browser) {
 }
 
 // src/stagehand-browser.ts
-var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
+var StagehandBrowser = class extends MastraBrowser {
   id;
   name = "StagehandBrowser";
   provider = "browserbase/stagehand";
-  stagehand = null;
   stagehandConfig;
-  /** Active screencast streams per thread (for reconnection on tab changes) */
-  activeScreencastStreams = /* @__PURE__ */ new Map();
   /** Debounce timers per thread for tab change reconnection */
   tabChangeDebounceTimers = /* @__PURE__ */ new Map();
-  /** Default key for shared scope */
-  static SHARED_STREAM_KEY = "__shared__";
   constructor(config = {}) {
     super(config);
     this.id = `stagehand-${Date.now()}`;
     this.stagehandConfig = config;
-    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 StagehandThreadManager({
       scope: effectiveScope,
       logger: this.logger,
@@ -403,15 +305,6 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
       }
     });
   }
-  /**
-   * Close a specific thread's browser session.
-   * For 'thread' scope, this closes only that thread's Stagehand instance.
-   * For 'shared' scope, this is a no-op (use close() to close the shared browser).
-   */
-  async closeThreadSession(threadId) {
-    await this.threadManager.destroySession(threadId);
-    this.notifyBrowserClosed(threadId);
-  }
   /**
    * Ensure browser is ready and thread session exists.
    * For 'thread' scope, this creates a dedicated Stagehand instance for the thread.
@@ -422,7 +315,7 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
     const scope = this.getScope();
     const threadId = this.getCurrentThread();
     if (scope === "thread" && threadId && threadId !== DEFAULT_THREAD_ID) {
-      await this.getStagehandForThread(threadId);
+      await this.getManagerForThread(threadId);
     }
   }
   // ---------------------------------------------------------------------------
@@ -469,7 +362,7 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
   }
   /**
    * Create a new Stagehand instance with the current config.
-   * Used by thread manager for 'browser' isolation mode.
+   * Used by thread manager for 'thread' scope.
    */
   async createStagehandInstance() {
     const stagehandOptions = await this.buildStagehandOptions();
@@ -483,15 +376,15 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
     if (scope === "thread") {
       return;
     }
-    this.stagehand = await this.createStagehandInstance();
-    this.threadManager.setStagehand(this.stagehand);
-    this.setupCloseListener(this.stagehand);
+    this.sharedManager = await this.createStagehandInstance();
+    this.threadManager.setSharedManager(this.sharedManager);
+    this.setupCloseListenerForSharedScope(this.sharedManager);
   }
   /**
-   * Set up close event listener for a Stagehand instance.
+   * Set up close event listener for a shared Stagehand instance.
    * Listens to both context and page close events for robust detection.
    */
-  setupCloseListener(stagehand) {
+  setupCloseListenerForSharedScope(stagehand) {
     let disconnectHandled = false;
     const handleDisconnect = () => {
       if (disconnectHandled) return;
@@ -565,20 +458,11 @@ var StagehandBrowser = class _StagehandBrowser extends 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 Stagehand session for thread: ${threadId}`);
-    this.notifyBrowserClosed(threadId);
-  }
   async doClose() {
-    await this.threadManager.destroyAll();
-    if (this.stagehand) {
-      await this.stagehand.close();
-      this.stagehand = null;
+    await this.threadManager.destroyAllSessions();
+    if (this.sharedManager) {
+      await this.sharedManager.close();
+      this.sharedManager = null;
     }
     this.setCurrentThread(void 0);
   }
@@ -589,13 +473,13 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
   async checkBrowserAlive() {
     const scope = this.getScope();
     if (scope === "thread") {
-      return this.threadManager.hasActiveThreadStagehands();
+      return this.threadManager.hasActiveThreadManagers();
     }
-    if (!this.stagehand) {
+    if (!this.sharedManager) {
       return false;
     }
     try {
-      const context = this.stagehand.context;
+      const context = this.sharedManager.context;
       if (!context) {
         return false;
       }
@@ -605,7 +489,7 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
       }
       const url = pages[0]?.url();
       if (url && url !== "about:blank") {
-        const state = this.getBrowserStateFromStagehand(this.stagehand);
+        const state = this.getBrowserStateFromStagehand(this.sharedManager);
         if (state) {
           this.lastBrowserState = state;
         }
@@ -619,24 +503,6 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
       return false;
     }
   }
-  /**
-   * Handle browser disconnection by clearing internal state.
-   * For 'thread' scope, only notifies the specific thread's callbacks.
-   * For 'shared' scope, notifies all callbacks.
-   */
-  handleBrowserDisconnected() {
-    const scope = this.threadManager.getScope();
-    const threadId = this.getCurrentThread();
-    if (scope === "thread" && threadId !== DEFAULT_THREAD_ID) {
-      this.threadManager.clearSession(threadId);
-      this.logger.debug?.(`Cleared Stagehand session for thread: ${threadId}`);
-      this.notifyBrowserClosed(threadId);
-    } else {
-      this.stagehand = null;
-      this.threadManager.clearStagehand();
-      super.handleBrowserDisconnected();
-    }
-  }
   /**
    * Create an error response from an exception.
    * Extends base class to add Stagehand-specific error handling.
@@ -657,21 +523,21 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
   // ---------------------------------------------------------------------------
   /**
    * Get the Stagehand instance for a thread, creating it if needed.
-   * For 'browser' isolation, this creates a dedicated Stagehand instance.
-   * For 'none' isolation, returns the shared instance.
+   * For 'thread' scope, this creates a dedicated Stagehand instance.
+   * For 'shared' scope, returns the shared instance.
    */
-  async getStagehandForThread(threadId) {
+  async getManagerForThread(threadId) {
     const scope = this.getScope();
     if (scope === "shared") {
-      return this.stagehand;
+      return this.sharedManager;
     }
     if (!threadId || threadId === DEFAULT_THREAD_ID) {
-      return this.stagehand;
+      return this.sharedManager;
     }
-    let stagehand = this.threadManager.getStagehandForThread(threadId);
+    let stagehand = this.threadManager.getExistingManagerForThread(threadId);
     if (!stagehand) {
       await this.threadManager.getManagerForThread(threadId);
-      stagehand = this.threadManager.getStagehandForThread(threadId);
+      stagehand = this.threadManager.getExistingManagerForThread(threadId);
     }
     return stagehand ?? null;
   }
@@ -683,14 +549,14 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
    */
   requireStagehand(explicitThreadId) {
     const threadId = explicitThreadId ?? this.getCurrentThread();
-    const stagehand = this.threadManager.getStagehandForThread(threadId ?? "") ?? this.stagehand;
+    const stagehand = this.threadManager.getExistingManagerForThread(threadId) ?? this.sharedManager;
     if (!stagehand) {
       throw new Error("Browser not launched");
     }
     return stagehand;
   }
   /**
-   * Get the current page from Stagehand v3, respecting thread isolation.
+   * Get the current page from Stagehand v3, respecting thread scope.
    * @param explicitThreadId - Optional thread ID to use instead of getCurrentThread()
    *                           Use this to avoid race conditions in concurrent tool calls.
    */
@@ -698,15 +564,15 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
     const scope = this.getScope();
     const threadId = explicitThreadId ?? this.getCurrentThread();
     if (scope === "thread" && threadId && threadId !== DEFAULT_THREAD_ID) {
-      const stagehand = this.threadManager.getStagehandForThread(threadId);
+      const stagehand = this.threadManager.getExistingManagerForThread(threadId);
       if (stagehand?.context) {
         return stagehand.context.activePage();
       }
       return null;
     }
-    if (!this.stagehand) return null;
+    if (!this.sharedManager) return null;
     try {
-      const context = this.stagehand.context;
+      const context = this.sharedManager.context;
       if (context) {
         const activePage = context.activePage();
         if (activePage) {
@@ -722,18 +588,10 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
     return null;
   }
   /**
-   * Get the page for a specific thread, creating session if needed.
+   * Get the active page for a thread (implements abstract method from base class).
    */
-  async getPageForThread(threadId) {
-    const scope = this.threadManager.getScope();
-    if (scope === "shared") {
-      return this.getPage();
-    }
-    const stagehand = await this.getStagehandForThread(threadId);
-    if (stagehand?.context) {
-      return stagehand.context.activePage();
-    }
-    return null;
+  async getActivePage(threadId) {
+    return this.getPage(threadId);
   }
   /**
    * Get a CDP session for a specific page.
@@ -984,7 +842,7 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
     const effectiveThreadId = threadId ?? this.getCurrentThread();
     const scope = this.threadManager.getScope();
     if (scope === "thread" && effectiveThreadId) {
-      const stagehand = this.threadManager.getStagehandForThread(effectiveThreadId);
+      const stagehand = this.threadManager.getExistingManagerForThread(effectiveThreadId);
       if (!stagehand?.context) {
         return null;
       }
@@ -1003,7 +861,7 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
     try {
       const url = page.url();
       if (url && url !== "about:blank") {
-        const state = this.getBrowserStateFromStagehand(this.stagehand);
+        const state = this.getBrowserStateFromStagehand(this.sharedManager);
         if (state) {
           this.lastBrowserState = state;
         }
@@ -1038,15 +896,24 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
       const scope = this.threadManager.getScope();
       const effectiveThreadId = threadId ?? this.getCurrentThread();
       if (scope === "thread" && effectiveThreadId) {
-        const stagehand = this.threadManager.getStagehandForThread(effectiveThreadId);
+        const stagehand = this.threadManager.getExistingManagerForThread(effectiveThreadId);
         if (!stagehand) return null;
         return this.getBrowserStateFromStagehand(stagehand);
       }
-      return this.getBrowserStateFromStagehand(this.stagehand);
+      return this.getBrowserStateFromStagehand(this.sharedManager);
     } catch {
       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() ?? DEFAULT_THREAD_ID;
+    const stagehand = this.threadManager.getExistingManagerForThread(effectiveThreadId);
+    return this.getBrowserStateFromStagehand(stagehand);
+  }
   /**
    * Get browser state from a specific Stagehand instance.
    */
@@ -1084,44 +951,15 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
     const state = await this.getBrowserState(threadId);
     return state?.activeTabIndex ?? 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() ?? DEFAULT_THREAD_ID;
-      const scope = this.threadManager.getScope();
-      let stagehand = null;
-      if (scope === "thread") {
-        stagehand = this.threadManager.getStagehandForThread(effectiveThreadId);
-      } else {
-        stagehand = this.stagehand;
-      }
-      if (stagehand) {
-        const state = this.getBrowserStateFromStagehand(stagehand);
-        if (state) {
-          this.threadManager.updateBrowserState(effectiveThreadId, state);
-        }
-      }
-    } catch {
-    }
-  }
   // ---------------------------------------------------------------------------
   // Screencast (for Studio live view)
   // Uses Stagehand v3's native CDP access
   // ---------------------------------------------------------------------------
-  /**
-   * Get the stream key for a thread (or shared key for shared scope).
-   */
-  getStreamKey(threadId) {
-    return threadId || _StagehandBrowser.SHARED_STREAM_KEY;
-  }
   async startScreencast(options) {
     const threadId = options?.threadId;
     const provider = {
       getCdpSession: async () => {
-        const page = await this.getPageForThread(threadId ?? "");
+        const page = await this.threadManager.getPageForThread(threadId);
         if (!page) {
           throw new Error("No page available for screencast");
         }
@@ -1155,7 +993,7 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
    * Uses CDP Target events since Stagehand doesn't expose page lifecycle events.
    */
   async setupTabChangeDetection(threadId, stream) {
-    const stagehand = await this.getStagehandForThread(threadId);
+    const stagehand = await this.getManagerForThread(threadId);
     if (!stagehand?.context) return;
     const connection = stagehand.context.conn;
     if (!connection) {
@@ -1217,7 +1055,7 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
               if (newPage && stagehand.context) {
                 stagehand.context.setActivePage(newPage);
               }
-              void this.reconnectScreencast("manual tab tracked");
+              void this.reconnectScreencastForThread(threadId, "manual tab tracked");
               void setupPageNavigationListener();
             } else {
               this.logger.debug?.("Stagehand did not register the page (non-injectable URL)");
@@ -1300,48 +1138,6 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
       this.logger.debug?.("Failed to set up tab change detection", error);
     }
   }
-  /**
-   * Reconnect the active screencast for a specific thread.
-   */
-  async reconnectScreencastForThread(threadId, reason) {
-    const streamKey = this.getStreamKey(threadId);
-    const stream = this.activeScreencastStreams.get(streamKey);
-    if (!stream || !stream.isActive()) {
-      return;
-    }
-    if (!this.isBrowserRunning()) {
-      this.logger.debug?.("Skipping screencast reconnect - browser not running");
-      return;
-    }
-    const scope = this.getScope();
-    if (scope === "thread" && threadId && !this.threadManager.getStagehandForThread(threadId)) {
-      this.logger.debug?.(`Skipping screencast reconnect - no session for thread ${threadId}`);
-      return;
-    }
-    this.logger.debug?.(`Reconnecting screencast: ${reason}`);
-    try {
-      await new Promise((resolve) => setTimeout(resolve, 150));
-      await stream.reconnect();
-      const stagehand = await this.getStagehandForThread(threadId);
-      const activePage = stagehand?.context?.activePage();
-      if (activePage) {
-        const url = activePage.url();
-        if (url) {
-          stream.emitUrl(url);
-        }
-      }
-    } catch (error) {
-      this.logger.debug?.("Screencast reconnect failed", error);
-    }
-  }
-  /**
-   * Reconnect the active screencast for the current thread.
-   * Wrapper for reconnectScreencastForThread using getCurrentThread().
-   */
-  async reconnectScreencast(reason) {
-    const threadId = this.getCurrentThread();
-    await this.reconnectScreencastForThread(threadId, reason);
-  }
   // NOTE: Manual tab switching in browser UI is not fully supported.
   // Stagehand v3 does not track pages opened via browser UI (only pages created through its API).
   // We've requested this feature from Browserbase - see Notion doc for details.
@@ -1350,7 +1146,7 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
   // ---------------------------------------------------------------------------
   async injectMouseEvent(event, threadId) {
     const effectiveThreadId = threadId ?? this.getCurrentThread();
-    const page = await this.getPageForThread(effectiveThreadId ?? "");
+    const page = await this.threadManager.getPageForThread(effectiveThreadId);
     const cdpSession = this.getCdpSessionForPage(page);
     if (!cdpSession) {
       throw new Error("No CDP session available");
@@ -1376,7 +1172,7 @@ var StagehandBrowser = class _StagehandBrowser extends MastraBrowser {
   }
   async injectKeyboardEvent(event, threadId) {
     const effectiveThreadId = threadId ?? this.getCurrentThread();
-    const page = await this.getPageForThread(effectiveThreadId ?? "");
+    const page = await this.threadManager.getPageForThread(effectiveThreadId);
     const cdpSession = this.getCdpSessionForPage(page);
     if (!cdpSession) {
       throw new Error("No CDP session available");