@browserbasehq/orca 3.0.0-preview.0

package/dist/index.d.ts

@@ -0,0 +1,1611 @@
+import * as puppeteer_core from 'puppeteer-core';
+import * as patchright_core from 'patchright-core';
+import * as playwright_core from 'playwright-core';
+import Browserbase from '@browserbasehq/sdk';
+import { Protocol } from 'devtools-protocol';
+import { Buffer as Buffer$1 } from 'buffer';
+import { ClientOptions as ClientOptions$2 } from '@anthropic-ai/sdk';
+import { ClientOptions as ClientOptions$1 } from 'openai';
+import { z, ZodType, ZodTypeAny, ZodError } from 'zod/v3';
+import { generateObject, generateText, streamText, streamObject, experimental_generateImage, embed, embedMany, experimental_transcribe, experimental_generateSpeech, LanguageModel, ToolSet } from 'ai';
+import { Client } from '@modelcontextprotocol/sdk/dist/esm/client';
+import { ClientOptions as ClientOptions$3, Client as Client$1 } from '@modelcontextprotocol/sdk/client/index.js';
+
+/**
+ * CDP transport & session multiplexer
+ *
+ * Owns the browser WebSocket and multiplexes flattened Target sessions.
+ * Tracks inflight CDP calls, routes responses to the right session, and forwards events.
+ *
+ * This does not interpret Page/DOM/Runtime semantics — callers own that logic.
+ */
+interface CDPSessionLike {
+    send<R = unknown>(method: string, params?: object): Promise<R>;
+    on<P = unknown>(event: string, handler: (params: P) => void): void;
+    off<P = unknown>(event: string, handler: (params: P) => void): void;
+    close(): Promise<void>;
+    readonly id: string | null;
+}
+type EventHandler = (params: unknown) => void;
+declare class CdpConnection implements CDPSessionLike {
+    private ws;
+    private nextId;
+    private inflight;
+    private eventHandlers;
+    private sessions;
+    readonly id: string | null;
+    private transportCloseHandlers;
+    onTransportClosed(handler: (why: string) => void): void;
+    offTransportClosed(handler: (why: string) => void): void;
+    private emitTransportClosed;
+    private constructor();
+    static connect(wsUrl: string): Promise<CdpConnection>;
+    enableAutoAttach(): Promise<void>;
+    send<R = unknown>(method: string, params?: object): Promise<R>;
+    on<P = unknown>(event: string, handler: (params: P) => void): void;
+    off<P = unknown>(event: string, handler: (params: P) => void): void;
+    close(): Promise<void>;
+    getSession(sessionId: string): CdpSession | undefined;
+    attachToTarget(targetId: string): Promise<CdpSession>;
+    getTargets(): Promise<Array<{
+        targetId: string;
+        type: string;
+        url: string;
+    }>>;
+    private onMessage;
+    _sendViaSession<R = unknown>(sessionId: string, method: string, params?: object): Promise<R>;
+    _onSessionEvent(sessionId: string, event: string, handler: EventHandler): void;
+    _offSessionEvent(sessionId: string, event: string, handler: EventHandler): void;
+    _dispatchToSession(sessionId: string, event: string, params: unknown): void;
+}
+declare class CdpSession implements CDPSessionLike {
+    private readonly root;
+    readonly id: string;
+    constructor(root: CdpConnection, id: string);
+    send<R = unknown>(method: string, params?: object): Promise<R>;
+    on<P = unknown>(event: string, handler: (params: P) => void): void;
+    off<P = unknown>(event: string, handler: (params: P) => void): void;
+    close(): Promise<void>;
+    dispatch(event: string, params: unknown): void;
+}
+
+interface FrameManager {
+    session: CDPSessionLike;
+    frameId: string;
+    pageId: string;
+}
+/**
+ * Frame
+ *
+ * A thin, session-bound handle to a specific DOM frame (by frameId).
+ * All CDP calls in this class go through `this.session`, which MUST be the
+ * owning session for `this.frameId`. Page is responsible for constructing
+ * Frames with the correct session.
+ */
+declare class Frame implements FrameManager {
+    session: CDPSessionLike;
+    frameId: string;
+    pageId: string;
+    /** Owning CDP session id (useful for logs); null for root connection (should not happen for targets) */
+    readonly sessionId: string | null;
+    constructor(session: CDPSessionLike, frameId: string, pageId: string);
+    /** DOM.getNodeForLocation → DOM.describeNode */
+    getNodeAtLocation(x: number, y: number): Promise<Protocol.DOM.Node>;
+    /** CSS selector → DOM.querySelector → DOM.getBoxModel */
+    getLocationForSelector(selector: string): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    /** Accessibility.getFullAXTree (+ recurse into child frames if requested) */
+    getAccessibilityTree(withFrames?: boolean): Promise<Protocol.Accessibility.AXNode[]>;
+    /**
+     * Evaluate a function or expression in this frame's isolated world.
+     * - If a string is provided, treated as a JS expression.
+     * - If a function is provided, it is stringified and invoked with the optional argument.
+     */
+    evaluate<R = unknown, Arg = unknown>(pageFunctionOrExpression: string | ((arg: Arg) => R | Promise<R>), arg?: Arg): Promise<R>;
+    /** Page.captureScreenshot (frame-scoped session) */
+    screenshot(options?: {
+        fullPage?: boolean;
+        clip?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }): Promise<string>;
+    /** Child frames via Page.getFrameTree */
+    childFrames(): Promise<Frame[]>;
+    /** Wait for a lifecycle state (load/domcontentloaded/networkidle) */
+    waitForLoadState(state?: "load" | "domcontentloaded" | "networkidle"): Promise<void>;
+    /** Simple placeholder for your own locator abstraction */
+    locator(selector: string, options?: {
+        deep?: boolean;
+        depth?: number;
+    }): Locator;
+    /** Create/get an isolated world for this frame and return its executionContextId */
+    private getExecutionContextId;
+}
+
+type MouseButton = "left" | "right" | "middle";
+/**
+ * Locator
+ *
+ * Purpose:
+ * A small, CDP-based element interaction helper scoped to a specific `Frame`.
+ * It resolves a CSS/XPath selector inside the frame’s **isolated world**, and then
+ * performs low-level actions (click, type, select) using DOM/Runtime/Input
+ * protocol domains with minimal abstraction.
+ *
+ * Key change:
+ * - Prefer **objectId**-based CDP calls (scroll, geometry) to avoid brittle
+ *   frontend nodeId mappings. nodeId is resolved on a best-effort basis and
+ *   returned for compatibility, but actions do not depend on it.
+ *
+ * Notes:
+ * - Resolution is lazy: every action resolves the selector again.
+ * - Uses `Page.createIsolatedWorld` so evaluation is isolated from page scripts.
+ * - Releases remote objects (`Runtime.releaseObject`) where appropriate.
+ */
+declare class Locator {
+    private readonly frame;
+    private readonly selector;
+    private readonly options?;
+    constructor(frame: Frame, selector: string, options?: {
+        deep?: boolean;
+        depth?: number;
+    });
+    /** Return the owning Frame for this locator (typed accessor, no private access). */
+    getFrame(): Frame;
+    /**
+     * Set files on an <input type="file"> element.
+     *
+     * Mirrors Playwright's Locator.setInputFiles basics:
+     * - Accepts file path(s) or payload object(s) { name, mimeType, buffer }.
+     * - Uses CDP DOM.setFileInputFiles under the hood.
+     * - Best‑effort dispatches change/input via CDP (Chrome does by default).
+     * - Passing an empty array clears the selection.
+     */
+    setInputFiles(files: string | string[] | {
+        name: string;
+        mimeType: string;
+        buffer: ArrayBuffer | Uint8Array | Buffer$1 | string;
+    } | Array<{
+        name: string;
+        mimeType: string;
+        buffer: ArrayBuffer | Uint8Array | Buffer$1 | string;
+    }>): Promise<void>;
+    /**
+     * Return the DOM backendNodeId for this locator's target element.
+     * Useful for identity comparisons without needing element handles.
+     */
+    backendNodeId(): Promise<Protocol.DOM.BackendNodeId>;
+    /**
+     * Return the center of the element's bounding box in the owning frame's viewport
+     * (CSS pixels), rounded to integers. Scrolls into view best-effort.
+     */
+    centroid(): Promise<{
+        x: number;
+        y: number;
+    }>;
+    /**
+     * Highlight the element's bounding box using the CDP Overlay domain.
+     * - Scrolls element into view best-effort.
+     * - Shows a semi-transparent overlay briefly, then hides it.
+     */
+    highlight(options?: {
+        durationMs?: number;
+        borderColor?: {
+            r: number;
+            g: number;
+            b: number;
+            a?: number;
+        };
+        contentColor?: {
+            r: number;
+            g: number;
+            b: number;
+            a?: number;
+        };
+    }): Promise<void>;
+    /**
+     * Click the element at its visual center.
+     * Steps:
+     *  1) Resolve selector to { objectId } in the frame world.
+     *  2) Scroll into view via `DOM.scrollIntoViewIfNeeded({ objectId })`.
+     *  3) Read geometry via `DOM.getBoxModel({ objectId })` → compute a center point.
+     *  4) Synthesize mouse press + release via `Input.dispatchMouseEvent`.
+     */
+    click(options?: {
+        button?: MouseButton;
+        clickCount?: number;
+    }): Promise<void>;
+    /**
+     * Dispatch a DOM 'click' MouseEvent on the element itself.
+     * - Does not synthesize real pointer input; directly dispatches an event.
+     * - Useful for elements that rely on click handlers without needing hit-testing.
+     */
+    sendClickEvent(options?: {
+        bubbles?: boolean;
+        cancelable?: boolean;
+        composed?: boolean;
+        detail?: number;
+    }): Promise<void>;
+    /**
+     * Scroll the element vertically to a given percentage (0–100).
+     * - If the element is <html> or <body>, scrolls the window/document.
+     * - Otherwise, scrolls the element itself via element.scrollTo.
+     */
+    scrollTo(percent: number | string): Promise<void>;
+    /**
+     * Fill an input/textarea/contenteditable element.
+     * - Sets the value/text directly in DOM.
+     * - Dispatches `input` and `change` events to mimic user input.
+     * - Releases the underlying `objectId` afterwards to avoid leaks.
+     */
+    fill(value: string): Promise<void>;
+    /**
+     * Type text into the element (focuses first).
+     * - Focus via element.focus() in page JS (no DOM.focus(nodeId)).
+     * - If no delay, uses `Input.insertText` for efficiency.
+     * - With delay, synthesizes `keyDown`/`keyUp` per character.
+     */
+    type(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    /**
+     * Select one or more options on a `<select>` element.
+     * Returns the values actually selected after the operation.
+     */
+    selectOption(values: string | string[]): Promise<string[]>;
+    /**
+     * Return true if the element is attached and visible (rough heuristic).
+     */
+    isVisible(): Promise<boolean>;
+    /**
+     * Return true if the element is an input[type=checkbox|radio] and is checked.
+     * Also considers aria-checked for ARIA widgets.
+     */
+    isChecked(): Promise<boolean>;
+    /**
+     * Return the element's input value (for input/textarea/select/contenteditable).
+     */
+    inputValue(): Promise<string>;
+    /**
+     * Return the element's textContent (raw, not innerText).
+     */
+    textContent(): Promise<string>;
+    /**
+     * Return the element's innerHTML string.
+     */
+    innerHtml(): Promise<string>;
+    /**
+     * Return the element's innerText (layout-aware, visible text).
+     */
+    innerText(): Promise<string>;
+    /**
+     * For API parity, returns the same locator (querySelector already returns the first match).
+     */
+    first(): Locator;
+    /**
+     * Resolve `this.selector` within the frame to `{ objectId, nodeId? }`:
+     * - Ensures Runtime/DOM are enabled.
+     * - Creates (or reuses) an isolated world for this frame.
+     * - Evaluates a CSS or XPath query in that isolated world.
+     * - Best-effort: attempts to convert `objectId` to `nodeId`; failure is non-fatal.
+     *
+     * - For XPath: first try page-side resolver (__stagehandV3__.resolveSimpleXPath).
+     *   If it returns null (e.g. closed DSD not captured), fall back to CDP DOM with
+     *   `pierce: true` to traverse closed shadow roots and resolve by backendNodeId.
+     */
+    resolveNode(): Promise<{
+        nodeId: Protocol.DOM.NodeId | null;
+        objectId: Protocol.Runtime.RemoteObjectId;
+    }>;
+    /**
+     * CDP fallback for XPath resolution that needs to cross *closed* shadow roots
+     * created via Declarative Shadow DOM (no attachShadow call to intercept).
+     *
+     * Strategy:
+     *   - Fetch full DOM with `pierce: true` so closed shadow roots are included.
+     *   - Run a small, tolerant XPath stepper over the CDP node tree:
+     *       • supports absolute paths like `/html/body/...`
+     *       • supports `//` descendant jumps
+     *       • supports `tag[n]` numeric predicates per sibling group
+     *       • supports `*`
+     *   - Resolve the winning backendNodeId to an objectId for downstream actions.
+     */
+    private resolveViaDomPierceXPath;
+    /** Compute a center point from a BoxModel content quad */
+    private centerFromBoxContent;
+}
+
+/**
+ * DeepLocatorDelegate: a lightweight wrapper that looks like a Locator and
+ * resolves to the correct frame/element on each call using hop/deep-XPath logic.
+ *
+ * Returned by `page.deepLocator()` for ergonomic, await-free chaining:
+ *   page.deepLocator('iframe#ifrA >> #btn').click()
+ */
+declare class DeepLocatorDelegate {
+    private readonly page;
+    private readonly root;
+    private readonly selector;
+    constructor(page: Page, root: Frame, selector: string);
+    private real;
+    click(options?: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+    }): Promise<void>;
+    fill(value: string): Promise<void>;
+    type(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    selectOption(values: string | string[]): Promise<string[]>;
+    scrollTo(percent: number | string): Promise<void>;
+    isVisible(): Promise<boolean>;
+    isChecked(): Promise<boolean>;
+    inputValue(): Promise<string>;
+    textContent(): Promise<string>;
+    innerHtml(): Promise<string>;
+    innerText(): Promise<string>;
+    centroid(): Promise<{
+        x: number;
+        y: number;
+    }>;
+    backendNodeId(): Promise<number>;
+    highlight(options?: {
+        durationMs?: number;
+        borderColor?: {
+            r: number;
+            g: number;
+            b: number;
+            a?: number;
+        };
+        contentColor?: {
+            r: number;
+            g: number;
+            b: number;
+            a?: number;
+        };
+    }): Promise<void>;
+    sendClickEvent(options?: {
+        bubbles?: boolean;
+        cancelable?: boolean;
+        composed?: boolean;
+        detail?: number;
+    }): Promise<void>;
+    first(): this;
+}
+
+/**
+ * FrameLocator: resolves iframe elements to their child Frames and allows
+ * creating locators scoped to that frame. Supports chaining.
+ */
+declare class FrameLocator {
+    private readonly parent?;
+    private readonly selector;
+    private readonly page;
+    private readonly root?;
+    constructor(page: Page, selector: string, parent?: FrameLocator, root?: Frame);
+    /** Create a nested FrameLocator under this one. */
+    frameLocator(selector: string): FrameLocator;
+    /** Resolve to the concrete Frame for this FrameLocator chain. */
+    resolveFrame(): Promise<Frame>;
+    /** Return a Locator scoped to this frame. Methods delegate to the frame lazily. */
+    locator(selector: string): LocatorDelegate;
+}
+/** A small delegating wrapper that resolves the frame lazily per call. */
+declare class LocatorDelegate {
+    private readonly fl;
+    private readonly sel;
+    constructor(fl: FrameLocator, sel: string);
+    private real;
+    click(options?: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+    }): Promise<void>;
+    fill(value: string): Promise<void>;
+    type(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    selectOption(values: string | string[]): Promise<string[]>;
+    scrollTo(percent: number | string): Promise<void>;
+    isVisible(): Promise<boolean>;
+    isChecked(): Promise<boolean>;
+    inputValue(): Promise<string>;
+    textContent(): Promise<string>;
+    innerHtml(): Promise<string>;
+    innerText(): Promise<string>;
+    first(): LocatorDelegate;
+}
+
+declare class Page {
+    private readonly conn;
+    private readonly mainSession;
+    private readonly _targetId;
+    /** Every CDP child session this page owns (top-level + adopted OOPIF sessions). */
+    private readonly sessions;
+    /** Unified truth for frame topology + ownership. */
+    private readonly registry;
+    /** A convenience wrapper bound to the current main frame id (top-level session). */
+    private mainFrameWrapper;
+    /** Compact ordinal per frameId (used by snapshot encoding). */
+    private frameOrdinals;
+    private nextOrdinal;
+    /** cache Frames per frameId so everyone uses the same one */
+    private readonly frameCache;
+    /** Stable id for Frames created by this Page (use top-level TargetId). */
+    private readonly pageId;
+    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): 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;
+    /**
+     * 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.
+     */
+    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;
+    targetId(): string;
+    mainFrameId(): string;
+    mainFrame(): Frame;
+    /**
+     * Close this top-level page (tab). Best-effort via Target.closeTarget.
+     */
+    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[];
+    /**
+     * Navigate the page; optionally wait for a lifecycle state.
+     * Waits on the **current** main frame and follows root swaps during navigation.
+     */
+    goto(url: string, options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Reload the page; optionally wait for a lifecycle state.
+     */
+    reload(options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+        ignoreCache?: boolean;
+    }): Promise<void>;
+    /**
+     * Navigate back in history if possible; optionally wait for a lifecycle state.
+     */
+    goBack(options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Navigate forward in history if possible; optionally wait for a lifecycle state.
+     */
+    goForward(options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Return the current page URL (from navigation history).
+     */
+    url(): Promise<string>;
+    /**
+     * 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 (delegated to the current main frame).
+     */
+    screenshot(options?: {
+        fullPage?: boolean;
+    }): Promise<string>;
+    /**
+     * Create a locator bound to the current main frame.
+     */
+    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 isolated world.
+     * - If a string is provided, it is treated as a JS expression.
+     * - If a function is provided, it is stringified and invoked with the optional argument.
+     * - The return value should be JSON-serializable. Non-serializable objects will
+     *   best-effort serialize via JSON.stringify inside the page context.
+     */
+    evaluate<R = unknown, Arg = unknown>(pageFunctionOrExpression: string | ((arg: Arg) => R | Promise<R>), arg?: Arg): Promise<R>;
+    /**
+     * Force the page viewport to an exact CSS size and device scale factor.
+     * Ensures screenshots match width x height pixels when deviceScaleFactor = 1.
+     */
+    setViewportSize(width: number, height: number, options?: {
+        deviceScaleFactor?: number;
+    }): Promise<void>;
+    /**
+     * Click at absolute page coordinates (CSS pixels).
+     * Dispatches mouseMoved → mousePressed → mouseReleased via CDP Input domain
+     * on the top-level page target's session. Coordinates are relative to the
+     * viewport origin (top-left). Does not scroll.
+     */
+    click(x: number, y: number, options: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+        returnXpath: true;
+    }): Promise<string>;
+    click(x: number, y: number, options?: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+        returnXpath?: false;
+    }): Promise<void>;
+    click(x: number, y: number, options: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+        returnXpath: boolean;
+    }): Promise<void | string>;
+    scroll(x: number, y: number, deltaX: number, deltaY: number, options: {
+        returnXpath: true;
+    }): Promise<string>;
+    scroll(x: number, y: number, deltaX: number, deltaY: number, options?: {
+        returnXpath?: false;
+    }): Promise<void>;
+    scroll(x: number, y: number, deltaX: number, deltaY: number, options: {
+        returnXpath: boolean;
+    }): Promise<void | string>;
+    /**
+     * Drag from (fromX, fromY) to (toX, toY) using mouse events.
+     * Sends mouseMoved → mousePressed → mouseMoved (steps) → mouseReleased.
+     */
+    dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options: {
+        button?: "left" | "right" | "middle";
+        steps?: number;
+        delay?: number;
+        returnXpath: true;
+    }): Promise<[string, string]>;
+    dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options?: {
+        button?: "left" | "right" | "middle";
+        steps?: number;
+        delay?: number;
+        returnXpath?: false;
+    }): Promise<void>;
+    dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options: {
+        button?: "left" | "right" | "middle";
+        steps?: number;
+        delay?: number;
+        returnXpath: boolean;
+    }): Promise<void | [string, string]>;
+    /**
+     * Type a string by dispatching keyDown/keyUp events per character.
+     * Focus must already be on the desired element. Uses CDP Input.dispatchKeyEvent
+     * and never falls back to Input.insertText. Optional delay applies between
+     * successive characters.
+     */
+    type(text: string, options?: {
+        delay?: number;
+        withMistakes?: boolean;
+    }): Promise<void>;
+    /**
+     * Press a single key (keyDown then keyUp). For printable characters,
+     * uses the text path on keyDown; for named keys, sets key/code/VK.
+     */
+    keyPress(key: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    /**
+     * Create an isolated world for the **current** main frame and return its context id.
+     */
+    private createIsolatedWorldForCurrentMain;
+    /**
+     * Wait until the **current** main frame reaches a lifecycle state.
+     * - Fast path via `document.readyState`.
+     * - Event path listens at the session level and compares incoming `frameId`
+     *   to `mainFrameId()` **at event time** to follow root swaps.
+     */
+    private waitForMainLoadState;
+}
+
+declare const AvailableModelSchema: z.ZodEnum<["gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "o4-mini", "o3", "o3-mini", "o1", "o1-mini", "gpt-4o", "gpt-4o-mini", "gpt-4o-2024-08-06", "gpt-4.5-preview", "o1-preview", "claude-3-5-sonnet-latest", "claude-3-5-sonnet-20241022", "claude-3-5-sonnet-20240620", "claude-3-7-sonnet-latest", "claude-3-7-sonnet-20250219", "cerebras-llama-3.3-70b", "cerebras-llama-3.1-8b", "groq-llama-3.3-70b-versatile", "groq-llama-3.3-70b-specdec", "gemini-1.5-flash", "gemini-1.5-pro", "gemini-1.5-flash-8b", "gemini-2.0-flash-lite", "gemini-2.0-flash", "gemini-2.5-flash-preview-04-17", "gemini-2.5-pro-preview-03-25"]>;
+type AvailableModel = z.infer<typeof AvailableModelSchema> | string;
+type ModelProvider = "openai" | "anthropic" | "cerebras" | "groq" | "google" | "aisdk";
+type ClientOptions = ClientOptions$1 | ClientOptions$2;
+type ModelConfiguration = AvailableModel | (ClientOptions & {
+    modelName: AvailableModel;
+});
+interface AnthropicJsonSchemaObject {
+    definitions?: {
+        MySchema?: {
+            properties?: Record<string, unknown>;
+            required?: string[];
+        };
+    };
+    properties?: Record<string, unknown>;
+    required?: string[];
+}
+
+interface LLMTool {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+
+type LogLevel = 0 | 1 | 2;
+/**
+ * Mapping between numeric log levels and their names
+ *
+ * 0 - error/warn - Critical issues or important warnings
+ * 1 - info - Standard information messages
+ * 2 - debug - Detailed information for debugging
+ */
+declare const LOG_LEVEL_NAMES: Record<LogLevel, string>;
+type LogLine = {
+    id?: string;
+    category?: string;
+    message: string;
+    level?: LogLevel;
+    timestamp?: string;
+    auxiliary?: {
+        [key: string]: {
+            value: string;
+            type: "object" | "string" | "html" | "integer" | "float" | "boolean";
+        };
+    };
+};
+type Logger = (logLine: LogLine) => void;
+
+interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: ChatMessageContent;
+}
+type ChatMessageContent = string | (ChatMessageImageContent | ChatMessageTextContent)[];
+interface ChatMessageImageContent {
+    type: string;
+    image_url?: {
+        url: string;
+    };
+    text?: string;
+    source?: {
+        type: string;
+        media_type: string;
+        data: string;
+    };
+}
+interface ChatMessageTextContent {
+    type: string;
+    text: string;
+}
+declare const AnnotatedScreenshotText = "This is a screenshot of the current page state with the elements annotated on it. Each element id is annotated with a number to the top left of it. Duplicate annotations at the same location are under each other vertically.";
+interface ChatCompletionOptions {
+    messages: ChatMessage[];
+    temperature?: number;
+    top_p?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    image?: {
+        buffer: Buffer;
+        description?: string;
+    };
+    response_model?: {
+        name: string;
+        schema: ZodType;
+    };
+    tools?: LLMTool[];
+    tool_choice?: "auto" | "none" | "required";
+    maxTokens?: number;
+    requestId?: string;
+}
+type LLMResponse = {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: {
+        index: number;
+        message: {
+            role: string;
+            content: string | null;
+            tool_calls: {
+                id: string;
+                type: string;
+                function: {
+                    name: string;
+                    arguments: string;
+                };
+            }[];
+        };
+        finish_reason: string;
+    }[];
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+};
+interface CreateChatCompletionOptions {
+    options: ChatCompletionOptions;
+    logger: (message: LogLine) => void;
+    retries?: number;
+}
+declare abstract class LLMClient {
+    type: "openai" | "anthropic" | "cerebras" | "groq" | (string & {});
+    modelName: AvailableModel | (string & {});
+    hasVision: boolean;
+    clientOptions: ClientOptions;
+    userProvidedInstructions?: string;
+    constructor(modelName: AvailableModel, userProvidedInstructions?: string);
+    abstract createChatCompletion<T = LLMResponse & {
+        usage?: LLMResponse["usage"];
+    }>(options: CreateChatCompletionOptions): Promise<T>;
+    generateObject: typeof generateObject;
+    generateText: typeof generateText;
+    streamText: typeof streamText;
+    streamObject: typeof streamObject;
+    generateImage: typeof experimental_generateImage;
+    embed: typeof embed;
+    embedMany: typeof embedMany;
+    transcribe: typeof experimental_transcribe;
+    generateSpeech: typeof experimental_generateSpeech;
+    getLanguageModel?(): LanguageModel;
+}
+
+type V3Env = "LOCAL" | "BROWSERBASE";
+/** Local launch options for V3 (chrome-launcher + CDP).
+ * Matches v2 shape where feasible; unsupported fields are accepted but ignored.
+ */
+interface LocalBrowserLaunchOptions {
+    args?: string[];
+    executablePath?: string;
+    userDataDir?: string;
+    preserveUserDataDir?: boolean;
+    headless?: boolean;
+    devtools?: boolean;
+    chromiumSandbox?: boolean;
+    ignoreDefaultArgs?: boolean | string[];
+    proxy?: {
+        server: string;
+        bypass?: string;
+        username?: string;
+        password?: string;
+    };
+    locale?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    deviceScaleFactor?: number;
+    hasTouch?: boolean;
+    ignoreHTTPSErrors?: boolean;
+    cdpUrl?: string;
+    connectTimeoutMs?: number;
+    downloadsPath?: string;
+    acceptDownloads?: boolean;
+}
+/** Constructor options for V3 */
+interface V3Options {
+    env: V3Env;
+    apiKey?: string;
+    projectId?: string;
+    /**
+     * Optional: fine-tune Browserbase session creation or resume an existing session.
+     */
+    browserbaseSessionCreateParams?: Omit<Browserbase.Sessions.SessionCreateParams, "projectId"> & {
+        projectId?: string;
+    };
+    browserbaseSessionID?: string;
+    localBrowserLaunchOptions?: LocalBrowserLaunchOptions;
+    model?: ModelConfiguration;
+    llmClient?: LLMClient;
+    systemPrompt?: string;
+    logInferenceToFile?: boolean;
+    experimental?: boolean;
+    verbose?: 0 | 1 | 2;
+    selfHeal?: boolean;
+    /** Disable pino logging backend (useful for tests or minimal environments). */
+    disablePino?: boolean;
+    /** Optional external logger hook for integrating with host apps. */
+    logger?: (line: LogLine) => void;
+    /** Show a visual cursor overlay that follows our mouse events. */
+    includeCursor?: boolean;
+    /** Directory used to persist cached actions for act(). */
+    cacheDir?: string;
+    domSettleTimeout?: number;
+}
+type PlaywrightPage = playwright_core.Page;
+type PatchrightPage = patchright_core.Page;
+type PuppeteerPage = puppeteer_core.Page;
+interface ActOptions$1 {
+    model?: ModelConfiguration;
+    variables?: Record<string, string>;
+    timeout?: number;
+    page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+}
+interface ExtractOptions$1 {
+    model?: ModelConfiguration;
+    timeout?: number;
+    selector?: string;
+    page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+}
+declare const defaultExtractSchema: z.ZodObject<{
+    extraction: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    extraction?: string;
+}, {
+    extraction?: string;
+}>;
+declare const pageTextSchema: z.ZodObject<{
+    pageText: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    pageText?: string;
+}, {
+    pageText?: string;
+}>;
+interface ObserveOptions$1 {
+    model?: ModelConfiguration;
+    timeout?: number;
+    selector?: string;
+    page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+}
+type LoadState = "load" | "domcontentloaded" | "networkidle";
+interface V3Metrics {
+    actPromptTokens: number;
+    actCompletionTokens: number;
+    actInferenceTimeMs: number;
+    extractPromptTokens: number;
+    extractCompletionTokens: number;
+    extractInferenceTimeMs: number;
+    observePromptTokens: number;
+    observeCompletionTokens: number;
+    observeInferenceTimeMs: number;
+    agentPromptTokens: number;
+    agentCompletionTokens: number;
+    agentInferenceTimeMs: number;
+    totalPromptTokens: number;
+    totalCompletionTokens: number;
+    totalInferenceTimeMs: number;
+}
+declare enum V3FunctionName {
+    ACT = "ACT",
+    EXTRACT = "EXTRACT",
+    OBSERVE = "OBSERVE",
+    AGENT = "AGENT"
+}
+
+/**
+ * V3Context
+ *
+ * Owns the root CDP connection and wires Target/Page events into Page.
+ * Maintains one Page per top-level target, adopts OOPIF child sessions into the owner Page,
+ * and tracks target→page and (root) frame→target mappings for lookups.
+ *
+ * IMPORTANT: FrameId → session ownership is managed inside Page (via its FrameRegistry).
+ * Context never “guesses” owners; it simply forwards events (with the emitting session)
+ * so Page can record the correct owner at event time.
+ */
+declare class V3Context {
+    readonly conn: CdpConnection;
+    private readonly includeCursor;
+    private readonly env;
+    private constructor();
+    private readonly _piercerInstalled;
+    private _lastPopupSignalAt;
+    private sessionKey;
+    private readonly _sessionInit;
+    private pagesByTarget;
+    private mainFrameToTarget;
+    private sessionOwnerPage;
+    private frameOwnerPage;
+    private pendingOopifByMainFrame;
+    private createdAtByTarget;
+    private typeByTarget;
+    private _pageOrder;
+    /**
+     * Create a Context for a given CDP websocket URL and bootstrap target wiring.
+     */
+    static create(wsUrl: string, opts?: {
+        includeCursor?: boolean;
+        env?: "LOCAL" | "BROWSERBASE";
+    }): Promise<V3Context>;
+    /**
+     * Wait until at least one top-level Page has been created and registered.
+     * We poll internal maps that bootstrap/onAttachedToTarget populate.
+     */
+    private waitForFirstTopLevelPage;
+    private ensurePiercer;
+    /** Mark a page target as the most-recent one (active). */
+    private _pushActive;
+    /** Remove a page target from the recency list (used on close). */
+    private _removeFromOrder;
+    /** Return the current active Page (most-recent page that still exists). */
+    activePage(): Page | undefined;
+    /**
+     * Return top-level `Page`s (oldest → newest). OOPIF targets are not included.
+     */
+    pages(): Page[];
+    /**
+     * Resolve an owning `Page` by the **top-level main frame id**.
+     * Note: child (OOPIF) roots are intentionally not present in this mapping.
+     */
+    resolvePageByMainFrameId(frameId: string): Page | undefined;
+    /**
+     * Serialize the full frame tree for a given top-level main frame id.
+     */
+    getFullFrameTreeByMainFrameId(rootMainFrameId: string): Promise<Protocol.Page.FrameTree>;
+    /**
+     * Create a new top-level page (tab) with the given URL and return its Page object.
+     * Waits until the target is attached and registered.
+     */
+    newPage(url?: string): Promise<Page>;
+    /**
+     * Close CDP and clear all mappings. Best-effort cleanup.
+     */
+    close(): Promise<void>;
+    /**
+     * Bootstrap target lifecycle:
+     * - Attach to existing targets.
+     * - Attach on `Target.targetCreated` (fallback for OOPIFs).
+     * - Handle auto-attach events.
+     * - Clean up on detach/destroy.
+     */
+    private bootstrap;
+    /**
+     * Handle a newly attached target (top-level or potential OOPIF):
+     * - Enable Page domain and lifecycle events.
+     * - If top-level → create Page, wire listeners, resume.
+     * - Else → probe child root frame id via `Page.getFrameTree` and adopt immediately
+     *   if the parent is known; otherwise stage until parent `frameAttached`.
+     * - Resume the target only after listeners are wired.
+     */
+    private onAttachedToTarget;
+    /**
+     * Detach handler:
+     * - Remove child session ownership and prune its subtree.
+     * - If a top-level target, cleanup its `Page` and mappings.
+     * - Drop any staged child for this session.
+     */
+    private onDetachedFromTarget;
+    /**
+     * Cleanup a top-level Page by target id, removing its root and staged children.
+     */
+    private cleanupByTarget;
+    /**
+     * Wire Page-domain frame events for a session into the owning Page & mappings.
+     * We forward the *emitting session* with every event so Page can stamp ownership precisely.
+     */
+    private installFrameEventBridges;
+    /**
+     * Register that a session belongs to a Page (used by event routing).
+     */
+    private wireSessionToOwnerPage;
+    /**
+     * Utility: reverse-lookup the top-level target id that owns a given Page.
+     */
+    private findTargetIdByPage;
+    private _notePopupSignal;
+    /**
+     * Await the current active page, waiting briefly if a popup/open was just triggered.
+     * Normal path returns immediately; popup path waits up to timeoutMs for the new page.
+     */
+    awaitActivePage(timeoutMs?: number): Promise<Page>;
+}
+
+interface AgentAction {
+    type: string;
+    reasoning?: string;
+    taskCompleted?: boolean;
+    action?: string;
+    timeMs?: number;
+    pageText?: string;
+    pageUrl?: string;
+    instruction?: string;
+    [key: string]: unknown;
+}
+interface AgentResult {
+    success: boolean;
+    message: string;
+    actions: AgentAction[];
+    completed: boolean;
+    metadata?: Record<string, unknown>;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+        inference_time_ms: number;
+    };
+}
+interface AgentOptions {
+    maxSteps?: number;
+    autoScreenshot?: boolean;
+    waitBetweenActions?: number;
+    context?: string;
+}
+interface AgentExecuteOptions extends AgentOptions {
+    instruction: string;
+}
+type AgentProviderType = "openai" | "anthropic";
+interface AgentClientOptions {
+    apiKey: string;
+    organization?: string;
+    baseURL?: string;
+    defaultMaxSteps?: number;
+    [key: string]: unknown;
+}
+type AgentType = "openai" | "anthropic";
+interface AgentExecutionOptions {
+    options: AgentExecuteOptions;
+    logger: (message: LogLine) => void;
+    retries?: number;
+}
+interface AgentHandlerOptions {
+    modelName: string;
+    clientOptions?: Record<string, unknown>;
+    userProvidedInstructions?: string;
+    agentType: AgentType;
+    experimental?: boolean;
+}
+interface ActionExecutionResult {
+    success: boolean;
+    error?: string;
+    data?: unknown;
+}
+interface ToolUseItem extends ResponseItem {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface AnthropicMessage {
+    role: string;
+    content: string | Array<AnthropicContentBlock>;
+}
+interface AnthropicContentBlock {
+    type: string;
+    [key: string]: unknown;
+}
+interface AnthropicTextBlock extends AnthropicContentBlock {
+    type: "text";
+    text: string;
+}
+interface AnthropicToolResult {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string | Array<AnthropicContentBlock>;
+}
+interface ResponseItem {
+    type: string;
+    id: string;
+    [key: string]: unknown;
+}
+interface ComputerCallItem extends ResponseItem {
+    type: "computer_call";
+    call_id: string;
+    action: {
+        type: string;
+        [key: string]: unknown;
+    };
+    pending_safety_checks?: Array<{
+        id: string;
+        code: string;
+        message: string;
+    }>;
+}
+interface FunctionCallItem extends ResponseItem {
+    type: "function_call";
+    call_id: string;
+    name: string;
+    arguments: string;
+}
+type ResponseInputItem = {
+    role: string;
+    content: string;
+} | {
+    type: "computer_call_output";
+    call_id: string;
+    output: {
+        type: "input_image";
+        image_url: string;
+        current_url?: string;
+        error?: string;
+        [key: string]: unknown;
+    } | string;
+    acknowledged_safety_checks?: Array<{
+        id: string;
+        code: string;
+        message: string;
+    }>;
+} | {
+    type: "function_call_output";
+    call_id: string;
+    output: string;
+};
+interface AgentInstance {
+    execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
+}
+
+interface ActOptions {
+    action: string;
+    model?: ModelConfiguration;
+    variables?: Record<string, string>;
+    domSettleTimeoutMs?: number;
+    timeoutMs?: number;
+    iframes?: boolean;
+    frameId?: string;
+}
+interface ActResult {
+    success: boolean;
+    message: string;
+    actionDescription: string;
+    actions: Action[];
+}
+interface ExtractOptions<T extends z.AnyZodObject> {
+    instruction?: string;
+    schema?: T;
+    model?: ModelConfiguration;
+    domSettleTimeoutMs?: number;
+    /**
+     * @deprecated The `useTextExtract` parameter has no effect in this version of Stagehand and will be removed in later versions.
+     */
+    useTextExtract?: boolean;
+    selector?: string;
+    iframes?: boolean;
+    frameId?: string;
+}
+type ExtractResult<T extends z.AnyZodObject> = z.infer<T>;
+interface ObserveOptions {
+    instruction?: string;
+    model?: ModelConfiguration;
+    domSettleTimeoutMs?: number;
+    returnAction?: boolean;
+    selector?: string;
+    /**
+     * @deprecated The `onlyVisible` parameter has no effect in this version of Stagehand and will be removed in later versions.
+     */
+    onlyVisible?: boolean;
+    drawOverlay?: boolean;
+    iframes?: boolean;
+    frameId?: string;
+}
+interface Action {
+    selector: string;
+    description: string;
+    backendNodeId?: number;
+    method?: string;
+    arguments?: string[];
+}
+/**
+ * Configuration for agent functionality
+ */
+interface AgentConfig {
+    /**
+     * The provider to use for agent functionality
+     */
+    provider?: AgentProviderType;
+    /**
+     * The model to use for agent functionality
+     */
+    model?: string;
+    /**
+     * The model to use for tool execution (observe/act calls within agent tools).
+     * If not specified, inherits from the main model configuration.
+     * Format: "provider/model" (e.g., "openai/gpt-4o-mini", "google/gemini-2.0-flash-exp")
+     */
+    executionModel?: string;
+    /**
+     * Custom instructions to provide to the agent
+     */
+    instructions?: string;
+    /**
+     * Additional options to pass to the agent client
+     */
+    options?: Record<string, unknown>;
+    /**
+     * MCP integrations - Array of Client objects
+     */
+    integrations?: (Client | string)[];
+    /**
+     * Tools passed to the agent client
+     */
+    tools?: ToolSet;
+}
+interface HistoryEntry {
+    method: "act" | "extract" | "observe" | "navigate";
+    parameters: unknown;
+    result: unknown;
+    timestamp: string;
+}
+/**
+ * Represents a path through a Zod schema from the root object down to a
+ * particular field. The `segments` array describes the chain of keys/indices.
+ *
+ * - **String** segments indicate object property names.
+ * - **Number** segments indicate array indices.
+ *
+ * For example, `["users", 0, "homepage"]` might describe reaching
+ * the `homepage` field in `schema.users[0].homepage`.
+ */
+interface ZodPathSegments {
+    /**
+     * The ordered list of keys/indices leading from the schema root
+     * to the targeted field.
+     */
+    segments: Array<string | number>;
+}
+
+type AgentReplayStep = AgentReplayActStep | AgentReplayFillFormStep | AgentReplayGotoStep | AgentReplayScrollStep | AgentReplayWaitStep | AgentReplayNavBackStep | {
+    type: string;
+    [key: string]: unknown;
+};
+interface AgentReplayActStep {
+    type: "act";
+    instruction: string;
+    actions?: Action[];
+    actionDescription?: string;
+    message?: string;
+    timeout?: number;
+}
+interface AgentReplayFillFormStep {
+    type: "fillForm";
+    fields?: Array<{
+        action: string;
+        value: string;
+    }>;
+    observeResults?: Action[];
+    actions?: Action[];
+}
+interface AgentReplayGotoStep {
+    type: "goto";
+    url: string;
+    waitUntil?: LoadState;
+}
+interface AgentReplayScrollStep {
+    type: "scroll";
+    deltaX?: number;
+    deltaY?: number;
+    anchor?: {
+        x: number;
+        y: number;
+    };
+}
+interface AgentReplayWaitStep {
+    type: "wait";
+    timeMs: number;
+}
+interface AgentReplayNavBackStep {
+    type: "navback";
+    waitUntil?: LoadState;
+}
+
+/**
+ * V3
+ *
+ * Purpose:
+ * A high-level orchestrator for Stagehand V3. Abstracts away whether the browser
+ * runs **locally via Chrome** or remotely on **Browserbase**, and exposes simple
+ * entrypoints (`act`, `extract`, `observe`) that delegate to the corresponding
+ * handler classes.
+ *
+ * Responsibilities:
+ * - Bootstraps Chrome or Browserbase, ensures a working CDP WebSocket, and builds a `V3Context`.
+ * - Manages lifecycle: init, context access, cleanup.
+ * - Bridges external page objects (Playwright/Puppeteer) into internal frameIds for handlers.
+ * - Provides a stable API surface for downstream code regardless of runtime environment.
+ */
+declare class V3 {
+    private readonly opts;
+    private state;
+    private actHandler;
+    private extractHandler;
+    private observeHandler;
+    private ctx;
+    llmClient: LLMClient;
+    private modelName;
+    private modelClientOptions;
+    private llmProvider;
+    private readonly domSettleTimeoutMs?;
+    private _isClosing;
+    private _onCdpClosed;
+    readonly experimental: boolean;
+    readonly logInferenceToFile: boolean;
+    private externalLogger?;
+    verbose: 0 | 1 | 2;
+    private _history;
+    private readonly instanceId;
+    private static _processGuardsInstalled;
+    private static _instances;
+    private cacheDir?;
+    private _agentReplayRecording;
+    v3Metrics: V3Metrics;
+    /**
+     * Async property for metrics so callers can `await v3.metrics`.
+     * Returning a Promise future-proofs async aggregation/storage.
+     */
+    get metrics(): Promise<V3Metrics>;
+    private cloneForCache;
+    private beginAgentReplayRecording;
+    private endAgentReplayRecording;
+    private discardAgentReplayRecording;
+    private isAgentReplayRecording;
+    isAgentReplayActive(): boolean;
+    recordAgentReplayStep(step: AgentReplayStep): void;
+    /**
+     * Async property for history so callers can `await v3.history`.
+     * Returns a frozen copy to avoid external mutation.
+     */
+    get history(): Promise<ReadonlyArray<HistoryEntry>>;
+    addToHistory(method: HistoryEntry["method"], parameters: unknown, result?: unknown): void;
+    updateMetrics(functionName: V3FunctionName, promptTokens: number, completionTokens: number, inferenceTimeMs: number): void;
+    private updateTotalMetrics;
+    constructor(opts: V3Options);
+    private _immediateShutdown;
+    private static _installProcessGuards;
+    /**
+     * Entrypoint: initializes handlers, launches Chrome or Browserbase,
+     * and sets up a CDP context.
+     */
+    init(): Promise<void>;
+    /** Apply post-connect local browser options that require CDP. */
+    private _applyPostConnectLocalOptions;
+    /**
+     * Run an "act" instruction through the ActHandler.
+     *
+     * New API:
+     * - act(instruction: string, options?: ActOptions)
+     * - act(action: Action, options?: ActOptions)
+     */
+    act(instruction: string, options?: ActOptions$1): Promise<ActResult>;
+    act(action: Action, options?: ActOptions$1): Promise<ActResult>;
+    /**
+     * Run an "extract" instruction through the ExtractHandler.
+     *
+     * Accepted forms:
+     * - extract() → pageText
+     * - extract(options) → pageText
+     * - extract(instruction) → defaultExtractSchema
+     * - extract(instruction, schema) → schema-inferred
+     * - extract(instruction, schema, options)
+     */
+    extract(): Promise<z.infer<typeof pageTextSchema>>;
+    extract(options: ExtractOptions$1): Promise<z.infer<typeof pageTextSchema>>;
+    extract(instruction: string, options?: ExtractOptions$1): Promise<z.infer<typeof defaultExtractSchema>>;
+    extract<T extends ZodTypeAny>(instruction: string, schema: T, options?: ExtractOptions$1): Promise<z.infer<T>>;
+    /**
+     * Run an "observe" instruction through the ObserveHandler.
+     */
+    observe(): Promise<Action[]>;
+    observe(options: ObserveOptions$1): Promise<Action[]>;
+    observe(instruction: string, options?: ObserveOptions$1): Promise<Action[]>;
+    /** Return the browser-level CDP WebSocket endpoint. */
+    connectURL(): string;
+    /** Expose the current CDP-backed context. */
+    get context(): V3Context;
+    /** Best-effort cleanup of context and launched resources. */
+    close(opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    /** Guard: ensure Browserbase credentials exist in options. */
+    private requireBrowserbaseCreds;
+    get logger(): (logLine: LogLine) => void;
+    /**
+     * Normalize a Playwright/Puppeteer page object into its top frame id,
+     * so handlers can resolve it to a `Page` within our V3Context.
+     */
+    private resolveTopFrameId;
+    private isPlaywrightPage;
+    private isPatchrightPage;
+    private isPuppeteerPage;
+    private normalizeToV3Page;
+    private buildActCacheKey;
+    private safeGetPageUrl;
+    private readActCacheEntry;
+    private writeActCacheEntry;
+    private sanitizeAgentExecuteOptions;
+    private buildAgentCacheSignature;
+    private buildAgentCacheKey;
+    private readAgentCacheEntry;
+    private writeAgentCacheEntry;
+    private replayAgentCacheEntry;
+    private executeAgentReplayStep;
+    private replayAgentActStep;
+    private replayAgentFillFormStep;
+    private replayAgentGotoStep;
+    private replayAgentScrollStep;
+    private replayAgentWaitStep;
+    private replayAgentNavBackStep;
+    private replayCachedActions;
+    private runWithActTimeout;
+    /**
+     * Create a v3 agent instance (AISDK tool-based) with execute().
+     * Mirrors the v2 Stagehand.agent() tool mode (no CUA provider here).
+     */
+    agent(options?: AgentConfig): {
+        execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
+    };
+}
+
+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);
+}
+
+declare class StagehandError extends Error {
+    constructor(message: string);
+}
+declare class StagehandDefaultError extends StagehandError {
+    constructor(error?: unknown);
+}
+declare class StagehandEnvironmentError extends StagehandError {
+    constructor(currentEnvironment: string, requiredEnvironment: string, feature: string);
+}
+declare class MissingEnvironmentVariableError extends StagehandError {
+    constructor(missingEnvironmentVariable: string, feature: string);
+}
+declare class UnsupportedModelError extends StagehandError {
+    constructor(supportedModels: string[], feature?: string);
+}
+declare class UnsupportedModelProviderError extends StagehandError {
+    constructor(supportedProviders: string[], feature?: string);
+}
+declare class UnsupportedAISDKModelProviderError extends StagehandError {
+    constructor(provider: string, supportedProviders: string[]);
+}
+declare class InvalidAISDKModelFormatError extends StagehandError {
+    constructor(modelName: string);
+}
+declare class StagehandNotInitializedError extends StagehandError {
+    constructor(prop: string);
+}
+declare class BrowserbaseSessionNotFoundError extends StagehandError {
+    constructor();
+}
+declare class CaptchaTimeoutError extends StagehandError {
+    constructor();
+}
+declare class MissingLLMConfigurationError extends StagehandError {
+    constructor();
+}
+declare class HandlerNotInitializedError extends StagehandError {
+    constructor(handlerType: string);
+}
+declare class StagehandInvalidArgumentError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandElementNotFoundError extends StagehandError {
+    constructor(xpaths: string[]);
+}
+declare class AgentScreenshotProviderError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandMissingArgumentError extends StagehandError {
+    constructor(message: string);
+}
+declare class CreateChatCompletionResponseError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandEvalError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandDomProcessError extends StagehandError {
+    constructor(message: string);
+}
+declare class StagehandClickError extends StagehandError {
+    constructor(message: string, selector: string);
+}
+declare class LLMResponseError extends StagehandError {
+    constructor(primitive: string, message: string);
+}
+declare class StagehandIframeError extends StagehandError {
+    constructor(frameUrl: string, message: string);
+}
+declare class ContentFrameNotFoundError extends StagehandError {
+    constructor(selector: string);
+}
+declare class XPathResolutionError extends StagehandError {
+    constructor(xpath: string);
+}
+declare class ExperimentalApiConflictError extends StagehandError {
+    constructor();
+}
+declare class ExperimentalNotConfiguredError extends StagehandError {
+    constructor(featureName: string);
+}
+declare class ZodSchemaValidationError extends Error {
+    readonly received: unknown;
+    readonly issues: ReturnType<ZodError["format"]>;
+    constructor(received: unknown, issues: ReturnType<ZodError["format"]>);
+}
+declare class StagehandInitError extends StagehandError {
+    constructor(message: string);
+}
+declare class MCPConnectionError extends StagehandError {
+    readonly serverUrl: string;
+    readonly originalError: unknown;
+    constructor(serverUrl: string, originalError: unknown);
+}
+declare class StagehandShadowRootMissingError extends StagehandError {
+    constructor(detail?: string);
+}
+declare class StagehandShadowSegmentEmptyError extends StagehandError {
+    constructor();
+}
+declare class StagehandShadowSegmentNotFoundError extends StagehandError {
+    constructor(segment: string, hint?: string);
+}
+
+interface ConnectToMCPServerOptions {
+    serverUrl: string | URL;
+    clientOptions?: ClientOptions$3;
+}
+interface StdioServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+declare const connectToMCPServer: (serverConfig: string | URL | StdioServerConfig | ConnectToMCPServerOptions) => Promise<Client$1>;
+
+export { type ActOptions, type ActResult, type Action, type ActionExecutionResult, type AgentAction, type AgentClientOptions, type AgentConfig, type AgentExecuteOptions, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentOptions, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AvailableModel, AvailableModelSchema, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, HandlerNotInitializedError, type HistoryEntry, InvalidAISDKModelFormatError, LLMClient, type LLMResponse, LLMResponseError, LOG_LEVEL_NAMES, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelProvider, type ObserveOptions, type ResponseInputItem, type ResponseItem, V3 as Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, XPathResolutionError, type ZodPathSegments, ZodSchemaValidationError, connectToMCPServer };