@browserbasehq/orca 3.0.9-alpha-3 → 3.0.9-alpha-4

package/dist/index.d.ts

@@ -191,6 +191,7 @@ declare class Frame implements FrameManager {
     private getMainWorldExecutionContextId;
 }
 
+type MouseButton = "left" | "right" | "middle";
 interface SetInputFilePayload {
     name: string;
     mimeType?: string;
@@ -199,7 +200,6 @@ interface SetInputFilePayload {
 }
 type SetInputFilesArgument = string | string[] | SetInputFilePayload | SetInputFilePayload[];
 
-type MouseButton = "left" | "right" | "middle";
 /**
  * Locator
  *
@@ -367,7 +367,7 @@ declare class Locator {
      */
     innerText(): Promise<string>;
     /**
-     * For API parity, returns the same locator (querySelector already returns the first match).
+     * Return a locator narrowed to the first match.
      */
     first(): Locator;
     /** Return a locator narrowed to the element at the given zero-based index. */
@@ -380,6 +380,14 @@ declare class Locator {
         nodeId: Protocol.DOM.NodeId | null;
         objectId: Protocol.Runtime.RemoteObjectId;
     }>;
+    /**
+     * Resolve all matching nodes for this locator.
+     * If the locator is narrowed via nth(), only that index is returned.
+     */
+    resolveNodesForMask(): Promise<Array<{
+        nodeId: Protocol.DOM.NodeId | null;
+        objectId: Protocol.Runtime.RemoteObjectId;
+    }>>;
     /** Compute a center point from a BoxModel content quad */
     private centerFromBoxContent;
 }
@@ -476,7 +484,8 @@ declare class FrameLocator {
 declare class LocatorDelegate {
     private readonly fl;
     private readonly sel;
-    constructor(fl: FrameLocator, sel: string);
+    private readonly nthIndex;
+    constructor(fl: FrameLocator, sel: string, nthIndex?: number);
     private real;
     click(options?: {
         button?: "left" | "right" | "middle";
@@ -497,6 +506,7 @@ declare class LocatorDelegate {
     innerText(): Promise<string>;
     count(): Promise<number>;
     first(): LocatorDelegate;
+    nth(index: number): LocatorDelegate;
 }
 
 type RemoteObject = Protocol.Runtime.RemoteObject;
@@ -1283,6 +1293,22 @@ declare const AgentConfigSchema: z$1.ZodObject<{
     }, z$1.core.$strip>, z$1.ZodString]>>;
     systemPrompt: z$1.ZodOptional<z$1.ZodString>;
     cua: z$1.ZodOptional<z$1.ZodBoolean>;
+    mode: z$1.ZodOptional<z$1.ZodEnum<{
+        cua: "cua";
+        dom: "dom";
+        hybrid: "hybrid";
+    }>>;
+    executionModel: z$1.ZodOptional<z$1.ZodUnion<readonly [z$1.ZodObject<{
+        provider: z$1.ZodOptional<z$1.ZodEnum<{
+            openai: "openai";
+            anthropic: "anthropic";
+            google: "google";
+            microsoft: "microsoft";
+        }>>;
+        modelName: z$1.ZodString;
+        apiKey: z$1.ZodOptional<z$1.ZodString>;
+        baseURL: z$1.ZodOptional<z$1.ZodString>;
+    }, z$1.core.$strip>, z$1.ZodString]>>;
 }, z$1.core.$strip>;
 /** Action taken by the agent during execution */
 declare const AgentActionSchema: z$1.ZodObject<{
@@ -1357,6 +1383,22 @@ declare const AgentExecuteRequestSchema: z$1.ZodObject<{
         }, z$1.core.$strip>, z$1.ZodString]>>;
         systemPrompt: z$1.ZodOptional<z$1.ZodString>;
         cua: z$1.ZodOptional<z$1.ZodBoolean>;
+        mode: z$1.ZodOptional<z$1.ZodEnum<{
+            cua: "cua";
+            dom: "dom";
+            hybrid: "hybrid";
+        }>>;
+        executionModel: z$1.ZodOptional<z$1.ZodUnion<readonly [z$1.ZodObject<{
+            provider: z$1.ZodOptional<z$1.ZodEnum<{
+                openai: "openai";
+                anthropic: "anthropic";
+                google: "google";
+                microsoft: "microsoft";
+            }>>;
+            modelName: z$1.ZodString;
+            apiKey: z$1.ZodOptional<z$1.ZodString>;
+            baseURL: z$1.ZodOptional<z$1.ZodString>;
+        }, z$1.core.$strip>, z$1.ZodString]>>;
     }, z$1.core.$strip>;
     executeOptions: z$1.ZodObject<{
         instruction: z$1.ZodString;
@@ -2081,6 +2123,9 @@ declare class StagehandEvalError extends StagehandError {
 declare class StagehandDomProcessError extends StagehandError {
     constructor(message: string);
 }
+declare class StagehandLocatorError extends StagehandError {
+    constructor(action: string, selector: string, message: string);
+}
 declare class StagehandClickError extends StagehandError {
     constructor(message: string, selector: string);
 }
@@ -2297,7 +2342,7 @@ declare class V3Context {
     private constructor();
     private readonly _piercerInstalled;
     private _lastPopupSignalAt;
-    private sessionKey;
+    private readonly _targetSessionListeners;
     private readonly _sessionInit;
     private pagesByTarget;
     private mainFrameToTarget;
@@ -2309,6 +2354,7 @@ declare class V3Context {
     private _pageOrder;
     private pendingCreatedTargetUrl;
     private readonly initScripts;
+    private installTargetSessionListeners;
     /**
      * Create a Context for a given CDP websocket URL and bootstrap target wiring.
      */
@@ -2359,7 +2405,6 @@ declare class V3Context {
     /**
      * Bootstrap target lifecycle:
      * - Attach to existing targets.
-     * - Attach on `Target.targetCreated` (fallback for OOPIFs).
      * - Handle auto-attach events.
      * - Clean up on detach/destroy.
      */
@@ -2680,6 +2725,7 @@ declare class Page {
     private installInitScriptOnSession;
     private applyInitScriptsToSession;
     registerInitScript(source: string): Promise<void>;
+    seedInitScript(source: string): void;
     private cursorEnabled;
     private ensureCursorScript;
     enableCursorOverlay(): Promise<void>;
@@ -2877,6 +2923,7 @@ declare class Page {
      * Supports iframe hop notation with '>>' (e.g., 'iframe#checkout >> .submit-btn').
      *
      * @param selector CSS selector to wait for (supports '>>' for iframe hops)
+     * @param options
      * @param options.state Element state to wait for: 'attached' | 'detached' | 'visible' | 'hidden' (default: 'visible')
      * @param options.timeout Maximum time to wait in milliseconds (default: 30000)
      * @param options.pierceShadow Whether to search inside shadow DOM (default: true)
@@ -3305,7 +3352,7 @@ interface AgentStreamExecuteOptions extends AgentExecuteOptionsBase {
     callbacks?: AgentStreamCallbacks;
 }
 type AgentType = "openai" | "anthropic" | "google" | "microsoft";
-declare const AVAILABLE_CUA_MODELS: readonly ["openai/computer-use-preview", "openai/computer-use-preview-2025-03-11", "anthropic/claude-3-7-sonnet-latest", "anthropic/claude-opus-4-5-20251101", "anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-20250514", "anthropic/claude-sonnet-4-5-20250929", "google/gemini-2.5-computer-use-preview-10-2025", "microsoft/fara-7b"];
+declare const AVAILABLE_CUA_MODELS: readonly ["openai/computer-use-preview", "openai/computer-use-preview-2025-03-11", "anthropic/claude-3-7-sonnet-latest", "anthropic/claude-opus-4-5-20251101", "anthropic/claude-opus-4-6", "anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-20250514", "anthropic/claude-sonnet-4-5-20250929", "google/gemini-2.5-computer-use-preview-10-2025", "google/gemini-3-flash-preview", "google/gemini-3-pro-preview", "microsoft/fara-7b"];
 type AvailableCuaModel = (typeof AVAILABLE_CUA_MODELS)[number];
 interface AgentExecutionOptions<TOptions extends AgentExecuteOptions = AgentExecuteOptions> {
     options: TOptions;
@@ -3558,10 +3605,12 @@ interface FillFormVisionToolResult {
     error?: string;
     screenshotBase64?: string;
 }
-interface ScrollVisionToolResult {
+interface ScrollToolResult {
     success: boolean;
     message: string;
     scrolledPixels: number;
+}
+interface ScrollVisionToolResult extends ScrollToolResult {
     screenshotBase64?: string;
 }
 interface WaitToolResult {
@@ -3978,13 +4027,10 @@ declare const actTool: (v3: V3, executionModel?: string) => ai.Tool<{
 }, {
     success: boolean;
     action: string;
-    playwrightArguments: Action;
-    error?: undefined;
+    playwrightArguments?: Action;
 } | {
     success: boolean;
     error: any;
-    action?: undefined;
-    playwrightArguments?: undefined;
 }>;
 
 declare const screenshotTool: (v3: V3) => ai.Tool<Record<string, never>, {
@@ -4026,11 +4072,7 @@ declare const fillFormTool: (v3: V3, executionModel?: string) => ai.Tool<{
 declare const scrollTool: (v3: V3) => ai.Tool<{
     direction: "up" | "down";
     percentage?: number;
-}, {
-    success: boolean;
-    message: string;
-    scrolledPixels: number;
-}>;
+}, ScrollToolResult>;
 /**
  * Scroll tool for hybrid mode (grounding models).
  * Supports optional coordinates for scrolling within nested scrollable elements.
@@ -4318,4 +4360,4 @@ interface ServerAgentCacheHandle {
 }
 declare function __internalCreateInMemoryAgentCacheHandle(stagehand: V3): ServerAgentCacheHandle;
 
-export { type AISDKCustomProvider, type AISDKProvider, AISdkClient, AVAILABLE_CUA_MODELS, type ActOptions, type ActResult, ActTimeoutError, type Action, type ActionExecutionResult, AgentAbortError, type AgentAction, type AgentCallbacks, type AgentConfig, type AgentContext, type AgentExecuteCallbacks, type AgentExecuteOptions, type AgentExecuteOptionsBase, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentModelConfig, AgentProvider, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentState, type AgentStreamCallbacks, type AgentStreamExecuteOptions, type AgentStreamResult, type AgentToolCall, type AgentToolMode, type AgentToolResult, type AgentToolTypesMap, type AgentTools, type AgentType, type AgentUITools, AnnotatedScreenshotText, type AnthropicClientOptions, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AnyPage, api as Api, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClickToolResult, type ClientOptions, type ComputerCallItem, ConnectionTimeoutError, type ConsoleListener, ConsoleMessage, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, CuaModelRequiredError, CustomOpenAIClient, type DragAndDropToolResult, ElementNotVisibleError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, ExtractTimeoutError, type FillFormField, type FillFormVisionToolResult, type FunctionCallItem, type GoogleServiceAccountCredentials, type GoogleVertexProviderSettings, HandlerNotInitializedError, type HistoryEntry, type InferStagehandSchema, InvalidAISDKModelFormatError, type JsonSchema, type JsonSchemaDocument, type JsonSchemaProperty, LLMClient, type LLMParsedResponse, type LLMResponse, LLMResponseError, type LLMTool, type LLMUsage, LOG_LEVEL_NAMES, type LoadState, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelOutputContentItem, type ModelProvider, type NonStreamingAgentInstance, type ObserveOptions, ObserveTimeoutError, type OpenAIClientOptions, Page, PageNotFoundError, type PageSnapshotOptions, Response$1 as Response, ResponseBodyError, type ResponseInputItem, type ResponseItem, ResponseParseError, type SafetyCheck, type SafetyConfirmationHandler, type SafetyConfirmationResponse, type ScrollVisionToolResult, type ServerAgentCacheHandle, type SnapshotResult, V3 as Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandClosedError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, StagehandSnapshotError, type StagehandZodObject, type StagehandZodSchema, type StreamingAgentInstance, StreamingCallbacksInNonStreamingModeError, TimeoutError, type ToolUseItem, type TypeToolResult, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, type WaitToolResult, XPathResolutionError, ZodSchemaValidationError, __internalCreateInMemoryAgentCacheHandle, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, isZod3Schema, isZod4Schema, jsonSchemaToZod, loadApiKeyFromEnv, localBrowserLaunchOptionsSchema, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, toJsonSchema, transformSchema, trimTrailingTextNode, validateZodSchema };
+export { type AISDKCustomProvider, type AISDKProvider, AISdkClient, AVAILABLE_CUA_MODELS, type ActOptions, type ActResult, ActTimeoutError, type Action, type ActionExecutionResult, AgentAbortError, type AgentAction, type AgentCallbacks, type AgentConfig, type AgentContext, type AgentExecuteCallbacks, type AgentExecuteOptions, type AgentExecuteOptionsBase, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentModelConfig, AgentProvider, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentState, type AgentStreamCallbacks, type AgentStreamExecuteOptions, type AgentStreamResult, type AgentToolCall, type AgentToolMode, type AgentToolResult, type AgentToolTypesMap, type AgentTools, type AgentType, type AgentUITools, AnnotatedScreenshotText, type AnthropicClientOptions, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AnyPage, api as Api, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClickToolResult, type ClientOptions, type ComputerCallItem, ConnectionTimeoutError, type ConsoleListener, ConsoleMessage, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, CuaModelRequiredError, CustomOpenAIClient, type DragAndDropToolResult, ElementNotVisibleError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, ExtractTimeoutError, type FillFormField, type FillFormVisionToolResult, type FunctionCallItem, type GoogleServiceAccountCredentials, type GoogleVertexProviderSettings, HandlerNotInitializedError, type HistoryEntry, type InferStagehandSchema, InvalidAISDKModelFormatError, type JsonSchema, type JsonSchemaDocument, type JsonSchemaProperty, LLMClient, type LLMParsedResponse, type LLMResponse, LLMResponseError, type LLMTool, type LLMUsage, LOG_LEVEL_NAMES, type LoadState, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelOutputContentItem, type ModelProvider, type NonStreamingAgentInstance, type ObserveOptions, ObserveTimeoutError, type OpenAIClientOptions, Page, PageNotFoundError, type PageSnapshotOptions, Response$1 as Response, ResponseBodyError, type ResponseInputItem, type ResponseItem, ResponseParseError, type SafetyCheck, type SafetyConfirmationHandler, type SafetyConfirmationResponse, type ScrollToolResult, type ScrollVisionToolResult, type ServerAgentCacheHandle, type SnapshotResult, V3 as Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandClosedError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, StagehandLocatorError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, StagehandSnapshotError, type StagehandZodObject, type StagehandZodSchema, type StreamingAgentInstance, StreamingCallbacksInNonStreamingModeError, TimeoutError, type ToolUseItem, type TypeToolResult, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, type WaitToolResult, XPathResolutionError, ZodSchemaValidationError, __internalCreateInMemoryAgentCacheHandle, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, isZod3Schema, isZod4Schema, jsonSchemaToZod, loadApiKeyFromEnv, localBrowserLaunchOptionsSchema, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, toJsonSchema, transformSchema, trimTrailingTextNode, validateZodSchema };