@browserbasehq/stagehand 2.5.3-alpha-4994eabfa8016347ec001b40ceadb0c905403470 → 4.0.0-alpha-49bc5b68e4fbeb28a120b301b51c31a36db7d922

package/dist/index.d.ts

@@ -1,25 +1,47 @@
-import { z, ZodType, ZodError } from 'zod/v3';
-import Browserbase from '@browserbasehq/sdk';
-import { Client } from '@modelcontextprotocol/sdk/dist/esm/client';
-import { generateObject, generateText, streamText, streamObject, experimental_generateImage, embed, embedMany, experimental_transcribe, experimental_generateSpeech, LanguageModel, ToolSet } from 'ai';
-import { Cookie, Page as Page$1, PageScreenshotOptions, Browser as Browser$1, BrowserContext as BrowserContext$1, Frame, CDPSession } from 'playwright';
+import z, { ZodType, z as z$1, 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 { ClientOptions as ClientOptions$3, Client as Client$1 } from '@modelcontextprotocol/sdk/client/index.js';
-import { ChatCompletion } from 'openai/resources';
+import { generateObject, generateText, streamText, streamObject, experimental_generateImage, embed, embedMany, experimental_transcribe, experimental_generateSpeech, ToolSet } from 'ai';
+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';
 
-declare class PlaywrightCommandException extends Error {
-    constructor(message: string);
-}
-declare class PlaywrightCommandMethodNotSupportedException extends Error {
-    constructor(message: string);
-}
-interface GotoOptions {
-    timeout?: number;
-    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
-    referer?: string;
-    frameId?: string;
+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;
 /**
@@ -45,28 +67,6 @@ type LogLine = {
 };
 type Logger = (logLine: LogLine) => void;
 
-interface LLMTool {
-    type: "function";
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-}
-
-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;
-interface AnthropicJsonSchemaObject {
-    definitions?: {
-        MySchema?: {
-            properties?: Record<string, unknown>;
-            required?: string[];
-        };
-    };
-    properties?: Record<string, unknown>;
-    required?: string[];
-}
-
 interface ChatMessage {
     role: "system" | "user" | "assistant";
     content: ChatMessageContent;
@@ -105,7 +105,7 @@ interface ChatCompletionOptions {
     };
     tools?: LLMTool[];
     tool_choice?: "auto" | "none" | "required";
-    maxTokens?: number;
+    maxOutputTokens?: number;
     requestId?: string;
 }
 type LLMResponse = {
@@ -159,393 +159,757 @@ declare abstract class LLMClient {
     embedMany: typeof embedMany;
     transcribe: typeof experimental_transcribe;
     generateSpeech: typeof experimental_generateSpeech;
-    getLanguageModel?(): LanguageModel;
+    getLanguageModel?(): LanguageModelV2;
 }
 
-declare class LLMProvider {
-    private logger;
-    private enableCaching;
-    private cache;
-    constructor(logger: (message: LogLine) => void, enableCaching: boolean);
-    cleanRequestCache(requestId: string): void;
-    getClient(modelName: AvailableModel, clientOptions?: ClientOptions): LLMClient;
-    static getModelProvider(modelName: AvailableModel): ModelProvider;
+/**
+ * CDP transport & session multiplexer
+ *
+ * Owns the browser WebSocket and multiplexes flattened Target sessions.
+ * Tracks inflight CDP calls, routes responses to the right session, and forwards events.
+ *
+ * This does not interpret Page/DOM/Runtime semantics — callers own that logic.
+ */
+interface CDPSessionLike {
+    send<R = unknown>(method: string, params?: object): Promise<R>;
+    on<P = unknown>(event: string, handler: (params: P) => void): void;
+    off<P = unknown>(event: string, handler: (params: P) => void): void;
+    close(): Promise<void>;
+    readonly id: string | null;
+}
+type EventHandler = (params: unknown) => void;
+declare class CdpConnection implements CDPSessionLike {
+    private ws;
+    private nextId;
+    private inflight;
+    private eventHandlers;
+    private sessions;
+    readonly id: string | null;
+    private transportCloseHandlers;
+    onTransportClosed(handler: (why: string) => void): void;
+    offTransportClosed(handler: (why: string) => void): void;
+    private emitTransportClosed;
+    private constructor();
+    static connect(wsUrl: string): Promise<CdpConnection>;
+    enableAutoAttach(): Promise<void>;
+    send<R = unknown>(method: string, params?: object): Promise<R>;
+    on<P = unknown>(event: string, handler: (params: P) => void): void;
+    off<P = unknown>(event: string, handler: (params: P) => void): void;
+    close(): Promise<void>;
+    getSession(sessionId: string): CdpSession | undefined;
+    attachToTarget(targetId: string): Promise<CdpSession>;
+    getTargets(): Promise<Array<{
+        targetId: string;
+        type: string;
+        url: string;
+    }>>;
+    private onMessage;
+    _sendViaSession<R = unknown>(sessionId: string, method: string, params?: object): Promise<R>;
+    _onSessionEvent(sessionId: string, event: string, handler: EventHandler): void;
+    _offSessionEvent(sessionId: string, event: string, handler: EventHandler): void;
+    _dispatchToSession(sessionId: string, event: string, params: unknown): void;
+}
+declare class CdpSession implements CDPSessionLike {
+    private readonly root;
+    readonly id: string;
+    constructor(root: CdpConnection, id: string);
+    send<R = unknown>(method: string, params?: object): Promise<R>;
+    on<P = unknown>(event: string, handler: (params: P) => void): void;
+    off<P = unknown>(event: string, handler: (params: P) => void): void;
+    close(): Promise<void>;
+    dispatch(event: string, params: unknown): void;
 }
 
-interface ConstructorParams {
+interface FrameManager {
+    session: CDPSessionLike;
+    frameId: string;
+    pageId: string;
+}
+/**
+ * Frame
+ *
+ * A thin, session-bound handle to a specific DOM frame (by frameId).
+ * All CDP calls in this class go through `this.session`, which MUST be the
+ * owning session for `this.frameId`. Page is responsible for constructing
+ * Frames with the correct session.
+ */
+declare class Frame implements FrameManager {
+    session: CDPSessionLike;
+    frameId: string;
+    pageId: string;
+    /** Owning CDP session id (useful for logs); null for root connection (should not happen for targets) */
+    readonly sessionId: string | null;
+    constructor(session: CDPSessionLike, frameId: string, pageId: string);
+    /** DOM.getNodeForLocation → DOM.describeNode */
+    getNodeAtLocation(x: number, y: number): Promise<Protocol.DOM.Node>;
+    /** CSS selector → DOM.querySelector → DOM.getBoxModel */
+    getLocationForSelector(selector: string): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    /** Accessibility.getFullAXTree (+ recurse into child frames if requested) */
+    getAccessibilityTree(withFrames?: boolean): Promise<Protocol.Accessibility.AXNode[]>;
     /**
-     * The environment to use for Stagehand
+     * Evaluate a function or expression in this frame's isolated world.
+     * - If a string is provided, treated as a JS expression.
+     * - If a function is provided, it is stringified and invoked with the optional argument.
      */
-    env: "LOCAL" | "BROWSERBASE";
+    evaluate<R = unknown, Arg = unknown>(pageFunctionOrExpression: string | ((arg: Arg) => R | Promise<R>), arg?: Arg): Promise<R>;
+    /** Page.captureScreenshot (frame-scoped session) */
+    screenshot(options?: {
+        fullPage?: boolean;
+        clip?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }): Promise<Buffer>;
+    /** Child frames via Page.getFrameTree */
+    childFrames(): Promise<Frame[]>;
+    /** Wait for a lifecycle state (load/domcontentloaded/networkidle) */
+    waitForLoadState(state?: "load" | "domcontentloaded" | "networkidle"): Promise<void>;
+    /** Simple placeholder for your own locator abstraction */
+    locator(selector: string, options?: {
+        deep?: boolean;
+        depth?: number;
+    }): Locator;
+    /** Create/get an isolated world for this frame and return its executionContextId */
+    private getExecutionContextId;
+}
+
+type MouseButton = "left" | "right" | "middle";
+/**
+ * Locator
+ *
+ * Purpose:
+ * A small, CDP-based element interaction helper scoped to a specific `Frame`.
+ * It resolves a CSS/XPath selector inside the frame’s **isolated world**, and then
+ * performs low-level actions (click, type, select) using DOM/Runtime/Input
+ * protocol domains with minimal abstraction.
+ *
+ * Key change:
+ * - Prefer **objectId**-based CDP calls (scroll, geometry) to avoid brittle
+ *   frontend nodeId mappings. nodeId is resolved on a best-effort basis and
+ *   returned for compatibility, but actions do not depend on it.
+ *
+ * Notes:
+ * - Resolution is lazy: every action resolves the selector again.
+ * - Uses `Page.createIsolatedWorld` so evaluation is isolated from page scripts.
+ * - Releases remote objects (`Runtime.releaseObject`) where appropriate.
+ */
+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;
     /**
-     * Your Browserbase API key
+     * Set files on an <input type="file"> element.
+     *
+     * Mirrors Playwright's Locator.setInputFiles basics:
+     * - Accepts file path(s) or payload object(s) { name, mimeType, buffer }.
+     * - Uses CDP DOM.setFileInputFiles under the hood.
+     * - Best‑effort dispatches change/input via CDP (Chrome does by default).
+     * - Passing an empty array clears the selection.
      */
-    apiKey?: string;
+    setInputFiles(files: string | string[] | {
+        name: string;
+        mimeType: string;
+        buffer: ArrayBuffer | Uint8Array | Buffer$1 | string;
+    } | Array<{
+        name: string;
+        mimeType: string;
+        buffer: ArrayBuffer | Uint8Array | Buffer$1 | string;
+    }>): Promise<void>;
     /**
-     * Your Browserbase project ID
+     * Return the DOM backendNodeId for this locator's target element.
+     * Useful for identity comparisons without needing element handles.
      */
-    projectId?: string;
+    backendNodeId(): Promise<Protocol.DOM.BackendNodeId>;
+    /** Return how many nodes the current selector resolves to. */
+    count(): Promise<number>;
     /**
-     * The verbosity of the Stagehand logger
-     * 0 - No logs
-     * 1 - Only errors
-     * 2 - All logs
+     * 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.
      */
-    verbose?: 0 | 1 | 2;
+    centroid(): Promise<{
+        x: number;
+        y: number;
+    }>;
     /**
-     * The LLM provider to use for Stagehand
-     * See
+     * Highlight the element's bounding box using the CDP Overlay domain.
+     * - Scrolls element into view best-effort.
+     * - Shows a semi-transparent overlay briefly, then hides it.
      */
-    llmProvider?: LLMProvider;
+    highlight(options?: {
+        durationMs?: number;
+        borderColor?: {
+            r: number;
+            g: number;
+            b: number;
+            a?: number;
+        };
+        contentColor?: {
+            r: number;
+            g: number;
+            b: number;
+            a?: number;
+        };
+    }): Promise<void>;
     /**
-     * The logger to use for Stagehand
+     * Move the mouse cursor to the element's visual center without clicking.
+     * - Scrolls into view best-effort, resolves geometry, then dispatches a mouse move.
      */
-    logger?: (message: LogLine) => void | Promise<void>;
+    hover(): Promise<void>;
     /**
-     * The timeout to use for the DOM to settle
-     * @default 10000
+     * Click the element at its visual center.
+     * Steps:
+     *  1) Resolve selector to { objectId } in the frame world.
+     *  2) Scroll into view via `DOM.scrollIntoViewIfNeeded({ objectId })`.
+     *  3) Read geometry via `DOM.getBoxModel({ objectId })` → compute a center point.
+     *  4) Synthesize mouse press + release via `Input.dispatchMouseEvent`.
      */
-    domSettleTimeoutMs?: number;
+    click(options?: {
+        button?: MouseButton;
+        clickCount?: number;
+    }): Promise<void>;
     /**
-     * The parameters to use for creating a Browserbase session
-     * See https://docs.browserbase.com/reference/api/create-a-session
-     * Note: projectId is optional here as it will use the main projectId parameter if not provided
+     * Dispatch a DOM 'click' MouseEvent on the element itself.
+     * - Does not synthesize real pointer input; directly dispatches an event.
+     * - Useful for elements that rely on click handlers without needing hit-testing.
      */
-    browserbaseSessionCreateParams?: Omit<Browserbase.Sessions.SessionCreateParams, "projectId"> & {
-        projectId?: string;
-    };
+    sendClickEvent(options?: {
+        bubbles?: boolean;
+        cancelable?: boolean;
+        composed?: boolean;
+        detail?: number;
+    }): Promise<void>;
     /**
-     * Enable caching of LLM responses
-     * @default true
+     * Scroll the element vertically to a given percentage (0–100).
+     * - If the element is <html> or <body>, scrolls the window/document.
+     * - Otherwise, scrolls the element itself via element.scrollTo.
      */
-    enableCaching?: boolean;
+    scrollTo(percent: number | string): Promise<void>;
     /**
-     * The ID of a Browserbase session to resume
+     * Fill an input/textarea/contenteditable element.
+     * 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.
      */
-    browserbaseSessionID?: string;
+    fill(value: string): Promise<void>;
     /**
-     * The model to use for Stagehand
+     * Type text into the element (focuses first).
+     * - Focus via element.focus() in page JS (no DOM.focus(nodeId)).
+     * - If no delay, uses `Input.insertText` for efficiency.
+     * - With delay, synthesizes `keyDown`/`keyUp` per character.
      */
-    modelName?: AvailableModel;
+    type(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
     /**
-     * The LLM client to use for Stagehand
+     * Select one or more options on a `<select>` element.
+     * Returns the values actually selected after the operation.
      */
-    llmClient?: LLMClient;
+    selectOption(values: string | string[]): Promise<string[]>;
     /**
-     * The parameters to use for the LLM client
-     * Useful for parameterizing LLM API Keys
+     * Return true if the element is attached and visible (rough heuristic).
      */
-    modelClientOptions?: ClientOptions;
+    isVisible(): Promise<boolean>;
     /**
-     * Customize the Stagehand system prompt
+     * Return true if the element is an input[type=checkbox|radio] and is checked.
+     * Also considers aria-checked for ARIA widgets.
      */
-    systemPrompt?: string;
+    isChecked(): Promise<boolean>;
     /**
-     * Offload Stagehand method calls to the Stagehand API.
-     * Must have a valid API key to use
+     * Return the element's input value (for input/textarea/select/contenteditable).
      */
-    useAPI?: boolean;
+    inputValue(): Promise<string>;
     /**
-     * Wait for captchas to be solved after navigation when using Browserbase environment.
-     *
-     * @default false
+     * Return the element's textContent (raw, not innerText).
      */
-    waitForCaptchaSolves?: boolean;
+    textContent(): Promise<string>;
     /**
-     * The parameters to use for launching a local browser
+     * Return the element's innerHTML string.
      */
-    localBrowserLaunchOptions?: LocalBrowserLaunchOptions;
+    innerHtml(): Promise<string>;
     /**
-     * Log the inference to a file
+     * Return the element's innerText (layout-aware, visible text).
      */
-    logInferenceToFile?: boolean;
-    selfHeal?: boolean;
+    innerText(): Promise<string>;
     /**
-     * Disable Pino (helpful for Next.js or test environments)
+     * For API parity, returns the same locator (querySelector already returns the first match).
      */
-    disablePino?: boolean;
+    first(): Locator;
+    /** Return a locator narrowed to the element at the given zero-based index. */
+    nth(index: number): Locator;
     /**
-     * Experimental Flag: Enables the latest experimental features
+     * Resolve `this.selector` within the frame to `{ objectId, nodeId? }`:
+     * Delegates to a shared selector resolver so all selector logic stays in sync.
      */
-    experimental?: boolean;
+    resolveNode(): Promise<{
+        nodeId: Protocol.DOM.NodeId | null;
+        objectId: Protocol.Runtime.RemoteObjectId;
+    }>;
+    /** Compute a center point from a BoxModel content quad */
+    private centerFromBoxContent;
 }
-interface InitResult {
-    debugUrl: string;
-    sessionUrl: string;
-    sessionId: string;
+
+/**
+ * DeepLocatorDelegate: a lightweight wrapper that looks like a Locator and
+ * resolves to the correct frame/element on each call using hop/deep-XPath logic.
+ *
+ * Returned by `page.deepLocator()` for ergonomic, await-free chaining:
+ *   page.deepLocator('iframe#ifrA >> #btn').click()
+ */
+declare class DeepLocatorDelegate {
+    private readonly page;
+    private readonly root;
+    private readonly selector;
+    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;
+    }): Promise<void>;
+    selectOption(values: string | string[]): Promise<string[]>;
+    scrollTo(percent: number | string): Promise<void>;
+    isVisible(): Promise<boolean>;
+    isChecked(): Promise<boolean>;
+    inputValue(): Promise<string>;
+    textContent(): Promise<string>;
+    innerHtml(): Promise<string>;
+    innerText(): Promise<string>;
+    centroid(): Promise<{
+        x: number;
+        y: number;
+    }>;
+    backendNodeId(): Promise<number>;
+    highlight(options?: {
+        durationMs?: number;
+        borderColor?: {
+            r: number;
+            g: number;
+            b: number;
+            a?: number;
+        };
+        contentColor?: {
+            r: number;
+            g: number;
+            b: number;
+            a?: number;
+        };
+    }): Promise<void>;
+    sendClickEvent(options?: {
+        bubbles?: boolean;
+        cancelable?: boolean;
+        composed?: boolean;
+        detail?: number;
+    }): Promise<void>;
+    setInputFiles(files: string | string[] | {
+        name: string;
+        mimeType: string;
+        buffer: ArrayBuffer | Uint8Array | Buffer | string;
+    } | Array<{
+        name: string;
+        mimeType: string;
+        buffer: ArrayBuffer | Uint8Array | Buffer | string;
+    }>): Promise<void>;
+    first(): DeepLocatorDelegate;
+    nth(index: number): DeepLocatorDelegate;
 }
-interface ActOptions {
-    action: string;
-    modelName?: AvailableModel;
-    modelClientOptions?: ClientOptions;
-    variables?: Record<string, string>;
-    domSettleTimeoutMs?: number;
-    timeoutMs?: number;
-    iframes?: boolean;
-    frameId?: string;
+
+/**
+ * FrameLocator: resolves iframe elements to their child Frames and allows
+ * creating locators scoped to that frame. Supports chaining.
+ */
+declare class FrameLocator {
+    private readonly parent?;
+    private readonly selector;
+    private readonly page;
+    private readonly root?;
+    constructor(page: Page, selector: string, parent?: FrameLocator, root?: Frame);
+    /** Create a nested FrameLocator under this one. */
+    frameLocator(selector: string): FrameLocator;
+    /** Resolve to the concrete Frame for this FrameLocator chain. */
+    resolveFrame(): Promise<Frame>;
+    /** Return a Locator scoped to this frame. Methods delegate to the frame lazily. */
+    locator(selector: string): LocatorDelegate;
+}
+/** A small delegating wrapper that resolves the frame lazily per call. */
+declare class LocatorDelegate {
+    private readonly fl;
+    private readonly sel;
+    constructor(fl: FrameLocator, sel: string);
+    private real;
+    click(options?: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+    }): Promise<void>;
+    hover(): Promise<void>;
+    fill(value: string): Promise<void>;
+    type(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    selectOption(values: string | string[]): Promise<string[]>;
+    scrollTo(percent: number | string): Promise<void>;
+    isVisible(): Promise<boolean>;
+    isChecked(): Promise<boolean>;
+    inputValue(): Promise<string>;
+    textContent(): Promise<string>;
+    innerHtml(): Promise<string>;
+    innerText(): Promise<string>;
+    count(): Promise<number>;
+    first(): LocatorDelegate;
 }
-interface ActResult {
-    success: boolean;
-    message: string;
-    action: string;
+
+type AnyPage = Page$1 | Page$2 | Page$3 | Page;
+type LoadState = "load" | "domcontentloaded" | "networkidle";
+
+declare class StagehandAPIClient {
+    private apiKey;
+    private projectId;
+    private sessionId?;
+    private modelApiKey;
+    private logger;
+    private fetchWithCookies;
+    constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams);
+    init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, systemPrompt, selfHeal, browserbaseSessionCreateParams, browserbaseSessionID, }: StartSessionParams): Promise<StartSessionResult>;
+    act({ input, options, frameId }: APIActParameters): Promise<ActResult>;
+    extract<T extends z.AnyZodObject>({ instruction, schema: zodSchema, options, frameId, }: APIExtractParameters): Promise<ExtractResult<T>>;
+    observe({ instruction, options, frameId, }: APIObserveParameters): Promise<Action[]>;
+    goto(url: string, options?: {
+        waitUntil?: "load" | "domcontentloaded" | "networkidle";
+    }, frameId?: string): Promise<void>;
+    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions | string, frameId?: string): Promise<AgentResult>;
+    end(): Promise<Response>;
+    private execute;
+    private request;
 }
-interface ExtractOptions<T extends z.AnyZodObject> {
-    instruction?: string;
-    schema?: T;
-    modelName?: AvailableModel;
-    modelClientOptions?: ClientOptions;
-    domSettleTimeoutMs?: number;
+
+declare class Page {
+    private readonly conn;
+    private readonly mainSession;
+    private readonly _targetId;
+    /** Every CDP child session this page owns (top-level + adopted OOPIF sessions). */
+    private readonly sessions;
+    /** Unified truth for frame topology + ownership. */
+    private readonly registry;
+    /** A convenience wrapper bound to the current main frame id (top-level session). */
+    private mainFrameWrapper;
+    /** Compact ordinal per frameId (used by snapshot encoding). */
+    private frameOrdinals;
+    private nextOrdinal;
+    /** cache Frames per frameId so everyone uses the same one */
+    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 navigationCommandSeq;
+    private latestNavigationCommandId;
+    private readonly networkManager;
+    /** Optional API client for routing page operations to the API */
+    private readonly apiClient;
+    private constructor();
+    private cursorEnabled;
+    private ensureCursorScript;
+    enableCursorOverlay(): Promise<void>;
+    private updateCursor;
     /**
-     * @deprecated The `useTextExtract` parameter has no effect in this version of Stagehand and will be removed in later versions.
+     * Factory: create Page and seed registry with the shallow tree from Page.getFrameTree.
+     * Assumes Page domain is already enabled on the session passed in.
      */
-    useTextExtract?: boolean;
-    selector?: string;
-    iframes?: boolean;
-    frameId?: string;
-}
-type ExtractResult<T extends z.AnyZodObject> = z.infer<T>;
-interface ObserveOptions {
-    instruction?: string;
-    modelName?: AvailableModel;
-    modelClientOptions?: ClientOptions;
-    domSettleTimeoutMs?: number;
-    returnAction?: boolean;
+    static create(conn: CdpConnection, session: CDPSessionLike, targetId: string, apiClient?: StagehandAPIClient | null, localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null): Promise<Page>;
     /**
-     * @deprecated The `onlyVisible` parameter has no effect in this version of Stagehand and will be removed in later versions.
+     * Parent/child session emitted a `frameAttached`.
+     * Topology update + ownership stamped to **emitting session**.
      */
-    onlyVisible?: boolean;
-    drawOverlay?: boolean;
-    iframes?: boolean;
-    frameId?: string;
-}
-interface ObserveResult$1 {
-    selector: string;
-    description: string;
-    backendNodeId?: number;
-    method?: string;
-    arguments?: string[];
-}
-interface LocalBrowserLaunchOptions {
-    args?: string[];
-    chromiumSandbox?: boolean;
-    devtools?: boolean;
-    env?: {
-        [key: string]: string | undefined;
-    };
-    executablePath?: string;
-    handleSIGHUP?: boolean;
-    handleSIGINT?: boolean;
-    handleSIGTERM?: boolean;
-    headless?: boolean;
-    ignoreDefaultArgs?: boolean | Array<string>;
-    proxy?: {
-        server: string;
-        bypass?: string;
-        username?: string;
-        password?: string;
-    };
-    tracesDir?: string;
-    userDataDir?: string;
-    preserveUserDataDir?: boolean;
-    acceptDownloads?: boolean;
-    downloadsPath?: string;
-    extraHTTPHeaders?: Record<string, string>;
-    geolocation?: {
-        latitude: number;
-        longitude: number;
-        accuracy?: number;
-    };
-    hasTouch?: boolean;
-    ignoreHTTPSErrors?: boolean;
-    locale?: string;
-    permissions?: Array<string>;
-    recordHar?: {
-        omitContent?: boolean;
-        content?: "omit" | "embed" | "attach";
-        path: string;
-        mode?: "full" | "minimal";
-        urlFilter?: string | RegExp;
-    };
-    recordVideo?: {
-        dir: string;
-        size?: {
-            width: number;
-            height: number;
-        };
-    };
-    viewport?: {
-        width: number;
-        height: number;
-    };
-    deviceScaleFactor?: number;
-    timezoneId?: string;
-    bypassCSP?: boolean;
-    cookies?: Cookie[];
-    cdpUrl?: string;
-}
-interface StagehandMetrics {
-    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;
-}
-/**
- * Options for executing a task with an agent
- */
-interface AgentExecuteParams {
+    onFrameAttached(frameId: string, parentId: string | null, session: CDPSessionLike): void;
     /**
-     * The instruction to execute with the agent
+     * Parent/child session emitted a `frameDetached`.
      */
-    instruction: string;
+    onFrameDetached(frameId: string, reason?: "remove" | "swap" | string): void;
     /**
-     * Maximum number of steps the agent can take to complete the task
-     * @default 10
+     * Parent/child session emitted a `frameNavigated`.
+     * Topology + ownership update. Handles root swaps.
      */
-    maxSteps?: number;
+    onFrameNavigated(frame: Protocol.Page.Frame, session: CDPSessionLike): void;
+    onNavigatedWithinDocument(frameId: string, url: string, session: CDPSessionLike): void;
     /**
-     * Take a screenshot automatically before each agent step
-     * @default true
+     * 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.
      */
-    autoScreenshot?: boolean;
+    adoptOopifSession(childSession: CDPSessionLike, childMainFrameId: string): void;
+    /** Detach an adopted child session and prune its subtree */
+    detachOopifSession(sessionId: string): void;
+    /** Return the owning CDP session for a frameId (falls back to main session) */
+    getSessionForFrame(frameId: string): CDPSessionLike;
+    /** Always returns a Frame bound to the owning session */
+    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;
     /**
-     * Wait time in milliseconds between agent actions
-     * @default 0
+     * Close this top-level page (tab). Best-effort via Target.closeTarget.
      */
-    waitBetweenActions?: number;
+    close(): Promise<void>;
+    getFullFrameTree(): Protocol.Page.FrameTree;
+    asProtocolFrameTree(rootMainFrameId: string): Protocol.Page.FrameTree;
+    private ensureOrdinal;
+    /** Public getter for snapshot code / handlers. */
+    getOrdinal(frameId: string): number;
+    listAllFrameIds(): string[];
     /**
-     * Additional context to provide to the agent
+     * Navigate the page; optionally wait for a lifecycle state.
+     * Waits on the **current** main frame and follows root swaps during navigation.
      */
-    context?: string;
-}
-/**
- * Configuration for agent functionality
- */
-interface AgentConfig {
+    goto(url: string, options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+    }): Promise<void>;
     /**
-     * The provider to use for agent functionality
+     * Reload the page; optionally wait for a lifecycle state.
      */
-    provider?: AgentProviderType;
+    reload(options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+        ignoreCache?: boolean;
+    }): Promise<void>;
     /**
-     * The model to use for agent functionality
+     * Navigate back in history if possible; optionally wait for a lifecycle state.
      */
-    model?: string;
+    goBack(options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+    }): Promise<void>;
     /**
-     * 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")
+     * Navigate forward in history if possible; optionally wait for a lifecycle state.
      */
-    executionModel?: string;
+    goForward(options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+    }): Promise<void>;
     /**
-     * Custom instructions to provide to the agent
+     * Return the current page URL (synchronous, cached from navigation events).
      */
-    instructions?: string;
+    url(): string;
+    private beginNavigationCommand;
+    isCurrentNavigationCommand(id: number): boolean;
     /**
-     * Additional options to pass to the agent client
+     * Return the current page title.
+     * Prefers reading from the active document via Runtime.evaluate to reflect dynamic changes.
+     * Falls back to navigation history title if evaluation is unavailable.
      */
-    options?: Record<string, unknown>;
+    title(): Promise<string>;
     /**
-     * MCP integrations - Array of Client objects
+     * Capture a screenshot (delegated to the current main frame).
      */
-    integrations?: (Client | string)[];
+    screenshot(options?: {
+        fullPage?: boolean;
+    }): Promise<Buffer>;
     /**
-     * Tools passed to the agent client
+     * Create a locator bound to the current main frame.
      */
-    tools?: ToolSet;
-}
-declare enum StagehandFunctionName {
-    ACT = "ACT",
-    EXTRACT = "EXTRACT",
-    OBSERVE = "OBSERVE",
-    AGENT = "AGENT"
-}
-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 {
+    locator(selector: string): ReturnType<Frame["locator"]>;
     /**
-     * The ordered list of keys/indices leading from the schema root
-     * to the targeted field.
+     * Deep locator that supports cross-iframe traversal.
+     * - Recognizes '>>' hop notation to enter iframe contexts.
+     * - Supports deep XPath that includes iframe steps (e.g., '/html/body/iframe[2]//div').
+     * Returns a Locator scoped to the appropriate frame.
      */
-    segments: Array<string | number>;
-}
-
-interface ActToolResult {
-    success: boolean;
-    action?: string;
-    error?: string;
-    isIframe?: boolean;
-    playwrightArguments?: ObserveResult$1 | null;
-}
-interface AgentAction$1 {
-    type: string;
-    reasoning?: string;
-    taskCompleted?: boolean;
-    action?: string;
-    timeMs?: number;
-    pageText?: string;
-    timestamp?: number;
-    pageUrl?: string;
-    instruction?: string;
-    playwrightArguments?: ObserveResult$1 | null;
-    [key: string]: unknown;
-}
-interface AgentResult$1 {
-    success: boolean;
-    message: string;
-    actions: AgentAction$1[];
-    completed: boolean;
-    metadata?: Record<string, unknown>;
-    usage?: {
-        input_tokens: number;
-        output_tokens: number;
-        inference_time_ms: number;
-    };
-}
-interface AgentOptions$1 {
-    maxSteps?: number;
-    autoScreenshot?: boolean;
-    waitBetweenActions?: number;
-    context?: string;
-    highlightCursor?: boolean;
-}
-interface AgentExecuteOptions$1 extends AgentOptions$1 {
-    instruction: string;
+    deepLocator(selector: string): DeepLocatorDelegate;
+    /**
+     * Frame locator similar to Playwright: targets iframe elements and scopes
+     * subsequent locators to that frame. Supports chaining.
+     */
+    frameLocator(selector: string): FrameLocator;
+    /**
+     * List all frames belonging to this page as Frame objects bound to their owning sessions.
+     * The list is ordered by a stable ordinal assigned during the page lifetime.
+     */
+    frames(): Frame[];
+    /**
+     * Wait until the page reaches a lifecycle state on the current main frame.
+     * Mirrors Playwright's API signatures.
+     */
+    waitForLoadState(state: LoadState, timeoutMs?: number): Promise<void>;
+    /**
+     * Evaluate a function or expression in the current main frame's isolated world.
+     * - If a string is provided, it is treated as a JS expression.
+     * - If a function is provided, it is stringified and invoked with the optional argument.
+     * - The return value should be JSON-serializable. Non-serializable objects will
+     *   best-effort serialize via JSON.stringify inside the page context.
+     */
+    evaluate<R = unknown, Arg = unknown>(pageFunctionOrExpression: string | ((arg: Arg) => R | Promise<R>), arg?: Arg): Promise<R>;
+    /**
+     * Force the page viewport to an exact CSS size and device scale factor.
+     * Ensures screenshots match width x height pixels when deviceScaleFactor = 1.
+     */
+    setViewportSize(width: number, height: number, options?: {
+        deviceScaleFactor?: number;
+    }): Promise<void>;
+    /**
+     * Click at absolute page coordinates (CSS pixels).
+     * Dispatches mouseMoved → mousePressed → mouseReleased via CDP Input domain
+     * on the top-level page target's session. Coordinates are relative to the
+     * viewport origin (top-left). Does not scroll.
+     */
+    click(x: number, y: number, options: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+        returnXpath: true;
+    }): Promise<string>;
+    click(x: number, y: number, options?: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+        returnXpath?: false;
+    }): Promise<void>;
+    click(x: number, y: number, options: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+        returnXpath: boolean;
+    }): Promise<void | string>;
+    scroll(x: number, y: number, deltaX: number, deltaY: number, options: {
+        returnXpath: true;
+    }): Promise<string>;
+    scroll(x: number, y: number, deltaX: number, deltaY: number, options?: {
+        returnXpath?: false;
+    }): Promise<void>;
+    scroll(x: number, y: number, deltaX: number, deltaY: number, options: {
+        returnXpath: boolean;
+    }): Promise<void | string>;
+    /**
+     * Drag from (fromX, fromY) to (toX, toY) using mouse events.
+     * Sends mouseMoved → mousePressed → mouseMoved (steps) → mouseReleased.
+     */
+    dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options: {
+        button?: "left" | "right" | "middle";
+        steps?: number;
+        delay?: number;
+        returnXpath: true;
+    }): Promise<[string, string]>;
+    dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options?: {
+        button?: "left" | "right" | "middle";
+        steps?: number;
+        delay?: number;
+        returnXpath?: false;
+    }): Promise<void>;
+    dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options: {
+        button?: "left" | "right" | "middle";
+        steps?: number;
+        delay?: number;
+        returnXpath: boolean;
+    }): Promise<void | [string, string]>;
+    /**
+     * Type a string by dispatching keyDown/keyUp events per character.
+     * Focus must already be on the desired element. Uses CDP Input.dispatchKeyEvent
+     * and never falls back to Input.insertText. Optional delay applies between
+     * successive characters.
+     */
+    type(text: string, options?: {
+        delay?: number;
+        withMistakes?: boolean;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    private createIsolatedWorldForCurrentMain;
+    /**
+     * Wait until the **current** main frame reaches a lifecycle state.
+     * - Fast path via `document.readyState`.
+     * - Event path listens at the session level and compares incoming `frameId`
+     *   to `mainFrameId()` **at event time** to follow root swaps.
+     */
+    waitForMainLoadState(state: LoadState, timeoutMs?: number): Promise<void>;
 }
-type AgentProviderType = "openai" | "anthropic" | "google";
-interface AgentClientOptions {
-    apiKey: string;
-    organization?: string;
-    baseURL?: string;
-    defaultMaxSteps?: number;
+
+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 AgentExecuteOptions {
+    instruction: string;
+    maxSteps?: number;
+    page?: Page$1 | Page$2 | Page$3 | Page;
+    highlightCursor?: boolean;
+}
 type AgentType = "openai" | "anthropic" | "google";
-interface AgentExecutionOptions {
-    options: AgentExecuteOptions$1;
+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;
 }
@@ -553,7 +917,6 @@ interface AgentHandlerOptions {
     modelName: string;
     clientOptions?: Record<string, unknown>;
     userProvidedInstructions?: string;
-    agentType: AgentType;
     experimental?: boolean;
 }
 interface ActionExecutionResult {
@@ -632,276 +995,40 @@ type ResponseInputItem = {
     output: string;
 };
 interface AgentInstance {
-    execute: (instructionOrOptions: string | AgentExecuteOptions$1) => Promise<AgentResult$1>;
-    setScreenshotCollector?: (collector: unknown) => void;
+    execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
 }
-
-declare const defaultExtractSchema: z.ZodObject<{
-    extraction: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    extraction?: string;
-}, {
-    extraction?: string;
-}>;
-declare const pageTextSchema: z.ZodObject<{
-    page_text: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    page_text?: string;
-}, {
-    page_text?: string;
-}>;
-interface StagehandScreenshotOptions extends PageScreenshotOptions {
-    /** Controls whether to use CDP for screenshots in Browserbase environment. Defaults to true. */
-    useCDP?: boolean;
-}
-interface Page extends Omit<Page$1, "on" | "screenshot"> {
-    act(action: string): Promise<ActResult>;
-    act(options: ActOptions): Promise<ActResult>;
-    act(observation: ObserveResult$1): Promise<ActResult>;
-    extract(instruction: string): Promise<ExtractResult<typeof defaultExtractSchema>>;
-    extract<T extends z.AnyZodObject>(options: ExtractOptions<T>): Promise<ExtractResult<T>>;
-    extract(): Promise<ExtractResult<typeof pageTextSchema>>;
-    observe(): Promise<ObserveResult$1[]>;
-    observe(instruction: string): Promise<ObserveResult$1[]>;
-    observe(options?: ObserveOptions): Promise<ObserveResult$1[]>;
-    screenshot(options?: StagehandScreenshotOptions): Promise<Buffer>;
-    on: {
-        (event: "popup", listener: (page: Page) => unknown): Page;
-    } & Page$1["on"];
-}
-type BrowserContext = BrowserContext$1;
-type Browser = Browser$1;
-
-interface EnhancedContext extends Omit<BrowserContext$1, "newPage" | "pages"> {
-    newPage(): Promise<Page>;
-    pages(): Page[];
-}
-type EncodedId = `${number}-${number}`;
-
-interface StagehandAPIConstructorParams {
-    apiKey: string;
-    projectId: string;
-    logger: (message: LogLine) => void;
-}
-interface StartSessionParams {
-    modelName: string;
-    modelApiKey: string;
-    domSettleTimeoutMs: number;
-    verbose: number;
-    debugDom: boolean;
+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;
-    browserbaseSessionCreateParams?: Omit<Browserbase.Sessions.SessionCreateParams, "projectId"> & {
-        projectId?: string;
-    };
-    selfHeal?: boolean;
-    waitForCaptchaSolves?: boolean;
-    actionTimeoutMs?: number;
-    browserbaseSessionID?: string;
-}
-interface StartSessionResult {
-    sessionId: string;
-    available?: boolean;
-}
-
-interface ObserveResult {
-    selector: string;
-    description: string;
-    backendNodeId?: number;
-    method?: string;
-    arguments?: string[];
-}
-interface AgentAction {
-    type: string;
-    reasoning?: string;
-    taskCompleted?: boolean;
-    action?: string;
-    timeMs?: number;
-    pageText?: string;
-    timestamp?: number;
-    pageUrl?: string;
-    instruction?: string;
-    playwrightArguments?: ObserveResult | null;
-    [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;
-    highlightCursor?: boolean;
-}
-interface AgentExecuteOptions extends AgentOptions {
-    instruction: string;
-}
-
-declare class StagehandAPI {
-    private apiKey;
-    private projectId;
-    private sessionId?;
-    private modelApiKey;
-    private logger;
-    private fetchWithCookies;
-    constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams);
-    init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, debugDom, systemPrompt, selfHeal, waitForCaptchaSolves, actionTimeoutMs, browserbaseSessionCreateParams, browserbaseSessionID, }: StartSessionParams): Promise<StartSessionResult>;
-    act(options: ActOptions | ObserveResult$1): Promise<ActResult>;
-    extract<T extends z.AnyZodObject>(options: ExtractOptions<T>): Promise<ExtractResult<T>>;
-    observe(options?: ObserveOptions): Promise<ObserveResult$1[]>;
-    goto(url: string, options?: GotoOptions): Promise<void>;
-    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions): Promise<AgentResult>;
-    end(): Promise<Response>;
-    private execute;
-    private request;
-}
-
-declare class StagehandContext {
-    private readonly stagehand;
-    private readonly intContext;
-    private pageMap;
-    private activeStagehandPage;
-    private readonly frameIdMap;
-    private constructor();
-    private createStagehandPage;
-    static init(context: BrowserContext$1, stagehand: Stagehand): Promise<StagehandContext>;
-    get frameIdLookup(): ReadonlyMap<string, StagehandPage>;
-    registerFrameId(frameId: string, page: StagehandPage): void;
-    unregisterFrameId(frameId: string): void;
-    getStagehandPageByFrameId(frameId: string): StagehandPage | undefined;
-    get context(): EnhancedContext;
-    getStagehandPage(page: Page$1): Promise<StagehandPage>;
-    getStagehandPages(): Promise<StagehandPage[]>;
-    setActivePage(page: StagehandPage): void;
-    getActivePage(): StagehandPage | null;
-    private handleNewPlaywrightPage;
-    private attachFrameNavigatedListener;
-}
-
-declare class StagehandPage {
-    private stagehand;
-    private rawPage;
-    private intPage;
-    private intContext;
-    private actHandler;
-    private extractHandler;
-    private observeHandler;
-    private llmClient;
-    private cdpClient;
-    private api;
-    private userProvidedInstructions?;
-    private waitForCaptchaSolves;
-    private initialized;
-    private readonly cdpClients;
-    private fidOrdinals;
-    private rootFrameId;
-    get frameId(): string;
-    updateRootFrameId(newId: string): void;
-    constructor(page: Page$1, stagehand: Stagehand, context: StagehandContext, llmClient: LLMClient, userProvidedInstructions?: string, api?: StagehandAPI, waitForCaptchaSolves?: boolean);
-    ordinalForFrameId(fid: string | undefined): number;
-    encodeWithFrameId(fid: string | undefined, backendId: number): EncodedId;
-    resetFrameOrdinals(): void;
-    private ensureStagehandScript;
-    /** Register the custom selector engine that pierces open/closed shadow roots. */
-    private ensureStagehandSelectorEngine;
-    /**
-     * Waits for a captcha to be solved when using Browserbase environment.
-     *
-     * @param timeoutMs - Optional timeout in milliseconds. If provided, the promise will reject if the captcha solving hasn't started within the given time.
-     * @throws StagehandEnvironmentError if called in a LOCAL environment
-     * @throws CaptchaTimeoutError if the timeout is reached before captcha solving starts
-     * @returns Promise that resolves when the captcha is solved
-     */
-    waitForCaptchaSolve(timeoutMs?: number): Promise<void>;
-    init(): Promise<StagehandPage>;
-    get page(): Page;
-    get context(): EnhancedContext;
-    /**
-     * `_waitForSettledDom` waits until the DOM is settled, and therefore is
-     * ready for actions to be taken.
-     *
-     * **Definition of "settled"**
-     *   • No in-flight network requests (except WebSocket / Server-Sent-Events).
-     *   • That idle state lasts for at least **500 ms** (the "quiet-window").
-     *
-     * **How it works**
-     *   1.  Subscribes to CDP Network and Page events for the main target and all
-     *       out-of-process iframes (via `Target.setAutoAttach { flatten:true }`).
-     *   2.  Every time `Network.requestWillBeSent` fires, the request ID is added
-     *       to an **`inflight`** `Set`.
-     *   3.  When the request finishes—`loadingFinished`, `loadingFailed`,
-     *       `requestServedFromCache`, or a *data:* response—the request ID is
-     *       removed.
-     *   4.  *Document* requests are also mapped **frameId → requestId**; when
-     *       `Page.frameStoppedLoading` fires the corresponding Document request is
-     *       removed immediately (covers iframes whose network events never close).
-     *   5.  A **stalled-request sweep timer** runs every 500 ms.  If a *Document*
-     *       request has been open for ≥ 2 s it is forcibly removed; this prevents
-     *       ad/analytics iframes from blocking the wait forever.
-     *   6.  When `inflight` becomes empty the helper starts a 500 ms timer.
-     *       If no new request appears before the timer fires, the promise
-     *       resolves → **DOM is considered settled**.
-     *   7.  A global guard (`timeoutMs` or `stagehand.domSettleTimeoutMs`,
-     *       default ≈ 30 s) ensures we always resolve; if it fires we log how many
-     *       requests were still outstanding.
-     *
-     * @param timeoutMs – Optional hard cap (ms).  Defaults to
-     *                    `this.stagehand.domSettleTimeoutMs`.
+    /**
+     * MCP integrations - Array of Client objects
      */
-    _waitForSettledDom(timeoutMs?: number): Promise<void>;
-    act(actionOrOptions: string | ActOptions | ObserveResult$1): Promise<ActResult>;
-    extract<T extends z.AnyZodObject = typeof defaultExtractSchema>(instructionOrOptions?: string | ExtractOptions<T>): Promise<ExtractResult<T>>;
-    observe(instructionOrOptions?: string | ObserveOptions): Promise<ObserveResult$1[]>;
+    integrations?: (Client | string)[];
     /**
-     * Get or create a CDP session for the given target.
-     * @param target  The Page or (OOPIF) Frame you want to talk to.
+     * Tools passed to the agent client
      */
-    getCDPClient(target?: Page$1 | Frame): Promise<CDPSession>;
+    tools?: ToolSet;
     /**
-     * Send a CDP command to the chosen DevTools target.
-     *
-     * @param method  Any valid CDP method, e.g. `"DOM.getDocument"`.
-     * @param params  Command parameters (optional).
-     * @param target  A `Page` or OOPIF `Frame`. Defaults to the main page.
-     *
-     * @typeParam T  Expected result shape (defaults to `unknown`).
+     * Indicates CUA is disabled for this configuration
      */
-    sendCDP<T = unknown>(method: string, params?: Record<string, unknown>, target?: Page$1 | Frame): Promise<T>;
-    /** Enable a CDP domain (e.g. `"Network"` or `"DOM"`) on the chosen target. */
-    enableCDP(domain: string, target?: Page$1 | Frame): Promise<void>;
-    /** Disable a CDP domain on the chosen target. */
-    disableCDP(domain: string, target?: Page$1 | Frame): Promise<void>;
-}
-
-interface ConnectToMCPServerOptions {
-    serverUrl: string | URL;
-    clientOptions?: ClientOptions$3;
-}
-interface StdioServerConfig {
-    command: string;
-    args?: string[];
-    env?: Record<string, string>;
-}
-declare const connectToMCPServer: (serverConfig: string | URL | StdioServerConfig | ConnectToMCPServerOptions) => Promise<Client$1>;
-
-interface BrowserResult {
-    env: "LOCAL" | "BROWSERBASE";
-    browser?: Browser;
-    context: BrowserContext;
-    debugUrl?: string;
-    sessionUrl?: string;
-    contextPath?: string;
-    sessionId?: string;
-}
+    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);
@@ -922,6 +1049,144 @@ 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$1.AnyZodObject> = z$1.infer<T>;
+interface Action {
+    selector: string;
+    description: string;
+    method?: string;
+    arguments?: string[];
+}
+interface HistoryEntry {
+    method: "act" | "extract" | "observe" | "navigate" | "agent";
+    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$1.ZodObject<{
+    extraction: z$1.ZodString;
+}, "strip", z$1.ZodTypeAny, {
+    extraction?: string;
+}, {
+    extraction?: string;
+}>;
+declare const pageTextSchema: z$1.ZodObject<{
+    pageText: z$1.ZodString;
+}, "strip", z$1.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 StagehandMetrics {
+    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;
+    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;
+    /** Directory used to persist cached actions for act(). */
+    cacheDir?: string;
+    domSettleTimeout?: number;
+    disableAPI?: boolean;
+}
+
 declare class StagehandError extends Error {
     constructor(message: string);
 }
@@ -1026,178 +1291,529 @@ declare class StagehandShadowSegmentNotFoundError extends StagehandError {
     constructor(segment: string, hint?: string);
 }
 
-interface CacheEntry {
-    timestamp: number;
-    data: unknown;
-    requestId: string;
-}
-interface CacheStore {
-    [key: string]: CacheEntry;
-}
-declare class BaseCache<T extends CacheEntry> {
-    private readonly CACHE_MAX_AGE_MS;
-    private readonly CLEANUP_PROBABILITY;
-    protected cacheDir: string;
-    protected cacheFile: string;
-    protected lockFile: string;
-    protected logger: (message: LogLine) => void;
-    private readonly LOCK_TIMEOUT_MS;
-    protected lockAcquired: boolean;
-    protected lockAcquireFailures: number;
-    protected requestIdToUsedHashes: {
-        [key: string]: string[];
+interface StagehandAPIConstructorParams {
+    apiKey: string;
+    projectId: string;
+    logger: (message: LogLine) => void;
+}
+interface StartSessionParams {
+    modelName: string;
+    modelApiKey: string;
+    domSettleTimeoutMs: number;
+    verbose: number;
+    systemPrompt?: string;
+    browserbaseSessionCreateParams?: Omit<Browserbase.Sessions.SessionCreateParams, "projectId"> & {
+        projectId?: string;
     };
-    constructor(logger: (message: LogLine) => void, cacheDir?: string, cacheFile?: string);
-    private setupProcessHandlers;
-    protected ensureCacheDirectory(): void;
-    protected createHash(data: unknown): string;
-    protected sleep(ms: number): Promise<void>;
-    acquireLock(): Promise<boolean>;
-    releaseLock(): void;
+    selfHeal?: boolean;
+    browserbaseSessionID?: string;
+}
+interface StartSessionResult {
+    sessionId: string;
+    available?: boolean;
+}
+interface APIActParameters {
+    input: string | Action;
+    options?: ActOptions;
+    frameId?: string;
+}
+interface APIExtractParameters {
+    instruction?: string;
+    schema?: ZodTypeAny;
+    options?: ExtractOptions;
+    frameId?: string;
+}
+interface APIObserveParameters {
+    instruction?: string;
+    options?: ObserveOptions;
+    frameId?: 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 {
     /**
-     * Cleans up stale cache entries that exceed the maximum age.
+     * The ordered list of keys/indices leading from the schema root
+     * to the targeted field.
      */
-    cleanupStaleEntries(): Promise<void>;
-    protected readCache(): CacheStore;
-    protected writeCache(cache: CacheStore): void;
+    segments: Array<string | number>;
+}
+
+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 {
     /**
-     * Retrieves data from the cache based on the provided options.
-     * @param hashObj - The options used to generate the cache key.
-     * @param requestId - The identifier for the current request.
-     * @returns The cached data if available, otherwise null.
+     * The evaluation result ('YES', 'NO', or 'INVALID' if parsing failed or value was unexpected)
      */
-    get(hashObj: Record<string, unknown> | string, requestId: string): Promise<T["data"] | null>;
+    evaluation: "YES" | "NO" | "INVALID";
     /**
-     * Stores data in the cache based on the provided options and requestId.
-     * @param hashObj - The options used to generate the cache key.
-     * @param data - The data to be cached.
-     * @param requestId - The identifier for the cache entry.
+     * The reasoning behind the evaluation
      */
-    set(hashObj: Record<string, unknown>, data: T["data"], requestId: string): Promise<void>;
-    delete(hashObj: Record<string, unknown>): Promise<void>;
+    reasoning: string;
+}
+
+/**
+ * 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 env;
+    private readonly apiClient;
+    private readonly localBrowserLaunchOptions;
+    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;
     /**
-     * Tracks the usage of a hash with a specific requestId.
-     * @param requestId - The identifier for the current request.
-     * @param hash - The cache key hash.
+     * Create a Context for a given CDP websocket URL and bootstrap target wiring.
      */
-    protected trackRequestIdUsage(requestId: string, hash: string): void;
+    static create(wsUrl: string, opts?: {
+        env?: "LOCAL" | "BROWSERBASE";
+        apiClient?: StagehandAPIClient | null;
+        localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null;
+    }): Promise<V3Context>;
     /**
-     * Deletes all cache entries associated with a specific requestId.
-     * @param requestId - The identifier for the request whose cache entries should be deleted.
+     * Wait until at least one top-level Page has been created and registered.
+     * We poll internal maps that bootstrap/onAttachedToTarget populate.
      */
-    deleteCacheForRequestId(requestId: string): Promise<void>;
+    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;
     /**
-     * Resets the entire cache by clearing the cache file.
+     * Return top-level `Page`s (oldest → newest). OOPIF targets are not included.
      */
-    resetCache(): void;
-}
-
-declare class LLMCache extends BaseCache<CacheEntry> {
-    constructor(logger: (message: {
-        category?: string;
-        message: string;
-        level?: number;
-    }) => void, cacheDir?: string, cacheFile?: string);
+    pages(): Page[];
     /**
-     * Overrides the get method to track used hashes by requestId.
-     * @param options - The options used to generate the cache key.
-     * @param requestId - The identifier for the current request.
-     * @returns The cached data if available, otherwise null.
+     * Resolve an owning `Page` by the **top-level main frame id**.
+     * Note: child (OOPIF) roots are intentionally not present in this mapping.
      */
-    get<T>(options: Record<string, unknown>, requestId: string): Promise<T | null>;
+    resolvePageByMainFrameId(frameId: string): Page | undefined;
     /**
-     * Overrides the set method to include cache cleanup logic.
-     * @param options - The options used to generate the cache key.
-     * @param data - The data to be cached.
-     * @param requestId - The identifier for the current request.
+     * Serialize the full frame tree for a given top-level main frame id.
      */
-    set(options: Record<string, unknown>, data: unknown, requestId: string): Promise<void>;
+    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>;
 }
 
-declare class AISdkClient extends LLMClient {
-    type: "aisdk";
-    private model;
-    private logger?;
-    private cache;
-    private enableCaching;
-    constructor({ model, logger, enableCaching, cache, }: {
-        model: LanguageModel;
-        logger?: (message: LogLine) => void;
-        enableCaching?: boolean;
-        cache?: LLMCache;
-    });
-    getLanguageModel(): LanguageModel;
-    createChatCompletion<T = ChatCompletion>({ options, }: CreateChatCompletionOptions): Promise<T>;
+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;
 }
-
-declare class Stagehand {
-    private stagehandPage;
-    private stagehandContext;
-    browserbaseSessionID?: string;
-    readonly domSettleTimeoutMs: number;
-    readonly debugDom: boolean;
-    readonly headless: boolean;
-    verbose: 0 | 1 | 2;
-    llmProvider: LLMProvider;
-    enableCaching: boolean;
-    protected apiKey: string | undefined;
-    private projectId;
-    private externalLogger?;
-    private browserbaseSessionCreateParams?;
-    variables: {
-        [key: string]: unknown;
+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;
     };
-    private contextPath?;
+}
+interface AgentReplayWaitStep {
+    type: "wait";
+    timeMs: number;
+}
+interface AgentReplayNavBackStep {
+    type: "navback";
+    waitUntil?: LoadState;
+}
+
+/**
+ * V3
+ *
+ * Purpose:
+ * A high-level orchestrator for Stagehand V3. Abstracts away whether the browser
+ * runs **locally via Chrome** or remotely on **Browserbase**, and exposes simple
+ * entrypoints (`act`, `extract`, `observe`) that delegate to the corresponding
+ * handler classes.
+ *
+ * Responsibilities:
+ * - Bootstraps Chrome or Browserbase, ensures a working CDP WebSocket, and builds a `V3Context`.
+ * - Manages lifecycle: init, context access, cleanup.
+ * - Bridges external page objects (Playwright/Puppeteer) into internal frameIds for handlers.
+ * - Provides a stable API surface for downstream code regardless of runtime environment.
+ */
+declare class V3 {
+    private readonly opts;
+    private state;
+    private actHandler;
+    private extractHandler;
+    private observeHandler;
+    private ctx;
     llmClient: LLMClient;
-    readonly userProvidedInstructions?: string;
-    private usingAPI;
     private modelName;
-    apiClient: StagehandAPI | undefined;
-    readonly waitForCaptchaSolves: boolean;
-    private localBrowserLaunchOptions?;
-    readonly selfHeal: boolean;
-    private cleanupCalled;
-    readonly actTimeoutMs: number;
-    readonly logInferenceToFile?: boolean;
+    private modelClientOptions;
+    private llmProvider;
+    private overrideLlmClients;
+    private readonly domSettleTimeoutMs?;
+    private _isClosing;
+    browserbaseSessionId?: string;
+    private _onCdpClosed;
+    readonly experimental: boolean;
+    readonly logInferenceToFile: boolean;
+    readonly disableAPI: boolean;
+    private externalLogger?;
+    verbose: 0 | 1 | 2;
     private stagehandLogger;
-    private disablePino;
-    protected modelClientOptions: ClientOptions;
-    private _env;
-    private _browser;
-    private _isClosed;
     private _history;
-    readonly experimental: boolean;
-    private _livePageProxy?;
-    private createLivePageProxy;
-    get history(): ReadonlyArray<HistoryEntry>;
-    protected setActivePage(page: StagehandPage): void;
-    get page(): Page;
+    private readonly instanceId;
+    private static _processGuardsInstalled;
+    private static _instances;
+    private cacheStorage;
+    private actCache;
+    private agentCache;
+    private apiClient;
     stagehandMetrics: StagehandMetrics;
-    get metrics(): StagehandMetrics;
-    get isClosed(): boolean;
-    updateMetrics(functionName: StagehandFunctionName, promptTokens: number, completionTokens: number, inferenceTimeMs: number): void;
+    constructor(opts: V3Options);
+    /**
+     * Async property for metrics so callers can `await v3.metrics`.
+     * Returning a Promise future-proofs async aggregation/storage.
+     */
+    get metrics(): Promise<StagehandMetrics>;
+    private resolveLlmClient;
+    private beginAgentReplayRecording;
+    private endAgentReplayRecording;
+    private discardAgentReplayRecording;
+    private isAgentReplayRecording;
+    isAgentReplayActive(): boolean;
+    recordAgentReplayStep(step: AgentReplayStep): void;
+    /**
+     * Async property for history so callers can `await v3.history`.
+     * Returns a frozen copy to avoid external mutation.
+     */
+    get history(): Promise<ReadonlyArray<HistoryEntry>>;
+    addToHistory(method: HistoryEntry["method"], parameters: unknown, result?: unknown): void;
+    updateMetrics(functionName: V3FunctionName, promptTokens: number, completionTokens: number, inferenceTimeMs: number): void;
     private updateTotalMetrics;
-    constructor({ env, apiKey, projectId, verbose, llmProvider, llmClient, logger, browserbaseSessionCreateParams, domSettleTimeoutMs, enableCaching, browserbaseSessionID, modelName, modelClientOptions, systemPrompt, useAPI, localBrowserLaunchOptions, waitForCaptchaSolves, logInferenceToFile, selfHeal, disablePino, experimental, }?: ConstructorParams);
-    private registerSignalHandlers;
+    private _immediateShutdown;
+    private static _installProcessGuards;
+    /**
+     * Entrypoint: initializes handlers, launches Chrome or Browserbase,
+     * and sets up a CDP context.
+     */
+    init(): Promise<void>;
+    /** Apply post-connect local browser options that require CDP. */
+    private _applyPostConnectLocalOptions;
+    private _ensureBrowserbaseDownloadsEnabled;
+    /**
+     * Run an "act" instruction through the ActHandler.
+     *
+     * New API:
+     * - act(instruction: string, options?: ActOptions)
+     * - act(action: Action, options?: ActOptions)
+     */
+    act(instruction: string, options?: ActOptions): Promise<ActResult>;
+    act(action: Action, options?: ActOptions): Promise<ActResult>;
+    /**
+     * Run an "extract" instruction through the ExtractHandler.
+     *
+     * Accepted forms:
+     * - extract() → pageText
+     * - extract(options) → pageText
+     * - extract(instruction) → defaultExtractSchema
+     * - extract(instruction, schema) → schema-inferred
+     * - extract(instruction, schema, options)
+     */
+    extract(): Promise<z$1.infer<typeof pageTextSchema>>;
+    extract(options: ExtractOptions): Promise<z$1.infer<typeof pageTextSchema>>;
+    extract(instruction: string, options?: ExtractOptions): Promise<z$1.infer<typeof defaultExtractSchema>>;
+    extract<T extends ZodTypeAny>(instruction: string, schema: T, options?: ExtractOptions): Promise<z$1.infer<T>>;
+    /**
+     * Run an "observe" instruction through the ObserveHandler.
+     */
+    observe(): 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. */
+    get context(): V3Context;
+    /** Best-effort cleanup of context and launched resources. */
+    close(opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    /** Guard: ensure Browserbase credentials exist in options. */
+    private requireBrowserbaseCreds;
     get logger(): (logLine: LogLine) => void;
-    get env(): "LOCAL" | "BROWSERBASE";
-    get downloadsPath(): string;
-    get context(): EnhancedContext;
-    init(): Promise<InitResult>;
-    log(logObj: LogLine): void;
-    close(): Promise<void>;
-    addToHistory(method: HistoryEntry["method"], parameters: ActOptions | ExtractOptions<z.AnyZodObject> | ObserveOptions | {
-        url: string;
-        options: GotoOptions;
-    } | string, result?: unknown): void;
     /**
-     * Create an agent instance that can be executed with different instructions
-     * @returns An agent instance with execute() method
+     * Normalize a Playwright/Puppeteer page object into its top frame id,
+     * so handlers can resolve it to a `Page` within our V3Context.
+     */
+    private resolveTopFrameId;
+    private isPlaywrightPage;
+    private isPatchrightPage;
+    private isPuppeteerPage;
+    /** Resolve an external page reference or fall back to the active V3 page. */
+    private resolvePage;
+    private normalizeToV3Page;
+    /**
+     * Create a v3 agent instance (AISDK tool-based) with execute().
+     * Mirrors the v2 Stagehand.agent() tool mode (no CUA provider here).
      */
     agent(options?: AgentConfig): {
-        execute: (instructionOrOptions: string | AgentExecuteOptions$1) => Promise<AgentResult$1>;
-        setScreenshotCollector?: (collector: unknown) => void;
+        execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
     };
 }
 
-export { AISdkClient, type ActOptions, type ActResult, type ActToolResult, type ActionExecutionResult, type AgentAction$1 as AgentAction, type AgentClientOptions, type AgentConfig, type AgentExecuteOptions$1 as AgentExecuteOptions, type AgentExecuteParams, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentOptions$1 as AgentOptions, type AgentProviderType, type AgentResult$1 as AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AvailableModel, AvailableModelSchema, type Browser, type BrowserContext, type BrowserResult, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, type ConstructorParams, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, type GotoOptions, HandlerNotInitializedError, type HistoryEntry, type InitResult, InvalidAISDKModelFormatError, LLMClient, type LLMResponse, LLMResponseError, LOG_LEVEL_NAMES, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelProvider, type ObserveOptions, type ObserveResult$1 as ObserveResult, type Page, PlaywrightCommandException, PlaywrightCommandMethodNotSupportedException, type ResponseInputItem, type ResponseItem, Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandFunctionName, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, type StagehandScreenshotOptions, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, XPathResolutionError, type ZodPathSegments, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, pageTextSchema };
+/**
+ * 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;
+}
+
+declare function validateZodSchema(schema: z$1.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$1.ZodTypeAny): Schema;
+declare function getZodType(schema: z$1.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$1.ZodTypeAny, currentPath: Array<string | number>): [z$1.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 | Array<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;
+}
+interface StdioServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+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 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, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, XPathResolutionError, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, jsonSchemaToZod, loadApiKeyFromEnv, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, transformSchema, trimTrailingTextNode, validateZodSchema };