@mastra/stagehand 0.3.1 → 0.3.2-alpha.1

package/dist/index.js

@@ -1,1310 +1,1222 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { Stagehand } from '@browserbasehq/stagehand';
-import { MastraBrowser, DEFAULT_THREAD_ID, createBrowserRecordingTools, ScreencastStreamImpl, ThreadManager } from '@mastra/core/browser';
-import { createTool } from '@mastra/core/tools';
-import { z } from 'zod';
-import { join } from 'path';
-
-// src/stagehand-browser.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { Stagehand } from "@browserbasehq/stagehand";
+import { DEFAULT_BROWSER_VIEWPORT, DEFAULT_THREAD_ID, MastraBrowser, ScreencastStreamImpl, ThreadManager, createBrowserRecordingTools, resolveViewportSize } from "@mastra/core/browser";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { join } from "path";
+//#region src/thread-manager.ts
+/**
+* Thread manager for StagehandBrowser.
+*
+* Supports two scope modes:
+* - 'shared': All threads share the shared Stagehand instance
+* - 'thread': Each thread gets a dedicated Stagehand instance
+*/
 var StagehandThreadManager = class extends ThreadManager {
-  sessions = /* @__PURE__ */ new Map();
-  createStagehand;
-  onBrowserCreated;
-  constructor(config) {
-    super(config);
-    this.createStagehand = config.createStagehand;
-    this.onBrowserCreated = config.onBrowserCreated;
-  }
-  /**
-   * Set the factory function for creating new Stagehand instances.
-   * Required for 'thread' scope mode.
-   */
-  setCreateStagehand(factory) {
-    this.createStagehand = factory;
-  }
-  /**
-   * Get the page for a specific thread, creating session if needed.
-   */
-  async getPageForThread(threadId) {
-    const stagehand = await this.getManagerForThread(threadId);
-    return stagehand?.context?.activePage() ?? null;
-  }
-  /**
-   * 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.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);
-      }
-      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}`);
-    }
-  }
-  /**
-   * Get the manager (Stagehand instance) for a specific session.
-   */
-  getManagerForSession(session) {
-    if (this.scope === "thread" && session.stagehand) {
-      return 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}`);
-      }
-    }
-  }
-  /**
-   * Destroy all sessions (called during browser close).
-   * doDestroySession handles closing individual Stagehand instances.
-   */
-  async destroyAllSessions() {
-    await super.destroyAllSessions();
-  }
+	sessions = /* @__PURE__ */ new Map();
+	createStagehand;
+	onBrowserCreated;
+	constructor(config) {
+		super(config);
+		this.createStagehand = config.createStagehand;
+		this.onBrowserCreated = config.onBrowserCreated;
+	}
+	/**
+	* Set the factory function for creating new Stagehand instances.
+	* Required for 'thread' scope mode.
+	*/
+	setCreateStagehand(factory) {
+		this.createStagehand = factory;
+	}
+	/**
+	* Get the page for a specific thread, creating session if needed.
+	*/
+	async getPageForThread(threadId) {
+		return (await this.getManagerForThread(threadId))?.context?.activePage() ?? null;
+	}
+	/**
+	* 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.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);
+			}
+			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 targetPage = context.pages()[state.activeTabIndex];
+			if (targetPage && targetPage !== context.activePage()) context.setActivePage(targetPage);
+		} catch (error) {
+			this.logger?.warn?.(`Failed to restore browser state: ${error}`);
+		}
+	}
+	/**
+	* Get the manager (Stagehand instance) for a specific session.
+	*/
+	getManagerForSession(session) {
+		if (this.scope === "thread" && session.stagehand) return 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}`);
+		}
+	}
+	/**
+	* Destroy all sessions (called during browser close).
+	* doDestroySession handles closing individual Stagehand instances.
+	*/
+	async destroyAllSessions() {
+		await super.destroyAllSessions();
+	}
 };
-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")
+//#endregion
+//#region src/schemas.ts
+/**
+* Stagehand Tool Schemas
+*
+* AI-powered browser tools using natural language instructions.
+* These are fundamentally different from the deterministic AgentBrowser tools.
+*/
+/**
+* stagehand_act - Perform an action using natural language
+*/
+const 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")
+/**
+* stagehand_extract - Extract structured data from a page
+*/
+const 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")
+/**
+* stagehand_observe - Discover actionable elements on a page
+*/
+const 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)")
+/**
+* stagehand_navigate - Navigate to a URL
+*/
+const 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)')
+/**
+* stagehand_close - Close the browser
+*/
+const closeInputSchema = z.object({});
+/**
+* stagehand_tabs - Manage browser tabs
+*/
+const 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 screenshotInputSchema = z.object({
-  fullPage: z.boolean().optional().describe("Capture the full scrollable page instead of just the viewport (default: false)")
+	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,
-  // Utility
-  screenshot: screenshotInputSchema
+/**
+* stagehand_screenshot - Capture a screenshot of the current page
+*/
+const screenshotInputSchema = z.object({ fullPage: z.boolean().optional().describe("Capture the full scrollable page instead of just the viewport (default: false)") });
+const stagehandSchemas = {
+	act: actInputSchema,
+	extract: extractInputSchema,
+	observe: observeInputSchema,
+	navigate: navigateInputSchema,
+	tabs: tabsInputSchema,
+	close: closeInputSchema,
+	screenshot: screenshotInputSchema
 };
-
-// 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",
-  // Utility
-  SCREENSHOT: "stagehand_screenshot"
+//#endregion
+//#region src/tools/constants.ts
+/**
+* Stagehand Tool Constants
+*/
+const STAGEHAND_TOOLS = {
+	ACT: "stagehand_act",
+	EXTRACT: "stagehand_extract",
+	OBSERVE: "stagehand_observe",
+	NAVIGATE: "stagehand_navigate",
+	TABS: "stagehand_tabs",
+	CLOSE: "stagehand_close",
+	SCREENSHOT: "stagehand_screenshot"
 };
-
-// src/tools/act.ts
+//#endregion
+//#region src/tools/act.ts
+/**
+* stagehand_act - Perform an action using natural language
+*/
 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);
-    }
-  });
+	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);
+		}
+	});
 }
+//#endregion
+//#region src/tools/close.ts
+/**
+* stagehand_close - Close the browser
+*/
 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."
-      };
-    }
-  });
+	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."
+			};
+		}
+	});
 }
+//#endregion
+//#region src/tools/extract.ts
+/**
+* stagehand_extract - Extract structured data from a page
+*/
 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);
-    }
-  });
+	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);
+		}
+	});
 }
+//#endregion
+//#region src/tools/navigate.ts
+/**
+* stagehand_navigate - Navigate to a URL
+*/
 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);
-    }
-  });
+	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);
+		}
+	});
 }
+//#endregion
+//#region src/tools/observe.ts
+/**
+* stagehand_observe - Discover actionable elements on a page
+*/
 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);
-    }
-  });
+	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);
+		}
+	});
 }
+//#endregion
+//#region src/tools/screenshot.ts
+/**
+* stagehand_screenshot - Capture a screenshot of the current page
+*/
 function createScreenshotTool(browser) {
-  return createTool({
-    id: STAGEHAND_TOOLS.SCREENSHOT,
-    description: "Capture a screenshot of the current viewport as a visible PNG (set fullPage: true for full-page capture). Use observe or extract when you only need text or interactive elements \u2014 screenshots are expensive. Use this when you need to visually inspect the page, e.g. evaluating images, product photos, layout, design, or colors.",
-    inputSchema: screenshotInputSchema,
-    execute: async (input, { agent }) => {
-      const threadId = agent?.threadId;
-      browser.setCurrentThread(threadId);
-      await browser.ensureReady();
-      return await browser.screenshot(input, threadId);
-    },
-    toModelOutput(output) {
-      const result = output;
-      if (typeof result.base64 !== "string") {
-        return {
-          type: "content",
-          value: [{ type: "text", text: result.message ?? "Failed to capture screenshot." }]
-        };
-      }
-      return {
-        type: "content",
-        value: [
-          {
-            type: "media",
-            mediaType: "image/png",
-            data: result.base64
-          }
-        ]
-      };
-    }
-  });
+	return createTool({
+		id: STAGEHAND_TOOLS.SCREENSHOT,
+		description: "Capture a screenshot of the current viewport as a visible PNG (set fullPage: true for full-page capture). Use observe or extract when you only need text or interactive elements — screenshots are expensive. Use this when you need to visually inspect the page, e.g. evaluating images, product photos, layout, design, or colors.",
+		inputSchema: screenshotInputSchema,
+		execute: async (input, { agent }) => {
+			const threadId = agent?.threadId;
+			browser.setCurrentThread(threadId);
+			await browser.ensureReady();
+			return await browser.screenshot(input, threadId);
+		},
+		toModelOutput(output) {
+			const result = output;
+			if (typeof result.base64 !== "string") return {
+				type: "content",
+				value: [{
+					type: "text",
+					text: result.message ?? "Failed to capture screenshot."
+				}]
+			};
+			return {
+				type: "content",
+				value: [{
+					type: "media",
+					mediaType: "image/png",
+					data: result.base64
+				}]
+			};
+		}
+	});
 }
+//#endregion
+//#region src/tools/tabs.ts
+/**
+* stagehand_tabs - Manage browser tabs
+*/
 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);
-    }
-  });
+	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
+//#endregion
+//#region src/tools/index.ts
+/**
+* Creates all Stagehand tools bound to a StagehandBrowser instance.
+* The browser is lazily initialized on first tool use.
+*/
 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),
-    // Utility
-    [STAGEHAND_TOOLS.SCREENSHOT]: createScreenshotTool(browser)
-  };
+	return {
+		[STAGEHAND_TOOLS.ACT]: createActTool(browser),
+		[STAGEHAND_TOOLS.EXTRACT]: createExtractTool(browser),
+		[STAGEHAND_TOOLS.OBSERVE]: createObserveTool(browser),
+		[STAGEHAND_TOOLS.NAVIGATE]: createNavigateTool(browser),
+		[STAGEHAND_TOOLS.TABS]: createTabsTool(browser),
+		[STAGEHAND_TOOLS.CLOSE]: createCloseTool(browser),
+		[STAGEHAND_TOOLS.SCREENSHOT]: createScreenshotTool(browser)
+	};
 }
+//#endregion
+//#region src/utils.ts
+/**
+* Patch Chrome's Preferences file to set exit_type to "Normal".
+*
+* Stagehand uses chrome-launcher which kills Chrome with SIGKILL. This races
+* with Chrome's own Preferences flush, often leaving exit_type as "Crashed".
+* On next launch Chrome shows the "didn't shut down correctly" restore dialog.
+*
+* Safe to call even if the file doesn't exist or isn't valid JSON.
+*/
 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 {
-  }
+	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 {}
 }
+/**
+* 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).
+*/
 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;
-  }
+	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;
+	}
 }
-
-// src/stagehand-browser.ts
+//#endregion
+//#region src/stagehand-browser.ts
+/**
+* StagehandBrowser - AI-powered browser automation using Stagehand v3
+*
+* Uses natural language instructions for browser interactions.
+* Fundamentally different from AgentBrowser's deterministic refs approach.
+*
+* Stagehand v3 is CDP-native and provides direct CDP access for screencast/input injection.
+*/
+/**
+* StagehandBrowser - AI-powered browser using Stagehand v3
+*
+* Unlike AgentBrowser which uses refs ([ref=e1]), StagehandBrowser uses
+* natural language instructions for all interactions.
+*
+* Supports thread scope via the scope config:
+* - 'shared': All threads share the same Stagehand instance
+* - 'thread': Each thread gets its own Stagehand instance (separate browser)
+*/
 var StagehandBrowser = class extends MastraBrowser {
-  id;
-  name = "StagehandBrowser";
-  provider = "browserbase/stagehand";
-  stagehandConfig;
-  /** Debounce timers per thread for tab change reconnection */
-  tabChangeDebounceTimers = /* @__PURE__ */ new Map();
-  constructor(config = {}) {
-    super(config);
-    this.id = `stagehand-${Date.now()}`;
-    this.stagehandConfig = config;
-    const effectiveScope = config.cdpUrl ? config.scope ?? "shared" : config.scope ?? "thread";
-    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.setupCloseListener(stagehand, () => this.handleThreadBrowserDisconnected(threadId), 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.getManagerForThread(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",
-      model: config.model,
-      experimental: config.experimental,
-      disableAPI: config.disableAPI,
-      selfHeal: config.selfHeal ?? true,
-      domSettleTimeout: config.domSettleTimeout,
-      verbose: config.verbose ?? 0,
-      systemPrompt: config.systemPrompt,
-      logger: config.logger ?? (() => {
-      }),
-      disablePino: config.disablePino ?? true
-    };
-    if (config.env === "BROWSERBASE") {
-      if (config.apiKey) {
-        stagehandOptions.apiKey = config.apiKey;
-      }
-      if (config.projectId) {
-        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: this.headless,
-        viewport: config.viewport,
-        userDataDir: config.profile,
-        executablePath: config.executablePath,
-        preserveUserDataDir: config.preserveUserDataDir
-      };
-    } else if (config.env !== "BROWSERBASE") {
-      stagehandOptions.localBrowserLaunchOptions = {
-        headless: this.headless,
-        viewport: config.viewport,
-        userDataDir: config.profile,
-        executablePath: config.executablePath,
-        preserveUserDataDir: config.preserveUserDataDir
-      };
-    }
-    return stagehandOptions;
-  }
-  /**
-   * Create a new Stagehand instance with the current config.
-   * Used by thread manager for 'thread' scope.
-   */
-  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.sharedManager = await this.createStagehandInstance();
-    this.threadManager.setSharedManager(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.
-   */
-  /**
-   * 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).
-   */
-  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;
-      onDisconnect();
-    };
-    try {
-      const stagehandAny = stagehand;
-      const conn = stagehandAny.ctx?.conn;
-      if (!conn?.on) return;
-      const pageTargets = /* @__PURE__ */ new Set();
-      const context = stagehand.context;
-      if (context) {
-        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);
-      });
-      conn.on("Target.targetDestroyed", (params) => {
-        if (pageTargets.has(params.targetId)) {
-          pageTargets.delete(params.targetId);
-          if (pageTargets.size === 0) handleDisconnect();
-        }
-      });
-    } catch {
-    }
-  }
-  async doClose() {
-    await this.threadManager.destroyAllSessions();
-    if (this.sharedManager) {
-      await this.sharedManager.close();
-      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.
-   * Called by base class ensureReady() to detect externally closed browsers.
-   */
-  async checkBrowserAlive() {
-    const scope = this.getScope();
-    if (scope === "thread") {
-      return this.threadManager.hasActiveThreadManagers();
-    }
-    if (!this.sharedManager) {
-      return false;
-    }
-    try {
-      const context = this.sharedManager.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.sharedManager);
-        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;
-    }
-  }
-  /**
-   * 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 'thread' scope, this creates a dedicated Stagehand instance.
-   * For 'shared' scope, returns the shared instance.
-   */
-  async getManagerForThread(threadId) {
-    const scope = this.getScope();
-    if (scope === "shared") {
-      return this.sharedManager;
-    }
-    if (!threadId || threadId === DEFAULT_THREAD_ID) {
-      return this.sharedManager;
-    }
-    let stagehand = this.threadManager.getExistingManagerForThread(threadId);
-    if (!stagehand) {
-      await this.threadManager.getManagerForThread(threadId);
-      stagehand = this.threadManager.getExistingManagerForThread(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.getExistingManagerForThread(threadId) ?? this.sharedManager;
-    if (!stagehand) {
-      throw new Error("Browser not launched");
-    }
-    return stagehand;
-  }
-  /**
-   * 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.
-   */
-  getPage(explicitThreadId) {
-    const scope = this.getScope();
-    const threadId = explicitThreadId ?? this.getCurrentThread();
-    if (scope === "thread" && threadId && threadId !== DEFAULT_THREAD_ID) {
-      const stagehand = this.threadManager.getExistingManagerForThread(threadId);
-      if (stagehand?.context) {
-        return stagehand.context.activePage();
-      }
-      return null;
-    }
-    if (!this.sharedManager) return null;
-    try {
-      const context = this.sharedManager.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 active page for a thread (implements abstract method from base class).
-   */
-  async getActivePage(threadId) {
-    return this.getPage(threadId);
-  }
-  /**
-   * 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() {
-    const tools = createStagehandTools(this);
-    if (this.stagehandConfig.recording) {
-      Object.assign(tools, createBrowserRecordingTools(this, this.stagehandConfig.recording));
-    }
-    const exclude = this.stagehandConfig.excludeTools;
-    if (exclude?.length) {
-      for (const name of exclude) {
-        delete tools[name];
-      }
-    }
-    return tools;
-  }
-  // ---------------------------------------------------------------------------
-  // 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");
-    }
-  }
-  // ---------------------------------------------------------------------------
-  // Screenshot
-  // ---------------------------------------------------------------------------
-  /**
-   * Capture a screenshot of the current page
-   * @param input - Screenshot input
-   * @param threadId - Optional thread ID for thread-safe operation
-   */
-  async screenshot(input, threadId) {
-    const page = this.getPage(threadId);
-    if (!page) {
-      return this.createError("browser_error", "Browser page not available.", "Ensure the browser is launched.");
-    }
-    try {
-      const buffer = await page.screenshot({
-        fullPage: input.fullPage ?? false,
-        type: "png"
-      });
-      const base64 = Buffer.from(buffer).toString("base64");
-      const url = page.url();
-      const title = await page.title();
-      return { base64, url, title };
-    } catch (error) {
-      return this.createErrorFromException(error, "Screenshot");
-    }
-  }
-  // ---------------------------------------------------------------------------
-  // 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.getExistingManagerForThread(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.sharedManager);
-        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.getExistingManagerForThread(effectiveThreadId);
-        if (!stagehand) return null;
-        return this.getBrowserStateFromStagehand(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.
-   */
-  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;
-  }
-  // ---------------------------------------------------------------------------
-  // Screencast (for Studio live view)
-  // Uses Stagehand v3's native CDP access
-  // ---------------------------------------------------------------------------
-  async startScreencast(options) {
-    const threadId = options?.threadId;
-    const provider = {
-      getCdpSession: async () => {
-        const page = await this.threadManager.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.getManagerForThread(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.reconnectScreencastForThread(threadId, "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);
-        const existingTimer = this.tabChangeDebounceTimers.get(streamKey);
-        if (existingTimer) {
-          clearTimeout(existingTimer);
-        }
-        this.tabChangeDebounceTimers.set(
-          streamKey,
-          setTimeout(() => {
-            this.tabChangeDebounceTimers.delete(streamKey);
-            void this.reconnectScreencastForThread(threadId, "same-tab navigation");
-          }, 300)
-        );
-      }
-    };
-    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);
-    }
-  }
-  // 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.threadManager.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.threadManager.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
-    });
-  }
+	id;
+	name = "StagehandBrowser";
+	provider = "browserbase/stagehand";
+	stagehandConfig;
+	/** Debounce timers per thread for tab change reconnection */
+	tabChangeDebounceTimers = /* @__PURE__ */ new Map();
+	constructor(config = {}) {
+		super(config);
+		this.id = `stagehand-${Date.now()}`;
+		this.stagehandConfig = config;
+		const effectiveScope = config.cdpUrl ? config.scope ?? "shared" : config.scope ?? "thread";
+		this.threadManager = new StagehandThreadManager({
+			scope: effectiveScope,
+			logger: this.logger,
+			onSessionCreated: (session) => {
+				this.notifyBrowserReady(session.threadId);
+			},
+			onBrowserCreated: (stagehand, threadId) => {
+				this.setupCloseListener(stagehand, () => this.handleThreadBrowserDisconnected(threadId), 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.getManagerForThread(threadId);
+	}
+	/**
+	* 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",
+			model: config.model,
+			experimental: config.experimental,
+			disableAPI: config.disableAPI,
+			selfHeal: config.selfHeal ?? true,
+			domSettleTimeout: config.domSettleTimeout,
+			verbose: config.verbose ?? 0,
+			systemPrompt: config.systemPrompt,
+			logger: config.logger ?? (() => {}),
+			disablePino: config.disablePino ?? true
+		};
+		if (config.env === "BROWSERBASE") {
+			if (config.apiKey) stagehandOptions.apiKey = config.apiKey;
+			if (config.projectId) 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);
+			stagehandOptions.localBrowserLaunchOptions = {
+				cdpUrl: await this.resolveWebSocketUrl(resolvedUrl),
+				headless: this.headless,
+				viewport: resolveViewportSize(config.viewport),
+				userDataDir: config.profile,
+				executablePath: config.executablePath,
+				preserveUserDataDir: config.preserveUserDataDir
+			};
+		} else if (config.env !== "BROWSERBASE") stagehandOptions.localBrowserLaunchOptions = {
+			headless: this.headless,
+			viewport: resolveViewportSize(config.viewport) ?? DEFAULT_BROWSER_VIEWPORT,
+			userDataDir: config.profile,
+			executablePath: config.executablePath,
+			preserveUserDataDir: config.preserveUserDataDir
+		};
+		return stagehandOptions;
+	}
+	/**
+	* Create a new Stagehand instance with the current config.
+	* Used by thread manager for 'thread' scope.
+	*/
+	async createStagehandInstance() {
+		const stagehand = new Stagehand(await this.buildStagehandOptions());
+		await stagehand.init();
+		return stagehand;
+	}
+	async doLaunch() {
+		const scope = this.getScope();
+		this.threadManager.setCreateStagehand(() => this.createStagehandInstance());
+		if (scope === "thread") return;
+		this.sharedManager = await this.createStagehandInstance();
+		this.threadManager.setSharedManager(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.
+	*/
+	/**
+	* 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).
+	*/
+	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;
+			onDisconnect();
+		};
+		try {
+			const conn = stagehand.ctx?.conn;
+			if (!conn?.on) return;
+			const pageTargets = /* @__PURE__ */ new Set();
+			const context = stagehand.context;
+			if (context) 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);
+			});
+			conn.on("Target.targetDestroyed", (params) => {
+				if (pageTargets.has(params.targetId)) {
+					pageTargets.delete(params.targetId);
+					if (pageTargets.size === 0) handleDisconnect();
+				}
+			});
+		} catch {}
+	}
+	async doClose() {
+		await this.threadManager.destroyAllSessions();
+		if (this.sharedManager) {
+			await this.sharedManager.close();
+			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.
+	* Called by base class ensureReady() to detect externally closed browsers.
+	*/
+	async checkBrowserAlive() {
+		if (this.getScope() === "thread") return this.threadManager.hasActiveThreadManagers();
+		if (!this.sharedManager) return false;
+		try {
+			const context = this.sharedManager.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.sharedManager);
+				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;
+		}
+	}
+	/**
+	* 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);
+	}
+	/**
+	* Get the Stagehand instance for a thread, creating it if needed.
+	* For 'thread' scope, this creates a dedicated Stagehand instance.
+	* For 'shared' scope, returns the shared instance.
+	*/
+	async getManagerForThread(threadId) {
+		if (this.getScope() === "shared") return this.sharedManager;
+		if (!threadId || threadId === DEFAULT_THREAD_ID) return this.sharedManager;
+		let stagehand = this.threadManager.getExistingManagerForThread(threadId);
+		if (!stagehand) {
+			await this.threadManager.getManagerForThread(threadId);
+			stagehand = this.threadManager.getExistingManagerForThread(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.getExistingManagerForThread(threadId) ?? this.sharedManager;
+		if (!stagehand) throw new Error("Browser not launched");
+		return stagehand;
+	}
+	/**
+	* 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.
+	*/
+	getPage(explicitThreadId) {
+		const scope = this.getScope();
+		const threadId = explicitThreadId ?? this.getCurrentThread();
+		if (scope === "thread" && threadId && threadId !== DEFAULT_THREAD_ID) {
+			const stagehand = this.threadManager.getExistingManagerForThread(threadId);
+			if (stagehand?.context) return stagehand.context.activePage();
+			return null;
+		}
+		if (!this.sharedManager) return null;
+		try {
+			const context = this.sharedManager.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 active page for a thread (implements abstract method from base class).
+	*/
+	async getActivePage(threadId) {
+		return this.getPage(threadId);
+	}
+	/**
+	* 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;
+	}
+	getTools() {
+		const tools = createStagehandTools(this);
+		if (this.stagehandConfig.recording) Object.assign(tools, createBrowserRecordingTools(this, this.stagehandConfig.recording));
+		const exclude = this.stagehandConfig.excludeTools;
+		if (exclude?.length) for (const name of exclude) delete tools[name];
+		return tools;
+	}
+	/**
+	* 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 };
+			return {
+				success: true,
+				data: input.schema ? await stagehand.extract(input.instruction, input.schema, options) : await stagehand.extract(input.instruction, options),
+				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");
+		}
+	}
+	/**
+	* 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" });
+			return {
+				success: true,
+				url: page.url(),
+				title: await page.title(),
+				hint: "Page loaded. Use observe() to discover actions or extract() to get data."
+			};
+		} catch (error) {
+			return this.createErrorFromException(error, "Navigate");
+		}
+	}
+	/**
+	* Capture a screenshot of the current page
+	* @param input - Screenshot input
+	* @param threadId - Optional thread ID for thread-safe operation
+	*/
+	async screenshot(input, threadId) {
+		const page = this.getPage(threadId);
+		if (!page) return this.createError("browser_error", "Browser page not available.", "Ensure the browser is launched.");
+		try {
+			const buffer = await page.screenshot({
+				fullPage: input.fullPage ?? false,
+				type: "png"
+			});
+			return {
+				base64: Buffer.from(buffer).toString("base64"),
+				url: page.url(),
+				title: await page.title()
+			};
+		} catch (error) {
+			return this.createErrorFromException(error, "Screenshot");
+		}
+	}
+	/**
+	* 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 context = this.requireStagehand(effectiveThreadId).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();
+					return {
+						success: true,
+						tabs: await Promise.all(pages.map(async (page, index) => ({
+							index,
+							url: page.url(),
+							title: await page.title(),
+							active: page === activePage
+						}))),
+						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.");
+					await pages[indexToClose].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");
+		}
+	}
+	async getCurrentUrl(threadId) {
+		if (!this.isBrowserRunning()) return null;
+		const effectiveThreadId = threadId ?? this.getCurrentThread();
+		if (this.threadManager.getScope() === "thread" && effectiveThreadId) {
+			const stagehand = this.threadManager.getExistingManagerForThread(effectiveThreadId);
+			if (!stagehand?.context) return null;
+			const url = stagehand.context.activePage()?.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.sharedManager);
+				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.getExistingManagerForThread(effectiveThreadId);
+				if (!stagehand) return null;
+				return this.getBrowserStateFromStagehand(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.
+	*/
+	getBrowserStateFromStagehand(stagehand) {
+		if (!stagehand?.context) return null;
+		try {
+			const pages = stagehand.context.pages();
+			const activePage = stagehand.context.activePage();
+			let activeIndex = 0;
+			return {
+				tabs: pages.map((page, index) => {
+					if (page === activePage) activeIndex = index;
+					return { url: page.url() };
+				}),
+				activeTabIndex: activeIndex
+			};
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Get all open tabs with their URLs and titles.
+	*/
+	async getTabState(threadId) {
+		return (await this.getBrowserState(threadId))?.tabs ?? [];
+	}
+	/**
+	* Get the active tab index.
+	*/
+	async getActiveTabIndex(threadId) {
+		return (await this.getBrowserState(threadId))?.activeTabIndex ?? 0;
+	}
+	async startScreencast(options) {
+		const threadId = options?.threadId;
+		const stream = new ScreencastStreamImpl({
+			getCdpSession: async () => {
+				const page = await this.threadManager.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()
+		}, 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.getManagerForThread(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) => {
+			return (stagehand.context?.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);
+				this.reconnectScreencastForThread(threadId, "new tab");
+				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;
+			if (!targetSessions.get(params.targetInfo.targetId)) 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 newPage = (stagehand.context?.pages() || []).find((p) => p.targetId() === info.targetId);
+						if (newPage && stagehand.context) stagehand.context.setActivePage(newPage);
+						this.reconnectScreencastForThread(threadId, "manual tab tracked");
+						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);
+				this.reconnectScreencastForThread(threadId, "tab closed");
+				setupPageNavigationListener();
+			}, 300));
+		};
+		const onFrameNavigated = (params) => {
+			if (!params.frame.parentId && params.frame.url) {
+				stream.emitUrl(params.frame.url);
+				this.updateSessionBrowserState(threadId);
+				const existingTimer = this.tabChangeDebounceTimers.get(streamKey);
+				if (existingTimer) clearTimeout(existingTimer);
+				this.tabChangeDebounceTimers.set(streamKey, setTimeout(() => {
+					this.tabChangeDebounceTimers.delete(streamKey);
+					this.reconnectScreencastForThread(threadId, "same-tab navigation");
+				}, 300));
+			}
+		};
+		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);
+		}
+	}
+	async injectMouseEvent(event, threadId) {
+		const effectiveThreadId = threadId ?? this.getCurrentThread();
+		const page = await this.threadManager.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.threadManager.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
+		});
+	}
 };
+//#endregion
+//#region src/types.ts
+/**
+* Providers Stagehand can resolve from a `provider/model` string.
+*
+* Stagehand splits the model id on its first slash and looks the prefix up in
+* its internal AI SDK provider registry; an unknown prefix throws during
+* browser startup rather than at configuration time. Mirrored here so callers
+* can reject a bad provider up front. Keep in sync with `AISDKProviders` in
+* `@browserbasehq/stagehand`.
+*/
+const STAGEHAND_MODEL_PROVIDERS = [
+	"anthropic",
+	"azure",
+	"bedrock",
+	"cerebras",
+	"deepseek",
+	"gateway",
+	"google",
+	"groq",
+	"mistral",
+	"ollama",
+	"openai",
+	"perplexity",
+	"togetherai",
+	"vertex",
+	"xai"
+];
+//#endregion
+export { STAGEHAND_MODEL_PROVIDERS, STAGEHAND_TOOLS, StagehandBrowser, actInputSchema, closeInputSchema, createStagehandTools, extractInputSchema, getStagehandChromePid, 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