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

package/dist/cjs/lib/v3/agent/tools/fillform.d.ts

@@ -0,0 +1,12 @@
+import type { V3 } from "../../v3.js";
+import type { Action } from "../../types/public/methods.js";
+export declare const fillFormTool: (v3: V3, executionModel?: string) => import("ai").Tool<{
+    fields: {
+        action: string;
+        value: string;
+    }[];
+}, {
+    success: boolean;
+    actions: unknown[];
+    playwrightArguments: Action[];
+}>;

package/dist/cjs/lib/v3/agent/tools/goto.d.ts

@@ -0,0 +1,12 @@
+import type { V3 } from "../../v3.js";
+export declare const gotoTool: (v3: V3) => import("ai").Tool<{
+    url: string;
+}, {
+    success: boolean;
+    url: string;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: any;
+    url?: undefined;
+}>;

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

@@ -0,0 +1,92 @@
+import { gotoTool } from "./goto.js";
+import { actTool } from "./act.js";
+import { screenshotTool } from "./screenshot.js";
+import { waitTool } from "./wait.js";
+import { navBackTool } from "./navback.js";
+import { ariaTreeTool } from "./ariaTree.js";
+import { fillFormTool } from "./fillform.js";
+import { scrollTool, scrollVisionTool } from "./scroll.js";
+import { extractTool } from "./extract.js";
+import { clickTool } from "./click.js";
+import { typeTool } from "./type.js";
+import { dragAndDropTool } from "./dragAndDrop.js";
+import { clickAndHoldTool } from "./clickAndHold.js";
+import { keysTool } from "./keys.js";
+import { fillFormVisionTool } from "./fillFormVision.js";
+import { thinkTool } from "./think.js";
+import { searchTool } from "./search.js";
+import type { ToolSet, InferUITools } from "ai";
+import type { V3 } from "../../v3.js";
+import type { LogLine } from "../../types/public/logs.js";
+import type { AgentToolMode } from "../../types/public/agent.js";
+export interface V3AgentToolOptions {
+    executionModel?: string;
+    logger?: (message: LogLine) => void;
+    /**
+     * Tool mode determines which set of tools are available.
+     * - 'dom' (default): Uses DOM-based tools (act, fillForm) - removes coordinate-based tools
+     * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, etc.) - removes fillForm
+     */
+    mode?: AgentToolMode;
+    /**
+     * The model provider. Used for model-specific coordinate handling
+     */
+    provider?: string;
+    /**
+     * Tools to exclude from the available toolset.
+     * These tools will be filtered out after mode-based filtering.
+     */
+    excludeTools?: string[];
+}
+export declare function createAgentTools(v3: V3, options?: V3AgentToolOptions): ToolSet;
+export type AgentTools = ReturnType<typeof createAgentTools>;
+/**
+ * Type map of all agent tools for strong typing of tool calls and results.
+ * Note: `search` is optional as it's only available when BRAVE_API_KEY is configured.
+ */
+export type AgentToolTypesMap = {
+    act: ReturnType<typeof actTool>;
+    ariaTree: ReturnType<typeof ariaTreeTool>;
+    click: ReturnType<typeof clickTool>;
+    clickAndHold: ReturnType<typeof clickAndHoldTool>;
+    dragAndDrop: ReturnType<typeof dragAndDropTool>;
+    extract: ReturnType<typeof extractTool>;
+    fillForm: ReturnType<typeof fillFormTool>;
+    fillFormVision: ReturnType<typeof fillFormVisionTool>;
+    goto: ReturnType<typeof gotoTool>;
+    keys: ReturnType<typeof keysTool>;
+    navback: ReturnType<typeof navBackTool>;
+    screenshot: ReturnType<typeof screenshotTool>;
+    scroll: ReturnType<typeof scrollTool> | ReturnType<typeof scrollVisionTool>;
+    search?: ReturnType<typeof searchTool>;
+    think: ReturnType<typeof thinkTool>;
+    type: ReturnType<typeof typeTool>;
+    wait: ReturnType<typeof waitTool>;
+};
+/**
+ * Inferred UI tools type for type-safe tool inputs and outputs.
+ * Use with UIMessage for full type safety in UI contexts.
+ */
+export type AgentUITools = InferUITools<AgentToolTypesMap>;
+/**
+ * Union type for all possible agent tool calls.
+ * Provides type-safe access to tool call arguments.
+ */
+export type AgentToolCall = {
+    [K in keyof AgentToolTypesMap]: {
+        toolName: K;
+        toolCallId: string;
+        args: AgentUITools[K]["input"];
+    };
+}[keyof AgentToolTypesMap];
+/**
+ * Union type for all possible agent tool results.
+ * Provides type-safe access to tool result values.
+ */
+export type AgentToolResult = {
+    [K in keyof AgentToolTypesMap]: {
+        toolName: K;
+        toolCallId: string;
+        result: AgentUITools[K]["output"];
+    };
+}[keyof AgentToolTypesMap];

package/dist/cjs/lib/v3/agent/tools/keys.d.ts

@@ -0,0 +1,24 @@
+import type { V3 } from "../../v3.js";
+export declare const keysTool: (v3: V3) => import("ai").Tool<{
+    method: "type" | "press";
+    value: string;
+    repeat?: number;
+}, {
+    success: boolean;
+    method: "type";
+    value: string;
+    times: number;
+    error?: undefined;
+} | {
+    success: boolean;
+    method: "press";
+    value: string;
+    times: number;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string;
+    method?: undefined;
+    value?: undefined;
+    times?: undefined;
+}>;

package/dist/cjs/lib/v3/agent/tools/navback.d.ts

@@ -0,0 +1,6 @@
+import type { V3 } from "../../v3.js";
+export declare const navBackTool: (v3: V3) => import("ai").Tool<{
+    reasoningText: string;
+}, {
+    success: boolean;
+}>;

package/dist/cjs/lib/v3/agent/tools/screenshot.d.ts

@@ -0,0 +1,6 @@
+import type { V3 } from "../../v3.js";
+export declare const screenshotTool: (v3: V3) => import("ai").Tool<Record<string, never>, {
+    base64: string;
+    timestamp: number;
+    pageUrl: string;
+}>;

package/dist/cjs/lib/v3/agent/tools/scroll.d.ts

@@ -0,0 +1,19 @@
+import type { V3 } from "../../v3.js";
+import type { ScrollToolResult, ScrollVisionToolResult } from "../../types/public/agent.js";
+/**
+ * Simple scroll tool for DOM mode (non-grounding models).
+ * No coordinates - scrolls from viewport center.
+ */
+export declare const scrollTool: (v3: V3) => import("ai").Tool<{
+    direction: "up" | "down";
+    percentage?: number;
+}, ScrollToolResult>;
+/**
+ * Scroll tool for hybrid mode (grounding models).
+ * Supports optional coordinates for scrolling within nested scrollable elements.
+ */
+export declare const scrollVisionTool: (v3: V3, provider?: string) => import("ai").Tool<{
+    direction: "up" | "down";
+    coordinates?: number[];
+    percentage?: number;
+}, ScrollVisionToolResult>;

package/dist/cjs/lib/v3/agent/tools/search.d.ts

@@ -0,0 +1,15 @@
+import type { V3 } from "../../v3.js";
+export interface BraveSearchResult {
+    title: string;
+    url: string;
+    description?: string;
+}
+export declare const searchTool: (v3: V3) => import("ai").Tool<{
+    query: string;
+}, {
+    timestamp: number;
+    data?: {
+        results: BraveSearchResult[];
+    };
+    error?: string;
+}>;

package/dist/cjs/lib/v3/agent/tools/think.d.ts

@@ -0,0 +1,6 @@
+export declare const thinkTool: () => import("ai").Tool<{
+    reasoning: string;
+}, {
+    acknowledged: boolean;
+    message: string;
+}>;

package/dist/cjs/lib/v3/agent/tools/type.d.ts

@@ -0,0 +1,7 @@
+import type { V3 } from "../../v3.js";
+import type { TypeToolResult } from "../../types/public/agent.js";
+export declare const typeTool: (v3: V3, provider?: string) => import("ai").Tool<{
+    describe: string;
+    text: string;
+    coordinates: number[];
+}, TypeToolResult>;

package/dist/cjs/lib/v3/agent/tools/wait.d.ts

@@ -0,0 +1,5 @@
+import type { V3 } from "../../v3.js";
+import type { AgentToolMode, WaitToolResult } from "../../types/public/agent.js";
+export declare const waitTool: (v3: V3, mode?: AgentToolMode) => import("ai").Tool<{
+    timeMs: number;
+}, WaitToolResult>;

package/dist/cjs/lib/v3/agent/utils/actionMapping.d.ts

@@ -0,0 +1,3 @@
+import { AgentAction } from "../../types/public/agent.js";
+import { ActionMappingOptions } from "../../types/private/agent.js";
+export declare function mapToolResultToActions({ toolCallName, toolResult, args, reasoning, }: ActionMappingOptions): AgentAction[];

package/dist/cjs/lib/v3/agent/utils/coordinateNormalization.d.ts

@@ -0,0 +1,13 @@
+import type { V3 } from "../../v3.js";
+export declare function isGoogleProvider(provider?: string): boolean;
+export declare function normalizeGoogleCoordinates(x: number, y: number, viewport: {
+    width: number;
+    height: number;
+}): {
+    x: number;
+    y: number;
+};
+export declare function processCoordinates(x: number, y: number, provider?: string, v3?: V3): {
+    x: number;
+    y: number;
+};

package/dist/cjs/lib/v3/agent/utils/cuaKeyMapping.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Universal key mapping utility for converting various key representations
+ * to Playwright-compatible key names. Used by all CUA clients and handlers.
+ */
+/**
+ * Maps a key name from various formats to Playwright-compatible format
+ * @param key The key name in any supported format
+ * @returns The Playwright-compatible key name
+ */
+export declare function mapKeyToPlaywright(key: string): string;

package/dist/cjs/lib/v3/agent/utils/googleCustomToolHandler.d.ts

@@ -0,0 +1,25 @@
+import { Part, FunctionCall, FunctionDeclaration } from "@google/genai";
+import { ToolSet } from "ai";
+import { LogLine } from "../../types/public/logs.js";
+/**
+ * Result of executing a custom tool for Google CUA
+ */
+export interface CustomToolExecutionResult {
+    functionResponse: Part;
+    success: boolean;
+}
+/**
+ * Execute a custom tool and format the response for Google's API
+ * This handles tool execution, result formatting, and error handling
+ * specific to Google's function response format
+ */
+export declare function executeGoogleCustomTool(toolName: string, toolArgs: Record<string, unknown>, tools: ToolSet, functionCall: FunctionCall, logger: (message: LogLine) => void): Promise<CustomToolExecutionResult>;
+/**
+ * Check if a function call is a custom tool
+ */
+export declare function isCustomTool(functionCall: FunctionCall, tools?: ToolSet): boolean;
+/**
+ * Convert ToolSet to Google's FunctionDeclaration array
+ * Handles the conversion of Zod schemas to Google's parameter format
+ */
+export declare function convertToolSetToFunctionDeclarations(tools: ToolSet): FunctionDeclaration[];

package/dist/cjs/lib/v3/agent/utils/handleDoneToolCall.d.ts

@@ -0,0 +1,22 @@
+import { ModelMessage, LanguageModel } from "ai";
+import { LogLine } from "../../types/public/logs.js";
+import { StagehandZodObject } from "../../zodCompat.js";
+interface DoneResult {
+    reasoning: string;
+    taskComplete: boolean;
+    messages: ModelMessage[];
+    output?: Record<string, unknown>;
+}
+/**
+ * Force a done tool call at the end of an agent run.
+ * This ensures we always get a structured final response,
+ * even if the main loop ended without calling done.
+ */
+export declare function handleDoneToolCall(options: {
+    model: LanguageModel;
+    inputMessages: ModelMessage[];
+    instruction: string;
+    outputSchema?: StagehandZodObject;
+    logger: (message: LogLine) => void;
+}): Promise<DoneResult>;
+export {};

package/dist/cjs/lib/v3/agent/utils/imageCompression.d.ts

@@ -0,0 +1,53 @@
+import { AnthropicMessage, AnthropicToolResult, ResponseInputItem as OpenAIResponseInputItem } from "../../types/public/agent.js";
+import type { Content as GoogleContent } from "@google/genai";
+export type ResponseInputItem = AnthropicMessage | AnthropicToolResult;
+export type AnthropicResponseInputItem = AnthropicMessage | AnthropicToolResult;
+export type SupportedInputItem = AnthropicResponseInputItem | OpenAIResponseInputItem | GoogleContent;
+/**
+ * Finds all items in the conversation history that contain images
+ * @param items - Array of conversation items to check
+ * @returns Array of indices where images were found
+ */
+export declare function findItemsWithImages(items: ResponseInputItem[]): number[];
+/**
+ * Compresses conversation history by removing images from older items
+ * while keeping the most recent images intact
+ * @param items - Array of conversation items to process
+ * @param keepMostRecentCount - Number of most recent image-containing items to preserve (default: 2)
+ * @returns Object with processed items
+ */
+export declare function compressConversationImages(items: ResponseInputItem[], keepMostRecentCount?: number): {
+    items: ResponseInputItem[];
+};
+/**
+ * Finds all items in the conversation history that contain images (Google format)
+ * @param items - Array of conversation items to check
+ * @returns Array of indices where images were found
+ */
+export declare function findGoogleItemsWithImages(items: GoogleContent[]): number[];
+/**
+ * Finds all items in the conversation history that contain images (OpenAI format)
+ * @param items - Array of conversation items to check
+ * @returns Array of indices where images were found
+ */
+export declare function findOpenAIItemsWithImages(items: OpenAIResponseInputItem[]): number[];
+/**
+ * Compresses OpenAI conversation history by removing images from older items
+ * while keeping the most recent images intact
+ * @param items - Array of conversation items to process
+ * @param keepMostRecentCount - Number of most recent image-containing items to preserve (default: 2)
+ * @returns Object with processed items
+ */
+export declare function compressOpenAIConversationImages(items: OpenAIResponseInputItem[], keepMostRecentCount?: number): {
+    items: OpenAIResponseInputItem[];
+};
+/**
+ * Compresses Google conversation history by removing images from older items
+ * while keeping the most recent images intact
+ * @param items - Array of conversation items to process
+ * @param keepMostRecentCount - Number of most recent image-containing items to preserve (default: 2)
+ * @returns Object with processed items
+ */
+export declare function compressGoogleConversationImages(items: GoogleContent[], keepMostRecentCount?: number): {
+    items: GoogleContent[];
+};

package/dist/cjs/lib/v3/agent/utils/messageProcessing.d.ts

@@ -0,0 +1,12 @@
+import type { ModelMessage } from "ai";
+/**
+ * Compress old screenshot/ariaTree data in messages in-place.
+ *
+ * Strategy:
+ * - Keep only the 2 most recent vision results (screenshots OR vision action tools like click/type/etc)
+ * - Keep only the 1 most recent ariaTree (replace older ones with placeholder)
+ *
+ * @param messages - The messages array to modify in-place
+ * @returns Number of items compressed
+ */
+export declare function processMessages(messages: ModelMessage[]): number;

package/dist/cjs/lib/v3/agent/utils/screenshotHandler.d.ts

@@ -0,0 +1,10 @@
+import type { Page } from "../../understudy/page.js";
+/**
+ * Waits for the page to settle and captures a screenshot.
+ * If the screenshot fails (e.g., page closed, navigation in progress),
+ * returns undefined instead of throwing - allowing the action to still succeed.
+ *
+ * @param page - The page to capture
+ * @param delayMs - Delay before capturing (default: 500ms, pass 0 to skip delay)
+ */
+export declare function waitAndCaptureScreenshot(page: Page, delayMs?: number): Promise<string | undefined>;

package/dist/cjs/lib/v3/agent/utils/validateExperimentalFeatures.d.ts

@@ -0,0 +1,26 @@
+import type { AgentConfig, AgentExecuteOptionsBase } from "../../types/public/index.js";
+export interface AgentValidationOptions {
+    /** Whether experimental mode is enabled */
+    isExperimental: boolean;
+    /** Agent config options (integrations, tools, stream, cua, etc.) */
+    agentConfig?: Partial<AgentConfig>;
+    /** Execute options (callbacks, signal, messages, etc.) */
+    executeOptions?: (Partial<AgentExecuteOptionsBase> & {
+        callbacks?: unknown;
+    }) | null;
+    /** Whether this is streaming mode (can be derived from agentConfig.stream) */
+    isStreaming?: boolean;
+}
+/**
+ * Validates agent configuration and experimental feature usage.
+ *
+ * This utility consolidates all validation checks for both CUA and non-CUA agent paths:
+ * - Invalid argument errors for CUA (streaming, abort signal, message continuation, excludeTools, output schema are not supported)
+ * - Experimental feature checks for integrations and tools (both CUA and non-CUA)
+ * - Experimental feature checks for hybrid mode (requires experimental: true)
+ * - Experimental feature checks for non-CUA only (callbacks, signal, messages, streaming, excludeTools, output schema)
+ *
+ * Throws StagehandInvalidArgumentError for invalid/unsupported configurations.
+ * Throws ExperimentalNotConfiguredError if experimental features are used without experimental mode.
+ */
+export declare function validateExperimentalFeatures(options: AgentValidationOptions): void;

package/dist/cjs/lib/v3/agent/utils/xpath.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Utility functions for XPath handling in agent tools.
+ */
+/**
+ * Ensures a value is properly formatted as an XPath selector.
+ * Returns null if the value is not a valid string.
+ *
+ * @param value - The value to normalize as an XPath
+ * @returns The normalized XPath string prefixed with "xpath=" or null
+ */
+export declare function ensureXPath(value: unknown): string | null;

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

@@ -0,0 +1,86 @@
+import type { Action, ActResult, AgentConfig, AgentExecuteOptions, AgentResult, ExtractResult, LogLine, StagehandMetrics, ActOptions, ExtractOptions, ObserveOptions, Api } from "./types/public/index.js";
+import type { SerializableResponse, AgentCacheTransferPayload } from "./types/private/index.js";
+import type { StagehandZodSchema } from "./zodCompat.js";
+/**
+ * Constructor parameters for StagehandAPIClient
+ */
+interface StagehandAPIConstructorParams {
+    apiKey: string;
+    projectId: string;
+    logger: (message: LogLine) => void;
+}
+/**
+ * Parameters for starting a session via the API client.
+ * Extends Api.SessionStartRequest with client-specific field (modelApiKey).
+ *
+ * Wire format: Api.SessionStartRequest (modelApiKey sent via header, not body)
+ */
+interface ClientSessionStartParams extends Api.SessionStartRequest {
+    /** Model API key - sent via x-model-api-key header, not in request body */
+    modelApiKey: string;
+}
+/**
+ * Client parameters for act() method.
+ * Derives structure from Api.ActRequest but uses SDK's ActOptions (which includes `page`).
+ * Before serialization, `page` is stripped to produce Api.ActRequest wire format.
+ */
+interface ClientActParameters {
+    input: Api.ActRequest["input"];
+    options?: ActOptions;
+    frameId?: Api.ActRequest["frameId"];
+}
+/**
+ * Client parameters for extract() method.
+ * Derives structure from Api.ExtractRequest but uses SDK's ExtractOptions (which includes `page`)
+ * and accepts Zod schema (converted to JSON schema for wire format).
+ */
+interface ClientExtractParameters {
+    instruction?: Api.ExtractRequest["instruction"];
+    schema?: StagehandZodSchema;
+    options?: ExtractOptions;
+    frameId?: Api.ExtractRequest["frameId"];
+}
+/**
+ * Client parameters for observe() method.
+ * Derives structure from Api.ObserveRequest but uses SDK's ObserveOptions (which includes `page`).
+ * Before serialization, `page` is stripped to produce Api.ObserveRequest wire format.
+ */
+interface ClientObserveParameters {
+    instruction?: Api.ObserveRequest["instruction"];
+    options?: ObserveOptions;
+    frameId?: Api.ObserveRequest["frameId"];
+}
+export declare class StagehandAPIClient {
+    private apiKey;
+    private projectId;
+    private sessionId?;
+    private modelApiKey;
+    private modelProvider?;
+    private logger;
+    private fetchWithCookies;
+    private lastFinishedEventData;
+    private latestAgentCacheEntry;
+    constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams);
+    init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, systemPrompt, selfHeal, browserbaseSessionCreateParams, browserbaseSessionID, }: ClientSessionStartParams): Promise<Api.SessionStartResult>;
+    act({ input, options, frameId, }: ClientActParameters): Promise<ActResult>;
+    extract<T extends StagehandZodSchema>({ instruction, schema: zodSchema, options, frameId, }: ClientExtractParameters): Promise<ExtractResult<T>>;
+    observe({ instruction, options, frameId, }: ClientObserveParameters): Promise<Action[]>;
+    goto(url: string, options?: Api.NavigateRequest["options"], frameId?: string): Promise<SerializableResponse | null>;
+    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions | string, frameId?: string, shouldCache?: boolean): Promise<AgentResult>;
+    consumeLatestAgentCacheEntry(): AgentCacheTransferPayload | null;
+    end(): Promise<Response>;
+    getReplayMetrics(): Promise<StagehandMetrics>;
+    /**
+     * Prepares a model configuration for the API payload by ensuring the `apiKey`
+     * is included. If the model is passed as a string, converts it to an object
+     * with `modelName` and `apiKey`.
+     *
+     * In API mode, we only attempt to load an API key from env vars when the
+     * model provider differs from the one used to init the session.
+     */
+    private prepareModelConfig;
+    private consumeFinishedEventData;
+    private execute;
+    private request;
+}
+export {};

package/dist/cjs/lib/v3/cache/ActCache.d.ts

@@ -0,0 +1,23 @@
+import type { LLMClient } from "../llm/LLMClient.js";
+import type { ActResult } from "../types/public/index.js";
+import type { Page } from "../understudy/page.js";
+import { ActCacheContext, ActCacheDeps } from "../types/private/index.js";
+export declare class ActCache {
+    private readonly storage;
+    private readonly logger;
+    private readonly getActHandler;
+    private readonly getDefaultLlmClient;
+    private readonly domSettleTimeoutMs?;
+    constructor({ storage, logger, getActHandler, getDefaultLlmClient, domSettleTimeoutMs, }: ActCacheDeps);
+    get enabled(): boolean;
+    prepareContext(instruction: string, page: Page, variables?: Record<string, string>): Promise<ActCacheContext | null>;
+    tryReplay(context: ActCacheContext, page: Page, timeout?: number, llmClientOverride?: LLMClient): Promise<ActResult | null>;
+    store(context: ActCacheContext, result: ActResult): Promise<void>;
+    private buildActCacheKey;
+    private replayCachedActions;
+    private haveActionsChanged;
+    private refreshCacheEntry;
+    private doVariableKeysMatch;
+    private hasAllVariableValues;
+    private runWithTimeout;
+}

package/dist/cjs/lib/v3/cache/AgentCache.d.ts

@@ -0,0 +1,109 @@
+import type { LLMClient } from "../llm/LLMClient.js";
+import type { AgentReplayStep, SanitizedAgentExecuteOptions, AgentCacheContext, AgentCacheDeps, AgentCacheTransferPayload } from "../types/private/index.js";
+import type { AgentResult, AgentStreamResult, AgentConfig, AgentExecuteOptionsBase } from "../types/public/index.js";
+import type { Page } from "../understudy/page.js";
+export declare class AgentCache {
+    private readonly storage;
+    private readonly logger;
+    private readonly getActHandler;
+    private readonly getContext;
+    private readonly getDefaultLlmClient;
+    private readonly getBaseModelName;
+    private readonly getSystemPrompt;
+    private readonly domSettleTimeoutMs?;
+    private readonly act;
+    private readonly bufferLatestEntry;
+    private recording;
+    private latestEntry;
+    constructor({ storage, logger, getActHandler, getContext, getDefaultLlmClient, getBaseModelName, getSystemPrompt, domSettleTimeoutMs, act, bufferLatestEntry, }: AgentCacheDeps);
+    get enabled(): boolean;
+    shouldAttemptCache(instruction: string): boolean;
+    sanitizeExecuteOptions(options?: AgentExecuteOptionsBase): SanitizedAgentExecuteOptions;
+    buildConfigSignature(agentOptions?: AgentConfig): string;
+    prepareContext(params: {
+        instruction: string;
+        options: SanitizedAgentExecuteOptions;
+        configSignature: string;
+        page: Page;
+    }): Promise<AgentCacheContext | null>;
+    tryReplay(context: AgentCacheContext, llmClientOverride?: LLMClient): Promise<AgentResult | null>;
+    /**
+     * Attempts to replay a cached agent execution and returns it as a stream result.
+     *
+     * This method exists because the agent API exposes two execution modes:
+     * - `execute()` - Returns a Promise<AgentResult> directly
+     * - `stream()` - Returns an AgentStreamResult with async iterables for real-time output
+     *
+     * When a cache hit occurs, we need to return the appropriate type for each mode:
+     * - For `execute()`, we use `tryReplay()` which returns AgentResult
+     * - For `stream()`, we use `tryReplayAsStream()` which wraps the result in a
+     *   stream-compatible interface
+     *
+     * This ensures consumers using `stream()` can still iterate over `textStream`
+     * and await `result` even when the response comes from cache, maintaining
+     * API consistency regardless of whether the result was cached or live.
+     */
+    tryReplayAsStream(context: AgentCacheContext, llmClientOverride?: LLMClient): Promise<AgentStreamResult | null>;
+    /**
+     * Creates a mock AgentStreamResult that wraps a cached AgentResult.
+     *
+     * AgentStreamResult (from the AI SDK) is a complex type with multiple async
+     * iterables and promises. When serving from cache, we don't have an actual
+     * LLM stream to consume - we just have the final result. This method creates
+     * a "fake" stream
+  
+     * This approach lets cached responses be transparent to the consumer -
+     * they can use the same iteration patterns whether the result is live or cached.
+     */
+    private createCachedStreamResult;
+    /**
+     * Wraps an AgentStreamResult with caching logic.
+     *
+     * This method handles the complexity of caching for streaming responses:
+     * 1. Begins recording agent replay steps
+     * 2. Wraps the stream's result promise to capture completion
+     * 3. On success: ends recording and stores the cache entry
+     * 4. On error: discards the recording
+     *
+     * This keeps the caching orchestration in AgentCache rather than
+     * spreading it across the V3 class.
+     *
+     * @param context - The cache context for this execution
+     * @param streamResult - The stream result from the agent handler
+     * @param beginRecording - Callback to start recording (from V3)
+     * @param endRecording - Callback to end recording and get steps (from V3)
+     * @param discardRecording - Callback to discard recording on error (from V3)
+     * @returns The wrapped stream result with caching enabled
+     */
+    wrapStreamForCaching(context: AgentCacheContext, streamResult: AgentStreamResult, beginRecording: () => void, endRecording: () => AgentReplayStep[], discardRecording: () => void): AgentStreamResult;
+    store(context: AgentCacheContext, steps: AgentReplayStep[], result: AgentResult): Promise<void>;
+    consumeBufferedEntry(): AgentCacheTransferPayload | null;
+    storeTransferredEntry(payload: AgentCacheTransferPayload | null): Promise<void>;
+    /**
+     * Clone the agent result and prune bulky fields (e.g. screenshot base64 blobs)
+     * before persisting it to disk. This keeps cache entries compact without
+     * mutating the live AgentResult returned to callers.
+     */
+    private pruneAgentResult;
+    beginRecording(): void;
+    endRecording(): AgentReplayStep[];
+    discardRecording(): void;
+    isRecording(): boolean;
+    recordStep(step: AgentReplayStep): void;
+    isReplayActive(): boolean;
+    private serializeAgentModelForCache;
+    private buildAgentCacheKey;
+    private sanitizeModelOptionsForCache;
+    private sanitizeModelValueForCache;
+    private replayAgentCacheEntry;
+    private executeAgentReplayStep;
+    private replayAgentActStep;
+    private replayAgentFillFormStep;
+    private replayAgentGotoStep;
+    private replayAgentScrollStep;
+    private replayAgentWaitStep;
+    private replayAgentNavBackStep;
+    private replayAgentKeysStep;
+    private haveActionsChanged;
+    private refreshAgentCacheEntry;
+}

package/dist/cjs/lib/v3/cache/CacheStorage.d.ts

@@ -0,0 +1,17 @@
+import type { Logger } from "../types/public/index.js";
+import { ReadJsonResult, WriteJsonResult } from "../types/private/index.js";
+export declare class CacheStorage {
+    private readonly logger;
+    private readonly dir?;
+    private readonly memoryStore?;
+    private constructor();
+    static create(cacheDir: string | undefined, logger: Logger, options?: {
+        label?: string;
+    }): CacheStorage;
+    static createMemory(logger: Logger): CacheStorage;
+    get directory(): string | undefined;
+    get enabled(): boolean;
+    private resolvePath;
+    readJson<T>(fileName: string): Promise<ReadJsonResult<T>>;
+    writeJson(fileName: string, data: unknown): Promise<WriteJsonResult>;
+}