@mastra/agent-browser 0.0.0-async-hooks-fix-20260405144639

package/dist/index.cjs

@@ -0,0 +1,1577 @@
+'use strict';
+
+var browser = require('@mastra/core/browser');
+var agentBrowser = require('agent-browser');
+var tools = require('@mastra/core/tools');
+var zod = require('zod');
+
+// src/agent-browser.ts
+var AgentBrowserThreadManager = class extends browser.ThreadManager {
+  browserConfig;
+  resolveCdpUrl;
+  onBrowserCreated;
+  constructor(config) {
+    super(config);
+    this.browserConfig = config.browserConfig;
+    this.resolveCdpUrl = config.resolveCdpUrl;
+    this.onBrowserCreated = config.onBrowserCreated;
+  }
+  /**
+   * Get the page for a specific thread, creating session if needed.
+   */
+  async getPageForThread(threadId) {
+    const manager = await this.getManagerForThread(threadId);
+    return manager.getPage();
+  }
+  /**
+   * 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") {
+      const manager = new agentBrowser.BrowserManager();
+      const launchOptions = {
+        headless: this.browserConfig.headless ?? true,
+        viewport: this.browserConfig.viewport
+      };
+      if (this.browserConfig.cdpUrl && this.resolveCdpUrl) {
+        launchOptions.cdpUrl = await this.resolveCdpUrl(this.browserConfig.cdpUrl);
+      }
+      try {
+        await manager.launch(launchOptions);
+      } catch (error) {
+        try {
+          await manager.close();
+        } catch {
+        }
+        throw error;
+      }
+      session.manager = manager;
+      this.threadManagers.set(threadId, manager);
+      try {
+        if (savedState && savedState.tabs.length > 0) {
+          this.logger?.debug?.(`Restoring browser state for thread ${threadId}: ${savedState.tabs.length} tabs`);
+          await this.restoreBrowserState(manager, savedState);
+        }
+        this.onBrowserCreated?.(manager, threadId);
+      } catch (error) {
+        this.threadManagers.delete(threadId);
+        session.manager = void 0;
+        try {
+          await manager.close();
+        } catch {
+        }
+        throw error;
+      }
+    }
+    return session;
+  }
+  /**
+   * Restore browser state (multiple tabs) to a browser manager.
+   */
+  async restoreBrowserState(manager, state) {
+    try {
+      const firstTab = state.tabs[0];
+      if (firstTab?.url) {
+        const page = manager.getPage();
+        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 manager.newTab();
+          const page = manager.getPage();
+          if (page) {
+            await page.goto(tab.url, { waitUntil: "domcontentloaded" });
+          }
+        }
+      }
+      if (state.tabs.length > 1 && state.activeTabIndex >= 0 && state.activeTabIndex < state.tabs.length) {
+        await manager.switchTo(state.activeTabIndex);
+      }
+    } catch (error) {
+      this.logger?.warn?.(`Failed to restore browser state: ${error}`);
+    }
+  }
+  /**
+   * Get the browser manager for a specific session.
+   */
+  getManagerForSession(session) {
+    if (this.scope === "thread" && session.manager) {
+      return session.manager;
+    }
+    return this.getSharedManager();
+  }
+  /**
+   * Destroy a session and clean up resources.
+   */
+  async doDestroySession(session) {
+    if (this.scope === "thread" && session.manager) {
+      await session.manager.close();
+    }
+  }
+  /**
+   * Destroy all sessions (called during browser close).
+   * doDestroySession handles closing individual browser managers.
+   */
+  async destroyAllSessions() {
+    await super.destroyAllSessions();
+  }
+};
+var gotoInputSchema = zod.z.object({
+  url: zod.z.string().describe("The URL to navigate to"),
+  waitUntil: zod.z.enum(["load", "domcontentloaded", "networkidle"]).optional().describe("When to consider navigation complete (default: domcontentloaded)"),
+  timeout: zod.z.number().optional().describe("Navigation timeout in milliseconds")
+});
+var snapshotInputSchema = zod.z.object({
+  interactiveOnly: zod.z.boolean().optional().describe("Only include interactive elements (default: true)"),
+  maxDepth: zod.z.number().optional().describe("Maximum depth of the tree to return")
+});
+var clickInputSchema = zod.z.object({
+  ref: zod.z.string().describe("Element ref from snapshot (e.g., @e5)"),
+  button: zod.z.enum(["left", "right", "middle"]).optional().describe("Mouse button (default: left)"),
+  clickCount: zod.z.number().optional().describe("Number of clicks (default: 1, use 2 for double-click)"),
+  modifiers: zod.z.array(zod.z.enum(["Alt", "Control", "Meta", "Shift"])).optional().describe("Modifier keys to hold")
+});
+var typeInputSchema = zod.z.object({
+  ref: zod.z.string().describe("Element ref from snapshot"),
+  text: zod.z.string().describe("Text to type"),
+  clear: zod.z.boolean().optional().describe("Clear existing content before typing (default: false)"),
+  delay: zod.z.number().optional().describe("Delay between keystrokes in ms")
+});
+var pressInputSchema = zod.z.object({
+  key: zod.z.string().describe("Key to press (e.g., Enter, Tab, Escape, Control+a)"),
+  modifiers: zod.z.array(zod.z.enum(["Alt", "Control", "Meta", "Shift"])).optional().describe("Modifier keys to hold")
+});
+var selectInputSchema = zod.z.object({
+  ref: zod.z.string().describe("Select element ref from snapshot"),
+  value: zod.z.string().optional().describe("Option value to select"),
+  label: zod.z.string().optional().describe("Option label to select"),
+  index: zod.z.number().int().min(0).optional().describe("Option index to select (0-based)")
+}).superRefine((data, ctx) => {
+  if (data.value === void 0 && data.label === void 0 && data.index === void 0) {
+    ctx.addIssue({
+      code: zod.z.ZodIssueCode.custom,
+      message: "At least one of value, label, or index is required"
+    });
+  }
+});
+var scrollInputSchema = zod.z.object({
+  direction: zod.z.enum(["up", "down", "left", "right"]).describe("Scroll direction"),
+  amount: zod.z.number().optional().describe("Scroll amount in pixels (default: 300)"),
+  ref: zod.z.string().optional().describe("Element ref to scroll (scrolls page if omitted)")
+});
+var closeInputSchema = zod.z.object({});
+var hoverInputSchema = zod.z.object({
+  ref: zod.z.string().describe("Element ref from snapshot")
+});
+var backInputSchema = zod.z.object({});
+var dialogInputSchema = zod.z.object({
+  triggerRef: zod.z.string().describe("Element ref that triggers the dialog (e.g., @e5)"),
+  action: zod.z.enum(["accept", "dismiss"]).describe("Accept or dismiss the dialog"),
+  text: zod.z.string().optional().describe("Text to enter for prompt dialogs")
+});
+var waitInputSchema = zod.z.object({
+  ref: zod.z.string().optional().describe("Element ref to wait for"),
+  state: zod.z.enum(["visible", "hidden", "attached", "detached"]).optional().describe("State to wait for (default: visible)"),
+  timeout: zod.z.number().optional().describe("Maximum wait time in ms (default: 30000)")
+});
+var tabsInputSchema = zod.z.object({
+  action: zod.z.enum(["list", "new", "switch", "close"]).describe("Tab action"),
+  index: zod.z.number().int().min(0).optional().describe("Tab index for switch/close"),
+  url: zod.z.string().optional().describe("URL to open in new tab")
+}).superRefine((value, ctx) => {
+  if (value.action === "switch" && value.index === void 0) {
+    ctx.addIssue({
+      code: zod.z.ZodIssueCode.custom,
+      path: ["index"],
+      message: 'index is required when action is "switch"'
+    });
+  }
+});
+var dragInputSchema = zod.z.object({
+  sourceRef: zod.z.string().optional().describe("Element ref to drag from (e.g., @e5)"),
+  targetRef: zod.z.string().optional().describe("Element ref to drag to (e.g., @e7)"),
+  sourceSelector: zod.z.string().optional().describe("CSS selector for source element (use if ref not available)"),
+  targetSelector: zod.z.string().optional().describe("CSS selector for target element (use if ref not available)")
+}).superRefine((data, ctx) => {
+  if (!data.sourceRef && !data.sourceSelector) {
+    ctx.addIssue({
+      code: zod.z.ZodIssueCode.custom,
+      path: ["sourceRef"],
+      message: "Either sourceRef or sourceSelector is required"
+    });
+  }
+  if (!data.targetRef && !data.targetSelector) {
+    ctx.addIssue({
+      code: zod.z.ZodIssueCode.custom,
+      path: ["targetRef"],
+      message: "Either targetRef or targetSelector is required"
+    });
+  }
+});
+var evaluateInputSchema = zod.z.object({
+  script: zod.z.string().describe("JavaScript code to execute"),
+  arg: zod.z.unknown().optional().describe("Argument to pass to the script (JSON-serializable)")
+});
+var browserSchemas = {
+  // Core
+  goto: gotoInputSchema,
+  snapshot: snapshotInputSchema,
+  click: clickInputSchema,
+  type: typeInputSchema,
+  press: pressInputSchema,
+  select: selectInputSchema,
+  scroll: scrollInputSchema,
+  close: closeInputSchema,
+  // Extended
+  hover: hoverInputSchema,
+  back: backInputSchema,
+  dialog: dialogInputSchema,
+  wait: waitInputSchema,
+  tabs: tabsInputSchema,
+  drag: dragInputSchema,
+  // Escape hatch
+  evaluate: evaluateInputSchema
+};
+
+// src/tools/constants.ts
+var BROWSER_TOOLS = {
+  // Core
+  GOTO: "browser_goto",
+  SNAPSHOT: "browser_snapshot",
+  CLICK: "browser_click",
+  TYPE: "browser_type",
+  PRESS: "browser_press",
+  SELECT: "browser_select",
+  SCROLL: "browser_scroll",
+  CLOSE: "browser_close",
+  // Extended
+  HOVER: "browser_hover",
+  BACK: "browser_back",
+  DIALOG: "browser_dialog",
+  WAIT: "browser_wait",
+  TABS: "browser_tabs",
+  DRAG: "browser_drag",
+  // Escape hatch
+  EVALUATE: "browser_evaluate"
+};
+
+// src/tools/back.ts
+function createBackTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.BACK,
+    description: "Go back to the previous page in browser history.",
+    inputSchema: backInputSchema,
+    execute: async (_input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.back(threadId);
+    }
+  });
+}
+function createClickTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.CLICK,
+    description: "Click an element using its ref from a snapshot. Use clickCount: 2 for double-click.",
+    inputSchema: clickInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.click(input, threadId);
+    }
+  });
+}
+function createCloseTool(browser) {
+  return tools.createTool({
+    id: BROWSER_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("browser_close requires agent.threadId when browser scope is not shared");
+        }
+        await browser.closeThreadSession(threadId);
+        return { success: true, hint: "Thread's browser session closed. A new session will be created on next use." };
+      }
+      await browser.close();
+      return { success: true, hint: "Browser closed. It will be re-launched automatically on next use." };
+    }
+  });
+}
+function createDialogTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.DIALOG,
+    description: "Click an element that triggers a browser dialog (alert, confirm, prompt) and handle it. Use this instead of browser_click when you expect a dialog to appear.",
+    inputSchema: dialogInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.dialog(input, threadId);
+    }
+  });
+}
+function createDragTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.DRAG,
+    description: "Drag an element to another element. Use refs from snapshot when available, or CSS selectors for elements not exposed in the accessibility tree.",
+    inputSchema: dragInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.drag(input, threadId);
+    }
+  });
+}
+function createEvaluateTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.EVALUATE,
+    description: "Execute JavaScript in the browser. Use for complex interactions not covered by other tools. Returns the script result.",
+    inputSchema: evaluateInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.evaluate(input, threadId);
+    }
+  });
+}
+function createGotoTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.GOTO,
+    description: "Navigate the browser to a URL.",
+    inputSchema: gotoInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.goto(input, threadId);
+    }
+  });
+}
+function createHoverTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.HOVER,
+    description: "Hover over an element to trigger hover states (dropdowns, tooltips).",
+    inputSchema: hoverInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.hover(input, threadId);
+    }
+  });
+}
+function createPressTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.PRESS,
+    description: "Press a keyboard key (e.g., Enter, Tab, Escape, Control+a).",
+    inputSchema: pressInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.press(input, threadId);
+    }
+  });
+}
+function createScrollTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.SCROLL,
+    description: "Scroll the page or a specific element.",
+    inputSchema: scrollInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.scroll(input, threadId);
+    }
+  });
+}
+function createSelectTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.SELECT,
+    description: "Select an option from a dropdown by value, label, or index.",
+    inputSchema: selectInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.select(input, threadId);
+    }
+  });
+}
+function createSnapshotTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.SNAPSHOT,
+    description: "Get accessibility tree snapshot of the page. Returns text-based representation with element refs like [ref=e1], [ref=e2] for targeting.",
+    inputSchema: snapshotInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.snapshot(input, threadId);
+    }
+  });
+}
+function createTabsTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.TABS,
+    description: "Manage browser tabs: list, open new, switch, or close tabs.",
+    inputSchema: tabsInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.tabs(input, threadId);
+    }
+  });
+}
+function createTypeTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.TYPE,
+    description: "Type text into an input element. Use clear: true to replace existing content.",
+    inputSchema: typeInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.type(input, threadId);
+    }
+  });
+}
+function createWaitTool(browser) {
+  return tools.createTool({
+    id: BROWSER_TOOLS.WAIT,
+    description: "Wait for an element to appear, disappear, or reach a state.",
+    inputSchema: waitInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return browser.wait(input, threadId);
+    }
+  });
+}
+
+// src/tools/index.ts
+function createAgentBrowserTools(browser) {
+  return {
+    // Core (9)
+    [BROWSER_TOOLS.GOTO]: createGotoTool(browser),
+    [BROWSER_TOOLS.SNAPSHOT]: createSnapshotTool(browser),
+    [BROWSER_TOOLS.CLICK]: createClickTool(browser),
+    [BROWSER_TOOLS.TYPE]: createTypeTool(browser),
+    [BROWSER_TOOLS.PRESS]: createPressTool(browser),
+    [BROWSER_TOOLS.SELECT]: createSelectTool(browser),
+    [BROWSER_TOOLS.SCROLL]: createScrollTool(browser),
+    [BROWSER_TOOLS.CLOSE]: createCloseTool(browser),
+    // Extended
+    [BROWSER_TOOLS.HOVER]: createHoverTool(browser),
+    [BROWSER_TOOLS.BACK]: createBackTool(browser),
+    [BROWSER_TOOLS.DIALOG]: createDialogTool(browser),
+    [BROWSER_TOOLS.WAIT]: createWaitTool(browser),
+    [BROWSER_TOOLS.TABS]: createTabsTool(browser),
+    [BROWSER_TOOLS.DRAG]: createDragTool(browser),
+    // Escape hatch (1)
+    [BROWSER_TOOLS.EVALUATE]: createEvaluateTool(browser)
+  };
+}
+
+// src/agent-browser.ts
+var AgentBrowser = class extends browser.MastraBrowser {
+  id;
+  name = "AgentBrowser";
+  provider = "vercel-labs/agent-browser";
+  defaultTimeout = 3e4;
+  constructor(config = {}) {
+    super(config);
+    this.id = `agent-browser-${Date.now()}`;
+    if (config.timeout) {
+      this.defaultTimeout = config.timeout;
+    }
+    const effectiveScope = config.cdpUrl ? config.scope ?? "shared" : config.scope ?? "thread";
+    this.threadManager = new AgentBrowserThreadManager({
+      scope: effectiveScope,
+      browserConfig: config,
+      resolveCdpUrl: this.resolveCdpUrl.bind(this),
+      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: (manager, threadId) => {
+        this.setupCloseListenerForThread(manager, threadId);
+      }
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Thread Scope (delegated to ThreadManager)
+  // ---------------------------------------------------------------------------
+  /**
+   * Ensure browser is ready and thread session exists.
+   * Creates a new page/context for the current thread if needed.
+   *
+   * For 'thread' scope, we need to create the thread session BEFORE
+   * calling super.ensureReady() because the base class's ensureReady() will
+   * call checkBrowserAlive(), which needs at least one thread browser to exist.
+   */
+  async ensureReady() {
+    const scope = this.threadManager.getScope();
+    const threadId = this.getCurrentThread();
+    const existingSession = this.threadManager.hasSession(threadId);
+    if (scope === "thread" && threadId !== browser.DEFAULT_THREAD_ID && !existingSession) {
+      await this.getManagerForThread(threadId);
+    }
+    await super.ensureReady();
+    if (scope === "thread" && threadId !== browser.DEFAULT_THREAD_ID && existingSession) {
+      await this.getManagerForThread(threadId);
+    }
+  }
+  /**
+   * Get the browser manager for the current thread.
+   * Delegates to ThreadManager for scope handling.
+   */
+  async getManagerForThread(threadId) {
+    const effectiveThreadId = threadId ?? this.getCurrentThread();
+    const scope = this.threadManager.getScope();
+    if (scope === "thread" && (!effectiveThreadId || effectiveThreadId === browser.DEFAULT_THREAD_ID)) {
+      const existingManager = this.threadManager.getExistingManagerForThread(effectiveThreadId);
+      if (existingManager) {
+        return existingManager;
+      }
+    }
+    return this.threadManager.getManagerForThread(effectiveThreadId);
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+  async doLaunch() {
+    const scope = this.threadManager.getScope();
+    if (scope === "thread") {
+      this.sharedManager = new agentBrowser.BrowserManager();
+      this.threadManager.setSharedManager(this.sharedManager);
+      return;
+    }
+    this.sharedManager = new agentBrowser.BrowserManager();
+    const localConfig = this.config;
+    const launchOptions = {
+      headless: localConfig.headless ?? true,
+      viewport: localConfig.viewport
+    };
+    if (localConfig.cdpUrl) {
+      launchOptions.cdpUrl = await this.resolveCdpUrl(localConfig.cdpUrl);
+    }
+    await this.sharedManager.launch(launchOptions);
+    this.threadManager.setSharedManager(this.sharedManager);
+    this.setupCloseListenerForSharedScope(this.sharedManager);
+  }
+  /**
+   * Set up close event listeners for 'shared' scope browser.
+   * This handles the case where the shared browser is closed externally.
+   */
+  setupCloseListenerForSharedScope(manager) {
+    try {
+      let disconnectHandled = false;
+      const handleDisconnect = () => {
+        if (disconnectHandled) return;
+        disconnectHandled = true;
+        this.handleBrowserDisconnected();
+      };
+      const context = manager.getContext();
+      if (context) {
+        context.on("close", handleDisconnect);
+      }
+      const pages = manager.getPages();
+      for (const page of pages) {
+        page.on("close", () => {
+          const remainingPages = manager.getPages();
+          if (remainingPages.length === 0) {
+            handleDisconnect();
+          }
+        });
+      }
+    } catch {
+    }
+  }
+  async doClose() {
+    await this.threadManager.destroyAllSessions();
+    this.setCurrentThread(void 0);
+    const scope = this.threadManager.getScope();
+    if (scope === "shared" && this.sharedManager) {
+      await this.sharedManager.close();
+    }
+    this.sharedManager = null;
+  }
+  /**
+   * Check if the browser is still alive by verifying the page is connected.
+   * Called by base class ensureReady() to detect externally closed browsers.
+   */
+  async checkBrowserAlive() {
+    const scope = this.threadManager.getScope();
+    if (scope === "thread") {
+      return this.threadManager.hasActiveThreadManagers();
+    }
+    if (!this.sharedManager) {
+      return false;
+    }
+    try {
+      const page = this.sharedManager.getPage();
+      const url = page.url();
+      if (url && url !== "about:blank") {
+        const state = await this.getBrowserState();
+        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;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Tools
+  // ---------------------------------------------------------------------------
+  /**
+   * Get the browser tools for this provider.
+   * Returns 17 flat tools for browser automation.
+   */
+  getTools() {
+    return createAgentBrowserTools(this);
+  }
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * Get the page for the current thread.
+   * Uses thread scope if enabled, otherwise returns the shared page.
+   * @param explicitThreadId - Optional thread ID to use instead of getCurrentThread()
+   *                           Use this to avoid race conditions in concurrent tool calls.
+   */
+  async getPage(explicitThreadId) {
+    const scope = this.getScope();
+    const threadId = explicitThreadId ?? this.getCurrentThread();
+    if (scope === "thread") {
+      return this.threadManager.getPageForThread(threadId);
+    }
+    if (!this.sharedManager) throw new Error("Browser not launched");
+    return this.sharedManager.getPage();
+  }
+  /**
+   * Get the active page for a thread (implements abstract method from base class).
+   * Returns null if no page is available, unlike getPage which throws.
+   */
+  async getActivePage(threadId) {
+    try {
+      return await this.getPage(threadId);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Set up close event listener for a thread's browser manager.
+   * This handles the case where a thread's browser is closed externally.
+   */
+  setupCloseListenerForThread(manager, threadId) {
+    try {
+      let disconnectHandled = false;
+      const handleDisconnect = () => {
+        if (disconnectHandled) return;
+        disconnectHandled = true;
+        this.handleThreadBrowserDisconnected(threadId);
+      };
+      const context = manager.getContext();
+      if (context) {
+        context.on("close", handleDisconnect);
+      }
+      const pages = manager.getPages();
+      for (const page of pages) {
+        page.on("close", () => {
+          const remainingPages = manager.getPages();
+          if (remainingPages.length === 0) {
+            handleDisconnect();
+          }
+        });
+      }
+    } catch {
+    }
+  }
+  /**
+   * Create an error response from an exception.
+   * Extends base class to add agent-browser specific error handling.
+   */
+  createErrorFromException(error, context) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.includes("stale") || msg.includes("Stale")) {
+      return this.createError(
+        "stale_ref",
+        "Element ref is no longer valid.",
+        "Get a fresh snapshot and use updated refs."
+      );
+    }
+    if (msg.includes("not found") || msg.includes("No element")) {
+      return this.createError(
+        "element_not_found",
+        "Element not found.",
+        "Check the ref is correct or get a fresh snapshot."
+      );
+    }
+    return super.createErrorFromException(error, context);
+  }
+  async requireLocator(ref, threadId) {
+    const manager = await this.getManagerForThread(threadId);
+    return manager.getLocatorFromRef(ref);
+  }
+  async getScrollInfo(threadId) {
+    const page = await this.getPage(threadId);
+    const info = await page.evaluate(`({
+      scrollY: Math.round(window.scrollY),
+      scrollHeight: document.documentElement.scrollHeight,
+      viewportHeight: window.innerHeight
+    })`);
+    if (!info || typeof info.scrollHeight !== "number") {
+      return {
+        scrollY: 0,
+        scrollHeight: 0,
+        viewportHeight: 0,
+        atTop: true,
+        atBottom: true,
+        percentDown: 0
+      };
+    }
+    const maxScroll = info.scrollHeight - info.viewportHeight;
+    return {
+      ...info,
+      atTop: info.scrollY < 50,
+      atBottom: info.scrollY >= maxScroll - 50,
+      percentDown: maxScroll > 0 ? Math.round(info.scrollY / maxScroll * 100) : 0
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // URL Access
+  // ---------------------------------------------------------------------------
+  /**
+   * Get the current page URL without launching the browser.
+   * @param threadId - Optional thread ID for thread-isolated browsers
+   * @returns The current URL string, or null if browser is not running
+   */
+  async getCurrentUrl(threadId) {
+    if (!this.isBrowserRunning()) {
+      return null;
+    }
+    try {
+      const effectiveThreadId = threadId ?? this.getCurrentThread();
+      const scope = this.threadManager.getScope();
+      if (scope === "thread" && effectiveThreadId) {
+        const manager2 = this.threadManager.getExistingManagerForThread(effectiveThreadId);
+        if (!manager2) {
+          return null;
+        }
+        const url2 = manager2.getPage().url();
+        if (url2 && url2 !== "about:blank") {
+          const state = this.getBrowserStateForManager(manager2);
+          if (state) {
+            this.threadManager.updateBrowserState(effectiveThreadId, state);
+          }
+        }
+        return url2;
+      }
+      const manager = await this.getManagerForThread(threadId);
+      const url = manager.getPage().url();
+      if (url && url !== "about:blank") {
+        const state = this.getBrowserStateForManager(manager);
+        if (state) {
+          this.lastBrowserState = state;
+        }
+      }
+      return url;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Navigate to a URL (simple form). Used internally for restoring state on relaunch.
+   */
+  async navigateTo(url) {
+    if (!this.isBrowserRunning()) {
+      return;
+    }
+    try {
+      const page = await this.getPage();
+      await page.goto(url, {
+        timeout: this.defaultTimeout,
+        waitUntil: "domcontentloaded"
+      });
+    } catch {
+    }
+  }
+  /**
+   * Get the current browser state (all tabs and active tab index).
+   */
+  async getBrowserState(threadId) {
+    if (!this.isBrowserRunning()) {
+      return null;
+    }
+    try {
+      const manager = await this.getManagerForThread(threadId);
+      return this.getBrowserStateForManager(manager);
+    } 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() ?? browser.DEFAULT_THREAD_ID;
+    const manager = this.threadManager.getExistingManagerForThread(effectiveThreadId);
+    if (!manager) return null;
+    return this.getBrowserStateForManager(manager);
+  }
+  /**
+   * Get browser state from a specific manager instance.
+   */
+  getBrowserStateForManager(manager) {
+    try {
+      const pages = manager.getPages();
+      const activeIndex = manager.getActiveIndex();
+      const tabs = pages.map((page) => ({
+        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) {
+    if (!this.isBrowserRunning()) {
+      return 0;
+    }
+    try {
+      const manager = await this.getManagerForThread(threadId);
+      return manager.getActiveIndex();
+    } catch {
+      return 0;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 1. browser_goto - Navigate to URL
+  // ---------------------------------------------------------------------------
+  async goto(input, threadId) {
+    try {
+      const page = await this.getPage(threadId);
+      await page.goto(input.url, {
+        timeout: input.timeout ?? this.defaultTimeout,
+        waitUntil: input.waitUntil ?? "domcontentloaded"
+      });
+      return {
+        success: true,
+        url: page.url(),
+        title: await page.title(),
+        hint: "Take a snapshot to see interactive elements and get refs."
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Goto");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 2. browser_snapshot - Capture accessibility tree
+  // ---------------------------------------------------------------------------
+  async snapshot(input, threadId) {
+    try {
+      const manager = await this.getManagerForThread(threadId);
+      const page = await this.getPage(threadId);
+      const rawSnapshot = await manager.getSnapshot({
+        interactive: input.interactiveOnly ?? true,
+        compact: true
+      });
+      const snapshot = (rawSnapshot.tree ?? "").replace(/\[ref=(\w+)\]/g, "@$1");
+      const scrollInfo = await this.getScrollInfo(threadId);
+      let scrollText;
+      if (scrollInfo.atTop && !scrollInfo.atBottom) {
+        scrollText = "TOP - more content below";
+      } else if (scrollInfo.atBottom) {
+        scrollText = "BOTTOM of page";
+      } else {
+        scrollText = `${scrollInfo.percentDown}% down`;
+      }
+      const refs = snapshot.match(/@e\d+/g) || [];
+      const elementCount = new Set(refs).size;
+      return {
+        success: true,
+        snapshot,
+        url: page.url(),
+        title: await page.title(),
+        elementCount,
+        scroll: scrollText,
+        hint: elementCount === 0 ? "No interactive elements found. Try scrolling or setting interactiveOnly:false." : void 0
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Snapshot");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 3. browser_click - Click on element
+  // ---------------------------------------------------------------------------
+  async click(input, threadId) {
+    try {
+      const page = await this.getPage(threadId);
+      const locator = await this.requireLocator(input.ref, threadId);
+      if (!locator) {
+        return this.createError(
+          "stale_ref",
+          `Ref ${input.ref} not found. The page has changed.`,
+          "Take a new snapshot to see the current page state and get fresh refs."
+        );
+      }
+      await locator.click({
+        button: input.button ?? "left",
+        clickCount: input.clickCount ?? 1,
+        modifiers: input.modifiers,
+        timeout: this.defaultTimeout
+      });
+      return {
+        success: true,
+        url: page.url(),
+        hint: "Take a new snapshot to see updated page state and get fresh refs."
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      if (errorMsg.includes("intercepts pointer events")) {
+        return this.createError(
+          "element_blocked",
+          `Element ${input.ref} is blocked by another element.`,
+          "Take a new snapshot to see what is blocking. Dismiss any modals or scroll the element into view."
+        );
+      }
+      return this.createErrorFromException(error, "Click");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 4. browser_type - Type text into element
+  // ---------------------------------------------------------------------------
+  async type(input, threadId) {
+    try {
+      const page = await this.getPage(threadId);
+      const locator = await this.requireLocator(input.ref, threadId);
+      if (!locator) {
+        return this.createError(
+          "stale_ref",
+          `Ref ${input.ref} not found. The page has changed.`,
+          "Take a new snapshot to see the current page state and get fresh refs."
+        );
+      }
+      if (input.clear) {
+        await locator.fill("", { timeout: this.defaultTimeout });
+      }
+      if (input.delay) {
+        await locator.focus();
+        for (const char of input.text) {
+          await page.keyboard.press(char);
+          await new Promise((r) => setTimeout(r, input.delay));
+        }
+      } else {
+        await locator.fill(input.text, { timeout: this.defaultTimeout });
+      }
+      const value = await locator.inputValue({ timeout: 1e3 }).catch(() => input.text);
+      return {
+        success: true,
+        value,
+        url: page.url(),
+        hint: "Take a new snapshot if you need to interact with more elements."
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      if (errorMsg.includes("is not an <input>") || errorMsg.includes("not an input") || errorMsg.includes("Cannot type") || errorMsg.includes("not focusable")) {
+        return this.createError(
+          "not_focusable",
+          `Element ${input.ref} is not a text input field.`,
+          'Take a new snapshot and look for elements with role "textbox" or "searchbox".'
+        );
+      }
+      return this.createErrorFromException(error, "Type");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 5. browser_press - Press keyboard key(s)
+  // ---------------------------------------------------------------------------
+  async press(input, threadId) {
+    try {
+      const page = await this.getPage(threadId);
+      await page.keyboard.press(input.key);
+      return {
+        success: true,
+        url: page.url(),
+        hint: "Take a new snapshot if the page may have changed."
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Press");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 6. browser_select - Select dropdown option
+  // ---------------------------------------------------------------------------
+  async select(input, threadId) {
+    try {
+      const page = await this.getPage(threadId);
+      const locator = await this.requireLocator(input.ref, threadId);
+      if (!locator) {
+        return this.createError(
+          "stale_ref",
+          `Ref ${input.ref} not found. The page has changed.`,
+          "Take a new snapshot to get fresh refs."
+        );
+      }
+      const selectValue = {};
+      if (input.value) selectValue.value = input.value;
+      if (input.label) selectValue.label = input.label;
+      if (input.index !== void 0) selectValue.index = input.index;
+      const selected = await locator.selectOption(selectValue, {
+        timeout: this.defaultTimeout
+      });
+      return {
+        success: true,
+        selected,
+        url: page.url(),
+        hint: "Selection complete. Take a snapshot if you need to continue."
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Select");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 7. browser_scroll - Scroll page or element
+  // ---------------------------------------------------------------------------
+  async scroll(input, threadId) {
+    try {
+      const page = await this.getPage(threadId);
+      if (input.ref) {
+        const locator = await this.requireLocator(input.ref, threadId);
+        if (locator) {
+          await locator.scrollIntoViewIfNeeded({ timeout: this.defaultTimeout });
+        }
+      } else {
+        const direction = input.direction;
+        const amount = input.amount ?? 300;
+        let deltaX = 0;
+        let deltaY = 0;
+        switch (direction) {
+          case "up":
+            deltaY = -amount;
+            break;
+          case "down":
+            deltaY = amount;
+            break;
+          case "left":
+            deltaX = -amount;
+            break;
+          case "right":
+            deltaX = amount;
+            break;
+        }
+        await page.evaluate(
+          ({ x, y }) => {
+            globalThis.scrollBy(x, y);
+          },
+          { x: deltaX, y: deltaY }
+        );
+      }
+      const scrollInfo = await this.getScrollInfo(threadId);
+      let scrollText;
+      if (scrollInfo.atTop && !scrollInfo.atBottom) {
+        scrollText = "TOP - more content below";
+      } else if (scrollInfo.atBottom) {
+        scrollText = "BOTTOM of page";
+      } else {
+        scrollText = `${scrollInfo.percentDown}% down`;
+      }
+      return {
+        success: true,
+        position: { x: 0, y: scrollInfo.scrollY },
+        scroll: scrollText,
+        hint: "Take a new snapshot to see elements in the new viewport."
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Scroll");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 8. browser_hover - Hover over element
+  // ---------------------------------------------------------------------------
+  async hover(input, threadId) {
+    try {
+      const page = await this.getPage(threadId);
+      const locator = await this.requireLocator(input.ref, threadId);
+      if (!locator) {
+        return this.createError(
+          "stale_ref",
+          `Ref ${input.ref} not found. The page has changed.`,
+          "Take a new snapshot to get fresh refs."
+        );
+      }
+      await locator.hover({ timeout: this.defaultTimeout });
+      return {
+        success: true,
+        url: page.url(),
+        hint: "Take a new snapshot to see any hover-triggered elements (dropdowns, tooltips)."
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Hover");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 10. browser_back - Navigate back
+  // ---------------------------------------------------------------------------
+  async back(threadId) {
+    try {
+      const page = await this.getPage(threadId);
+      await page.goBack({ timeout: this.defaultTimeout });
+      return {
+        success: true,
+        url: page.url(),
+        title: await page.title(),
+        hint: "Take a new snapshot to see the previous page."
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Back");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 11. browser_dialog - Click element that triggers dialog and handle it
+  // ---------------------------------------------------------------------------
+  async dialog(input, threadId) {
+    try {
+      const page = await this.getPage(threadId);
+      const locator = await this.requireLocator(input.triggerRef, threadId);
+      if (!locator) {
+        return this.createError(
+          "stale_ref",
+          `Trigger ref ${input.triggerRef} not found.`,
+          "Take a new snapshot to get fresh refs."
+        );
+      }
+      return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          page.off("dialog", dialogHandler);
+          reject(
+            new Error(`No dialog appeared after clicking ${input.triggerRef}. The element may not trigger a dialog.`)
+          );
+        }, this.defaultTimeout);
+        const dialogHandler = async (dialog) => {
+          clearTimeout(timeout);
+          try {
+            const dialogType = dialog.type();
+            const message = dialog.message();
+            if (input.action === "accept") {
+              await dialog.accept(input.text);
+            } else {
+              await dialog.dismiss();
+            }
+            resolve({
+              success: true,
+              action: input.action,
+              dialogType,
+              message,
+              hint: "Dialog handled. Take a snapshot to continue."
+            });
+          } catch (e) {
+            reject(e);
+          }
+        };
+        page.once("dialog", dialogHandler);
+        locator.click({ timeout: this.defaultTimeout }).catch((e) => {
+          clearTimeout(timeout);
+          page.off("dialog", dialogHandler);
+          reject(e);
+        });
+      });
+    } catch (error) {
+      return this.createErrorFromException(error, "Dialog");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 13. browser_wait - Wait for element or condition
+  // ---------------------------------------------------------------------------
+  async wait(input, threadId) {
+    try {
+      const timeout = input.timeout ?? this.defaultTimeout;
+      if (input.ref) {
+        const locator = await this.requireLocator(input.ref, threadId);
+        if (!locator) {
+          return this.createError("stale_ref", `Ref ${input.ref} not found.`, "Take a new snapshot to get fresh refs.");
+        }
+        const state = input.state ?? "visible";
+        await locator.waitFor({ state, timeout });
+        return {
+          success: true,
+          hint: `Element is now ${state}. Take a snapshot to continue.`
+        };
+      } else {
+        const page = await this.getPage(threadId);
+        await page.waitForTimeout(timeout);
+        return {
+          success: true,
+          hint: "Wait complete. Take a snapshot to see current state."
+        };
+      }
+    } catch (error) {
+      return this.createErrorFromException(error, "Wait");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 14. browser_tabs - Manage browser tabs
+  // ---------------------------------------------------------------------------
+  async tabs(input, threadId) {
+    try {
+      const browser = await this.getManagerForThread(threadId);
+      if (!browser) {
+        return this.createError(
+          "browser_closed",
+          "Browser not launched",
+          "Call a navigation tool first to launch the browser."
+        );
+      }
+      switch (input.action) {
+        case "list": {
+          if (!browser.listTabs) {
+            return this.createError(
+              "browser_error",
+              "Tab management not supported",
+              "This browser provider does not support tab management."
+            );
+          }
+          const tabsList = await browser.listTabs();
+          return {
+            success: true,
+            tabs: tabsList,
+            hint: 'Use browser_tabs with action:"switch" and index to change tabs.'
+          };
+        }
+        case "new": {
+          if (!browser.newTab) {
+            return this.createError(
+              "browser_error",
+              "Tab management not supported",
+              "This browser provider does not support tab management."
+            );
+          }
+          const result = await browser.newTab();
+          if (input.url) {
+            const page = await this.getPage(threadId);
+            await page.goto(input.url);
+          }
+          this.updateSessionBrowserState(threadId);
+          return {
+            success: true,
+            ...result,
+            hint: "New tab opened. Take a snapshot to see its content."
+          };
+        }
+        case "switch": {
+          if (!browser.switchTo) {
+            return this.createError(
+              "browser_error",
+              "Tab management not supported",
+              "This browser provider does not support tab management."
+            );
+          }
+          await browser.switchTo(input.index);
+          await this.reconnectScreencastForThread(threadId, "tab switch");
+          const page = browser.getPage();
+          const pageUrl = page.url();
+          const streamKey = this.getStreamKey(threadId);
+          const stream = this.activeScreencastStreams.get(streamKey);
+          if (pageUrl && stream?.isActive()) {
+            stream.emitUrl(pageUrl);
+          }
+          this.updateSessionBrowserState(threadId);
+          return {
+            success: true,
+            index: input.index,
+            url: pageUrl,
+            title: await page.title(),
+            hint: "Tab switched. Take a snapshot to see its content."
+          };
+        }
+        case "close": {
+          if (!browser.closeTab) {
+            return this.createError(
+              "browser_error",
+              "Tab management not supported",
+              "This browser provider does not support tab management."
+            );
+          }
+          await browser.closeTab(input.index);
+          await this.reconnectScreencastForThread(threadId, "tab close");
+          this.updateSessionBrowserState(threadId);
+          const tabsList = await browser.listTabs?.() ?? [];
+          return {
+            success: true,
+            remaining: tabsList.length,
+            hint: tabsList.length > 0 ? "Tab closed. Take a snapshot 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");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 15. browser_drag - Drag element to target
+  // ---------------------------------------------------------------------------
+  async drag(input, threadId) {
+    try {
+      const page = await this.getPage(threadId);
+      let sourceLocator = null;
+      if (input.sourceRef) {
+        sourceLocator = await this.requireLocator(input.sourceRef, threadId);
+      } else if (input.sourceSelector) {
+        sourceLocator = page.locator(input.sourceSelector);
+      }
+      if (!sourceLocator) {
+        return this.createError(
+          "stale_ref",
+          input.sourceRef ? `Source ref ${input.sourceRef} not found.` : "No source element specified. Provide sourceRef or sourceSelector.",
+          input.sourceRef ? "Take a new snapshot to get fresh refs, or use sourceSelector for elements not in the accessibility tree." : void 0
+        );
+      }
+      let targetLocator = null;
+      if (input.targetRef) {
+        targetLocator = await this.requireLocator(input.targetRef, threadId);
+      } else if (input.targetSelector) {
+        targetLocator = page.locator(input.targetSelector);
+      }
+      if (!targetLocator) {
+        return this.createError(
+          "stale_ref",
+          input.targetRef ? `Target ref ${input.targetRef} not found.` : "No target element specified. Provide targetRef or targetSelector.",
+          input.targetRef ? "Take a new snapshot to get fresh refs, or use targetSelector for elements not in the accessibility tree." : void 0
+        );
+      }
+      await sourceLocator.dragTo(targetLocator, { timeout: this.defaultTimeout });
+      return {
+        success: true,
+        url: page.url(),
+        hint: "Drag complete. Take a snapshot to see the result."
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Drag");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 16. browser_evaluate - Execute JavaScript
+  // ---------------------------------------------------------------------------
+  async evaluate(input, threadId) {
+    try {
+      const page = await this.getPage(threadId);
+      const wrappedScript = `(async () => { ${input.script} })()`;
+      const result = await page.evaluate(wrappedScript);
+      return {
+        success: true,
+        result,
+        hint: "JavaScript executed. Take a snapshot if the page may have changed."
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Evaluate");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // 17. browser_close - Close browser
+  // ---------------------------------------------------------------------------
+  async closeBrowser() {
+    try {
+      await this.close();
+      return {
+        success: true,
+        hint: "Browser closed. Call browser_goto to start a new session."
+      };
+    } catch (error) {
+      return this.createErrorFromException(error, "Close");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Screencast (for Studio live view)
+  // ---------------------------------------------------------------------------
+  async startScreencast(_options) {
+    const requestedThreadId = _options?.threadId;
+    const effectiveThreadId = this.getScope() === "thread" ? requestedThreadId ?? this.getCurrentThread() ?? browser.DEFAULT_THREAD_ID : requestedThreadId;
+    let browserManager;
+    if (this.getScope() === "thread") {
+      browserManager = await this.getManagerForThread(effectiveThreadId);
+    } else {
+      if (!this.sharedManager) throw new Error("Browser not launched");
+      browserManager = this.sharedManager;
+    }
+    const provider = {
+      getCdpSession: async () => {
+        const currentPage = browserManager.getPage();
+        if (!currentPage) {
+          throw new Error("No active page available");
+        }
+        const cdpSession = await currentPage.context().newCDPSession(currentPage);
+        return cdpSession;
+      },
+      isBrowserRunning: () => browserManager.isLaunched()
+    };
+    const stream = new browser.ScreencastStreamImpl(provider, _options);
+    const streamKey = this.getStreamKey(effectiveThreadId);
+    this.activeScreencastStreams.set(streamKey, stream);
+    const context = browserManager.getContext();
+    if (context) {
+      const onNewPage = (_newPage) => {
+        setTimeout(() => {
+          if (stream.isActive()) {
+            stream.reconnect().catch(() => {
+            });
+          }
+        }, 100);
+      };
+      context.on("page", onNewPage);
+      const pageCloseHandlers = /* @__PURE__ */ new Map();
+      const frameNavigatedHandlers = /* @__PURE__ */ new Map();
+      const setupPageListeners = (page) => {
+        const onFrameNavigated = (frame) => {
+          if (!frame.parentFrame()) {
+            stream.emitUrl(frame.url());
+            this.updateSessionBrowserState(effectiveThreadId);
+          }
+        };
+        page.on("framenavigated", onFrameNavigated);
+        frameNavigatedHandlers.set(page, onFrameNavigated);
+        const onClose = () => {
+          pageCloseHandlers.delete(page);
+          const navHandler = frameNavigatedHandlers.get(page);
+          if (navHandler) {
+            page.off("framenavigated", navHandler);
+            frameNavigatedHandlers.delete(page);
+          }
+          setTimeout(() => {
+            const remainingPages = browserManager.getPages();
+            if (stream.isActive() && remainingPages.length > 0) {
+              stream.reconnect().catch(() => {
+              });
+              const activePage = remainingPages[browserManager.getActiveIndex()] || remainingPages[0];
+              if (activePage) {
+                const url = activePage.url();
+                if (url && url !== "about:blank") {
+                  stream.emitUrl(url);
+                }
+              }
+            }
+          }, 100);
+        };
+        page.once("close", onClose);
+        pageCloseHandlers.set(page, onClose);
+      };
+      const setupPageCloseListener = setupPageListeners;
+      for (const page of browserManager.getPages()) {
+        setupPageCloseListener(page);
+      }
+      const onNewPageWithCloseListener = (newPage) => {
+        setupPageCloseListener(newPage);
+        const url = newPage.url();
+        if (url && url !== "about:blank") {
+          stream.emitUrl(url);
+        }
+        onNewPage();
+      };
+      context.off("page", onNewPage);
+      context.on("page", onNewPageWithCloseListener);
+      stream.once("stop", () => {
+        context.off("page", onNewPageWithCloseListener);
+        for (const [page, handler] of pageCloseHandlers) {
+          page.off("close", handler);
+        }
+        pageCloseHandlers.clear();
+        for (const [page, handler] of frameNavigatedHandlers) {
+          page.off("framenavigated", handler);
+        }
+        frameNavigatedHandlers.clear();
+        this.activeScreencastStreams.delete(streamKey);
+      });
+    }
+    await stream.start();
+    return stream;
+  }
+  // ---------------------------------------------------------------------------
+  // Event Injection (for Studio live view interactivity)
+  // ---------------------------------------------------------------------------
+  async injectMouseEvent(event, threadId) {
+    const effectiveThreadId = threadId ?? this.getCurrentThread();
+    const manager = await this.getManagerForThread(effectiveThreadId);
+    await manager.injectMouseEvent(event);
+  }
+  async injectKeyboardEvent(event, threadId) {
+    const effectiveThreadId = threadId ?? this.getCurrentThread();
+    const manager = await this.getManagerForThread(effectiveThreadId);
+    const cdp = await manager.getCDPSession();
+    await cdp.send("Input.dispatchKeyEvent", {
+      type: event.type,
+      key: event.key,
+      code: event.code,
+      text: event.text,
+      modifiers: event.modifiers ?? 0,
+      windowsVirtualKeyCode: event.windowsVirtualKeyCode
+    });
+  }
+};
+
+exports.AgentBrowser = AgentBrowser;
+exports.BROWSER_TOOLS = BROWSER_TOOLS;
+exports.backInputSchema = backInputSchema;
+exports.browserSchemas = browserSchemas;
+exports.clickInputSchema = clickInputSchema;
+exports.closeInputSchema = closeInputSchema;
+exports.createAgentBrowserTools = createAgentBrowserTools;
+exports.dialogInputSchema = dialogInputSchema;
+exports.dragInputSchema = dragInputSchema;
+exports.evaluateInputSchema = evaluateInputSchema;
+exports.gotoInputSchema = gotoInputSchema;
+exports.hoverInputSchema = hoverInputSchema;
+exports.pressInputSchema = pressInputSchema;
+exports.scrollInputSchema = scrollInputSchema;
+exports.selectInputSchema = selectInputSchema;
+exports.snapshotInputSchema = snapshotInputSchema;
+exports.tabsInputSchema = tabsInputSchema;
+exports.typeInputSchema = typeInputSchema;
+exports.waitInputSchema = waitInputSchema;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map