@browserbasehq/stagehand 2.5.3-alpha-4994eabfa8016347ec001b40ceadb0c905403470 → 4.0.0-alpha-49bc5b68e4fbeb28a120b301b51c31a36db7d922

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

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

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

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

package/dist/lib/logger.d.ts

@@ -1,54 +0,0 @@
-import pino from "pino";
-import { LogLine } from "../types/log";
-export interface LoggerOptions {
-    pretty?: boolean;
-    level?: pino.Level;
-    destination?: pino.DestinationStream;
-    usePino?: boolean;
-}
-/**
- * Creates a configured Pino logger instance
- */
-export declare function createLogger(options?: LoggerOptions): pino.Logger<never, boolean>;
-/**
- * StagehandLogger class that wraps Pino for our specific needs
- */
-export declare class StagehandLogger {
-    /**
-     * We maintain a single shared Pino instance when `usePino` is enabled.
-     * This prevents spawning a new worker thread for every Stagehand instance
-     * (which happens when `pino-pretty` transport is used), eliminating the
-     * memory/RSS growth observed when many Stagehand objects are created and
-     * disposed within the same process (e.g. a request-per-instance API).
-     */
-    private static sharedPinoLogger;
-    private logger?;
-    private verbose;
-    private externalLogger?;
-    private usePino;
-    private isTest;
-    constructor(options?: LoggerOptions, externalLogger?: (logLine: LogLine) => void);
-    /**
-     * Set the verbosity level
-     */
-    setVerbosity(level: 0 | 1 | 2): void;
-    /**
-     * Log a message using our LogLine format
-     */
-    log(logLine: LogLine): void;
-    /**
-     * Helper to format auxiliary data for structured logging
-     */
-    private formatAuxiliaryData;
-    /**
-     * Convenience methods for different log levels
-     */
-    error(message: string, data?: Record<string, unknown>): void;
-    warn(message: string, data?: Record<string, unknown>): void;
-    info(message: string, data?: Record<string, unknown>): void;
-    debug(message: string, data?: Record<string, unknown>): void;
-    /**
-     * Convert a plain object to our auxiliary format
-     */
-    private convertToAuxiliary;
-}

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

@@ -1,11 +0,0 @@
-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/mcp/utils.d.ts

@@ -1,3 +0,0 @@
-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/prompt.d.ts

@@ -1,14 +0,0 @@
-import { ChatMessage } from "./llm/LLMClient";
-export declare function buildUserInstructionsString(userProvidedInstructions?: string): string;
-export declare function buildExtractSystemPrompt(isUsingPrintExtractedDataTool?: boolean, userProvidedInstructions?: string): ChatMessage;
-export declare function buildExtractUserPrompt(instruction: string, domElements: string, isUsingPrintExtractedDataTool?: boolean): ChatMessage;
-export declare function buildMetadataSystemPrompt(): ChatMessage;
-export declare function buildMetadataPrompt(instruction: string, extractionResponse: object, chunksSeen: number, chunksTotal: number): ChatMessage;
-export declare function buildObserveSystemPrompt(userProvidedInstructions?: string): ChatMessage;
-export declare function buildObserveUserMessage(instruction: string, domElements: string): ChatMessage;
-/**
- * Builds the instruction for the observeAct method to find the most relevant element for an action
- */
-export declare function buildActObservePrompt(action: string, supportedActions: string[], variables?: Record<string, string>): string;
-export declare function buildOperatorSystemPrompt(goal: string): ChatMessage;
-export declare function buildGoogleCUASystemPrompt(): ChatMessage;

package/dist/lib/utils.d.ts

@@ -1,68 +0,0 @@
-import { Schema } from "@google/genai";
-import { z, ZodTypeAny } from "zod/v3";
-import { ObserveResult, Page } from ".";
-import { LogLine } from "../types/log";
-import { ModelProvider } from "../types/model";
-import { ZodPathSegments } from "../types/stagehand";
-export declare function validateZodSchema(schema: z.ZodTypeAny, data: unknown): boolean;
-export declare function drawObserveOverlay(page: Page, results: ObserveResult[]): Promise<void>;
-export declare function clearOverlays(page: Page): Promise<void>;
-/**
- * Detects if the code is running in the Bun runtime environment.
- * @returns {boolean} True if running in Bun, false otherwise.
- */
-export declare function isRunningInBun(): boolean;
-export declare function toGeminiSchema(zodSchema: z.ZodTypeAny): Schema;
-export declare function getZodType(schema: z.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()`.
- *
- * This function is used internally by higher-level utilities (e.g., transforming entire object schemas)
- * and handles nested objects, arrays, unions, intersections, optionals.
- *
- * @param schema - The Zod schema to transform.
- * @param currentPath - An array of string/number keys representing the current schema path (used internally for recursion).
- * @returns A two-element tuple:
- *   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.
- */
-export declare function transformSchema(schema: z.ZodTypeAny, currentPath: Array<string | number>): [z.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
- * with the real URL strings from idToUrlMapping. The `path` may include `*`
- * for array indices (indicating "all items in the array").
- */
-export declare function injectUrls(obj: unknown, path: Array<string | number>, idToUrlMapping: Record<string, string>): void;
-/**
- * Mapping from LLM provider names to their corresponding environment variable names for API keys.
- */
-export declare const providerEnvVarMap: Partial<Record<ModelProvider | string, string>>;
-/**
- * Loads an API key for a provider, checking environment variables.
- * @param provider The name of the provider (e.g., 'openai', 'anthropic')
- * @param logger Optional logger for info/error messages
- * @returns The API key if found, undefined otherwise
- */
-export declare function loadApiKeyFromEnv(provider: string | undefined, logger: (logLine: LogLine) => void): string | undefined;
-export declare function trimTrailingTextNode(path: string | undefined): string | undefined;
-export interface JsonSchemaProperty {
-    type: string;
-    enum?: unknown[];
-    items?: JsonSchemaProperty;
-    properties?: Record<string, JsonSchemaProperty>;
-    required?: string[];
-    minimum?: number;
-    maximum?: number;
-    description?: string;
-}
-export interface JsonSchema extends JsonSchemaProperty {
-    type: string;
-}
-/**
- * Converts a JSON Schema object to a Zod schema
- * @param schema The JSON Schema object to convert
- * @returns A Zod schema equivalent to the input JSON Schema
- */
-export declare function jsonSchemaToZod(schema: JsonSchema): ZodTypeAny;

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: "2.5.3-alpha-4994eabfa8016347ec001b40ceadb0c905403470";

package/dist/scripts/gen-version.d.ts

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

package/dist/scripts/run-evals.d.ts

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

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,144 +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;
-    timestamp?: number;
-    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,95 +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",
-    PROXY_ERROR = "proxy_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;
-};