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

package/dist/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/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/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/types/model.d.ts

@@ -0,0 +1,17 @@
+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 interface AnthropicJsonSchemaObject {
+    definitions?: {
+        MySchema?: {
+            properties?: Record<string, unknown>;
+            required?: string[];
+        };
+    };
+    properties?: Record<string, unknown>;
+    required?: string[];
+}

package/dist/types/page.d.ts

@@ -0,0 +1,38 @@
+import type { Browser as PlaywrightBrowser, BrowserContext as PlaywrightContext, Page as PlaywrightPage, PageScreenshotOptions } from "playwright";
+import { z } from "zod/v3";
+import type { ActOptions, ActResult, ExtractOptions, ExtractResult, ObserveOptions, ObserveResult } from "./stagehand";
+export declare const defaultExtractSchema: z.ZodObject<{
+    extraction: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    extraction?: string;
+}, {
+    extraction?: string;
+}>;
+export declare const pageTextSchema: z.ZodObject<{
+    page_text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    page_text?: string;
+}, {
+    page_text?: string;
+}>;
+export interface StagehandScreenshotOptions extends PageScreenshotOptions {
+    /** Controls whether to use CDP for screenshots in Browserbase environment. Defaults to true. */
+    useCDP?: boolean;
+}
+export interface Page extends Omit<PlaywrightPage, "on" | "screenshot"> {
+    act(action: string): Promise<ActResult>;
+    act(options: ActOptions): Promise<ActResult>;
+    act(observation: ObserveResult): Promise<ActResult>;
+    extract(instruction: string): Promise<ExtractResult<typeof defaultExtractSchema>>;
+    extract<T extends z.AnyZodObject>(options: ExtractOptions<T>): Promise<ExtractResult<T>>;
+    extract(): Promise<ExtractResult<typeof pageTextSchema>>;
+    observe(): Promise<ObserveResult[]>;
+    observe(instruction: string): Promise<ObserveResult[]>;
+    observe(options?: ObserveOptions): Promise<ObserveResult[]>;
+    screenshot(options?: StagehandScreenshotOptions): Promise<Buffer>;
+    on: {
+        (event: "popup", listener: (page: Page) => unknown): Page;
+    } & PlaywrightPage["on"];
+}
+export type BrowserContext = PlaywrightContext;
+export type Browser = PlaywrightBrowser;

package/dist/types/playwright.d.ts

@@ -0,0 +1,12 @@
+export declare class PlaywrightCommandException extends Error {
+    constructor(message: string);
+}
+export declare class PlaywrightCommandMethodNotSupportedException extends Error {
+    constructor(message: string);
+}
+export interface GotoOptions {
+    timeout?: number;
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+    referer?: string;
+    frameId?: string;
+}

package/dist/types/stagehand.d.ts

@@ -0,0 +1,330 @@
+import Browserbase from "@browserbasehq/sdk";
+import { Client } from "@modelcontextprotocol/sdk/dist/esm/client";
+import { ToolSet } from "ai";
+import { Cookie } from "playwright";
+import { z } from "zod/v3";
+import { LLMClient } from "../lib/llm/LLMClient";
+import { LLMProvider } from "../lib/llm/LLMProvider";
+import { AgentProviderType } from "./agent";
+import { LogLine } from "./log";
+import { AvailableModel, ClientOptions } from "./model";
+export interface ConstructorParams {
+    /**
+     * The environment to use for Stagehand
+     */
+    env: "LOCAL" | "BROWSERBASE";
+    /**
+     * Your Browserbase API key
+     */
+    apiKey?: string;
+    /**
+     * Your Browserbase project ID
+     */
+    projectId?: string;
+    /**
+     * The verbosity of the Stagehand logger
+     * 0 - No logs
+     * 1 - Only errors
+     * 2 - All logs
+     */
+    verbose?: 0 | 1 | 2;
+    /**
+     * The LLM provider to use for Stagehand
+     * See
+     */
+    llmProvider?: LLMProvider;
+    /**
+     * The logger to use for Stagehand
+     */
+    logger?: (message: LogLine) => void | Promise<void>;
+    /**
+     * The timeout to use for the DOM to settle
+     * @default 10000
+     */
+    domSettleTimeoutMs?: number;
+    /**
+     * The parameters to use for creating a Browserbase session
+     * See https://docs.browserbase.com/reference/api/create-a-session
+     * Note: projectId is optional here as it will use the main projectId parameter if not provided
+     */
+    browserbaseSessionCreateParams?: Omit<Browserbase.Sessions.SessionCreateParams, "projectId"> & {
+        projectId?: string;
+    };
+    /**
+     * Enable caching of LLM responses
+     * @default true
+     */
+    enableCaching?: boolean;
+    /**
+     * The ID of a Browserbase session to resume
+     */
+    browserbaseSessionID?: string;
+    /**
+     * The model to use for Stagehand
+     */
+    modelName?: AvailableModel;
+    /**
+     * The LLM client to use for Stagehand
+     */
+    llmClient?: LLMClient;
+    /**
+     * The parameters to use for the LLM client
+     * Useful for parameterizing LLM API Keys
+     */
+    modelClientOptions?: ClientOptions;
+    /**
+     * Customize the Stagehand system prompt
+     */
+    systemPrompt?: string;
+    /**
+     * Offload Stagehand method calls to the Stagehand API.
+     * Must have a valid API key to use
+     */
+    useAPI?: boolean;
+    /**
+     * Wait for captchas to be solved after navigation when using Browserbase environment.
+     *
+     * @default false
+     */
+    waitForCaptchaSolves?: boolean;
+    /**
+     * The parameters to use for launching a local browser
+     */
+    localBrowserLaunchOptions?: LocalBrowserLaunchOptions;
+    /**
+     * Log the inference to a file
+     */
+    logInferenceToFile?: boolean;
+    selfHeal?: boolean;
+    /**
+     * Disable Pino (helpful for Next.js or test environments)
+     */
+    disablePino?: boolean;
+    /**
+     * Experimental Flag: Enables the latest experimental features
+     */
+    experimental?: boolean;
+}
+export interface InitResult {
+    debugUrl: string;
+    sessionUrl: string;
+    sessionId: string;
+}
+export interface ActOptions {
+    action: string;
+    modelName?: AvailableModel;
+    modelClientOptions?: ClientOptions;
+    variables?: Record<string, string>;
+    domSettleTimeoutMs?: number;
+    timeoutMs?: number;
+    iframes?: boolean;
+    frameId?: string;
+}
+export interface ActResult {
+    success: boolean;
+    message: string;
+    action: string;
+}
+export interface ExtractOptions<T extends z.AnyZodObject> {
+    instruction?: string;
+    schema?: T;
+    modelName?: AvailableModel;
+    modelClientOptions?: ClientOptions;
+    domSettleTimeoutMs?: number;
+    /**
+     * @deprecated The `useTextExtract` parameter has no effect in this version of Stagehand and will be removed in later versions.
+     */
+    useTextExtract?: boolean;
+    selector?: string;
+    iframes?: boolean;
+    frameId?: string;
+}
+export type ExtractResult<T extends z.AnyZodObject> = z.infer<T>;
+export interface ObserveOptions {
+    instruction?: string;
+    modelName?: AvailableModel;
+    modelClientOptions?: ClientOptions;
+    domSettleTimeoutMs?: number;
+    returnAction?: boolean;
+    /**
+     * @deprecated The `onlyVisible` parameter has no effect in this version of Stagehand and will be removed in later versions.
+     */
+    onlyVisible?: boolean;
+    drawOverlay?: boolean;
+    iframes?: boolean;
+    frameId?: string;
+}
+export interface ObserveResult {
+    selector: string;
+    description: string;
+    backendNodeId?: number;
+    method?: string;
+    arguments?: string[];
+}
+export interface LocalBrowserLaunchOptions {
+    args?: string[];
+    chromiumSandbox?: boolean;
+    devtools?: boolean;
+    env?: {
+        [key: string]: string | undefined;
+    };
+    executablePath?: string;
+    handleSIGHUP?: boolean;
+    handleSIGINT?: boolean;
+    handleSIGTERM?: boolean;
+    headless?: boolean;
+    ignoreDefaultArgs?: boolean | Array<string>;
+    proxy?: {
+        server: string;
+        bypass?: string;
+        username?: string;
+        password?: string;
+    };
+    tracesDir?: string;
+    userDataDir?: string;
+    preserveUserDataDir?: boolean;
+    acceptDownloads?: boolean;
+    downloadsPath?: string;
+    extraHTTPHeaders?: Record<string, string>;
+    geolocation?: {
+        latitude: number;
+        longitude: number;
+        accuracy?: number;
+    };
+    hasTouch?: boolean;
+    ignoreHTTPSErrors?: boolean;
+    locale?: string;
+    permissions?: Array<string>;
+    recordHar?: {
+        omitContent?: boolean;
+        content?: "omit" | "embed" | "attach";
+        path: string;
+        mode?: "full" | "minimal";
+        urlFilter?: string | RegExp;
+    };
+    recordVideo?: {
+        dir: string;
+        size?: {
+            width: number;
+            height: number;
+        };
+    };
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    deviceScaleFactor?: number;
+    timezoneId?: string;
+    bypassCSP?: boolean;
+    cookies?: Cookie[];
+    cdpUrl?: string;
+}
+export interface StagehandMetrics {
+    actPromptTokens: number;
+    actCompletionTokens: number;
+    actInferenceTimeMs: number;
+    extractPromptTokens: number;
+    extractCompletionTokens: number;
+    extractInferenceTimeMs: number;
+    observePromptTokens: number;
+    observeCompletionTokens: number;
+    observeInferenceTimeMs: number;
+    agentPromptTokens: number;
+    agentCompletionTokens: number;
+    agentInferenceTimeMs: number;
+    totalPromptTokens: number;
+    totalCompletionTokens: number;
+    totalInferenceTimeMs: number;
+}
+/**
+ * Options for executing a task with an agent
+ */
+export interface AgentExecuteParams {
+    /**
+     * The instruction to execute with the agent
+     */
+    instruction: string;
+    /**
+     * Maximum number of steps the agent can take to complete the task
+     * @default 10
+     */
+    maxSteps?: number;
+    /**
+     * Take a screenshot automatically before each agent step
+     * @default true
+     */
+    autoScreenshot?: boolean;
+    /**
+     * Wait time in milliseconds between agent actions
+     * @default 0
+     */
+    waitBetweenActions?: number;
+    /**
+     * Additional context to provide to the agent
+     */
+    context?: string;
+}
+/**
+ * Configuration for agent functionality
+ */
+export interface AgentConfig {
+    /**
+     * The provider to use for agent functionality
+     */
+    provider?: AgentProviderType;
+    /**
+     * The model to use for agent functionality
+     */
+    model?: string;
+    /**
+     * The model to use for tool execution (observe/act calls within agent tools).
+     * If not specified, inherits from the main model configuration.
+     * Format: "provider/model" (e.g., "openai/gpt-4o-mini", "google/gemini-2.0-flash-exp")
+     */
+    executionModel?: string;
+    /**
+     * Custom instructions to provide to the agent
+     */
+    instructions?: string;
+    /**
+     * Additional options to pass to the agent client
+     */
+    options?: Record<string, unknown>;
+    /**
+     * MCP integrations - Array of Client objects
+     */
+    integrations?: (Client | string)[];
+    /**
+     * Tools passed to the agent client
+     */
+    tools?: ToolSet;
+}
+export declare enum StagehandFunctionName {
+    ACT = "ACT",
+    EXTRACT = "EXTRACT",
+    OBSERVE = "OBSERVE",
+    AGENT = "AGENT"
+}
+export interface HistoryEntry {
+    method: "act" | "extract" | "observe" | "navigate";
+    parameters: unknown;
+    result: unknown;
+    timestamp: 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`.
+ */
+export interface ZodPathSegments {
+    /**
+     * The ordered list of keys/indices leading from the schema root
+     * to the targeted field.
+     */
+    segments: Array<string | number>;
+}

package/dist/types/stagehandApiErrors.d.ts

@@ -0,0 +1,18 @@
+export declare class StagehandAPIError extends Error {
+    constructor(message: string);
+}
+export declare class StagehandAPIUnauthorizedError extends StagehandAPIError {
+    constructor(message?: string);
+}
+export declare class StagehandHttpError extends StagehandAPIError {
+    constructor(message: string);
+}
+export declare class StagehandServerError extends StagehandAPIError {
+    constructor(message: string);
+}
+export declare class StagehandResponseBodyError extends StagehandAPIError {
+    constructor();
+}
+export declare class StagehandResponseParseError extends StagehandAPIError {
+    constructor(message: string);
+}

package/dist/types/stagehandErrors.d.ts

@@ -0,0 +1,104 @@
+import { ZodError } from "zod/v3";
+export declare class StagehandError extends Error {
+    constructor(message: string);
+}
+export declare class StagehandDefaultError extends StagehandError {
+    constructor(error?: unknown);
+}
+export declare class StagehandEnvironmentError extends StagehandError {
+    constructor(currentEnvironment: string, requiredEnvironment: string, feature: string);
+}
+export declare class MissingEnvironmentVariableError extends StagehandError {
+    constructor(missingEnvironmentVariable: string, feature: string);
+}
+export declare class UnsupportedModelError extends StagehandError {
+    constructor(supportedModels: string[], feature?: string);
+}
+export declare class UnsupportedModelProviderError extends StagehandError {
+    constructor(supportedProviders: string[], feature?: string);
+}
+export declare class UnsupportedAISDKModelProviderError extends StagehandError {
+    constructor(provider: string, supportedProviders: string[]);
+}
+export declare class InvalidAISDKModelFormatError extends StagehandError {
+    constructor(modelName: string);
+}
+export declare class StagehandNotInitializedError extends StagehandError {
+    constructor(prop: string);
+}
+export declare class BrowserbaseSessionNotFoundError extends StagehandError {
+    constructor();
+}
+export declare class CaptchaTimeoutError extends StagehandError {
+    constructor();
+}
+export declare class MissingLLMConfigurationError extends StagehandError {
+    constructor();
+}
+export declare class HandlerNotInitializedError extends StagehandError {
+    constructor(handlerType: string);
+}
+export declare class StagehandInvalidArgumentError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandElementNotFoundError extends StagehandError {
+    constructor(xpaths: string[]);
+}
+export declare class AgentScreenshotProviderError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandMissingArgumentError extends StagehandError {
+    constructor(message: string);
+}
+export declare class CreateChatCompletionResponseError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandEvalError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandDomProcessError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandClickError extends StagehandError {
+    constructor(message: string, selector: string);
+}
+export declare class LLMResponseError extends StagehandError {
+    constructor(primitive: string, message: string);
+}
+export declare class StagehandIframeError extends StagehandError {
+    constructor(frameUrl: string, message: string);
+}
+export declare class ContentFrameNotFoundError extends StagehandError {
+    constructor(selector: string);
+}
+export declare class XPathResolutionError extends StagehandError {
+    constructor(xpath: string);
+}
+export declare class ExperimentalApiConflictError extends StagehandError {
+    constructor();
+}
+export declare class ExperimentalNotConfiguredError extends StagehandError {
+    constructor(featureName: string);
+}
+export declare class ZodSchemaValidationError extends Error {
+    readonly received: unknown;
+    readonly issues: ReturnType<ZodError["format"]>;
+    constructor(received: unknown, issues: ReturnType<ZodError["format"]>);
+}
+export declare class StagehandInitError extends StagehandError {
+    constructor(message: string);
+}
+export declare class MCPConnectionError extends StagehandError {
+    readonly serverUrl: string;
+    readonly originalError: unknown;
+    constructor(serverUrl: string, originalError: unknown);
+}
+export declare class StagehandShadowRootMissingError extends StagehandError {
+    constructor(detail?: string);
+}
+export declare class StagehandShadowSegmentEmptyError extends StagehandError {
+    constructor();
+}
+export declare class StagehandShadowSegmentNotFoundError extends StagehandError {
+    constructor(segment: string, hint?: string);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbasehq/orca",
-  "version": "3.0.0-preview.0",
+  "version": "3.0.0-preview.1",
   "description": "An AI web browsing framework focused on simplicity and extensibility.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",