@browserbasehq/orca 3.0.0-preview.6 → 3.0.0-preview.8

package/dist/index.d.ts

@@ -1,17 +1,17 @@
-import { ZodType, z, ZodError, ZodTypeAny } from 'zod/v3';
+import z, { ZodType, z as z$1, ZodError, ZodTypeAny } from 'zod/v3';
 import { ClientOptions as ClientOptions$2 } from '@anthropic-ai/sdk';
 import { LanguageModelV2 } from '@ai-sdk/provider';
 import { ClientOptions as ClientOptions$1 } from 'openai';
 import { generateObject, generateText, streamText, streamObject, experimental_generateImage, embed, embedMany, experimental_transcribe, experimental_generateSpeech, ToolSet } from 'ai';
-import { Protocol } from 'devtools-protocol';
-import { Buffer as Buffer$1 } from 'buffer';
+import { Client, ClientOptions as ClientOptions$3 } from '@modelcontextprotocol/sdk/client/index.js';
 import { Page as Page$1 } from 'playwright-core';
 export { Page as PlaywrightPage } from 'playwright-core';
-import { Page as Page$3 } from 'patchright-core';
-export { Page as PatchrightPage } from 'patchright-core';
 import { Page as Page$2 } from 'puppeteer-core';
 export { Page as PuppeteerPage } from 'puppeteer-core';
-import { Client, ClientOptions as ClientOptions$3 } from '@modelcontextprotocol/sdk/client/index.js';
+import { Page as Page$3 } from 'patchright-core';
+export { Page as PatchrightPage } from 'patchright-core';
+import { Protocol } from 'devtools-protocol';
+import { Buffer as Buffer$1 } from 'buffer';
 import Browserbase from '@browserbasehq/sdk';
 import { ToolSet as ToolSet$1 } from 'ai/dist';
 import { Schema } from '@google/genai';
@@ -522,6 +522,15 @@ declare class DeepLocatorDelegate {
         composed?: boolean;
         detail?: number;
     }): Promise<void>;
+    setInputFiles(files: string | string[] | {
+        name: string;
+        mimeType: string;
+        buffer: ArrayBuffer | Uint8Array | Buffer | string;
+    } | Array<{
+        name: string;
+        mimeType: string;
+        buffer: ArrayBuffer | Uint8Array | Buffer | string;
+    }>): Promise<void>;
     first(): DeepLocatorDelegate;
     nth(index: number): DeepLocatorDelegate;
 }
@@ -573,6 +582,27 @@ declare class LocatorDelegate {
 type AnyPage = Page$1 | Page$2 | Page$3 | Page;
 type LoadState = "load" | "domcontentloaded" | "networkidle";
 
+declare class StagehandAPIClient {
+    private apiKey;
+    private projectId;
+    private sessionId?;
+    private modelApiKey;
+    private logger;
+    private fetchWithCookies;
+    constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams);
+    init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, systemPrompt, selfHeal, browserbaseSessionCreateParams, browserbaseSessionID, }: StartSessionParams): Promise<StartSessionResult>;
+    act({ input, options, frameId }: APIActParameters): Promise<ActResult>;
+    extract<T extends z.AnyZodObject>({ instruction, schema: zodSchema, options, frameId, }: APIExtractParameters): Promise<ExtractResult<T>>;
+    observe({ instruction, options, frameId, }: APIObserveParameters): Promise<Action[]>;
+    goto(url: string, options?: {
+        waitUntil?: "load" | "domcontentloaded" | "networkidle";
+    }, frameId?: string): Promise<void>;
+    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions | string, frameId?: string): Promise<AgentResult>;
+    end(): Promise<Response>;
+    private execute;
+    private request;
+}
+
 declare class Page {
     private readonly conn;
     private readonly mainSession;
@@ -592,7 +622,11 @@ declare class Page {
     private readonly pageId;
     /** Cached current URL for synchronous page.url() */
     private _currentUrl;
+    private navigationCommandSeq;
+    private latestNavigationCommandId;
     private readonly networkManager;
+    /** Optional API client for routing page operations to the API */
+    private readonly apiClient;
     private constructor();
     private cursorEnabled;
     private ensureCursorScript;
@@ -602,7 +636,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): Promise<Page>;
+    static create(conn: CdpConnection, session: CDPSessionLike, targetId: string, apiClient?: StagehandAPIClient | null, localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null): Promise<Page>;
     /**
      * Parent/child session emitted a `frameAttached`.
      * Topology update + ownership stamped to **emitting session**.
@@ -682,6 +716,8 @@ declare class Page {
      * Return the current page URL (synchronous, cached from navigation events).
      */
     url(): string;
+    private beginNavigationCommand;
+    isCurrentNavigationCommand(id: number): boolean;
     /**
      * Return the current page title.
      * Prefers reading from the active document via Runtime.evaluate to reflect dynamic changes.
@@ -840,65 +876,6 @@ declare class Page {
     waitForMainLoadState(state: LoadState, timeoutMs?: number): Promise<void>;
 }
 
-/**
- * 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 EvaluateOptions = {
-    /** The question to ask about the task state */
-    question: string;
-    /** The answer to the question */
-    answer?: string;
-    /** Whether to take a screenshot of the task state, or array of screenshots to evaluate */
-    screenshot?: boolean | Buffer[];
-    /** Custom system prompt for the evaluator */
-    systemPrompt?: string;
-    /** Delay in milliseconds before taking the screenshot @default 250 */
-    screenshotDelayMs?: number;
-    /** The agent's reasoning/thought process for completing the task */
-    agentReasoning?: string;
-};
-type BatchAskOptions = {
-    /** Array of questions with optional answers */
-    questions: Array<{
-        question: string;
-        answer?: string;
-    }>;
-    /** Whether to take a screenshot of the task state */
-    screenshot?: boolean;
-    /** Custom system prompt for the evaluator */
-    systemPrompt?: string;
-    /** Delay in milliseconds before taking the screenshot @default 1000 */
-    screenshotDelayMs?: number;
-};
-/**
- * Result of an evaluation
- */
-interface EvaluationResult {
-    /**
-     * The evaluation result ('YES', 'NO', or 'INVALID' if parsing failed or value was unexpected)
-     */
-    evaluation: "YES" | "NO" | "INVALID";
-    /**
-     * The reasoning behind the evaluation
-     */
-    reasoning: string;
-}
-
 interface AgentAction {
     type: string;
     reasoning?: string;
@@ -1084,7 +1061,7 @@ interface ActResult {
     actionDescription: string;
     actions: Action[];
 }
-type ExtractResult<T extends z.AnyZodObject> = z.infer<T>;
+type ExtractResult<T extends z$1.AnyZodObject> = z$1.infer<T>;
 interface Action {
     selector: string;
     description: string;
@@ -1092,7 +1069,7 @@ interface Action {
     arguments?: string[];
 }
 interface HistoryEntry {
-    method: "act" | "extract" | "observe" | "navigate";
+    method: "act" | "extract" | "observe" | "navigate" | "agent";
     parameters: unknown;
     result: unknown;
     timestamp: string;
@@ -1103,16 +1080,16 @@ interface ExtractOptions {
     selector?: string;
     page?: Page$1 | Page$2 | Page$3 | Page;
 }
-declare const defaultExtractSchema: z.ZodObject<{
-    extraction: z.ZodString;
-}, "strip", z.ZodTypeAny, {
+declare const defaultExtractSchema: z$1.ZodObject<{
+    extraction: z$1.ZodString;
+}, "strip", z$1.ZodTypeAny, {
     extraction?: string;
 }, {
     extraction?: string;
 }>;
-declare const pageTextSchema: z.ZodObject<{
-    pageText: z.ZodString;
-}, "strip", z.ZodTypeAny, {
+declare const pageTextSchema: z$1.ZodObject<{
+    pageText: z$1.ZodString;
+}, "strip", z$1.ZodTypeAny, {
     pageText?: string;
 }, {
     pageText?: string;
@@ -1130,7 +1107,7 @@ declare enum V3FunctionName {
     AGENT = "AGENT"
 }
 
-interface V3Metrics {
+interface StagehandMetrics {
     actPromptTokens: number;
     actCompletionTokens: number;
     actInferenceTimeMs: number;
@@ -1207,6 +1184,7 @@ interface V3Options {
     /** Directory used to persist cached actions for act(). */
     cacheDir?: string;
     domSettleTimeout?: number;
+    disableAPI?: boolean;
 }
 
 declare class StagehandError extends Error {
@@ -1313,6 +1291,103 @@ declare class StagehandShadowSegmentNotFoundError extends StagehandError {
     constructor(segment: string, hint?: string);
 }
 
+interface StagehandAPIConstructorParams {
+    apiKey: string;
+    projectId: string;
+    logger: (message: LogLine) => void;
+}
+interface StartSessionParams {
+    modelName: string;
+    modelApiKey: string;
+    domSettleTimeoutMs: number;
+    verbose: number;
+    systemPrompt?: string;
+    browserbaseSessionCreateParams?: Omit<Browserbase.Sessions.SessionCreateParams, "projectId"> & {
+        projectId?: string;
+    };
+    selfHeal?: boolean;
+    browserbaseSessionID?: string;
+}
+interface StartSessionResult {
+    sessionId: string;
+    available?: boolean;
+}
+interface APIActParameters {
+    input: string | Action;
+    options?: ActOptions;
+    frameId?: string;
+}
+interface APIExtractParameters {
+    instruction?: string;
+    schema?: ZodTypeAny;
+    options?: ExtractOptions;
+    frameId?: string;
+}
+interface APIObserveParameters {
+    instruction?: string;
+    options?: ObserveOptions;
+    frameId?: string;
+}
+
+/**
+ * Represents a path through a Zod schema from the root object down to a
+ * particular field. The `segments` array describes the chain of keys/indices.
+ *
+ * - **String** segments indicate object property names.
+ * - **Number** segments indicate array indices.
+ *
+ * For example, `["users", 0, "homepage"]` might describe reaching
+ * the `homepage` field in `schema.users[0].homepage`.
+ */
+interface ZodPathSegments {
+    /**
+     * The ordered list of keys/indices leading from the schema root
+     * to the targeted field.
+     */
+    segments: Array<string | number>;
+}
+
+type EvaluateOptions = {
+    /** The question to ask about the task state */
+    question: string;
+    /** The answer to the question */
+    answer?: string;
+    /** Whether to take a screenshot of the task state, or array of screenshots to evaluate */
+    screenshot?: boolean | Buffer[];
+    /** Custom system prompt for the evaluator */
+    systemPrompt?: string;
+    /** Delay in milliseconds before taking the screenshot @default 250 */
+    screenshotDelayMs?: number;
+    /** The agent's reasoning/thought process for completing the task */
+    agentReasoning?: string;
+};
+type BatchAskOptions = {
+    /** Array of questions with optional answers */
+    questions: Array<{
+        question: string;
+        answer?: string;
+    }>;
+    /** Whether to take a screenshot of the task state */
+    screenshot?: boolean;
+    /** Custom system prompt for the evaluator */
+    systemPrompt?: string;
+    /** Delay in milliseconds before taking the screenshot @default 1000 */
+    screenshotDelayMs?: number;
+};
+/**
+ * Result of an evaluation
+ */
+interface EvaluationResult {
+    /**
+     * The evaluation result ('YES', 'NO', or 'INVALID' if parsing failed or value was unexpected)
+     */
+    evaluation: "YES" | "NO" | "INVALID";
+    /**
+     * The reasoning behind the evaluation
+     */
+    reasoning: string;
+}
+
 /**
  * V3Context
  *
@@ -1327,6 +1402,8 @@ declare class StagehandShadowSegmentNotFoundError extends StagehandError {
 declare class V3Context {
     readonly conn: CdpConnection;
     private readonly env;
+    private readonly apiClient;
+    private readonly localBrowserLaunchOptions;
     private constructor();
     private readonly _piercerInstalled;
     private _lastPopupSignalAt;
@@ -1346,6 +1423,8 @@ declare class V3Context {
      */
     static create(wsUrl: string, opts?: {
         env?: "LOCAL" | "BROWSERBASE";
+        apiClient?: StagehandAPIClient | null;
+        localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null;
     }): Promise<V3Context>;
     /**
      * Wait until at least one top-level Page has been created and registered.
@@ -1509,8 +1588,10 @@ declare class V3 {
     private _onCdpClosed;
     readonly experimental: boolean;
     readonly logInferenceToFile: boolean;
+    readonly disableAPI: boolean;
     private externalLogger?;
     verbose: 0 | 1 | 2;
+    private stagehandLogger;
     private _history;
     private readonly instanceId;
     private static _processGuardsInstalled;
@@ -1518,12 +1599,14 @@ declare class V3 {
     private cacheStorage;
     private actCache;
     private agentCache;
-    v3Metrics: V3Metrics;
+    private apiClient;
+    stagehandMetrics: StagehandMetrics;
+    constructor(opts: V3Options);
     /**
      * Async property for metrics so callers can `await v3.metrics`.
      * Returning a Promise future-proofs async aggregation/storage.
      */
-    get metrics(): Promise<V3Metrics>;
+    get metrics(): Promise<StagehandMetrics>;
     private resolveLlmClient;
     private beginAgentReplayRecording;
     private endAgentReplayRecording;
@@ -1539,7 +1622,6 @@ declare class V3 {
     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;
     /**
@@ -1569,10 +1651,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.
      */
@@ -1644,14 +1726,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()`.
@@ -1665,7 +1747,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
@@ -1676,7 +1758,7 @@ declare function injectUrls(obj: unknown, path: Array<string | number>, idToUrlM
 /**
  * Mapping from LLM provider names to their corresponding environment variable names for API keys.
  */
-declare const providerEnvVarMap: Partial<Record<ModelProvider | string, string>>;
+declare const providerEnvVarMap: Partial<Record<ModelProvider | string, string | Array<string>>>;
 /**
  * Loads an API key for a provider, checking environment variables.
  * @param provider The name of the provider (e.g., 'openai', 'anthropic')
@@ -1734,4 +1816,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 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, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Metrics, type V3Options, XPathResolutionError, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, jsonSchemaToZod, loadApiKeyFromEnv, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, transformSchema, trimTrailingTextNode, validateZodSchema };
+export { type AISDKCustomProvider, type AISDKProvider, AVAILABLE_CUA_MODELS, type ActOptions, type ActResult, type Action, type ActionExecutionResult, type AgentAction, type AgentConfig, type AgentExecuteOptions, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentModelConfig, AgentProvider, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AnyPage, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, HandlerNotInitializedError, type HistoryEntry, InvalidAISDKModelFormatError, type JsonSchema, type JsonSchemaProperty, LLMClient, type LLMResponse, LLMResponseError, type LLMTool, LOG_LEVEL_NAMES, type LoadState, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelProvider, type ObserveOptions, type ResponseInputItem, type ResponseItem, V3 as Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, XPathResolutionError, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, jsonSchemaToZod, loadApiKeyFromEnv, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, transformSchema, trimTrailingTextNode, validateZodSchema };