@browserbasehq/stagehand 3.0.7-alpha-5e337135056e0c4be59099b1919c2df741b27fea → 3.0.7-alpha-4d71162beb119635b69b17637564a2bbd0e373e7

package/dist/index.d.ts

@@ -6,7 +6,8 @@ import { GoogleVertexProviderSettings as GoogleVertexProviderSettings$1 } from '
 import { LanguageModelV2 } from '@ai-sdk/provider';
 import { ClientOptions as ClientOptions$1 } from 'openai';
 import { Client, ClientOptions as ClientOptions$3 } from '@modelcontextprotocol/sdk/client/index.js';
-import { ToolSet, ModelMessage, PrepareStepFunction, GenerateTextOnStepFinishCallback, StreamTextOnStepFinishCallback, StreamTextOnErrorCallback, StreamTextOnChunkCallback, StreamTextOnFinishCallback, StepResult, StreamTextResult, wrapLanguageModel, generateObject, generateText, streamText, streamObject, experimental_generateImage, embed, embedMany, experimental_transcribe, experimental_generateSpeech } from 'ai';
+import * as ai from 'ai';
+import { ToolSet, ModelMessage, PrepareStepFunction, GenerateTextOnStepFinishCallback, StreamTextOnStepFinishCallback, StreamTextOnErrorCallback, StreamTextOnChunkCallback, StreamTextOnFinishCallback, StepResult, StreamTextResult, wrapLanguageModel, generateObject, generateText, streamText, streamObject, experimental_generateImage, embed, embedMany, experimental_transcribe, experimental_generateSpeech, InferUITools } from 'ai';
 export { ModelMessage } from 'ai';
 import { Page as Page$1 } from 'playwright-core';
 export { Page as PlaywrightPage } from 'playwright-core';
@@ -1582,7 +1583,7 @@ declare class Page {
     private keyDown;
     /** Release a pressed key */
     private keyUp;
-    /** Normalize modifier key names to match CDP expectations */
+    /** Normalize key names to match CDP expectations */
     private normalizeModifierKey;
     /**
      * Get the map of named keys with their properties
@@ -1929,6 +1930,12 @@ type AgentProviderType = AgentType;
 type AgentModelConfig<TModelName extends string = string> = {
     modelName: TModelName;
 } & Record<string, unknown>;
+/**
+ * Agent tool mode determines which set of tools are available to the agent.
+ * - 'dom': Uses DOM-based tools (act, fillForm) - better for structured page interactions
+ * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, etc.) - better for visual/screenshot-based interactions
+ */
+type AgentToolMode = "dom" | "hybrid";
 type AgentConfig = {
     /**
      * Custom system prompt to provide to the agent. Overrides the default system prompt.
@@ -1962,6 +1969,13 @@ type AgentConfig = {
      * When false (default), execute() returns AgentResult after completion.
      */
     stream?: boolean;
+    /**
+     * Tool mode for the agent. Determines which set of tools are available.
+     * - 'dom' (default): Uses DOM-based tools (act, fillForm) for structured interactions
+     * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, clickAndHold, fillFormVision)
+     *             for visual/screenshot-based interactions
+     */
+    mode?: AgentToolMode;
 };
 /**
  * Agent instance returned when stream: true is set in AgentConfig.
@@ -2197,6 +2211,10 @@ declare class V3 {
     get browserbaseSessionID(): string | undefined;
     get browserbaseSessionURL(): string | undefined;
     get browserbaseDebugURL(): string | undefined;
+    /**
+     * Returns true if the browser is running on Browserbase.
+     */
+    get isBrowserbase(): boolean;
     private _onCdpClosed;
     readonly experimental: boolean;
     readonly logInferenceToFile: boolean;
@@ -2355,6 +2373,314 @@ declare class AgentProvider {
     static getAgentProvider(modelName: string): AgentProviderType;
 }
 
+declare const gotoTool: (v3: V3) => ai.Tool<{
+    url: string;
+}, {
+    success: boolean;
+    url: string;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: any;
+    url?: undefined;
+}>;
+
+declare const actTool: (v3: V3, executionModel?: string) => ai.Tool<{
+    action: string;
+}, {
+    success: boolean;
+    action: string;
+    playwrightArguments: Action;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: any;
+    action?: undefined;
+    playwrightArguments?: undefined;
+}>;
+
+declare const screenshotTool: (v3: V3) => ai.Tool<Record<string, never>, {
+    base64: string;
+    timestamp: number;
+    pageUrl: string;
+}>;
+
+declare const waitTool: (v3: V3) => ai.Tool<{
+    timeMs: number;
+}, {
+    success: boolean;
+    waited: number;
+}>;
+
+declare const navBackTool: (v3: V3) => ai.Tool<{
+    reasoningText: string;
+}, {
+    success: boolean;
+}>;
+
+declare const closeTool: () => ai.Tool<{
+    reasoning: string;
+    taskComplete: boolean;
+}, {
+    success: boolean;
+    reasoning: string;
+    taskComplete: boolean;
+}>;
+
+declare const ariaTreeTool: (v3: V3) => ai.Tool<Record<string, never>, {
+    content: string;
+    pageUrl: string;
+}>;
+
+declare const fillFormTool: (v3: V3, executionModel?: string) => ai.Tool<{
+    fields: {
+        action: string;
+        value: string;
+    }[];
+}, {
+    success: boolean;
+    actions: unknown[];
+    playwrightArguments: Action[];
+}>;
+
+/**
+ * Simple scroll tool for DOM mode (non-grounding models).
+ * No coordinates - scrolls from viewport center.
+ */
+declare const scrollTool: (v3: V3) => ai.Tool<{
+    direction: "up" | "down";
+    percentage?: number;
+}, {
+    success: boolean;
+    message: string;
+    scrolledPixels: number;
+}>;
+/**
+ * Scroll tool for hybrid mode (grounding models).
+ * Supports optional coordinates for scrolling within nested scrollable elements.
+ */
+declare const scrollVisionTool: (v3: V3, provider?: string) => ai.Tool<{
+    direction: "up" | "down";
+    coordinates?: number[];
+    percentage?: number;
+}, {
+    success: boolean;
+    message: string;
+    scrolledPixels: number;
+}>;
+
+declare const extractTool: (v3: V3, executionModel?: string, logger?: (message: LogLine) => void) => ai.Tool<{
+    instruction: string;
+    schema?: string;
+}, {
+    success: boolean;
+    result: any;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: any;
+    result?: undefined;
+}>;
+
+declare const clickTool: (v3: V3, provider?: string) => ai.Tool<{
+    describe: string;
+    coordinates: number[];
+}, {
+    success: boolean;
+    describe: string;
+    coordinates: number[];
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string;
+    describe?: undefined;
+    coordinates?: undefined;
+}>;
+
+declare const typeTool: (v3: V3, provider?: string) => ai.Tool<{
+    describe: string;
+    text: string;
+    coordinates: number[];
+}, {
+    success: boolean;
+    describe: string;
+    text: string;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string;
+    describe?: undefined;
+    text?: undefined;
+}>;
+
+declare const dragAndDropTool: (v3: V3, provider?: string) => ai.Tool<{
+    describe: string;
+    startCoordinates: number[];
+    endCoordinates: number[];
+}, {
+    success: boolean;
+    describe: string;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string;
+    describe?: undefined;
+}>;
+
+declare const clickAndHoldTool: (v3: V3, provider?: string) => ai.Tool<{
+    describe: string;
+    duration: number;
+    coordinates: number[];
+}, {
+    success: boolean;
+    describe: string;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string;
+    describe?: undefined;
+}>;
+
+declare const keysTool: (v3: V3) => 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;
+}>;
+
+declare const fillFormVisionTool: (v3: V3, provider?: string) => ai.Tool<{
+    fields: {
+        action: string;
+        value: string;
+        coordinates: {
+            x: number;
+            y: number;
+        };
+    }[];
+}, {
+    success: boolean;
+    playwrightArguments: {
+        coordinates: {
+            x: number;
+            y: number;
+        };
+        action: string;
+        value: string;
+    }[];
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string;
+    playwrightArguments?: undefined;
+}>;
+
+declare const thinkTool: () => ai.Tool<{
+    reasoning: string;
+}, {
+    acknowledged: boolean;
+    message: string;
+}>;
+
+interface BraveSearchResult {
+    title: string;
+    url: string;
+    description?: string;
+}
+declare const searchTool: (v3: V3) => ai.Tool<{
+    query: string;
+}, {
+    timestamp: number;
+    data?: {
+        results: BraveSearchResult[];
+    };
+    error?: string;
+}>;
+
+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;
+}
+declare function createAgentTools(v3: V3, options?: V3AgentToolOptions): ToolSet;
+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.
+ */
+type AgentToolTypesMap = {
+    act: ReturnType<typeof actTool>;
+    ariaTree: ReturnType<typeof ariaTreeTool>;
+    click: ReturnType<typeof clickTool>;
+    clickAndHold: ReturnType<typeof clickAndHoldTool>;
+    close: ReturnType<typeof closeTool>;
+    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.
+ */
+type AgentUITools = InferUITools<AgentToolTypesMap>;
+/**
+ * Union type for all possible agent tool calls.
+ * Provides type-safe access to tool call arguments.
+ */
+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.
+ */
+type AgentToolResult = {
+    [K in keyof AgentToolTypesMap]: {
+        toolName: K;
+        toolCallId: string;
+        result: AgentUITools[K]["output"];
+    };
+}[keyof AgentToolTypesMap];
+
 declare function validateZodSchema(schema: StagehandZodSchema, data: unknown): boolean;
 /**
  * Detects if the code is running in the Bun runtime environment.
@@ -2446,4 +2772,4 @@ declare class V3Evaluator {
     private _evaluateWithMultipleScreenshots;
 }
 
-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 AgentType, AnnotatedScreenshotText, type AnthropicClientOptions, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AnyPage, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, ConnectionTimeoutError, type ConsoleListener, ConsoleMessage, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, CuaModelRequiredError, ElementNotVisibleError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, ExtractTimeoutError, 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 ModelProvider, type NonStreamingAgentInstance, type ObserveOptions, ObserveTimeoutError, type OpenAIClientOptions, Page, PageNotFoundError, Response$1 as Response, ResponseBodyError, type ResponseInputItem, type ResponseItem, ResponseParseError, 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, type StagehandZodObject, type StagehandZodSchema, type StreamingAgentInstance, StreamingCallbacksInNonStreamingModeError, TimeoutError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, XPathResolutionError, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, isZod3Schema, isZod4Schema, jsonSchemaToZod, loadApiKeyFromEnv, 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, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, ConnectionTimeoutError, type ConsoleListener, ConsoleMessage, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, CuaModelRequiredError, ElementNotVisibleError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, ExtractTimeoutError, 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 ModelProvider, type NonStreamingAgentInstance, type ObserveOptions, ObserveTimeoutError, type OpenAIClientOptions, Page, PageNotFoundError, Response$1 as Response, ResponseBodyError, type ResponseInputItem, type ResponseItem, ResponseParseError, 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, type StagehandZodObject, type StagehandZodSchema, type StreamingAgentInstance, StreamingCallbacksInNonStreamingModeError, TimeoutError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, XPathResolutionError, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, isZod3Schema, isZod4Schema, jsonSchemaToZod, loadApiKeyFromEnv, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, toJsonSchema, transformSchema, trimTrailingTextNode, validateZodSchema };