@mastra/stagehand 0.0.0

package/dist/index.js

@@ -0,0 +1,1397 @@
+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';
+
+// 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.
+   */
+  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.
+   */
+  getSharedManager() {
+    const stagehand = this.getSharedStagehand();
+    return stagehand.context.activePage() ?? stagehand;
+  }
+  /**
+   * Create a new session for a thread.
+   */
+  async createSession(threadId) {
+    const savedState = this.getSavedBrowserState(threadId);
+    const session = {
+      threadId,
+      createdAt: Date.now(),
+      browserState: savedState
+    };
+    if (this.scope === "thread") {
+      if (!this.createStagehand) {
+        throw new Error("createStagehand factory not set - required for thread scope");
+      }
+      this.logger?.debug?.(`Creating dedicated Stagehand instance for thread ${threadId}`);
+      const stagehand = await this.createStagehand();
+      session.stagehand = stagehand;
+      this.threadStagehands.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);
+      }
+      this.onBrowserCreated?.(stagehand, threadId);
+    }
+    return session;
+  }
+  /**
+   * Restore browser state (multiple tabs) to a Stagehand instance.
+   */
+  async restoreBrowserState(stagehand, state) {
+    try {
+      const context = stagehand.context;
+      if (!context) return;
+      const firstTab = state.tabs[0];
+      if (firstTab?.url) {
+        const page = context.activePage();
+        if (page) {
+          await page.goto(firstTab.url, { waitUntil: "domcontentloaded" });
+        }
+      }
+      for (let i = 1; i < state.tabs.length; i++) {
+        const tab = state.tabs[i];
+        if (tab?.url) {
+          await context.newPage(tab.url);
+        }
+      }
+      const pages = context.pages();
+      const targetPage = pages[state.activeTabIndex];
+      if (targetPage && targetPage !== context.activePage()) {
+        context.setActivePage(targetPage);
+      }
+    } catch (error) {
+      this.logger?.warn?.(`Failed to restore browser state: ${error}`);
+    }
+  }
+  /**
+   * 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.
+   */
+  getManagerForSession(session) {
+    if (this.scope === "thread" && session.stagehand) {
+      return session.stagehand.context.activePage() ?? session.stagehand;
+    }
+    return this.getSharedManager();
+  }
+  /**
+   * Destroy a session and clean up resources.
+   */
+  async doDestroySession(session) {
+    if (this.scope === "thread" && session.stagehand) {
+      try {
+        await session.stagehand.close();
+        this.logger?.debug?.(`Closed Stagehand instance for thread ${session.threadId}`);
+      } catch (error) {
+        this.logger?.warn?.(`Failed to close Stagehand for thread ${session.threadId}: ${error}`);
+      }
+      this.threadStagehands.delete(session.threadId);
+    }
+  }
+  /**
+   * Clean up all thread sessions.
+   */
+  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);
+  }
+};
+var actInputSchema = z.object({
+  instruction: z.string().describe('Natural language instruction for the action (e.g., "click the login button")'),
+  variables: z.record(z.string(), z.string()).optional().describe("Variables to substitute in the instruction using %variableName% syntax"),
+  useVision: z.boolean().optional().describe("Whether to use vision capabilities (default: true)"),
+  timeout: z.number().optional().describe("Timeout in milliseconds")
+});
+var extractInputSchema = z.object({
+  instruction: z.string().describe("Natural language instruction for what data to extract"),
+  schema: z.record(z.string(), z.unknown()).optional().describe("JSON schema defining the expected data structure (optional, will return unstructured if omitted)"),
+  timeout: z.number().optional().describe("Timeout in milliseconds")
+});
+var observeInputSchema = z.object({
+  instruction: z.string().optional().describe(
+    'Natural language instruction for what to find (e.g., "find all buttons"). If omitted, finds all interactive elements.'
+  ),
+  onlyVisible: z.boolean().optional().describe("Only return visible elements (default: true)"),
+  timeout: z.number().optional().describe("Timeout in milliseconds")
+});
+var navigateInputSchema = z.object({
+  url: z.string().describe("The URL to navigate to"),
+  waitUntil: z.enum(["load", "domcontentloaded", "networkidle"]).optional().describe("When to consider navigation complete (default: domcontentloaded)")
+});
+var closeInputSchema = z.object({});
+var tabsInputSchema = z.object({
+  action: z.enum(["list", "new", "switch", "close"]).describe("Action to perform: list all tabs, open new tab, switch to tab, or close tab"),
+  index: z.number().int().min(0).optional().describe(
+    "Tab index for switch/close actions (0-based). Required for switch, optional for close (defaults to current)."
+  ),
+  url: z.string().optional().describe('URL to navigate to after opening new tab (optional, for "new" action only)')
+}).superRefine((value, ctx) => {
+  if (value.action === "switch" && value.index === void 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["index"],
+      message: 'index is required when action is "switch"'
+    });
+  }
+});
+var stagehandSchemas = {
+  // Core AI
+  act: actInputSchema,
+  extract: extractInputSchema,
+  observe: observeInputSchema,
+  // Navigation & State
+  navigate: navigateInputSchema,
+  tabs: tabsInputSchema,
+  close: closeInputSchema
+};
+
+// src/tools/constants.ts
+var STAGEHAND_TOOLS = {
+  // Core AI
+  ACT: "stagehand_act",
+  EXTRACT: "stagehand_extract",
+  OBSERVE: "stagehand_observe",
+  // Navigation & State
+  NAVIGATE: "stagehand_navigate",
+  TABS: "stagehand_tabs",
+  CLOSE: "stagehand_close"
+};
+
+// src/tools/act.ts
+function createActTool(browser) {
+  return createTool({
+    id: STAGEHAND_TOOLS.ACT,
+    description: 'Perform an action on the page using natural language. Examples: "click the login button", "type hello into the search box", "scroll down".',
+    inputSchema: actInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return await browser.act(input, threadId);
+    }
+  });
+}
+function createCloseTool(browser) {
+  return createTool({
+    id: STAGEHAND_TOOLS.CLOSE,
+    description: "Close the browser. Only use when done with all browsing.",
+    inputSchema: closeInputSchema,
+    execute: async (_input, { agent }) => {
+      const threadId = agent?.threadId;
+      if (browser.getScope() !== "shared") {
+        if (!threadId) {
+          throw new Error("stagehand_close requires agent.threadId when browser scope is not shared");
+        }
+        await browser.closeThreadSession(threadId);
+        return {
+          success: true,
+          hint: "Thread's browser session closed. A new session will be created on next use."
+        };
+      }
+      await browser.close();
+      return {
+        success: true,
+        hint: "Browser closed. It will be re-launched automatically on next use."
+      };
+    }
+  });
+}
+function createExtractTool(browser) {
+  return createTool({
+    id: STAGEHAND_TOOLS.EXTRACT,
+    description: "Extract structured data from the page using natural language. Can optionally provide a JSON schema for the expected data structure.",
+    inputSchema: extractInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return await browser.extract(input, threadId);
+    }
+  });
+}
+function createNavigateTool(browser) {
+  return createTool({
+    id: STAGEHAND_TOOLS.NAVIGATE,
+    description: "Navigate the browser to a URL.",
+    inputSchema: navigateInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return await browser.navigate(input, threadId);
+    }
+  });
+}
+function createObserveTool(browser) {
+  return createTool({
+    id: STAGEHAND_TOOLS.OBSERVE,
+    description: "Discover actionable elements on the page. Returns a list of actions that can be performed. Use this to understand what's on the page before acting.",
+    inputSchema: observeInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return await browser.observe(input, threadId);
+    }
+  });
+}
+function createTabsTool(browser) {
+  return createTool({
+    id: STAGEHAND_TOOLS.TABS,
+    description: 'Manage browser tabs. Actions: "list" shows all tabs, "new" opens a tab (optionally with URL), "switch" changes to tab by index, "close" closes a tab.',
+    inputSchema: tabsInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return await browser.tabs(input, threadId);
+    }
+  });
+}
+
+// src/tools/index.ts
+function createStagehandTools(browser) {
+  return {
+    // Core AI
+    [STAGEHAND_TOOLS.ACT]: createActTool(browser),
+    [STAGEHAND_TOOLS.EXTRACT]: createExtractTool(browser),
+    [STAGEHAND_TOOLS.OBSERVE]: createObserveTool(browser),
+    // Navigation & State
+    [STAGEHAND_TOOLS.NAVIGATE]: createNavigateTool(browser),
+    [STAGEHAND_TOOLS.TABS]: createTabsTool(browser),
+    [STAGEHAND_TOOLS.CLOSE]: createCloseTool(browser)
+  };
+}
+
+// src/stagehand-browser.ts
+var StagehandBrowser = class _StagehandBrowser 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";
+    }
+    this.threadManager = new StagehandThreadManager({
+      scope: effectiveScope,
+      logger: this.logger,
+      // When a new thread session is created, notify listeners so screencast can start
+      onSessionCreated: (session) => {
+        this.notifyBrowserReady(session.threadId);
+      },
+      // When a new browser is created for a thread, set up close listener
+      onBrowserCreated: (stagehand, threadId) => {
+        this.setupCloseListenerForThread(stagehand, threadId);
+      }
+    });
+  }
+  /**
+   * 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.
+   */
+  async ensureReady() {
+    this.threadManager.setCreateStagehand(() => this.createStagehandInstance());
+    await super.ensureReady();
+    const scope = this.getScope();
+    const threadId = this.getCurrentThread();
+    if (scope === "thread" && threadId && threadId !== DEFAULT_THREAD_ID) {
+      await this.getStagehandForThread(threadId);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+  /**
+   * Build Stagehand options from config.
+   * Returns the configuration object expected by Stagehand constructor.
+   */
+  async buildStagehandOptions() {
+    const config = this.stagehandConfig;
+    const stagehandOptions = {
+      env: config.env ?? "LOCAL",
+      // v3 uses "provider/model" format
+      model: typeof config.model === "string" ? config.model : config.model?.modelName,
+      selfHeal: config.selfHeal ?? true,
+      domSettleTimeoutMs: config.domSettleTimeout,
+      verbose: config.verbose ?? 1,
+      systemPrompt: config.systemPrompt
+    };
+    if (config.env === "BROWSERBASE") {
+      if (config.apiKey) {
+        stagehandOptions.apiKey = config.apiKey;
+      }
+      if (config.projectId) {
+        stagehandOptions.projectId = config.projectId;
+      }
+    }
+    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
+      };
+    } else if (config.env !== "BROWSERBASE") {
+      stagehandOptions.localBrowserLaunchOptions = {
+        headless: config.headless,
+        viewport: config.viewport
+      };
+    }
+    return stagehandOptions;
+  }
+  /**
+   * Create a new Stagehand instance with the current config.
+   * Used by thread manager for 'browser' isolation mode.
+   */
+  async createStagehandInstance() {
+    const stagehandOptions = await this.buildStagehandOptions();
+    const stagehand = new Stagehand(stagehandOptions);
+    await stagehand.init();
+    return stagehand;
+  }
+  async doLaunch() {
+    const scope = this.getScope();
+    this.threadManager.setCreateStagehand(() => this.createStagehandInstance());
+    if (scope === "thread") {
+      return;
+    }
+    this.stagehand = await this.createStagehandInstance();
+    this.threadManager.setStagehand(this.stagehand);
+    this.setupCloseListener(this.stagehand);
+  }
+  /**
+   * Set up close event listener for a Stagehand instance.
+   * Listens to both context and page close events for robust detection.
+   */
+  setupCloseListener(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.
+   */
+  setupCloseListenerForThread(stagehand, threadId) {
+    let disconnectHandled = false;
+    const handleDisconnect = () => {
+      if (disconnectHandled) return;
+      disconnectHandled = true;
+      this.handleThreadBrowserDisconnected(threadId);
+    };
+    try {
+      const stagehandAny = stagehand;
+      const conn = stagehandAny.ctx?.conn;
+      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);
+          }
+        }
+      }
+      conn.on("Target.targetCreated", (params) => {
+        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();
+          }
+        }
+      });
+    } 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;
+    }
+    this.setCurrentThread(void 0);
+  }
+  /**
+   * Check if the browser is still alive by verifying the context and pages exist.
+   * Called by base class ensureReady() to detect externally closed browsers.
+   */
+  async checkBrowserAlive() {
+    const scope = this.getScope();
+    if (scope === "thread") {
+      return this.threadManager.hasActiveThreadStagehands();
+    }
+    if (!this.stagehand) {
+      return false;
+    }
+    try {
+      const context = this.stagehand.context;
+      if (!context) {
+        return false;
+      }
+      const pages = context.pages();
+      if (!pages || pages.length === 0) {
+        return false;
+      }
+      const url = pages[0]?.url();
+      if (url && url !== "about:blank") {
+        const state = this.getBrowserStateFromStagehand(this.stagehand);
+        if (state) {
+          this.lastBrowserState = state;
+        }
+      }
+      return true;
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      if (this.isDisconnectionError(msg)) {
+        this.logger.debug?.("Browser was externally closed");
+      }
+      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.
+   */
+  createErrorFromException(error, context) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.includes("No actions found") || msg.includes("Could not find")) {
+      return this.createError(
+        "element_not_found",
+        `${context}: Could not find matching element or action.`,
+        "Try rephrasing the instruction or use observe() to see available actions."
+      );
+    }
+    return super.createErrorFromException(error, context);
+  }
+  // ---------------------------------------------------------------------------
+  // Internal Helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async getStagehandForThread(threadId) {
+    const scope = this.getScope();
+    if (scope === "shared") {
+      return this.stagehand;
+    }
+    if (!threadId || threadId === DEFAULT_THREAD_ID) {
+      return this.stagehand;
+    }
+    let stagehand = this.threadManager.getStagehandForThread(threadId);
+    if (!stagehand) {
+      await this.threadManager.getManagerForThread(threadId);
+      stagehand = this.threadManager.getStagehandForThread(threadId);
+    }
+    return stagehand ?? null;
+  }
+  /**
+   * Require a Stagehand instance for the given or current thread.
+   * Throws if no instance is available.
+   * @param explicitThreadId - Optional thread ID to use instead of getCurrentThread()
+   *                           Use this to avoid race conditions in concurrent tool calls.
+   */
+  requireStagehand(explicitThreadId) {
+    const threadId = explicitThreadId ?? this.getCurrentThread();
+    const stagehand = this.threadManager.getStagehandForThread(threadId ?? "") ?? this.stagehand;
+    if (!stagehand) {
+      throw new Error("Browser not launched");
+    }
+    return stagehand;
+  }
+  /**
+   * Get the current page from Stagehand v3, respecting thread isolation.
+   * @param explicitThreadId - Optional thread ID to use instead of getCurrentThread()
+   *                           Use this to avoid race conditions in concurrent tool calls.
+   */
+  getPage(explicitThreadId) {
+    const scope = this.getScope();
+    const threadId = explicitThreadId ?? this.getCurrentThread();
+    if (scope === "thread" && threadId && threadId !== DEFAULT_THREAD_ID) {
+      const stagehand = this.threadManager.getStagehandForThread(threadId);
+      if (stagehand?.context) {
+        return stagehand.context.activePage();
+      }
+      return null;
+    }
+    if (!this.stagehand) return null;
+    try {
+      const context = this.stagehand.context;
+      if (context) {
+        const activePage = context.activePage();
+        if (activePage) {
+          return activePage;
+        }
+        const pages = context.pages();
+        if (pages && pages.length > 0) {
+          return pages[0];
+        }
+      }
+    } catch {
+    }
+    return null;
+  }
+  /**
+   * Get the page for a specific thread, creating session if needed.
+   */
+  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;
+  }
+  /**
+   * Get a CDP session for a specific page.
+   */
+  getCdpSessionForPage(page) {
+    if (!page) return null;
+    try {
+      const mainFrameId = page.mainFrameId?.();
+      if (mainFrameId && page.getSessionForFrame) {
+        return page.getSessionForFrame(mainFrameId);
+      }
+    } catch {
+    }
+    return null;
+  }
+  // ---------------------------------------------------------------------------
+  // Tools - Implements MastraBrowser.getTools()
+  // ---------------------------------------------------------------------------
+  getTools() {
+    return createStagehandTools(this);
+  }
+  // ---------------------------------------------------------------------------
+  // Core AI Methods
+  // ---------------------------------------------------------------------------
+  /**
+   * Perform an action using natural language instruction
+   * @param input - Action input
+   * @param threadId - Optional thread ID for thread-safe operation
+   */
+  async act(input, threadId) {
+    const stagehand = this.requireStagehand(threadId);
+    const page = this.getPage(threadId);
+    const url = page?.url() ?? "";
+    try {
+      const result = await stagehand.act(input.instruction, {
+        variables: input.variables,
+        timeout: input.timeout,
+        page: page ?? void 0
+      });
+      return {
+        success: result.success,
+        message: result.message,
+        action: result.actionDescription,
+        url: page?.url() ?? url,
+        hint: "Use observe() to discover available actions or extract() to get page data."
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Act");
+    }
+  }
+  /**
+   * Extract structured data from a page using natural language
+   * @param input - Extract input
+   * @param threadId - Optional thread ID for thread-safe operation
+   */
+  async extract(input, threadId) {
+    const stagehand = this.requireStagehand(threadId);
+    const page = this.getPage(threadId);
+    const url = page?.url() ?? "";
+    try {
+      const options = { page: page ?? void 0 };
+      const result = input.schema ? await stagehand.extract(input.instruction, input.schema, options) : await stagehand.extract(input.instruction, options);
+      return {
+        success: true,
+        data: result,
+        url: page?.url() ?? url,
+        hint: "Data extracted successfully. Use act() to perform actions based on this data."
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Extract");
+    }
+  }
+  /**
+   * Discover actionable elements on a page
+   * @param input - Observe input
+   * @param threadId - Optional thread ID for thread-safe operation
+   */
+  async observe(input, threadId) {
+    const stagehand = this.requireStagehand(threadId);
+    const page = this.getPage(threadId);
+    const url = page?.url() ?? "";
+    try {
+      const options = { page: page ?? void 0 };
+      const actions = input.instruction ? await stagehand.observe(input.instruction, options) : await stagehand.observe(options);
+      return {
+        success: true,
+        actions: actions.map((a) => ({
+          selector: a.selector,
+          description: a.description,
+          method: a.method,
+          arguments: a.arguments
+        })),
+        url: page?.url() ?? url,
+        hint: actions.length > 0 ? `Found ${actions.length} actions. Use act() with a specific instruction to execute one.` : "No actions found. Try a different instruction or navigate to a different page."
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Observe");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Navigation & State Methods
+  // ---------------------------------------------------------------------------
+  /**
+   * Navigate to a URL
+   * @param input - Navigate input
+   * @param threadId - Optional thread ID for thread-safe operation
+   */
+  async navigate(input, threadId) {
+    const page = this.getPage(threadId);
+    if (!page) {
+      return this.createError("browser_error", "Browser page not available.", "Ensure the browser is launched.");
+    }
+    try {
+      await page.goto(input.url, {
+        waitUntil: input.waitUntil ?? "domcontentloaded"
+      });
+      const url = page.url();
+      const title = await page.title();
+      return {
+        success: true,
+        url,
+        title,
+        hint: "Page loaded. Use observe() to discover actions or extract() to get data."
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Navigate");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Tab Management
+  // ---------------------------------------------------------------------------
+  /**
+   * Manage browser tabs - list, create, switch, close
+   * @param input - Tabs input
+   * @param threadId - Optional thread ID for thread-safe operation
+   */
+  async tabs(input, threadId) {
+    const effectiveThreadId = threadId ?? this.getCurrentThread();
+    const stagehand = this.requireStagehand(effectiveThreadId);
+    const context = stagehand.context;
+    if (!context) {
+      return this.createError("browser_error", "Browser context not available.", "Ensure the browser is launched.");
+    }
+    try {
+      switch (input.action) {
+        case "list": {
+          const pages = context.pages();
+          const activePage = context.activePage();
+          const tabs = await Promise.all(
+            pages.map(async (page, index) => ({
+              index,
+              url: page.url(),
+              title: await page.title(),
+              active: page === activePage
+            }))
+          );
+          return {
+            success: true,
+            tabs,
+            hint: 'Use stagehand_tabs with action:"switch" and index to change tabs.'
+          };
+        }
+        case "new": {
+          const newPage = await context.newPage(input.url);
+          await this.reconnectScreencastForThread(effectiveThreadId, "new tab via tool");
+          this.updateSessionBrowserState(effectiveThreadId);
+          return {
+            success: true,
+            index: context.pages().length - 1,
+            url: newPage.url(),
+            title: await newPage.title(),
+            hint: "New tab opened. Use stagehand_observe to discover actions."
+          };
+        }
+        case "switch": {
+          if (input.index === void 0) {
+            return this.createError(
+              "browser_error",
+              "Tab index required for switch action.",
+              "Provide index parameter."
+            );
+          }
+          const pages = context.pages();
+          if (input.index < 0 || input.index >= pages.length) {
+            return this.createError(
+              "browser_error",
+              `Invalid tab index: ${input.index}. Valid range: 0-${pages.length - 1}`,
+              'Use stagehand_tabs with action:"list" to see available tabs.'
+            );
+          }
+          const targetPage = pages[input.index];
+          const targetUrl = targetPage.url();
+          context.setActivePage(targetPage);
+          await this.reconnectScreencastForThread(effectiveThreadId, "tab switch via tool");
+          const streamKey = this.getStreamKey(effectiveThreadId);
+          const stream = this.activeScreencastStreams.get(streamKey);
+          if (targetUrl && stream?.isActive()) {
+            stream.emitUrl(targetUrl);
+          }
+          this.updateSessionBrowserState(effectiveThreadId);
+          return {
+            success: true,
+            index: input.index,
+            url: targetUrl,
+            title: await targetPage.title(),
+            hint: "Tab switched. Use stagehand_observe to discover actions."
+          };
+        }
+        case "close": {
+          const pages = context.pages();
+          const indexToClose = input.index ?? pages.findIndex((p) => p === context.activePage());
+          if (indexToClose < 0 || indexToClose >= pages.length) {
+            return this.createError(
+              "browser_error",
+              `Invalid tab index: ${indexToClose}`,
+              'Use stagehand_tabs with action:"list" to see available tabs.'
+            );
+          }
+          const pageToClose = pages[indexToClose];
+          await pageToClose.close();
+          await this.reconnectScreencastForThread(effectiveThreadId, "tab close via tool");
+          this.updateSessionBrowserState(effectiveThreadId);
+          const remainingPages = context.pages();
+          return {
+            success: true,
+            remaining: remainingPages.length,
+            hint: remainingPages.length > 0 ? "Tab closed. Use stagehand_observe to see current tab." : "All tabs closed."
+          };
+        }
+        default:
+          return this.createError(
+            "browser_error",
+            `Unknown tabs action: ${input.action}`,
+            'Use "list", "new", "switch", or "close".'
+          );
+      }
+    } catch (error) {
+      return this.createErrorFromException(error, "Tabs");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // URL Tracking (for Studio browser view)
+  // ---------------------------------------------------------------------------
+  async getCurrentUrl(threadId) {
+    if (!this.isBrowserRunning()) {
+      return null;
+    }
+    const effectiveThreadId = threadId ?? this.getCurrentThread();
+    const scope = this.threadManager.getScope();
+    if (scope === "thread" && effectiveThreadId) {
+      const stagehand = this.threadManager.getStagehandForThread(effectiveThreadId);
+      if (!stagehand?.context) {
+        return null;
+      }
+      const page2 = stagehand.context.activePage();
+      const url = page2?.url() ?? null;
+      if (url && url !== "about:blank") {
+        const state = this.getBrowserStateFromStagehand(stagehand);
+        if (state) {
+          this.threadManager.updateBrowserState(effectiveThreadId, state);
+        }
+      }
+      return url;
+    }
+    const page = this.getPage();
+    if (!page) return null;
+    try {
+      const url = page.url();
+      if (url && url !== "about:blank") {
+        const state = this.getBrowserStateFromStagehand(this.stagehand);
+        if (state) {
+          this.lastBrowserState = state;
+        }
+      }
+      return url;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Navigate to a URL (simple version). Used internally for restoring state on relaunch.
+   */
+  async navigateTo(url) {
+    const page = this.getPage();
+    if (!page) return;
+    try {
+      await page.goto(url, {
+        timeoutMs: this.config.timeout ?? 3e4,
+        waitUntil: "domcontentloaded"
+      });
+    } catch {
+    }
+  }
+  /**
+   * Get the current browser state (all tabs and active tab index).
+   */
+  async getBrowserState(threadId) {
+    if (!this.isBrowserRunning()) {
+      return null;
+    }
+    try {
+      const scope = this.threadManager.getScope();
+      const effectiveThreadId = threadId ?? this.getCurrentThread();
+      if (scope === "thread" && effectiveThreadId) {
+        const stagehand = this.threadManager.getStagehandForThread(effectiveThreadId);
+        if (!stagehand) return null;
+        return this.getBrowserStateFromStagehand(stagehand);
+      }
+      return this.getBrowserStateFromStagehand(this.stagehand);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get browser state from a specific Stagehand instance.
+   */
+  getBrowserStateFromStagehand(stagehand) {
+    if (!stagehand?.context) return null;
+    try {
+      const pages = stagehand.context.pages();
+      const activePage = stagehand.context.activePage();
+      let activeIndex = 0;
+      const tabs = pages.map((page, index) => {
+        if (page === activePage) {
+          activeIndex = index;
+        }
+        return { url: page.url() };
+      });
+      return {
+        tabs,
+        activeTabIndex: activeIndex
+      };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get all open tabs with their URLs and titles.
+   */
+  async getTabState(threadId) {
+    const state = await this.getBrowserState(threadId);
+    return state?.tabs ?? [];
+  }
+  /**
+   * Get the active tab index.
+   */
+  async getActiveTabIndex(threadId) {
+    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 ?? "");
+        if (!page) {
+          throw new Error("No page available for screencast");
+        }
+        const session = this.getCdpSessionForPage(page);
+        if (!session) {
+          throw new Error("No CDP session available for page");
+        }
+        return session;
+      },
+      isBrowserRunning: () => this.isBrowserRunning()
+    };
+    const stream = new ScreencastStreamImpl(provider, options);
+    const streamKey = this.getStreamKey(threadId);
+    this.activeScreencastStreams.set(streamKey, stream);
+    await stream.start();
+    await this.setupTabChangeDetection(threadId, stream);
+    stream.once("stop", () => {
+      if (this.activeScreencastStreams.get(streamKey) === stream) {
+        this.activeScreencastStreams.delete(streamKey);
+      }
+      const timer = this.tabChangeDebounceTimers.get(streamKey);
+      if (timer) {
+        clearTimeout(timer);
+        this.tabChangeDebounceTimers.delete(streamKey);
+      }
+    });
+    return stream;
+  }
+  /**
+   * Set up listeners to detect tab changes and reconnect the screencast.
+   * Uses CDP Target events since Stagehand doesn't expose page lifecycle events.
+   */
+  async setupTabChangeDetection(threadId, stream) {
+    const stagehand = await this.getStagehandForThread(threadId);
+    if (!stagehand?.context) return;
+    const connection = stagehand.context.conn;
+    if (!connection) {
+      this.logger.debug?.("No CDP connection available for tab change detection");
+      return;
+    }
+    const targetSessions = /* @__PURE__ */ new Map();
+    let targetInfoDebounceTimer = null;
+    const isTrackedByStagehand = (targetId) => {
+      const pages = stagehand.context?.pages() || [];
+      return pages.some((p) => p.targetId() === targetId);
+    };
+    const streamKey = this.getStreamKey(threadId);
+    const onTargetCreated = (params) => {
+      if (params.targetInfo.type !== "page") return;
+      const existingTimer = this.tabChangeDebounceTimers.get(streamKey);
+      if (existingTimer) {
+        clearTimeout(existingTimer);
+      }
+      this.tabChangeDebounceTimers.set(
+        streamKey,
+        setTimeout(() => {
+          this.tabChangeDebounceTimers.delete(streamKey);
+          void this.reconnectScreencastForThread(threadId, "new tab");
+          void setupPageNavigationListener();
+        }, 300)
+      );
+    };
+    const onTargetAttached = (params) => {
+      if (params.targetInfo.type !== "page") return;
+      targetSessions.set(params.targetInfo.targetId, params.sessionId);
+    };
+    let pendingTargetInfo = null;
+    const onTargetInfoChanged = (params) => {
+      if (params.targetInfo.type !== "page") return;
+      if (isTrackedByStagehand(params.targetInfo.targetId)) return;
+      const sessionId = targetSessions.get(params.targetInfo.targetId);
+      if (!sessionId) return;
+      pendingTargetInfo = params;
+      if (targetInfoDebounceTimer) {
+        clearTimeout(targetInfoDebounceTimer);
+      }
+      targetInfoDebounceTimer = setTimeout(async () => {
+        targetInfoDebounceTimer = null;
+        if (!pendingTargetInfo) return;
+        const info = pendingTargetInfo.targetInfo;
+        const sid = targetSessions.get(info.targetId);
+        pendingTargetInfo = null;
+        if (isTrackedByStagehand(info.targetId) || !sid) return;
+        const contextAny = stagehand.context;
+        if (contextAny?.onAttachedToTarget) {
+          try {
+            await contextAny.onAttachedToTarget(info, sid);
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            if (isTrackedByStagehand(info.targetId)) {
+              this.logger.debug?.("Page registered successfully, setting as active");
+              const pages = stagehand.context?.pages() || [];
+              const newPage = pages.find((p) => p.targetId() === info.targetId);
+              if (newPage && stagehand.context) {
+                stagehand.context.setActivePage(newPage);
+              }
+              void this.reconnectScreencast("manual tab tracked");
+              void setupPageNavigationListener();
+            } else {
+              this.logger.debug?.("Stagehand did not register the page (non-injectable URL)");
+            }
+          } catch (e) {
+            this.logger.debug?.("Failed to register page with Stagehand", e);
+          }
+        }
+      }, 300);
+    };
+    const onTargetDestroyed = (params) => {
+      this.logger.debug?.("Page target destroyed");
+      targetSessions.delete(params.targetId);
+      const existingTimer = this.tabChangeDebounceTimers.get(streamKey);
+      if (existingTimer) {
+        clearTimeout(existingTimer);
+      }
+      this.tabChangeDebounceTimers.set(
+        streamKey,
+        setTimeout(() => {
+          this.tabChangeDebounceTimers.delete(streamKey);
+          void this.reconnectScreencastForThread(threadId, "tab closed");
+          void setupPageNavigationListener();
+        }, 300)
+      );
+    };
+    const onFrameNavigated = (params) => {
+      if (!params.frame.parentId && params.frame.url) {
+        stream.emitUrl(params.frame.url);
+        this.updateSessionBrowserState(threadId);
+      }
+    };
+    let pageSession = null;
+    const setupPageNavigationListener = async () => {
+      try {
+        if (pageSession?.off) {
+          pageSession.off("Page.frameNavigated", onFrameNavigated);
+        }
+        const page = stagehand.context?.activePage();
+        if (!page) return;
+        const session = page.getSessionForFrame(page.mainFrameId());
+        if (!session) return;
+        pageSession = session;
+        await session.send("Page.enable");
+        session.on("Page.frameNavigated", onFrameNavigated);
+        const currentUrl = page.url();
+        if (currentUrl && currentUrl !== "about:blank") {
+          stream.emitUrl(currentUrl);
+        }
+      } catch (error) {
+        this.logger.debug?.("Failed to set up page navigation listener", error);
+      }
+    };
+    const cleanup = () => {
+      const timer = this.tabChangeDebounceTimers.get(streamKey);
+      if (timer) {
+        clearTimeout(timer);
+        this.tabChangeDebounceTimers.delete(streamKey);
+      }
+      if (targetInfoDebounceTimer) {
+        clearTimeout(targetInfoDebounceTimer);
+        targetInfoDebounceTimer = null;
+      }
+      connection.off?.("Target.targetCreated", onTargetCreated);
+      connection.off?.("Target.targetDestroyed", onTargetDestroyed);
+      connection.off?.("Target.attachedToTarget", onTargetAttached);
+      connection.off?.("Target.targetInfoChanged", onTargetInfoChanged);
+      if (pageSession?.off) {
+        pageSession.off("Page.frameNavigated", onFrameNavigated);
+      }
+    };
+    stream.once("stop", cleanup);
+    try {
+      connection.on?.("Target.targetCreated", onTargetCreated);
+      connection.on?.("Target.targetDestroyed", onTargetDestroyed);
+      connection.on?.("Target.attachedToTarget", onTargetAttached);
+      connection.on?.("Target.targetInfoChanged", onTargetInfoChanged);
+      await setupPageNavigationListener();
+    } catch (error) {
+      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.
+  // ---------------------------------------------------------------------------
+  // Event Injection (for Studio live view interactivity)
+  // ---------------------------------------------------------------------------
+  async injectMouseEvent(event, threadId) {
+    const effectiveThreadId = threadId ?? this.getCurrentThread();
+    const page = await this.getPageForThread(effectiveThreadId ?? "");
+    const cdpSession = this.getCdpSessionForPage(page);
+    if (!cdpSession) {
+      throw new Error("No CDP session available");
+    }
+    const buttonMap = {
+      none: 0,
+      left: 1,
+      middle: 4,
+      right: 2
+    };
+    const defaultClickCount = event.type === "mousePressed" || event.type === "mouseReleased" ? 1 : 0;
+    await cdpSession.send("Input.dispatchMouseEvent", {
+      type: event.type,
+      x: event.x,
+      y: event.y,
+      button: event.button ?? "none",
+      buttons: buttonMap[event.button ?? "none"] ?? 0,
+      clickCount: event.clickCount ?? defaultClickCount,
+      deltaX: event.deltaX ?? 0,
+      deltaY: event.deltaY ?? 0,
+      modifiers: event.modifiers ?? 0
+    });
+  }
+  async injectKeyboardEvent(event, threadId) {
+    const effectiveThreadId = threadId ?? this.getCurrentThread();
+    const page = await this.getPageForThread(effectiveThreadId ?? "");
+    const cdpSession = this.getCdpSessionForPage(page);
+    if (!cdpSession) {
+      throw new Error("No CDP session available");
+    }
+    await cdpSession.send("Input.dispatchKeyEvent", {
+      type: event.type,
+      key: event.key,
+      code: event.code,
+      text: event.text,
+      modifiers: event.modifiers ?? 0,
+      windowsVirtualKeyCode: event.windowsVirtualKeyCode
+    });
+  }
+};
+
+export { STAGEHAND_TOOLS, StagehandBrowser, actInputSchema, closeInputSchema, createStagehandTools, extractInputSchema, navigateInputSchema, observeInputSchema, stagehandSchemas, tabsInputSchema };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map