@browserbasehq/orca 3.0.0-test.1 → 3.0.1

package/README.md

@@ -0,0 +1,164 @@
+<div id="toc" align="center" style="margin-bottom: 0;">
+  <ul style="list-style: none; margin: 0; padding: 0;">
+    <a href="https://stagehand.dev">
+      <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="../../media/dark_logo.png" />
+        <img alt="Stagehand" src="../../media/light_logo.png" width="200" style="margin-right: 30px;" />
+      </picture>
+    </a>
+  </ul>
+</div>
+<p align="center">
+  <strong>The AI Browser Automation Framework</strong><br>
+  <a href="https://docs.stagehand.dev">Read the Docs</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/browserbase/stagehand/tree/main?tab=MIT-1-ov-file#MIT-1-ov-file">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="../../media/dark_license.svg" />
+      <img alt="MIT License" src="../../media/light_license.svg" />
+    </picture>
+  </a>
+  <a href="https://join.slack.com/t/stagehand-dev/shared_invite/zt-3hgv6bwqu-s7MXXgPd7_rD53aViGo1MQ">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="../../media/dark_slack.svg" />
+      <img alt="Slack Community" src="../../media/light_slack.svg" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+	<a href="https://trendshift.io/repositories/12122" target="_blank"><img src="https://trendshift.io/api/badge/repositories/12122" alt="browserbase%2Fstagehand | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+  <a href="https://deepwiki.com/browserbase/stagehand">
+    <img alt="Ask DeepWiki" src="https://deepwiki.com/badge.svg" />
+  </a>
+</p>
+
+<p align="center">
+If you're looking for the Python implementation, you can find it 
+<a href="https://github.com/browserbase/stagehand-python"> here</a>
+</p>
+
+<div align="center" style="display: flex; align-items: center; justify-content: center; gap: 4px; margin-bottom: 0;">
+  <b>Vibe code</b>
+  <span style="font-size: 1.05em;"> Stagehand with </span>
+  <a href="https://director.ai" style="display: flex; align-items: center;">
+    <span>Director</span>
+  </a>
+  <span> </span>
+  <picture>
+    <img alt="Director" src="../../media/director_icon.svg" width="25" />
+  </picture>
+</div>
+
+## What is Stagehand?
+
+Stagehand is a browser automation framework used to control web browsers with natural language and code. By combining the power of AI with the precision of code, Stagehand makes web automation flexible, maintainable, and actually reliable.
+
+## Why Stagehand?
+
+Most existing browser automation tools either require you to write low-level code in a framework like Selenium, Playwright, or Puppeteer, or use high-level agents that can be unpredictable in production. By letting developers choose what to write in code vs. natural language (and bridging the gap between the two) Stagehand is the natural choice for browser automations in production.
+
+1. **Choose when to write code vs. natural language**: use AI when you want to navigate unfamiliar pages, and use code when you know exactly what you want to do.
+
+2. **Go from AI-driven to repeatable workflows**: Stagehand lets you preview AI actions before running them, and also helps you easily cache repeatable actions to save time and tokens.
+
+3. **Write once, run forever**: Stagehand's auto-caching combined with self-healing remembers previous actions, runs without LLM inference, and knows when to involve AI whenever the website changes and your automation breaks.
+
+## Getting Started
+
+Start with Stagehand with one line of code, or check out our [Quickstart Guide](https://docs.stagehand.dev/v3/first-steps/quickstart) for more information:
+
+```bash
+npx create-browser-app
+```
+
+## Example
+
+Here's how to build a sample browser automation with Stagehand:
+
+```typescript
+// Stagehand's CDP engine provides an optimized, low level interface to the browser built for automation
+const page = stagehand.context.pages()[0];
+await page.goto("https://github.com/browserbase");
+
+// Use act() to execute individual actions
+await stagehand.act("click on the stagehand repo");
+
+// Use agent() for multi-step tasks
+const agent = stagehand.agent();
+await agent.execute("Get to the latest PR");
+
+// Use extract() to get structured data from the page
+const { author, title } = await stagehand.extract(
+  "extract the author and title of the PR",
+  z.object({
+    author: z.string().describe("The username of the PR author"),
+    title: z.string().describe("The title of the PR"),
+  }),
+);
+```
+
+## Documentation
+
+Visit [docs.stagehand.dev](https://docs.stagehand.dev) to view the full documentation.
+
+### Build and Run from Source
+
+```bash
+git clone https://github.com/browserbase/stagehand.git
+cd stagehand
+pnpm install
+pnpm run build
+pnpm run example # run the blank script at ./examples/example.ts
+```
+
+Stagehand is best when you have an API key for an LLM provider and Browserbase credentials. To add these to your project, run:
+
+```bash
+cp .env.example .env
+nano .env # Edit the .env file to add API keys
+```
+
+### Installing from a branch
+
+You can install and build Stagehand directly from a github branch using [gitpkg](https://github.com/EqualMa/gitpkg)
+
+In your project's `package.json` set:
+
+```json
+"@browserbasehq/stagehand": "https://gitpkg.now.sh/browserbase/stagehand/packages/core?<branchName>",
+```
+
+## Contributing
+
+> [!NOTE]  
+> We highly value contributions to Stagehand! For questions or support, please join our [Slack community](https://join.slack.com/t/stagehand-dev/shared_invite/zt-3hgv6bwqu-s7MXXgPd7_rD53aViGo1MQ).
+
+At a high level, we're focused on improving reliability, extensibility, speed, and cost in that order of priority. If you're interested in contributing, **bug fixes and small improvements are the best way to get started**. For more involved features, we strongly recommend reaching out to [Miguel Gonzalez](https://x.com/miguel_gonzf) or [Paul Klein](https://x.com/pk_iv) in our [Slack community](https://join.slack.com/t/stagehand-dev/shared_invite/zt-3hgv6bwqu-s7MXXgPd7_rD53aViGo1MQ) before starting to ensure that your contribution aligns with our goals.
+
+<!-- For more information, please see our [Contributing Guide](https://docs.stagehand.dev/examples/contributing). -->
+
+## Acknowledgements
+
+We'd like to thank the following people for their major contributions to Stagehand:
+
+- [Paul Klein](https://github.com/pkiv)
+- [Sean McGuire](https://github.com/seanmcguire12)
+- [Miguel Gonzalez](https://github.com/miguelg719)
+- [Sameel Arif](https://github.com/sameelarif)
+- [Thomas Katwan](https://github.com/tkattkat)
+- [Filip Michalsky](https://github.com/filip-michalsky)
+- [Anirudh Kamath](https://github.com/kamath)
+- [Jeremy Press](https://x.com/jeremypress)
+- [Navid Pour](https://github.com/navidpour)
+
+## License
+
+Licensed under the MIT License.
+
+Copyright 2025 Browserbase, Inc.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ZodType, z, ZodError, ZodTypeAny } from 'zod';
+import z, { ZodType, z as z$1, ZodError, ZodTypeAny } from 'zod/v3';
 import { ClientOptions as ClientOptions$2 } from '@anthropic-ai/sdk';
 import { LanguageModelV2 } from '@ai-sdk/provider';
 import { ClientOptions as ClientOptions$1 } from 'openai';
@@ -13,6 +13,7 @@ export { Page as PatchrightPage } from 'patchright-core';
 import { Protocol } from 'devtools-protocol';
 import { Buffer as Buffer$1 } from 'buffer';
 import Browserbase from '@browserbasehq/sdk';
+import { ChatCompletion } from 'openai/resources';
 import { ToolSet as ToolSet$1 } from 'ai/dist';
 import { Schema } from '@google/genai';
 
@@ -140,14 +141,6 @@ interface CreateChatCompletionOptions {
     logger: (message: LogLine) => void;
     retries?: number;
 }
-interface LLMParsedResponse<T> {
-    data: T;
-    usage?: {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-    };
-}
 declare abstract class LLMClient {
     type: "openai" | "anthropic" | "cerebras" | "groq" | (string & {});
     modelName: AvailableModel | (string & {});
@@ -155,15 +148,9 @@ declare abstract class LLMClient {
     clientOptions: ClientOptions;
     userProvidedInstructions?: string;
     constructor(modelName: AvailableModel, userProvidedInstructions?: string);
-    abstract createChatCompletion<T>(options: CreateChatCompletionOptions & {
-        options: {
-            response_model: {
-                name: string;
-                schema: ZodType;
-            };
-        };
-    }): Promise<LLMParsedResponse<T>>;
-    abstract createChatCompletion<T = LLMResponse>(options: CreateChatCompletionOptions): Promise<T>;
+    abstract createChatCompletion<T = LLMResponse & {
+        usage?: LLMResponse["usage"];
+    }>(options: CreateChatCompletionOptions): Promise<T>;
     generateObject: typeof generateObject;
     generateText: typeof generateText;
     streamText: typeof streamText;
@@ -280,6 +267,9 @@ declare class Frame implements FrameManager {
             width: number;
             height: number;
         };
+        type?: "png" | "jpeg";
+        quality?: number;
+        scale?: number;
     }): Promise<Buffer>;
     /** Child frames via Page.getFrameTree */
     childFrames(): Promise<Frame[]>;
@@ -593,7 +583,152 @@ declare class LocatorDelegate {
     first(): LocatorDelegate;
 }
 
+type RemoteObject = Protocol.Runtime.RemoteObject;
+type ConsoleListener = (message: ConsoleMessage) => void;
+declare class ConsoleMessage {
+    private readonly event;
+    private readonly pageRef?;
+    constructor(event: Protocol.Runtime.ConsoleAPICalledEvent, pageRef?: Page);
+    type(): Protocol.Runtime.ConsoleAPICalledEvent["type"];
+    text(): string;
+    args(): RemoteObject[];
+    location(): {
+        url?: string;
+        lineNumber?: number;
+        columnNumber?: number;
+    };
+    page(): Page | undefined;
+    timestamp(): number | undefined;
+    raw(): Protocol.Runtime.ConsoleAPICalledEvent;
+    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.
+ */
+
+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;
+    /** 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";
 
 declare class StagehandAPIClient {
@@ -606,17 +741,43 @@ declare class StagehandAPIClient {
     constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams);
     init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, systemPrompt, selfHeal, browserbaseSessionCreateParams, browserbaseSessionID, }: StartSessionParams): Promise<StartSessionResult>;
     act({ input, options, frameId }: APIActParameters): Promise<ActResult>;
-    extract<T extends z.ZodObject>({ instruction, schema: zodSchema, options, frameId, }: APIExtractParameters): Promise<ExtractResult<T>>;
+    extract<T extends z.AnyZodObject>({ instruction, schema: zodSchema, options, frameId, }: APIExtractParameters): Promise<ExtractResult<T>>;
     observe({ instruction, options, frameId, }: APIObserveParameters): Promise<Action[]>;
     goto(url: string, options?: {
         waitUntil?: "load" | "domcontentloaded" | "networkidle";
     }, frameId?: string): Promise<void>;
     agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions | string, frameId?: string): Promise<AgentResult>;
     end(): Promise<Response>;
+    getReplayMetrics(): Promise<StagehandMetrics>;
     private execute;
     private request;
 }
 
+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;
@@ -641,6 +802,8 @@ declare class Page {
     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;
@@ -681,7 +844,30 @@ declare class Page {
     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;
+    /**
+     * 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" }
+     * );
+     */
+    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;
@@ -696,6 +882,13 @@ declare class Page {
     /** 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;
     /**
      * Navigate the page; optionally wait for a lifecycle state.
      * Waits on the **current** main frame and follows root swaps during navigation.
@@ -703,7 +896,7 @@ declare class Page {
     goto(url: string, options?: {
         waitUntil?: LoadState;
         timeoutMs?: number;
-    }): Promise<void>;
+    }): Promise<Response$1 | null>;
     /**
      * Reload the page; optionally wait for a lifecycle state.
      */
@@ -711,21 +904,21 @@ declare class Page {
         waitUntil?: LoadState;
         timeoutMs?: number;
         ignoreCache?: boolean;
-    }): Promise<void>;
+    }): Promise<Response$1 | null>;
     /**
      * Navigate back in history if possible; optionally wait for a lifecycle state.
      */
     goBack(options?: {
         waitUntil?: LoadState;
         timeoutMs?: number;
-    }): Promise<void>;
+    }): Promise<Response$1 | null>;
     /**
      * Navigate forward in history if possible; optionally wait for a lifecycle state.
      */
     goForward(options?: {
         waitUntil?: LoadState;
         timeoutMs?: number;
-    }): Promise<void>;
+    }): Promise<Response$1 | null>;
     /**
      * Return the current page URL (synchronous, cached from navigation events).
      */
@@ -739,11 +932,36 @@ declare class Page {
      */
     title(): Promise<string>;
     /**
-     * Capture a screenshot (delegated to the current main frame).
-     */
-    screenshot(options?: {
-        fullPage?: boolean;
-    }): Promise<Buffer>;
+     * 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>;
     /**
      * Create a locator bound to the current main frame.
      */
@@ -1075,7 +1293,7 @@ interface ActResult {
     actionDescription: string;
     actions: Action[];
 }
-type ExtractResult<T extends z.ZodObject> = z.infer<T>;
+type ExtractResult<T extends z$1.AnyZodObject> = z$1.infer<T>;
 interface Action {
     selector: string;
     description: string;
@@ -1094,12 +1312,20 @@ interface ExtractOptions {
     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>;
+declare const defaultExtractSchema: z$1.ZodObject<{
+    extraction: z$1.ZodString;
+}, "strip", z$1.ZodTypeAny, {
+    extraction?: string;
+}, {
+    extraction?: string;
+}>;
+declare const pageTextSchema: z$1.ZodObject<{
+    pageText: z$1.ZodString;
+}, "strip", z$1.ZodTypeAny, {
+    pageText?: string;
+}, {
+    pageText?: string;
+}>;
 interface ObserveOptions {
     model?: ModelConfiguration;
     timeout?: number;
@@ -1297,6 +1523,15 @@ declare class StagehandShadowSegmentNotFoundError extends StagehandError {
     constructor(segment: string, hint?: 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;
@@ -1591,6 +1826,7 @@ declare class V3 {
     private readonly domSettleTimeoutMs?;
     private _isClosing;
     browserbaseSessionId?: string;
+    get browserbaseSessionID(): string | undefined;
     private _onCdpClosed;
     readonly experimental: boolean;
     readonly logInferenceToFile: boolean;
@@ -1610,7 +1846,7 @@ declare class V3 {
     constructor(opts: V3Options);
     /**
      * Async property for metrics so callers can `await v3.metrics`.
-     * Returning a Promise future-proofs async aggregation/storage.
+     * When using API mode, fetches metrics from the API. Otherwise returns local metrics.
      */
     get metrics(): Promise<StagehandMetrics>;
     private resolveLlmClient;
@@ -1657,10 +1893,10 @@ declare class V3 {
      * - extract(instruction, schema) → schema-inferred
      * - extract(instruction, schema, options)
      */
-    extract(): Promise<z.infer<typeof pageTextSchema>>;
-    extract(options: ExtractOptions): Promise<z.infer<typeof pageTextSchema>>;
-    extract(instruction: string, options?: ExtractOptions): Promise<z.infer<typeof defaultExtractSchema>>;
-    extract<T extends ZodTypeAny>(instruction: string, schema: T, options?: ExtractOptions): Promise<z.infer<T>>;
+    extract(): Promise<z$1.infer<typeof pageTextSchema>>;
+    extract(options: ExtractOptions): Promise<z$1.infer<typeof pageTextSchema>>;
+    extract(instruction: string, options?: ExtractOptions): Promise<z$1.infer<typeof defaultExtractSchema>>;
+    extract<T extends ZodTypeAny>(instruction: string, schema: T, options?: ExtractOptions): Promise<z$1.infer<T>>;
     /**
      * Run an "observe" instruction through the ObserveHandler.
      */
@@ -1732,14 +1968,14 @@ declare class AgentProvider {
     static getAgentProvider(modelName: string): AgentProviderType;
 }
 
-declare function validateZodSchema(schema: z.ZodTypeAny, data: unknown): boolean;
+declare function validateZodSchema(schema: z$1.ZodTypeAny, data: unknown): boolean;
 /**
  * Detects if the code is running in the Bun runtime environment.
  * @returns {boolean} True if running in Bun, false otherwise.
  */
 declare function isRunningInBun(): boolean;
-declare function toGeminiSchema(zodSchema: z.ZodTypeAny): Schema;
-declare function getZodType(schema: z.ZodTypeAny): string;
+declare function toGeminiSchema(zodSchema: z$1.ZodTypeAny): Schema;
+declare function getZodType(schema: z$1.ZodTypeAny): string;
 /**
  * Recursively traverses a given Zod schema, scanning for any fields of type `z.string().url()`.
  * For each such field, it replaces the `z.string().url()` with `z.number()`.
@@ -1753,7 +1989,7 @@ declare function getZodType(schema: z.ZodTypeAny): string;
  *   1. The updated Zod schema, with any `.url()` fields replaced by `z.number()`.
  *   2. An array of {@link ZodPathSegments} objects representing each replaced field, including the path segments.
  */
-declare function transformSchema(schema: z.ZodTypeAny, currentPath: Array<string | number>): [z.ZodTypeAny, ZodPathSegments[]];
+declare function transformSchema(schema: z$1.ZodTypeAny, currentPath: Array<string | number>): [z$1.ZodTypeAny, ZodPathSegments[]];
 /**
  * Once we get the final extracted object that has numeric IDs in place of URLs,
  * use `injectUrls` to walk the object and replace numeric IDs
@@ -1822,4 +2058,4 @@ declare class V3Evaluator {
     private _evaluateWithMultipleScreenshots;
 }
 
-export { type AISDKCustomProvider, type AISDKProvider, AVAILABLE_CUA_MODELS, type ActOptions, type ActResult, type Action, type ActionExecutionResult, type AgentAction, type AgentConfig, type AgentExecuteOptions, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentModelConfig, AgentProvider, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AnyPage, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, HandlerNotInitializedError, type HistoryEntry, InvalidAISDKModelFormatError, type JsonSchema, type JsonSchemaProperty, LLMClient, type LLMParsedResponse, type LLMResponse, LLMResponseError, type LLMTool, LOG_LEVEL_NAMES, type LoadState, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelProvider, type ObserveOptions, type ResponseInputItem, type ResponseItem, V3 as Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, XPathResolutionError, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, jsonSchemaToZod, loadApiKeyFromEnv, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, transformSchema, trimTrailingTextNode, validateZodSchema };
+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, type ConsoleListener, ConsoleMessage, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, HandlerNotInitializedError, type HistoryEntry, InvalidAISDKModelFormatError, type JsonSchema, type JsonSchemaProperty, LLMClient, type LLMResponse, LLMResponseError, type LLMTool, LOG_LEVEL_NAMES, type LoadState, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelProvider, type ObserveOptions, Page, Response$1 as Response, type ResponseInputItem, type ResponseItem, V3 as Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, XPathResolutionError, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, jsonSchemaToZod, loadApiKeyFromEnv, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, transformSchema, trimTrailingTextNode, validateZodSchema };