@browserbasehq/orca 3.0.0-preview.1 → 3.0.0-preview.4

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

@@ -1,158 +0,0 @@
-import { V3Options, ActOptions, ObserveOptions, V3Metrics, V3FunctionName, ExtractOptions } from "@/lib/v3/types";
-import { V3Context } from "@/lib/v3/understudy/context";
-import { LLMClient } from "./llm/LLMClient";
-import { z } from "zod/v3";
-import type { ZodTypeAny } from "zod/v3";
-import { Action, ActResult, HistoryEntry, AgentConfig } from "./types/stagehand";
-import { AgentExecuteOptions, AgentResult } from "./types/agent";
-import { LogLine } from "./types/log";
-import { defaultExtractSchema, pageTextSchema } from "./types";
-import type { AgentReplayStep } from "./types/cache";
-/**
- * V3
- *
- * Purpose:
- * A high-level orchestrator for Stagehand V3. Abstracts away whether the browser
- * runs **locally via Chrome** or remotely on **Browserbase**, and exposes simple
- * entrypoints (`act`, `extract`, `observe`) that delegate to the corresponding
- * handler classes.
- *
- * Responsibilities:
- * - Bootstraps Chrome or Browserbase, ensures a working CDP WebSocket, and builds a `V3Context`.
- * - Manages lifecycle: init, context access, cleanup.
- * - Bridges external page objects (Playwright/Puppeteer) into internal frameIds for handlers.
- * - Provides a stable API surface for downstream code regardless of runtime environment.
- */
-export declare class V3 {
-    private readonly opts;
-    private state;
-    private actHandler;
-    private extractHandler;
-    private observeHandler;
-    private ctx;
-    llmClient: LLMClient;
-    private modelName;
-    private modelClientOptions;
-    private llmProvider;
-    private readonly domSettleTimeoutMs?;
-    private _isClosing;
-    browserbaseSessionId?: string;
-    private _onCdpClosed;
-    readonly experimental: boolean;
-    readonly logInferenceToFile: boolean;
-    private externalLogger?;
-    verbose: 0 | 1 | 2;
-    private _history;
-    private readonly instanceId;
-    private static _processGuardsInstalled;
-    private static _instances;
-    private cacheDir?;
-    private _agentReplayRecording;
-    v3Metrics: V3Metrics;
-    /**
-     * Async property for metrics so callers can `await v3.metrics`.
-     * Returning a Promise future-proofs async aggregation/storage.
-     */
-    get metrics(): Promise<V3Metrics>;
-    private cloneForCache;
-    private beginAgentReplayRecording;
-    private endAgentReplayRecording;
-    private discardAgentReplayRecording;
-    private isAgentReplayRecording;
-    isAgentReplayActive(): boolean;
-    recordAgentReplayStep(step: AgentReplayStep): void;
-    /**
-     * Async property for history so callers can `await v3.history`.
-     * Returns a frozen copy to avoid external mutation.
-     */
-    get history(): Promise<ReadonlyArray<HistoryEntry>>;
-    addToHistory(method: HistoryEntry["method"], parameters: unknown, result?: unknown): void;
-    updateMetrics(functionName: V3FunctionName, promptTokens: number, completionTokens: number, inferenceTimeMs: number): void;
-    private updateTotalMetrics;
-    constructor(opts: V3Options);
-    private _immediateShutdown;
-    private static _installProcessGuards;
-    /**
-     * Entrypoint: initializes handlers, launches Chrome or Browserbase,
-     * and sets up a CDP context.
-     */
-    init(): Promise<void>;
-    /** Apply post-connect local browser options that require CDP. */
-    private _applyPostConnectLocalOptions;
-    private _ensureBrowserbaseDownloadsEnabled;
-    /**
-     * Run an "act" instruction through the ActHandler.
-     *
-     * New API:
-     * - act(instruction: string, options?: ActOptions)
-     * - act(action: Action, options?: ActOptions)
-     */
-    act(instruction: string, options?: ActOptions): Promise<ActResult>;
-    act(action: Action, options?: ActOptions): Promise<ActResult>;
-    /**
-     * Run an "extract" instruction through the ExtractHandler.
-     *
-     * Accepted forms:
-     * - extract() → pageText
-     * - extract(options) → pageText
-     * - extract(instruction) → defaultExtractSchema
-     * - extract(instruction, schema) → schema-inferred
-     * - extract(instruction, schema, options)
-     */
-    extract(): Promise<z.infer<typeof pageTextSchema>>;
-    extract(options: ExtractOptions): 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>>;
-    /**
-     * Run an "observe" instruction through the ObserveHandler.
-     */
-    observe(): Promise<Action[]>;
-    observe(options: ObserveOptions): Promise<Action[]>;
-    observe(instruction: string, options?: ObserveOptions): Promise<Action[]>;
-    /** Return the browser-level CDP WebSocket endpoint. */
-    connectURL(): string;
-    /** Expose the current CDP-backed context. */
-    get context(): V3Context;
-    /** Best-effort cleanup of context and launched resources. */
-    close(opts?: {
-        force?: boolean;
-    }): Promise<void>;
-    /** Guard: ensure Browserbase credentials exist in options. */
-    private requireBrowserbaseCreds;
-    get logger(): (logLine: LogLine) => void;
-    /**
-     * Normalize a Playwright/Puppeteer page object into its top frame id,
-     * so handlers can resolve it to a `Page` within our V3Context.
-     */
-    private resolveTopFrameId;
-    private isPlaywrightPage;
-    private isPatchrightPage;
-    private isPuppeteerPage;
-    private normalizeToV3Page;
-    private buildActCacheKey;
-    private safeGetPageUrl;
-    private readActCacheEntry;
-    private writeActCacheEntry;
-    private sanitizeAgentExecuteOptions;
-    private buildAgentCacheSignature;
-    private buildAgentCacheKey;
-    private readAgentCacheEntry;
-    private writeAgentCacheEntry;
-    private replayAgentCacheEntry;
-    private executeAgentReplayStep;
-    private replayAgentActStep;
-    private replayAgentFillFormStep;
-    private replayAgentGotoStep;
-    private replayAgentScrollStep;
-    private replayAgentWaitStep;
-    private replayAgentNavBackStep;
-    private replayCachedActions;
-    private runWithActTimeout;
-    /**
-     * Create a v3 agent instance (AISDK tool-based) with execute().
-     * Mirrors the v2 Stagehand.agent() tool mode (no CUA provider here).
-     */
-    agent(options?: AgentConfig): {
-        execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
-    };
-}

package/dist/lib/version.d.ts

@@ -1,5 +0,0 @@
-/**
- * AUTO-GENERATED — DO NOT EDIT BY HAND
- *  Run `pnpm run gen-version` to refresh.
- */
-export declare const STAGEHAND_VERSION: "3.0.0-preview.1";

package/dist/stagehand.config.d.ts

@@ -1,3 +0,0 @@
-import type { ConstructorParams } from "@/dist";
-declare const StagehandConfig: ConstructorParams;
-export default StagehandConfig;

package/dist/types/act.d.ts

@@ -1,50 +0,0 @@
-import { LLMClient } from "../lib/llm/LLMClient";
-import { Locator } from "playwright";
-import { Logger } from "@/types/log";
-import { StagehandPage } from "@/lib/StagehandPage";
-export interface ActCommandParams {
-    action: string;
-    steps?: string;
-    domElements: string;
-    llmClient: LLMClient;
-    retries?: number;
-    logger: (message: {
-        category?: string;
-        message: string;
-    }) => void;
-    requestId: string;
-    variables?: Record<string, string>;
-    userProvidedInstructions?: string;
-}
-export interface ActCommandResult {
-    method: string;
-    element: number;
-    args: unknown[];
-    completed: boolean;
-    step: string;
-    why?: string;
-}
-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"
-}
-/**
- * A context object to hold all parameters that might be needed by
- * any of the methods in the `methodHandlerMap`
- */
-export interface MethodHandlerContext {
-    method: string;
-    locator: Locator;
-    xpath: string;
-    args: unknown[];
-    logger: Logger;
-    stagehandPage: StagehandPage;
-    initialUrl: string;
-    domSettleTimeoutMs?: number;
-}

package/dist/types/agent.d.ts

@@ -1,143 +0,0 @@
-import { LogLine } from "./log";
-import { ObserveResult } from "./stagehand";
-export interface ActToolResult {
-    success: boolean;
-    action?: string;
-    error?: string;
-    isIframe?: boolean;
-    playwrightArguments?: ObserveResult | null;
-}
-export interface AgentAction {
-    type: string;
-    reasoning?: string;
-    taskCompleted?: boolean;
-    action?: string;
-    timeMs?: number;
-    pageText?: string;
-    pageUrl?: string;
-    instruction?: string;
-    playwrightArguments?: ObserveResult | null;
-    [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;
-    highlightCursor?: boolean;
-}
-export interface AgentExecuteOptions extends AgentOptions {
-    instruction: string;
-}
-export type AgentProviderType = "openai" | "anthropic" | "google";
-export interface AgentClientOptions {
-    apiKey: string;
-    organization?: string;
-    baseURL?: string;
-    defaultMaxSteps?: number;
-    [key: string]: unknown;
-}
-export type AgentType = "openai" | "anthropic" | "google";
-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>;
-    setScreenshotCollector?: (collector: unknown) => void;
-}

package/dist/types/api.d.ts

@@ -1,40 +0,0 @@
-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/types/browser.d.ts

@@ -1,10 +0,0 @@
-import { Browser, BrowserContext } from "./page";
-export interface BrowserResult {
-    env: "LOCAL" | "BROWSERBASE";
-    browser?: Browser;
-    context: BrowserContext;
-    debugUrl?: string;
-    sessionUrl?: string;
-    contextPath?: string;
-    sessionId?: string;
-}

package/dist/types/context.d.ts

@@ -1,117 +0,0 @@
-import type { BrowserContext as PlaywrightContext, Frame } from "playwright";
-import { Page } from "../types/page";
-export interface AXNode {
-    role?: {
-        value: string;
-    };
-    name?: {
-        value: string;
-    };
-    description?: {
-        value: string;
-    };
-    value?: {
-        value: string;
-    };
-    nodeId: string;
-    backendDOMNodeId?: number;
-    parentId?: string;
-    childIds?: string[];
-    properties?: {
-        name: string;
-        value: {
-            type: string;
-            value?: string;
-        };
-    }[];
-}
-export type AccessibilityNode = {
-    role: string;
-    name?: string;
-    description?: string;
-    value?: string;
-    children?: AccessibilityNode[];
-    childIds?: string[];
-    parentId?: string;
-    nodeId?: string;
-    backendDOMNodeId?: number;
-    properties?: {
-        name: string;
-        value: {
-            type: string;
-            value?: string;
-        };
-    }[];
-};
-export interface TreeResult {
-    tree: AccessibilityNode[];
-    simplified: string;
-    iframes?: AccessibilityNode[];
-    idToUrl: Record<EncodedId, string>;
-    xpathMap: Record<EncodedId, string>;
-}
-export type DOMNode = {
-    backendNodeId?: number;
-    nodeName?: string;
-    children?: DOMNode[];
-    shadowRoots?: DOMNode[];
-    contentDocument?: DOMNode;
-    nodeType: number;
-    frameId?: string;
-};
-export type BackendIdMaps = {
-    tagNameMap: Record<number, string>;
-    xpathMap: Record<number, string>;
-    iframeXPath?: string;
-};
-export interface EnhancedContext extends Omit<PlaywrightContext, "newPage" | "pages"> {
-    newPage(): Promise<Page>;
-    pages(): Page[];
-}
-export type FrameId = string;
-export type LoaderId = string;
-export interface CdpFrame {
-    id: FrameId;
-    parentId?: FrameId;
-    loaderId: LoaderId;
-    name?: string;
-    url: string;
-    urlFragment?: string;
-    domainAndRegistry?: string;
-    securityOrigin: string;
-    securityOriginDetails?: Record<string, unknown>;
-    mimeType: string;
-    unreachableUrl?: string;
-    adFrameStatus?: string;
-    secureContextType?: string;
-    crossOriginIsolatedContextType?: string;
-    gatedAPIFeatures?: string[];
-}
-export interface CdpFrameTree {
-    frame: CdpFrame;
-    childFrames?: CdpFrameTree[];
-}
-export interface FrameOwnerResult {
-    backendNodeId?: number;
-}
-export interface CombinedA11yResult {
-    combinedTree: string;
-    combinedXpathMap: Record<EncodedId, string>;
-    combinedUrlMap: Record<EncodedId, string>;
-}
-export interface FrameSnapshot {
-    frame: Frame;
-    tree: string;
-    xpathMap: Record<EncodedId, string>;
-    urlMap: Record<EncodedId, string>;
-    frameXpath: string;
-    backendNodeId: number | null;
-    parentFrame?: Frame;
-    /** CDP frame identifier for this snapshot; used to generate stable EncodedIds. */
-    frameId?: string;
-}
-export type EncodedId = `${number}-${number}`;
-export interface RichNode extends AccessibilityNode {
-    encodedId?: EncodedId;
-}
-export declare const ID_PATTERN: RegExp;

package/dist/types/evals.d.ts

@@ -1,94 +0,0 @@
-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 { Stagehand } from "@/dist";
-import { ConstructorParams } from "@/dist";
-import { EvalLogger } from "@/evals/logger";
-export type StagehandInitResult = {
-    stagehand: Stagehand;
-    logger: EvalLogger;
-    debugUrl: string;
-    sessionUrl: string;
-    stagehandConfig: ConstructorParams;
-    modelName: AvailableModel;
-    agent: AgentInstance;
-};
-export declare enum ErrorType {
-    TIMEOUT = "timeout",
-    NETWORK = "network",
-    AGENT_FAILURE = "agent_failure",
-    EVALUATION_ERROR = "evaluation_error",
-    SETUP_ERROR = "setup_error",
-    PARSING_ERROR = "parsing_error",
-    ANTIBOT = "bot_detected",
-    UNKNOWN = "unknown"
-}
-export interface EvalOutput {
-    _success: boolean;
-    logs: LogLine[];
-    debugUrl: string;
-    sessionUrl: string;
-    error?: unknown;
-    error_type?: ErrorType;
-    error_message?: string;
-    error_stack?: string;
-    execution_time?: number;
-    agent_steps?: number;
-    final_answer?: string;
-    reasoning?: string;
-    observations?: string | unknown;
-    [key: string]: unknown;
-}
-export type EvalFunction = (taskInput: StagehandInitResult & {
-    input: EvalInput;
-}) => Promise<EvalOutput>;
-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 TestcaseMetadata {
-    model: AvailableModel;
-    test: string;
-    category?: string;
-    dataset?: string;
-    dataset_id?: string;
-    dataset_level?: string | number;
-    dataset_category?: string;
-    [key: string]: unknown;
-}
-export interface Testcase extends EvalCase<EvalInput, unknown, TestcaseMetadata> {
-    input: EvalInput;
-    name: string;
-    tags: string[];
-    metadata: TestcaseMetadata;
-    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/types/evaluator.d.ts

@@ -1,40 +0,0 @@
-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/types/llm.d.ts

@@ -1,11 +0,0 @@
-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;