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

package/dist/lib/a11y/utils.d.ts

@@ -1,144 +0,0 @@
-import { AccessibilityNode, TreeResult, BackendIdMaps, CombinedA11yResult, EncodedId } from "../../types/context";
-import { StagehandPage } from "../StagehandPage";
-import { LogLine } from "../../types/log";
-import { Frame } from "playwright";
-/**
- * Clean a string by removing private-use unicode characters, normalizing whitespace,
- * and trimming the result.
- *
- * @param input - The text to clean, potentially containing PUA and NBSP characters.
- * @returns A cleaned string with PUA characters removed, NBSP variants collapsed,
- *          consecutive spaces merged, and leading/trailing whitespace trimmed.
- */
-export declare function cleanText(input: string): string;
-/**
- * Generate a human-readable, indented outline of an accessibility node tree.
- *
- * @param node - The accessibility node to format, optionally with an encodedId.
- * @param level - The current depth level for indentation (used internally).
- * @returns A string representation of the node and its descendants, with one node per line.
- */
-export declare function formatSimplifiedTree(node: AccessibilityNode & {
-    encodedId?: EncodedId;
-}, level?: number): string;
-/**
- * Build mappings from CDP backendNodeIds to HTML tag names and relative XPaths.
- *
- * @param experimental - Whether to use experimental behaviour.
- * @param sp - The StagehandPage wrapper for Playwright and CDP calls.
- * @param targetFrame - Optional Playwright.Frame whose DOM subtree to map; defaults to main frame.
- * @returns A Promise resolving to BackendIdMaps containing tagNameMap and xpathMap.
- */
-export declare function buildBackendIdMaps(experimental: boolean, sp: StagehandPage, targetFrame?: Frame): Promise<BackendIdMaps>;
-/**
- * Convert a flat array of AccessibilityNodes into a cleaned, hierarchical tree.
- * Nodes are pruned, structural wrappers removed, and each kept node is stamped
- * with its EncodedId for later lookup or subtree injection.
- *
- * @param nodes - Raw flat list of AX nodes retrieved via CDP.
- * @param tagNameMap - Mapping of EncodedId to HTML tag names for structural decisions.
- * @param logger - Optional function for logging diagnostic messages.
- * @param xpathMap - Optional mapping of EncodedId to relative XPath for element lookup.
- * @returns A Promise resolving to a TreeResult with cleaned tree, simplified text outline,
- *          iframe list, URL map, and inherited xpathMap.
- */
-export declare function buildHierarchicalTree(nodes: AccessibilityNode[], tagNameMap: Record<EncodedId, string>, logger?: (l: LogLine) => void, xpathMap?: Record<EncodedId, string>): Promise<TreeResult>;
-/**
- * Resolve the CDP frame identifier for a Playwright Frame, handling same-process and OOPIF.
- *
- * @param sp - The StagehandPage instance for issuing CDP commands.
- * @param frame - The target Playwright.Frame; undefined or main frame yields undefined.
- * @returns A Promise resolving to the CDP frameId string, or undefined for main document.
- */
-export declare function getCDPFrameId(sp: StagehandPage, frame?: Frame): Promise<string | undefined>;
-/**
- * Retrieve and build a cleaned accessibility tree for a document or specific iframe.
- * Prunes, formats, and optionally filters by XPath, including scrollable role decoration.
- *
- * @param stagehandPage - The StagehandPage instance for Playwright and CDP interaction.
- * @param logger - Logging function for diagnostics and performance metrics.
- * @param selector - Optional XPath to filter the AX tree to a specific subtree.
- * @param targetFrame - Optional Playwright.Frame to scope the AX tree retrieval.
- * @returns A Promise resolving to a TreeResult with the hierarchical AX tree and related metadata.
- */
-export declare function getAccessibilityTree(experimental: boolean, stagehandPage: StagehandPage, logger: (log: LogLine) => void, selector?: string, targetFrame?: Frame): Promise<TreeResult>;
-/**
- * Get the backendNodeId of the iframe element that contains a given Playwright.Frame.
- *
- * @param sp - The StagehandPage instance for issuing CDP commands.
- * @param frame - The Playwright.Frame whose host iframe element to locate.
- * @returns A Promise resolving to the backendNodeId of the iframe element, or null if not applicable.
- */
-export declare function getFrameRootBackendNodeId(sp: StagehandPage, frame: Frame | undefined): Promise<number | null>;
-/**
- * Compute the absolute XPath for the iframe element hosting a given Playwright.Frame.
- *
- * @param frame - The Playwright.Frame whose iframe element to locate.
- * @returns A Promise resolving to the XPath of the iframe element, or "/" if no frame provided.
- */
-export declare function getFrameRootXpathWithShadow(frame: Frame | undefined): Promise<string>;
-export declare function getFrameRootXpath(frame: Frame | undefined): Promise<string>;
-/**
- * Inject simplified subtree outlines into the main frame outline for nested iframes.
- * Walks the main tree text, looks for EncodedId labels, and inserts matching subtrees.
- *
- * @param tree - The indented AX outline of the main frame.
- * @param idToTree - Map of EncodedId to subtree outlines for nested frames.
- * @returns A single combined text outline with iframe subtrees injected.
- */
-export declare function injectSubtrees(tree: string, idToTree: Map<EncodedId, string>): string;
-/**
- * Retrieve and merge accessibility trees for the main document and nested iframes.
- * Walks through frame chains if a root XPath is provided, then stitches subtree outlines.
- *
- * @param stagehandPage - The StagehandPage instance for Playwright and CDP interaction.
- * @param logger - Logging function for diagnostics and performance.
- * @param rootXPath - Optional absolute XPath to focus the crawl on a subtree across frames.
- * @returns A Promise resolving to CombinedA11yResult with combined tree text, xpath map, and URL map.
- */
-export declare function getAccessibilityTreeWithFrames(experimental: boolean, stagehandPage: StagehandPage, logger: (l: LogLine) => void, rootXPath?: string): Promise<CombinedA11yResult>;
-/**
- * `findScrollableElementIds` is a function that identifies elements in
- * the browser that are deemed "scrollable". At a high level, it does the
- * following:
- * - Calls the browser-side `window.getScrollableElementXpaths()` function,
- *   which returns a list of XPaths for scrollable containers.
- * - Iterates over the returned list of XPaths, locating each element in the DOM
- *   using `stagehandPage.sendCDP(...)`
- *     - During each iteration, we call `Runtime.evaluate` to run `document.evaluate(...)`
- *       with each XPath, obtaining a `RemoteObject` reference if it exists.
- *     - Then, for each valid object reference, we call `DOM.describeNode` to retrieve
- *       the element’s `backendNodeId`.
- * - Collects all resulting `backendNodeId`s in a Set and returns them.
- *
- * @param stagehandPage - A StagehandPage instance with built-in CDP helpers.
- * @returns A Promise that resolves to a Set of unique `backendNodeId`s corresponding
- *          to scrollable elements in the DOM.
- */
-export declare function findScrollableElementIds(stagehandPage: StagehandPage, targetFrame?: Frame): Promise<Set<number>>;
-/**
- * Resolve an XPath to a Chrome-DevTools-Protocol (CDP) remote-object ID.
- *
- * @param page     A StagehandPage (or Playwright.Page with .sendCDP)
- * @param xpath    An absolute or relative XPath
- * @returns        The remote objectId for the matched node, or null
- */
-export declare function resolveObjectIdForXPath(page: StagehandPage, xpath: string, targetFrame?: Frame): Promise<string | null>;
-/**
- * Resolve a chain of iframe frames from an absolute XPath, returning the frame sequence and inner XPath.
- *
- * This helper walks an XPath expression containing iframe steps (e.g., '/html/body/iframe[2]/...'),
- * descending into each matching iframe element to build a frame chain, and returns the leftover
- * XPath segment to evaluate within the context of the last iframe.
- *
- * @param sp - The StagehandPage instance for evaluating XPath and locating frames.
- * @param absPath - An absolute XPath expression starting with '/', potentially including iframe steps.
- * @returns An object containing:
- *   frames: Array of Frame objects representing each iframe in the chain.
- *   rest: The remaining XPath string to evaluate inside the final iframe.
- * @throws Error if an iframe cannot be found or the final XPath cannot be resolved.
- */
-export declare function resolveFrameChain(sp: StagehandPage, absPath: string): Promise<{
-    frames: Frame[];
-    rest: string;
-}>;

package/dist/lib/agent/AgentClient.d.ts

@@ -1,20 +0,0 @@
-import { AgentAction, AgentResult, AgentType, AgentExecutionOptions } from "@/types/agent";
-import { ToolSet } from "ai/dist";
-/**
- * Abstract base class for agent clients
- * This provides a common interface for all agent implementations
- */
-export declare abstract class AgentClient {
-    type: AgentType;
-    modelName: string;
-    clientOptions: Record<string, unknown>;
-    userProvidedInstructions?: string;
-    constructor(type: AgentType, modelName: string, userProvidedInstructions?: string);
-    abstract execute(options: AgentExecutionOptions): Promise<AgentResult>;
-    abstract captureScreenshot(options?: Record<string, unknown>): Promise<unknown>;
-    abstract setViewport(width: number, height: number): void;
-    abstract setCurrentUrl(url: string): void;
-    abstract setScreenshotProvider(provider: () => Promise<string>): void;
-    abstract setActionHandler(handler: (action: AgentAction) => Promise<void>): void;
-    abstract setTools(tools: ToolSet): void;
-}

package/dist/lib/agent/AgentProvider.d.ts

@@ -1,19 +0,0 @@
-import { AgentType } from "@/types/agent";
-import { LogLine } from "@/types/log";
-import { ToolSet } from "ai/dist";
-import { AgentClient } from "./AgentClient";
-export declare const modelToAgentProviderMap: Record<string, AgentType>;
-/**
- * Provider for agent clients
- * This class is responsible for creating the appropriate agent client
- * based on the provider type
- */
-export declare class AgentProvider {
-    private logger;
-    /**
-     * Create a new agent provider
-     */
-    constructor(logger: (message: LogLine) => void);
-    getClient(modelName: string, clientOptions?: Record<string, unknown>, userProvidedInstructions?: string, tools?: ToolSet): AgentClient;
-    static getAgentProvider(modelName: string): AgentType;
-}

package/dist/lib/agent/AnthropicCUAClient.d.ts

@@ -1,56 +0,0 @@
-import { AgentAction, AgentExecutionOptions, AgentResult, AgentType, AnthropicContentBlock, AnthropicMessage, AnthropicToolResult, ToolUseItem } from "@/types/agent";
-import { LogLine } from "@/types/log";
-import { ToolSet } from "ai";
-import { AgentClient } from "./AgentClient";
-export type ResponseInputItem = AnthropicMessage | AnthropicToolResult;
-/**
- * Client for Anthropic's Computer Use API
- * This implementation uses the official Anthropic Messages API for Computer Use
- */
-export declare class AnthropicCUAClient extends AgentClient {
-    private apiKey;
-    private baseURL?;
-    private client;
-    lastMessageId?: string;
-    private currentViewport;
-    private currentUrl?;
-    private screenshotProvider?;
-    private actionHandler?;
-    private thinkingBudget;
-    private tools?;
-    constructor(type: AgentType, modelName: string, userProvidedInstructions?: string, clientOptions?: Record<string, unknown>, tools?: ToolSet);
-    setViewport(width: number, height: number): void;
-    setCurrentUrl(url: string): void;
-    setScreenshotProvider(provider: () => Promise<string>): void;
-    setActionHandler(handler: (action: AgentAction) => Promise<void>): void;
-    setTools(tools: ToolSet): void;
-    /**
-     * Execute a task with the Anthropic CUA
-     * This is the main entry point for the agent
-     * @implements AgentClient.execute
-     */
-    execute(executionOptions: AgentExecutionOptions): Promise<AgentResult>;
-    executeStep(inputItems: ResponseInputItem[], logger: (message: LogLine) => void): Promise<{
-        actions: AgentAction[];
-        message: string;
-        completed: boolean;
-        nextInputItems: ResponseInputItem[];
-        usage: {
-            input_tokens: number;
-            output_tokens: number;
-            inference_time_ms: number;
-        };
-    }>;
-    private createInitialInputItems;
-    getAction(inputItems: ResponseInputItem[]): Promise<{
-        content: AnthropicContentBlock[];
-        id: string;
-        usage: Record<string, number>;
-    }>;
-    takeAction(toolUseItems: ToolUseItem[], logger: (message: LogLine) => void): Promise<AnthropicToolResult[]>;
-    private convertToolUseToAction;
-    captureScreenshot(options?: {
-        base64Image?: string;
-        currentUrl?: string;
-    }): Promise<string>;
-}

package/dist/lib/agent/GoogleCUAClient.d.ts

@@ -1,63 +0,0 @@
-import { LogLine } from "../../types/log";
-import { AgentAction, AgentResult, AgentType, AgentExecutionOptions } from "@/types/agent";
-import { AgentClient } from "./AgentClient";
-/**
- * Client for Google's Computer Use Assistant API
- * This implementation uses the Google Generative AI SDK for Computer Use
- */
-export declare class GoogleCUAClient extends AgentClient {
-    private apiKey;
-    private client;
-    private currentViewport;
-    private currentUrl?;
-    private screenshotProvider?;
-    private actionHandler?;
-    private history;
-    private environment;
-    private generateContentConfig;
-    constructor(type: AgentType, modelName: string, userProvidedInstructions?: string, clientOptions?: Record<string, unknown>);
-    setViewport(width: number, height: number): void;
-    setCurrentUrl(url: string): void;
-    setScreenshotProvider(provider: () => Promise<string>): void;
-    setActionHandler(handler: (action: AgentAction) => Promise<void>): void;
-    setTools(): void;
-    /**
-     * Execute a task with the Google CUA
-     * This is the main entry point for the agent
-     * @implements AgentClient.execute
-     */
-    execute(executionOptions: AgentExecutionOptions): Promise<AgentResult>;
-    /**
-     * Initialize conversation history with the initial instruction
-     */
-    private initializeHistory;
-    /**
-     * Execute a single step of the agent
-     */
-    executeStep(logger: (message: LogLine) => void): Promise<{
-        actions: AgentAction[];
-        message: string;
-        completed: boolean;
-        usage: {
-            input_tokens: number;
-            output_tokens: number;
-            inference_time_ms: number;
-        };
-    }>;
-    /**
-     * Process the response from Google's API
-     */
-    private processResponse;
-    /**
-     * Convert Google function call to Stagehand action
-     */
-    private convertFunctionCallToAction;
-    /**
-     * Normalize coordinates from Google's 0-1000 range to actual viewport dimensions
-     */
-    private normalizeCoordinates;
-    captureScreenshot(options?: {
-        base64Image?: string;
-        currentUrl?: string;
-    }): Promise<string>;
-}

package/dist/lib/agent/OpenAICUAClient.d.ts

@@ -1,65 +0,0 @@
-import { LogLine } from "../../types/log";
-import { AgentAction, AgentResult, AgentType, AgentExecutionOptions, ResponseInputItem, ResponseItem } from "@/types/agent";
-import { AgentClient } from "./AgentClient";
-import { ToolSet } from "ai/dist";
-/**
- * Client for OpenAI's Computer Use Assistant API
- * This implementation uses the official OpenAI Responses API for Computer Use
- */
-export declare class OpenAICUAClient extends AgentClient {
-    private apiKey;
-    private organization?;
-    private baseURL;
-    private client;
-    lastResponseId?: string;
-    private currentViewport;
-    private currentUrl?;
-    private screenshotProvider?;
-    private actionHandler?;
-    private reasoningItems;
-    private environment;
-    private tools?;
-    constructor(type: AgentType, modelName: string, userProvidedInstructions?: string, clientOptions?: Record<string, unknown>, tools?: ToolSet);
-    setViewport(width: number, height: number): void;
-    setCurrentUrl(url: string): void;
-    setScreenshotProvider(provider: () => Promise<string>): void;
-    setActionHandler(handler: (action: AgentAction) => Promise<void>): void;
-    setTools(tools: ToolSet): void;
-    /**
-     * Execute a task with the OpenAI CUA
-     * This is the main entry point for the agent
-     * @implements AgentClient.execute
-     */
-    execute(executionOptions: AgentExecutionOptions): Promise<AgentResult>;
-    /**
-     * Execute a single step of the agent
-     * This coordinates the flow: Request → Get Action → Execute Action
-     */
-    executeStep(inputItems: ResponseInputItem[], previousResponseId: string | undefined, logger: (message: LogLine) => void): Promise<{
-        actions: AgentAction[];
-        message: string;
-        completed: boolean;
-        nextInputItems: ResponseInputItem[];
-        responseId: string;
-        usage: {
-            input_tokens: number;
-            output_tokens: number;
-            inference_time_ms: number;
-        };
-    }>;
-    private isComputerCallItem;
-    private isFunctionCallItem;
-    private createInitialInputItems;
-    getAction(inputItems: ResponseInputItem[], previousResponseId?: string): Promise<{
-        output: ResponseItem[];
-        responseId: string;
-        usage: Record<string, number>;
-    }>;
-    takeAction(output: ResponseItem[], logger: (message: LogLine) => void): Promise<ResponseInputItem[]>;
-    private convertComputerCallToAction;
-    private convertFunctionCallToAction;
-    captureScreenshot(options?: {
-        base64Image?: string;
-        currentUrl?: string;
-    }): Promise<string>;
-}

package/dist/lib/agent/StagehandAgent.d.ts

@@ -1,15 +0,0 @@
-import { LogLine } from "@/types/log";
-import { AgentExecuteOptions, AgentResult } from "@/types/agent";
-import { AgentClient } from "./AgentClient";
-/**
- * Main interface for agent operations in Stagehand
- * This class provides methods for executing tasks with an agent
- */
-export declare class StagehandAgent {
-    private client;
-    private logger;
-    constructor(client: AgentClient, logger: (message: LogLine) => void);
-    execute(optionsOrInstruction: AgentExecuteOptions | string): Promise<AgentResult>;
-    getModelName(): string;
-    getAgentType(): string;
-}

package/dist/lib/agent/tools/act.d.ts

@@ -1,59 +0,0 @@
-import { z } from "zod/v3";
-import { Stagehand } from "../../index";
-export declare const createActTool: (stagehand: Stagehand, executionModel?: string) => import("ai/dist").Tool<z.ZodObject<{
-    action: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    action?: string;
-}, {
-    action?: string;
-}>, {
-    success: boolean;
-    error: string;
-    isIframe: boolean;
-    action?: undefined;
-    playwrightArguments?: undefined;
-} | {
-    success: boolean;
-    action: string;
-    isIframe: boolean;
-    playwrightArguments: {
-        description: string;
-        method: string;
-        arguments: string[];
-        selector: string;
-    };
-    error?: undefined;
-} | {
-    success: boolean;
-    error: any;
-    isIframe?: undefined;
-    action?: undefined;
-    playwrightArguments?: undefined;
-}> & {
-    execute: (args: {
-        action?: string;
-    }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
-        success: boolean;
-        error: string;
-        isIframe: boolean;
-        action?: undefined;
-        playwrightArguments?: undefined;
-    } | {
-        success: boolean;
-        action: string;
-        isIframe: boolean;
-        playwrightArguments: {
-            description: string;
-            method: string;
-            arguments: string[];
-            selector: string;
-        };
-        error?: undefined;
-    } | {
-        success: boolean;
-        error: any;
-        isIframe?: undefined;
-        action?: undefined;
-        playwrightArguments?: undefined;
-    }>;
-};

package/dist/lib/agent/tools/ariaTree.d.ts

@@ -1,11 +0,0 @@
-import { z } from "zod/v3";
-import { Stagehand } from "../../index";
-export declare const createAriaTreeTool: (stagehand: Stagehand) => import("ai/dist").Tool<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>, {
-    content: string;
-    pageUrl: string;
-}> & {
-    execute: (args: {}, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
-        content: string;
-        pageUrl: string;
-    }>;
-};

package/dist/lib/agent/tools/close.d.ts

@@ -1,22 +0,0 @@
-import { z } from "zod/v3";
-export declare const createCloseTool: () => import("ai/dist").Tool<z.ZodObject<{
-    reasoning: z.ZodString;
-    success: z.ZodBoolean;
-}, "strip", z.ZodTypeAny, {
-    reasoning?: string;
-    success?: boolean;
-}, {
-    reasoning?: string;
-    success?: boolean;
-}>, {
-    success: boolean;
-    reasoning: string;
-}> & {
-    execute: (args: {
-        reasoning?: string;
-        success?: boolean;
-    }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
-        success: boolean;
-        reasoning: string;
-    }>;
-};

package/dist/lib/agent/tools/extract.d.ts

@@ -1,38 +0,0 @@
-import { z } from "zod/v3";
-import { Stagehand } from "../../index";
-import { LogLine } from "@/types/log";
-export declare const createExtractTool: (stagehand: Stagehand, executionModel?: string, logger?: (message: LogLine) => void) => import("ai/dist").Tool<z.ZodObject<{
-    instruction: z.ZodString;
-    schema: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    schema?: string;
-    instruction?: string;
-}, {
-    schema?: string;
-    instruction?: string;
-}>, {
-    success: boolean;
-    data: any;
-    timestamp: number;
-    error?: undefined;
-} | {
-    success: boolean;
-    error: string;
-    timestamp: number;
-    data?: undefined;
-}> & {
-    execute: (args: {
-        schema?: string;
-        instruction?: string;
-    }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
-        success: boolean;
-        data: any;
-        timestamp: number;
-        error?: undefined;
-    } | {
-        success: boolean;
-        error: string;
-        timestamp: number;
-        data?: undefined;
-    }>;
-};

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

@@ -1,37 +0,0 @@
-import { z } from "zod/v3";
-import { Stagehand } from "../../index";
-export declare const createFillFormTool: (stagehand: Stagehand, executionModel?: string) => import("ai/dist").Tool<z.ZodObject<{
-    fields: z.ZodArray<z.ZodObject<{
-        action: z.ZodString;
-        value: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        value?: string;
-        action?: string;
-    }, {
-        value?: string;
-        action?: string;
-    }>, "many">;
-}, "strip", z.ZodTypeAny, {
-    fields?: {
-        value?: string;
-        action?: string;
-    }[];
-}, {
-    fields?: {
-        value?: string;
-        action?: string;
-    }[];
-}>, {
-    success: boolean;
-    actions: import("@/types/stagehand").ActResult[];
-}> & {
-    execute: (args: {
-        fields?: {
-            value?: string;
-            action?: string;
-        }[];
-    }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
-        success: boolean;
-        actions: import("@/types/stagehand").ActResult[];
-    }>;
-};

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

@@ -1,29 +0,0 @@
-import { z } from "zod/v3";
-import { Stagehand } from "../../index";
-export declare const createGotoTool: (stagehand: Stagehand) => import("ai/dist").Tool<z.ZodObject<{
-    url: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    url?: string;
-}, {
-    url?: string;
-}>, {
-    success: boolean;
-    url: string;
-    error?: undefined;
-} | {
-    success: boolean;
-    error: any;
-    url?: undefined;
-}> & {
-    execute: (args: {
-        url?: string;
-    }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
-        success: boolean;
-        url: string;
-        error?: undefined;
-    } | {
-        success: boolean;
-        error: any;
-        url?: undefined;
-    }>;
-};