@browserbasehq/orca 3.0.9-alpha-4 → 3.1.0-patch.1

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

@@ -0,0 +1,139 @@
+import fs from "node:fs";
+import pino from "pino";
+import type { LanguageModelMiddleware } from "ai";
+import type { V3Options } from "./types/public/index.js";
+interface FlowLoggerMetrics {
+    taskStartTime?: number;
+    stepStartTime?: number;
+    actionStartTime?: number;
+    llmRequests: number;
+    llmInputTokens: number;
+    llmOutputTokens: number;
+    cdpEvents: number;
+}
+export interface FlowLoggerContext {
+    logger: pino.Logger;
+    metrics: FlowLoggerMetrics;
+    sessionId: string;
+    sessionDir: string;
+    configDir: string;
+    initPromise: Promise<void>;
+    initialized: boolean;
+    taskId: string | null;
+    stepId: string | null;
+    stepLabel: string | null;
+    actionId: string | null;
+    actionLabel: string | null;
+    fileStreams: {
+        agent: fs.WriteStream | null;
+        stagehand: fs.WriteStream | null;
+        understudy: fs.WriteStream | null;
+        cdp: fs.WriteStream | null;
+        llm: fs.WriteStream | null;
+        jsonl: fs.WriteStream | null;
+    };
+}
+/**
+ * Get the config directory. Returns empty string if logging is disabled.
+ */
+export declare function getConfigDir(): string;
+/**
+ * Format a prompt preview from LLM messages for logging.
+ * Returns format like: "some text... +{5.8kb image} +{schema} +{12 tools}"
+ */
+export declare function formatLlmPromptPreview(messages: Array<{
+    role: string;
+    content: unknown;
+}>, options?: {
+    toolCount?: number;
+    hasSchema?: boolean;
+}): string | undefined;
+/**
+ * Extract a text preview from CUA-style messages.
+ * Accepts various message formats (Anthropic, OpenAI, Google).
+ */
+export declare function formatCuaPromptPreview(messages: unknown[], maxLen?: number): string | undefined;
+/** Format CUA response output for logging */
+export declare function formatCuaResponsePreview(output: unknown, maxLen?: number): string;
+export declare class SessionFileLogger {
+    /**
+     * Initialize a new logging context. Call this at the start of a session.
+     * If BROWSERBASE_CONFIG_DIR is not set, logging is disabled.
+     */
+    static init(sessionId: string, v3Options?: V3Options): void;
+    private static initAsync;
+    static close(): Promise<void>;
+    static get sessionId(): string | null;
+    static get sessionDir(): string | null;
+    /**
+     * Get the current logger context object.
+     */
+    static getContext(): FlowLoggerContext | null;
+    /**
+     * Start a new task and log it.
+     */
+    static logAgentTaskStarted({ invocation, args, }: {
+        invocation: string;
+        args?: unknown | unknown[];
+    }): void;
+    /**
+     * Log task completion with metrics summary.
+     */
+    static logAgentTaskCompleted(options?: {
+        cacheHit?: boolean;
+    }): void;
+    static logStagehandStepEvent({ invocation, args, label, }: {
+        invocation: string;
+        args?: unknown | unknown[];
+        label: string;
+    }): string;
+    static logStagehandStepCompleted(): void;
+    static logUnderstudyActionEvent({ actionType, target, args, }: {
+        actionType: string;
+        target?: string;
+        args?: unknown | unknown[];
+    }): string;
+    static logUnderstudyActionCompleted(): void;
+    private static logCdpEvent;
+    static logCdpCallEvent(data: {
+        method: string;
+        params?: object;
+        targetId?: string | null;
+    }, ctx?: FlowLoggerContext | null): void;
+    static logCdpMessageEvent(data: {
+        method: string;
+        params?: unknown;
+        targetId?: string | null;
+    }, ctx?: FlowLoggerContext | null): void;
+    static logLlmRequest({ requestId, model, prompt, }: {
+        requestId: string;
+        model: string;
+        operation: string;
+        prompt?: string;
+    }, explicitCtx?: FlowLoggerContext | null): void;
+    static logLlmResponse({ requestId, model, output, inputTokens, outputTokens, }: {
+        requestId: string;
+        model: string;
+        operation: string;
+        output?: string;
+        inputTokens?: number;
+        outputTokens?: number;
+    }, explicitCtx?: FlowLoggerContext | null): void;
+    /**
+     * Create middleware for wrapping language models with LLM call logging.
+     * Returns a no-op middleware when logging is disabled.
+     */
+    static createLlmLoggingMiddleware(modelId: string): Pick<LanguageModelMiddleware, "wrapGenerate">;
+}
+/**
+ * Method decorator for logging understudy actions with automatic start/complete.
+ * Logs all arguments automatically. No-op when CONFIG_DIR is empty.
+ */
+export declare function logAction(actionType: string): <T extends (...args: never[]) => Promise<unknown>>(originalMethod: T) => T;
+/**
+ * Method decorator for logging Stagehand step events (act, extract, observe).
+ * Only adds logging - does NOT wrap with withInstanceLogContext (caller handles that).
+ * No-op when CONFIG_DIR is empty.
+ */
+export declare function logStagehandStep(invocation: string, label: string): <T extends (...args: never[]) => Promise<unknown>>(originalMethod: T) => T;
+export {};

package/dist/cjs/lib/v3/handlers/actHandler.d.ts

@@ -0,0 +1,21 @@
+import { ActHandlerParams } from "../types/private/handlers.js";
+import { ActResult, Action, V3FunctionName } from "../types/public/methods.js";
+import { LLMClient } from "../llm/LLMClient.js";
+import { AvailableModel, ClientOptions, ModelConfiguration } from "../types/public/model.js";
+import type { Page } from "../understudy/page.js";
+export declare class ActHandler {
+    private readonly llmClient;
+    private readonly defaultModelName;
+    private readonly defaultClientOptions;
+    private readonly resolveLlmClient;
+    private readonly systemPrompt;
+    private readonly logInferenceToFile;
+    private readonly selfHeal;
+    private readonly onMetrics?;
+    private readonly defaultDomSettleTimeoutMs?;
+    constructor(llmClient: LLMClient, defaultModelName: AvailableModel, defaultClientOptions: ClientOptions, resolveLlmClient: (model?: ModelConfiguration) => LLMClient, systemPrompt?: string, logInferenceToFile?: boolean, selfHeal?: boolean, onMetrics?: (functionName: V3FunctionName, promptTokens: number, completionTokens: number, reasoningTokens: number, cachedInputTokens: number, inferenceTimeMs: number) => void, defaultDomSettleTimeoutMs?: number);
+    private recordActMetrics;
+    private getActionFromLLM;
+    act(params: ActHandlerParams): Promise<ActResult>;
+    takeDeterministicAction(action: Action, page: Page, domSettleTimeoutMs?: number, llmClientOverride?: LLMClient, ensureTimeRemaining?: () => void, variables?: Record<string, string>): Promise<ActResult>;
+}

package/dist/cjs/lib/v3/handlers/extractHandler.d.ts

@@ -0,0 +1,31 @@
+import { V3FunctionName } from "../types/public/methods.js";
+import { LLMClient } from "../llm/LLMClient.js";
+import { ExtractHandlerParams } from "../types/private/handlers.js";
+import { ZodPathSegments } from "../types/private/internal.js";
+import { AvailableModel, ClientOptions, ModelConfiguration } from "../types/public/model.js";
+import type { InferStagehandSchema, StagehandZodSchema } from "../zodCompat.js";
+/**
+ * Scans the provided Zod schema for any `z.string().url()` fields and
+ * replaces them with `z.number()`.
+ *
+ * @param schema - The Zod object schema to transform.
+ * @returns A tuple containing:
+ *   1. The transformed schema (or the original schema if no changes were needed).
+ *   2. An array of {@link ZodPathSegments} objects representing all the replaced URL fields,
+ *      with each path segment showing where in the schema the replacement occurred.
+ */
+export declare function transformUrlStringsToNumericIds<T extends StagehandZodSchema>(schema: T): [StagehandZodSchema, ZodPathSegments[]];
+export declare class ExtractHandler {
+    private readonly llmClient;
+    private readonly defaultModelName;
+    private readonly defaultClientOptions;
+    private readonly resolveLlmClient;
+    private readonly systemPrompt;
+    private readonly logInferenceToFile;
+    private readonly experimental;
+    private readonly onMetrics?;
+    constructor(llmClient: LLMClient, defaultModelName: AvailableModel, defaultClientOptions: ClientOptions, resolveLlmClient: (model?: ModelConfiguration) => LLMClient, systemPrompt?: string, logInferenceToFile?: boolean, experimental?: boolean, onMetrics?: (functionName: V3FunctionName, promptTokens: number, completionTokens: number, reasoningTokens: number, cachedInputTokens: number, inferenceTimeMs: number) => void);
+    extract<T extends StagehandZodSchema>(params: ExtractHandlerParams<T>): Promise<InferStagehandSchema<T> | {
+        pageText: string;
+    }>;
+}

package/dist/cjs/lib/v3/handlers/handlerUtils/actHandlerUtils.d.ts

@@ -0,0 +1,24 @@
+import { Frame } from "../../understudy/frame.js";
+import { Locator } from "../../understudy/locator.js";
+import type { Page } from "../../understudy/page.js";
+export declare class UnderstudyCommandException extends Error {
+    constructor(message: string);
+}
+export interface UnderstudyMethodHandlerContext {
+    method: string;
+    locator: Locator;
+    xpath: string;
+    args: ReadonlyArray<string>;
+    frame: Frame;
+    page: Page;
+    initialUrl: string;
+    domSettleTimeoutMs?: number;
+}
+export declare function performUnderstudyMethod(page: Page, frame: Frame, method: string, rawXPath: string, args: ReadonlyArray<unknown>, domSettleTimeoutMs?: number): Promise<void>;
+export declare function selectOption(ctx: UnderstudyMethodHandlerContext): Promise<void>;
+export declare function hover(ctx: UnderstudyMethodHandlerContext): Promise<void>;
+/**
+ * More robust DOM settle using Network + Page events to detect network quiet.
+ * Closely modeled after the provided snippet, adapted to our Frame/session + logger.
+ */
+export declare function waitForDomNetworkQuiet(frame: Frame, timeoutMs?: number): Promise<void>;

package/dist/cjs/lib/v3/handlers/handlerUtils/timeoutGuard.d.ts

@@ -0,0 +1,2 @@
+export type TimeoutGuard = () => void;
+export declare function createTimeoutGuard(timeoutMs?: number, errorFactory?: (timeoutMs: number) => Error): TimeoutGuard;

package/dist/cjs/lib/v3/handlers/observeHandler.d.ts

@@ -0,0 +1,17 @@
+import { V3FunctionName } from "../types/public/methods.js";
+import { LLMClient } from "../llm/LLMClient.js";
+import { ObserveHandlerParams } from "../types/private/handlers.js";
+import { Action } from "../types/public/methods.js";
+import { AvailableModel, ClientOptions, ModelConfiguration } from "../types/public/model.js";
+export declare class ObserveHandler {
+    private readonly llmClient;
+    private readonly defaultModelName;
+    private readonly defaultClientOptions;
+    private readonly resolveLlmClient;
+    private readonly systemPrompt;
+    private readonly logInferenceToFile;
+    private readonly experimental;
+    private readonly onMetrics?;
+    constructor(llmClient: LLMClient, defaultModelName: AvailableModel, defaultClientOptions: ClientOptions, resolveLlmClient: (model?: ModelConfiguration) => LLMClient, systemPrompt?: string, logInferenceToFile?: boolean, experimental?: boolean, onMetrics?: (functionName: V3FunctionName, promptTokens: number, completionTokens: number, reasoningTokens: number, cachedInputTokens: number, inferenceTimeMs: number) => void);
+    observe(params: ObserveHandlerParams): Promise<Action[]>;
+}

package/dist/cjs/lib/v3/handlers/v3AgentHandler.d.ts

@@ -0,0 +1,32 @@
+import { LogLine } from "../types/public/logs.js";
+import { V3 } from "../v3.js";
+import { ToolSet } from "ai";
+import { LLMClient } from "../llm/LLMClient.js";
+import { AgentExecuteOptions, AgentStreamExecuteOptions, AgentResult, AgentStreamResult, AgentToolMode } from "../types/public/agent.js";
+export declare class V3AgentHandler {
+    private v3;
+    private logger;
+    private llmClient;
+    private executionModel?;
+    private systemInstructions?;
+    private mcpTools?;
+    private mode;
+    constructor(v3: V3, logger: (message: LogLine) => void, llmClient: LLMClient, executionModel?: string, systemInstructions?: string, mcpTools?: ToolSet, mode?: AgentToolMode);
+    private prepareAgent;
+    private createPrepareStep;
+    private createStepHandler;
+    execute(instructionOrOptions: string | AgentExecuteOptions): Promise<AgentResult>;
+    stream(instructionOrOptions: string | AgentStreamExecuteOptions): Promise<AgentStreamResult>;
+    private consolidateMetricsAndResult;
+    private createTools;
+    private handleStop;
+    /**
+     * Ensures the done tool is called at the end of agent execution.
+     * Returns the messages and any extracted output from the done call.
+     */
+    private ensureDone;
+    /**
+     * Capture a screenshot and emit it via the event bus
+     */
+    private captureAndEmitScreenshot;
+}

package/dist/cjs/lib/v3/handlers/v3CuaAgentHandler.d.ts

@@ -0,0 +1,33 @@
+import { V3 } from "../v3.js";
+import { ToolSet } from "ai";
+import { AgentExecuteOptions, AgentHandlerOptions, AgentResult, SafetyConfirmationHandler } from "../types/public/agent.js";
+import { LogLine } from "../types/public/logs.js";
+export declare class V3CuaAgentHandler {
+    private v3;
+    private agent;
+    private provider;
+    private logger;
+    private agentClient;
+    private options;
+    private highlightCursor;
+    constructor(v3: V3, logger: (message: LogLine) => void, options: AgentHandlerOptions, tools?: ToolSet);
+    /**
+     * Ensures the V3 context is still available (not closed).
+     * Throws StagehandClosedError if stagehand.close() was called.
+     */
+    private ensureNotClosed;
+    private setupAgentClient;
+    setSafetyConfirmationHandler(handler?: SafetyConfirmationHandler): void;
+    execute(optionsOrInstruction: AgentExecuteOptions | string): Promise<AgentResult>;
+    private executeAction;
+    private computePointerTarget;
+    private describePointerAction;
+    private describeTypeAction;
+    private describeDragAction;
+    private buildInstructionFallback;
+    private recordCuaActStep;
+    private updateClientViewport;
+    private updateClientUrl;
+    captureAndSendScreenshot(): Promise<unknown>;
+    private injectCursor;
+}

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

@@ -0,0 +1,18 @@
+export { V3 } from "./v3.js";
+export { V3 as Stagehand } from "./v3.js";
+export * from "./types/public/index.js";
+export { AnnotatedScreenshotText, LLMClient } from "./llm/LLMClient.js";
+export { AgentProvider, modelToAgentProviderMap, } from "./agent/AgentProvider.js";
+export type { AgentTools, AgentToolTypesMap, AgentUITools, AgentToolCall, AgentToolResult, } from "./agent/tools/index.js";
+export { validateZodSchema, isRunningInBun, toGeminiSchema, getZodType, transformSchema, injectUrls, providerEnvVarMap, loadApiKeyFromEnv, trimTrailingTextNode, jsonSchemaToZod, } from "../utils.js";
+export { isZod4Schema, isZod3Schema, toJsonSchema } from "./zodCompat.js";
+export { connectToMCPServer } from "./mcp/connection.js";
+export { V3Evaluator } from "../v3Evaluator.js";
+export { tool } from "ai";
+export { getAISDKLanguageModel } from "./llm/LLMProvider.js";
+export { __internalCreateInMemoryAgentCacheHandle } from "./cache/serverAgentCache.js";
+export { maybeRunShutdownSupervisorFromArgv as __internalMaybeRunShutdownSupervisorFromArgv } from "./shutdown/supervisor.js";
+export type { ServerAgentCacheHandle } from "./cache/serverAgentCache.js";
+export type { ChatMessage, ChatMessageContent, ChatMessageImageContent, ChatMessageTextContent, ChatCompletionOptions, LLMResponse, CreateChatCompletionOptions, LLMUsage, LLMParsedResponse, } from "./llm/LLMClient.js";
+export type { StagehandZodSchema, StagehandZodObject, InferStagehandSchema, JsonSchemaDocument, } from "./zodCompat.js";
+export type { JsonSchema, JsonSchemaProperty } from "../utils.js";

package/dist/cjs/lib/v3/launch/browserbase.d.ts

@@ -0,0 +1,7 @@
+import Browserbase from "@browserbasehq/sdk";
+import type { BrowserbaseSessionCreateParams } from "../types/public/api.js";
+export declare function createBrowserbaseSession(apiKey: string, projectId: string, params?: BrowserbaseSessionCreateParams, resumeSessionId?: string): Promise<{
+    ws: string;
+    sessionId: string;
+    bb: Browserbase;
+}>;

package/dist/cjs/lib/v3/launch/local.d.ts

@@ -0,0 +1,15 @@
+import { LaunchedChrome } from "chrome-launcher";
+interface LaunchLocalOptions {
+    chromePath?: string;
+    chromeFlags?: string[];
+    headless?: boolean;
+    userDataDir?: string;
+    port?: number;
+    connectTimeoutMs?: number;
+    handleSIGINT?: boolean;
+}
+export declare function launchLocalChrome(opts: LaunchLocalOptions): Promise<{
+    ws: string;
+    chrome: LaunchedChrome;
+}>;
+export {};

package/dist/cjs/lib/v3/llm/AnthropicClient.d.ts

@@ -0,0 +1,16 @@
+import { ClientOptions } from "@anthropic-ai/sdk";
+import { LogLine } from "../types/public/logs.js";
+import { AvailableModel } from "../types/public/model.js";
+import { CreateChatCompletionOptions, LLMClient, LLMResponse } from "./LLMClient.js";
+export declare class AnthropicClient extends LLMClient {
+    type: "anthropic";
+    private client;
+    clientOptions: ClientOptions;
+    constructor({ modelName, clientOptions, userProvidedInstructions, }: {
+        logger: (message: LogLine) => void;
+        modelName: AvailableModel;
+        clientOptions?: ClientOptions;
+        userProvidedInstructions?: string;
+    });
+    createChatCompletion<T = LLMResponse>({ options, retries, logger, }: CreateChatCompletionOptions): Promise<T>;
+}

package/dist/cjs/lib/v3/llm/CerebrasClient.d.ts

@@ -0,0 +1,17 @@
+import type { ClientOptions } from "openai";
+import { LogLine } from "../types/public/logs.js";
+import { AvailableModel } from "../types/public/model.js";
+import { CreateChatCompletionOptions, LLMClient, LLMResponse } from "./LLMClient.js";
+export declare class CerebrasClient extends LLMClient {
+    type: "cerebras";
+    private client;
+    clientOptions: ClientOptions;
+    hasVision: boolean;
+    constructor({ modelName, clientOptions, userProvidedInstructions, }: {
+        logger: (message: LogLine) => void;
+        modelName: AvailableModel;
+        clientOptions?: ClientOptions;
+        userProvidedInstructions?: string;
+    });
+    createChatCompletion<T = LLMResponse>({ options, retries, logger, }: CreateChatCompletionOptions): Promise<T>;
+}

package/dist/cjs/lib/v3/llm/GoogleClient.d.ts

@@ -0,0 +1,19 @@
+import { LogLine } from "../types/public/logs.js";
+import { AvailableModel, ClientOptions } from "../types/public/model.js";
+import { CreateChatCompletionOptions, LLMClient, LLMResponse } from "./LLMClient.js";
+export declare class GoogleClient extends LLMClient {
+    type: "google";
+    private client;
+    clientOptions: ClientOptions;
+    hasVision: boolean;
+    private logger;
+    constructor({ logger, // Added logger based on other clients
+    modelName, clientOptions, }: {
+        logger: (message: LogLine) => void;
+        modelName: AvailableModel;
+        clientOptions?: ClientOptions;
+    });
+    private formatMessages;
+    private formatTools;
+    createChatCompletion<T = LLMResponse>({ options, logger, retries, }: CreateChatCompletionOptions): Promise<T>;
+}

package/dist/cjs/lib/v3/llm/GroqClient.d.ts

@@ -0,0 +1,17 @@
+import type { ClientOptions } from "openai";
+import { LogLine } from "../types/public/logs.js";
+import { AvailableModel } from "../types/public/model.js";
+import { CreateChatCompletionOptions, LLMClient, LLMResponse } from "./LLMClient.js";
+export declare class GroqClient extends LLMClient {
+    type: "groq";
+    private client;
+    clientOptions: ClientOptions;
+    hasVision: boolean;
+    constructor({ modelName, clientOptions, userProvidedInstructions, }: {
+        logger: (message: LogLine) => void;
+        modelName: AvailableModel;
+        clientOptions?: ClientOptions;
+        userProvidedInstructions?: string;
+    });
+    createChatCompletion<T = LLMResponse>({ options, retries, logger, }: CreateChatCompletionOptions): Promise<T>;
+}

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

@@ -0,0 +1,121 @@
+import { LLMTool } from "../types/public/model.js";
+import { embed, embedMany, experimental_generateImage, experimental_generateSpeech, experimental_transcribe, generateObject, generateText, streamObject, streamText } from "ai";
+import type { LanguageModelV2 } from "@ai-sdk/provider";
+import { LogLine } from "../types/public/logs.js";
+import { AvailableModel, ClientOptions } from "../types/public/model.js";
+import type { StagehandZodSchema } from "../zodCompat.js";
+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: StagehandZodSchema;
+    };
+    tools?: LLMTool[];
+    tool_choice?: "auto" | "none" | "required";
+    maxOutputTokens?: 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;
+}
+/** Simple usage shape if your LLM returns usage tokens. */
+export interface LLMUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    reasoning_tokens?: number;
+    cached_input_tokens?: number;
+}
+/**
+ * For calls that use a schema: the LLMClient may return { data: T; usage?: LLMUsage }
+ */
+export interface LLMParsedResponse<T> {
+    data: T;
+    usage?: LLMUsage;
+}
+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>(options: CreateChatCompletionOptions & {
+        options: {
+            response_model: {
+                name: string;
+                schema: StagehandZodSchema;
+            };
+        };
+    }): Promise<LLMParsedResponse<T>>;
+    abstract createChatCompletion<T = LLMResponse>(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?(): LanguageModelV2;
+}

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

@@ -0,0 +1,13 @@
+import { LogLine } from "../types/public/logs.js";
+import { AvailableModel, ClientOptions, ModelProvider } from "../types/public/model.js";
+import { LLMClient } from "./LLMClient.js";
+export declare function getAISDKLanguageModel(subProvider: string, subModelName: string, clientOptions?: ClientOptions): import("@ai-sdk/provider").LanguageModelV2;
+export declare class LLMProvider {
+    private logger;
+    constructor(logger: (message: LogLine) => void);
+    getClient(modelName: AvailableModel, clientOptions?: ClientOptions, options?: {
+        experimental?: boolean;
+        disableAPI?: boolean;
+    }): LLMClient;
+    static getModelProvider(modelName: AvailableModel): ModelProvider;
+}

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

@@ -0,0 +1,15 @@
+import { ClientOptions } from "openai";
+import { LogLine } from "../types/public/logs.js";
+import { AvailableModel } from "../types/public/model.js";
+import { CreateChatCompletionOptions, LLMClient, LLMResponse } from "./LLMClient.js";
+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/cjs/lib/v3/llm/aisdk.d.ts

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

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

@@ -0,0 +1,9 @@
+import type { LogLine } from "./types/public/logs.js";
+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;
+/**
+ * Routes logs to the appropriate instance logger based on AsyncLocalStorage context.
+ * Falls back to console output if no instance context is available.
+ */
+export declare function v3Logger(line: LogLine): void;

package/dist/cjs/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/cjs/lib/v3/mcp/utils.d.ts

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

package/dist/cjs/lib/v3/shutdown/cleanupLocal.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared cleanup logic for locally launched Chrome.
+ *
+ * Used by both `V3.close()` (normal shutdown) and the supervisor process
+ * (crash cleanup). The caller provides a `killChrome` callback since the
+ * kill mechanism differs: chrome-launcher's `chrome.kill()` in-process
+ * vs raw `process.kill(pid)` from the supervisor.
+ */
+export declare function cleanupLocalBrowser(opts: {
+    killChrome?: () => Promise<void> | void;
+    userDataDir?: string;
+    createdTempProfile?: boolean;
+    preserveUserDataDir?: boolean;
+}): Promise<void>;

package/dist/cjs/lib/v3/shutdown/supervisor.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shutdown supervisor process.
+ *
+ * This process watches a stdin lifeline. When the parent dies, stdin closes
+ * and the supervisor performs best-effort cleanup:
+ * - LOCAL: kill Chrome + remove temp profile
+ * - STAGEHAND_API: request session release
+ */
+import type { ShutdownSupervisorConfig } from "../types/private/shutdown.js";
+export declare const runShutdownSupervisor: (initialConfig: ShutdownSupervisorConfig) => void;
+export declare const maybeRunShutdownSupervisorFromArgv: (argv?: readonly string[]) => boolean;