@browserbasehq/orca 3.6.0-gemini-cua → 3.7.1-preview.0

package/dist/esm/lib/v3/types/private/agent.js

@@ -7,5 +7,6 @@ export const HYBRID_CAPABLE_MODEL_PATTERNS = [
     "claude",
     "gpt-5.4",
     "gpt-5.5",
+    "gpt-5.6",
 ];
 //# sourceMappingURL=agent.js.map

package/dist/esm/lib/v3/types/private/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/agent.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,UAAU;IACV,QAAQ;IACR,SAAS;IACT,SAAS;CACD,CAAC","sourcesContent":["export interface ActionMappingOptions {\n  toolCallName: string;\n  toolResult: unknown;\n  args: Record<string, unknown>;\n  reasoning?: string;\n}\n\n/**\n * Model name substrings that indicate hybrid mode compatibility.\n * Used for auto-routing when the user doesn't specify a mode.\n */\nexport const HYBRID_CAPABLE_MODEL_PATTERNS = [\n  \"gemini-3\",\n  \"claude\",\n  \"gpt-5.4\",\n  \"gpt-5.5\",\n] as const;\n"]}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/agent.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,UAAU;IACV,QAAQ;IACR,SAAS;IACT,SAAS;IACT,SAAS;CACD,CAAC","sourcesContent":["export interface ActionMappingOptions {\n  toolCallName: string;\n  toolResult: unknown;\n  args: Record<string, unknown>;\n  reasoning?: string;\n}\n\n/**\n * Model name substrings that indicate hybrid mode compatibility.\n * Used for auto-routing when the user doesn't specify a mode.\n */\nexport const HYBRID_CAPABLE_MODEL_PATTERNS = [\n  \"gemini-3\",\n  \"claude\",\n  \"gpt-5.4\",\n  \"gpt-5.5\",\n  \"gpt-5.6\",\n] as const;\n"]}

package/dist/esm/lib/v3/types/public/agent.d.ts

@@ -10,6 +10,15 @@ import { Page as PlaywrightPage } from "playwright-core";
 import { Page as PuppeteerPage } from "puppeteer-core";
 import { Page as PatchrightPage } from "patchright-core";
 import { Page } from "../../understudy/page.js";
+/**
+ * Result of a screenshot provider: the base64-encoded image bytes plus an
+ * explicit media type. Declaring the media type at the capture boundary lets
+ * every CUA client pass it through instead of hardcoding or inferring it.
+ */
+export interface ScreenshotProviderResult {
+    base64: string;
+    mediaType: "image/png" | "image/jpeg";
+}
 /**
  * A variable value can be a simple primitive or a rich object with an optional description.
  * This unified type is shared across `act`, `agent.execute`, and other methods.
@@ -402,7 +411,7 @@ export interface AgentStreamExecuteOptions extends AgentExecuteOptionsBase {
     callbacks?: AgentStreamCallbacks;
 }
 export type AgentType = "openai" | "anthropic" | "google" | "microsoft" | "bedrock" | "vertex" | "azure";
-export declare const AVAILABLE_CUA_MODELS: readonly ["openai/gpt-5.4", "openai/gpt-5.4-mini", "openai/gpt-5.5", "openai/computer-use-preview", "openai/computer-use-preview-2025-03-11", "anthropic/claude-opus-4-5-20251101", "anthropic/claude-opus-4-6", "anthropic/claude-opus-4-8", "anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5", "anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-20250514", "anthropic/claude-sonnet-4-5-20250929", "anthropic/claude-fable-5", "google/gemini-2.5-computer-use-preview-10-2025", "google/gemini-3-flash-preview", "google/gemini-3.5-flash", "google/gemini-3-pro-preview", "microsoft/fara-7b"];
+export declare const AVAILABLE_CUA_MODELS: readonly ["openai/gpt-5.4", "openai/gpt-5.4-mini", "openai/gpt-5.5", "openai/gpt-5.6-terra", "openai/gpt-5.6-luna", "openai/gpt-5.6-sol", "openai/computer-use-preview", "openai/computer-use-preview-2025-03-11", "anthropic/claude-opus-4-5-20251101", "anthropic/claude-opus-4-6", "anthropic/claude-opus-4-8", "anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5", "anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-20250514", "anthropic/claude-sonnet-4-5-20250929", "anthropic/claude-fable-5", "google/gemini-2.5-computer-use-preview-10-2025", "google/gemini-3-flash-preview", "google/gemini-3.5-flash", "google/gemini-3-pro-preview", "microsoft/fara-7b"];
 export type AvailableCuaModel = (typeof AVAILABLE_CUA_MODELS)[number];
 export interface AgentExecutionOptions<TOptions extends AgentExecuteOptions = AgentExecuteOptions> {
     options: TOptions;

package/dist/esm/lib/v3/types/public/agent.js

@@ -2,6 +2,9 @@ export const AVAILABLE_CUA_MODELS = [
     "openai/gpt-5.4",
     "openai/gpt-5.4-mini",
     "openai/gpt-5.5",
+    "openai/gpt-5.6-terra",
+    "openai/gpt-5.6-luna",
+    "openai/gpt-5.6-sol",
     "openai/computer-use-preview",
     "openai/computer-use-preview-2025-03-11",
     "anthropic/claude-opus-4-5-20251101",

package/dist/esm/lib/v3/types/public/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/agent.ts"],"names":[],"mappings":"AAycA,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,gBAAgB;IAChB,qBAAqB;IACrB,gBAAgB;IAChB,6BAA6B;IAC7B,wCAAwC;IACxC,oCAAoC;IACpC,2BAA2B;IAC3B,2BAA2B;IAC3B,6BAA6B;IAC7B,4BAA4B;IAC5B,qCAAqC;IACrC,oCAAoC;IACpC,sCAAsC;IACtC,0BAA0B;IAC1B,gDAAgD;IAChD,+BAA+B;IAC/B,yBAAyB;IACzB,6BAA6B;IAC7B,mBAAmB;CACX,CAAC","sourcesContent":["import type { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport {\n  ToolSet,\n  ModelMessage,\n  wrapLanguageModel,\n  StreamTextResult,\n  StepResult,\n  PrepareStepFunction,\n  GenerateTextOnStepFinishCallback,\n  StreamTextOnStepFinishCallback,\n  StreamTextOnErrorCallback,\n  StreamTextOnChunkCallback,\n  StreamTextOnFinishCallback,\n} from \"ai\";\nimport { LogLine } from \"./logs.js\";\nimport { ClientOptions } from \"./model.js\";\nimport { StagehandZodObject } from \"../../zodCompat.js\";\nimport type { AgentEvidenceCallback } from \"./agentEvidenceEvents.js\";\n\n// Re-export ModelMessage for consumers who want to use it for conversation continuation\nexport type { ModelMessage } from \"ai\";\n\n// Re-export Tool type for consumers who want to define custom tools\nexport type { Tool } from \"ai\";\nimport { Page as PlaywrightPage } from \"playwright-core\";\nimport { Page as PuppeteerPage } from \"puppeteer-core\";\nimport { Page as PatchrightPage } from \"patchright-core\";\nimport { Page } from \"../../understudy/page.js\";\n\n// =============================================================================\n// Variable Types\n// =============================================================================\n\n/**\n * A variable value can be a simple primitive or a rich object with an optional description.\n * This unified type is shared across `act`, `agent.execute`, and other methods.\n *\n * @example Simple (backward-compatible):\n * ```typescript\n * variables: { username: \"john@example.com\" }\n * ```\n *\n * @example Rich with description (useful for agents):\n * ```typescript\n * variables: {\n *   username: { value: \"john@example.com\", description: \"The login email\" }\n * }\n * ```\n */\nexport type VariableValue =\n  | string\n  | number\n  | boolean\n  | { value: string | number | boolean; description?: string };\n\n/**\n * A collection of named variables for use in act, agent, and other methods.\n */\nexport type Variables = Record<string, VariableValue>;\n\nexport interface AgentContext {\n  options: AgentExecuteOptionsBase;\n  maxSteps: number;\n  systemPrompt: string;\n  allTools: ToolSet;\n  messages: ModelMessage[];\n  wrappedModel: ReturnType<typeof wrapLanguageModel>;\n  initialPageUrl: string;\n}\n\nexport interface AgentState {\n  collectedReasoning: string[];\n  actions: AgentAction[];\n  finalMessage: string;\n  completed: boolean;\n  currentPageUrl: string;\n}\n\nexport interface AgentAction {\n  type: string;\n  reasoning?: string;\n  taskCompleted?: boolean;\n  action?: string;\n  // Tool-specific fields\n  timeMs?: number; // wait tool\n  pageText?: string; // ariaTree tool\n  pageUrl?: string; // ariaTree tool\n  instruction?: string; // various tools\n  [key: string]: unknown;\n}\n\nexport interface AgentResult {\n  success: boolean;\n  message: string;\n  actions: AgentAction[];\n  completed: boolean;\n  metadata?: Record<string, unknown>;\n  usage?: {\n    input_tokens: number;\n    output_tokens: number;\n    reasoning_tokens?: number;\n    cached_input_tokens?: number;\n    inference_time_ms: number;\n  };\n  /**\n   * The conversation messages from this execution.\n   * Pass these to a subsequent execute() call via the `messages` option to continue the conversation.\n   * @experimental\n   */\n  messages?: ModelMessage[];\n  /**\n   * Custom output data extracted based on the `output` schema provided in execute options.\n   * Only populated if an `output` schema was provided.\n   * @experimental\n   */\n  output?: Record<string, unknown>;\n}\n\nexport type AgentStreamResult = StreamTextResult<ToolSet, never> & {\n  result: Promise<AgentResult>;\n};\n\n/**\n * Base callbacks shared between execute (non-streaming) and streaming modes.\n */\nexport interface AgentCallbacks {\n  /**\n   * Optional function called before each step to modify settings.\n   * You can change the model, tool choices, active tools, system prompt,\n   * and input messages for each step.\n   */\n  prepareStep?: PrepareStepFunction<ToolSet>;\n  /**\n   * Callback called when each step (LLM call) is finished.\n   * This is called for intermediate steps as well as the final step.\n   */\n  onStepFinish?:\n    | GenerateTextOnStepFinishCallback<ToolSet>\n    | StreamTextOnStepFinishCallback<ToolSet>;\n  /**\n   * Callback called when Stagehand captures agent-run evidence such as\n   * screenshots, completed tool/action steps, or post-action observations.\n   */\n  onEvidence?: AgentEvidenceCallback;\n}\n\n/**\n * Error message type for streaming-only callbacks used in non-streaming mode.\n * This provides a clear error message when users try to use streaming callbacks without stream: true.\n */\ntype StreamingCallbackNotAvailable =\n  \"This callback requires 'stream: true' in AgentConfig. Set stream: true to use streaming callbacks like onChunk, onFinish, onError, and onAbort.\";\n\n/**\n * Error message for safety confirmation callback misuse.\n * Safety confirmations are only available for non-streaming CUA agent executions.\n */\ntype SafetyConfirmationCallbackNotAvailable =\n  \"Safety confirmation callbacks are only available via non-streaming AgentExecuteOptions.callbacks when using mode: 'cua'.\";\n\n/**\n * Callbacks specific to the non-streaming execute method.\n */\nexport interface AgentExecuteCallbacks extends AgentCallbacks {\n  /**\n   * Callback called when each step (LLM call) is finished.\n   */\n  onStepFinish?: GenerateTextOnStepFinishCallback<ToolSet>;\n  /**\n   * Callback for handling safety confirmation requests from CUA providers.\n   * Only available when running an agent configured with mode: \"cua\".\n   */\n  onSafetyConfirmation?: SafetyConfirmationHandler;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onChunk:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onChunk: async (chunk) => console.log(chunk) }\n   * });\n   * ```\n   */\n  onChunk?: StreamingCallbackNotAvailable;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onFinish:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onFinish: (event) => console.log(\"Done!\", event) }\n   * });\n   * ```\n   */\n  onFinish?: StreamingCallbackNotAvailable;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onError:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onError: ({ error }) => console.error(error) }\n   * });\n   * ```\n   */\n  onError?: StreamingCallbackNotAvailable;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onAbort:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onAbort: (event) => console.log(\"Aborted\", event.steps) }\n   * });\n   * ```\n   */\n  onAbort?: StreamingCallbackNotAvailable;\n}\n\n/**\n * Callbacks specific to the streaming mode.\n */\nexport interface AgentStreamCallbacks extends AgentCallbacks {\n  /**\n   * Callback called when each step (LLM call) is finished during streaming.\n   */\n  onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;\n  /**\n   * Callback called when an error occurs during streaming.\n   * Use this to log errors or handle error states.\n   */\n  onError?: StreamTextOnErrorCallback;\n  /**\n   * Callback called for each chunk of the stream.\n   * Stream processing will pause until the callback promise resolves.\n   */\n  onChunk?: StreamTextOnChunkCallback<ToolSet>;\n  /**\n   * Callback called when the stream finishes.\n   */\n  onFinish?: StreamTextOnFinishCallback<ToolSet>;\n  /**\n   * Callback called when the stream is aborted.\n   */\n  onAbort?: (event: {\n    steps: Array<StepResult<ToolSet>>;\n  }) => PromiseLike<void> | void;\n  /**\n   * NOT AVAILABLE in streaming mode.\n   * Safety confirmations currently require non-streaming execute() on CUA agents.\n   */\n  onSafetyConfirmation?: SafetyConfirmationCallbackNotAvailable;\n}\n\n/**\n * Base options for agent execution (without callbacks).\n */\nexport interface AgentExecuteOptionsBase {\n  instruction: string;\n  maxSteps?: number;\n  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;\n  highlightCursor?: boolean;\n  /**\n   * Previous conversation messages to continue from.\n   * Pass the `messages` from a previous AgentResult to continue that conversation.\n   * @experimental\n   */\n  messages?: ModelMessage[];\n  /**\n   * An AbortSignal that can be used to cancel the agent execution.\n   * When aborted, the agent will stop and return a partial result.\n   * @experimental\n   *\n   * @example\n   * ```typescript\n   * const controller = new AbortController();\n   * setTimeout(() => controller.abort(), 30000); // 30 second timeout\n   *\n   * const result = await agent.execute({\n   *   instruction: \"...\",\n   *   signal: controller.signal\n   * });\n   * ```\n   */\n  signal?: AbortSignal;\n  /**\n   * Tools to exclude from this execution.\n   * Pass an array of tool names to prevent the agent from using those tools.\n   *\n   * **Note:** Not supported in CUA mode (`mode: \"cua\"`).\n   *\n   * **Available tools by mode:**\n   *\n   * **DOM mode (default):**\n   * - `act` - Perform semantic actions (click, type, etc.)\n   * - `fillForm` - Fill form fields using DOM selectors\n   * - `ariaTree` - Get accessibility tree of the page\n   * - `extract` - Extract structured data from page\n   * - `goto` - Navigate to a URL\n   * - `scroll` - Scroll using semantic directions (up/down/left/right)\n   * - `keys` - Press keyboard keys\n   * - `navback` - Navigate back in history\n   * - `screenshot` - Take a screenshot\n   * - `think` - Agent reasoning/planning step\n   * - `wait` - Wait for time or condition\n   * - `done` - Mark task as complete\n   * - `search` - Web search (requires useSearch: true and BROWSERBASE_API_KEY)\n   *\n   * **Hybrid mode:**\n   * - `click` - Click at specific coordinates\n   * - `type` - Type text at coordinates\n   * - `dragAndDrop` - Drag from one point to another\n   * - `clickAndHold` - Click and hold at coordinates\n   * - `fillFormVision` - Fill forms using vision/coordinates\n   * - `act` - Perform semantic actions\n   * - `ariaTree` - Get accessibility tree\n   * - `extract` - Extract data from page\n   * - `goto` - Navigate to URL\n   * - `scroll` - Scroll using coordinates\n   * - `keys` - Press keyboard keys\n   * - `navback` - Navigate back\n   * - `screenshot` - Take screenshot\n   * - `think` - Agent reasoning step\n   * - `wait` - Wait for time/condition\n   * - `done` - Mark task complete\n   * - `search` - Web search (requires useSearch: true and BROWSERBASE_API_KEY)\n   *\n   * @experimental\n   * @example\n   * ```typescript\n   * // Exclude screenshot and extract tools\n   * const result = await agent.execute({\n   *   instruction: \"Click the submit button\",\n   *   excludeTools: [\"screenshot\", \"extract\"]\n   * });\n   * ```\n   */\n  excludeTools?: string[];\n  /**\n   * A Zod schema defining custom output data to return when the task completes.\n   * The agent will populate this data in the final done tool call.\n   *\n   * @experimental\n   * @example\n   * ```typescript\n   * const result = await agent.execute({\n   *   instruction: \"Find the cheapest flight from NYC to LA\",\n   *   output: z.object({\n   *     price: z.string().describe(\"The price of the flight\"),\n   *     airline: z.string().describe(\"The airline name\"),\n   *     departureTime: z.string().describe(\"Departure time\"),\n   *   }),\n   * });\n   *\n   * console.log(result.output); // { price: \"$199\", airline: \"Delta\", departureTime: \"8:00 AM\" }\n   * ```\n   */\n  output?: StagehandZodObject;\n  /**\n   * Variables that the agent can use when filling forms or typing text.\n   * The agent will see variable names and descriptions in the system prompt,\n   * and can use them via `%variableName%` syntax in act/type/fillForm tool calls.\n   *\n   * Accepts both simple values and rich objects with descriptions (same type as `act`).\n   *\n   * **Note:** Not supported in CUA mode (`mode: \"cua\"`).\n   *\n   * @example\n   * ```typescript\n   * // Simple values\n   * variables: { username: \"john@example.com\", password: \"secret123\" }\n   *\n   * // Rich values with descriptions (helps the agent understand context)\n   * variables: {\n   *   username: { value: \"john@example.com\", description: \"The login email\" },\n   *   password: { value: \"secret123\", description: \"The login password\" },\n   * }\n   * ```\n   */\n  variables?: Variables;\n  /**\n   * Timeout in milliseconds for each agent tool call.\n   * If a tool call exceeds this duration, it will be aborted and\n   * reported back to the LLM as a timeout error so it can retry or adjust.\n   * For tools that call v3 methods (act, extract, fillForm, ariaTree), the\n   * timeout is also forwarded to the underlying v3 call for true cancellation.\n   * @default 45000 (45 seconds)\n   */\n  toolTimeout?: number;\n  /**\n   * Enable the web search tool powered by Browserbase Search API.\n   * Requires a valid Browserbase API key (BROWSERBASE_API_KEY).\n   * When set to true, the agent gains access to a `search` tool for web searches.\n   *\n   * @example\n   * ```typescript\n   * const result = await agent.execute({\n   *   instruction: \"Find the latest news about AI\",\n   *   useSearch: true,\n   * });\n   * ```\n   */\n  useSearch?: boolean;\n}\n\n/**\n * Options for non-streaming agent execution.\n * Only accepts AgentExecuteCallbacks (no streaming-specific callbacks like onChunk, onFinish).\n */\nexport interface AgentExecuteOptions extends AgentExecuteOptionsBase {\n  /**\n   * Callbacks for non-streaming agent execution.\n   * For streaming callbacks (onChunk, onFinish, onError, onAbort), use stream: true in AgentConfig.\n   */\n  callbacks?: AgentExecuteCallbacks;\n}\n\n/**\n * Options for streaming agent execution.\n * Accepts AgentStreamCallbacks including onChunk, onFinish, onError, and onAbort.\n */\nexport interface AgentStreamExecuteOptions extends AgentExecuteOptionsBase {\n  /**\n   * Callbacks for streaming agent execution.\n   * Includes streaming-specific callbacks: onChunk, onFinish, onError, onAbort.\n   */\n  callbacks?: AgentStreamCallbacks;\n}\nexport type AgentType =\n  | \"openai\"\n  | \"anthropic\"\n  | \"google\"\n  | \"microsoft\"\n  | \"bedrock\"\n  | \"vertex\"\n  | \"azure\";\n\nexport const AVAILABLE_CUA_MODELS = [\n  \"openai/gpt-5.4\",\n  \"openai/gpt-5.4-mini\",\n  \"openai/gpt-5.5\",\n  \"openai/computer-use-preview\",\n  \"openai/computer-use-preview-2025-03-11\",\n  \"anthropic/claude-opus-4-5-20251101\",\n  \"anthropic/claude-opus-4-6\",\n  \"anthropic/claude-opus-4-8\",\n  \"anthropic/claude-sonnet-4-6\",\n  \"anthropic/claude-haiku-4-5\",\n  \"anthropic/claude-haiku-4-5-20251001\",\n  \"anthropic/claude-sonnet-4-20250514\",\n  \"anthropic/claude-sonnet-4-5-20250929\",\n  \"anthropic/claude-fable-5\",\n  \"google/gemini-2.5-computer-use-preview-10-2025\",\n  \"google/gemini-3-flash-preview\",\n  \"google/gemini-3.5-flash\",\n  \"google/gemini-3-pro-preview\",\n  \"microsoft/fara-7b\",\n] as const;\nexport type AvailableCuaModel = (typeof AVAILABLE_CUA_MODELS)[number];\n\nexport interface AgentExecutionOptions<\n  TOptions extends AgentExecuteOptions = AgentExecuteOptions,\n> {\n  options: TOptions;\n  logger: (message: LogLine) => void;\n  retries?: number;\n}\n\nexport interface AgentHandlerOptions {\n  modelName: string;\n  clientOptions?: ClientOptions;\n  userProvidedInstructions?: string;\n  experimental?: boolean;\n}\n\nexport interface ActionExecutionResult {\n  success: boolean;\n  error?: string;\n  data?: unknown;\n}\n\n/**\n * Represents a safety check that requires user confirmation before proceeding.\n * These are issued by CUA providers (OpenAI, Google) when the agent attempts\n * potentially risky actions.\n */\nexport interface SafetyCheck {\n  /** Unique identifier for this safety check */\n  id: string;\n  /** Code identifying the type of safety concern */\n  code: string;\n  /** Human-readable description of the safety concern */\n  message: string;\n}\n\n/**\n * Response from the user for a safety confirmation request.\n */\nexport interface SafetyConfirmationResponse {\n  /** Whether the user acknowledged/approved the safety checks */\n  acknowledged: boolean;\n}\n\n/**\n * Callback for handling safety confirmation requests.\n * Called when the CUA provider issues safety checks that require user confirmation.\n * The callback should return a promise that resolves when the user has made a decision.\n *\n * @param safetyChecks - Array of safety checks requiring confirmation\n * @returns Promise resolving to the user's response\n *\n * @example\n * ```typescript\n * const agent = stagehand.agent({\n *   mode: \"cua\",\n * });\n * await agent.execute({\n *   instruction: \"...\",\n *   callbacks: {\n *     onSafetyConfirmation: async (checks) => {\n *       console.log(\"Safety checks:\", checks);\n *       const userApproved = await showConfirmationDialog(checks);\n *       return { acknowledged: userApproved };\n *     },\n *   },\n * });\n * ```\n */\nexport type SafetyConfirmationHandler = (\n  safetyChecks: SafetyCheck[],\n) => Promise<SafetyConfirmationResponse>;\n\n// Anthropic types:\n\nexport interface ToolUseItem extends ResponseItem {\n  type: \"tool_use\";\n  id: string; // This is the correct property name from Anthropic's API\n  name: string; // Name of the tool being used\n  input: Record<string, unknown>;\n}\n\nexport interface AnthropicMessage {\n  role: string;\n  content: string | Array<AnthropicContentBlock>;\n}\n\nexport interface AnthropicContentBlock {\n  type: string;\n  [key: string]: unknown;\n}\n\nexport interface AnthropicTextBlock extends AnthropicContentBlock {\n  type: \"text\";\n  text: string;\n}\n\nexport interface AnthropicToolResult {\n  type: \"tool_result\";\n  tool_use_id: string;\n  content: string | Array<AnthropicContentBlock>;\n}\n\n// OpenAI types:\n\nexport interface ResponseItem {\n  type: string;\n  id: string;\n  [key: string]: unknown;\n}\n\nexport interface ComputerCallItem extends ResponseItem {\n  type: \"computer_call\";\n  call_id: string;\n  action?: {\n    type: string;\n    [key: string]: unknown;\n  };\n  actions?: Array<{\n    type: string;\n    [key: string]: unknown;\n  }>;\n  pending_safety_checks?: Array<{\n    id: string;\n    code: string;\n    message: string;\n  }>;\n}\n\nexport interface FunctionCallItem extends ResponseItem {\n  type: \"function_call\";\n  call_id: string;\n  name: string;\n  arguments: string;\n}\n\nexport type ResponseInputItem =\n  | { role: string; content: string }\n  | {\n      type: \"computer_call_output\";\n      call_id: string;\n      output:\n        | {\n            type: \"input_image\" | \"computer_screenshot\";\n            image_url: string;\n            detail?: \"original\" | \"high\" | \"low\";\n            current_url?: string;\n            error?: string;\n            [key: string]: unknown;\n          }\n        | string;\n      acknowledged_safety_checks?: Array<{\n        id: string;\n        code: string;\n        message: string;\n      }>;\n    }\n  | {\n      type: \"function_call_output\";\n      call_id: string;\n      output: string;\n    };\n\nexport interface AgentInstance {\n  execute: (\n    instructionOrOptions: string | AgentExecuteOptions,\n  ) => Promise<AgentResult>;\n}\n\nexport type AgentProviderType = AgentType;\n\nexport type AgentModelConfig<TModelName extends string = string> = {\n  modelName: TModelName;\n} & Record<string, unknown>;\n\n/**\n * Agent tool mode determines which set of tools are available to the agent.\n * - 'dom': Uses DOM-based tools (act, fillForm) - better for structured page interactions\n * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, etc.) - better for visual/screenshot-based interactions\n * - 'cua': Uses Computer Use Agent (CUA) providers like Anthropic Claude or Google Gemini for screenshot-based automation\n */\nexport type AgentToolMode = \"dom\" | \"hybrid\" | \"cua\";\n\nexport type AgentConfig = {\n  /**\n   * Custom system prompt to provide to the agent. Overrides the default system prompt.\n   */\n  systemPrompt?: string;\n  /**\n   * MCP integrations - Array of Client objects\n   */\n  integrations?: (Client | string)[];\n  /**\n   * Tools passed to the agent client\n   */\n  tools?: ToolSet;\n  /**\n   * @deprecated Use `mode: \"cua\"` instead. This option will be removed in a future version.\n   * Enables Computer Use Agent (CUA) mode.\n   */\n  cua?: boolean;\n  /**\n   * The model to use for agent functionality\n   */\n  model?: string | AgentModelConfig<string>;\n  /**\n   * The model to use for tool execution (observe/act calls within agent tools).\n   * If not specified, inherits from the main model configuration.\n   * Format: \"provider/model\" (e.g., \"openai/gpt-4o-mini\", \"google/gemini-2.0-flash-exp\")\n   */\n  executionModel?: string | AgentModelConfig<string>;\n  /**\n   * Enable streaming mode for the agent.\n   * When true, execute() returns AgentStreamResult with textStream for incremental output.\n   * When false (default), execute() returns AgentResult after completion.\n   */\n  stream?: boolean;\n  /**\n   * Tool mode for the agent. Determines which set of tools are available.\n   * - 'dom' (default): Uses DOM-based tools (act, fillForm) for structured interactions\n   * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, clickAndHold, fillFormVision)\n   *             for visual/screenshot-based interactions\n   * - 'cua': Uses Computer Use Agent (CUA) providers for screenshot-based automation\n   */\n  mode?: AgentToolMode;\n};\n\n/**\n * Agent instance returned when stream: true is set in AgentConfig.\n * execute() returns a streaming result that can be consumed incrementally.\n * Accepts AgentStreamExecuteOptions with streaming-specific callbacks.\n */\nexport interface StreamingAgentInstance {\n  execute: (\n    instructionOrOptions: string | AgentStreamExecuteOptions,\n  ) => Promise<AgentStreamResult>;\n}\n\n/**\n * Agent instance returned when stream is false or not set in AgentConfig.\n * execute() returns a result after the agent completes.\n * Accepts AgentExecuteOptions with non-streaming callbacks only.\n */\nexport interface NonStreamingAgentInstance {\n  execute: (\n    instructionOrOptions: string | AgentExecuteOptions,\n  ) => Promise<AgentResult>;\n}\n\n// =============================================================================\n// Vision Action Tool Result Types\n// =============================================================================\n\n/**\n * Content item type for toModelOutput return values.\n * Used in tool definitions to return text and/or media to the model.\n */\nexport type ModelOutputContentItem =\n  | { type: \"text\"; text: string }\n  | { type: \"media\"; mediaType: string; data: string };\n\nexport interface ClickToolResult {\n  success: boolean;\n  describe?: string;\n  coordinates?: number[];\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface TypeToolResult {\n  success: boolean;\n  describe?: string;\n  text?: string;\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface DragAndDropToolResult {\n  success: boolean;\n  describe?: string;\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface FillFormField {\n  action: string;\n  value: string;\n  coordinates: { x: number; y: number };\n}\n\nexport interface FillFormVisionToolResult {\n  success: boolean;\n  playwrightArguments?: FillFormField[];\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface ScrollToolResult {\n  success: boolean;\n  message: string;\n  scrolledPixels: number;\n  error?: string;\n}\n\nexport interface ScrollVisionToolResult extends ScrollToolResult {\n  screenshotBase64?: string;\n}\n\nexport interface WaitToolResult {\n  success: boolean;\n  waited: number;\n  screenshotBase64?: string;\n  error?: string;\n}\n"]}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/agent.ts"],"names":[],"mappings":"AAmdA,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,gBAAgB;IAChB,qBAAqB;IACrB,gBAAgB;IAChB,sBAAsB;IACtB,qBAAqB;IACrB,oBAAoB;IACpB,6BAA6B;IAC7B,wCAAwC;IACxC,oCAAoC;IACpC,2BAA2B;IAC3B,2BAA2B;IAC3B,6BAA6B;IAC7B,4BAA4B;IAC5B,qCAAqC;IACrC,oCAAoC;IACpC,sCAAsC;IACtC,0BAA0B;IAC1B,gDAAgD;IAChD,+BAA+B;IAC/B,yBAAyB;IACzB,6BAA6B;IAC7B,mBAAmB;CACX,CAAC","sourcesContent":["import type { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport {\n  ToolSet,\n  ModelMessage,\n  wrapLanguageModel,\n  StreamTextResult,\n  StepResult,\n  PrepareStepFunction,\n  GenerateTextOnStepFinishCallback,\n  StreamTextOnStepFinishCallback,\n  StreamTextOnErrorCallback,\n  StreamTextOnChunkCallback,\n  StreamTextOnFinishCallback,\n} from \"ai\";\nimport { LogLine } from \"./logs.js\";\nimport { ClientOptions } from \"./model.js\";\nimport { StagehandZodObject } from \"../../zodCompat.js\";\nimport type { AgentEvidenceCallback } from \"./agentEvidenceEvents.js\";\n\n// Re-export ModelMessage for consumers who want to use it for conversation continuation\nexport type { ModelMessage } from \"ai\";\n\n// Re-export Tool type for consumers who want to define custom tools\nexport type { Tool } from \"ai\";\nimport { Page as PlaywrightPage } from \"playwright-core\";\nimport { Page as PuppeteerPage } from \"puppeteer-core\";\nimport { Page as PatchrightPage } from \"patchright-core\";\nimport { Page } from \"../../understudy/page.js\";\n\n/**\n * Result of a screenshot provider: the base64-encoded image bytes plus an\n * explicit media type. Declaring the media type at the capture boundary lets\n * every CUA client pass it through instead of hardcoding or inferring it.\n */\nexport interface ScreenshotProviderResult {\n  base64: string;\n  mediaType: \"image/png\" | \"image/jpeg\";\n}\n\n// =============================================================================\n// Variable Types\n// =============================================================================\n\n/**\n * A variable value can be a simple primitive or a rich object with an optional description.\n * This unified type is shared across `act`, `agent.execute`, and other methods.\n *\n * @example Simple (backward-compatible):\n * ```typescript\n * variables: { username: \"john@example.com\" }\n * ```\n *\n * @example Rich with description (useful for agents):\n * ```typescript\n * variables: {\n *   username: { value: \"john@example.com\", description: \"The login email\" }\n * }\n * ```\n */\nexport type VariableValue =\n  | string\n  | number\n  | boolean\n  | { value: string | number | boolean; description?: string };\n\n/**\n * A collection of named variables for use in act, agent, and other methods.\n */\nexport type Variables = Record<string, VariableValue>;\n\nexport interface AgentContext {\n  options: AgentExecuteOptionsBase;\n  maxSteps: number;\n  systemPrompt: string;\n  allTools: ToolSet;\n  messages: ModelMessage[];\n  wrappedModel: ReturnType<typeof wrapLanguageModel>;\n  initialPageUrl: string;\n}\n\nexport interface AgentState {\n  collectedReasoning: string[];\n  actions: AgentAction[];\n  finalMessage: string;\n  completed: boolean;\n  currentPageUrl: string;\n}\n\nexport interface AgentAction {\n  type: string;\n  reasoning?: string;\n  taskCompleted?: boolean;\n  action?: string;\n  // Tool-specific fields\n  timeMs?: number; // wait tool\n  pageText?: string; // ariaTree tool\n  pageUrl?: string; // ariaTree tool\n  instruction?: string; // various tools\n  [key: string]: unknown;\n}\n\nexport interface AgentResult {\n  success: boolean;\n  message: string;\n  actions: AgentAction[];\n  completed: boolean;\n  metadata?: Record<string, unknown>;\n  usage?: {\n    input_tokens: number;\n    output_tokens: number;\n    reasoning_tokens?: number;\n    cached_input_tokens?: number;\n    inference_time_ms: number;\n  };\n  /**\n   * The conversation messages from this execution.\n   * Pass these to a subsequent execute() call via the `messages` option to continue the conversation.\n   * @experimental\n   */\n  messages?: ModelMessage[];\n  /**\n   * Custom output data extracted based on the `output` schema provided in execute options.\n   * Only populated if an `output` schema was provided.\n   * @experimental\n   */\n  output?: Record<string, unknown>;\n}\n\nexport type AgentStreamResult = StreamTextResult<ToolSet, never> & {\n  result: Promise<AgentResult>;\n};\n\n/**\n * Base callbacks shared between execute (non-streaming) and streaming modes.\n */\nexport interface AgentCallbacks {\n  /**\n   * Optional function called before each step to modify settings.\n   * You can change the model, tool choices, active tools, system prompt,\n   * and input messages for each step.\n   */\n  prepareStep?: PrepareStepFunction<ToolSet>;\n  /**\n   * Callback called when each step (LLM call) is finished.\n   * This is called for intermediate steps as well as the final step.\n   */\n  onStepFinish?:\n    | GenerateTextOnStepFinishCallback<ToolSet>\n    | StreamTextOnStepFinishCallback<ToolSet>;\n  /**\n   * Callback called when Stagehand captures agent-run evidence such as\n   * screenshots, completed tool/action steps, or post-action observations.\n   */\n  onEvidence?: AgentEvidenceCallback;\n}\n\n/**\n * Error message type for streaming-only callbacks used in non-streaming mode.\n * This provides a clear error message when users try to use streaming callbacks without stream: true.\n */\ntype StreamingCallbackNotAvailable =\n  \"This callback requires 'stream: true' in AgentConfig. Set stream: true to use streaming callbacks like onChunk, onFinish, onError, and onAbort.\";\n\n/**\n * Error message for safety confirmation callback misuse.\n * Safety confirmations are only available for non-streaming CUA agent executions.\n */\ntype SafetyConfirmationCallbackNotAvailable =\n  \"Safety confirmation callbacks are only available via non-streaming AgentExecuteOptions.callbacks when using mode: 'cua'.\";\n\n/**\n * Callbacks specific to the non-streaming execute method.\n */\nexport interface AgentExecuteCallbacks extends AgentCallbacks {\n  /**\n   * Callback called when each step (LLM call) is finished.\n   */\n  onStepFinish?: GenerateTextOnStepFinishCallback<ToolSet>;\n  /**\n   * Callback for handling safety confirmation requests from CUA providers.\n   * Only available when running an agent configured with mode: \"cua\".\n   */\n  onSafetyConfirmation?: SafetyConfirmationHandler;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onChunk:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onChunk: async (chunk) => console.log(chunk) }\n   * });\n   * ```\n   */\n  onChunk?: StreamingCallbackNotAvailable;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onFinish:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onFinish: (event) => console.log(\"Done!\", event) }\n   * });\n   * ```\n   */\n  onFinish?: StreamingCallbackNotAvailable;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onError:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onError: ({ error }) => console.error(error) }\n   * });\n   * ```\n   */\n  onError?: StreamingCallbackNotAvailable;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onAbort:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onAbort: (event) => console.log(\"Aborted\", event.steps) }\n   * });\n   * ```\n   */\n  onAbort?: StreamingCallbackNotAvailable;\n}\n\n/**\n * Callbacks specific to the streaming mode.\n */\nexport interface AgentStreamCallbacks extends AgentCallbacks {\n  /**\n   * Callback called when each step (LLM call) is finished during streaming.\n   */\n  onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;\n  /**\n   * Callback called when an error occurs during streaming.\n   * Use this to log errors or handle error states.\n   */\n  onError?: StreamTextOnErrorCallback;\n  /**\n   * Callback called for each chunk of the stream.\n   * Stream processing will pause until the callback promise resolves.\n   */\n  onChunk?: StreamTextOnChunkCallback<ToolSet>;\n  /**\n   * Callback called when the stream finishes.\n   */\n  onFinish?: StreamTextOnFinishCallback<ToolSet>;\n  /**\n   * Callback called when the stream is aborted.\n   */\n  onAbort?: (event: {\n    steps: Array<StepResult<ToolSet>>;\n  }) => PromiseLike<void> | void;\n  /**\n   * NOT AVAILABLE in streaming mode.\n   * Safety confirmations currently require non-streaming execute() on CUA agents.\n   */\n  onSafetyConfirmation?: SafetyConfirmationCallbackNotAvailable;\n}\n\n/**\n * Base options for agent execution (without callbacks).\n */\nexport interface AgentExecuteOptionsBase {\n  instruction: string;\n  maxSteps?: number;\n  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;\n  highlightCursor?: boolean;\n  /**\n   * Previous conversation messages to continue from.\n   * Pass the `messages` from a previous AgentResult to continue that conversation.\n   * @experimental\n   */\n  messages?: ModelMessage[];\n  /**\n   * An AbortSignal that can be used to cancel the agent execution.\n   * When aborted, the agent will stop and return a partial result.\n   * @experimental\n   *\n   * @example\n   * ```typescript\n   * const controller = new AbortController();\n   * setTimeout(() => controller.abort(), 30000); // 30 second timeout\n   *\n   * const result = await agent.execute({\n   *   instruction: \"...\",\n   *   signal: controller.signal\n   * });\n   * ```\n   */\n  signal?: AbortSignal;\n  /**\n   * Tools to exclude from this execution.\n   * Pass an array of tool names to prevent the agent from using those tools.\n   *\n   * **Note:** Not supported in CUA mode (`mode: \"cua\"`).\n   *\n   * **Available tools by mode:**\n   *\n   * **DOM mode (default):**\n   * - `act` - Perform semantic actions (click, type, etc.)\n   * - `fillForm` - Fill form fields using DOM selectors\n   * - `ariaTree` - Get accessibility tree of the page\n   * - `extract` - Extract structured data from page\n   * - `goto` - Navigate to a URL\n   * - `scroll` - Scroll using semantic directions (up/down/left/right)\n   * - `keys` - Press keyboard keys\n   * - `navback` - Navigate back in history\n   * - `screenshot` - Take a screenshot\n   * - `think` - Agent reasoning/planning step\n   * - `wait` - Wait for time or condition\n   * - `done` - Mark task as complete\n   * - `search` - Web search (requires useSearch: true and BROWSERBASE_API_KEY)\n   *\n   * **Hybrid mode:**\n   * - `click` - Click at specific coordinates\n   * - `type` - Type text at coordinates\n   * - `dragAndDrop` - Drag from one point to another\n   * - `clickAndHold` - Click and hold at coordinates\n   * - `fillFormVision` - Fill forms using vision/coordinates\n   * - `act` - Perform semantic actions\n   * - `ariaTree` - Get accessibility tree\n   * - `extract` - Extract data from page\n   * - `goto` - Navigate to URL\n   * - `scroll` - Scroll using coordinates\n   * - `keys` - Press keyboard keys\n   * - `navback` - Navigate back\n   * - `screenshot` - Take screenshot\n   * - `think` - Agent reasoning step\n   * - `wait` - Wait for time/condition\n   * - `done` - Mark task complete\n   * - `search` - Web search (requires useSearch: true and BROWSERBASE_API_KEY)\n   *\n   * @experimental\n   * @example\n   * ```typescript\n   * // Exclude screenshot and extract tools\n   * const result = await agent.execute({\n   *   instruction: \"Click the submit button\",\n   *   excludeTools: [\"screenshot\", \"extract\"]\n   * });\n   * ```\n   */\n  excludeTools?: string[];\n  /**\n   * A Zod schema defining custom output data to return when the task completes.\n   * The agent will populate this data in the final done tool call.\n   *\n   * @experimental\n   * @example\n   * ```typescript\n   * const result = await agent.execute({\n   *   instruction: \"Find the cheapest flight from NYC to LA\",\n   *   output: z.object({\n   *     price: z.string().describe(\"The price of the flight\"),\n   *     airline: z.string().describe(\"The airline name\"),\n   *     departureTime: z.string().describe(\"Departure time\"),\n   *   }),\n   * });\n   *\n   * console.log(result.output); // { price: \"$199\", airline: \"Delta\", departureTime: \"8:00 AM\" }\n   * ```\n   */\n  output?: StagehandZodObject;\n  /**\n   * Variables that the agent can use when filling forms or typing text.\n   * The agent will see variable names and descriptions in the system prompt,\n   * and can use them via `%variableName%` syntax in act/type/fillForm tool calls.\n   *\n   * Accepts both simple values and rich objects with descriptions (same type as `act`).\n   *\n   * **Note:** Not supported in CUA mode (`mode: \"cua\"`).\n   *\n   * @example\n   * ```typescript\n   * // Simple values\n   * variables: { username: \"john@example.com\", password: \"secret123\" }\n   *\n   * // Rich values with descriptions (helps the agent understand context)\n   * variables: {\n   *   username: { value: \"john@example.com\", description: \"The login email\" },\n   *   password: { value: \"secret123\", description: \"The login password\" },\n   * }\n   * ```\n   */\n  variables?: Variables;\n  /**\n   * Timeout in milliseconds for each agent tool call.\n   * If a tool call exceeds this duration, it will be aborted and\n   * reported back to the LLM as a timeout error so it can retry or adjust.\n   * For tools that call v3 methods (act, extract, fillForm, ariaTree), the\n   * timeout is also forwarded to the underlying v3 call for true cancellation.\n   * @default 45000 (45 seconds)\n   */\n  toolTimeout?: number;\n  /**\n   * Enable the web search tool powered by Browserbase Search API.\n   * Requires a valid Browserbase API key (BROWSERBASE_API_KEY).\n   * When set to true, the agent gains access to a `search` tool for web searches.\n   *\n   * @example\n   * ```typescript\n   * const result = await agent.execute({\n   *   instruction: \"Find the latest news about AI\",\n   *   useSearch: true,\n   * });\n   * ```\n   */\n  useSearch?: boolean;\n}\n\n/**\n * Options for non-streaming agent execution.\n * Only accepts AgentExecuteCallbacks (no streaming-specific callbacks like onChunk, onFinish).\n */\nexport interface AgentExecuteOptions extends AgentExecuteOptionsBase {\n  /**\n   * Callbacks for non-streaming agent execution.\n   * For streaming callbacks (onChunk, onFinish, onError, onAbort), use stream: true in AgentConfig.\n   */\n  callbacks?: AgentExecuteCallbacks;\n}\n\n/**\n * Options for streaming agent execution.\n * Accepts AgentStreamCallbacks including onChunk, onFinish, onError, and onAbort.\n */\nexport interface AgentStreamExecuteOptions extends AgentExecuteOptionsBase {\n  /**\n   * Callbacks for streaming agent execution.\n   * Includes streaming-specific callbacks: onChunk, onFinish, onError, onAbort.\n   */\n  callbacks?: AgentStreamCallbacks;\n}\nexport type AgentType =\n  | \"openai\"\n  | \"anthropic\"\n  | \"google\"\n  | \"microsoft\"\n  | \"bedrock\"\n  | \"vertex\"\n  | \"azure\";\n\nexport const AVAILABLE_CUA_MODELS = [\n  \"openai/gpt-5.4\",\n  \"openai/gpt-5.4-mini\",\n  \"openai/gpt-5.5\",\n  \"openai/gpt-5.6-terra\",\n  \"openai/gpt-5.6-luna\",\n  \"openai/gpt-5.6-sol\",\n  \"openai/computer-use-preview\",\n  \"openai/computer-use-preview-2025-03-11\",\n  \"anthropic/claude-opus-4-5-20251101\",\n  \"anthropic/claude-opus-4-6\",\n  \"anthropic/claude-opus-4-8\",\n  \"anthropic/claude-sonnet-4-6\",\n  \"anthropic/claude-haiku-4-5\",\n  \"anthropic/claude-haiku-4-5-20251001\",\n  \"anthropic/claude-sonnet-4-20250514\",\n  \"anthropic/claude-sonnet-4-5-20250929\",\n  \"anthropic/claude-fable-5\",\n  \"google/gemini-2.5-computer-use-preview-10-2025\",\n  \"google/gemini-3-flash-preview\",\n  \"google/gemini-3.5-flash\",\n  \"google/gemini-3-pro-preview\",\n  \"microsoft/fara-7b\",\n] as const;\nexport type AvailableCuaModel = (typeof AVAILABLE_CUA_MODELS)[number];\n\nexport interface AgentExecutionOptions<\n  TOptions extends AgentExecuteOptions = AgentExecuteOptions,\n> {\n  options: TOptions;\n  logger: (message: LogLine) => void;\n  retries?: number;\n}\n\nexport interface AgentHandlerOptions {\n  modelName: string;\n  clientOptions?: ClientOptions;\n  userProvidedInstructions?: string;\n  experimental?: boolean;\n}\n\nexport interface ActionExecutionResult {\n  success: boolean;\n  error?: string;\n  data?: unknown;\n}\n\n/**\n * Represents a safety check that requires user confirmation before proceeding.\n * These are issued by CUA providers (OpenAI, Google) when the agent attempts\n * potentially risky actions.\n */\nexport interface SafetyCheck {\n  /** Unique identifier for this safety check */\n  id: string;\n  /** Code identifying the type of safety concern */\n  code: string;\n  /** Human-readable description of the safety concern */\n  message: string;\n}\n\n/**\n * Response from the user for a safety confirmation request.\n */\nexport interface SafetyConfirmationResponse {\n  /** Whether the user acknowledged/approved the safety checks */\n  acknowledged: boolean;\n}\n\n/**\n * Callback for handling safety confirmation requests.\n * Called when the CUA provider issues safety checks that require user confirmation.\n * The callback should return a promise that resolves when the user has made a decision.\n *\n * @param safetyChecks - Array of safety checks requiring confirmation\n * @returns Promise resolving to the user's response\n *\n * @example\n * ```typescript\n * const agent = stagehand.agent({\n *   mode: \"cua\",\n * });\n * await agent.execute({\n *   instruction: \"...\",\n *   callbacks: {\n *     onSafetyConfirmation: async (checks) => {\n *       console.log(\"Safety checks:\", checks);\n *       const userApproved = await showConfirmationDialog(checks);\n *       return { acknowledged: userApproved };\n *     },\n *   },\n * });\n * ```\n */\nexport type SafetyConfirmationHandler = (\n  safetyChecks: SafetyCheck[],\n) => Promise<SafetyConfirmationResponse>;\n\n// Anthropic types:\n\nexport interface ToolUseItem extends ResponseItem {\n  type: \"tool_use\";\n  id: string; // This is the correct property name from Anthropic's API\n  name: string; // Name of the tool being used\n  input: Record<string, unknown>;\n}\n\nexport interface AnthropicMessage {\n  role: string;\n  content: string | Array<AnthropicContentBlock>;\n}\n\nexport interface AnthropicContentBlock {\n  type: string;\n  [key: string]: unknown;\n}\n\nexport interface AnthropicTextBlock extends AnthropicContentBlock {\n  type: \"text\";\n  text: string;\n}\n\nexport interface AnthropicToolResult {\n  type: \"tool_result\";\n  tool_use_id: string;\n  content: string | Array<AnthropicContentBlock>;\n}\n\n// OpenAI types:\n\nexport interface ResponseItem {\n  type: string;\n  id: string;\n  [key: string]: unknown;\n}\n\nexport interface ComputerCallItem extends ResponseItem {\n  type: \"computer_call\";\n  call_id: string;\n  action?: {\n    type: string;\n    [key: string]: unknown;\n  };\n  actions?: Array<{\n    type: string;\n    [key: string]: unknown;\n  }>;\n  pending_safety_checks?: Array<{\n    id: string;\n    code: string;\n    message: string;\n  }>;\n}\n\nexport interface FunctionCallItem extends ResponseItem {\n  type: \"function_call\";\n  call_id: string;\n  name: string;\n  arguments: string;\n}\n\nexport type ResponseInputItem =\n  | { role: string; content: string }\n  | {\n      type: \"computer_call_output\";\n      call_id: string;\n      output:\n        | {\n            type: \"input_image\" | \"computer_screenshot\";\n            image_url: string;\n            detail?: \"original\" | \"high\" | \"low\";\n            current_url?: string;\n            error?: string;\n            [key: string]: unknown;\n          }\n        | string;\n      acknowledged_safety_checks?: Array<{\n        id: string;\n        code: string;\n        message: string;\n      }>;\n    }\n  | {\n      type: \"function_call_output\";\n      call_id: string;\n      output: string;\n    };\n\nexport interface AgentInstance {\n  execute: (\n    instructionOrOptions: string | AgentExecuteOptions,\n  ) => Promise<AgentResult>;\n}\n\nexport type AgentProviderType = AgentType;\n\nexport type AgentModelConfig<TModelName extends string = string> = {\n  modelName: TModelName;\n} & Record<string, unknown>;\n\n/**\n * Agent tool mode determines which set of tools are available to the agent.\n * - 'dom': Uses DOM-based tools (act, fillForm) - better for structured page interactions\n * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, etc.) - better for visual/screenshot-based interactions\n * - 'cua': Uses Computer Use Agent (CUA) providers like Anthropic Claude or Google Gemini for screenshot-based automation\n */\nexport type AgentToolMode = \"dom\" | \"hybrid\" | \"cua\";\n\nexport type AgentConfig = {\n  /**\n   * Custom system prompt to provide to the agent. Overrides the default system prompt.\n   */\n  systemPrompt?: string;\n  /**\n   * MCP integrations - Array of Client objects\n   */\n  integrations?: (Client | string)[];\n  /**\n   * Tools passed to the agent client\n   */\n  tools?: ToolSet;\n  /**\n   * @deprecated Use `mode: \"cua\"` instead. This option will be removed in a future version.\n   * Enables Computer Use Agent (CUA) mode.\n   */\n  cua?: boolean;\n  /**\n   * The model to use for agent functionality\n   */\n  model?: string | AgentModelConfig<string>;\n  /**\n   * The model to use for tool execution (observe/act calls within agent tools).\n   * If not specified, inherits from the main model configuration.\n   * Format: \"provider/model\" (e.g., \"openai/gpt-4o-mini\", \"google/gemini-2.0-flash-exp\")\n   */\n  executionModel?: string | AgentModelConfig<string>;\n  /**\n   * Enable streaming mode for the agent.\n   * When true, execute() returns AgentStreamResult with textStream for incremental output.\n   * When false (default), execute() returns AgentResult after completion.\n   */\n  stream?: boolean;\n  /**\n   * Tool mode for the agent. Determines which set of tools are available.\n   * - 'dom' (default): Uses DOM-based tools (act, fillForm) for structured interactions\n   * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, clickAndHold, fillFormVision)\n   *             for visual/screenshot-based interactions\n   * - 'cua': Uses Computer Use Agent (CUA) providers for screenshot-based automation\n   */\n  mode?: AgentToolMode;\n};\n\n/**\n * Agent instance returned when stream: true is set in AgentConfig.\n * execute() returns a streaming result that can be consumed incrementally.\n * Accepts AgentStreamExecuteOptions with streaming-specific callbacks.\n */\nexport interface StreamingAgentInstance {\n  execute: (\n    instructionOrOptions: string | AgentStreamExecuteOptions,\n  ) => Promise<AgentStreamResult>;\n}\n\n/**\n * Agent instance returned when stream is false or not set in AgentConfig.\n * execute() returns a result after the agent completes.\n * Accepts AgentExecuteOptions with non-streaming callbacks only.\n */\nexport interface NonStreamingAgentInstance {\n  execute: (\n    instructionOrOptions: string | AgentExecuteOptions,\n  ) => Promise<AgentResult>;\n}\n\n// =============================================================================\n// Vision Action Tool Result Types\n// =============================================================================\n\n/**\n * Content item type for toModelOutput return values.\n * Used in tool definitions to return text and/or media to the model.\n */\nexport type ModelOutputContentItem =\n  | { type: \"text\"; text: string }\n  | { type: \"media\"; mediaType: string; data: string };\n\nexport interface ClickToolResult {\n  success: boolean;\n  describe?: string;\n  coordinates?: number[];\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface TypeToolResult {\n  success: boolean;\n  describe?: string;\n  text?: string;\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface DragAndDropToolResult {\n  success: boolean;\n  describe?: string;\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface FillFormField {\n  action: string;\n  value: string;\n  coordinates: { x: number; y: number };\n}\n\nexport interface FillFormVisionToolResult {\n  success: boolean;\n  playwrightArguments?: FillFormField[];\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface ScrollToolResult {\n  success: boolean;\n  message: string;\n  scrolledPixels: number;\n  error?: string;\n}\n\nexport interface ScrollVisionToolResult extends ScrollToolResult {\n  screenshotBase64?: string;\n}\n\nexport interface WaitToolResult {\n  success: boolean;\n  waited: number;\n  screenshotBase64?: string;\n  error?: string;\n}\n"]}

package/dist/esm/lib/v3/types/public/context.d.ts

@@ -30,3 +30,10 @@ export interface ClearCookieOptions {
     domain?: string | RegExp;
     path?: string | RegExp;
 }
+/** Context-wide network domain policy. */
+export interface DomainPolicy {
+    /** Domain-only allow patterns, e.g. "example.com" or "*.example.com". */
+    allowedDomains?: string[];
+    /** Domain-only block patterns, e.g. "example.com" or "*.example.com". */
+    blockedDomains?: string[];
+}

package/dist/esm/lib/v3/types/public/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/context.ts"],"names":[],"mappings":"","sourcesContent":["/** A cookie as returned by the browser. */\nexport interface Cookie {\n  name: string;\n  value: string;\n  domain: string;\n  path: string;\n  /** Unix time in seconds. -1 means session cookie. */\n  expires: number;\n  httpOnly: boolean;\n  secure: boolean;\n  sameSite: \"Strict\" | \"Lax\" | \"None\";\n}\n\n/** Parameters for setting a cookie. Provide `url` OR `domain`+`path`, not both. */\nexport interface CookieParam {\n  name: string;\n  value: string;\n  /** Convenience: if provided, domain/path/secure are derived from this URL. */\n  url?: string;\n  domain?: string;\n  path?: string;\n  /** Unix timestamp in seconds. -1 or omitted = session cookie. */\n  expires?: number;\n  httpOnly?: boolean;\n  secure?: boolean;\n  sameSite?: \"Strict\" | \"Lax\" | \"None\";\n}\n\n/** Filter options for clearing cookies selectively. */\nexport interface ClearCookieOptions {\n  name?: string | RegExp;\n  domain?: string | RegExp;\n  path?: string | RegExp;\n}\n"]}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/context.ts"],"names":[],"mappings":"","sourcesContent":["/** A cookie as returned by the browser. */\nexport interface Cookie {\n  name: string;\n  value: string;\n  domain: string;\n  path: string;\n  /** Unix time in seconds. -1 means session cookie. */\n  expires: number;\n  httpOnly: boolean;\n  secure: boolean;\n  sameSite: \"Strict\" | \"Lax\" | \"None\";\n}\n\n/** Parameters for setting a cookie. Provide `url` OR `domain`+`path`, not both. */\nexport interface CookieParam {\n  name: string;\n  value: string;\n  /** Convenience: if provided, domain/path/secure are derived from this URL. */\n  url?: string;\n  domain?: string;\n  path?: string;\n  /** Unix timestamp in seconds. -1 or omitted = session cookie. */\n  expires?: number;\n  httpOnly?: boolean;\n  secure?: boolean;\n  sameSite?: \"Strict\" | \"Lax\" | \"None\";\n}\n\n/** Filter options for clearing cookies selectively. */\nexport interface ClearCookieOptions {\n  name?: string | RegExp;\n  domain?: string | RegExp;\n  path?: string | RegExp;\n}\n\n/** Context-wide network domain policy. */\nexport interface DomainPolicy {\n  /** Domain-only allow patterns, e.g. \"example.com\" or \"*.example.com\". */\n  allowedDomains?: string[];\n\n  /** Domain-only block patterns, e.g. \"example.com\" or \"*.example.com\". */\n  blockedDomains?: string[];\n}\n"]}

package/dist/esm/lib/v3/types/public/model.d.ts

@@ -80,6 +80,7 @@ export type ModelProvider = "openai" | "anthropic" | "cerebras" | "groq" | "goog
  * - "max": Claude always thinks with no constraints
  */
 export type ThinkingEffort = "none" | "low" | "medium" | "high" | "xhigh" | "max";
+export type OpenAIEndpointFormat = "responses" | "chat";
 export type ClientOptions = (OpenAIClientOptions | AnthropicClientOptions) & {
     apiKey?: string;
     provider?: AgentProviderType;
@@ -113,6 +114,12 @@ export type ClientOptions = (OpenAIClientOptions | AnthropicClientOptions) & {
     headers?: Record<string, string>;
     /** Reasoning effort for reasoning-capable models (e.g., "none", "low", "medium", "high") */
     reasoningEffort?: string;
+    /**
+     * Wire format used against the OpenAI-compatible endpoint at `baseURL`.
+     * Defaults to the Responses API. Use `chat` for providers that expose only
+     * an OpenAI-compatible Chat Completions endpoint (e.g. Databricks).
+     */
+    openaiEndpointFormat?: OpenAIEndpointFormat;
 };
 export type ModelConfiguration = AvailableModel | (ClientOptions & {
     modelName: AvailableModel;

package/dist/esm/lib/v3/types/public/model.js.map

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/model.ts"],"names":[],"mappings":"","sourcesContent":["import type { ClientOptions as AnthropicClientOptionsBase } from \"@anthropic-ai/sdk\";\nimport type {\n  LanguageModelV2,\n  LanguageModelV2Middleware,\n} from \"@ai-sdk/provider\";\nimport type { ClientOptions as OpenAIClientOptionsBase } from \"openai\";\nimport type { AgentProviderType } from \"./agent.js\";\n\nexport type OpenAIClientOptions = Pick<\n  OpenAIClientOptionsBase,\n  \"baseURL\" | \"apiKey\"\n>;\n\nexport type AnthropicClientOptions = Pick<\n  AnthropicClientOptionsBase,\n  \"baseURL\" | \"apiKey\"\n>;\n\nexport interface GoogleServiceAccountCredentials {\n  type?: \"service_account\";\n  project_id?: string;\n  private_key_id?: string;\n  private_key: string;\n  client_email: string;\n  client_id?: string;\n  auth_uri?: string;\n  token_uri?: string;\n  auth_provider_x509_cert_url?: string;\n  client_x509_cert_url?: string;\n  universe_domain?: string;\n}\n\nexport interface GoogleServiceAccountAuth {\n  type: \"googleServiceAccount\";\n  credentials: GoogleServiceAccountCredentials;\n  scopes?: string | string[];\n  projectId?: string;\n  universeDomain?: string;\n}\n\nexport interface AzureEntraIdAuth {\n  type: \"azureEntraId\";\n  token: string;\n}\n\nexport type ModelAuth = GoogleServiceAccountAuth | AzureEntraIdAuth;\n\nexport interface VertexProviderOptions {\n  project: string;\n  location: string;\n  baseURL?: string;\n  headers?: Record<string, string>;\n}\n\nexport interface AzureProviderOptions {\n  resourceName?: string;\n  baseURL?: string;\n  apiVersion?: string;\n  useDeploymentBasedUrls?: boolean;\n  headers?: Record<string, string>;\n}\n\nexport type ModelProviderOptions =\n  | { vertex: VertexProviderOptions; azure?: never }\n  | { azure: AzureProviderOptions; vertex?: never };\n\nexport type AnthropicJsonSchemaObject = {\n  definitions?: {\n    MySchema?: {\n      properties?: Record<string, unknown>;\n      required?: string[];\n    };\n  };\n  properties?: Record<string, unknown>;\n  required?: string[];\n} & Record<string, unknown>;\n\nexport interface LLMTool {\n  type: \"function\";\n  name: string;\n  description: string;\n  parameters: Record<string, unknown>;\n}\n\nexport type AISDKProvider = (modelName: string) => LanguageModelV2;\n// Represents a function that takes options (like apiKey) and returns an AISDKProvider\nexport type AISDKCustomProvider = (options: ClientOptions) => AISDKProvider;\n\nexport type AvailableModel =\n  | \"gpt-4.1\"\n  | \"gpt-4.1-mini\"\n  | \"gpt-4.1-nano\"\n  | \"o4-mini\"\n  | \"o3\"\n  | \"o3-mini\"\n  | \"o1\"\n  | \"o1-mini\"\n  | \"gpt-4o\"\n  | \"gpt-4o-mini\"\n  | \"gpt-4o-2024-08-06\"\n  | \"gpt-4.5-preview\"\n  | \"o1-preview\"\n  | \"cerebras-llama-3.3-70b\"\n  | \"cerebras-llama-3.1-8b\"\n  | \"groq-llama-3.3-70b-versatile\"\n  | \"groq-llama-3.3-70b-specdec\"\n  | \"gemini-1.5-flash\"\n  | \"gemini-1.5-pro\"\n  | \"gemini-1.5-flash-8b\"\n  | \"gemini-2.0-flash-lite\"\n  | \"gemini-2.0-flash\"\n  | \"gemini-2.5-flash-preview-04-17\"\n  | \"gemini-2.5-pro-preview-03-25\"\n  | string;\n\nexport type ModelProvider =\n  | \"openai\"\n  | \"anthropic\"\n  | \"cerebras\"\n  | \"groq\"\n  | \"google\"\n  | \"aisdk\";\n\n/**\n * Effort levels for Claude adaptive thinking.\n * Used with Claude 4.6+ models (claude-opus-4-6, claude-sonnet-4-6).\n * - \"none\": Disable adaptive thinking entirely\n * - \"low\": Claude minimizes thinking, skips for simple tasks\n * - \"medium\": Claude uses moderate thinking, may skip for simple queries (default)\n * - \"high\": Claude always thinks with deep reasoning\n * - \"xhigh\": Deeper reasoning than \"high\" (Opus 4.7/4.8 and Fable 5 only)\n * - \"max\": Claude always thinks with no constraints\n */\nexport type ThinkingEffort =\n  | \"none\"\n  | \"low\"\n  | \"medium\"\n  | \"high\"\n  | \"xhigh\"\n  | \"max\";\n\nexport type ClientOptions = (OpenAIClientOptions | AnthropicClientOptions) & {\n  apiKey?: string;\n  provider?: AgentProviderType;\n  auth?: ModelAuth;\n  providerOptions?: ModelProviderOptions;\n  baseURL?: string;\n  /** OpenAI organization ID */\n  organization?: string;\n  /** Delay between agent actions in ms */\n  waitBetweenActions?: number;\n  /**\n   * @deprecated For Claude 4.6+ models, use `thinkingEffort` instead.\n   * Anthropic thinking budget for extended thinking (used with older Claude models like 4.5).\n   * Sets `thinking.type: \"enabled\"` with the specified `budget_tokens`.\n   */\n  thinkingBudget?: number;\n  /**\n   * Effort level for Claude adaptive thinking (Claude 4.6+ models only).\n   * Uses `thinking.type: \"adaptive\"` with `output_config.effort`.\n   * This is the recommended approach for Claude Opus 4.6 and Sonnet 4.6.\n   * @see https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking\n   */\n  thinkingEffort?: ThinkingEffort;\n  /** Environment type for CUA agents (browser, mac, windows, ubuntu) */\n  environment?: string;\n  /** Max images for Microsoft FARA agent */\n  maxImages?: number;\n  /** Temperature for model inference */\n  temperature?: number;\n  /** Custom headers sent with every request to the provider */\n  headers?: Record<string, string>;\n  /** Reasoning effort for reasoning-capable models (e.g., \"none\", \"low\", \"medium\", \"high\") */\n  reasoningEffort?: string;\n};\n\nexport type ModelConfiguration =\n  | AvailableModel\n  | (ClientOptions & {\n      modelName: AvailableModel;\n      /**\n       * Optional AI SDK middleware applied to every LanguageModelV2 created for this model.\n       * Use this to intercept LLM calls for usage tracking, logging, request transforms, etc.\n       *\n       * Only effective when running locally (direct mode). Cannot be serialized over HTTP,\n       */\n      middleware?: LanguageModelV2Middleware;\n    });\n"]}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/model.ts"],"names":[],"mappings":"","sourcesContent":["import type { ClientOptions as AnthropicClientOptionsBase } from \"@anthropic-ai/sdk\";\nimport type {\n  LanguageModelV2,\n  LanguageModelV2Middleware,\n} from \"@ai-sdk/provider\";\nimport type { ClientOptions as OpenAIClientOptionsBase } from \"openai\";\nimport type { AgentProviderType } from \"./agent.js\";\n\nexport type OpenAIClientOptions = Pick<\n  OpenAIClientOptionsBase,\n  \"baseURL\" | \"apiKey\"\n>;\n\nexport type AnthropicClientOptions = Pick<\n  AnthropicClientOptionsBase,\n  \"baseURL\" | \"apiKey\"\n>;\n\nexport interface GoogleServiceAccountCredentials {\n  type?: \"service_account\";\n  project_id?: string;\n  private_key_id?: string;\n  private_key: string;\n  client_email: string;\n  client_id?: string;\n  auth_uri?: string;\n  token_uri?: string;\n  auth_provider_x509_cert_url?: string;\n  client_x509_cert_url?: string;\n  universe_domain?: string;\n}\n\nexport interface GoogleServiceAccountAuth {\n  type: \"googleServiceAccount\";\n  credentials: GoogleServiceAccountCredentials;\n  scopes?: string | string[];\n  projectId?: string;\n  universeDomain?: string;\n}\n\nexport interface AzureEntraIdAuth {\n  type: \"azureEntraId\";\n  token: string;\n}\n\nexport type ModelAuth = GoogleServiceAccountAuth | AzureEntraIdAuth;\n\nexport interface VertexProviderOptions {\n  project: string;\n  location: string;\n  baseURL?: string;\n  headers?: Record<string, string>;\n}\n\nexport interface AzureProviderOptions {\n  resourceName?: string;\n  baseURL?: string;\n  apiVersion?: string;\n  useDeploymentBasedUrls?: boolean;\n  headers?: Record<string, string>;\n}\n\nexport type ModelProviderOptions =\n  | { vertex: VertexProviderOptions; azure?: never }\n  | { azure: AzureProviderOptions; vertex?: never };\n\nexport type AnthropicJsonSchemaObject = {\n  definitions?: {\n    MySchema?: {\n      properties?: Record<string, unknown>;\n      required?: string[];\n    };\n  };\n  properties?: Record<string, unknown>;\n  required?: string[];\n} & Record<string, unknown>;\n\nexport interface LLMTool {\n  type: \"function\";\n  name: string;\n  description: string;\n  parameters: Record<string, unknown>;\n}\n\nexport type AISDKProvider = (modelName: string) => LanguageModelV2;\n// Represents a function that takes options (like apiKey) and returns an AISDKProvider\nexport type AISDKCustomProvider = (options: ClientOptions) => AISDKProvider;\n\nexport type AvailableModel =\n  | \"gpt-4.1\"\n  | \"gpt-4.1-mini\"\n  | \"gpt-4.1-nano\"\n  | \"o4-mini\"\n  | \"o3\"\n  | \"o3-mini\"\n  | \"o1\"\n  | \"o1-mini\"\n  | \"gpt-4o\"\n  | \"gpt-4o-mini\"\n  | \"gpt-4o-2024-08-06\"\n  | \"gpt-4.5-preview\"\n  | \"o1-preview\"\n  | \"cerebras-llama-3.3-70b\"\n  | \"cerebras-llama-3.1-8b\"\n  | \"groq-llama-3.3-70b-versatile\"\n  | \"groq-llama-3.3-70b-specdec\"\n  | \"gemini-1.5-flash\"\n  | \"gemini-1.5-pro\"\n  | \"gemini-1.5-flash-8b\"\n  | \"gemini-2.0-flash-lite\"\n  | \"gemini-2.0-flash\"\n  | \"gemini-2.5-flash-preview-04-17\"\n  | \"gemini-2.5-pro-preview-03-25\"\n  | string;\n\nexport type ModelProvider =\n  | \"openai\"\n  | \"anthropic\"\n  | \"cerebras\"\n  | \"groq\"\n  | \"google\"\n  | \"aisdk\";\n\n/**\n * Effort levels for Claude adaptive thinking.\n * Used with Claude 4.6+ models (claude-opus-4-6, claude-sonnet-4-6).\n * - \"none\": Disable adaptive thinking entirely\n * - \"low\": Claude minimizes thinking, skips for simple tasks\n * - \"medium\": Claude uses moderate thinking, may skip for simple queries (default)\n * - \"high\": Claude always thinks with deep reasoning\n * - \"xhigh\": Deeper reasoning than \"high\" (Opus 4.7/4.8 and Fable 5 only)\n * - \"max\": Claude always thinks with no constraints\n */\nexport type ThinkingEffort =\n  | \"none\"\n  | \"low\"\n  | \"medium\"\n  | \"high\"\n  | \"xhigh\"\n  | \"max\";\n\nexport type OpenAIEndpointFormat = \"responses\" | \"chat\";\n\nexport type ClientOptions = (OpenAIClientOptions | AnthropicClientOptions) & {\n  apiKey?: string;\n  provider?: AgentProviderType;\n  auth?: ModelAuth;\n  providerOptions?: ModelProviderOptions;\n  baseURL?: string;\n  /** OpenAI organization ID */\n  organization?: string;\n  /** Delay between agent actions in ms */\n  waitBetweenActions?: number;\n  /**\n   * @deprecated For Claude 4.6+ models, use `thinkingEffort` instead.\n   * Anthropic thinking budget for extended thinking (used with older Claude models like 4.5).\n   * Sets `thinking.type: \"enabled\"` with the specified `budget_tokens`.\n   */\n  thinkingBudget?: number;\n  /**\n   * Effort level for Claude adaptive thinking (Claude 4.6+ models only).\n   * Uses `thinking.type: \"adaptive\"` with `output_config.effort`.\n   * This is the recommended approach for Claude Opus 4.6 and Sonnet 4.6.\n   * @see https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking\n   */\n  thinkingEffort?: ThinkingEffort;\n  /** Environment type for CUA agents (browser, mac, windows, ubuntu) */\n  environment?: string;\n  /** Max images for Microsoft FARA agent */\n  maxImages?: number;\n  /** Temperature for model inference */\n  temperature?: number;\n  /** Custom headers sent with every request to the provider */\n  headers?: Record<string, string>;\n  /** Reasoning effort for reasoning-capable models (e.g., \"none\", \"low\", \"medium\", \"high\") */\n  reasoningEffort?: string;\n  /**\n   * Wire format used against the OpenAI-compatible endpoint at `baseURL`.\n   * Defaults to the Responses API. Use `chat` for providers that expose only\n   * an OpenAI-compatible Chat Completions endpoint (e.g. Databricks).\n   */\n  openaiEndpointFormat?: OpenAIEndpointFormat;\n};\n\nexport type ModelConfiguration =\n  | AvailableModel\n  | (ClientOptions & {\n      modelName: AvailableModel;\n      /**\n       * Optional AI SDK middleware applied to every LanguageModelV2 created for this model.\n       * Use this to intercept LLM calls for usage tracking, logging, request transforms, etc.\n       *\n       * Only effective when running locally (direct mode). Cannot be serialized over HTTP,\n       */\n      middleware?: LanguageModelV2Middleware;\n    });\n"]}

package/dist/esm/lib/v3/types/public/sdkErrors.d.ts

@@ -163,6 +163,10 @@ export declare class StagehandSetExtraHTTPHeadersError extends StagehandError {
     readonly failures: string[];
     constructor(failures: string[]);
 }
+export declare class StagehandSetDomainPolicyError extends StagehandError {
+    readonly failures: string[];
+    constructor(failures: string[]);
+}
 export declare class StagehandSnapshotError extends StagehandError {
     constructor(cause?: unknown);
 }

package/dist/esm/lib/v3/types/public/sdkErrors.js

@@ -319,6 +319,13 @@ export class StagehandSetExtraHTTPHeadersError extends StagehandError {
         this.failures = failures;
     }
 }
+export class StagehandSetDomainPolicyError extends StagehandError {
+    failures;
+    constructor(failures) {
+        super(`setDomainPolicy failed for ${failures.length} session(s): ${failures.join(", ")}`);
+        this.failures = failures;
+    }
+}
 export class StagehandSnapshotError extends StagehandError {
     constructor(cause) {
         const suffix = cause instanceof Error

package/dist/esm/lib/v3/types/public/sdkErrors.js.map

@@ -1 +1 @@
-{"version":3,"file":"sdkErrors.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/sdkErrors.ts"],"names":[],"mappings":"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","sourcesContent":["import { ZodError } from \"zod\";\n// Avoid .js extension so bundlers resolve TS source\nimport { STAGEHAND_VERSION } from \"../../../version.js\";\n\nexport class StagehandError extends Error {\n  public readonly cause?: unknown;\n\n  constructor(message: string, cause?: unknown) {\n    super(message);\n    this.name = this.constructor.name;\n    if (cause !== undefined) {\n      this.cause = cause;\n    }\n  }\n}\n\nexport class StagehandDefaultError extends StagehandError {\n  constructor(error?: unknown) {\n    if (error instanceof Error || error instanceof StagehandError) {\n      super(\n        `\\nHey! We're sorry you ran into an error. \\nStagehand version: ${STAGEHAND_VERSION} \\nIf you need help, please open a Github issue or reach out to us on Discord: https://stagehand.dev/discord\\n\\nFull error:\\n${error.message}`,\n      );\n    }\n  }\n}\n\nexport class StagehandEnvironmentError extends StagehandError {\n  constructor(\n    currentEnvironment: string,\n    requiredEnvironment: string,\n    feature: string,\n  ) {\n    super(\n      `You seem to be setting the current environment to ${currentEnvironment}.` +\n        `Ensure the environment is set to ${requiredEnvironment} if you want to use ${feature}.`,\n    );\n  }\n}\n\nexport class MissingEnvironmentVariableError extends StagehandError {\n  constructor(missingEnvironmentVariable: string, feature: string) {\n    super(\n      `${missingEnvironmentVariable} is required to use ${feature}.` +\n        `Please set ${missingEnvironmentVariable} in your environment.`,\n    );\n  }\n}\n\nexport class UnsupportedModelError extends StagehandError {\n  constructor(supportedModels: string[], feature?: string) {\n    const message = feature\n      ? `${feature} requires a valid model.`\n      : `Unsupported model.`;\n\n    const guidance =\n      `\\n\\nPlease use the provider/model format (e.g., \"openai/gpt-4o\", \"anthropic/claude-sonnet-4-5\", \"google/gemini-3-flash-preview\").` +\n      `\\n\\nFor a complete list of supported models and providers, see: https://docs.stagehand.dev/v3/configuration/models#configuration-setup`;\n\n    super(`${message}${guidance}`);\n  }\n}\n\nexport class UnsupportedModelProviderError extends StagehandError {\n  constructor(supportedProviders: string[], feature?: string) {\n    super(\n      feature\n        ? `${feature} requires one of the following model providers: ${supportedProviders}`\n        : `please use one of the supported model providers: ${supportedProviders}`,\n    );\n  }\n}\n\nexport class UnsupportedAISDKModelProviderError extends StagehandError {\n  constructor(provider: string, supportedProviders: string[]) {\n    super(\n      `${provider} is not currently supported for aiSDK. please use one of the supported model providers: ${supportedProviders}`,\n    );\n  }\n}\n\nexport class StagehandUnsupportedBrowserFeatureError extends StagehandError {\n  constructor(feature: string, message: string, cause?: unknown) {\n    super(`Unsupported browser feature \"${feature}\": ${message}`, cause);\n  }\n}\n\nexport class InvalidAISDKModelFormatError extends StagehandError {\n  constructor(modelName: string) {\n    super(\n      `${modelName} does not follow correct format for specifying aiSDK models. Please define your model as 'provider/model-name'. For example: \\`model: 'openai/gpt-4o-mini'\\``,\n    );\n  }\n}\n\nexport class StagehandNotInitializedError extends StagehandError {\n  constructor(prop: string) {\n    super(\n      `You seem to be calling \\`${prop}\\` on a page in an uninitialized \\`Stagehand\\` object. ` +\n        `Ensure you are running \\`await stagehand.init()\\` on the Stagehand object before ` +\n        `referencing the \\`page\\` object.`,\n    );\n  }\n}\n\nexport class BrowserbaseSessionNotFoundError extends StagehandError {\n  constructor() {\n    super(\"No Browserbase session ID found\");\n  }\n}\n\nexport class CaptchaTimeoutError extends StagehandError {\n  constructor() {\n    super(\"Captcha timeout\");\n  }\n}\n\nexport class MissingLLMConfigurationError extends StagehandError {\n  constructor() {\n    super(\n      \"No LLM API key or LLM Client configured. An LLM API key or a custom LLM Client \" +\n        \"is required to use act, extract, or observe.\",\n    );\n  }\n}\n\nexport class HandlerNotInitializedError extends StagehandError {\n  constructor(handlerType: string) {\n    super(`${handlerType} handler not initialized`);\n  }\n}\n\nexport class StagehandInvalidArgumentError extends StagehandError {\n  constructor(message: string) {\n    super(`InvalidArgumentError: ${message}`);\n  }\n}\n\nexport class CookieValidationError extends StagehandError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n\nexport class CookieSetError extends StagehandError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n\nexport class StagehandElementNotFoundError extends StagehandError {\n  constructor(xpaths: string[]) {\n    super(`Could not find an element for the given xPath(s): ${xpaths}`);\n  }\n}\n\nexport class AgentScreenshotProviderError extends StagehandError {\n  constructor(message: string) {\n    super(`ScreenshotProviderError: ${message}`);\n  }\n}\n\nexport class StagehandMissingArgumentError extends StagehandError {\n  constructor(message: string) {\n    super(`MissingArgumentError: ${message}`);\n  }\n}\n\nexport class CreateChatCompletionResponseError extends StagehandError {\n  constructor(message: string) {\n    super(`CreateChatCompletionResponseError: ${message}`);\n  }\n}\n\nexport class StagehandEvalError extends StagehandError {\n  constructor(message: string) {\n    super(`StagehandEvalError: ${message}`);\n  }\n}\n\nexport class StagehandDomProcessError extends StagehandError {\n  constructor(message: string) {\n    super(`Error Processing Dom: ${message}`);\n  }\n}\n\nexport class StagehandLocatorError extends StagehandError {\n  constructor(action: string, selector: string, message: string) {\n    super(\n      `Error ${action} Element with selector: ${selector} Reason: ${message}`,\n    );\n  }\n}\n\nexport class StagehandClickError extends StagehandError {\n  constructor(message: string, selector: string) {\n    super(\n      `Error Clicking Element with selector: ${selector} Reason: ${message}`,\n    );\n  }\n}\n\nexport class LLMResponseError extends StagehandError {\n  constructor(primitive: string, message: string) {\n    super(`${primitive} LLM response error: ${message}`);\n  }\n}\n\nexport class StagehandIframeError extends StagehandError {\n  constructor(frameUrl: string, message: string) {\n    super(\n      `Unable to resolve frameId for iframe with URL: ${frameUrl} Full error: ${message}`,\n    );\n  }\n}\n\nexport class ContentFrameNotFoundError extends StagehandError {\n  constructor(selector: string) {\n    super(`Unable to obtain a content frame for selector: ${selector}`);\n  }\n}\n\nexport class XPathResolutionError extends StagehandError {\n  constructor(xpath: string) {\n    super(`XPath \"${xpath}\" does not resolve in the current page or frames`);\n  }\n}\n\nexport class ExperimentalApiConflictError extends StagehandError {\n  constructor() {\n    super(\n      \"`experimental` mode cannot be used together with the Stagehand API. \" +\n        \"To use experimental features, set experimental: true and disableAPI: true in the stagehand constructor. \" +\n        \"To use the Stagehand API, set experimental: false and disableAPI: false (or omit it) in the stagehand constructor.\",\n    );\n  }\n}\n\nexport class ExperimentalNotConfiguredError extends StagehandError {\n  constructor(featureName: string) {\n    super(`Feature \"${featureName}\" is an experimental feature, and cannot be configured when disableAPI: false.\n    Please set experimental: true and disableAPI: true in the stagehand constructor to use this feature.\n    If you wish to use the Stagehand API, please ensure ${featureName} is not defined in your function call,\n    and set experimental: false, disableAPI: false (or omit it) in the Stagehand constructor.`);\n  }\n}\n\nexport class CuaModelRequiredError extends StagehandError {\n  constructor(availableModels: readonly string[]) {\n    super(\n      `To use the computer use agent (CUA), please provide a CUA model in the agent constructor or stagehand config. ` +\n        `Try one of our supported CUA models: ${availableModels.join(\", \")}`,\n    );\n  }\n}\n\nexport class ZodSchemaValidationError extends Error {\n  constructor(\n    public readonly received: unknown,\n    public readonly issues: ReturnType<ZodError[\"format\"]>,\n  ) {\n    super(`Zod schema validation failed\n\n— Received —\n${JSON.stringify(received, null, 2)}\n\n— Issues —\n${JSON.stringify(issues, null, 2)}`);\n    this.name = \"ZodSchemaValidationError\";\n  }\n}\n\nexport class StagehandInitError extends StagehandError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n\nexport class MCPConnectionError extends StagehandError {\n  public readonly serverUrl: string;\n  public readonly originalError: unknown;\n\n  constructor(serverUrl: string, originalError: unknown) {\n    const errorMessage =\n      originalError instanceof Error\n        ? originalError.message\n        : String(originalError);\n\n    super(\n      `Failed to connect to MCP server at \"${serverUrl}\". ${errorMessage}. ` +\n        `Please verify the server URL is correct and the server is running.`,\n    );\n\n    this.serverUrl = serverUrl;\n    this.originalError = originalError;\n  }\n}\n\nexport class StagehandShadowRootMissingError extends StagehandError {\n  constructor(detail?: string) {\n    super(\n      `No shadow root present on the resolved host` +\n        (detail ? `: ${detail}` : \"\"),\n    );\n  }\n}\n\nexport class StagehandShadowSegmentEmptyError extends StagehandError {\n  constructor() {\n    super(`Empty selector segment after shadow-DOM hop (\"//\")`);\n  }\n}\n\nexport class StagehandShadowSegmentNotFoundError extends StagehandError {\n  constructor(segment: string, hint?: string) {\n    super(\n      `Shadow segment '${segment}' matched no element inside shadow root` +\n        (hint ? ` ${hint}` : \"\"),\n    );\n  }\n}\n\nexport class ElementNotVisibleError extends StagehandError {\n  constructor(selector: string) {\n    super(`Element not visible (no box model): ${selector}`);\n  }\n}\n\nexport class ResponseBodyError extends StagehandError {\n  constructor(message: string) {\n    super(`Failed to retrieve response body: ${message}`);\n  }\n}\n\nexport class ResponseParseError extends StagehandError {\n  constructor(message: string) {\n    super(`Failed to parse response: ${message}`);\n  }\n}\n\nexport class TimeoutError extends StagehandError {\n  constructor(operation: string, timeoutMs: number) {\n    super(`${operation} timed out after ${timeoutMs}ms`);\n  }\n}\n\nexport class ActTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"act()\", timeoutMs);\n    this.name = \"ActTimeoutError\";\n  }\n}\n\nexport class ExtractTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"extract()\", timeoutMs);\n    this.name = \"ExtractTimeoutError\";\n  }\n}\n\nexport class ObserveTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"observe()\", timeoutMs);\n    this.name = \"ObserveTimeoutError\";\n  }\n}\n\nexport class PageNotFoundError extends StagehandError {\n  constructor(identifier: string) {\n    super(`No Page found for ${identifier}`);\n  }\n}\n\nexport class ConnectionTimeoutError extends StagehandError {\n  constructor(message: string) {\n    super(`Connection timeout: ${message}`);\n  }\n}\n\nexport class StreamingCallbacksInNonStreamingModeError extends StagehandError {\n  public readonly invalidCallbacks: string[];\n\n  constructor(invalidCallbacks: string[]) {\n    super(\n      `Streaming-only callback(s) \"${invalidCallbacks.join('\", \"')}\" cannot be used in non-streaming mode. ` +\n        `Set 'stream: true' in AgentConfig to use these callbacks.`,\n    );\n    this.invalidCallbacks = invalidCallbacks;\n  }\n}\n\nexport class AgentAbortError extends StagehandError {\n  public readonly reason: string;\n\n  constructor(reason?: string) {\n    const message = reason\n      ? `Agent execution was aborted: ${reason}`\n      : \"Agent execution was aborted\";\n    super(message);\n    this.reason = reason || \"aborted\";\n  }\n}\n\nexport class StagehandClosedError extends StagehandError {\n  constructor() {\n    super(\"Stagehand session was closed\");\n  }\n}\n\nexport class CdpConnectionClosedError extends StagehandError {\n  constructor(reason: string) {\n    super(`CDP connection closed: ${reason}`);\n  }\n}\n\nexport class StagehandSetExtraHTTPHeadersError extends StagehandError {\n  public readonly failures: string[];\n\n  constructor(failures: string[]) {\n    super(\n      `setExtraHTTPHeaders failed for ${failures.length} session(s): ${failures.join(\", \")}`,\n    );\n    this.failures = failures;\n  }\n}\n\nexport class StagehandSnapshotError extends StagehandError {\n  constructor(cause?: unknown) {\n    const suffix =\n      cause instanceof Error\n        ? `: ${cause.message}`\n        : cause\n          ? `: ${String(cause)}`\n          : \"\";\n    super(`error taking snapshot${suffix}`, cause);\n  }\n}\n\nexport class UnderstudyCommandException extends StagehandError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = \"UnderstudyCommandException\";\n  }\n}\n"]}
+{"version":3,"file":"sdkErrors.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/sdkErrors.ts"],"names":[],"mappings":"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","sourcesContent":["import { ZodError } from \"zod\";\n// Avoid .js extension so bundlers resolve TS source\nimport { STAGEHAND_VERSION } from \"../../../version.js\";\n\nexport class StagehandError extends Error {\n  public readonly cause?: unknown;\n\n  constructor(message: string, cause?: unknown) {\n    super(message);\n    this.name = this.constructor.name;\n    if (cause !== undefined) {\n      this.cause = cause;\n    }\n  }\n}\n\nexport class StagehandDefaultError extends StagehandError {\n  constructor(error?: unknown) {\n    if (error instanceof Error || error instanceof StagehandError) {\n      super(\n        `\\nHey! We're sorry you ran into an error. \\nStagehand version: ${STAGEHAND_VERSION} \\nIf you need help, please open a Github issue or reach out to us on Discord: https://stagehand.dev/discord\\n\\nFull error:\\n${error.message}`,\n      );\n    }\n  }\n}\n\nexport class StagehandEnvironmentError extends StagehandError {\n  constructor(\n    currentEnvironment: string,\n    requiredEnvironment: string,\n    feature: string,\n  ) {\n    super(\n      `You seem to be setting the current environment to ${currentEnvironment}.` +\n        `Ensure the environment is set to ${requiredEnvironment} if you want to use ${feature}.`,\n    );\n  }\n}\n\nexport class MissingEnvironmentVariableError extends StagehandError {\n  constructor(missingEnvironmentVariable: string, feature: string) {\n    super(\n      `${missingEnvironmentVariable} is required to use ${feature}.` +\n        `Please set ${missingEnvironmentVariable} in your environment.`,\n    );\n  }\n}\n\nexport class UnsupportedModelError extends StagehandError {\n  constructor(supportedModels: string[], feature?: string) {\n    const message = feature\n      ? `${feature} requires a valid model.`\n      : `Unsupported model.`;\n\n    const guidance =\n      `\\n\\nPlease use the provider/model format (e.g., \"openai/gpt-4o\", \"anthropic/claude-sonnet-4-5\", \"google/gemini-3-flash-preview\").` +\n      `\\n\\nFor a complete list of supported models and providers, see: https://docs.stagehand.dev/v3/configuration/models#configuration-setup`;\n\n    super(`${message}${guidance}`);\n  }\n}\n\nexport class UnsupportedModelProviderError extends StagehandError {\n  constructor(supportedProviders: string[], feature?: string) {\n    super(\n      feature\n        ? `${feature} requires one of the following model providers: ${supportedProviders}`\n        : `please use one of the supported model providers: ${supportedProviders}`,\n    );\n  }\n}\n\nexport class UnsupportedAISDKModelProviderError extends StagehandError {\n  constructor(provider: string, supportedProviders: string[]) {\n    super(\n      `${provider} is not currently supported for aiSDK. please use one of the supported model providers: ${supportedProviders}`,\n    );\n  }\n}\n\nexport class StagehandUnsupportedBrowserFeatureError extends StagehandError {\n  constructor(feature: string, message: string, cause?: unknown) {\n    super(`Unsupported browser feature \"${feature}\": ${message}`, cause);\n  }\n}\n\nexport class InvalidAISDKModelFormatError extends StagehandError {\n  constructor(modelName: string) {\n    super(\n      `${modelName} does not follow correct format for specifying aiSDK models. Please define your model as 'provider/model-name'. For example: \\`model: 'openai/gpt-4o-mini'\\``,\n    );\n  }\n}\n\nexport class StagehandNotInitializedError extends StagehandError {\n  constructor(prop: string) {\n    super(\n      `You seem to be calling \\`${prop}\\` on a page in an uninitialized \\`Stagehand\\` object. ` +\n        `Ensure you are running \\`await stagehand.init()\\` on the Stagehand object before ` +\n        `referencing the \\`page\\` object.`,\n    );\n  }\n}\n\nexport class BrowserbaseSessionNotFoundError extends StagehandError {\n  constructor() {\n    super(\"No Browserbase session ID found\");\n  }\n}\n\nexport class CaptchaTimeoutError extends StagehandError {\n  constructor() {\n    super(\"Captcha timeout\");\n  }\n}\n\nexport class MissingLLMConfigurationError extends StagehandError {\n  constructor() {\n    super(\n      \"No LLM API key or LLM Client configured. An LLM API key or a custom LLM Client \" +\n        \"is required to use act, extract, or observe.\",\n    );\n  }\n}\n\nexport class HandlerNotInitializedError extends StagehandError {\n  constructor(handlerType: string) {\n    super(`${handlerType} handler not initialized`);\n  }\n}\n\nexport class StagehandInvalidArgumentError extends StagehandError {\n  constructor(message: string) {\n    super(`InvalidArgumentError: ${message}`);\n  }\n}\n\nexport class CookieValidationError extends StagehandError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n\nexport class CookieSetError extends StagehandError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n\nexport class StagehandElementNotFoundError extends StagehandError {\n  constructor(xpaths: string[]) {\n    super(`Could not find an element for the given xPath(s): ${xpaths}`);\n  }\n}\n\nexport class AgentScreenshotProviderError extends StagehandError {\n  constructor(message: string) {\n    super(`ScreenshotProviderError: ${message}`);\n  }\n}\n\nexport class StagehandMissingArgumentError extends StagehandError {\n  constructor(message: string) {\n    super(`MissingArgumentError: ${message}`);\n  }\n}\n\nexport class CreateChatCompletionResponseError extends StagehandError {\n  constructor(message: string) {\n    super(`CreateChatCompletionResponseError: ${message}`);\n  }\n}\n\nexport class StagehandEvalError extends StagehandError {\n  constructor(message: string) {\n    super(`StagehandEvalError: ${message}`);\n  }\n}\n\nexport class StagehandDomProcessError extends StagehandError {\n  constructor(message: string) {\n    super(`Error Processing Dom: ${message}`);\n  }\n}\n\nexport class StagehandLocatorError extends StagehandError {\n  constructor(action: string, selector: string, message: string) {\n    super(\n      `Error ${action} Element with selector: ${selector} Reason: ${message}`,\n    );\n  }\n}\n\nexport class StagehandClickError extends StagehandError {\n  constructor(message: string, selector: string) {\n    super(\n      `Error Clicking Element with selector: ${selector} Reason: ${message}`,\n    );\n  }\n}\n\nexport class LLMResponseError extends StagehandError {\n  constructor(primitive: string, message: string) {\n    super(`${primitive} LLM response error: ${message}`);\n  }\n}\n\nexport class StagehandIframeError extends StagehandError {\n  constructor(frameUrl: string, message: string) {\n    super(\n      `Unable to resolve frameId for iframe with URL: ${frameUrl} Full error: ${message}`,\n    );\n  }\n}\n\nexport class ContentFrameNotFoundError extends StagehandError {\n  constructor(selector: string) {\n    super(`Unable to obtain a content frame for selector: ${selector}`);\n  }\n}\n\nexport class XPathResolutionError extends StagehandError {\n  constructor(xpath: string) {\n    super(`XPath \"${xpath}\" does not resolve in the current page or frames`);\n  }\n}\n\nexport class ExperimentalApiConflictError extends StagehandError {\n  constructor() {\n    super(\n      \"`experimental` mode cannot be used together with the Stagehand API. \" +\n        \"To use experimental features, set experimental: true and disableAPI: true in the stagehand constructor. \" +\n        \"To use the Stagehand API, set experimental: false and disableAPI: false (or omit it) in the stagehand constructor.\",\n    );\n  }\n}\n\nexport class ExperimentalNotConfiguredError extends StagehandError {\n  constructor(featureName: string) {\n    super(`Feature \"${featureName}\" is an experimental feature, and cannot be configured when disableAPI: false.\n    Please set experimental: true and disableAPI: true in the stagehand constructor to use this feature.\n    If you wish to use the Stagehand API, please ensure ${featureName} is not defined in your function call,\n    and set experimental: false, disableAPI: false (or omit it) in the Stagehand constructor.`);\n  }\n}\n\nexport class CuaModelRequiredError extends StagehandError {\n  constructor(availableModels: readonly string[]) {\n    super(\n      `To use the computer use agent (CUA), please provide a CUA model in the agent constructor or stagehand config. ` +\n        `Try one of our supported CUA models: ${availableModels.join(\", \")}`,\n    );\n  }\n}\n\nexport class ZodSchemaValidationError extends Error {\n  constructor(\n    public readonly received: unknown,\n    public readonly issues: ReturnType<ZodError[\"format\"]>,\n  ) {\n    super(`Zod schema validation failed\n\n— Received —\n${JSON.stringify(received, null, 2)}\n\n— Issues —\n${JSON.stringify(issues, null, 2)}`);\n    this.name = \"ZodSchemaValidationError\";\n  }\n}\n\nexport class StagehandInitError extends StagehandError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n\nexport class MCPConnectionError extends StagehandError {\n  public readonly serverUrl: string;\n  public readonly originalError: unknown;\n\n  constructor(serverUrl: string, originalError: unknown) {\n    const errorMessage =\n      originalError instanceof Error\n        ? originalError.message\n        : String(originalError);\n\n    super(\n      `Failed to connect to MCP server at \"${serverUrl}\". ${errorMessage}. ` +\n        `Please verify the server URL is correct and the server is running.`,\n    );\n\n    this.serverUrl = serverUrl;\n    this.originalError = originalError;\n  }\n}\n\nexport class StagehandShadowRootMissingError extends StagehandError {\n  constructor(detail?: string) {\n    super(\n      `No shadow root present on the resolved host` +\n        (detail ? `: ${detail}` : \"\"),\n    );\n  }\n}\n\nexport class StagehandShadowSegmentEmptyError extends StagehandError {\n  constructor() {\n    super(`Empty selector segment after shadow-DOM hop (\"//\")`);\n  }\n}\n\nexport class StagehandShadowSegmentNotFoundError extends StagehandError {\n  constructor(segment: string, hint?: string) {\n    super(\n      `Shadow segment '${segment}' matched no element inside shadow root` +\n        (hint ? ` ${hint}` : \"\"),\n    );\n  }\n}\n\nexport class ElementNotVisibleError extends StagehandError {\n  constructor(selector: string) {\n    super(`Element not visible (no box model): ${selector}`);\n  }\n}\n\nexport class ResponseBodyError extends StagehandError {\n  constructor(message: string) {\n    super(`Failed to retrieve response body: ${message}`);\n  }\n}\n\nexport class ResponseParseError extends StagehandError {\n  constructor(message: string) {\n    super(`Failed to parse response: ${message}`);\n  }\n}\n\nexport class TimeoutError extends StagehandError {\n  constructor(operation: string, timeoutMs: number) {\n    super(`${operation} timed out after ${timeoutMs}ms`);\n  }\n}\n\nexport class ActTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"act()\", timeoutMs);\n    this.name = \"ActTimeoutError\";\n  }\n}\n\nexport class ExtractTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"extract()\", timeoutMs);\n    this.name = \"ExtractTimeoutError\";\n  }\n}\n\nexport class ObserveTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"observe()\", timeoutMs);\n    this.name = \"ObserveTimeoutError\";\n  }\n}\n\nexport class PageNotFoundError extends StagehandError {\n  constructor(identifier: string) {\n    super(`No Page found for ${identifier}`);\n  }\n}\n\nexport class ConnectionTimeoutError extends StagehandError {\n  constructor(message: string) {\n    super(`Connection timeout: ${message}`);\n  }\n}\n\nexport class StreamingCallbacksInNonStreamingModeError extends StagehandError {\n  public readonly invalidCallbacks: string[];\n\n  constructor(invalidCallbacks: string[]) {\n    super(\n      `Streaming-only callback(s) \"${invalidCallbacks.join('\", \"')}\" cannot be used in non-streaming mode. ` +\n        `Set 'stream: true' in AgentConfig to use these callbacks.`,\n    );\n    this.invalidCallbacks = invalidCallbacks;\n  }\n}\n\nexport class AgentAbortError extends StagehandError {\n  public readonly reason: string;\n\n  constructor(reason?: string) {\n    const message = reason\n      ? `Agent execution was aborted: ${reason}`\n      : \"Agent execution was aborted\";\n    super(message);\n    this.reason = reason || \"aborted\";\n  }\n}\n\nexport class StagehandClosedError extends StagehandError {\n  constructor() {\n    super(\"Stagehand session was closed\");\n  }\n}\n\nexport class CdpConnectionClosedError extends StagehandError {\n  constructor(reason: string) {\n    super(`CDP connection closed: ${reason}`);\n  }\n}\n\nexport class StagehandSetExtraHTTPHeadersError extends StagehandError {\n  public readonly failures: string[];\n\n  constructor(failures: string[]) {\n    super(\n      `setExtraHTTPHeaders failed for ${failures.length} session(s): ${failures.join(\", \")}`,\n    );\n    this.failures = failures;\n  }\n}\n\nexport class StagehandSetDomainPolicyError extends StagehandError {\n  public readonly failures: string[];\n\n  constructor(failures: string[]) {\n    super(\n      `setDomainPolicy failed for ${failures.length} session(s): ${failures.join(\", \")}`,\n    );\n    this.failures = failures;\n  }\n}\n\nexport class StagehandSnapshotError extends StagehandError {\n  constructor(cause?: unknown) {\n    const suffix =\n      cause instanceof Error\n        ? `: ${cause.message}`\n        : cause\n          ? `: ${String(cause)}`\n          : \"\";\n    super(`error taking snapshot${suffix}`, cause);\n  }\n}\n\nexport class UnderstudyCommandException extends StagehandError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = \"UnderstudyCommandException\";\n  }\n}\n"]}

package/dist/esm/lib/v3/understudy/a11y/snapshot/capture.js

@@ -150,14 +150,15 @@ export async function tryScopedSnapshot(page, options, context, pierce, sessionT
             }
         }
         const scopedUrlMap = { ...urlMap };
+        const wellFormedOutline = outline.toWellFormed();
         const snapshot = {
-            combinedTree: outline,
+            combinedTree: wellFormedOutline,
             combinedXpathMap: scopedXpathMap,
             combinedUrlMap: scopedUrlMap,
             perFrame: [
                 {
                     frameId: targetFrameId,
-                    outline,
+                    outline: wellFormedOutline,
                     xpathMap,
                     urlMap,
                 },
@@ -562,7 +563,7 @@ export function mergeFramesIntoSnapshot(context, perFrameMaps, perFrameOutlines,
     const rootOutline = perFrameOutlines.find((o) => o.frameId === context.rootId)?.outline ??
         perFrameOutlines[0]?.outline ??
         "";
-    const combinedTree = injectSubtrees(rootOutline, idToTree);
+    const combinedTree = injectSubtrees(rootOutline, idToTree).toWellFormed();
     return {
         combinedTree,
         combinedXpathMap,