@browserbasehq/orca 3.0.0-preview.0

package/dist/lib/v3/llm/LLMClient.d.ts

@@ -0,0 +1,99 @@
+import { LLMTool } from "../types/llm";
+import { embed, embedMany, experimental_generateImage, experimental_generateSpeech, experimental_transcribe, generateObject, generateText, LanguageModel, streamObject, streamText } from "ai";
+import { ZodType } from "zod/v3";
+import { LogLine } from "../types/log";
+import { AvailableModel, ClientOptions } from "../types/model";
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: ChatMessageContent;
+}
+export type ChatMessageContent = string | (ChatMessageImageContent | ChatMessageTextContent)[];
+export interface ChatMessageImageContent {
+    type: string;
+    image_url?: {
+        url: string;
+    };
+    text?: string;
+    source?: {
+        type: string;
+        media_type: string;
+        data: string;
+    };
+}
+export interface ChatMessageTextContent {
+    type: string;
+    text: string;
+}
+export 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.";
+export 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;
+}
+export 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;
+    };
+};
+export interface CreateChatCompletionOptions {
+    options: ChatCompletionOptions;
+    logger: (message: LogLine) => void;
+    retries?: number;
+}
+export 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;
+}

package/dist/lib/v3/llm/LLMProvider.d.ts

@@ -0,0 +1,10 @@
+import { LogLine } from "../types/log";
+import { AvailableModel, ClientOptions, ModelProvider } from "../types/model";
+import { LLMClient } from "./LLMClient";
+export declare function getAISDKLanguageModel(subProvider: string, subModelName: string, apiKey?: string, baseURL?: string): import("ai/dist").LanguageModelV1;
+export declare class LLMProvider {
+    private logger;
+    constructor(logger: (message: LogLine) => void);
+    getClient(modelName: AvailableModel, clientOptions?: ClientOptions): LLMClient;
+    static getModelProvider(modelName: AvailableModel): ModelProvider;
+}

package/dist/lib/v3/llm/OpenAIClient.d.ts

@@ -0,0 +1,15 @@
+import { ClientOptions } from "openai";
+import { LogLine } from "../types/log";
+import { AvailableModel } from "../types/model";
+import { CreateChatCompletionOptions, LLMClient, LLMResponse } from "./LLMClient";
+export declare class OpenAIClient extends LLMClient {
+    type: "openai";
+    private client;
+    clientOptions: ClientOptions;
+    constructor({ modelName, clientOptions, }: {
+        logger: (message: LogLine) => void;
+        modelName: AvailableModel;
+        clientOptions?: ClientOptions;
+    });
+    createChatCompletion<T = LLMResponse>({ options: optionsInitial, logger, retries, }: CreateChatCompletionOptions): Promise<T>;
+}

package/dist/lib/v3/llm/aisdk.d.ts

@@ -0,0 +1,15 @@
+import { LanguageModel } from "ai";
+import { ChatCompletion } from "openai/resources";
+import { LogLine } from "../types/log";
+import { CreateChatCompletionOptions, LLMClient } from "./LLMClient";
+export declare class AISdkClient extends LLMClient {
+    type: "aisdk";
+    private model;
+    private logger?;
+    constructor({ model, logger, }: {
+        model: LanguageModel;
+        logger?: (message: LogLine) => void;
+    });
+    getLanguageModel(): LanguageModel;
+    createChatCompletion<T = ChatCompletion>({ options, }: CreateChatCompletionOptions): Promise<T>;
+}

package/dist/lib/v3/logger.d.ts

@@ -0,0 +1,48 @@
+import type { LogLine } from "./types/log";
+/**
+ * Stagehand V3 Logging
+ *
+ * Design goals:
+ * - Provide a single global logging sink (Pino or console) for general output.
+ * - Support concurrent V3 instances by routing logs to an instance-bound external logger
+ *   (e.g., Braintrust EvalLogger) without cross-talk.
+ * - Keep the public API simple: per-instance binding happens via V3, not here.
+ *
+ * How it works:
+ * - initV3Logger(): initializes the global logger backend (Pino if enabled, otherwise a
+ *   lightweight console logger). No external logger is bound globally.
+ * - bindInstanceLogger()/unbindInstanceLogger(): registers an external logger callback per
+ *   instance id for use by v3Logger.
+ * - withInstanceLogContext(): establishes a context so v3Logger can route logs to the
+ *   correct instance's external logger during that call tree.
+ * - v3Logger(): preferred entrypoint for emitting structured logs from V3 internals and handlers.
+ *   It routes to the instance logger when available, or falls back to the global backend.
+ */
+type Verbosity = 0 | 1 | 2;
+type MinimalLogger = {
+    log: (line: LogLine) => void;
+    setVerbosity: (v: Verbosity) => void;
+    error: (msg: string, data?: Record<string, unknown>) => void;
+    info: (msg: string, data?: Record<string, unknown>) => void;
+    debug: (msg: string, data?: Record<string, unknown>) => void;
+};
+export declare function bindInstanceLogger(instanceId: string, logger: (line: LogLine) => void): void;
+export declare function unbindInstanceLogger(instanceId: string): void;
+export declare function withInstanceLogContext<T>(instanceId: string, fn: () => T): T;
+/**
+ * Initialize the global V3 logger backend.
+ * - When disablePino is false (default), uses the Stagehand Pino logger for rich console output.
+ * - When disablePino is true, uses a lightweight console logger that respects verbosity.
+ *
+ * Note: This function never binds an external logger globally. Use bindInstanceLogger()
+ * with withInstanceLogContext() for per-instance routing.
+ */
+export declare function initV3Logger(opts?: {
+    verbose?: Verbosity;
+    disablePino?: boolean;
+    pretty?: boolean;
+}): Promise<void>;
+export declare function getV3Logger(): MinimalLogger;
+export declare function v3Logger(line: LogLine): void;
+export declare function setV3Verbosity(v: Verbosity): void;
+export {};

package/dist/lib/v3/mcp/connection.d.ts

@@ -0,0 +1,11 @@
+import { Client, ClientOptions } from "@modelcontextprotocol/sdk/client/index.js";
+export interface ConnectToMCPServerOptions {
+    serverUrl: string | URL;
+    clientOptions?: ClientOptions;
+}
+export interface StdioServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+export declare const connectToMCPServer: (serverConfig: string | URL | StdioServerConfig | ConnectToMCPServerOptions) => Promise<Client>;

package/dist/lib/v3/mcp/utils.d.ts

@@ -0,0 +1,3 @@
+import { Client } from "@modelcontextprotocol/sdk/dist/esm/client";
+import { ToolSet } from "ai/dist";
+export declare const resolveTools: (clients: (Client | string)[], userTools: ToolSet) => Promise<ToolSet>;

package/dist/lib/v3/tests/default-page-tracking.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/v3/tests/perform-understudy-method.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/v3/tests/shadow-iframe.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/v3/tests/timeouts.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/v3/tests/v3.config.d.ts

@@ -0,0 +1,4 @@
+import type { V3Options } from "@/lib/v3/types";
+export declare const v3TestConfig: V3Options;
+export declare function getV3TestConfig(overrides?: Partial<V3Options>): V3Options;
+export default getV3TestConfig;

package/dist/lib/v3/tests/v3.playwright.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@playwright/test").PlaywrightTestConfig<{}, {}>;
+export default _default;

package/dist/lib/v3/tests/xpath-for-location-deep.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/v3/types/act.d.ts

@@ -0,0 +1,10 @@
+export declare enum SupportedPlaywrightAction {
+    CLICK = "click",
+    FILL = "fill",
+    TYPE = "type",
+    PRESS = "press",
+    SCROLL = "scrollTo",
+    NEXT_CHUNK = "nextChunk",
+    PREV_CHUNK = "prevChunk",
+    SELECT_OPTION_FROM_DROPDOWN = "selectOptionFromDropdown"
+}

package/dist/lib/v3/types/agent.d.ts

@@ -0,0 +1,132 @@
+import { LogLine } from "./log";
+export interface AgentAction {
+    type: string;
+    reasoning?: string;
+    taskCompleted?: boolean;
+    action?: string;
+    timeMs?: number;
+    pageText?: string;
+    pageUrl?: string;
+    instruction?: string;
+    [key: string]: unknown;
+}
+export 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;
+    };
+}
+export interface AgentOptions {
+    maxSteps?: number;
+    autoScreenshot?: boolean;
+    waitBetweenActions?: number;
+    context?: string;
+}
+export interface AgentExecuteOptions extends AgentOptions {
+    instruction: string;
+}
+export type AgentProviderType = "openai" | "anthropic";
+export interface AgentClientOptions {
+    apiKey: string;
+    organization?: string;
+    baseURL?: string;
+    defaultMaxSteps?: number;
+    [key: string]: unknown;
+}
+export type AgentType = "openai" | "anthropic";
+export interface AgentExecutionOptions {
+    options: AgentExecuteOptions;
+    logger: (message: LogLine) => void;
+    retries?: number;
+}
+export interface AgentHandlerOptions {
+    modelName: string;
+    clientOptions?: Record<string, unknown>;
+    userProvidedInstructions?: string;
+    agentType: AgentType;
+    experimental?: boolean;
+}
+export interface ActionExecutionResult {
+    success: boolean;
+    error?: string;
+    data?: unknown;
+}
+export interface ToolUseItem extends ResponseItem {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface AnthropicMessage {
+    role: string;
+    content: string | Array<AnthropicContentBlock>;
+}
+export interface AnthropicContentBlock {
+    type: string;
+    [key: string]: unknown;
+}
+export interface AnthropicTextBlock extends AnthropicContentBlock {
+    type: "text";
+    text: string;
+}
+export interface AnthropicToolResult {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string | Array<AnthropicContentBlock>;
+}
+export interface ResponseItem {
+    type: string;
+    id: string;
+    [key: string]: unknown;
+}
+export 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;
+    }>;
+}
+export interface FunctionCallItem extends ResponseItem {
+    type: "function_call";
+    call_id: string;
+    name: string;
+    arguments: string;
+}
+export 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;
+};
+export interface AgentInstance {
+    execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
+}

package/dist/lib/v3/types/api.d.ts

@@ -0,0 +1,40 @@
+import Browserbase from "@browserbasehq/sdk";
+import { LogLine } from "./log";
+export interface StagehandAPIConstructorParams {
+    apiKey: string;
+    projectId: string;
+    logger: (message: LogLine) => void;
+}
+export interface ExecuteActionParams {
+    method: "act" | "extract" | "observe" | "navigate" | "end" | "agentExecute";
+    args?: unknown;
+    params?: unknown;
+}
+export interface StartSessionParams {
+    modelName: string;
+    modelApiKey: string;
+    domSettleTimeoutMs: number;
+    verbose: number;
+    debugDom: boolean;
+    systemPrompt?: string;
+    browserbaseSessionCreateParams?: Omit<Browserbase.Sessions.SessionCreateParams, "projectId"> & {
+        projectId?: string;
+    };
+    selfHeal?: boolean;
+    waitForCaptchaSolves?: boolean;
+    actionTimeoutMs?: number;
+    browserbaseSessionID?: string;
+}
+export interface StartSessionResult {
+    sessionId: string;
+    available?: boolean;
+}
+export interface SuccessResponse<T> {
+    success: true;
+    data: T;
+}
+export interface ErrorResponse {
+    success: false;
+    message: string;
+}
+export type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;

package/dist/lib/v3/types/cache.d.ts

@@ -0,0 +1,71 @@
+import type { AgentResult } from "@/lib/v3/types/agent";
+import type { Action } from "@/lib/v3/types/stagehand";
+import type { LoadState } from "@/lib/v3/types";
+export interface CachedActEntry {
+    version: 1;
+    instruction: string;
+    url: string;
+    variables: Record<string, string>;
+    actions: Action[];
+    actionDescription?: string;
+    message?: string;
+}
+export type AgentReplayStep = AgentReplayActStep | AgentReplayFillFormStep | AgentReplayGotoStep | AgentReplayScrollStep | AgentReplayWaitStep | AgentReplayNavBackStep | {
+    type: string;
+    [key: string]: unknown;
+};
+export interface AgentReplayActStep {
+    type: "act";
+    instruction: string;
+    actions?: Action[];
+    actionDescription?: string;
+    message?: string;
+    timeout?: number;
+}
+export interface AgentReplayFillFormStep {
+    type: "fillForm";
+    fields?: Array<{
+        action: string;
+        value: string;
+    }>;
+    observeResults?: Action[];
+    actions?: Action[];
+}
+export interface AgentReplayGotoStep {
+    type: "goto";
+    url: string;
+    waitUntil?: LoadState;
+}
+export interface AgentReplayScrollStep {
+    type: "scroll";
+    deltaX?: number;
+    deltaY?: number;
+    anchor?: {
+        x: number;
+        y: number;
+    };
+}
+export interface AgentReplayWaitStep {
+    type: "wait";
+    timeMs: number;
+}
+export interface AgentReplayNavBackStep {
+    type: "navback";
+    waitUntil?: LoadState;
+}
+export interface SanitizedAgentExecuteOptions {
+    maxSteps?: number;
+    autoScreenshot?: boolean;
+    waitBetweenActions?: number;
+    context?: string;
+}
+export interface CachedAgentEntry {
+    version: 1;
+    instruction: string;
+    startUrl: string;
+    options: SanitizedAgentExecuteOptions;
+    configSignature: string;
+    steps: AgentReplayStep[];
+    result: AgentResult;
+    timestamp: string;
+}

package/dist/lib/v3/types/context.d.ts

@@ -0,0 +1,2 @@
+export type EncodedId = `${number}-${number}`;
+export declare const ID_PATTERN: RegExp;

package/dist/lib/v3/types/evals.d.ts

@@ -0,0 +1,71 @@
+import { z } from "zod/v3";
+import type { AvailableModel } from "../types/model";
+import type { LogLine } from "../types/log";
+import type { AgentInstance } from "../types/agent";
+import type { EvalCase } from "braintrust";
+import type { V3 } from "@/lib/v3/v3";
+import { EvalLogger } from "@/evals/logger";
+export type StagehandInitResult = {
+    v3?: V3;
+    v3Agent?: AgentInstance;
+    logger: EvalLogger;
+    debugUrl: string;
+    sessionUrl: string;
+    modelName: AvailableModel;
+    agent: AgentInstance;
+};
+export type EvalFunction = (taskInput: StagehandInitResult & {
+    input: EvalInput;
+}) => Promise<{
+    _success: boolean;
+    logs: LogLine[];
+    debugUrl: string;
+    sessionUrl: string;
+    error?: unknown;
+}>;
+export declare const EvalCategorySchema: z.ZodEnum<["observe", "act", "combination", "extract", "experimental", "targeted_extract", "regression", "regression_llm_providers", "llm_clients", "agent", "external_agent_benchmarks"]>;
+export type EvalCategory = z.infer<typeof EvalCategorySchema>;
+export interface EvalInput {
+    name: string;
+    modelName: AvailableModel;
+    params?: Record<string, unknown>;
+}
+export interface Testcase extends EvalCase<EvalInput, unknown, {
+    model: AvailableModel;
+    test: string;
+    categories?: string[];
+}> {
+    input: EvalInput;
+    name: string;
+    tags: string[];
+    metadata: {
+        model: AvailableModel;
+        test: string;
+        categories?: string[];
+    };
+    expected: unknown;
+}
+export interface SummaryResult {
+    input: EvalInput;
+    output: {
+        _success: boolean;
+    };
+    name: string;
+    score: number;
+}
+export interface EvalArgs<TInput, TOutput, TExpected> {
+    input: TInput;
+    output: TOutput;
+    expected: TExpected;
+    metadata?: {
+        model: AvailableModel;
+        test: string;
+    };
+}
+export interface EvalResult {
+    name: string;
+    score: number;
+}
+export type LogLineEval = LogLine & {
+    parsedAuxiliary?: string | object;
+};

package/dist/lib/v3/types/evaluator.d.ts

@@ -0,0 +1,40 @@
+export 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;
+};
+export 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
+ */
+export 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;
+}

package/dist/lib/v3/types/llm.d.ts

@@ -0,0 +1,11 @@
+import { LanguageModel } from "ai";
+export interface LLMTool {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export type AISDKProvider = (modelName: string) => LanguageModel;
+export type AISDKCustomProvider = (options: {
+    apiKey: string;
+}) => AISDKProvider;

package/dist/lib/v3/types/log.d.ts

@@ -0,0 +1,23 @@
+export 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
+ */
+export declare const LOG_LEVEL_NAMES: Record<LogLevel, string>;
+export type LogLine = {
+    id?: string;
+    category?: string;
+    message: string;
+    level?: LogLevel;
+    timestamp?: string;
+    auxiliary?: {
+        [key: string]: {
+            value: string;
+            type: "object" | "string" | "html" | "integer" | "float" | "boolean";
+        };
+    };
+};
+export type Logger = (logLine: LogLine) => void;

package/dist/lib/v3/types/model.d.ts

@@ -0,0 +1,20 @@
+import type { ClientOptions as AnthropicClientOptions } from "@anthropic-ai/sdk";
+import type { ClientOptions as OpenAIClientOptions } from "openai";
+import { z } from "zod/v3";
+export 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"]>;
+export type AvailableModel = z.infer<typeof AvailableModelSchema> | string;
+export type ModelProvider = "openai" | "anthropic" | "cerebras" | "groq" | "google" | "aisdk";
+export type ClientOptions = OpenAIClientOptions | AnthropicClientOptions;
+export type ModelConfiguration = AvailableModel | (ClientOptions & {
+    modelName: AvailableModel;
+});
+export interface AnthropicJsonSchemaObject {
+    definitions?: {
+        MySchema?: {
+            properties?: Record<string, unknown>;
+            required?: string[];
+        };
+    };
+    properties?: Record<string, unknown>;
+    required?: string[];
+}

package/dist/lib/v3/types/playwright.d.ts

@@ -0,0 +1,6 @@
+export interface GotoOptions {
+    timeout?: number;
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+    referer?: string;
+    frameId?: string;
+}