@browserbasehq/stagehand 2.5.3 → 2.5.5

package/dist/index.d.ts

@@ -52,7 +52,7 @@ interface LLMTool {
     parameters: Record<string, unknown>;
 }
 
-declare const AvailableModelSchema: z.ZodEnum<["gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "o4-mini", "o3", "o3-mini", "o1", "o1-mini", "gpt-4o", "gpt-4o-mini", "gpt-4o-2024-08-06", "gpt-4.5-preview", "o1-preview", "claude-3-5-sonnet-latest", "claude-3-5-sonnet-20241022", "claude-3-5-sonnet-20240620", "claude-3-7-sonnet-latest", "claude-3-7-sonnet-20250219", "cerebras-llama-3.3-70b", "cerebras-llama-3.1-8b", "groq-llama-3.3-70b-versatile", "groq-llama-3.3-70b-specdec", "gemini-1.5-flash", "gemini-1.5-pro", "gemini-1.5-flash-8b", "gemini-2.0-flash-lite", "gemini-2.0-flash", "gemini-2.5-flash-preview-04-17", "gemini-2.5-pro-preview-03-25"]>;
+declare const AvailableModelSchema: z.ZodEnum<["gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "o4-mini", "o3", "o3-mini", "o1", "o1-mini", "gpt-4o", "gpt-4o-mini", "gpt-4o-2024-08-06", "gpt-4.5-preview", "o1-preview", "claude-haiku-4-5", "claude-3-7-sonnet-latest", "claude-3-7-sonnet-20250219", "cerebras-llama-3.3-70b", "cerebras-llama-3.1-8b", "groq-llama-3.3-70b-versatile", "groq-llama-3.3-70b-specdec", "gemini-1.5-flash", "gemini-1.5-pro", "gemini-1.5-flash-8b", "gemini-2.0-flash-lite", "gemini-2.0-flash", "gemini-2.5-flash-preview-04-17", "gemini-2.5-pro-preview-03-25"]>;
 type AvailableModel = z.infer<typeof AvailableModelSchema> | string;
 type ModelProvider = "openai" | "anthropic" | "cerebras" | "groq" | "google" | "aisdk";
 type ClientOptions = ClientOptions$1 | ClientOptions$2;
@@ -318,7 +318,7 @@ interface ObserveOptions {
     iframes?: boolean;
     frameId?: string;
 }
-interface ObserveResult {
+interface ObserveResult$1 {
     selector: string;
     description: string;
     backendNodeId?: number;
@@ -498,9 +498,9 @@ interface ActToolResult {
     action?: string;
     error?: string;
     isIframe?: boolean;
-    playwrightArguments?: ObserveResult | null;
+    playwrightArguments?: ObserveResult$1 | null;
 }
-interface AgentAction {
+interface AgentAction$1 {
     type: string;
     reasoning?: string;
     taskCompleted?: boolean;
@@ -510,13 +510,13 @@ interface AgentAction {
     timestamp?: number;
     pageUrl?: string;
     instruction?: string;
-    playwrightArguments?: ObserveResult | null;
+    playwrightArguments?: ObserveResult$1 | null;
     [key: string]: unknown;
 }
-interface AgentResult {
+interface AgentResult$1 {
     success: boolean;
     message: string;
-    actions: AgentAction[];
+    actions: AgentAction$1[];
     completed: boolean;
     metadata?: Record<string, unknown>;
     usage?: {
@@ -525,14 +525,14 @@ interface AgentResult {
         inference_time_ms: number;
     };
 }
-interface AgentOptions {
+interface AgentOptions$1 {
     maxSteps?: number;
     autoScreenshot?: boolean;
     waitBetweenActions?: number;
     context?: string;
     highlightCursor?: boolean;
 }
-interface AgentExecuteOptions extends AgentOptions {
+interface AgentExecuteOptions$1 extends AgentOptions$1 {
     instruction: string;
 }
 type AgentProviderType = "openai" | "anthropic" | "google";
@@ -545,7 +545,7 @@ interface AgentClientOptions {
 }
 type AgentType = "openai" | "anthropic" | "google";
 interface AgentExecutionOptions {
-    options: AgentExecuteOptions;
+    options: AgentExecuteOptions$1;
     logger: (message: LogLine) => void;
     retries?: number;
 }
@@ -632,7 +632,7 @@ type ResponseInputItem = {
     output: string;
 };
 interface AgentInstance {
-    execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
+    execute: (instructionOrOptions: string | AgentExecuteOptions$1) => Promise<AgentResult$1>;
     setScreenshotCollector?: (collector: unknown) => void;
 }
 
@@ -657,13 +657,13 @@ interface StagehandScreenshotOptions extends PageScreenshotOptions {
 interface Page extends Omit<Page$1, "on" | "screenshot"> {
     act(action: string): Promise<ActResult>;
     act(options: ActOptions): Promise<ActResult>;
-    act(observation: ObserveResult): Promise<ActResult>;
+    act(observation: ObserveResult$1): Promise<ActResult>;
     extract(instruction: string): Promise<ExtractResult<typeof defaultExtractSchema>>;
     extract<T extends z.AnyZodObject>(options: ExtractOptions<T>): Promise<ExtractResult<T>>;
     extract(): Promise<ExtractResult<typeof pageTextSchema>>;
-    observe(): Promise<ObserveResult[]>;
-    observe(instruction: string): Promise<ObserveResult[]>;
-    observe(options?: ObserveOptions): Promise<ObserveResult[]>;
+    observe(): Promise<ObserveResult$1[]>;
+    observe(instruction: string): Promise<ObserveResult$1[]>;
+    observe(options?: ObserveOptions): Promise<ObserveResult$1[]>;
     screenshot(options?: StagehandScreenshotOptions): Promise<Buffer>;
     on: {
         (event: "popup", listener: (page: Page) => unknown): Page;
@@ -672,6 +672,31 @@ interface Page extends Omit<Page$1, "on" | "screenshot"> {
 type BrowserContext = BrowserContext$1;
 type Browser = Browser$1;
 
+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;
+        };
+    }[];
+};
+interface TreeResult {
+    tree: AccessibilityNode[];
+    simplified: string;
+    iframes?: AccessibilityNode[];
+    idToUrl: Record<EncodedId, string>;
+    xpathMap: Record<EncodedId, string>;
+}
 interface EnhancedContext extends Omit<BrowserContext$1, "newPage" | "pages"> {
     newPage(): Promise<Page>;
     pages(): Page[];
@@ -703,14 +728,14 @@ interface StartSessionResult {
     available?: boolean;
 }
 
-interface ObserveResult$1 {
+interface ObserveResult {
     selector: string;
     description: string;
     backendNodeId?: number;
     method?: string;
     arguments?: string[];
 }
-interface AgentAction$1 {
+interface AgentAction {
     type: string;
     reasoning?: string;
     taskCompleted?: boolean;
@@ -720,13 +745,13 @@ interface AgentAction$1 {
     timestamp?: number;
     pageUrl?: string;
     instruction?: string;
-    playwrightArguments?: ObserveResult$1 | null;
+    playwrightArguments?: ObserveResult | null;
     [key: string]: unknown;
 }
-interface AgentResult$1 {
+interface AgentResult {
     success: boolean;
     message: string;
-    actions: AgentAction$1[];
+    actions: AgentAction[];
     completed: boolean;
     metadata?: Record<string, unknown>;
     usage?: {
@@ -735,14 +760,14 @@ interface AgentResult$1 {
         inference_time_ms: number;
     };
 }
-interface AgentOptions$1 {
+interface AgentOptions {
     maxSteps?: number;
     autoScreenshot?: boolean;
     waitBetweenActions?: number;
     context?: string;
     highlightCursor?: boolean;
 }
-interface AgentExecuteOptions$1 extends AgentOptions$1 {
+interface AgentExecuteOptions extends AgentOptions {
     instruction: string;
 }
 
@@ -755,11 +780,11 @@ declare class StagehandAPI {
     private fetchWithCookies;
     constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams);
     init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, debugDom, systemPrompt, selfHeal, waitForCaptchaSolves, actionTimeoutMs, browserbaseSessionCreateParams, browserbaseSessionID, }: StartSessionParams): Promise<StartSessionResult>;
-    act(options: ActOptions | ObserveResult): Promise<ActResult>;
+    act(options: ActOptions | ObserveResult$1): Promise<ActResult>;
     extract<T extends z.AnyZodObject>(options: ExtractOptions<T>): Promise<ExtractResult<T>>;
-    observe(options?: ObserveOptions): Promise<ObserveResult[]>;
+    observe(options?: ObserveOptions): Promise<ObserveResult$1[]>;
     goto(url: string, options?: GotoOptions): Promise<void>;
-    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions$1): Promise<AgentResult$1>;
+    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions): Promise<AgentResult>;
     end(): Promise<Response>;
     private execute;
     private request;
@@ -771,6 +796,7 @@ declare class StagehandContext {
     private pageMap;
     private activeStagehandPage;
     private readonly frameIdMap;
+    private static readonly contextsWithInitScript;
     private constructor();
     private createStagehandPage;
     static init(context: BrowserContext$1, stagehand: Stagehand): Promise<StagehandContext>;
@@ -810,7 +836,6 @@ declare class StagehandPage {
     ordinalForFrameId(fid: string | undefined): number;
     encodeWithFrameId(fid: string | undefined, backendId: number): EncodedId;
     resetFrameOrdinals(): void;
-    private ensureStagehandScript;
     /** Register the custom selector engine that pierces open/closed shadow roots. */
     private ensureStagehandSelectorEngine;
     /**
@@ -858,9 +883,9 @@ declare class StagehandPage {
      *                    `this.stagehand.domSettleTimeoutMs`.
      */
     _waitForSettledDom(timeoutMs?: number): Promise<void>;
-    act(actionOrOptions: string | ActOptions | ObserveResult): Promise<ActResult>;
+    act(actionOrOptions: string | ActOptions | ObserveResult$1): Promise<ActResult>;
     extract<T extends z.AnyZodObject = typeof defaultExtractSchema>(instructionOrOptions?: string | ExtractOptions<T>): Promise<ExtractResult<T>>;
-    observe(instructionOrOptions?: string | ObserveOptions): Promise<ObserveResult[]>;
+    observe(instructionOrOptions?: string | ObserveOptions): Promise<ObserveResult$1[]>;
     /**
      * Get or create a CDP session for the given target.
      * @param target  The Page or (OOPIF) Frame you want to talk to.
@@ -926,6 +951,7 @@ declare class StagehandError extends Error {
     constructor(message: string);
 }
 declare class StagehandDefaultError extends StagehandError {
+    causedBy?: Error | StagehandError;
     constructor(error?: unknown);
 }
 declare class StagehandEnvironmentError extends StagehandError {
@@ -1130,6 +1156,21 @@ declare class AISdkClient extends LLMClient {
     createChatCompletion<T = ChatCompletion>({ options, }: CreateChatCompletionOptions): Promise<T>;
 }
 
+/**
+ * Retrieve and build a cleaned accessibility tree for a document or specific iframe.
+ * Prunes, formats, and optionally filters by XPath, including scrollable role decoration.
+ *
+ * @deprecated This helper is an escape hatch intended for troubleshooting. Prefer
+ * extract() for supported usage and reach for this only
+ * when absolutely necessary.
+ * @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.
+ */
+declare function getAccessibilityTree(experimental: boolean, stagehandPage: StagehandPage, logger: (log: LogLine) => void, selector?: string, targetFrame?: Frame): Promise<TreeResult>;
+
 declare class Stagehand {
     private stagehandPage;
     private stagehandContext;
@@ -1195,9 +1236,9 @@ declare class Stagehand {
      * @returns An agent instance with execute() method
      */
     agent(options?: AgentConfig): {
-        execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
+        execute: (instructionOrOptions: string | AgentExecuteOptions$1) => Promise<AgentResult$1>;
         setScreenshotCollector?: (collector: unknown) => void;
     };
 }
 
-export { AISdkClient, type ActOptions, type ActResult, type ActToolResult, type ActionExecutionResult, type AgentAction, type AgentClientOptions, type AgentConfig, type AgentExecuteOptions, type AgentExecuteParams, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentOptions, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AvailableModel, AvailableModelSchema, type Browser, type BrowserContext, type BrowserResult, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, type ConstructorParams, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, type GotoOptions, HandlerNotInitializedError, type HistoryEntry, type InitResult, InvalidAISDKModelFormatError, LLMClient, type LLMResponse, LLMResponseError, LOG_LEVEL_NAMES, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelProvider, type ObserveOptions, type ObserveResult, type Page, PlaywrightCommandException, PlaywrightCommandMethodNotSupportedException, type ResponseInputItem, type ResponseItem, Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandFunctionName, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, type StagehandScreenshotOptions, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, XPathResolutionError, type ZodPathSegments, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, pageTextSchema };
+export { AISdkClient, type ActOptions, type ActResult, type ActToolResult, type ActionExecutionResult, type AgentAction$1 as AgentAction, type AgentClientOptions, type AgentConfig, type AgentExecuteOptions$1 as AgentExecuteOptions, type AgentExecuteParams, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentOptions$1 as AgentOptions, type AgentProviderType, type AgentResult$1 as AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AvailableModel, AvailableModelSchema, type Browser, type BrowserContext, type BrowserResult, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, type ConstructorParams, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, type GotoOptions, HandlerNotInitializedError, type HistoryEntry, type InitResult, InvalidAISDKModelFormatError, LLMClient, type LLMResponse, LLMResponseError, LOG_LEVEL_NAMES, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelProvider, type ObserveOptions, type ObserveResult$1 as ObserveResult, type Page, PlaywrightCommandException, PlaywrightCommandMethodNotSupportedException, type ResponseInputItem, type ResponseItem, Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandFunctionName, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, type StagehandScreenshotOptions, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type ToolUseItem, type TreeResult, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, XPathResolutionError, type ZodPathSegments, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getAccessibilityTree, pageTextSchema };