@browserbasehq/orca 3.0.2-test-cua-base-url → 3.0.2-zod34

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import z, { ZodType, z as z$1, ZodError, ZodTypeAny } from 'zod/v3';
+import { ZodTypeAny, z, ZodError } from 'zod';
+import * as z3 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';
@@ -17,6 +18,9 @@ import { ChatCompletion } from 'openai/resources';
 import { ToolSet as ToolSet$1 } from 'ai/dist';
 import { Schema } from '@google/genai';
 
+type StagehandZodSchema = ZodTypeAny | z3.ZodTypeAny;
+type InferStagehandSchema<T extends StagehandZodSchema> = T extends z3.ZodTypeAny ? z3.infer<T> : T extends ZodTypeAny ? z.infer<T> : never;
+
 type AnthropicJsonSchemaObject = {
     definitions?: {
         MySchema?: {
@@ -102,7 +106,7 @@ interface ChatCompletionOptions {
     };
     response_model?: {
         name: string;
-        schema: ZodType;
+        schema: StagehandZodSchema;
     };
     tools?: LLMTool[];
     tool_choice?: "auto" | "none" | "required";
@@ -141,6 +145,21 @@ interface CreateChatCompletionOptions {
     logger: (message: LogLine) => void;
     retries?: number;
 }
+/** Simple usage shape if your LLM returns usage tokens. */
+interface LLMUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    reasoning_tokens?: number;
+    cached_input_tokens?: number;
+}
+/**
+ * For calls that use a schema: the LLMClient may return { data: T; usage?: LLMUsage }
+ */
+interface LLMParsedResponse<T> {
+    data: T;
+    usage?: LLMUsage;
+}
 declare abstract class LLMClient {
     type: "openai" | "anthropic" | "cerebras" | "groq" | (string & {});
     modelName: AvailableModel | (string & {});
@@ -148,9 +167,15 @@ declare abstract class LLMClient {
     clientOptions: ClientOptions;
     userProvidedInstructions?: string;
     constructor(modelName: AvailableModel, userProvidedInstructions?: string);
-    abstract createChatCompletion<T = LLMResponse & {
-        usage?: LLMResponse["usage"];
-    }>(options: CreateChatCompletionOptions): Promise<T>;
+    abstract createChatCompletion<T>(options: CreateChatCompletionOptions & {
+        options: {
+            response_model: {
+                name: string;
+                schema: StagehandZodSchema;
+            };
+        };
+    }): Promise<LLMParsedResponse<T>>;
+    abstract createChatCompletion<T = LLMResponse>(options: CreateChatCompletionOptions): Promise<T>;
     generateObject: typeof generateObject;
     generateText: typeof generateText;
     streamText: typeof streamText;
@@ -199,11 +224,7 @@ declare class CdpConnection implements CDPSessionLike {
     close(): Promise<void>;
     getSession(sessionId: string): CdpSession | undefined;
     attachToTarget(targetId: string): Promise<CdpSession>;
-    getTargets(): Promise<Array<{
-        targetId: string;
-        type: string;
-        url: string;
-    }>>;
+    getTargets(): Promise<Protocol.Target.TargetInfo[]>;
     private onMessage;
     _sendViaSession<R = unknown>(sessionId: string, method: string, params?: object): Promise<R>;
     _onSessionEvent(sessionId: string, event: string, handler: EventHandler): void;
@@ -238,9 +259,12 @@ declare class Frame implements FrameManager {
     session: CDPSessionLike;
     frameId: string;
     pageId: string;
+    private readonly remoteBrowser;
     /** 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);
+    constructor(session: CDPSessionLike, frameId: string, pageId: string, remoteBrowser: boolean);
+    /** True when the controlled browser runs on a different machine. */
+    isBrowserRemote(): boolean;
     /** DOM.getNodeForLocation → DOM.describeNode */
     getNodeAtLocation(x: number, y: number): Promise<Protocol.DOM.Node>;
     /** CSS selector → DOM.querySelector → DOM.getBoxModel */
@@ -284,6 +308,14 @@ declare class Frame implements FrameManager {
     private getExecutionContextId;
 }
 
+interface SetInputFilePayload {
+    name: string;
+    mimeType?: string;
+    buffer: ArrayBuffer | Uint8Array | Buffer$1 | string;
+    lastModified?: number;
+}
+type SetInputFilesArgument = string | string[] | SetInputFilePayload | SetInputFilePayload[];
+
 type MouseButton = "left" | "right" | "middle";
 /**
  * Locator
@@ -326,15 +358,16 @@ declare class Locator {
      * - 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>;
+    setInputFiles(files: SetInputFilesArgument): Promise<void>;
+    /**
+     * Remote browser fallback: build File objects inside the page and attach them via JS.
+     *
+     * When Stagehand is driving a browser that cannot see the local filesystem (Browserbase,
+     * remote CDP, etc.), CDP's DOM.setFileInputFiles would fail because Chrome can't reach
+     * our temp files. Instead we base64-encode the payloads, send them into the page, and
+     * let a DOM helper create File objects + dispatch change/input events.
+     */
+    private assignFilesViaPayloadInjection;
     /**
      * Return the DOM backendNodeId for this locator's target element.
      * Useful for identity comparisons without needing element handles.
@@ -723,6 +756,14 @@ declare class Response$1 {
      * richer metadata.
      */
     applyExtraInfo(event: Protocol.Network.ResponseReceivedExtraInfoEvent): void;
+    /**
+     * Internal helper for creating a Response object from a Serializable
+     * goto response from the Stagehand API
+     */
+    static fromSerializable(serialized: SerializableResponse, context: {
+        page: Page;
+        session: CDPSessionLike;
+    }): Response$1;
     /** Marks the response as finished and resolves the `finished()` promise. */
     markFinished(error: Error | null): void;
 }
@@ -741,11 +782,11 @@ 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.AnyZodObject>({ instruction, schema: zodSchema, options, frameId, }: APIExtractParameters): Promise<ExtractResult<T>>;
+    extract<T extends StagehandZodSchema>({ instruction, schema: zodSchema, options, frameId, }: APIExtractParameters): Promise<ExtractResult<T>>;
     observe({ instruction, options, frameId, }: APIObserveParameters): Promise<Action[]>;
     goto(url: string, options?: {
         waitUntil?: "load" | "domcontentloaded" | "networkidle";
-    }, frameId?: string): Promise<void>;
+    }, frameId?: string): Promise<SerializableResponse | null>;
     agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions | string, frameId?: string): Promise<AgentResult>;
     end(): Promise<Response>;
     getReplayMetrics(): Promise<StagehandMetrics>;
@@ -793,6 +834,7 @@ declare class Page {
     private nextOrdinal;
     /** cache Frames per frameId so everyone uses the same one */
     private readonly frameCache;
+    private readonly browserIsRemote;
     /** Stable id for Frames created by this Page (use top-level TargetId). */
     private readonly pageId;
     /** Cached current URL for synchronous page.url() */
@@ -813,7 +855,7 @@ declare class Page {
      * Factory: create Page and seed registry with the shallow tree from Page.getFrameTree.
      * Assumes Page domain is already enabled on the session passed in.
      */
-    static create(conn: CdpConnection, session: CDPSessionLike, targetId: string, apiClient?: StagehandAPIClient | null, localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null): Promise<Page>;
+    static create(conn: CdpConnection, session: CDPSessionLike, targetId: string, apiClient?: StagehandAPIClient | null, localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null, browserIsRemote?: boolean): Promise<Page>;
     /**
      * Parent/child session emitted a `frameAttached`.
      * Topology update + ownership stamped to **emitting session**.
@@ -1128,6 +1170,8 @@ interface AgentResult {
     usage?: {
         input_tokens: number;
         output_tokens: number;
+        reasoning_tokens?: number;
+        cached_input_tokens?: number;
         inference_time_ms: number;
     };
 }
@@ -1293,7 +1337,7 @@ interface ActResult {
     actionDescription: string;
     actions: Action[];
 }
-type ExtractResult<T extends z$1.AnyZodObject> = z$1.infer<T>;
+type ExtractResult<T extends StagehandZodSchema> = InferStagehandSchema<T>;
 interface Action {
     selector: string;
     description: string;
@@ -1312,20 +1356,12 @@ interface ExtractOptions {
     selector?: string;
     page?: Page$1 | Page$2 | Page$3 | Page;
 }
-declare const defaultExtractSchema: z$1.ZodObject<{
-    extraction: z$1.ZodString;
-}, "strip", z$1.ZodTypeAny, {
-    extraction?: string;
-}, {
-    extraction?: string;
-}>;
-declare const pageTextSchema: z$1.ZodObject<{
-    pageText: z$1.ZodString;
-}, "strip", z$1.ZodTypeAny, {
-    pageText?: string;
-}, {
-    pageText?: string;
-}>;
+declare const defaultExtractSchema: z.ZodObject<{
+    extraction: z.ZodString;
+}, z.core.$strip>;
+declare const pageTextSchema: z.ZodObject<{
+    pageText: z.ZodString;
+}, z.core.$strip>;
 interface ObserveOptions {
     model?: ModelConfiguration;
     timeout?: number;
@@ -1342,18 +1378,28 @@ declare enum V3FunctionName {
 interface StagehandMetrics {
     actPromptTokens: number;
     actCompletionTokens: number;
+    actReasoningTokens: number;
+    actCachedInputTokens: number;
     actInferenceTimeMs: number;
     extractPromptTokens: number;
     extractCompletionTokens: number;
+    extractReasoningTokens: number;
+    extractCachedInputTokens: number;
     extractInferenceTimeMs: number;
     observePromptTokens: number;
     observeCompletionTokens: number;
+    observeReasoningTokens: number;
+    observeCachedInputTokens: number;
     observeInferenceTimeMs: number;
     agentPromptTokens: number;
     agentCompletionTokens: number;
+    agentReasoningTokens: number;
+    agentCachedInputTokens: number;
     agentInferenceTimeMs: number;
     totalPromptTokens: number;
     totalCompletionTokens: number;
+    totalReasoningTokens: number;
+    totalCachedInputTokens: number;
     totalInferenceTimeMs: number;
 }
 
@@ -1500,6 +1546,9 @@ declare class ExperimentalApiConflictError extends StagehandError {
 declare class ExperimentalNotConfiguredError extends StagehandError {
     constructor(featureName: string);
 }
+declare class CuaModelRequiredError extends StagehandError {
+    constructor(availableModels: readonly string[]);
+}
 declare class ZodSchemaValidationError extends Error {
     readonly received: unknown;
     readonly issues: ReturnType<ZodError["format"]>;
@@ -1522,6 +1571,24 @@ declare class StagehandShadowSegmentEmptyError extends StagehandError {
 declare class StagehandShadowSegmentNotFoundError extends StagehandError {
     constructor(segment: string, hint?: string);
 }
+declare class ElementNotVisibleError extends StagehandError {
+    constructor(selector: string);
+}
+declare class ResponseBodyError extends StagehandError {
+    constructor(message: string);
+}
+declare class ResponseParseError extends StagehandError {
+    constructor(message: string);
+}
+declare class TimeoutError extends StagehandError {
+    constructor(operation: string, timeoutMs: number);
+}
+declare class PageNotFoundError extends StagehandError {
+    constructor(identifier: string);
+}
+declare class ConnectionTimeoutError extends StagehandError {
+    constructor(message: string);
+}
 
 declare class AISdkClient extends LLMClient {
     type: "aisdk";
@@ -1560,7 +1627,7 @@ interface APIActParameters {
 }
 interface APIExtractParameters {
     instruction?: string;
-    schema?: ZodTypeAny;
+    schema?: StagehandZodSchema;
     options?: ExtractOptions;
     frameId?: string;
 }
@@ -1569,6 +1636,16 @@ interface APIObserveParameters {
     options?: ObserveOptions;
     frameId?: string;
 }
+interface SerializableResponse {
+    requestId: string;
+    frameId?: string;
+    loaderId?: string;
+    response: Protocol.Network.Response;
+    fromServiceWorkerFlag?: boolean;
+    finishedSettled?: boolean;
+    extraInfoHeaders?: Protocol.Network.Headers | null;
+    extraInfoHeadersText?: string;
+}
 
 /**
  * Represents a path through a Zod schema from the root object down to a
@@ -1672,6 +1749,7 @@ declare class V3Context {
      * We poll internal maps that bootstrap/onAttachedToTarget populate.
      */
     private waitForFirstTopLevelPage;
+    private waitForInitialTopLevelTargets;
     private ensurePiercer;
     /** Mark a page target as the most-recent one (active). */
     private _pushActive;
@@ -1862,7 +1940,7 @@ declare class V3 {
      */
     get history(): Promise<ReadonlyArray<HistoryEntry>>;
     addToHistory(method: HistoryEntry["method"], parameters: unknown, result?: unknown): void;
-    updateMetrics(functionName: V3FunctionName, promptTokens: number, completionTokens: number, inferenceTimeMs: number): void;
+    updateMetrics(functionName: V3FunctionName, promptTokens: number, completionTokens: number, reasoningTokens: number, cachedInputTokens: number, inferenceTimeMs: number): void;
     private updateTotalMetrics;
     private _immediateShutdown;
     private static _installProcessGuards;
@@ -1893,10 +1971,10 @@ declare class V3 {
      * - extract(instruction, schema) → schema-inferred
      * - extract(instruction, schema, options)
      */
-    extract(): Promise<z$1.infer<typeof pageTextSchema>>;
-    extract(options: ExtractOptions): Promise<z$1.infer<typeof pageTextSchema>>;
-    extract(instruction: string, options?: ExtractOptions): Promise<z$1.infer<typeof defaultExtractSchema>>;
-    extract<T extends ZodTypeAny>(instruction: string, schema: T, options?: ExtractOptions): Promise<z$1.infer<T>>;
+    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 StagehandZodSchema>(instruction: string, schema: T, options?: ExtractOptions): Promise<InferStagehandSchema<T>>;
     /**
      * Run an "observe" instruction through the ObserveHandler.
      */
@@ -1968,14 +2046,14 @@ declare class AgentProvider {
     static getAgentProvider(modelName: string): AgentProviderType;
 }
 
-declare function validateZodSchema(schema: z$1.ZodTypeAny, data: unknown): boolean;
+declare function validateZodSchema(schema: StagehandZodSchema, data: unknown): boolean;
 /**
  * Detects if the code is running in the Bun runtime environment.
  * @returns {boolean} True if running in Bun, false otherwise.
  */
 declare function isRunningInBun(): boolean;
-declare function toGeminiSchema(zodSchema: z$1.ZodTypeAny): Schema;
-declare function getZodType(schema: z$1.ZodTypeAny): string;
+declare function toGeminiSchema(zodSchema: StagehandZodSchema): Schema;
+declare function getZodType(schema: StagehandZodSchema): 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()`.
@@ -1989,7 +2067,7 @@ declare function getZodType(schema: z$1.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$1.ZodTypeAny, currentPath: Array<string | number>): [z$1.ZodTypeAny, ZodPathSegments[]];
+declare function transformSchema(schema: StagehandZodSchema, currentPath: Array<string | number>): [StagehandZodSchema, 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
@@ -2058,4 +2136,4 @@ declare class V3Evaluator {
     private _evaluateWithMultipleScreenshots;
 }
 
-export { type AISDKCustomProvider, type AISDKProvider, AISdkClient, AVAILABLE_CUA_MODELS, type ActOptions, type ActResult, type Action, type ActionExecutionResult, type AgentAction, type AgentConfig, type AgentExecuteOptions, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentModelConfig, AgentProvider, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AnyPage, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, 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 };
+export { type AISDKCustomProvider, type AISDKProvider, AISdkClient, AVAILABLE_CUA_MODELS, type ActOptions, type ActResult, type Action, type ActionExecutionResult, type AgentAction, type AgentConfig, type AgentExecuteOptions, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentModelConfig, AgentProvider, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AnyPage, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, ConnectionTimeoutError, type ConsoleListener, ConsoleMessage, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, CuaModelRequiredError, ElementNotVisibleError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, HandlerNotInitializedError, type HistoryEntry, InvalidAISDKModelFormatError, type JsonSchema, type JsonSchemaProperty, LLMClient, type LLMParsedResponse, type LLMResponse, LLMResponseError, type LLMTool, type LLMUsage, LOG_LEVEL_NAMES, type LoadState, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelProvider, type ObserveOptions, Page, PageNotFoundError, Response$1 as Response, ResponseBodyError, type ResponseInputItem, type ResponseItem, ResponseParseError, V3 as Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, TimeoutError, 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 };