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

package/dist/index.d.ts

@@ -1,15 +1,165 @@
-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, ZodTypeAny, ZodError } from 'zod/v3';
 import { ClientOptions as ClientOptions$2 } from '@anthropic-ai/sdk';
+import { LanguageModel, generateObject, generateText, streamText, streamObject, experimental_generateImage, embed, embedMany, experimental_transcribe, experimental_generateSpeech, ToolSet } from 'ai';
 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 { Client, ClientOptions as ClientOptions$3 } from '@modelcontextprotocol/sdk/client/index.js';
+import { Page as Page$1 } from 'playwright-core';
+export { Page as PlaywrightPage } from 'playwright-core';
+import { Page as Page$2 } from 'puppeteer-core';
+export { Page as PuppeteerPage } from 'puppeteer-core';
+import { Page as Page$3 } from 'patchright-core';
+export { Page as PatchrightPage } from 'patchright-core';
+import { Protocol } from 'devtools-protocol';
+import { Buffer as Buffer$1 } from 'buffer';
+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) => LanguageModel;
+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";
+    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;
+    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?(): LanguageModel;
+}
 
 /**
  * CDP transport & session multiplexer
@@ -115,7 +265,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 +303,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 +335,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 +365,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:
@@ -289,35 +449,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 +474,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 +521,8 @@ declare class DeepLocatorDelegate {
         composed?: boolean;
         detail?: number;
     }): Promise<void>;
-    first(): this;
+    first(): DeepLocatorDelegate;
+    nth(index: number): DeepLocatorDelegate;
 }
 
 /**
@@ -407,6 +552,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 +565,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 +589,8 @@ 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 constructor();
     private cursorEnabled;
     private ensureCursorScript;
@@ -463,6 +615,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.
@@ -477,6 +630,8 @@ declare class Page {
     /** Expose a session by id (used by snapshot to resolve session id -> session) */
     getSessionById(id: string): CDPSessionLike | undefined;
     targetId(): string;
+    /** Seed the cached URL before navigation events converge. */
+    seedCurrentUrl(url: string | undefined | null): void;
     mainFrameId(): string;
     mainFrame(): Frame;
     /**
@@ -520,9 +675,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 +689,7 @@ declare class Page {
      */
     screenshot(options?: {
         fullPage?: boolean;
-    }): Promise<string>;
+    }): Promise<Buffer>;
     /**
      * Create a locator bound to the current main frame.
      */
@@ -658,441 +813,46 @@ declare class Page {
     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>;
+interface AgentAction {
+    type: string;
+    reasoning?: string;
+    taskCompleted?: boolean;
+    action?: string;
+    timeMs?: number;
+    pageText?: string;
+    pageUrl?: string;
+    instruction?: string;
+    [key: string]: unknown;
 }
-
-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;
+interface AgentResult {
+    success: boolean;
     message: string;
-    level?: LogLevel;
-    timestamp?: string;
-    auxiliary?: {
-        [key: string]: {
-            value: string;
-            type: "object" | "string" | "html" | "integer" | "float" | "boolean";
-        };
+    actions: AgentAction[];
+    completed: boolean;
+    metadata?: Record<string, unknown>;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+        inference_time_ms: number;
     };
-};
-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 AgentExecuteOptions {
+    instruction: string;
+    maxSteps?: number;
+    highlightCursor?: boolean;
+    page?: Page$1 | Page$2 | Page$3 | Page;
 }
-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";
-    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;
-    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?(): LanguageModel;
-}
-
-type V3Env = "LOCAL" | "BROWSERBASE";
-/** Local launch options for V3 (chrome-launcher + CDP).
- * Matches v2 shape where feasible; unsupported fields are accepted but ignored.
- */
-interface LocalBrowserLaunchOptions {
-    args?: string[];
-    executablePath?: string;
-    userDataDir?: string;
-    preserveUserDataDir?: boolean;
-    headless?: boolean;
-    devtools?: boolean;
-    chromiumSandbox?: boolean;
-    ignoreDefaultArgs?: boolean | string[];
-    proxy?: {
-        server: string;
-        bypass?: string;
-        username?: string;
-        password?: string;
-    };
-    locale?: string;
-    viewport?: {
-        width: number;
-        height: number;
-    };
-    deviceScaleFactor?: number;
-    hasTouch?: boolean;
-    ignoreHTTPSErrors?: boolean;
-    cdpUrl?: string;
-    connectTimeoutMs?: number;
-    downloadsPath?: string;
-    acceptDownloads?: boolean;
-}
-/** Constructor options for V3 */
-interface V3Options {
-    env: V3Env;
-    apiKey?: string;
-    projectId?: string;
-    /**
-     * Optional: fine-tune Browserbase session creation or resume an existing session.
-     */
-    browserbaseSessionCreateParams?: Omit<Browserbase.Sessions.SessionCreateParams, "projectId"> & {
-        projectId?: string;
-    };
-    browserbaseSessionID?: string;
-    localBrowserLaunchOptions?: LocalBrowserLaunchOptions;
-    model?: ModelConfiguration;
-    llmClient?: LLMClient;
-    systemPrompt?: string;
-    logInferenceToFile?: boolean;
-    experimental?: boolean;
-    verbose?: 0 | 1 | 2;
-    selfHeal?: boolean;
-    /** Disable pino logging backend (useful for tests or minimal environments). */
-    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;
-}
-interface ExtractOptions$1 {
-    model?: ModelConfiguration;
-    timeout?: number;
-    selector?: string;
-    page?: PlaywrightPage | PuppeteerPage | PatchrightPage | 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$1 {
-    model?: ModelConfiguration;
-    timeout?: number;
-    selector?: string;
-    page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
-}
-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 enum V3FunctionName {
-    ACT = "ACT",
-    EXTRACT = "EXTRACT",
-    OBSERVE = "OBSERVE",
-    AGENT = "AGENT"
-}
-
-/**
- * V3Context
- *
- * Owns the root CDP connection and wires Target/Page events into Page.
- * Maintains one Page per top-level target, adopts OOPIF child sessions into the owner Page,
- * and tracks target→page and (root) frame→target mappings for lookups.
- *
- * IMPORTANT: FrameId → session ownership is managed inside Page (via its FrameRegistry).
- * Context never “guesses” owners; it simply forwards events (with the emitting session)
- * so Page can record the correct owner at event time.
- */
-declare class V3Context {
-    readonly conn: CdpConnection;
-    private readonly includeCursor;
-    private readonly env;
-    private constructor();
-    private readonly _piercerInstalled;
-    private _lastPopupSignalAt;
-    private sessionKey;
-    private readonly _sessionInit;
-    private pagesByTarget;
-    private mainFrameToTarget;
-    private sessionOwnerPage;
-    private frameOwnerPage;
-    private pendingOopifByMainFrame;
-    private createdAtByTarget;
-    private typeByTarget;
-    private _pageOrder;
-    /**
-     * 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;
+type AgentType = "openai" | "anthropic" | "google";
+type AvailableCuaModel = "openai/computer-use-preview" | "openai/computer-use-preview-2025-03-11" | "anthropic/claude-3-7-sonnet-latest" | "anthropic/claude-sonnet-4-20250514" | "anthropic/claude-sonnet-4-5-20250929" | "google/gemini-2.5-computer-use-preview-10-2025";
+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 {
@@ -1173,15 +933,64 @@ type ResponseInputItem = {
 interface AgentInstance {
     execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
 }
+type AgentProviderType = AgentType;
+type AgentModelConfig<TModelName extends string = string> = {
+    modelName: TModelName;
+} & Record<string, unknown>;
+type SharedAgentConfigFields = {
+    /**
+     * 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;
+};
+type StandardAgentConfig = SharedAgentConfigFields & {
+    /**
+     * Indicates CUA is disabled for this configuration
+     */
+    cua?: false;
+    /**
+     * 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;
+};
+type CuaAgentConfig = SharedAgentConfigFields & {
+    /**
+     * Indicates CUA is enabled for this configuration
+     */
+    cua: true;
+    /**
+     * The model to use for agent functionality when CUA is enabled
+     */
+    model: AvailableCuaModel | AgentModelConfig<AvailableCuaModel>;
+    /**
+     * Execution models are not supported when CUA is enabled
+     */
+    executionModel?: never;
+};
+/**
+ * Configuration for agent functionality
+ */
+type AgentConfig = StandardAgentConfig | CuaAgentConfig;
 
 interface ActOptions {
-    action: string;
     model?: ModelConfiguration;
     variables?: Record<string, string>;
-    domSettleTimeoutMs?: number;
-    timeoutMs?: number;
-    iframes?: boolean;
-    frameId?: string;
+    timeout?: number;
+    page?: Page$1 | Page$2 | Page$3 | Page;
 }
 interface ActResult {
     success: boolean;
@@ -1189,142 +998,321 @@ interface ActResult {
     actionDescription: string;
     actions: Action[];
 }
-interface ExtractOptions<T extends z.AnyZodObject> {
-    instruction?: string;
-    schema?: T;
+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 CachedActEntry {
+    version: 1;
+    instruction: string;
+    url: string;
+    variables: Record<string, string>;
+    actions: Action[];
+    actionDescription?: string;
+    message?: string;
+}
+type AgentReplayStep = AgentReplayActStep | AgentReplayFillFormStep | AgentReplayGotoStep | AgentReplayScrollStep | AgentReplayWaitStep | AgentReplayNavBackStep | {
+    type: string;
+    [key: string]: unknown;
+};
+interface AgentReplayActStep {
+    type: "act";
+    instruction: string;
+    actions?: Action[];
+    actionDescription?: string;
+    message?: string;
+    timeout?: number;
+}
+interface AgentReplayFillFormStep {
+    type: "fillForm";
+    fields?: Array<{
+        action: string;
+        value: string;
+    }>;
+    observeResults?: Action[];
+    actions?: Action[];
+}
+interface AgentReplayGotoStep {
+    type: "goto";
+    url: string;
+    waitUntil?: LoadState;
+}
+interface AgentReplayScrollStep {
+    type: "scroll";
+    deltaX?: number;
+    deltaY?: number;
+    anchor?: {
+        x: number;
+        y: number;
+    };
+}
+interface AgentReplayWaitStep {
+    type: "wait";
+    timeMs: number;
+}
+interface AgentReplayNavBackStep {
+    type: "navback";
+    waitUntil?: LoadState;
+}
+interface SanitizedAgentExecuteOptions {
+    maxSteps?: number;
+    autoScreenshot?: boolean;
+    waitBetweenActions?: number;
+    context?: string;
+}
+interface CachedAgentEntry {
+    version: 1;
+    instruction: string;
+    startUrl: string;
+    options: SanitizedAgentExecuteOptions;
+    configSignature: string;
+    steps: AgentReplayStep[];
+    result: AgentResult;
+    timestamp: string;
+}
+
+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";
+/** Local launch options for V3 (chrome-launcher + CDP).
+ * Matches v2 shape where feasible; unsupported fields are accepted but ignored.
+ */
+interface LocalBrowserLaunchOptions {
+    args?: string[];
+    executablePath?: string;
+    userDataDir?: string;
+    preserveUserDataDir?: boolean;
+    headless?: boolean;
+    devtools?: boolean;
+    chromiumSandbox?: boolean;
+    ignoreDefaultArgs?: boolean | string[];
+    proxy?: {
+        server: string;
+        bypass?: string;
+        username?: string;
+        password?: string;
+    };
+    locale?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    deviceScaleFactor?: number;
+    hasTouch?: boolean;
+    ignoreHTTPSErrors?: boolean;
+    cdpUrl?: string;
+    connectTimeoutMs?: number;
+    downloadsPath?: string;
+    acceptDownloads?: boolean;
+}
+/** Constructor options for V3 */
+interface V3Options {
+    env: V3Env;
+    apiKey?: string;
+    projectId?: string;
+    /**
+     * Optional: fine-tune Browserbase session creation or resume an existing session.
+     */
+    browserbaseSessionCreateParams?: Omit<Browserbase.Sessions.SessionCreateParams, "projectId"> & {
+        projectId?: string;
+    };
+    browserbaseSessionID?: string;
+    localBrowserLaunchOptions?: LocalBrowserLaunchOptions;
     model?: ModelConfiguration;
-    domSettleTimeoutMs?: number;
+    llmClient?: LLMClient;
+    systemPrompt?: string;
+    logInferenceToFile?: boolean;
+    experimental?: boolean;
+    verbose?: 0 | 1 | 2;
+    selfHeal?: boolean;
+    /** Disable pino logging backend (useful for tests or minimal environments). */
+    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;
+}
+
+/**
+ * V3Context
+ *
+ * Owns the root CDP connection and wires Target/Page events into Page.
+ * Maintains one Page per top-level target, adopts OOPIF child sessions into the owner Page,
+ * and tracks target→page and (root) frame→target mappings for lookups.
+ *
+ * IMPORTANT: FrameId → session ownership is managed inside Page (via its FrameRegistry).
+ * Context never “guesses” owners; it simply forwards events (with the emitting session)
+ * so Page can record the correct owner at event time.
+ */
+declare class V3Context {
+    readonly conn: CdpConnection;
+    private readonly includeCursor;
+    private readonly env;
+    private constructor();
+    private readonly _piercerInstalled;
+    private _lastPopupSignalAt;
+    private sessionKey;
+    private readonly _sessionInit;
+    private pagesByTarget;
+    private mainFrameToTarget;
+    private sessionOwnerPage;
+    private frameOwnerPage;
+    private pendingOopifByMainFrame;
+    private createdAtByTarget;
+    private typeByTarget;
+    private _pageOrder;
+    private pendingCreatedTargetUrl;
     /**
-     * @deprecated The `useTextExtract` parameter has no effect in this version of Stagehand and will be removed in later versions.
+     * Create a Context for a given CDP websocket URL and bootstrap target wiring.
      */
-    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;
+    static create(wsUrl: string, opts?: {
+        includeCursor?: boolean;
+        env?: "LOCAL" | "BROWSERBASE";
+    }): Promise<V3Context>;
     /**
-     * @deprecated The `onlyVisible` 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.
      */
-    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 {
+    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;
     /**
-     * The provider to use for agent functionality
+     * Return top-level `Page`s (oldest → newest). OOPIF targets are not included.
      */
-    provider?: AgentProviderType;
+    pages(): Page[];
     /**
-     * The model 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.
      */
-    model?: string;
+    resolvePageByMainFrameId(frameId: string): Page | undefined;
     /**
-     * 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")
+     * Serialize the full frame tree for a given top-level main frame id.
      */
-    executionModel?: string;
+    getFullFrameTreeByMainFrameId(rootMainFrameId: string): Promise<Protocol.Page.FrameTree>;
     /**
-     * Custom instructions to provide to the agent
+     * Create a new top-level page (tab) with the given URL and return its Page object.
+     * Waits until the target is attached and registered.
      */
-    instructions?: string;
+    newPage(url?: string): Promise<Page>;
     /**
-     * Additional options to pass to the agent client
+     * Close CDP and clear all mappings. Best-effort cleanup.
      */
-    options?: Record<string, unknown>;
+    close(): Promise<void>;
     /**
-     * MCP integrations - Array of Client objects
+     * Bootstrap target lifecycle:
+     * - Attach to existing targets.
+     * - Attach on `Target.targetCreated` (fallback for OOPIFs).
+     * - Handle auto-attach events.
+     * - Clean up on detach/destroy.
      */
-    integrations?: (Client | string)[];
+    private bootstrap;
     /**
-     * Tools passed to the agent client
+     * 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.
      */
-    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 onAttachedToTarget;
     /**
-     * The ordered list of keys/indices leading from the schema root
-     * to the targeted field.
+     * 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.
      */
-    segments: Array<string | number>;
-}
-
-type AgentReplayStep = AgentReplayActStep | AgentReplayFillFormStep | AgentReplayGotoStep | AgentReplayScrollStep | AgentReplayWaitStep | AgentReplayNavBackStep | {
-    type: string;
-    [key: string]: unknown;
-};
-interface AgentReplayActStep {
-    type: "act";
-    instruction: string;
-    actions?: Action[];
-    actionDescription?: string;
-    message?: string;
-    timeout?: number;
-}
-interface AgentReplayFillFormStep {
-    type: "fillForm";
-    fields?: Array<{
-        action: string;
-        value: string;
-    }>;
-    observeResults?: Action[];
-    actions?: Action[];
-}
-interface AgentReplayGotoStep {
-    type: "goto";
-    url: string;
-    waitUntil?: LoadState;
-}
-interface AgentReplayScrollStep {
-    type: "scroll";
-    deltaX?: number;
-    deltaY?: number;
-    anchor?: {
-        x: number;
-        y: number;
-    };
-}
-interface AgentReplayWaitStep {
-    type: "wait";
-    timeMs: number;
-}
-interface AgentReplayNavBackStep {
-    type: "navback";
-    waitUntil?: LoadState;
+    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>;
 }
 
 /**
@@ -1353,6 +1341,7 @@ declare class V3 {
     private modelName;
     private modelClientOptions;
     private llmProvider;
+    private overrideLlmClients;
     private readonly domSettleTimeoutMs?;
     private _isClosing;
     browserbaseSessionId?: string;
@@ -1374,6 +1363,7 @@ declare class V3 {
      */
     get metrics(): Promise<V3Metrics>;
     private cloneForCache;
+    private resolveLlmClient;
     private beginAgentReplayRecording;
     private endAgentReplayRecording;
     private discardAgentReplayRecording;
@@ -1406,8 +1396,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 +1409,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. */
@@ -1453,6 +1443,10 @@ declare class V3 {
     private readActCacheEntry;
     private writeActCacheEntry;
     private sanitizeAgentExecuteOptions;
+    private createLlmClientOverride;
+    private inferProviderFromModelName;
+    private extractAgentModel;
+    private serializeAgentModelForCache;
     private buildAgentCacheSignature;
     private buildAgentCacheKey;
     private readAgentCacheEntry;
@@ -1599,6 +1593,119 @@ declare class StagehandShadowSegmentNotFoundError extends StagehandError {
     constructor(segment: string, hint?: 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 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;
+}
+
+/**
+ * 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 {
+    /**
+     * The ordered list of keys/indices leading from the schema root
+     * to the targeted field.
+     */
+    segments: Array<string | number>;
+}
+
+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;
+}
+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;
     clientOptions?: ClientOptions$3;
@@ -1608,6 +1715,65 @@ 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>;
+
+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;
+}
+
+/**
+ * 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, 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 AgentReplayActStep, type AgentReplayFillFormStep, type AgentReplayGotoStep, type AgentReplayNavBackStep, type AgentReplayScrollStep, type AgentReplayStep, type AgentReplayWaitStep, type AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AnyPage, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, type CachedActEntry, type CachedAgentEntry, 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, type SanitizedAgentExecuteOptions, 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 };