@browserbasehq/orca 3.0.0-preview.1 → 3.0.0-preview.4

package/dist/index.d.ts

@@ -1,15 +1,166 @@
-import * as puppeteer_core from 'puppeteer-core';
-import * as patchright_core from 'patchright-core';
-import * as playwright_core from 'playwright-core';
-import Browserbase from '@browserbasehq/sdk';
-import { Protocol } from 'devtools-protocol';
-import { Buffer as Buffer$1 } from 'buffer';
+import { ZodType, z, ZodError, ZodTypeAny } from 'zod/v3';
 import { ClientOptions as ClientOptions$2 } from '@anthropic-ai/sdk';
+import { LanguageModelV2 } from '@ai-sdk/provider';
 import { ClientOptions as ClientOptions$1 } from 'openai';
-import { z, ZodType, ZodTypeAny, ZodError } from 'zod/v3';
-import { generateObject, generateText, streamText, streamObject, experimental_generateImage, embed, embedMany, experimental_transcribe, experimental_generateSpeech, LanguageModel, ToolSet } from 'ai';
-import { Client } from '@modelcontextprotocol/sdk/dist/esm/client';
-import { ClientOptions as ClientOptions$3, Client as Client$1 } from '@modelcontextprotocol/sdk/client/index.js';
+import { generateObject, generateText, streamText, streamObject, experimental_generateImage, embed, embedMany, experimental_transcribe, experimental_generateSpeech, ToolSet } from 'ai';
+import { Protocol } from 'devtools-protocol';
+import { Buffer as Buffer$1 } from 'buffer';
+import { Page as Page$1 } from 'playwright-core';
+export { Page as PlaywrightPage } from 'playwright-core';
+import { Page as Page$3 } from 'patchright-core';
+export { Page as PatchrightPage } from 'patchright-core';
+import { Page as Page$2 } from 'puppeteer-core';
+export { Page as PuppeteerPage } from 'puppeteer-core';
+import { Client, ClientOptions as ClientOptions$3 } from '@modelcontextprotocol/sdk/client/index.js';
+import Browserbase from '@browserbasehq/sdk';
+import { ToolSet as ToolSet$1 } from 'ai/dist';
+import { Schema } from '@google/genai';
+
+type AnthropicJsonSchemaObject = {
+    definitions?: {
+        MySchema?: {
+            properties?: Record<string, unknown>;
+            required?: string[];
+        };
+    };
+    properties?: Record<string, unknown>;
+    required?: string[];
+} & Record<string, unknown>;
+interface LLMTool {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+type AISDKProvider = (modelName: string) => LanguageModelV2;
+type AISDKCustomProvider = (options: {
+    apiKey: string;
+}) => AISDKProvider;
+type AvailableModel = "gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "o4-mini" | "o3" | "o3-mini" | "o1" | "o1-mini" | "gpt-4o" | "gpt-4o-mini" | "gpt-4o-2024-08-06" | "gpt-4.5-preview" | "o1-preview" | "claude-3-5-sonnet-latest" | "claude-3-5-sonnet-20241022" | "claude-3-5-sonnet-20240620" | "claude-3-7-sonnet-latest" | "claude-3-7-sonnet-20250219" | "cerebras-llama-3.3-70b" | "cerebras-llama-3.1-8b" | "groq-llama-3.3-70b-versatile" | "groq-llama-3.3-70b-specdec" | "gemini-1.5-flash" | "gemini-1.5-pro" | "gemini-1.5-flash-8b" | "gemini-2.0-flash-lite" | "gemini-2.0-flash" | "gemini-2.5-flash-preview-04-17" | "gemini-2.5-pro-preview-03-25" | string;
+type ModelProvider = "openai" | "anthropic" | "cerebras" | "groq" | "google" | "aisdk";
+type ClientOptions = ClientOptions$1 | ClientOptions$2;
+type ModelConfiguration = AvailableModel | (ClientOptions & {
+    modelName: AvailableModel;
+});
+
+type LogLevel = 0 | 1 | 2;
+/**
+ * Mapping between numeric log levels and their names
+ *
+ * 0 - error/warn - Critical issues or important warnings
+ * 1 - info - Standard information messages
+ * 2 - debug - Detailed information for debugging
+ */
+declare const LOG_LEVEL_NAMES: Record<LogLevel, string>;
+type LogLine = {
+    id?: string;
+    category?: string;
+    message: string;
+    level?: LogLevel;
+    timestamp?: string;
+    auxiliary?: {
+        [key: string]: {
+            value: string;
+            type: "object" | "string" | "html" | "integer" | "float" | "boolean";
+        };
+    };
+};
+type Logger = (logLine: LogLine) => void;
+
+interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: ChatMessageContent;
+}
+type ChatMessageContent = string | (ChatMessageImageContent | ChatMessageTextContent)[];
+interface ChatMessageImageContent {
+    type: string;
+    image_url?: {
+        url: string;
+    };
+    text?: string;
+    source?: {
+        type: string;
+        media_type: string;
+        data: string;
+    };
+}
+interface ChatMessageTextContent {
+    type: string;
+    text: string;
+}
+declare const AnnotatedScreenshotText = "This is a screenshot of the current page state with the elements annotated on it. Each element id is annotated with a number to the top left of it. Duplicate annotations at the same location are under each other vertically.";
+interface ChatCompletionOptions {
+    messages: ChatMessage[];
+    temperature?: number;
+    top_p?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    image?: {
+        buffer: Buffer;
+        description?: string;
+    };
+    response_model?: {
+        name: string;
+        schema: ZodType;
+    };
+    tools?: LLMTool[];
+    tool_choice?: "auto" | "none" | "required";
+    maxOutputTokens?: number;
+    requestId?: string;
+}
+type LLMResponse = {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: {
+        index: number;
+        message: {
+            role: string;
+            content: string | null;
+            tool_calls: {
+                id: string;
+                type: string;
+                function: {
+                    name: string;
+                    arguments: string;
+                };
+            }[];
+        };
+        finish_reason: string;
+    }[];
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+};
+interface CreateChatCompletionOptions {
+    options: ChatCompletionOptions;
+    logger: (message: LogLine) => void;
+    retries?: number;
+}
+declare abstract class LLMClient {
+    type: "openai" | "anthropic" | "cerebras" | "groq" | (string & {});
+    modelName: AvailableModel | (string & {});
+    hasVision: boolean;
+    clientOptions: ClientOptions;
+    userProvidedInstructions?: string;
+    constructor(modelName: AvailableModel, userProvidedInstructions?: string);
+    abstract createChatCompletion<T = LLMResponse & {
+        usage?: LLMResponse["usage"];
+    }>(options: CreateChatCompletionOptions): Promise<T>;
+    generateObject: typeof generateObject;
+    generateText: typeof generateText;
+    streamText: typeof streamText;
+    streamObject: typeof streamObject;
+    generateImage: typeof experimental_generateImage;
+    embed: typeof embed;
+    embedMany: typeof embedMany;
+    transcribe: typeof experimental_transcribe;
+    generateSpeech: typeof experimental_generateSpeech;
+    getLanguageModel?(): LanguageModelV2;
+}
 
 /**
  * CDP transport & session multiplexer
@@ -115,7 +266,7 @@ declare class Frame implements FrameManager {
             width: number;
             height: number;
         };
-    }): Promise<string>;
+    }): Promise<Buffer>;
     /** Child frames via Page.getFrameTree */
     childFrames(): Promise<Frame[]>;
     /** Wait for a lifecycle state (load/domcontentloaded/networkidle) */
@@ -153,10 +304,13 @@ declare class Locator {
     private readonly frame;
     private readonly selector;
     private readonly options?;
+    private readonly selectorResolver;
+    private readonly selectorQuery;
+    private readonly nthIndex;
     constructor(frame: Frame, selector: string, options?: {
         deep?: boolean;
         depth?: number;
-    });
+    }, nthIndex?: number);
     /** Return the owning Frame for this locator (typed accessor, no private access). */
     getFrame(): Frame;
     /**
@@ -182,6 +336,8 @@ declare class Locator {
      * Useful for identity comparisons without needing element handles.
      */
     backendNodeId(): Promise<Protocol.DOM.BackendNodeId>;
+    /** Return how many nodes the current selector resolves to. */
+    count(): Promise<number>;
     /**
      * Return the center of the element's bounding box in the owning frame's viewport
      * (CSS pixels), rounded to integers. Scrolls into view best-effort.
@@ -210,6 +366,11 @@ declare class Locator {
             a?: number;
         };
     }): Promise<void>;
+    /**
+     * Move the mouse cursor to the element's visual center without clicking.
+     * - Scrolls into view best-effort, resolves geometry, then dispatches a mouse move.
+     */
+    hover(): Promise<void>;
     /**
      * Click the element at its visual center.
      * Steps:
@@ -241,9 +402,9 @@ declare class Locator {
     scrollTo(percent: number | string): Promise<void>;
     /**
      * Fill an input/textarea/contenteditable element.
-     * - Sets the value/text directly in DOM.
-     * - Dispatches `input` and `change` events to mimic user input.
-     * - Releases the underlying `objectId` afterwards to avoid leaks.
+     * Mirrors Playwright semantics: the DOM helper either applies the native
+     * value setter (for special input types) or asks us to type text via the CDP
+     * Input domain after focusing/selecting.
      */
     fill(value: string): Promise<void>;
     /**
@@ -289,35 +450,16 @@ declare class Locator {
      * For API parity, returns the same locator (querySelector already returns the first match).
      */
     first(): Locator;
+    /** Return a locator narrowed to the element at the given zero-based index. */
+    nth(index: number): Locator;
     /**
      * Resolve `this.selector` within the frame to `{ objectId, nodeId? }`:
-     * - Ensures Runtime/DOM are enabled.
-     * - Creates (or reuses) an isolated world for this frame.
-     * - Evaluates a CSS or XPath query in that isolated world.
-     * - Best-effort: attempts to convert `objectId` to `nodeId`; failure is non-fatal.
-     *
-     * - For XPath: first try page-side resolver (__stagehandV3__.resolveSimpleXPath).
-     *   If it returns null (e.g. closed DSD not captured), fall back to CDP DOM with
-     *   `pierce: true` to traverse closed shadow roots and resolve by backendNodeId.
+     * Delegates to a shared selector resolver so all selector logic stays in sync.
      */
     resolveNode(): Promise<{
         nodeId: Protocol.DOM.NodeId | null;
         objectId: Protocol.Runtime.RemoteObjectId;
     }>;
-    /**
-     * CDP fallback for XPath resolution that needs to cross *closed* shadow roots
-     * created via Declarative Shadow DOM (no attachShadow call to intercept).
-     *
-     * Strategy:
-     *   - Fetch full DOM with `pierce: true` so closed shadow roots are included.
-     *   - Run a small, tolerant XPath stepper over the CDP node tree:
-     *       • supports absolute paths like `/html/body/...`
-     *       • supports `//` descendant jumps
-     *       • supports `tag[n]` numeric predicates per sibling group
-     *       • supports `*`
-     *   - Resolve the winning backendNodeId to an objectId for downstream actions.
-     */
-    private resolveViaDomPierceXPath;
     /** Compute a center point from a BoxModel content quad */
     private centerFromBoxContent;
 }
@@ -333,12 +475,15 @@ declare class DeepLocatorDelegate {
     private readonly page;
     private readonly root;
     private readonly selector;
-    constructor(page: Page, root: Frame, selector: string);
+    private readonly nthIndex;
+    constructor(page: Page, root: Frame, selector: string, nthIndex?: number);
     private real;
     click(options?: {
         button?: "left" | "right" | "middle";
         clickCount?: number;
     }): Promise<void>;
+    count(): Promise<number>;
+    hover(): Promise<void>;
     fill(value: string): Promise<void>;
     type(text: string, options?: {
         delay?: number;
@@ -377,7 +522,8 @@ declare class DeepLocatorDelegate {
         composed?: boolean;
         detail?: number;
     }): Promise<void>;
-    first(): this;
+    first(): DeepLocatorDelegate;
+    nth(index: number): DeepLocatorDelegate;
 }
 
 /**
@@ -407,6 +553,7 @@ declare class LocatorDelegate {
         button?: "left" | "right" | "middle";
         clickCount?: number;
     }): Promise<void>;
+    hover(): Promise<void>;
     fill(value: string): Promise<void>;
     type(text: string, options?: {
         delay?: number;
@@ -419,9 +566,13 @@ declare class LocatorDelegate {
     textContent(): Promise<string>;
     innerHtml(): Promise<string>;
     innerText(): Promise<string>;
+    count(): Promise<number>;
     first(): LocatorDelegate;
 }
 
+type AnyPage = Page$1 | Page$2 | Page$3 | Page;
+type LoadState = "load" | "domcontentloaded" | "networkidle";
+
 declare class Page {
     private readonly conn;
     private readonly mainSession;
@@ -439,6 +590,9 @@ declare class Page {
     private readonly frameCache;
     /** Stable id for Frames created by this Page (use top-level TargetId). */
     private readonly pageId;
+    /** Cached current URL for synchronous page.url() */
+    private _currentUrl;
+    private readonly networkManager;
     private constructor();
     private cursorEnabled;
     private ensureCursorScript;
@@ -463,6 +617,7 @@ declare class Page {
      * Topology + ownership update. Handles root swaps.
      */
     onFrameNavigated(frame: Protocol.Page.Frame, session: CDPSessionLike): void;
+    onNavigatedWithinDocument(frameId: string, url: string, session: CDPSessionLike): void;
     /**
      * An OOPIF child session whose **main** frame id equals the parent iframe’s frameId
      * has been attached; adopt the session into this Page and seed ownership for its subtree.
@@ -476,7 +631,11 @@ declare class Page {
     frameForId(frameId: string): Frame;
     /** Expose a session by id (used by snapshot to resolve session id -> session) */
     getSessionById(id: string): CDPSessionLike | undefined;
+    registerSessionForNetwork(session: CDPSessionLike): void;
+    unregisterSessionForNetwork(sessionId: string | undefined): void;
     targetId(): string;
+    /** Seed the cached URL before navigation events converge. */
+    seedCurrentUrl(url: string | undefined | null): void;
     mainFrameId(): string;
     mainFrame(): Frame;
     /**
@@ -520,9 +679,9 @@ declare class Page {
         timeoutMs?: number;
     }): Promise<void>;
     /**
-     * Return the current page URL (from navigation history).
+     * Return the current page URL (synchronous, cached from navigation events).
      */
-    url(): Promise<string>;
+    url(): string;
     /**
      * Return the current page title.
      * Prefers reading from the active document via Runtime.evaluate to reflect dynamic changes.
@@ -534,7 +693,7 @@ declare class Page {
      */
     screenshot(options?: {
         fullPage?: boolean;
-    }): Promise<string>;
+    }): Promise<Buffer>;
     /**
      * Create a locator bound to the current main frame.
      */
@@ -639,12 +798,35 @@ declare class Page {
         withMistakes?: boolean;
     }): Promise<void>;
     /**
-     * Press a single key (keyDown then keyUp). For printable characters,
-     * uses the text path on keyDown; for named keys, sets key/code/VK.
+     * Press a single key or key combination (keyDown then keyUp).
+     * For printable characters, uses the text path on keyDown; for named keys, sets key/code/VK.
+     * Supports key combinations with modifiers like "Cmd+A", "Ctrl+C", "Shift+Tab", etc.
      */
     keyPress(key: string, options?: {
         delay?: number;
     }): Promise<void>;
+    private _pressedModifiers;
+    /** Press a key down without releasing it */
+    private keyDown;
+    /** Release a pressed key */
+    private keyUp;
+    /** Normalize modifier key names to match CDP expectations */
+    private normalizeModifierKey;
+    /**
+     * Get the map of named keys with their properties
+     */
+    private getNamedKeys;
+    /**
+     * Minimal description for printable keys (letters/digits/space) to provide code and VK.
+     * Used when non-Shift modifiers are pressed to avoid sending text while keeping accelerator info.
+     */
+    private describePrintableKey;
+    private isMacOS;
+    /**
+     * Return Chromium mac editing commands (without trailing ':') for a given code like 'KeyA'
+     * Only used on macOS to trigger system editing shortcuts (e.g., selectAll, copy, paste...).
+     */
+    private macCommandsFor;
     /**
      * Create an isolated world for the **current** main frame and return its context id.
      */
@@ -655,151 +837,315 @@ declare class Page {
      * - Event path listens at the session level and compares incoming `frameId`
      *   to `mainFrameId()` **at event time** to follow root swaps.
      */
-    private waitForMainLoadState;
-}
-
-declare const AvailableModelSchema: z.ZodEnum<["gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "o4-mini", "o3", "o3-mini", "o1", "o1-mini", "gpt-4o", "gpt-4o-mini", "gpt-4o-2024-08-06", "gpt-4.5-preview", "o1-preview", "claude-3-5-sonnet-latest", "claude-3-5-sonnet-20241022", "claude-3-5-sonnet-20240620", "claude-3-7-sonnet-latest", "claude-3-7-sonnet-20250219", "cerebras-llama-3.3-70b", "cerebras-llama-3.1-8b", "groq-llama-3.3-70b-versatile", "groq-llama-3.3-70b-specdec", "gemini-1.5-flash", "gemini-1.5-pro", "gemini-1.5-flash-8b", "gemini-2.0-flash-lite", "gemini-2.0-flash", "gemini-2.5-flash-preview-04-17", "gemini-2.5-pro-preview-03-25"]>;
-type AvailableModel = z.infer<typeof AvailableModelSchema> | string;
-type ModelProvider = "openai" | "anthropic" | "cerebras" | "groq" | "google" | "aisdk";
-type ClientOptions = ClientOptions$1 | ClientOptions$2;
-type ModelConfiguration = AvailableModel | (ClientOptions & {
-    modelName: AvailableModel;
-});
-interface AnthropicJsonSchemaObject {
-    definitions?: {
-        MySchema?: {
-            properties?: Record<string, unknown>;
-            required?: string[];
-        };
-    };
-    properties?: Record<string, unknown>;
-    required?: string[];
-}
-
-interface LLMTool {
-    type: "function";
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
+    waitForMainLoadState(state: LoadState, timeoutMs?: number): Promise<void>;
 }
 
-type LogLevel = 0 | 1 | 2;
 /**
- * Mapping between numeric log levels and their names
+ * Represents a path through a Zod schema from the root object down to a
+ * particular field. The `segments` array describes the chain of keys/indices.
  *
- * 0 - error/warn - Critical issues or important warnings
- * 1 - info - Standard information messages
- * 2 - debug - Detailed information for debugging
+ * - **String** segments indicate object property names.
+ * - **Number** segments indicate array indices.
+ *
+ * For example, `["users", 0, "homepage"]` might describe reaching
+ * the `homepage` field in `schema.users[0].homepage`.
  */
-declare const LOG_LEVEL_NAMES: Record<LogLevel, string>;
-type LogLine = {
-    id?: string;
-    category?: string;
-    message: string;
-    level?: LogLevel;
-    timestamp?: string;
-    auxiliary?: {
-        [key: string]: {
-            value: string;
-            type: "object" | "string" | "html" | "integer" | "float" | "boolean";
-        };
-    };
-};
-type Logger = (logLine: LogLine) => void;
-
-interface ChatMessage {
-    role: "system" | "user" | "assistant";
-    content: ChatMessageContent;
+interface ZodPathSegments {
+    /**
+     * The ordered list of keys/indices leading from the schema root
+     * to the targeted field.
+     */
+    segments: Array<string | number>;
 }
-type ChatMessageContent = string | (ChatMessageImageContent | ChatMessageTextContent)[];
-interface ChatMessageImageContent {
-    type: string;
-    image_url?: {
-        url: string;
-    };
-    text?: string;
-    source?: {
-        type: string;
-        media_type: string;
-        data: string;
-    };
+
+type EvaluateOptions = {
+    /** The question to ask about the task state */
+    question: string;
+    /** The answer to the question */
+    answer?: string;
+    /** Whether to take a screenshot of the task state, or array of screenshots to evaluate */
+    screenshot?: boolean | Buffer[];
+    /** Custom system prompt for the evaluator */
+    systemPrompt?: string;
+    /** Delay in milliseconds before taking the screenshot @default 250 */
+    screenshotDelayMs?: number;
+    /** The agent's reasoning/thought process for completing the task */
+    agentReasoning?: string;
+};
+type BatchAskOptions = {
+    /** Array of questions with optional answers */
+    questions: Array<{
+        question: string;
+        answer?: string;
+    }>;
+    /** Whether to take a screenshot of the task state */
+    screenshot?: boolean;
+    /** Custom system prompt for the evaluator */
+    systemPrompt?: string;
+    /** Delay in milliseconds before taking the screenshot @default 1000 */
+    screenshotDelayMs?: number;
+};
+/**
+ * Result of an evaluation
+ */
+interface EvaluationResult {
+    /**
+     * The evaluation result ('YES', 'NO', or 'INVALID' if parsing failed or value was unexpected)
+     */
+    evaluation: "YES" | "NO" | "INVALID";
+    /**
+     * The reasoning behind the evaluation
+     */
+    reasoning: string;
 }
-interface ChatMessageTextContent {
+
+interface AgentAction {
     type: string;
-    text: string;
+    reasoning?: string;
+    taskCompleted?: boolean;
+    action?: string;
+    timeMs?: number;
+    pageText?: string;
+    pageUrl?: string;
+    instruction?: string;
+    [key: string]: unknown;
 }
-declare const AnnotatedScreenshotText = "This is a screenshot of the current page state with the elements annotated on it. Each element id is annotated with a number to the top left of it. Duplicate annotations at the same location are under each other vertically.";
-interface ChatCompletionOptions {
-    messages: ChatMessage[];
-    temperature?: number;
-    top_p?: number;
-    frequency_penalty?: number;
-    presence_penalty?: number;
-    image?: {
-        buffer: Buffer;
-        description?: string;
-    };
-    response_model?: {
-        name: string;
-        schema: ZodType;
+interface AgentResult {
+    success: boolean;
+    message: string;
+    actions: AgentAction[];
+    completed: boolean;
+    metadata?: Record<string, unknown>;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+        inference_time_ms: number;
     };
-    tools?: LLMTool[];
-    tool_choice?: "auto" | "none" | "required";
-    maxTokens?: number;
-    requestId?: string;
 }
-type LLMResponse = {
-    id: string;
-    object: string;
-    created: number;
-    model: string;
-    choices: {
-        index: number;
-        message: {
-            role: string;
-            content: string | null;
-            tool_calls: {
-                id: string;
-                type: string;
-                function: {
-                    name: string;
-                    arguments: string;
-                };
-            }[];
-        };
-        finish_reason: string;
-    }[];
-    usage: {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-    };
-};
-interface CreateChatCompletionOptions {
-    options: ChatCompletionOptions;
+interface AgentExecuteOptions {
+    instruction: string;
+    maxSteps?: number;
+    page?: Page$1 | Page$2 | Page$3 | Page;
+    highlightCursor?: boolean;
+}
+type AgentType = "openai" | "anthropic" | "google";
+declare const AVAILABLE_CUA_MODELS: readonly ["openai/computer-use-preview", "openai/computer-use-preview-2025-03-11", "anthropic/claude-3-7-sonnet-latest", "anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-20250514", "anthropic/claude-sonnet-4-5-20250929", "google/gemini-2.5-computer-use-preview-10-2025"];
+type AvailableCuaModel = (typeof AVAILABLE_CUA_MODELS)[number];
+interface AgentExecutionOptions<TOptions extends AgentExecuteOptions = AgentExecuteOptions> {
+    options: TOptions;
     logger: (message: LogLine) => void;
     retries?: number;
 }
-declare abstract class LLMClient {
-    type: "openai" | "anthropic" | "cerebras" | "groq" | (string & {});
-    modelName: AvailableModel | (string & {});
-    hasVision: boolean;
-    clientOptions: ClientOptions;
+interface AgentHandlerOptions {
+    modelName: string;
+    clientOptions?: Record<string, unknown>;
     userProvidedInstructions?: string;
-    constructor(modelName: AvailableModel, userProvidedInstructions?: string);
-    abstract createChatCompletion<T = LLMResponse & {
-        usage?: LLMResponse["usage"];
-    }>(options: CreateChatCompletionOptions): Promise<T>;
-    generateObject: typeof generateObject;
-    generateText: typeof generateText;
-    streamText: typeof streamText;
-    streamObject: typeof streamObject;
-    generateImage: typeof experimental_generateImage;
-    embed: typeof embed;
-    embedMany: typeof embedMany;
-    transcribe: typeof experimental_transcribe;
-    generateSpeech: typeof experimental_generateSpeech;
-    getLanguageModel?(): LanguageModel;
+    experimental?: boolean;
+}
+interface ActionExecutionResult {
+    success: boolean;
+    error?: string;
+    data?: unknown;
+}
+interface ToolUseItem extends ResponseItem {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface AnthropicMessage {
+    role: string;
+    content: string | Array<AnthropicContentBlock>;
+}
+interface AnthropicContentBlock {
+    type: string;
+    [key: string]: unknown;
+}
+interface AnthropicTextBlock extends AnthropicContentBlock {
+    type: "text";
+    text: string;
+}
+interface AnthropicToolResult {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string | Array<AnthropicContentBlock>;
+}
+interface ResponseItem {
+    type: string;
+    id: string;
+    [key: string]: unknown;
+}
+interface ComputerCallItem extends ResponseItem {
+    type: "computer_call";
+    call_id: string;
+    action: {
+        type: string;
+        [key: string]: unknown;
+    };
+    pending_safety_checks?: Array<{
+        id: string;
+        code: string;
+        message: string;
+    }>;
+}
+interface FunctionCallItem extends ResponseItem {
+    type: "function_call";
+    call_id: string;
+    name: string;
+    arguments: string;
+}
+type ResponseInputItem = {
+    role: string;
+    content: string;
+} | {
+    type: "computer_call_output";
+    call_id: string;
+    output: {
+        type: "input_image";
+        image_url: string;
+        current_url?: string;
+        error?: string;
+        [key: string]: unknown;
+    } | string;
+    acknowledged_safety_checks?: Array<{
+        id: string;
+        code: string;
+        message: string;
+    }>;
+} | {
+    type: "function_call_output";
+    call_id: string;
+    output: string;
+};
+interface AgentInstance {
+    execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
+}
+type AgentProviderType = AgentType;
+type AgentModelConfig<TModelName extends string = string> = {
+    modelName: TModelName;
+} & Record<string, unknown>;
+type AgentConfig = {
+    /**
+     * Custom system prompt to provide to the agent. Overrides the default system prompt.
+     */
+    systemPrompt?: string;
+    /**
+     * MCP integrations - Array of Client objects
+     */
+    integrations?: (Client | string)[];
+    /**
+     * Tools passed to the agent client
+     */
+    tools?: ToolSet;
+    /**
+     * Indicates CUA is disabled for this configuration
+     */
+    cua?: boolean;
+    /**
+     * The model to use for agent functionality
+     */
+    model?: string | AgentModelConfig<string>;
+    /**
+     * The model to use for tool execution (observe/act calls within agent tools).
+     * If not specified, inherits from the main model configuration.
+     * Format: "provider/model" (e.g., "openai/gpt-4o-mini", "google/gemini-2.0-flash-exp")
+     */
+    executionModel?: string | AgentModelConfig<string>;
+};
+
+declare class StagehandAPIError extends Error {
+    constructor(message: string);
+}
+declare class StagehandAPIUnauthorizedError extends StagehandAPIError {
+    constructor(message?: string);
+}
+declare class StagehandHttpError extends StagehandAPIError {
+    constructor(message: string);
+}
+declare class StagehandServerError extends StagehandAPIError {
+    constructor(message: string);
+}
+declare class StagehandResponseBodyError extends StagehandAPIError {
+    constructor();
+}
+declare class StagehandResponseParseError extends StagehandAPIError {
+    constructor(message: string);
+}
+
+interface ActOptions {
+    model?: ModelConfiguration;
+    variables?: Record<string, string>;
+    timeout?: number;
+    page?: Page$1 | Page$2 | Page$3 | Page;
+}
+interface ActResult {
+    success: boolean;
+    message: string;
+    actionDescription: string;
+    actions: Action[];
+}
+type ExtractResult<T extends z.AnyZodObject> = z.infer<T>;
+interface Action {
+    selector: string;
+    description: string;
+    method?: string;
+    arguments?: string[];
+}
+interface HistoryEntry {
+    method: "act" | "extract" | "observe" | "navigate";
+    parameters: unknown;
+    result: unknown;
+    timestamp: string;
+}
+interface ExtractOptions {
+    model?: ModelConfiguration;
+    timeout?: number;
+    selector?: string;
+    page?: Page$1 | Page$2 | Page$3 | Page;
+}
+declare const defaultExtractSchema: z.ZodObject<{
+    extraction: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    extraction?: string;
+}, {
+    extraction?: string;
+}>;
+declare const pageTextSchema: z.ZodObject<{
+    pageText: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    pageText?: string;
+}, {
+    pageText?: string;
+}>;
+interface ObserveOptions {
+    model?: ModelConfiguration;
+    timeout?: number;
+    selector?: string;
+    page?: Page$1 | Page$2 | Page$3 | Page;
+}
+declare enum V3FunctionName {
+    ACT = "ACT",
+    EXTRACT = "EXTRACT",
+    OBSERVE = "OBSERVE",
+    AGENT = "AGENT"
+}
+
+interface V3Metrics {
+    actPromptTokens: number;
+    actCompletionTokens: number;
+    actInferenceTimeMs: number;
+    extractPromptTokens: number;
+    extractCompletionTokens: number;
+    extractInferenceTimeMs: number;
+    observePromptTokens: number;
+    observeCompletionTokens: number;
+    observeInferenceTimeMs: number;
+    agentPromptTokens: number;
+    agentCompletionTokens: number;
+    agentInferenceTimeMs: number;
+    totalPromptTokens: number;
+    totalCompletionTokens: number;
+    totalInferenceTimeMs: number;
 }
 
 type V3Env = "LOCAL" | "BROWSERBASE";
@@ -858,70 +1204,113 @@ interface V3Options {
     disablePino?: boolean;
     /** Optional external logger hook for integrating with host apps. */
     logger?: (line: LogLine) => void;
-    /** Show a visual cursor overlay that follows our mouse events. */
-    includeCursor?: boolean;
     /** Directory used to persist cached actions for act(). */
     cacheDir?: string;
     domSettleTimeout?: number;
 }
-type PlaywrightPage = playwright_core.Page;
-type PatchrightPage = patchright_core.Page;
-type PuppeteerPage = puppeteer_core.Page;
-interface ActOptions$1 {
-    model?: ModelConfiguration;
-    variables?: Record<string, string>;
-    timeout?: number;
-    page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+
+declare class StagehandError extends Error {
+    constructor(message: string);
 }
-interface ExtractOptions$1 {
-    model?: ModelConfiguration;
-    timeout?: number;
-    selector?: string;
-    page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+declare class StagehandDefaultError extends StagehandError {
+    constructor(error?: unknown);
 }
-declare const defaultExtractSchema: z.ZodObject<{
-    extraction: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    extraction?: string;
-}, {
-    extraction?: string;
-}>;
-declare const pageTextSchema: z.ZodObject<{
-    pageText: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    pageText?: string;
-}, {
-    pageText?: string;
-}>;
-interface ObserveOptions$1 {
-    model?: ModelConfiguration;
-    timeout?: number;
-    selector?: string;
-    page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+declare class StagehandEnvironmentError extends StagehandError {
+    constructor(currentEnvironment: string, requiredEnvironment: string, feature: string);
+}
+declare class MissingEnvironmentVariableError extends StagehandError {
+    constructor(missingEnvironmentVariable: string, feature: string);
+}
+declare class UnsupportedModelError extends StagehandError {
+    constructor(supportedModels: string[], feature?: string);
+}
+declare class UnsupportedModelProviderError extends StagehandError {
+    constructor(supportedProviders: string[], feature?: string);
+}
+declare class UnsupportedAISDKModelProviderError extends StagehandError {
+    constructor(provider: string, supportedProviders: string[]);
+}
+declare class InvalidAISDKModelFormatError extends StagehandError {
+    constructor(modelName: string);
+}
+declare class StagehandNotInitializedError extends StagehandError {
+    constructor(prop: string);
+}
+declare class BrowserbaseSessionNotFoundError extends StagehandError {
+    constructor();
+}
+declare class CaptchaTimeoutError extends StagehandError {
+    constructor();
+}
+declare class MissingLLMConfigurationError extends StagehandError {
+    constructor();
+}
+declare class HandlerNotInitializedError extends StagehandError {
+    constructor(handlerType: string);
+}
+declare class StagehandInvalidArgumentError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandElementNotFoundError extends StagehandError {
+    constructor(xpaths: string[]);
+}
+declare class AgentScreenshotProviderError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandMissingArgumentError extends StagehandError {
+    constructor(message: string);
+}
+declare class CreateChatCompletionResponseError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandEvalError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandDomProcessError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandClickError extends StagehandError {
+    constructor(message: string, selector: string);
+}
+declare class LLMResponseError extends StagehandError {
+    constructor(primitive: string, message: string);
+}
+declare class StagehandIframeError extends StagehandError {
+    constructor(frameUrl: string, message: string);
+}
+declare class ContentFrameNotFoundError extends StagehandError {
+    constructor(selector: string);
+}
+declare class XPathResolutionError extends StagehandError {
+    constructor(xpath: string);
+}
+declare class ExperimentalApiConflictError extends StagehandError {
+    constructor();
+}
+declare class ExperimentalNotConfiguredError extends StagehandError {
+    constructor(featureName: string);
 }
-type LoadState = "load" | "domcontentloaded" | "networkidle";
-interface V3Metrics {
-    actPromptTokens: number;
-    actCompletionTokens: number;
-    actInferenceTimeMs: number;
-    extractPromptTokens: number;
-    extractCompletionTokens: number;
-    extractInferenceTimeMs: number;
-    observePromptTokens: number;
-    observeCompletionTokens: number;
-    observeInferenceTimeMs: number;
-    agentPromptTokens: number;
-    agentCompletionTokens: number;
-    agentInferenceTimeMs: number;
-    totalPromptTokens: number;
-    totalCompletionTokens: number;
-    totalInferenceTimeMs: number;
+declare class ZodSchemaValidationError extends Error {
+    readonly received: unknown;
+    readonly issues: ReturnType<ZodError["format"]>;
+    constructor(received: unknown, issues: ReturnType<ZodError["format"]>);
 }
-declare enum V3FunctionName {
-    ACT = "ACT",
-    EXTRACT = "EXTRACT",
-    OBSERVE = "OBSERVE",
-    AGENT = "AGENT"
+declare class StagehandInitError extends StagehandError {
+    constructor(message: string);
+}
+declare class MCPConnectionError extends StagehandError {
+    readonly serverUrl: string;
+    readonly originalError: unknown;
+    constructor(serverUrl: string, originalError: unknown);
+}
+declare class StagehandShadowRootMissingError extends StagehandError {
+    constructor(detail?: string);
+}
+declare class StagehandShadowSegmentEmptyError extends StagehandError {
+    constructor();
+}
+declare class StagehandShadowSegmentNotFoundError extends StagehandError {
+    constructor(segment: string, hint?: string);
 }
 
 /**
@@ -937,7 +1326,6 @@ declare enum V3FunctionName {
  */
 declare class V3Context {
     readonly conn: CdpConnection;
-    private readonly includeCursor;
     private readonly env;
     private constructor();
     private readonly _piercerInstalled;
@@ -952,335 +1340,96 @@ declare class V3Context {
     private createdAtByTarget;
     private typeByTarget;
     private _pageOrder;
+    private pendingCreatedTargetUrl;
     /**
      * Create a Context for a given CDP websocket URL and bootstrap target wiring.
      */
     static create(wsUrl: string, opts?: {
-        includeCursor?: boolean;
         env?: "LOCAL" | "BROWSERBASE";
     }): Promise<V3Context>;
     /**
-     * Wait until at least one top-level Page has been created and registered.
-     * We poll internal maps that bootstrap/onAttachedToTarget populate.
-     */
-    private waitForFirstTopLevelPage;
-    private ensurePiercer;
-    /** Mark a page target as the most-recent one (active). */
-    private _pushActive;
-    /** Remove a page target from the recency list (used on close). */
-    private _removeFromOrder;
-    /** Return the current active Page (most-recent page that still exists). */
-    activePage(): Page | undefined;
-    /**
-     * Return top-level `Page`s (oldest → newest). OOPIF targets are not included.
-     */
-    pages(): Page[];
-    /**
-     * Resolve an owning `Page` by the **top-level main frame id**.
-     * Note: child (OOPIF) roots are intentionally not present in this mapping.
-     */
-    resolvePageByMainFrameId(frameId: string): Page | undefined;
-    /**
-     * Serialize the full frame tree for a given top-level main frame id.
-     */
-    getFullFrameTreeByMainFrameId(rootMainFrameId: string): Promise<Protocol.Page.FrameTree>;
-    /**
-     * Create a new top-level page (tab) with the given URL and return its Page object.
-     * Waits until the target is attached and registered.
-     */
-    newPage(url?: string): Promise<Page>;
-    /**
-     * Close CDP and clear all mappings. Best-effort cleanup.
-     */
-    close(): Promise<void>;
-    /**
-     * Bootstrap target lifecycle:
-     * - Attach to existing targets.
-     * - Attach on `Target.targetCreated` (fallback for OOPIFs).
-     * - Handle auto-attach events.
-     * - Clean up on detach/destroy.
-     */
-    private bootstrap;
-    /**
-     * Handle a newly attached target (top-level or potential OOPIF):
-     * - Enable Page domain and lifecycle events.
-     * - If top-level → create Page, wire listeners, resume.
-     * - Else → probe child root frame id via `Page.getFrameTree` and adopt immediately
-     *   if the parent is known; otherwise stage until parent `frameAttached`.
-     * - Resume the target only after listeners are wired.
-     */
-    private onAttachedToTarget;
-    /**
-     * Detach handler:
-     * - Remove child session ownership and prune its subtree.
-     * - If a top-level target, cleanup its `Page` and mappings.
-     * - Drop any staged child for this session.
-     */
-    private onDetachedFromTarget;
-    /**
-     * Cleanup a top-level Page by target id, removing its root and staged children.
-     */
-    private cleanupByTarget;
-    /**
-     * Wire Page-domain frame events for a session into the owning Page & mappings.
-     * We forward the *emitting session* with every event so Page can stamp ownership precisely.
-     */
-    private installFrameEventBridges;
-    /**
-     * Register that a session belongs to a Page (used by event routing).
-     */
-    private wireSessionToOwnerPage;
-    /**
-     * Utility: reverse-lookup the top-level target id that owns a given Page.
-     */
-    private findTargetIdByPage;
-    private _notePopupSignal;
-    /**
-     * Await the current active page, waiting briefly if a popup/open was just triggered.
-     * Normal path returns immediately; popup path waits up to timeoutMs for the new page.
-     */
-    awaitActivePage(timeoutMs?: number): Promise<Page>;
-}
-
-interface AgentAction {
-    type: string;
-    reasoning?: string;
-    taskCompleted?: boolean;
-    action?: string;
-    timeMs?: number;
-    pageText?: string;
-    pageUrl?: string;
-    instruction?: string;
-    [key: string]: unknown;
-}
-interface AgentResult {
-    success: boolean;
-    message: string;
-    actions: AgentAction[];
-    completed: boolean;
-    metadata?: Record<string, unknown>;
-    usage?: {
-        input_tokens: number;
-        output_tokens: number;
-        inference_time_ms: number;
-    };
-}
-interface AgentOptions {
-    maxSteps?: number;
-    autoScreenshot?: boolean;
-    waitBetweenActions?: number;
-    context?: string;
-}
-interface AgentExecuteOptions extends AgentOptions {
-    instruction: string;
-}
-type AgentProviderType = "openai" | "anthropic";
-interface AgentClientOptions {
-    apiKey: string;
-    organization?: string;
-    baseURL?: string;
-    defaultMaxSteps?: number;
-    [key: string]: unknown;
-}
-type AgentType = "openai" | "anthropic";
-interface AgentExecutionOptions {
-    options: AgentExecuteOptions;
-    logger: (message: LogLine) => void;
-    retries?: number;
-}
-interface AgentHandlerOptions {
-    modelName: string;
-    clientOptions?: Record<string, unknown>;
-    userProvidedInstructions?: string;
-    agentType: AgentType;
-    experimental?: boolean;
-}
-interface ActionExecutionResult {
-    success: boolean;
-    error?: string;
-    data?: unknown;
-}
-interface ToolUseItem extends ResponseItem {
-    type: "tool_use";
-    id: string;
-    name: string;
-    input: Record<string, unknown>;
-}
-interface AnthropicMessage {
-    role: string;
-    content: string | Array<AnthropicContentBlock>;
-}
-interface AnthropicContentBlock {
-    type: string;
-    [key: string]: unknown;
-}
-interface AnthropicTextBlock extends AnthropicContentBlock {
-    type: "text";
-    text: string;
-}
-interface AnthropicToolResult {
-    type: "tool_result";
-    tool_use_id: string;
-    content: string | Array<AnthropicContentBlock>;
-}
-interface ResponseItem {
-    type: string;
-    id: string;
-    [key: string]: unknown;
-}
-interface ComputerCallItem extends ResponseItem {
-    type: "computer_call";
-    call_id: string;
-    action: {
-        type: string;
-        [key: string]: unknown;
-    };
-    pending_safety_checks?: Array<{
-        id: string;
-        code: string;
-        message: string;
-    }>;
-}
-interface FunctionCallItem extends ResponseItem {
-    type: "function_call";
-    call_id: string;
-    name: string;
-    arguments: string;
-}
-type ResponseInputItem = {
-    role: string;
-    content: string;
-} | {
-    type: "computer_call_output";
-    call_id: string;
-    output: {
-        type: "input_image";
-        image_url: string;
-        current_url?: string;
-        error?: string;
-        [key: string]: unknown;
-    } | string;
-    acknowledged_safety_checks?: Array<{
-        id: string;
-        code: string;
-        message: string;
-    }>;
-} | {
-    type: "function_call_output";
-    call_id: string;
-    output: string;
-};
-interface AgentInstance {
-    execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
-}
-
-interface ActOptions {
-    action: string;
-    model?: ModelConfiguration;
-    variables?: Record<string, string>;
-    domSettleTimeoutMs?: number;
-    timeoutMs?: number;
-    iframes?: boolean;
-    frameId?: string;
-}
-interface ActResult {
-    success: boolean;
-    message: string;
-    actionDescription: string;
-    actions: Action[];
-}
-interface ExtractOptions<T extends z.AnyZodObject> {
-    instruction?: string;
-    schema?: T;
-    model?: ModelConfiguration;
-    domSettleTimeoutMs?: number;
-    /**
-     * @deprecated The `useTextExtract` parameter has no effect in this version of Stagehand and will be removed in later versions.
+     * Wait until at least one top-level Page has been created and registered.
+     * We poll internal maps that bootstrap/onAttachedToTarget populate.
      */
-    useTextExtract?: boolean;
-    selector?: string;
-    iframes?: boolean;
-    frameId?: string;
-}
-type ExtractResult<T extends z.AnyZodObject> = z.infer<T>;
-interface ObserveOptions {
-    instruction?: string;
-    model?: ModelConfiguration;
-    domSettleTimeoutMs?: number;
-    returnAction?: boolean;
-    selector?: string;
+    private waitForFirstTopLevelPage;
+    private ensurePiercer;
+    /** Mark a page target as the most-recent one (active). */
+    private _pushActive;
+    /** Remove a page target from the recency list (used on close). */
+    private _removeFromOrder;
+    /** Return the current active Page (most-recent page that still exists). */
+    activePage(): Page | undefined;
+    /** Explicitly mark a known Page as the most-recent active page (and focus it). */
+    setActivePage(page: Page): void;
     /**
-     * @deprecated The `onlyVisible` parameter has no effect in this version of Stagehand and will be removed in later versions.
+     * Return top-level `Page`s (oldest → newest). OOPIF targets are not included.
      */
-    onlyVisible?: boolean;
-    drawOverlay?: boolean;
-    iframes?: boolean;
-    frameId?: string;
-}
-interface Action {
-    selector: string;
-    description: string;
-    backendNodeId?: number;
-    method?: string;
-    arguments?: string[];
-}
-/**
- * Configuration for agent functionality
- */
-interface AgentConfig {
+    pages(): Page[];
     /**
-     * The provider to use for agent functionality
+     * Resolve an owning `Page` by the **top-level main frame id**.
+     * Note: child (OOPIF) roots are intentionally not present in this mapping.
      */
-    provider?: AgentProviderType;
+    resolvePageByMainFrameId(frameId: string): Page | undefined;
     /**
-     * The model to use for agent functionality
+     * Serialize the full frame tree for a given top-level main frame id.
      */
-    model?: string;
+    getFullFrameTreeByMainFrameId(rootMainFrameId: string): Promise<Protocol.Page.FrameTree>;
     /**
-     * The model to use for tool execution (observe/act calls within agent tools).
-     * If not specified, inherits from the main model configuration.
-     * Format: "provider/model" (e.g., "openai/gpt-4o-mini", "google/gemini-2.0-flash-exp")
+     * Create a new top-level page (tab) with the given URL and return its Page object.
+     * Waits until the target is attached and registered.
      */
-    executionModel?: string;
+    newPage(url?: string): Promise<Page>;
     /**
-     * Custom instructions to provide to the agent
+     * Close CDP and clear all mappings. Best-effort cleanup.
      */
-    instructions?: string;
+    close(): Promise<void>;
     /**
-     * Additional options to pass to the agent client
+     * Bootstrap target lifecycle:
+     * - Attach to existing targets.
+     * - Attach on `Target.targetCreated` (fallback for OOPIFs).
+     * - Handle auto-attach events.
+     * - Clean up on detach/destroy.
      */
-    options?: Record<string, unknown>;
+    private bootstrap;
     /**
-     * MCP integrations - Array of Client objects
+     * Handle a newly attached target (top-level or potential OOPIF):
+     * - Enable Page domain and lifecycle events.
+     * - If top-level → create Page, wire listeners, resume.
+     * - Else → probe child root frame id via `Page.getFrameTree` and adopt immediately
+     *   if the parent is known; otherwise stage until parent `frameAttached`.
+     * - Resume the target only after listeners are wired.
      */
-    integrations?: (Client | string)[];
+    private onAttachedToTarget;
     /**
-     * Tools passed to the agent client
+     * Detach handler:
+     * - Remove child session ownership and prune its subtree.
+     * - If a top-level target, cleanup its `Page` and mappings.
+     * - Drop any staged child for this session.
      */
-    tools?: ToolSet;
-}
-interface HistoryEntry {
-    method: "act" | "extract" | "observe" | "navigate";
-    parameters: unknown;
-    result: unknown;
-    timestamp: string;
-}
-/**
- * Represents a path through a Zod schema from the root object down to a
- * particular field. The `segments` array describes the chain of keys/indices.
- *
- * - **String** segments indicate object property names.
- * - **Number** segments indicate array indices.
- *
- * For example, `["users", 0, "homepage"]` might describe reaching
- * the `homepage` field in `schema.users[0].homepage`.
- */
-interface ZodPathSegments {
+    private onDetachedFromTarget;
     /**
-     * The ordered list of keys/indices leading from the schema root
-     * to the targeted field.
+     * Cleanup a top-level Page by target id, removing its root and staged children.
      */
-    segments: Array<string | number>;
+    private cleanupByTarget;
+    /**
+     * Wire Page-domain frame events for a session into the owning Page & mappings.
+     * We forward the *emitting session* with every event so Page can stamp ownership precisely.
+     */
+    private installFrameEventBridges;
+    /**
+     * Register that a session belongs to a Page (used by event routing).
+     */
+    private wireSessionToOwnerPage;
+    /**
+     * Utility: reverse-lookup the top-level target id that owns a given Page.
+     */
+    private findTargetIdByPage;
+    private _notePopupSignal;
+    /**
+     * Await the current active page, waiting briefly if a popup/open was just triggered.
+     * Normal path returns immediately; popup path waits up to timeoutMs for the new page.
+     */
+    awaitActivePage(timeoutMs?: number): Promise<Page>;
 }
 
 type AgentReplayStep = AgentReplayActStep | AgentReplayFillFormStep | AgentReplayGotoStep | AgentReplayScrollStep | AgentReplayWaitStep | AgentReplayNavBackStep | {
@@ -1353,6 +1502,7 @@ declare class V3 {
     private modelName;
     private modelClientOptions;
     private llmProvider;
+    private overrideLlmClients;
     private readonly domSettleTimeoutMs?;
     private _isClosing;
     browserbaseSessionId?: string;
@@ -1365,15 +1515,16 @@ declare class V3 {
     private readonly instanceId;
     private static _processGuardsInstalled;
     private static _instances;
-    private cacheDir?;
-    private _agentReplayRecording;
+    private cacheStorage;
+    private actCache;
+    private agentCache;
     v3Metrics: V3Metrics;
     /**
      * Async property for metrics so callers can `await v3.metrics`.
      * Returning a Promise future-proofs async aggregation/storage.
      */
     get metrics(): Promise<V3Metrics>;
-    private cloneForCache;
+    private resolveLlmClient;
     private beginAgentReplayRecording;
     private endAgentReplayRecording;
     private discardAgentReplayRecording;
@@ -1406,8 +1557,8 @@ declare class V3 {
      * - act(instruction: string, options?: ActOptions)
      * - act(action: Action, options?: ActOptions)
      */
-    act(instruction: string, options?: ActOptions$1): Promise<ActResult>;
-    act(action: Action, options?: ActOptions$1): Promise<ActResult>;
+    act(instruction: string, options?: ActOptions): Promise<ActResult>;
+    act(action: Action, options?: ActOptions): Promise<ActResult>;
     /**
      * Run an "extract" instruction through the ExtractHandler.
      *
@@ -1419,15 +1570,15 @@ declare class V3 {
      * - extract(instruction, schema, options)
      */
     extract(): Promise<z.infer<typeof pageTextSchema>>;
-    extract(options: ExtractOptions$1): Promise<z.infer<typeof pageTextSchema>>;
-    extract(instruction: string, options?: ExtractOptions$1): Promise<z.infer<typeof defaultExtractSchema>>;
-    extract<T extends ZodTypeAny>(instruction: string, schema: T, options?: ExtractOptions$1): Promise<z.infer<T>>;
+    extract(options: ExtractOptions): Promise<z.infer<typeof pageTextSchema>>;
+    extract(instruction: string, options?: ExtractOptions): Promise<z.infer<typeof defaultExtractSchema>>;
+    extract<T extends ZodTypeAny>(instruction: string, schema: T, options?: ExtractOptions): Promise<z.infer<T>>;
     /**
      * Run an "observe" instruction through the ObserveHandler.
      */
     observe(): Promise<Action[]>;
-    observe(options: ObserveOptions$1): Promise<Action[]>;
-    observe(instruction: string, options?: ObserveOptions$1): Promise<Action[]>;
+    observe(options: ObserveOptions): Promise<Action[]>;
+    observe(instruction: string, options?: ObserveOptions): Promise<Action[]>;
     /** Return the browser-level CDP WebSocket endpoint. */
     connectURL(): string;
     /** Expose the current CDP-backed context. */
@@ -1447,26 +1598,9 @@ declare class V3 {
     private isPlaywrightPage;
     private isPatchrightPage;
     private isPuppeteerPage;
+    /** Resolve an external page reference or fall back to the active V3 page. */
+    private resolvePage;
     private normalizeToV3Page;
-    private buildActCacheKey;
-    private safeGetPageUrl;
-    private readActCacheEntry;
-    private writeActCacheEntry;
-    private sanitizeAgentExecuteOptions;
-    private buildAgentCacheSignature;
-    private buildAgentCacheKey;
-    private readAgentCacheEntry;
-    private writeAgentCacheEntry;
-    private replayAgentCacheEntry;
-    private executeAgentReplayStep;
-    private replayAgentActStep;
-    private replayAgentFillFormStep;
-    private replayAgentGotoStep;
-    private replayAgentScrollStep;
-    private replayAgentWaitStep;
-    private replayAgentNavBackStep;
-    private replayCachedActions;
-    private runWithActTimeout;
     /**
      * Create a v3 agent instance (AISDK tool-based) with execute().
      * Mirrors the v2 Stagehand.agent() tool mode (no CUA provider here).
@@ -1476,128 +1610,100 @@ declare class V3 {
     };
 }
 
-declare class StagehandAPIError extends Error {
-    constructor(message: string);
-}
-declare class StagehandAPIUnauthorizedError extends StagehandAPIError {
-    constructor(message?: string);
-}
-declare class StagehandHttpError extends StagehandAPIError {
-    constructor(message: string);
-}
-declare class StagehandServerError extends StagehandAPIError {
-    constructor(message: string);
-}
-declare class StagehandResponseBodyError extends StagehandAPIError {
-    constructor();
-}
-declare class StagehandResponseParseError extends StagehandAPIError {
-    constructor(message: string);
+/**
+ * Abstract base class for agent clients
+ * This provides a common interface for all agent implementations
+ */
+declare abstract class AgentClient {
+    type: AgentType;
+    modelName: string;
+    clientOptions: Record<string, unknown>;
+    userProvidedInstructions?: string;
+    constructor(type: AgentType, modelName: string, userProvidedInstructions?: string);
+    abstract execute(options: AgentExecutionOptions): Promise<AgentResult>;
+    abstract captureScreenshot(options?: Record<string, unknown>): Promise<unknown>;
+    abstract setViewport(width: number, height: number): void;
+    abstract setCurrentUrl(url: string): void;
+    abstract setScreenshotProvider(provider: () => Promise<string>): void;
+    abstract setActionHandler(handler: (action: AgentAction) => Promise<void>): void;
 }
 
-declare class StagehandError extends Error {
-    constructor(message: string);
-}
-declare class StagehandDefaultError extends StagehandError {
-    constructor(error?: unknown);
-}
-declare class StagehandEnvironmentError extends StagehandError {
-    constructor(currentEnvironment: string, requiredEnvironment: string, feature: string);
-}
-declare class MissingEnvironmentVariableError extends StagehandError {
-    constructor(missingEnvironmentVariable: string, feature: string);
-}
-declare class UnsupportedModelError extends StagehandError {
-    constructor(supportedModels: string[], feature?: string);
-}
-declare class UnsupportedModelProviderError extends StagehandError {
-    constructor(supportedProviders: string[], feature?: string);
-}
-declare class UnsupportedAISDKModelProviderError extends StagehandError {
-    constructor(provider: string, supportedProviders: string[]);
-}
-declare class InvalidAISDKModelFormatError extends StagehandError {
-    constructor(modelName: string);
-}
-declare class StagehandNotInitializedError extends StagehandError {
-    constructor(prop: string);
-}
-declare class BrowserbaseSessionNotFoundError extends StagehandError {
-    constructor();
-}
-declare class CaptchaTimeoutError extends StagehandError {
-    constructor();
-}
-declare class MissingLLMConfigurationError extends StagehandError {
-    constructor();
-}
-declare class HandlerNotInitializedError extends StagehandError {
-    constructor(handlerType: string);
-}
-declare class StagehandInvalidArgumentError extends StagehandError {
-    constructor(message: string);
-}
-declare class StagehandElementNotFoundError extends StagehandError {
-    constructor(xpaths: string[]);
-}
-declare class AgentScreenshotProviderError extends StagehandError {
-    constructor(message: string);
-}
-declare class StagehandMissingArgumentError extends StagehandError {
-    constructor(message: string);
-}
-declare class CreateChatCompletionResponseError extends StagehandError {
-    constructor(message: string);
-}
-declare class StagehandEvalError extends StagehandError {
-    constructor(message: string);
-}
-declare class StagehandDomProcessError extends StagehandError {
-    constructor(message: string);
-}
-declare class StagehandClickError extends StagehandError {
-    constructor(message: string, selector: string);
-}
-declare class LLMResponseError extends StagehandError {
-    constructor(primitive: string, message: string);
-}
-declare class StagehandIframeError extends StagehandError {
-    constructor(frameUrl: string, message: string);
-}
-declare class ContentFrameNotFoundError extends StagehandError {
-    constructor(selector: string);
-}
-declare class XPathResolutionError extends StagehandError {
-    constructor(xpath: string);
-}
-declare class ExperimentalApiConflictError extends StagehandError {
-    constructor();
-}
-declare class ExperimentalNotConfiguredError extends StagehandError {
-    constructor(featureName: string);
-}
-declare class ZodSchemaValidationError extends Error {
-    readonly received: unknown;
-    readonly issues: ReturnType<ZodError["format"]>;
-    constructor(received: unknown, issues: ReturnType<ZodError["format"]>);
-}
-declare class StagehandInitError extends StagehandError {
-    constructor(message: string);
-}
-declare class MCPConnectionError extends StagehandError {
-    readonly serverUrl: string;
-    readonly originalError: unknown;
-    constructor(serverUrl: string, originalError: unknown);
-}
-declare class StagehandShadowRootMissingError extends StagehandError {
-    constructor(detail?: string);
+declare const modelToAgentProviderMap: Record<string, AgentProviderType>;
+/**
+ * Provider for agent clients
+ * This class is responsible for creating the appropriate agent client
+ * based on the provider type
+ */
+declare class AgentProvider {
+    private logger;
+    /**
+     * Create a new agent provider
+     */
+    constructor(logger: (message: LogLine) => void);
+    getClient(modelName: string, clientOptions?: Record<string, unknown>, userProvidedInstructions?: string, tools?: ToolSet$1): AgentClient;
+    static getAgentProvider(modelName: string): AgentProviderType;
 }
-declare class StagehandShadowSegmentEmptyError extends StagehandError {
-    constructor();
+
+declare function validateZodSchema(schema: z.ZodTypeAny, data: unknown): boolean;
+/**
+ * Detects if the code is running in the Bun runtime environment.
+ * @returns {boolean} True if running in Bun, false otherwise.
+ */
+declare function isRunningInBun(): boolean;
+declare function toGeminiSchema(zodSchema: z.ZodTypeAny): Schema;
+declare function getZodType(schema: z.ZodTypeAny): string;
+/**
+ * Recursively traverses a given Zod schema, scanning for any fields of type `z.string().url()`.
+ * For each such field, it replaces the `z.string().url()` with `z.number()`.
+ *
+ * This function is used internally by higher-level utilities (e.g., transforming entire object schemas)
+ * and handles nested objects, arrays, unions, intersections, optionals.
+ *
+ * @param schema - The Zod schema to transform.
+ * @param currentPath - An array of string/number keys representing the current schema path (used internally for recursion).
+ * @returns A two-element tuple:
+ *   1. The updated Zod schema, with any `.url()` fields replaced by `z.number()`.
+ *   2. An array of {@link ZodPathSegments} objects representing each replaced field, including the path segments.
+ */
+declare function transformSchema(schema: z.ZodTypeAny, currentPath: Array<string | number>): [z.ZodTypeAny, ZodPathSegments[]];
+/**
+ * Once we get the final extracted object that has numeric IDs in place of URLs,
+ * use `injectUrls` to walk the object and replace numeric IDs
+ * with the real URL strings from idToUrlMapping. The `path` may include `*`
+ * for array indices (indicating "all items in the array").
+ */
+declare function injectUrls(obj: unknown, path: Array<string | number>, idToUrlMapping: Record<string, string>): void;
+/**
+ * Mapping from LLM provider names to their corresponding environment variable names for API keys.
+ */
+declare const providerEnvVarMap: Partial<Record<ModelProvider | string, string>>;
+/**
+ * Loads an API key for a provider, checking environment variables.
+ * @param provider The name of the provider (e.g., 'openai', 'anthropic')
+ * @param logger Optional logger for info/error messages
+ * @returns The API key if found, undefined otherwise
+ */
+declare function loadApiKeyFromEnv(provider: string | undefined, logger: (logLine: LogLine) => void): string | undefined;
+declare function trimTrailingTextNode(path: string | undefined): string | undefined;
+interface JsonSchemaProperty {
+    type: string;
+    enum?: unknown[];
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    minimum?: number;
+    maximum?: number;
+    description?: string;
 }
-declare class StagehandShadowSegmentNotFoundError extends StagehandError {
-    constructor(segment: string, hint?: string);
+interface JsonSchema extends JsonSchemaProperty {
+    type: string;
 }
+/**
+ * Converts a JSON Schema object to a Zod schema
+ * @param schema The JSON Schema object to convert
+ * @returns A Zod schema equivalent to the input JSON Schema
+ */
+declare function jsonSchemaToZod(schema: JsonSchema): ZodTypeAny;
 
 interface ConnectToMCPServerOptions {
     serverUrl: string | URL;
@@ -1608,6 +1714,24 @@ interface StdioServerConfig {
     args?: string[];
     env?: Record<string, string>;
 }
-declare const connectToMCPServer: (serverConfig: string | URL | StdioServerConfig | ConnectToMCPServerOptions) => Promise<Client$1>;
+declare const connectToMCPServer: (serverConfig: string | URL | StdioServerConfig | ConnectToMCPServerOptions) => Promise<Client>;
+
+/**
+ * V3Evaluator mirrors Evaluator but operates on a V3 instance instead of Stagehand.
+ * It uses the V3 page/screenshot APIs and constructs an LLM client to run
+ * structured evaluations (YES/NO with reasoning) on screenshots and/or text.
+ */
+
+declare class V3Evaluator {
+    private v3;
+    private modelName;
+    private modelClientOptions;
+    private silentLogger;
+    constructor(v3: V3, modelName?: AvailableModel, modelClientOptions?: ClientOptions);
+    private getClient;
+    ask(options: EvaluateOptions): Promise<EvaluationResult>;
+    batchAsk(options: BatchAskOptions): Promise<EvaluationResult[]>;
+    private _evaluateWithMultipleScreenshots;
+}
 
-export { type ActOptions, type ActResult, type Action, type ActionExecutionResult, type AgentAction, type AgentClientOptions, type AgentConfig, type AgentExecuteOptions, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentOptions, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AvailableModel, AvailableModelSchema, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, HandlerNotInitializedError, type HistoryEntry, InvalidAISDKModelFormatError, LLMClient, type LLMResponse, LLMResponseError, LOG_LEVEL_NAMES, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelProvider, type ObserveOptions, type ResponseInputItem, type ResponseItem, V3 as Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, XPathResolutionError, type ZodPathSegments, ZodSchemaValidationError, connectToMCPServer };
+export { type AISDKCustomProvider, type AISDKProvider, AVAILABLE_CUA_MODELS, type ActOptions, type ActResult, type Action, type ActionExecutionResult, type AgentAction, type AgentConfig, type AgentExecuteOptions, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentModelConfig, AgentProvider, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AnyPage, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, HandlerNotInitializedError, type HistoryEntry, InvalidAISDKModelFormatError, type JsonSchema, type JsonSchemaProperty, LLMClient, type LLMResponse, LLMResponseError, type LLMTool, LOG_LEVEL_NAMES, type LoadState, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelProvider, type ObserveOptions, type ResponseInputItem, type ResponseItem, V3 as Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Metrics, type V3Options, XPathResolutionError, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, jsonSchemaToZod, loadApiKeyFromEnv, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, transformSchema, trimTrailingTextNode, validateZodSchema };