@browserbasehq/orca 3.0.3-zod-1 → 3.0.6-alpha-1

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 import { ZodTypeAny, z, ZodObject, ZodRawShape, ZodError } from 'zod';
 import * as z3 from 'zod/v3';
 import { ClientOptions as ClientOptions$2 } from '@anthropic-ai/sdk';
+import { GoogleVertexProviderSettings as GoogleVertexProviderSettings$1 } from '@ai-sdk/google-vertex';
 import { LanguageModelV2 } from '@ai-sdk/provider';
 import { ClientOptions as ClientOptions$1 } from 'openai';
-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 { ToolSet, ModelMessage, PrepareStepFunction, GenerateTextOnStepFinishCallback, StreamTextOnStepFinishCallback, StreamTextOnErrorCallback, StreamTextOnChunkCallback, StreamTextOnFinishCallback, StepResult, StreamTextResult, wrapLanguageModel, generateObject, generateText, streamText, streamObject, experimental_generateImage, embed, embedMany, experimental_transcribe, experimental_generateSpeech } from 'ai';
+export { ModelMessage } from 'ai';
 import { Page as Page$1 } from 'playwright-core';
 export { Page as PlaywrightPage } from 'playwright-core';
 import { Page as Page$2 } from 'puppeteer-core';
@@ -28,33 +30,6 @@ declare const isZod3Schema: (schema: StagehandZodSchema) => schema is z3.ZodType
 type JsonSchemaDocument = Record<string, unknown>;
 declare function toJsonSchema(schema: StagehandZodSchema): JsonSchemaDocument;
 
-type AnthropicJsonSchemaObject = {
-    definitions?: {
-        MySchema?: {
-            properties?: Record<string, unknown>;
-            required?: string[];
-        };
-    };
-    properties?: Record<string, unknown>;
-    required?: string[];
-} & Record<string, unknown>;
-interface LLMTool {
-    type: "function";
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-}
-type AISDKProvider = (modelName: string) => LanguageModelV2;
-type AISDKCustomProvider = (options: {
-    apiKey: string;
-}) => AISDKProvider;
-type AvailableModel = "gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "o4-mini" | "o3" | "o3-mini" | "o1" | "o1-mini" | "gpt-4o" | "gpt-4o-mini" | "gpt-4o-2024-08-06" | "gpt-4.5-preview" | "o1-preview" | "claude-3-5-sonnet-latest" | "claude-3-5-sonnet-20241022" | "claude-3-5-sonnet-20240620" | "claude-3-7-sonnet-latest" | "claude-3-7-sonnet-20250219" | "cerebras-llama-3.3-70b" | "cerebras-llama-3.1-8b" | "groq-llama-3.3-70b-versatile" | "groq-llama-3.3-70b-specdec" | "gemini-1.5-flash" | "gemini-1.5-pro" | "gemini-1.5-flash-8b" | "gemini-2.0-flash-lite" | "gemini-2.0-flash" | "gemini-2.5-flash-preview-04-17" | "gemini-2.5-pro-preview-03-25" | string;
-type ModelProvider = "openai" | "anthropic" | "cerebras" | "groq" | "google" | "aisdk";
-type ClientOptions = ClientOptions$1 | ClientOptions$2;
-type ModelConfiguration = AvailableModel | (ClientOptions & {
-    modelName: AvailableModel;
-});
-
 type LogLevel = 0 | 1 | 2;
 /**
  * Mapping between numeric log levels and their names
@@ -79,122 +54,6 @@ type LogLine = {
 };
 type Logger = (logLine: LogLine) => void;
 
-interface ChatMessage {
-    role: "system" | "user" | "assistant";
-    content: ChatMessageContent;
-}
-type ChatMessageContent = string | (ChatMessageImageContent | ChatMessageTextContent)[];
-interface ChatMessageImageContent {
-    type: string;
-    image_url?: {
-        url: string;
-    };
-    text?: string;
-    source?: {
-        type: string;
-        media_type: string;
-        data: string;
-    };
-}
-interface ChatMessageTextContent {
-    type: string;
-    text: string;
-}
-declare const AnnotatedScreenshotText = "This is a screenshot of the current page state with the elements annotated on it. Each element id is annotated with a number to the top left of it. Duplicate annotations at the same location are under each other vertically.";
-interface ChatCompletionOptions {
-    messages: ChatMessage[];
-    temperature?: number;
-    top_p?: number;
-    frequency_penalty?: number;
-    presence_penalty?: number;
-    image?: {
-        buffer: Buffer;
-        description?: string;
-    };
-    response_model?: {
-        name: string;
-        schema: StagehandZodSchema;
-    };
-    tools?: LLMTool[];
-    tool_choice?: "auto" | "none" | "required";
-    maxOutputTokens?: number;
-    requestId?: string;
-}
-type LLMResponse = {
-    id: string;
-    object: string;
-    created: number;
-    model: string;
-    choices: {
-        index: number;
-        message: {
-            role: string;
-            content: string | null;
-            tool_calls: {
-                id: string;
-                type: string;
-                function: {
-                    name: string;
-                    arguments: string;
-                };
-            }[];
-        };
-        finish_reason: string;
-    }[];
-    usage: {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-    };
-};
-interface CreateChatCompletionOptions {
-    options: ChatCompletionOptions;
-    logger: (message: LogLine) => void;
-    retries?: number;
-}
-/** Simple usage shape if your LLM returns usage tokens. */
-interface LLMUsage {
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
-    reasoning_tokens?: number;
-    cached_input_tokens?: number;
-}
-/**
- * For calls that use a schema: the LLMClient may return { data: T; usage?: LLMUsage }
- */
-interface LLMParsedResponse<T> {
-    data: T;
-    usage?: LLMUsage;
-}
-declare abstract class LLMClient {
-    type: "openai" | "anthropic" | "cerebras" | "groq" | (string & {});
-    modelName: AvailableModel | (string & {});
-    hasVision: boolean;
-    clientOptions: ClientOptions;
-    userProvidedInstructions?: string;
-    constructor(modelName: AvailableModel, userProvidedInstructions?: string);
-    abstract createChatCompletion<T>(options: CreateChatCompletionOptions & {
-        options: {
-            response_model: {
-                name: string;
-                schema: StagehandZodSchema;
-            };
-        };
-    }): Promise<LLMParsedResponse<T>>;
-    abstract createChatCompletion<T = LLMResponse>(options: CreateChatCompletionOptions): Promise<T>;
-    generateObject: typeof generateObject;
-    generateText: typeof generateText;
-    streamText: typeof streamText;
-    streamObject: typeof streamObject;
-    generateImage: typeof experimental_generateImage;
-    embed: typeof embed;
-    embedMany: typeof embedMany;
-    transcribe: typeof experimental_transcribe;
-    generateSpeech: typeof experimental_generateSpeech;
-    getLanguageModel?(): LanguageModelV2;
-}
-
 /**
  * CDP transport & session multiplexer
  *
@@ -217,8 +76,22 @@ declare class CdpConnection implements CDPSessionLike {
     private inflight;
     private eventHandlers;
     private sessions;
+    /** Maps sessionId -> targetId (1:1 mapping) */
+    private sessionToTarget;
     readonly id: string | null;
     private transportCloseHandlers;
+    /** Optional CDP logger - set this to receive all outgoing CDP method calls */
+    cdpLogger?: (info: {
+        method: string;
+        params?: object;
+        targetId?: string | null;
+    }) => void;
+    /** Optional CDP event logger - set this to receive all incoming CDP events */
+    cdpEventLogger?: (info: {
+        method: string;
+        params?: unknown;
+        targetId?: string | null;
+    }) => void;
     onTransportClosed(handler: (why: string) => void): void;
     offTransportClosed(handler: (why: string) => void): void;
     private emitTransportClosed;
@@ -284,7 +157,7 @@ declare class Frame implements FrameManager {
     /** Accessibility.getFullAXTree (+ recurse into child frames if requested) */
     getAccessibilityTree(withFrames?: boolean): Promise<Protocol.Accessibility.AXNode[]>;
     /**
-     * Evaluate a function or expression in this frame's isolated world.
+     * Evaluate a function or expression in this frame's main 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.
      */
@@ -305,14 +178,14 @@ declare class Frame implements FrameManager {
     /** Child frames via Page.getFrameTree */
     childFrames(): Promise<Frame[]>;
     /** Wait for a lifecycle state (load/domcontentloaded/networkidle) */
-    waitForLoadState(state?: "load" | "domcontentloaded" | "networkidle"): Promise<void>;
+    waitForLoadState(state?: "load" | "domcontentloaded" | "networkidle", timeoutMs?: number): 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;
+    /** Resolve the main-world execution context id for this frame. */
+    private getMainWorldExecutionContextId;
 }
 
 interface SetInputFilePayload {
@@ -643,1242 +516,1661 @@ declare class ConsoleMessage {
     toString(): string;
 }
 
-/**
- * Response
- * -----------------
- *
- * This module implements a Playwright-inspired response wrapper that exposes
- * navigation metadata and helpers for retrieving HTTP response bodies. The
- * abstraction is consumed by navigation routines (e.g. `Page.goto`) so callers
- * can synchronously inspect status codes, lazily fetch body text, or await the
- * network layer finishing the request. The implementation is built directly on
- * Chrome DevTools Protocol primitives – it holds the originating `requestId`
- * so it can request payloads via `Network.getResponseBody`, and it listens for
- * `responseReceivedExtraInfo`, `loadingFinished`, and `loadingFailed` events to
- * hydrate the richer header view and resolve callers waiting on completion.
- */
+declare class StagehandAPIError extends Error {
+    constructor(message: string);
+}
+declare class StagehandAPIUnauthorizedError extends StagehandAPIError {
+    constructor(message?: string);
+}
+declare class StagehandHttpError extends StagehandAPIError {
+    constructor(message: string);
+}
+declare class StagehandServerError extends StagehandAPIError {
+    constructor(message: string);
+}
+declare class StagehandResponseBodyError extends StagehandAPIError {
+    constructor();
+}
+declare class StagehandResponseParseError extends StagehandAPIError {
+    constructor(message: string);
+}
 
-type ServerAddr = {
-    ipAddress: string;
-    port: number;
-};
-/**
- * Thin wrapper around CDP response metadata that mirrors the ergonomics of
- * Playwright's `Response` class. The class intentionally keeps the same method
- * names so upstream integrations can transition with minimal code changes.
- */
-declare class Response$1 {
-    private readonly page;
-    private readonly session;
-    private readonly requestId;
-    private readonly frameId?;
-    private readonly loaderId?;
-    private readonly response;
-    private readonly fromServiceWorkerFlag;
-    private readonly serverAddress?;
-    private headersObject;
-    private headersArrayCache;
-    private allHeadersCache;
-    private readonly headerValuesMap;
-    private finishedDeferred;
-    private finishedSettled;
-    private extraInfoHeaders;
-    private extraInfoHeadersText;
-    /**
-     * Build a response wrapper from the CDP notification associated with a
-     * navigation. The constructor captures the owning page/session so follow-up
-     * methods (body/text/json) can query CDP on-demand. The `response` payload is
-     * the raw `Protocol.Network.Response` object emitted by Chrome.
-     */
-    constructor(params: {
-        page: Page;
-        session: CDPSessionLike;
-        requestId: string;
-        frameId?: string;
-        loaderId?: string;
-        response: Protocol.Network.Response;
-        fromServiceWorker: boolean;
-    });
-    /** URL associated with the navigation request. */
-    url(): string;
-    /** HTTP status code reported by Chrome. */
-    status(): number;
-    /** Human-readable status text that accompanied the response. */
-    statusText(): string;
-    /** Convenience predicate that checks for 2xx statuses. */
-    ok(): boolean;
-    /** Returns the Stagehand frame object that initiated the navigation. */
-    frame(): Frame | null;
-    /** Indicates whether the response was serviced by a Service Worker. */
-    fromServiceWorker(): boolean;
-    /**
-     * Returns TLS security metadata when provided by the browser. In practice
-     * this includes certificate issuer, protocol, and validity interval.
-     */
-    securityDetails(): Promise<Protocol.Network.SecurityDetails | null>;
-    /** Returns the resolved server address for the navigation when available. */
-    serverAddr(): Promise<ServerAddr | null>;
-    /**
-     * Returns the response headers normalised to lowercase keys. Matches the
-     * behaviour of Playwright's `headers()` by eliding duplicate header entries.
-     */
-    headers(): Record<string, string>;
-    /**
-     * Returns all headers including those only surfaced through
-     * `responseReceivedExtraInfo` such as `set-cookie`. Values are reported as the
-     * browser sends them (no further splitting or concatenation).
-     */
-    allHeaders(): Promise<Record<string, string>>;
-    /** Returns a concatenated header string for the supplied header name. */
-    headerValue(name: string): Promise<string | null>;
-    /** Returns all values for a header (case-insensitive lookup). */
-    headerValues(name: string): Promise<string[]>;
-    /**
-     * Returns header entries preserving their original wire casing and ordering.
-     * Falls back to the CDP object when the raw header text is unavailable.
-     */
-    headersArray(): Promise<Array<{
-        name: string;
-        value: string;
-    }>>;
-    /**
-     * Requests the raw response body from Chrome DevTools Protocol. The method is
-     * intentionally lazy because not every caller needs the payload, and CDP only
-     * allows retrieving it once the response completes.
-     */
-    body(): Promise<Buffer>;
-    /** Decodes the response body as UTF-8 text. */
-    text(): Promise<string>;
-    /** Parses the response body as JSON and throws if parsing fails. */
-    json<T = unknown>(): Promise<T>;
-    /**
-     * Resolves once the underlying network request completes or fails. Mirrors
-     * Playwright's behaviour by resolving to `null` on success and to an `Error`
-     * instance when Chrome reports `Network.loadingFailed`.
-     */
-    finished(): Promise<null | Error>;
-    /**
-     * Internal helper invoked by the navigation tracker when CDP reports extra
-     * header information. This keeps the cached header views in sync with the
-     * richer metadata.
-     */
-    applyExtraInfo(event: Protocol.Network.ResponseReceivedExtraInfoEvent): void;
-    /**
-     * Internal helper for creating a Response object from a Serializable
-     * goto response from the Stagehand API
-     */
-    static fromSerializable(serialized: SerializableResponse, context: {
-        page: Page;
-        session: CDPSessionLike;
-    }): Response$1;
-    /** Marks the response as finished and resolves the `finished()` promise. */
-    markFinished(error: Error | null): void;
+interface ActOptions {
+    model?: ModelConfiguration;
+    variables?: Record<string, string>;
+    timeout?: number;
+    page?: Page$1 | Page$2 | Page$3 | Page;
 }
-
-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 StagehandZodSchema>({ 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<SerializableResponse | null>;
-    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions | string, frameId?: string): Promise<AgentResult>;
-    end(): Promise<Response>;
-    getReplayMetrics(): Promise<StagehandMetrics>;
-    private execute;
-    private request;
+interface ActResult {
+    success: boolean;
+    message: string;
+    actionDescription: string;
+    actions: Action[];
 }
-
-type ScreenshotAnimationsOption = "disabled" | "allow";
-type ScreenshotCaretOption = "hide" | "initial";
-type ScreenshotScaleOption = "css" | "device";
-interface ScreenshotClip {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
+type ExtractResult<T extends StagehandZodSchema> = InferStagehandSchema<T>;
+interface Action {
+    selector: string;
+    description: string;
+    method?: string;
+    arguments?: string[];
 }
-interface ScreenshotOptions {
-    animations?: ScreenshotAnimationsOption;
-    caret?: ScreenshotCaretOption;
-    clip?: ScreenshotClip;
-    fullPage?: boolean;
-    mask?: Locator[];
-    maskColor?: string;
-    omitBackground?: boolean;
-    path?: string;
-    quality?: number;
-    scale?: ScreenshotScaleOption;
-    style?: string;
+interface HistoryEntry {
+    method: "act" | "extract" | "observe" | "navigate" | "agent";
+    parameters: unknown;
+    result: unknown;
+    timestamp: string;
+}
+interface ExtractOptions {
+    model?: ModelConfiguration;
     timeout?: number;
-    type?: "png" | "jpeg";
+    selector?: string;
+    page?: Page$1 | Page$2 | Page$3 | Page;
+}
+declare const defaultExtractSchema: z.ZodObject<{
+    extraction: z.ZodString;
+}, z.core.$strip>;
+declare const pageTextSchema: z.ZodObject<{
+    pageText: z.ZodString;
+}, z.core.$strip>;
+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"
 }
 
-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;
-    private readonly browserIsRemote;
-    /** 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 readonly consoleListeners;
-    private readonly consoleHandlers;
-    private constructor();
-    private cursorEnabled;
-    private ensureCursorScript;
-    enableCursorOverlay(): Promise<void>;
-    private updateCursor;
-    /**
-     * Factory: create Page and seed registry with the shallow tree from Page.getFrameTree.
-     * Assumes Page domain is already enabled on the session passed in.
-     */
-    static create(conn: CdpConnection, session: CDPSessionLike, targetId: string, apiClient?: StagehandAPIClient | null, localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null, browserIsRemote?: boolean): Promise<Page>;
-    /**
-     * Parent/child session emitted a `frameAttached`.
-     * Topology update + ownership stamped to **emitting session**.
-     */
-    onFrameAttached(frameId: string, parentId: string | null, session: CDPSessionLike): void;
-    /**
-     * Parent/child session emitted a `frameDetached`.
-     */
-    onFrameDetached(frameId: string, reason?: "remove" | "swap" | string): void;
-    /**
-     * Parent/child session emitted a `frameNavigated`.
-     * Topology + ownership update. Handles root swaps.
-     */
-    onFrameNavigated(frame: Protocol.Page.Frame, session: CDPSessionLike): void;
-    onNavigatedWithinDocument(frameId: string, url: string, session: CDPSessionLike): void;
+interface StagehandMetrics {
+    actPromptTokens: number;
+    actCompletionTokens: number;
+    actReasoningTokens: number;
+    actCachedInputTokens: number;
+    actInferenceTimeMs: number;
+    extractPromptTokens: number;
+    extractCompletionTokens: number;
+    extractReasoningTokens: number;
+    extractCachedInputTokens: number;
+    extractInferenceTimeMs: number;
+    observePromptTokens: number;
+    observeCompletionTokens: number;
+    observeReasoningTokens: number;
+    observeCachedInputTokens: number;
+    observeInferenceTimeMs: number;
+    agentPromptTokens: number;
+    agentCompletionTokens: number;
+    agentReasoningTokens: number;
+    agentCachedInputTokens: number;
+    agentInferenceTimeMs: number;
+    totalPromptTokens: number;
+    totalCompletionTokens: number;
+    totalReasoningTokens: number;
+    totalCachedInputTokens: 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;
     /**
-     * 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.
+     * Optional: fine-tune Browserbase session creation or resume an existing session.
      */
-    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;
-    on(event: "console", listener: ConsoleListener): Page;
-    once(event: "console", listener: ConsoleListener): Page;
-    off(event: "console", listener: ConsoleListener): Page;
-    targetId(): string;
+    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);
+}
+declare class StagehandDefaultError extends StagehandError {
+    constructor(error?: unknown);
+}
+declare class StagehandEnvironmentError extends StagehandError {
+    constructor(currentEnvironment: string, requiredEnvironment: string, feature: string);
+}
+declare class MissingEnvironmentVariableError extends StagehandError {
+    constructor(missingEnvironmentVariable: string, feature: string);
+}
+declare class UnsupportedModelError extends StagehandError {
+    constructor(supportedModels: string[], feature?: string);
+}
+declare class UnsupportedModelProviderError extends StagehandError {
+    constructor(supportedProviders: string[], feature?: string);
+}
+declare class UnsupportedAISDKModelProviderError extends StagehandError {
+    constructor(provider: string, supportedProviders: string[]);
+}
+declare class InvalidAISDKModelFormatError extends StagehandError {
+    constructor(modelName: string);
+}
+declare class StagehandNotInitializedError extends StagehandError {
+    constructor(prop: string);
+}
+declare class BrowserbaseSessionNotFoundError extends StagehandError {
+    constructor();
+}
+declare class CaptchaTimeoutError extends StagehandError {
+    constructor();
+}
+declare class MissingLLMConfigurationError extends StagehandError {
+    constructor();
+}
+declare class HandlerNotInitializedError extends StagehandError {
+    constructor(handlerType: string);
+}
+declare class StagehandInvalidArgumentError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandElementNotFoundError extends StagehandError {
+    constructor(xpaths: string[]);
+}
+declare class AgentScreenshotProviderError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandMissingArgumentError extends StagehandError {
+    constructor(message: string);
+}
+declare class CreateChatCompletionResponseError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandEvalError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandDomProcessError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandClickError extends StagehandError {
+    constructor(message: string, selector: string);
+}
+declare class LLMResponseError extends StagehandError {
+    constructor(primitive: string, message: string);
+}
+declare class StagehandIframeError extends StagehandError {
+    constructor(frameUrl: string, message: string);
+}
+declare class ContentFrameNotFoundError extends StagehandError {
+    constructor(selector: string);
+}
+declare class XPathResolutionError extends StagehandError {
+    constructor(xpath: string);
+}
+declare class ExperimentalApiConflictError extends StagehandError {
+    constructor();
+}
+declare class ExperimentalNotConfiguredError extends StagehandError {
+    constructor(featureName: string);
+}
+declare class CuaModelRequiredError extends StagehandError {
+    constructor(availableModels: readonly string[]);
+}
+declare class ZodSchemaValidationError extends Error {
+    readonly received: unknown;
+    readonly issues: ReturnType<ZodError["format"]>;
+    constructor(received: unknown, issues: ReturnType<ZodError["format"]>);
+}
+declare class StagehandInitError extends StagehandError {
+    constructor(message: string);
+}
+declare class MCPConnectionError extends StagehandError {
+    readonly serverUrl: string;
+    readonly originalError: unknown;
+    constructor(serverUrl: string, originalError: unknown);
+}
+declare class StagehandShadowRootMissingError extends StagehandError {
+    constructor(detail?: string);
+}
+declare class StagehandShadowSegmentEmptyError extends StagehandError {
+    constructor();
+}
+declare class StagehandShadowSegmentNotFoundError extends StagehandError {
+    constructor(segment: string, hint?: string);
+}
+declare class ElementNotVisibleError extends StagehandError {
+    constructor(selector: string);
+}
+declare class ResponseBodyError extends StagehandError {
+    constructor(message: string);
+}
+declare class ResponseParseError extends StagehandError {
+    constructor(message: string);
+}
+declare class TimeoutError extends StagehandError {
+    constructor(operation: string, timeoutMs: number);
+}
+declare class ActTimeoutError extends TimeoutError {
+    constructor(timeoutMs: number);
+}
+declare class ExtractTimeoutError extends TimeoutError {
+    constructor(timeoutMs: number);
+}
+declare class ObserveTimeoutError extends TimeoutError {
+    constructor(timeoutMs: number);
+}
+declare class PageNotFoundError extends StagehandError {
+    constructor(identifier: string);
+}
+declare class ConnectionTimeoutError extends StagehandError {
+    constructor(message: string);
+}
+declare class StreamingCallbacksInNonStreamingModeError extends StagehandError {
+    readonly invalidCallbacks: string[];
+    constructor(invalidCallbacks: string[]);
+}
+declare class AgentAbortError extends StagehandError {
+    readonly reason: string;
+    constructor(reason?: string);
+}
+
+declare class AISdkClient extends LLMClient {
+    type: "aisdk";
+    private model;
+    constructor({ model }: {
+        model: LanguageModelV2;
+    });
+    createChatCompletion<T = ChatCompletion>({ options, }: CreateChatCompletionOptions): Promise<T>;
+}
+
+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;
+    };
+    selfHeal?: boolean;
+    browserbaseSessionID?: string;
+}
+interface StartSessionResult {
+    sessionId: string;
+    available?: boolean;
+}
+interface APIActParameters {
+    input: string | Action;
+    options?: ActOptions;
+    frameId?: string;
+}
+interface APIExtractParameters {
+    instruction?: string;
+    schema?: StagehandZodSchema;
+    options?: ExtractOptions;
+    frameId?: string;
+}
+interface APIObserveParameters {
+    instruction?: string;
+    options?: ObserveOptions;
+    frameId?: string;
+}
+interface SerializableResponse {
+    requestId: string;
+    frameId?: string;
+    loaderId?: string;
+    response: Protocol.Network.Response;
+    fromServiceWorkerFlag?: boolean;
+    finishedSettled?: boolean;
+    extraInfoHeaders?: Protocol.Network.Headers | null;
+    extraInfoHeadersText?: 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 {
+    /**
+     * The ordered list of keys/indices leading from the schema root
+     * to the targeted field.
+     */
+    segments: Array<string | number>;
+}
+type InitScriptSource<Arg> = string | {
+    path?: string;
+    content?: string;
+} | ((arg: Arg) => unknown);
+
+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 {
     /**
-     * Send a CDP command through the main session.
-     * Allows external consumers to execute arbitrary Chrome DevTools Protocol commands.
-     *
-     * @param method - The CDP method name (e.g., "Page.enable", "Runtime.evaluate")
-     * @param params - Optional parameters for the CDP command
-     * @returns Promise resolving to the typed CDP response
-     *
-     * @example
-     * // Enable the Runtime domain
-     * await page.sendCDP("Runtime.enable");
-     *
-     * @example
-     * // Evaluate JavaScript with typed response
-     * const result = await page.sendCDP<Protocol.Runtime.EvaluateResponse>(
-     *   "Runtime.evaluate",
-     *   { expression: "1 + 1" }
-     * );
+     * The evaluation result ('YES', 'NO', or 'INVALID' if parsing failed or value was unexpected)
      */
-    sendCDP<T = unknown>(method: string, params?: object): Promise<T>;
-    /** Seed the cached URL before navigation events converge. */
-    seedCurrentUrl(url: string | undefined | null): void;
-    mainFrameId(): string;
-    mainFrame(): Frame;
+    evaluation: "YES" | "NO" | "INVALID";
     /**
-     * Close this top-level page (tab). Best-effort via Target.closeTarget.
+     * The reasoning behind the evaluation
      */
-    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[];
-    private ensureConsoleTaps;
-    private installConsoleTap;
+    reasoning: string;
+}
+
+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 StagehandZodSchema>({ 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<SerializableResponse | null>;
+    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions | string, frameId?: string): Promise<AgentResult>;
+    end(): Promise<Response>;
+    getReplayMetrics(): Promise<StagehandMetrics>;
+    private execute;
+    private request;
+}
+
+/**
+ * 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 resolveSessionByKey;
-    private teardownConsoleTap;
-    private removeAllConsoleTaps;
-    private emitConsole;
+    private readonly _sessionInit;
+    private pagesByTarget;
+    private mainFrameToTarget;
+    private sessionOwnerPage;
+    private frameOwnerPage;
+    private pendingOopifByMainFrame;
+    private createdAtByTarget;
+    private typeByTarget;
+    private _pageOrder;
+    private pendingCreatedTargetUrl;
+    private readonly initScripts;
     /**
-     * Navigate the page; optionally wait for a lifecycle state.
-     * Waits on the **current** main frame and follows root swaps during navigation.
+     * Create a Context for a given CDP websocket URL and bootstrap target wiring.
      */
-    goto(url: string, options?: {
-        waitUntil?: LoadState;
-        timeoutMs?: number;
-    }): Promise<Response$1 | null>;
+    static create(wsUrl: string, opts?: {
+        env?: "LOCAL" | "BROWSERBASE";
+        apiClient?: StagehandAPIClient | null;
+        localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null;
+    }): Promise<V3Context>;
     /**
-     * Reload the page; optionally wait for a lifecycle state.
+     * Wait until at least one top-level Page has been created and registered.
+     * We poll internal maps that bootstrap/onAttachedToTarget populate.
      */
-    reload(options?: {
-        waitUntil?: LoadState;
-        timeoutMs?: number;
-        ignoreCache?: boolean;
-    }): Promise<Response$1 | null>;
+    private waitForFirstTopLevelPage;
+    private waitForInitialTopLevelTargets;
+    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;
+    addInitScript<Arg>(script: InitScriptSource<Arg>, arg?: Arg): Promise<void>;
     /**
-     * Navigate back in history if possible; optionally wait for a lifecycle state.
+     * Return top-level `Page`s (oldest → newest). OOPIF targets are not included.
      */
-    goBack(options?: {
-        waitUntil?: LoadState;
-        timeoutMs?: number;
-    }): Promise<Response$1 | null>;
+    pages(): Page[];
+    private applyInitScriptsToPage;
     /**
-     * Navigate forward in history if possible; optionally wait for a lifecycle state.
+     * Resolve an owning `Page` by the **top-level main frame id**.
+     * Note: child (OOPIF) roots are intentionally not present in this mapping.
      */
-    goForward(options?: {
-        waitUntil?: LoadState;
-        timeoutMs?: number;
-    }): Promise<Response$1 | null>;
+    resolvePageByMainFrameId(frameId: string): Page | undefined;
+    /**
+     * Serialize the full frame tree for a given top-level main frame id.
+     */
+    getFullFrameTreeByMainFrameId(rootMainFrameId: string): Promise<Protocol.Page.FrameTree>;
+    /**
+     * Create a new top-level page (tab) with the given URL and return its Page object.
+     * Waits until the target is attached and registered.
+     */
+    newPage(url?: string): Promise<Page>;
+    /**
+     * Close CDP and clear all mappings. Best-effort cleanup.
+     */
+    close(): Promise<void>;
+    /**
+     * Bootstrap target lifecycle:
+     * - Attach to existing targets.
+     * - Attach on `Target.targetCreated` (fallback for OOPIFs).
+     * - Handle auto-attach events.
+     * - Clean up on detach/destroy.
+     */
+    private bootstrap;
+    /**
+     * Handle a newly attached target (top-level or potential OOPIF):
+     * - Enable Page domain and lifecycle events.
+     * - If top-level → create Page, wire listeners, resume.
+     * - Else → probe child root frame id via `Page.getFrameTree` and adopt immediately
+     *   if the parent is known; otherwise stage until parent `frameAttached`.
+     * - Resume the target only after listeners are wired.
+     */
+    private onAttachedToTarget;
+    /**
+     * Detach handler:
+     * - Remove child session ownership and prune its subtree.
+     * - If a top-level target, cleanup its `Page` and mappings.
+     * - Drop any staged child for this session.
+     */
+    private onDetachedFromTarget;
+    /**
+     * Cleanup a top-level Page by target id, removing its root and staged children.
+     */
+    private cleanupByTarget;
+    /**
+     * Wire Page-domain frame events for a session into the owning Page & mappings.
+     * We forward the *emitting session* with every event so Page can stamp ownership precisely.
+     */
+    private installFrameEventBridges;
+    /**
+     * Register that a session belongs to a Page (used by event routing).
+     */
+    private wireSessionToOwnerPage;
+    /**
+     * Utility: reverse-lookup the top-level target id that owns a given Page.
+     */
+    private findTargetIdByPage;
+    private _notePopupSignal;
+    /**
+     * Await the current active page, waiting briefly if a popup/open was just triggered.
+     * Normal path returns immediately; popup path waits up to timeoutMs for the new page.
+     */
+    awaitActivePage(timeoutMs?: number): Promise<Page>;
+}
+
+type AgentReplayStep = AgentReplayActStep | AgentReplayFillFormStep | AgentReplayGotoStep | AgentReplayScrollStep | AgentReplayWaitStep | AgentReplayNavBackStep | {
+    type: string;
+    [key: string]: unknown;
+};
+interface AgentReplayActStep {
+    type: "act";
+    instruction: string;
+    actions?: Action[];
+    actionDescription?: string;
+    message?: string;
+    timeout?: number;
+}
+interface AgentReplayFillFormStep {
+    type: "fillForm";
+    fields?: Array<{
+        action: string;
+        value: string;
+    }>;
+    observeResults?: Action[];
+    actions?: Action[];
+}
+interface AgentReplayGotoStep {
+    type: "goto";
+    url: string;
+    waitUntil?: LoadState;
+}
+interface AgentReplayScrollStep {
+    type: "scroll";
+    deltaX?: number;
+    deltaY?: number;
+    anchor?: {
+        x: number;
+        y: number;
+    };
+}
+interface AgentReplayWaitStep {
+    type: "wait";
+    timeMs: number;
+}
+interface AgentReplayNavBackStep {
+    type: "navback";
+    waitUntil?: LoadState;
+}
+
+/**
+ * Response
+ * -----------------
+ *
+ * This module implements a Playwright-inspired response wrapper that exposes
+ * navigation metadata and helpers for retrieving HTTP response bodies. The
+ * abstraction is consumed by navigation routines (e.g. `Page.goto`) so callers
+ * can synchronously inspect status codes, lazily fetch body text, or await the
+ * network layer finishing the request. The implementation is built directly on
+ * Chrome DevTools Protocol primitives – it holds the originating `requestId`
+ * so it can request payloads via `Network.getResponseBody`, and it listens for
+ * `responseReceivedExtraInfo`, `loadingFinished`, and `loadingFailed` events to
+ * hydrate the richer header view and resolve callers waiting on completion.
+ */
+
+type ServerAddr = {
+    ipAddress: string;
+    port: number;
+};
+/**
+ * Thin wrapper around CDP response metadata that mirrors the ergonomics of
+ * Playwright's `Response` class. The class intentionally keeps the same method
+ * names so upstream integrations can transition with minimal code changes.
+ */
+declare class Response$1 {
+    private readonly page;
+    private readonly session;
+    private readonly requestId;
+    private readonly frameId?;
+    private readonly loaderId?;
+    private readonly response;
+    private readonly fromServiceWorkerFlag;
+    private readonly serverAddress?;
+    private headersObject;
+    private headersArrayCache;
+    private allHeadersCache;
+    private readonly headerValuesMap;
+    private finishedDeferred;
+    private finishedSettled;
+    private extraInfoHeaders;
+    private extraInfoHeadersText;
     /**
-     * Return the current page URL (synchronous, cached from navigation events).
+     * Build a response wrapper from the CDP notification associated with a
+     * navigation. The constructor captures the owning page/session so follow-up
+     * methods (body/text/json) can query CDP on-demand. The `response` payload is
+     * the raw `Protocol.Network.Response` object emitted by Chrome.
      */
+    constructor(params: {
+        page: Page;
+        session: CDPSessionLike;
+        requestId: string;
+        frameId?: string;
+        loaderId?: string;
+        response: Protocol.Network.Response;
+        fromServiceWorker: boolean;
+    });
+    /** URL associated with the navigation request. */
     url(): string;
-    private beginNavigationCommand;
-    isCurrentNavigationCommand(id: number): boolean;
-    /**
-     * 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.
-     */
-    title(): Promise<string>;
-    /**
-     * Capture a screenshot with Playwright-style options.
-     *
-     * @param options Optional screenshot configuration.
-     * @param options.animations Control CSS/Web animations during capture. Use
-     * "disabled" to fast-forward finite animations and pause infinite ones.
-     * @param options.caret Either hide the text caret (default) or leave it
-     * visible via "initial".
-     * @param options.clip Restrict capture to a specific rectangle (in CSS
-     * pixels). Cannot be combined with `fullPage`.
-     * @param options.fullPage Capture the full scrollable page instead of the
-     * current viewport.
-     * @param options.mask Array of locators that should be covered with an
-     * overlay while the screenshot is taken.
-     * @param options.maskColor CSS color used for the mask overlay (default
-     * `#FF00FF`).
-     * @param options.omitBackground Make the default page background transparent
-     * (PNG only).
-     * @param options.path File path to write the screenshot to. The file extension
-     * determines the image type when `type` is not explicitly provided.
-     * @param options.quality JPEG quality (0–100). Only applies when
-     * `type === "jpeg"`.
-     * @param options.scale Render scale: use "css" for one pixel per CSS pixel,
-     * otherwise the default "device" leverages the current device pixel ratio.
-     * @param options.style Additional CSS text injected into every frame before
-     * capture (removed afterwards).
-     * @param options.timeout Maximum capture duration in milliseconds before a
-     * timeout error is thrown.
-     * @param options.type Image format (`"png"` by default).
-     */
-    screenshot(options?: ScreenshotOptions): Promise<Buffer>;
+    /** HTTP status code reported by Chrome. */
+    status(): number;
+    /** Human-readable status text that accompanied the response. */
+    statusText(): string;
+    /** Convenience predicate that checks for 2xx statuses. */
+    ok(): boolean;
+    /** Returns the Stagehand frame object that initiated the navigation. */
+    frame(): Frame | null;
+    /** Indicates whether the response was serviced by a Service Worker. */
+    fromServiceWorker(): boolean;
     /**
-     * Create a locator bound to the current main frame.
+     * Returns TLS security metadata when provided by the browser. In practice
+     * this includes certificate issuer, protocol, and validity interval.
      */
-    locator(selector: string): ReturnType<Frame["locator"]>;
+    securityDetails(): Promise<Protocol.Network.SecurityDetails | null>;
+    /** Returns the resolved server address for the navigation when available. */
+    serverAddr(): Promise<ServerAddr | null>;
     /**
-     * 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.
+     * Returns the response headers normalised to lowercase keys. Matches the
+     * behaviour of Playwright's `headers()` by eliding duplicate header entries.
      */
-    deepLocator(selector: string): DeepLocatorDelegate;
+    headers(): Record<string, string>;
     /**
-     * Frame locator similar to Playwright: targets iframe elements and scopes
-     * subsequent locators to that frame. Supports chaining.
+     * Returns all headers including those only surfaced through
+     * `responseReceivedExtraInfo` such as `set-cookie`. Values are reported as the
+     * browser sends them (no further splitting or concatenation).
      */
-    frameLocator(selector: string): FrameLocator;
+    allHeaders(): Promise<Record<string, string>>;
+    /** Returns a concatenated header string for the supplied header name. */
+    headerValue(name: string): Promise<string | null>;
+    /** Returns all values for a header (case-insensitive lookup). */
+    headerValues(name: string): Promise<string[]>;
     /**
-     * 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.
+     * Returns header entries preserving their original wire casing and ordering.
+     * Falls back to the CDP object when the raw header text is unavailable.
      */
-    frames(): Frame[];
+    headersArray(): Promise<Array<{
+        name: string;
+        value: string;
+    }>>;
     /**
-     * Wait until the page reaches a lifecycle state on the current main frame.
-     * Mirrors Playwright's API signatures.
+     * Requests the raw response body from Chrome DevTools Protocol. The method is
+     * intentionally lazy because not every caller needs the payload, and CDP only
+     * allows retrieving it once the response completes.
      */
-    waitForLoadState(state: LoadState, timeoutMs?: number): Promise<void>;
+    body(): Promise<Buffer>;
+    /** Decodes the response body as UTF-8 text. */
+    text(): Promise<string>;
+    /** Parses the response body as JSON and throws if parsing fails. */
+    json<T = unknown>(): Promise<T>;
     /**
-     * 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.
+     * Resolves once the underlying network request completes or fails. Mirrors
+     * Playwright's behaviour by resolving to `null` on success and to an `Error`
+     * instance when Chrome reports `Network.loadingFailed`.
      */
-    evaluate<R = unknown, Arg = unknown>(pageFunctionOrExpression: string | ((arg: Arg) => R | Promise<R>), arg?: Arg): Promise<R>;
+    finished(): Promise<null | Error>;
     /**
-     * Force the page viewport to an exact CSS size and device scale factor.
-     * Ensures screenshots match width x height pixels when deviceScaleFactor = 1.
+     * Internal helper invoked by the navigation tracker when CDP reports extra
+     * header information. This keeps the cached header views in sync with the
+     * richer metadata.
      */
-    setViewportSize(width: number, height: number, options?: {
-        deviceScaleFactor?: number;
-    }): Promise<void>;
+    applyExtraInfo(event: Protocol.Network.ResponseReceivedExtraInfoEvent): 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.
+     * Internal helper for creating a Response object from a Serializable
+     * goto response from the Stagehand API
      */
-    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>;
+    static fromSerializable(serialized: SerializableResponse, context: {
+        page: Page;
+        session: CDPSessionLike;
+    }): Response$1;
+    /** Marks the response as finished and resolves the `finished()` promise. */
+    markFinished(error: Error | null): void;
+}
+
+type AnyPage = Page$1 | Page$2 | Page$3 | Page;
+
+type LoadState = "load" | "domcontentloaded" | "networkidle";
+
+type ScreenshotAnimationsOption = "disabled" | "allow";
+type ScreenshotCaretOption = "hide" | "initial";
+type ScreenshotScaleOption = "css" | "device";
+interface ScreenshotClip {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ScreenshotOptions {
+    animations?: ScreenshotAnimationsOption;
+    caret?: ScreenshotCaretOption;
+    clip?: ScreenshotClip;
+    fullPage?: boolean;
+    mask?: Locator[];
+    maskColor?: string;
+    omitBackground?: boolean;
+    path?: string;
+    quality?: number;
+    scale?: ScreenshotScaleOption;
+    style?: string;
+    timeout?: number;
+    type?: "png" | "jpeg";
+}
+
+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;
+    private readonly browserIsRemote;
+    /** 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 readonly consoleListeners;
+    private readonly consoleHandlers;
+    /** Document-start scripts installed across every session this page owns. */
+    private readonly initScripts;
+    private constructor();
+    private installInitScriptOnSession;
+    private applyInitScriptsToSession;
+    registerInitScript(source: string): Promise<void>;
+    private cursorEnabled;
+    private ensureCursorScript;
+    enableCursorOverlay(): Promise<void>;
+    private updateCursor;
+    addInitScript<Arg>(script: InitScriptSource<Arg>, arg?: Arg): Promise<void>;
     /**
-     * Drag from (fromX, fromY) to (toX, toY) using mouse events.
-     * Sends mouseMoved → mousePressed → mouseMoved (steps) → mouseReleased.
+     * Factory: create Page and seed registry with the shallow tree from Page.getFrameTree.
+     * Assumes Page domain is already enabled on the session passed in.
      */
-    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]>;
+    static create(conn: CdpConnection, session: CDPSessionLike, targetId: string, apiClient?: StagehandAPIClient | null, localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null, browserIsRemote?: boolean): Promise<Page>;
     /**
-     * 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.
+     * Parent/child session emitted a `frameAttached`.
+     * Topology update + ownership stamped to **emitting session**.
      */
-    type(text: string, options?: {
-        delay?: number;
-        withMistakes?: boolean;
-    }): Promise<void>;
+    onFrameAttached(frameId: string, parentId: string | null, session: CDPSessionLike): 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.
+     * Parent/child session emitted a `frameDetached`.
      */
-    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;
+    onFrameDetached(frameId: string, reason?: "remove" | "swap" | string): void;
     /**
-     * Get the map of named keys with their properties
+     * Parent/child session emitted a `frameNavigated`.
+     * Topology + ownership update. Handles root swaps.
      */
-    private getNamedKeys;
+    onFrameNavigated(frame: Protocol.Page.Frame, session: CDPSessionLike): void;
+    onNavigatedWithinDocument(frameId: string, url: string, session: CDPSessionLike): void;
     /**
-     * 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.
+     * 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.
      */
-    private describePrintableKey;
-    private isMacOS;
+    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;
+    on(event: "console", listener: ConsoleListener): Page;
+    once(event: "console", listener: ConsoleListener): Page;
+    off(event: "console", listener: ConsoleListener): Page;
+    targetId(): string;
     /**
-     * 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...).
+     * Send a CDP command through the main session.
+     * Allows external consumers to execute arbitrary Chrome DevTools Protocol commands.
+     *
+     * @param method - The CDP method name (e.g., "Page.enable", "Runtime.evaluate")
+     * @param params - Optional parameters for the CDP command
+     * @returns Promise resolving to the typed CDP response
+     *
+     * @example
+     * // Enable the Runtime domain
+     * await page.sendCDP("Runtime.enable");
+     *
+     * @example
+     * // Evaluate JavaScript with typed response
+     * const result = await page.sendCDP<Protocol.Runtime.EvaluateResponse>(
+     *   "Runtime.evaluate",
+     *   { expression: "1 + 1" }
+     * );
      */
-    private macCommandsFor;
+    sendCDP<T = unknown>(method: string, params?: object): Promise<T>;
+    /** Seed the cached URL before navigation events converge. */
+    seedCurrentUrl(url: string | undefined | null): void;
+    mainFrameId(): string;
+    mainFrame(): Frame;
     /**
-     * Create an isolated world for the **current** main frame and return its context id.
+     * Close this top-level page (tab). Best-effort via Target.closeTarget.
      */
-    private createIsolatedWorldForCurrentMain;
+    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[];
+    private ensureConsoleTaps;
+    private installConsoleTap;
+    private sessionKey;
+    private resolveSessionByKey;
+    private teardownConsoleTap;
+    private removeAllConsoleTaps;
+    private emitConsole;
     /**
-     * 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.
+     * Navigate the page; optionally wait for a lifecycle state.
+     * Waits on the **current** main frame and follows root swaps during navigation.
      */
-    waitForMainLoadState(state: LoadState, timeoutMs?: number): Promise<void>;
-}
-
-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;
-        reasoning_tokens?: number;
-        cached_input_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";
-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;
-}
-interface AgentHandlerOptions {
-    modelName: string;
-    clientOptions?: Record<string, unknown>;
-    userProvidedInstructions?: string;
-    experimental?: boolean;
-}
-interface ActionExecutionResult {
-    success: boolean;
-    error?: string;
-    data?: unknown;
-}
-interface ToolUseItem extends ResponseItem {
-    type: "tool_use";
-    id: string;
-    name: string;
-    input: Record<string, unknown>;
-}
-interface AnthropicMessage {
-    role: string;
-    content: string | Array<AnthropicContentBlock>;
-}
-interface AnthropicContentBlock {
-    type: string;
-    [key: string]: unknown;
-}
-interface AnthropicTextBlock extends AnthropicContentBlock {
-    type: "text";
-    text: string;
-}
-interface AnthropicToolResult {
-    type: "tool_result";
-    tool_use_id: string;
-    content: string | Array<AnthropicContentBlock>;
-}
-interface ResponseItem {
-    type: string;
-    id: string;
-    [key: string]: unknown;
-}
-interface ComputerCallItem extends ResponseItem {
-    type: "computer_call";
-    call_id: string;
-    action: {
-        type: string;
-        [key: string]: unknown;
-    };
-    pending_safety_checks?: Array<{
-        id: string;
-        code: string;
-        message: string;
-    }>;
-}
-interface FunctionCallItem extends ResponseItem {
-    type: "function_call";
-    call_id: string;
-    name: string;
-    arguments: string;
-}
-type ResponseInputItem = {
-    role: string;
-    content: string;
-} | {
-    type: "computer_call_output";
-    call_id: string;
-    output: {
-        type: "input_image";
-        image_url: string;
-        current_url?: string;
-        error?: string;
-        [key: string]: unknown;
-    } | string;
-    acknowledged_safety_checks?: Array<{
-        id: string;
-        code: string;
-        message: string;
-    }>;
-} | {
-    type: "function_call_output";
-    call_id: string;
-    output: string;
-};
-interface AgentInstance {
-    execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
-}
-type AgentProviderType = AgentType;
-type AgentModelConfig<TModelName extends string = string> = {
-    modelName: TModelName;
-} & Record<string, unknown>;
-type AgentConfig = {
+    goto(url: string, options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+    }): Promise<Response$1 | null>;
+    /**
+     * Reload the page; optionally wait for a lifecycle state.
+     */
+    reload(options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+        ignoreCache?: boolean;
+    }): Promise<Response$1 | null>;
     /**
-     * Custom system prompt to provide to the agent. Overrides the default system prompt.
+     * Navigate back in history if possible; optionally wait for a lifecycle state.
      */
-    systemPrompt?: string;
+    goBack(options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+    }): Promise<Response$1 | null>;
     /**
-     * MCP integrations - Array of Client objects
+     * Navigate forward in history if possible; optionally wait for a lifecycle state.
      */
-    integrations?: (Client | string)[];
+    goForward(options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+    }): Promise<Response$1 | null>;
     /**
-     * Tools passed to the agent client
+     * Return the current page URL (synchronous, cached from navigation events).
      */
-    tools?: ToolSet;
+    url(): string;
+    private beginNavigationCommand;
+    isCurrentNavigationCommand(id: number): boolean;
     /**
-     * Indicates CUA is disabled for this configuration
+     * 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.
      */
-    cua?: boolean;
+    title(): Promise<string>;
     /**
-     * The model to use for agent functionality
+     * Capture a screenshot with Playwright-style options.
+     *
+     * @param options Optional screenshot configuration.
+     * @param options.animations Control CSS/Web animations during capture. Use
+     * "disabled" to fast-forward finite animations and pause infinite ones.
+     * @param options.caret Either hide the text caret (default) or leave it
+     * visible via "initial".
+     * @param options.clip Restrict capture to a specific rectangle (in CSS
+     * pixels). Cannot be combined with `fullPage`.
+     * @param options.fullPage Capture the full scrollable page instead of the
+     * current viewport.
+     * @param options.mask Array of locators that should be covered with an
+     * overlay while the screenshot is taken.
+     * @param options.maskColor CSS color used for the mask overlay (default
+     * `#FF00FF`).
+     * @param options.omitBackground Make the default page background transparent
+     * (PNG only).
+     * @param options.path File path to write the screenshot to. The file extension
+     * determines the image type when `type` is not explicitly provided.
+     * @param options.quality JPEG quality (0–100). Only applies when
+     * `type === "jpeg"`.
+     * @param options.scale Render scale: use "css" for one pixel per CSS pixel,
+     * otherwise the default "device" leverages the current device pixel ratio.
+     * @param options.style Additional CSS text injected into every frame before
+     * capture (removed afterwards).
+     * @param options.timeout Maximum capture duration in milliseconds before a
+     * timeout error is thrown.
+     * @param options.type Image format (`"png"` by default).
      */
-    model?: string | AgentModelConfig<string>;
+    screenshot(options?: ScreenshotOptions): Promise<Buffer>;
     /**
-     * The model to use for tool execution (observe/act calls within agent tools).
-     * If not specified, inherits from the main model configuration.
-     * Format: "provider/model" (e.g., "openai/gpt-4o-mini", "google/gemini-2.0-flash-exp")
+     * Create a locator bound to the current main frame.
      */
-    executionModel?: string | AgentModelConfig<string>;
-};
-
-declare class StagehandAPIError extends Error {
-    constructor(message: string);
-}
-declare class StagehandAPIUnauthorizedError extends StagehandAPIError {
-    constructor(message?: string);
-}
-declare class StagehandHttpError extends StagehandAPIError {
-    constructor(message: string);
-}
-declare class StagehandServerError extends StagehandAPIError {
-    constructor(message: string);
-}
-declare class StagehandResponseBodyError extends StagehandAPIError {
-    constructor();
-}
-declare class StagehandResponseParseError extends StagehandAPIError {
-    constructor(message: string);
-}
-
-interface ActOptions {
-    model?: ModelConfiguration;
-    variables?: Record<string, string>;
-    timeout?: number;
-    page?: Page$1 | Page$2 | Page$3 | Page;
-}
-interface ActResult {
-    success: boolean;
-    message: string;
-    actionDescription: string;
-    actions: Action[];
-}
-type ExtractResult<T extends StagehandZodSchema> = InferStagehandSchema<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.ZodObject<{
-    extraction: z.ZodString;
-}, z.core.$strip>;
-declare const pageTextSchema: z.ZodObject<{
-    pageText: z.ZodString;
-}, z.core.$strip>;
-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;
-    actReasoningTokens: number;
-    actCachedInputTokens: number;
-    actInferenceTimeMs: number;
-    extractPromptTokens: number;
-    extractCompletionTokens: number;
-    extractReasoningTokens: number;
-    extractCachedInputTokens: number;
-    extractInferenceTimeMs: number;
-    observePromptTokens: number;
-    observeCompletionTokens: number;
-    observeReasoningTokens: number;
-    observeCachedInputTokens: number;
-    observeInferenceTimeMs: number;
-    agentPromptTokens: number;
-    agentCompletionTokens: number;
-    agentReasoningTokens: number;
-    agentCachedInputTokens: number;
-    agentInferenceTimeMs: number;
-    totalPromptTokens: number;
-    totalCompletionTokens: number;
-    totalReasoningTokens: number;
-    totalCachedInputTokens: 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;
+    locator(selector: string): ReturnType<Frame["locator"]>;
+    /**
+     * 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.
+     */
+    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 main 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>;
     /**
-     * Optional: fine-tune Browserbase session creation or resume an existing session.
+     * Drag from (fromX, fromY) to (toX, toY) using mouse events.
+     * Sends mouseMoved → mousePressed → mouseMoved (steps) → mouseReleased.
      */
-    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);
-}
-declare class StagehandDefaultError extends StagehandError {
-    constructor(error?: unknown);
-}
-declare class StagehandEnvironmentError extends StagehandError {
-    constructor(currentEnvironment: string, requiredEnvironment: string, feature: string);
-}
-declare class MissingEnvironmentVariableError extends StagehandError {
-    constructor(missingEnvironmentVariable: string, feature: string);
-}
-declare class UnsupportedModelError extends StagehandError {
-    constructor(supportedModels: string[], feature?: string);
-}
-declare class UnsupportedModelProviderError extends StagehandError {
-    constructor(supportedProviders: string[], feature?: string);
-}
-declare class UnsupportedAISDKModelProviderError extends StagehandError {
-    constructor(provider: string, supportedProviders: string[]);
-}
-declare class InvalidAISDKModelFormatError extends StagehandError {
-    constructor(modelName: string);
-}
-declare class StagehandNotInitializedError extends StagehandError {
-    constructor(prop: string);
-}
-declare class BrowserbaseSessionNotFoundError extends StagehandError {
-    constructor();
-}
-declare class CaptchaTimeoutError extends StagehandError {
-    constructor();
-}
-declare class MissingLLMConfigurationError extends StagehandError {
-    constructor();
-}
-declare class HandlerNotInitializedError extends StagehandError {
-    constructor(handlerType: string);
-}
-declare class StagehandInvalidArgumentError extends StagehandError {
-    constructor(message: string);
-}
-declare class StagehandElementNotFoundError extends StagehandError {
-    constructor(xpaths: string[]);
-}
-declare class AgentScreenshotProviderError extends StagehandError {
-    constructor(message: string);
-}
-declare class StagehandMissingArgumentError extends StagehandError {
-    constructor(message: string);
-}
-declare class CreateChatCompletionResponseError extends StagehandError {
-    constructor(message: string);
-}
-declare class StagehandEvalError extends StagehandError {
-    constructor(message: string);
-}
-declare class StagehandDomProcessError extends StagehandError {
-    constructor(message: string);
-}
-declare class StagehandClickError extends StagehandError {
-    constructor(message: string, selector: string);
-}
-declare class LLMResponseError extends StagehandError {
-    constructor(primitive: string, message: string);
-}
-declare class StagehandIframeError extends StagehandError {
-    constructor(frameUrl: string, message: string);
-}
-declare class ContentFrameNotFoundError extends StagehandError {
-    constructor(selector: string);
-}
-declare class XPathResolutionError extends StagehandError {
-    constructor(xpath: string);
-}
-declare class ExperimentalApiConflictError extends StagehandError {
-    constructor();
-}
-declare class ExperimentalNotConfiguredError extends StagehandError {
-    constructor(featureName: string);
-}
-declare class CuaModelRequiredError extends StagehandError {
-    constructor(availableModels: readonly string[]);
-}
-declare class ZodSchemaValidationError extends Error {
-    readonly received: unknown;
-    readonly issues: ReturnType<ZodError["format"]>;
-    constructor(received: unknown, issues: ReturnType<ZodError["format"]>);
-}
-declare class StagehandInitError extends StagehandError {
-    constructor(message: string);
-}
-declare class MCPConnectionError extends StagehandError {
-    readonly serverUrl: string;
-    readonly originalError: unknown;
-    constructor(serverUrl: string, originalError: unknown);
-}
-declare class StagehandShadowRootMissingError extends StagehandError {
-    constructor(detail?: string);
-}
-declare class StagehandShadowSegmentEmptyError extends StagehandError {
-    constructor();
-}
-declare class StagehandShadowSegmentNotFoundError extends StagehandError {
-    constructor(segment: string, hint?: string);
-}
-declare class ElementNotVisibleError extends StagehandError {
-    constructor(selector: string);
-}
-declare class ResponseBodyError extends StagehandError {
-    constructor(message: string);
-}
-declare class ResponseParseError extends StagehandError {
-    constructor(message: string);
-}
-declare class TimeoutError extends StagehandError {
-    constructor(operation: string, timeoutMs: number);
-}
-declare class PageNotFoundError extends StagehandError {
-    constructor(identifier: string);
-}
-declare class ConnectionTimeoutError extends StagehandError {
-    constructor(message: string);
-}
-
-declare class AISdkClient extends LLMClient {
-    type: "aisdk";
-    private model;
-    constructor({ model }: {
-        model: LanguageModelV2;
-    });
-    createChatCompletion<T = ChatCompletion>({ options, }: CreateChatCompletionOptions): Promise<T>;
-}
-
-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;
-    };
-    selfHeal?: boolean;
-    browserbaseSessionID?: string;
-}
-interface StartSessionResult {
-    sessionId: string;
-    available?: boolean;
-}
-interface APIActParameters {
-    input: string | Action;
-    options?: ActOptions;
-    frameId?: string;
+    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;
+    /** Resolve the main-world execution context for the current main frame. */
+    private mainWorldExecutionContextId;
+    /**
+     * 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>;
 }
-interface APIExtractParameters {
-    instruction?: string;
-    schema?: StagehandZodSchema;
-    options?: ExtractOptions;
-    frameId?: string;
+
+interface AgentContext {
+    options: AgentExecuteOptionsBase;
+    maxSteps: number;
+    systemPrompt: string;
+    allTools: ToolSet;
+    messages: ModelMessage[];
+    wrappedModel: ReturnType<typeof wrapLanguageModel>;
+    initialPageUrl: string;
+}
+interface AgentState {
+    collectedReasoning: string[];
+    actions: AgentAction[];
+    finalMessage: string;
+    completed: boolean;
+    currentPageUrl: string;
 }
-interface APIObserveParameters {
+interface AgentAction {
+    type: string;
+    reasoning?: string;
+    taskCompleted?: boolean;
+    action?: string;
+    timeMs?: number;
+    pageText?: string;
+    pageUrl?: string;
     instruction?: string;
-    options?: ObserveOptions;
-    frameId?: string;
+    [key: string]: unknown;
 }
-interface SerializableResponse {
-    requestId: string;
-    frameId?: string;
-    loaderId?: string;
-    response: Protocol.Network.Response;
-    fromServiceWorkerFlag?: boolean;
-    finishedSettled?: boolean;
-    extraInfoHeaders?: Protocol.Network.Headers | null;
-    extraInfoHeadersText?: string;
+interface AgentResult {
+    success: boolean;
+    message: string;
+    actions: AgentAction[];
+    completed: boolean;
+    metadata?: Record<string, unknown>;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+        reasoning_tokens?: number;
+        cached_input_tokens?: number;
+        inference_time_ms: number;
+    };
+    /**
+     * The conversation messages from this execution.
+     * Pass these to a subsequent execute() call via the `messages` option to continue the conversation.
+     * @experimental
+     */
+    messages?: ModelMessage[];
 }
-
+type AgentStreamResult = StreamTextResult<ToolSet, never> & {
+    result: Promise<AgentResult>;
+};
 /**
- * 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`.
+ * Base callbacks shared between execute (non-streaming) and streaming modes.
  */
-interface ZodPathSegments {
+interface AgentCallbacks {
     /**
-     * The ordered list of keys/indices leading from the schema root
-     * to the targeted field.
+     * Optional function called before each step to modify settings.
+     * You can change the model, tool choices, active tools, system prompt,
+     * and input messages for each step.
      */
-    segments: Array<string | number>;
+    prepareStep?: PrepareStepFunction<ToolSet>;
+    /**
+     * Callback called when each step (LLM call) is finished.
+     * This is called for intermediate steps as well as the final step.
+     */
+    onStepFinish?: GenerateTextOnStepFinishCallback<ToolSet> | StreamTextOnStepFinishCallback<ToolSet>;
 }
-
-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
+ * Error message type for streaming-only callbacks used in non-streaming mode.
+ * This provides a clear error message when users try to use streaming callbacks without stream: true.
  */
-interface EvaluationResult {
+type StreamingCallbackNotAvailable = "This callback requires 'stream: true' in AgentConfig. Set stream: true to use streaming callbacks like onChunk, onFinish, onError, and onAbort.";
+/**
+ * Callbacks specific to the non-streaming execute method.
+ */
+interface AgentExecuteCallbacks extends AgentCallbacks {
     /**
-     * The evaluation result ('YES', 'NO', or 'INVALID' if parsing failed or value was unexpected)
+     * Callback called when each step (LLM call) is finished.
      */
-    evaluation: "YES" | "NO" | "INVALID";
+    onStepFinish?: GenerateTextOnStepFinishCallback<ToolSet>;
     /**
-     * The reasoning behind the evaluation
+     * NOT AVAILABLE in non-streaming mode.
+     * This callback requires `stream: true` in AgentConfig.
+     *
+     * @example
+     * ```typescript
+     * // Enable streaming to use onChunk:
+     * const agent = stagehand.agent({ stream: true });
+     * await agent.execute({
+     *   instruction: "...",
+     *   callbacks: { onChunk: async (chunk) => console.log(chunk) }
+     * });
+     * ```
+     */
+    onChunk?: StreamingCallbackNotAvailable;
+    /**
+     * NOT AVAILABLE in non-streaming mode.
+     * This callback requires `stream: true` in AgentConfig.
+     *
+     * @example
+     * ```typescript
+     * // Enable streaming to use onFinish:
+     * const agent = stagehand.agent({ stream: true });
+     * await agent.execute({
+     *   instruction: "...",
+     *   callbacks: { onFinish: (event) => console.log("Done!", event) }
+     * });
+     * ```
+     */
+    onFinish?: StreamingCallbackNotAvailable;
+    /**
+     * NOT AVAILABLE in non-streaming mode.
+     * This callback requires `stream: true` in AgentConfig.
+     *
+     * @example
+     * ```typescript
+     * // Enable streaming to use onError:
+     * const agent = stagehand.agent({ stream: true });
+     * await agent.execute({
+     *   instruction: "...",
+     *   callbacks: { onError: ({ error }) => console.error(error) }
+     * });
+     * ```
+     */
+    onError?: StreamingCallbackNotAvailable;
+    /**
+     * NOT AVAILABLE in non-streaming mode.
+     * This callback requires `stream: true` in AgentConfig.
+     *
+     * @example
+     * ```typescript
+     * // Enable streaming to use onAbort:
+     * const agent = stagehand.agent({ stream: true });
+     * await agent.execute({
+     *   instruction: "...",
+     *   callbacks: { onAbort: (event) => console.log("Aborted", event.steps) }
+     * });
+     * ```
      */
-    reasoning: string;
+    onAbort?: StreamingCallbackNotAvailable;
 }
-
 /**
- * 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.
+ * Callbacks specific to the streaming mode.
  */
-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;
+interface AgentStreamCallbacks extends AgentCallbacks {
     /**
-     * Create a Context for a given CDP websocket URL and bootstrap target wiring.
+     * Callback called when each step (LLM call) is finished during streaming.
      */
-    static create(wsUrl: string, opts?: {
-        env?: "LOCAL" | "BROWSERBASE";
-        apiClient?: StagehandAPIClient | null;
-        localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null;
-    }): Promise<V3Context>;
+    onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
     /**
-     * Wait until at least one top-level Page has been created and registered.
-     * We poll internal maps that bootstrap/onAttachedToTarget populate.
+     * Callback called when an error occurs during streaming.
+     * Use this to log errors or handle error states.
      */
-    private waitForFirstTopLevelPage;
-    private waitForInitialTopLevelTargets;
-    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;
+    onError?: StreamTextOnErrorCallback;
     /**
-     * Return top-level `Page`s (oldest → newest). OOPIF targets are not included.
+     * Callback called for each chunk of the stream.
+     * Stream processing will pause until the callback promise resolves.
      */
-    pages(): Page[];
+    onChunk?: StreamTextOnChunkCallback<ToolSet>;
     /**
-     * Resolve an owning `Page` by the **top-level main frame id**.
-     * Note: child (OOPIF) roots are intentionally not present in this mapping.
+     * Callback called when the stream finishes.
      */
-    resolvePageByMainFrameId(frameId: string): Page | undefined;
+    onFinish?: StreamTextOnFinishCallback<ToolSet>;
     /**
-     * Serialize the full frame tree for a given top-level main frame id.
+     * Callback called when the stream is aborted.
      */
-    getFullFrameTreeByMainFrameId(rootMainFrameId: string): Promise<Protocol.Page.FrameTree>;
+    onAbort?: (event: {
+        steps: Array<StepResult<ToolSet>>;
+    }) => PromiseLike<void> | void;
+}
+/**
+ * Base options for agent execution (without callbacks).
+ */
+interface AgentExecuteOptionsBase {
+    instruction: string;
+    maxSteps?: number;
+    page?: Page$1 | Page$2 | Page$3 | Page;
+    highlightCursor?: boolean;
     /**
-     * Create a new top-level page (tab) with the given URL and return its Page object.
-     * Waits until the target is attached and registered.
+     * Previous conversation messages to continue from.
+     * Pass the `messages` from a previous AgentResult to continue that conversation.
+     * @experimental
      */
-    newPage(url?: string): Promise<Page>;
+    messages?: ModelMessage[];
     /**
-     * Close CDP and clear all mappings. Best-effort cleanup.
+     * An AbortSignal that can be used to cancel the agent execution.
+     * When aborted, the agent will stop and return a partial result.
+     * @experimental
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController();
+     * setTimeout(() => controller.abort(), 30000); // 30 second timeout
+     *
+     * const result = await agent.execute({
+     *   instruction: "...",
+     *   signal: controller.signal
+     * });
+     * ```
      */
-    close(): Promise<void>;
+    signal?: AbortSignal;
+}
+/**
+ * Options for non-streaming agent execution.
+ * Only accepts AgentExecuteCallbacks (no streaming-specific callbacks like onChunk, onFinish).
+ */
+interface AgentExecuteOptions extends AgentExecuteOptionsBase {
     /**
-     * Bootstrap target lifecycle:
-     * - Attach to existing targets.
-     * - Attach on `Target.targetCreated` (fallback for OOPIFs).
-     * - Handle auto-attach events.
-     * - Clean up on detach/destroy.
+     * Callbacks for non-streaming agent execution.
+     * For streaming callbacks (onChunk, onFinish, onError, onAbort), use stream: true in AgentConfig.
      */
-    private bootstrap;
+    callbacks?: AgentExecuteCallbacks;
+}
+/**
+ * Options for streaming agent execution.
+ * Accepts AgentStreamCallbacks including onChunk, onFinish, onError, and onAbort.
+ */
+interface AgentStreamExecuteOptions extends AgentExecuteOptionsBase {
+    /**
+     * Callbacks for streaming agent execution.
+     * Includes streaming-specific callbacks: onChunk, onFinish, onError, onAbort.
+     */
+    callbacks?: AgentStreamCallbacks;
+}
+type AgentType = "openai" | "anthropic" | "google" | "microsoft";
+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-opus-4-5-20251101", "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", "microsoft/fara-7b"];
+type AvailableCuaModel = (typeof AVAILABLE_CUA_MODELS)[number];
+interface AgentExecutionOptions<TOptions extends AgentExecuteOptions = AgentExecuteOptions> {
+    options: TOptions;
+    logger: (message: LogLine) => void;
+    retries?: number;
+}
+interface AgentHandlerOptions {
+    modelName: string;
+    clientOptions?: ClientOptions;
+    userProvidedInstructions?: string;
+    experimental?: boolean;
+}
+interface ActionExecutionResult {
+    success: boolean;
+    error?: string;
+    data?: unknown;
+}
+interface ToolUseItem extends ResponseItem {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface AnthropicMessage {
+    role: string;
+    content: string | Array<AnthropicContentBlock>;
+}
+interface AnthropicContentBlock {
+    type: string;
+    [key: string]: unknown;
+}
+interface AnthropicTextBlock extends AnthropicContentBlock {
+    type: "text";
+    text: string;
+}
+interface AnthropicToolResult {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string | Array<AnthropicContentBlock>;
+}
+interface ResponseItem {
+    type: string;
+    id: string;
+    [key: string]: unknown;
+}
+interface ComputerCallItem extends ResponseItem {
+    type: "computer_call";
+    call_id: string;
+    action: {
+        type: string;
+        [key: string]: unknown;
+    };
+    pending_safety_checks?: Array<{
+        id: string;
+        code: string;
+        message: string;
+    }>;
+}
+interface FunctionCallItem extends ResponseItem {
+    type: "function_call";
+    call_id: string;
+    name: string;
+    arguments: string;
+}
+type ResponseInputItem = {
+    role: string;
+    content: string;
+} | {
+    type: "computer_call_output";
+    call_id: string;
+    output: {
+        type: "input_image";
+        image_url: string;
+        current_url?: string;
+        error?: string;
+        [key: string]: unknown;
+    } | string;
+    acknowledged_safety_checks?: Array<{
+        id: string;
+        code: string;
+        message: string;
+    }>;
+} | {
+    type: "function_call_output";
+    call_id: string;
+    output: string;
+};
+interface AgentInstance {
+    execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
+}
+type AgentProviderType = AgentType;
+type AgentModelConfig<TModelName extends string = string> = {
+    modelName: TModelName;
+} & Record<string, unknown>;
+type AgentConfig = {
     /**
-     * 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.
+     * Custom system prompt to provide to the agent. Overrides the default system prompt.
      */
-    private onAttachedToTarget;
+    systemPrompt?: string;
     /**
-     * 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.
+     * MCP integrations - Array of Client objects
      */
-    private onDetachedFromTarget;
+    integrations?: (Client | string)[];
     /**
-     * Cleanup a top-level Page by target id, removing its root and staged children.
+     * Tools passed to the agent client
      */
-    private cleanupByTarget;
+    tools?: ToolSet;
     /**
-     * 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.
+     * Indicates CUA is disabled for this configuration
      */
-    private installFrameEventBridges;
+    cua?: boolean;
     /**
-     * Register that a session belongs to a Page (used by event routing).
+     * The model to use for agent functionality
      */
-    private wireSessionToOwnerPage;
+    model?: string | AgentModelConfig<string>;
     /**
-     * Utility: reverse-lookup the top-level target id that owns a given Page.
+     * 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")
      */
-    private findTargetIdByPage;
-    private _notePopupSignal;
+    executionModel?: string | AgentModelConfig<string>;
     /**
-     * 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.
+     * Enable streaming mode for the agent.
+     * When true, execute() returns AgentStreamResult with textStream for incremental output.
+     * When false (default), execute() returns AgentResult after completion.
      */
-    awaitActivePage(timeoutMs?: number): Promise<Page>;
+    stream?: boolean;
+};
+/**
+ * Agent instance returned when stream: true is set in AgentConfig.
+ * execute() returns a streaming result that can be consumed incrementally.
+ * Accepts AgentStreamExecuteOptions with streaming-specific callbacks.
+ */
+interface StreamingAgentInstance {
+    execute: (instructionOrOptions: string | AgentStreamExecuteOptions) => Promise<AgentStreamResult>;
+}
+/**
+ * Agent instance returned when stream is false or not set in AgentConfig.
+ * execute() returns a result after the agent completes.
+ * Accepts AgentExecuteOptions with non-streaming callbacks only.
+ */
+interface NonStreamingAgentInstance {
+    execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
 }
 
-type AgentReplayStep = AgentReplayActStep | AgentReplayFillFormStep | AgentReplayGotoStep | AgentReplayScrollStep | AgentReplayWaitStep | AgentReplayNavBackStep | {
-    type: string;
-    [key: string]: unknown;
+type OpenAIClientOptions = Pick<ClientOptions$1, "baseURL" | "apiKey">;
+type AnthropicClientOptions = Pick<ClientOptions$2, "baseURL" | "apiKey">;
+interface GoogleServiceAccountCredentials {
+    type?: string;
+    project_id?: string;
+    private_key_id?: string;
+    private_key?: string;
+    client_email?: string;
+    client_id?: string;
+    auth_uri?: string;
+    token_uri?: string;
+    auth_provider_x509_cert_url?: string;
+    client_x509_cert_url?: string;
+    universe_domain?: string;
+}
+type GoogleVertexProviderSettings = Pick<GoogleVertexProviderSettings$1, "project" | "location"> & {
+    googleAuthOptions?: {
+        credentials?: GoogleServiceAccountCredentials;
+    };
 };
-interface AgentReplayActStep {
-    type: "act";
-    instruction: string;
-    actions?: Action[];
-    actionDescription?: string;
-    message?: string;
-    timeout?: number;
+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>;
 }
-interface AgentReplayFillFormStep {
-    type: "fillForm";
-    fields?: Array<{
-        action: string;
-        value: string;
-    }>;
-    observeResults?: Action[];
-    actions?: Action[];
+type AISDKProvider = (modelName: string) => LanguageModelV2;
+type AISDKCustomProvider = (options: ClientOptions) => 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 = (OpenAIClientOptions | AnthropicClientOptions | GoogleVertexProviderSettings) & {
+    apiKey?: string;
+    provider?: AgentProviderType;
+    baseURL?: string;
+    /** OpenAI organization ID */
+    organization?: string;
+    /** Delay between agent actions in ms */
+    waitBetweenActions?: number;
+    /** Anthropic thinking budget for extended thinking */
+    thinkingBudget?: number;
+    /** Environment type for CUA agents (browser, mac, windows, ubuntu) */
+    environment?: string;
+    /** Max images for Microsoft FARA agent */
+    maxImages?: number;
+    /** Temperature for model inference */
+    temperature?: number;
+};
+type ModelConfiguration = AvailableModel | (ClientOptions & {
+    modelName: AvailableModel;
+});
+
+interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: ChatMessageContent;
 }
-interface AgentReplayGotoStep {
-    type: "goto";
-    url: string;
-    waitUntil?: LoadState;
+type ChatMessageContent = string | (ChatMessageImageContent | ChatMessageTextContent)[];
+interface ChatMessageImageContent {
+    type: string;
+    image_url?: {
+        url: string;
+    };
+    text?: string;
+    source?: {
+        type: string;
+        media_type: string;
+        data: string;
+    };
 }
-interface AgentReplayScrollStep {
-    type: "scroll";
-    deltaX?: number;
-    deltaY?: number;
-    anchor?: {
-        x: number;
-        y: number;
+interface ChatMessageTextContent {
+    type: string;
+    text: string;
+}
+declare const AnnotatedScreenshotText = "This is a screenshot of the current page state with the elements annotated on it. Each element id is annotated with a number to the top left of it. Duplicate annotations at the same location are under each other vertically.";
+interface ChatCompletionOptions {
+    messages: ChatMessage[];
+    temperature?: number;
+    top_p?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    image?: {
+        buffer: Buffer;
+        description?: string;
+    };
+    response_model?: {
+        name: string;
+        schema: StagehandZodSchema;
     };
+    tools?: LLMTool[];
+    tool_choice?: "auto" | "none" | "required";
+    maxOutputTokens?: number;
+    requestId?: string;
 }
-interface AgentReplayWaitStep {
-    type: "wait";
-    timeMs: number;
+type LLMResponse = {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: {
+        index: number;
+        message: {
+            role: string;
+            content: string | null;
+            tool_calls: {
+                id: string;
+                type: string;
+                function: {
+                    name: string;
+                    arguments: string;
+                };
+            }[];
+        };
+        finish_reason: string;
+    }[];
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+};
+interface CreateChatCompletionOptions {
+    options: ChatCompletionOptions;
+    logger: (message: LogLine) => void;
+    retries?: number;
 }
-interface AgentReplayNavBackStep {
-    type: "navback";
-    waitUntil?: LoadState;
+/** Simple usage shape if your LLM returns usage tokens. */
+interface LLMUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    reasoning_tokens?: number;
+    cached_input_tokens?: number;
+}
+/**
+ * For calls that use a schema: the LLMClient may return { data: T; usage?: LLMUsage }
+ */
+interface LLMParsedResponse<T> {
+    data: T;
+    usage?: LLMUsage;
+}
+declare abstract class LLMClient {
+    type: "openai" | "anthropic" | "cerebras" | "groq" | (string & {});
+    modelName: AvailableModel | (string & {});
+    hasVision: boolean;
+    clientOptions: ClientOptions;
+    userProvidedInstructions?: string;
+    constructor(modelName: AvailableModel, userProvidedInstructions?: string);
+    abstract createChatCompletion<T>(options: CreateChatCompletionOptions & {
+        options: {
+            response_model: {
+                name: string;
+                schema: StagehandZodSchema;
+            };
+        };
+    }): Promise<LLMParsedResponse<T>>;
+    abstract createChatCompletion<T = LLMResponse>(options: CreateChatCompletionOptions): Promise<T>;
+    generateObject: typeof generateObject;
+    generateText: typeof generateText;
+    streamText: typeof streamText;
+    streamObject: typeof streamObject;
+    generateImage: typeof experimental_generateImage;
+    embed: typeof embed;
+    embedMany: typeof embedMany;
+    transcribe: typeof experimental_transcribe;
+    generateSpeech: typeof experimental_generateSpeech;
+    getLanguageModel?(): LanguageModelV2;
 }
 
 /**
@@ -1911,7 +2203,11 @@ declare class V3 {
     private readonly domSettleTimeoutMs?;
     private _isClosing;
     browserbaseSessionId?: string;
+    private browserbaseSessionUrl?;
+    private browserbaseDebugUrl?;
     get browserbaseSessionID(): string | undefined;
+    get browserbaseSessionURL(): string | undefined;
+    get browserbaseDebugURL(): string | undefined;
     private _onCdpClosed;
     readonly experimental: boolean;
     readonly logInferenceToFile: boolean;
@@ -1959,6 +2255,7 @@ declare class V3 {
     /** Apply post-connect local browser options that require CDP. */
     private _applyPostConnectLocalOptions;
     private _ensureBrowserbaseDownloadsEnabled;
+    private resetBrowserbaseSessionMetadata;
     /**
      * Run an "act" instruction through the ActHandler.
      *
@@ -2010,11 +2307,27 @@ declare class V3 {
     /** Resolve an external page reference or fall back to the active V3 page. */
     private resolvePage;
     private normalizeToV3Page;
+    private _logBrowserbaseSessionStatus;
+    /**
+     * Prepares shared context for agent execution (both execute and stream).
+     * Extracts duplicated setup logic into a single helper.
+     */
+    private prepareAgentExecution;
     /**
      * Create a v3 agent instance (AISDK tool-based) with execute().
      * Mirrors the v2 Stagehand.agent() tool mode (no CUA provider here).
+     *
+     * @overload When stream: true, returns a streaming agent where execute() returns AgentStreamResult
+     * @overload When stream is false/undefined, returns a non-streaming agent where execute() returns AgentResult
      */
-    agent(options?: AgentConfig): {
+    agent(options: AgentConfig & {
+        stream: true;
+    }): {
+        execute: (instructionOrOptions: string | AgentStreamExecuteOptions) => Promise<AgentStreamResult>;
+    };
+    agent(options?: AgentConfig & {
+        stream?: false;
+    }): {
         execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
     };
 }
@@ -2026,7 +2339,7 @@ declare class V3 {
 declare abstract class AgentClient {
     type: AgentType;
     modelName: string;
-    clientOptions: Record<string, unknown>;
+    clientOptions: ClientOptions;
     userProvidedInstructions?: string;
     constructor(type: AgentType, modelName: string, userProvidedInstructions?: string);
     abstract execute(options: AgentExecutionOptions): Promise<AgentResult>;
@@ -2049,7 +2362,7 @@ declare class AgentProvider {
      * Create a new agent provider
      */
     constructor(logger: (message: LogLine) => void);
-    getClient(modelName: string, clientOptions?: Record<string, unknown>, userProvidedInstructions?: string, tools?: ToolSet$1): AgentClient;
+    getClient(modelName: string, clientOptions?: ClientOptions, userProvidedInstructions?: string, tools?: ToolSet$1): AgentClient;
     static getAgentProvider(modelName: string): AgentProviderType;
 }
 
@@ -2144,4 +2457,4 @@ declare class V3Evaluator {
     private _evaluateWithMultipleScreenshots;
 }
 
-export { type AISDKCustomProvider, type AISDKProvider, AISdkClient, 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, ConnectionTimeoutError, type ConsoleListener, ConsoleMessage, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, CuaModelRequiredError, ElementNotVisibleError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, HandlerNotInitializedError, type HistoryEntry, type InferStagehandSchema, InvalidAISDKModelFormatError, type JsonSchema, type JsonSchemaDocument, type JsonSchemaProperty, LLMClient, type LLMParsedResponse, type LLMResponse, LLMResponseError, type LLMTool, type LLMUsage, LOG_LEVEL_NAMES, type LoadState, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelProvider, type ObserveOptions, Page, PageNotFoundError, Response$1 as Response, ResponseBodyError, type ResponseInputItem, type ResponseItem, ResponseParseError, 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 StagehandZodObject, type StagehandZodSchema, TimeoutError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, XPathResolutionError, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, isZod3Schema, isZod4Schema, jsonSchemaToZod, loadApiKeyFromEnv, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, toJsonSchema, transformSchema, trimTrailingTextNode, validateZodSchema };
+export { type AISDKCustomProvider, type AISDKProvider, AISdkClient, AVAILABLE_CUA_MODELS, type ActOptions, type ActResult, ActTimeoutError, type Action, type ActionExecutionResult, AgentAbortError, type AgentAction, type AgentCallbacks, type AgentConfig, type AgentContext, type AgentExecuteCallbacks, type AgentExecuteOptions, type AgentExecuteOptionsBase, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentModelConfig, AgentProvider, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentState, type AgentStreamCallbacks, type AgentStreamExecuteOptions, type AgentStreamResult, type AgentType, AnnotatedScreenshotText, type AnthropicClientOptions, 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, ConnectionTimeoutError, type ConsoleListener, ConsoleMessage, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, CuaModelRequiredError, ElementNotVisibleError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, ExtractTimeoutError, type FunctionCallItem, type GoogleServiceAccountCredentials, type GoogleVertexProviderSettings, HandlerNotInitializedError, type HistoryEntry, type InferStagehandSchema, InvalidAISDKModelFormatError, type JsonSchema, type JsonSchemaDocument, type JsonSchemaProperty, LLMClient, type LLMParsedResponse, type LLMResponse, LLMResponseError, type LLMTool, type LLMUsage, LOG_LEVEL_NAMES, type LoadState, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelProvider, type NonStreamingAgentInstance, type ObserveOptions, ObserveTimeoutError, type OpenAIClientOptions, Page, PageNotFoundError, Response$1 as Response, ResponseBodyError, type ResponseInputItem, type ResponseItem, ResponseParseError, 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 StagehandZodObject, type StagehandZodSchema, type StreamingAgentInstance, StreamingCallbacksInNonStreamingModeError, TimeoutError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, XPathResolutionError, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, isZod3Schema, isZod4Schema, jsonSchemaToZod, loadApiKeyFromEnv, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, toJsonSchema, transformSchema, trimTrailingTextNode, validateZodSchema };