@browserbasehq/orca 3.1.0-patch.3 → 3.2.0-preview.1

package/dist/cjs/lib/v3/types/private/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/cache.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  ActOptions,\n  ActResult,\n  AvailableModel,\n  Logger,\n  AgentResult,\n  Action,\n  LoadState,\n} from \"../public/index.js\";\nimport { CacheStorage } from \"../../cache/CacheStorage.js\";\nimport type { ActHandler } from \"../../handlers/actHandler.js\";\nimport type { V3Context } from \"../../understudy/context.js\";\nimport type { LLMClient } from \"../../llm/LLMClient.js\";\n\nexport type ActFn = (\n  instruction: string,\n  options?: ActOptions,\n) => Promise<ActResult>;\n\nexport type AgentCacheContext = {\n  instruction: string;\n  startUrl: string;\n  options: SanitizedAgentExecuteOptions;\n  configSignature: string;\n  cacheKey: string;\n  variableKeys: string[] /** Variable keys used in this execution (for cache key) */;\n  /** Variable values to substitute during replay */\n  variables?: Record<string, string>;\n};\n\nexport type AgentCacheTransferPayload = {\n  cacheKey: string;\n  entry: CachedAgentEntry;\n};\n\nexport type AgentCacheDeps = {\n  storage: CacheStorage;\n  logger: Logger;\n  getActHandler: () => ActHandler | null;\n  getContext: () => V3Context | null;\n  getDefaultLlmClient: () => LLMClient;\n  getBaseModelName: () => AvailableModel;\n  getSystemPrompt: () => string | undefined;\n  domSettleTimeoutMs?: number;\n  act: ActFn;\n  bufferLatestEntry?: boolean;\n};\n\nexport type ActCacheContext = {\n  instruction: string;\n  cacheKey: string;\n  pageUrl: string;\n  variableKeys: string[];\n  variables?: Record<string, string>;\n};\n\nexport type ActCacheDeps = {\n  storage: CacheStorage;\n  logger: Logger;\n  getActHandler: () => ActHandler | null;\n  getDefaultLlmClient: () => LLMClient;\n  domSettleTimeoutMs?: number;\n};\n\nexport type ReadJsonResult<T> = {\n  value: T | null;\n  path?: string;\n  error?: unknown;\n};\n\nexport type WriteJsonResult = {\n  path?: string;\n  error?: unknown;\n};\n\nexport interface CachedActEntry {\n  version: 1;\n  instruction: string;\n  url: string;\n  variableKeys: string[];\n  actions: Action[];\n  actionDescription?: string;\n  message?: string;\n}\n\nexport type AgentReplayStep =\n  | AgentReplayActStep\n  | AgentReplayFillFormStep\n  | AgentReplayGotoStep\n  | AgentReplayScrollStep\n  | AgentReplayWaitStep\n  | AgentReplayNavBackStep\n  | AgentReplayKeysStep\n  | { type: string; [key: string]: unknown };\n\nexport interface AgentReplayActStep {\n  type: \"act\";\n  instruction: string;\n  actions?: Action[];\n  actionDescription?: string;\n  message?: string;\n  timeout?: number;\n}\n\nexport interface AgentReplayFillFormStep {\n  type: \"fillForm\";\n  fields?: Array<{ action: string; value: string }>;\n  observeResults?: Action[];\n  actions?: Action[];\n}\n\nexport interface AgentReplayGotoStep {\n  type: \"goto\";\n  url: string;\n  waitUntil?: LoadState;\n}\n\nexport interface AgentReplayScrollStep {\n  type: \"scroll\";\n  deltaX?: number;\n  deltaY?: number;\n  anchor?: { x: number; y: number };\n}\n\nexport interface AgentReplayWaitStep {\n  type: \"wait\";\n  timeMs: number;\n}\n\nexport interface AgentReplayNavBackStep {\n  type: \"navback\";\n  waitUntil?: LoadState;\n}\n\nexport interface AgentReplayKeysStep {\n  type: \"keys\";\n  instruction?: string;\n  playwrightArguments: {\n    method: \"type\" | \"press\";\n    text?: string;\n    keys?: string;\n    times?: number;\n  };\n}\n\nexport interface SanitizedAgentExecuteOptions {\n  maxSteps?: number;\n  highlightCursor?: boolean;\n}\n\nexport interface CachedAgentEntry {\n  version: 1;\n  instruction: string;\n  startUrl: string;\n  options: SanitizedAgentExecuteOptions;\n  configSignature: string;\n  steps: AgentReplayStep[];\n  result: AgentResult;\n  timestamp: string;\n}\n"]}

package/dist/cjs/lib/v3/types/private/evaluator.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=evaluator.js.map

package/dist/cjs/lib/v3/types/private/evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/evaluator.ts"],"names":[],"mappings":"","sourcesContent":["export type EvaluateOptions = {\n  /** The question to ask about the task state */\n  question: string;\n  /** The answer to the question */\n  answer?: string;\n  /** Whether to take a screenshot of the task state, or array of screenshots to evaluate */\n  screenshot?: boolean | Buffer[];\n  /** Custom system prompt for the evaluator */\n  systemPrompt?: string;\n  /** Delay in milliseconds before taking the screenshot @default 250 */\n  screenshotDelayMs?: number;\n  /** The agent's reasoning/thought process for completing the task */\n  agentReasoning?: string;\n};\n\nexport type BatchAskOptions = {\n  /** Array of questions with optional answers */\n  questions: Array<{\n    question: string;\n    answer?: string;\n  }>;\n  /** Whether to take a screenshot of the task state */\n  screenshot?: boolean;\n  /** Custom system prompt for the evaluator */\n  systemPrompt?: string;\n  /** Delay in milliseconds before taking the screenshot @default 1000 */\n  screenshotDelayMs?: number;\n};\n\n/**\n * Result of an evaluation\n */\nexport interface EvaluationResult {\n  /**\n   * The evaluation result ('YES', 'NO', or 'INVALID' if parsing failed or value was unexpected)\n   */\n  evaluation: \"YES\" | \"NO\" | \"INVALID\";\n  /**\n   * The reasoning behind the evaluation\n   */\n  reasoning: string;\n}\n"]}

package/dist/cjs/lib/v3/types/private/handlers.d.ts

@@ -1,10 +1,11 @@
 import { Page } from "../../understudy/page.js";
 import { ModelConfiguration } from "../public/model.js";
 import type { StagehandZodSchema } from "../../zodCompat.js";
+import type { Variables } from "../public/agent.js";
 export interface ActHandlerParams {
     instruction: string;
     model?: ModelConfiguration;
-    variables?: Record<string, string>;
+    variables?: Variables;
     timeout?: number;
     page: Page;
 }

package/dist/cjs/lib/v3/types/private/handlers.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SupportedUnderstudyAction = void 0;
+// We can use this enum to list the actions supported in performUnderstudyMethod
+var SupportedUnderstudyAction;
+(function (SupportedUnderstudyAction) {
+    SupportedUnderstudyAction["CLICK"] = "click";
+    SupportedUnderstudyAction["FILL"] = "fill";
+    SupportedUnderstudyAction["TYPE"] = "type";
+    SupportedUnderstudyAction["PRESS"] = "press";
+    SupportedUnderstudyAction["SCROLL"] = "scrollTo";
+    SupportedUnderstudyAction["NEXT_CHUNK"] = "nextChunk";
+    SupportedUnderstudyAction["PREV_CHUNK"] = "prevChunk";
+    SupportedUnderstudyAction["SELECT_OPTION_FROM_DROPDOWN"] = "selectOptionFromDropdown";
+    SupportedUnderstudyAction["HOVER"] = "hover";
+    SupportedUnderstudyAction["DOUBLE_CLICK"] = "doubleClick";
+    SupportedUnderstudyAction["DRAG_AND_DROP"] = "dragAndDrop";
+})(SupportedUnderstudyAction || (exports.SupportedUnderstudyAction = SupportedUnderstudyAction = {}));
+//# sourceMappingURL=handlers.js.map

package/dist/cjs/lib/v3/types/private/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/handlers.ts"],"names":[],"mappings":";;;AA8BA,gFAAgF;AAChF,IAAY,yBAYX;AAZD,WAAY,yBAAyB;IACnC,4CAAe,CAAA;IACf,0CAAa,CAAA;IACb,0CAAa,CAAA;IACb,4CAAe,CAAA;IACf,gDAAmB,CAAA;IACnB,qDAAwB,CAAA;IACxB,qDAAwB,CAAA;IACxB,qFAAwD,CAAA;IACxD,4CAAe,CAAA;IACf,yDAA4B,CAAA;IAC5B,0DAA6B,CAAA;AAC/B,CAAC,EAZW,yBAAyB,yCAAzB,yBAAyB,QAYpC","sourcesContent":["import { Page } from \"../../understudy/page.js\";\nimport { ModelConfiguration } from \"../public/model.js\";\nimport type { StagehandZodSchema } from \"../../zodCompat.js\";\nimport type { Variables } from \"../public/agent.js\";\n\nexport interface ActHandlerParams {\n  instruction: string;\n  model?: ModelConfiguration;\n  variables?: Variables;\n  timeout?: number;\n  page: Page;\n}\n\nexport interface ExtractHandlerParams<T extends StagehandZodSchema> {\n  instruction?: string;\n  schema?: T;\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  page: Page;\n}\n\nexport interface ObserveHandlerParams {\n  instruction?: string;\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  page: Page;\n}\n\n// We can use this enum to list the actions supported in performUnderstudyMethod\nexport enum SupportedUnderstudyAction {\n  CLICK = \"click\",\n  FILL = \"fill\",\n  TYPE = \"type\",\n  PRESS = \"press\",\n  SCROLL = \"scrollTo\",\n  NEXT_CHUNK = \"nextChunk\",\n  PREV_CHUNK = \"prevChunk\",\n  SELECT_OPTION_FROM_DROPDOWN = \"selectOptionFromDropdown\",\n  HOVER = \"hover\",\n  DOUBLE_CLICK = \"doubleClick\",\n  DRAG_AND_DROP = \"dragAndDrop\",\n}\n"]}

package/dist/cjs/lib/v3/types/private/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./api.js"), exports);
+__exportStar(require("./handlers.js"), exports);
+__exportStar(require("./internal.js"), exports);
+__exportStar(require("./evaluator.js"), exports);
+__exportStar(require("./cache.js"), exports);
+__exportStar(require("./agent.js"), exports);
+__exportStar(require("./snapshot.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/lib/v3/types/private/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,gDAA8B;AAC9B,gDAA8B;AAC9B,iDAA+B;AAC/B,6CAA2B;AAC3B,6CAA2B;AAC3B,gDAA8B","sourcesContent":["export * from \"./api.js\";\nexport * from \"./handlers.js\";\nexport * from \"./internal.js\";\nexport * from \"./evaluator.js\";\nexport * from \"./cache.js\";\nexport * from \"./agent.js\";\nexport * from \"./snapshot.js\";\n"]}

package/dist/cjs/lib/v3/types/private/internal.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=internal.js.map

package/dist/cjs/lib/v3/types/private/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/internal.ts"],"names":[],"mappings":"","sourcesContent":["import Browserbase from \"@browserbasehq/sdk\";\nimport { LaunchedChrome } from \"chrome-launcher\";\n\nexport type InitState =\n  | { kind: \"UNINITIALIZED\" }\n  | {\n      kind: \"LOCAL\";\n      chrome: LaunchedChrome;\n      ws: string;\n      userDataDir?: string;\n      createdTempProfile?: boolean;\n      preserveUserDataDir?: boolean;\n    }\n  | { kind: \"BROWSERBASE\"; bb: Browserbase; sessionId: string; ws: string };\n\nexport type EncodedId = `${number}-${number}`;\n\n/**\n * Represents a path through a Zod schema from the root object down to a\n * particular field. The `segments` array describes the chain of keys/indices.\n *\n * - **String** segments indicate object property names.\n * - **Number** segments indicate array indices.\n *\n * For example, `[\"users\", 0, \"homepage\"]` might describe reaching\n * the `homepage` field in `schema.users[0].homepage`.\n */\nexport interface ZodPathSegments {\n  /**\n   * The ordered list of keys/indices leading from the schema root\n   * to the targeted field.\n   */\n  segments: Array<string | number>;\n}\n\nexport type InitScriptSource<Arg> =\n  | string\n  | { path?: string; content?: string }\n  | ((arg: Arg) => unknown);\n"]}

package/dist/cjs/lib/v3/types/private/locator.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=locator.js.map

package/dist/cjs/lib/v3/types/private/locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/locator.ts"],"names":[],"mappings":"","sourcesContent":["import { Buffer } from \"buffer\";\n\nexport interface NormalizedFilePayload {\n  name: string;\n  mimeType: string;\n  buffer: Buffer;\n  lastModified: number;\n  /** Absolute path to the source file when provided by the caller. */\n  absolutePath?: string;\n}\n"]}

package/dist/cjs/lib/v3/types/private/network.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IGNORED_RESOURCE_TYPES = exports.DEFAULT_IDLE_WAIT = void 0;
+exports.DEFAULT_IDLE_WAIT = 500;
+exports.IGNORED_RESOURCE_TYPES = new Set(["EventSource", "WebSocket"]);
+//# sourceMappingURL=network.js.map

package/dist/cjs/lib/v3/types/private/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/network.ts"],"names":[],"mappings":";;;AA+Ba,QAAA,iBAAiB,GAAG,GAAG,CAAC;AACxB,QAAA,sBAAsB,GAAG,IAAI,GAAG,CAE3C,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC","sourcesContent":["import { Protocol } from \"devtools-protocol\";\n\n/** Metadata tracked for each network request currently in-flight. */\nexport type NetworkRequestInfo = {\n  sessionId: string;\n  requestId: string;\n  requestKey: string;\n  frameId?: string;\n  loaderId?: string;\n  url?: string;\n  timestamp: number;\n  resourceType?: Protocol.Network.ResourceType;\n  documentRequest: boolean;\n};\n\n/** Callback hooks consumers can implement to observe network transitions. */\nexport interface NetworkObserver {\n  onRequestStarted(info: NetworkRequestInfo): void;\n  onRequestFinished(info: NetworkRequestInfo): void;\n  onRequestFailed(info: NetworkRequestInfo): void;\n}\n\n/** Options for the idle waiter helper. */\nexport type WaitForIdleOptions = {\n  startTime?: number;\n  timeoutMs: number;\n  idleTimeMs?: number;\n  filter?: (info: NetworkRequestInfo) => boolean;\n  totalBudgetMs?: number;\n};\n\nexport const DEFAULT_IDLE_WAIT = 500;\nexport const IGNORED_RESOURCE_TYPES = new Set<\n  Protocol.Network.ResourceType | undefined\n>([\"EventSource\", \"WebSocket\"]);\n\n/** The handle returned by the network manager idle helper. */\nexport type WaitForIdleHandle = {\n  promise: Promise<void>;\n  dispose: () => void;\n};\n"]}

package/dist/cjs/lib/v3/types/private/shutdown.d.ts

@@ -11,7 +11,7 @@ export type ShutdownSupervisorConfig = {
     kind: "STAGEHAND_API";
     sessionId: string;
     apiKey: string;
-    projectId: string;
+    projectId?: string;
 };
 export interface ShutdownSupervisorHandle {
     /** Best-effort signal to stop the supervisor process. */

package/dist/cjs/lib/v3/types/private/shutdown.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Internal-only types for the shutdown supervisor process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=shutdown.js.map

package/dist/cjs/lib/v3/types/private/shutdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/shutdown.ts"],"names":[],"mappings":";AAAA;;GAEG","sourcesContent":["/**\n * Internal-only types for the shutdown supervisor process.\n */\n\nexport type ShutdownSupervisorConfig =\n  | {\n      kind: \"LOCAL\";\n      pid: number;\n      userDataDir?: string;\n      createdTempProfile?: boolean;\n      preserveUserDataDir?: boolean;\n    }\n  | {\n      kind: \"STAGEHAND_API\";\n      sessionId: string;\n      apiKey: string;\n      projectId?: string;\n    };\n\nexport interface ShutdownSupervisorHandle {\n  /** Best-effort signal to stop the supervisor process. */\n  stop: () => void;\n}\n"]}

package/dist/cjs/lib/v3/types/private/shutdownErrors.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Internal-only errors for the shutdown supervisor.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShutdownSupervisorSpawnError = exports.ShutdownSupervisorResolveError = exports.ShutdownSupervisorError = void 0;
+class ShutdownSupervisorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ShutdownSupervisorError";
+    }
+}
+exports.ShutdownSupervisorError = ShutdownSupervisorError;
+class ShutdownSupervisorResolveError extends ShutdownSupervisorError {
+    constructor(message) {
+        super(message);
+        this.name = "ShutdownSupervisorResolveError";
+    }
+}
+exports.ShutdownSupervisorResolveError = ShutdownSupervisorResolveError;
+class ShutdownSupervisorSpawnError extends ShutdownSupervisorError {
+    constructor(message) {
+        super(message);
+        this.name = "ShutdownSupervisorSpawnError";
+    }
+}
+exports.ShutdownSupervisorSpawnError = ShutdownSupervisorSpawnError;
+//# sourceMappingURL=shutdownErrors.js.map

package/dist/cjs/lib/v3/types/private/shutdownErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdownErrors.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/shutdownErrors.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,MAAa,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AALD,0DAKC;AAED,MAAa,8BAA+B,SAAQ,uBAAuB;IACzE,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;IAC/C,CAAC;CACF;AALD,wEAKC;AAED,MAAa,4BAA6B,SAAQ,uBAAuB;IACvE,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AALD,oEAKC","sourcesContent":["/**\n * Internal-only errors for the shutdown supervisor.\n */\n\nexport class ShutdownSupervisorError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ShutdownSupervisorError\";\n  }\n}\n\nexport class ShutdownSupervisorResolveError extends ShutdownSupervisorError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ShutdownSupervisorResolveError\";\n  }\n}\n\nexport class ShutdownSupervisorSpawnError extends ShutdownSupervisorError {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ShutdownSupervisorSpawnError\";\n  }\n}\n"]}

package/dist/cjs/lib/v3/types/private/snapshot.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=snapshot.js.map

package/dist/cjs/lib/v3/types/private/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/snapshot.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Options that control how hybrid snapshots and targeted scopes are captured.\n */\nexport type SnapshotOptions = {\n  /**\n   * Filter the snapshot to a specific element/subtree using a selector that can cross iframes.\n   * Supports XPath (prefixed with `xpath=` or starting with `/`) and CSS with iframe hops via `>>`.\n   */\n  focusSelector?: string;\n  /**\n   * Pierce shadow DOM when calling DOM.getDocument. Defaults to true to retain the\n   * existing behaviour.\n   */\n  pierceShadow?: boolean;\n  /**\n   * Toggle whether iframe subtrees are included in the merged snapshot. Defaults to true.\n   */\n  includeIframes?: boolean;\n  /**\n   * Optional feature flag that surfaces experimental traversal tweaks in the Accessibility layer.\n   */\n  experimental?: boolean;\n};\n\n/**\n * Hybrid snapshot payload consumed by act/extract/observe handlers.\n */\nexport type HybridSnapshot = {\n  /** Merged outline across every frame. */\n  combinedTree: string;\n  /** EncodedId (frameOrdinal-backendNodeId) -> absolute XPath. */\n  combinedXpathMap: Record<string, string>;\n  /** EncodedId -> URL extracted from AX properties. */\n  combinedUrlMap: Record<string, string>;\n  /** Per-frame payloads expose the original relative data for debugging. */\n  perFrame?: PerFrameSnapshot[];\n};\n\nexport type PerFrameSnapshot = {\n  frameId: string;\n  outline: string;\n  xpathMap: Record<string, string>;\n  urlMap: Record<string, string>;\n};\n\n/**\n * Compact encoding of DOM data for an entire session. Shared between capture\n * and focus helpers so DOM traversal can be unit tested in isolation.\n */\nexport type SessionDomIndex = {\n  rootBackend: number;\n  absByBe: Map<number, string>;\n  tagByBe: Map<number, string>;\n  scrollByBe: Map<number, boolean>;\n  docRootOf: Map<number, number>;\n  contentDocRootByIframe: Map<number, number>;\n};\n\nexport type FrameDomMaps = {\n  tagNameMap: Record<string, string>;\n  xpathMap: Record<string, string>;\n  scrollableMap: Record<string, boolean>;\n  urlMap: Record<string, string>;\n};\n\nexport type ResolvedLocation = {\n  frameId: string;\n  backendNodeId: number;\n  absoluteXPath: string;\n};\n\nexport type ResolvedFocusFrame = {\n  targetFrameId: string;\n  tailXPath: string;\n  absPrefix: string;\n};\n\nexport type ResolvedCssFocus = {\n  targetFrameId: string;\n  tailSelector: string;\n  absPrefix: string;\n};\n\nexport type Axis = \"child\" | \"desc\";\n\nexport type Step = {\n  axis: Axis;\n  raw: string;\n  name: string;\n};\n\nexport type A11yNode = {\n  role: string;\n  name?: string;\n  description?: string;\n  value?: string | number | boolean;\n  nodeId: string;\n  backendDOMNodeId?: number;\n  parentId?: string;\n  childIds?: string[];\n  children?: A11yNode[];\n  encodedId?: string;\n};\n\nexport type A11yOptions = {\n  focusSelector?: string;\n  experimental: boolean;\n  tagNameMap: Record<string, string>;\n  scrollableMap: Record<string, boolean>;\n  encode: (backendNodeId: number) => string;\n};\n\nexport type AccessibilityTreeResult = {\n  outline: string;\n  urlMap: Record<string, string>;\n  scopeApplied: boolean;\n};\n\nexport type FrameParentIndex = Map<string, string | null>;\n\n/**\n * Shared frame metadata that every snapshot step needs.\n * - `rootId`: stable identifier for the main frame so we can detect root prefixes.\n * - `parentByFrame`: lookup table for iframe parentage (used by focus scoping and prefixing).\n * - `frames`: DFS-ordered frame ids so merging walks parents before children.\n */\nexport type FrameContext = {\n  rootId: string;\n  parentByFrame: FrameParentIndex;\n  frames: string[];\n};\n"]}

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

@@ -9,6 +9,30 @@ 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";
+/**
+ * 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.
+ *
+ * @example Simple (backward-compatible):
+ * ```typescript
+ * variables: { username: "john@example.com" }
+ * ```
+ *
+ * @example Rich with description (useful for agents):
+ * ```typescript
+ * variables: {
+ *   username: { value: "john@example.com", description: "The login email" }
+ * }
+ * ```
+ */
+export type VariableValue = string | number | boolean | {
+    value: string | number | boolean;
+    description?: string;
+};
+/**
+ * A collection of named variables for use in act, agent, and other methods.
+ */
+export type Variables = Record<string, VariableValue>;
 export interface AgentContext {
     options: AgentExecuteOptionsBase;
     maxSteps: number;
@@ -303,6 +327,38 @@ export interface AgentExecuteOptionsBase {
      * ```
      */
     output?: StagehandZodObject;
+    /**
+     * Variables that the agent can use when filling forms or typing text.
+     * The agent will see variable names and descriptions in the system prompt,
+     * and can use them via `%variableName%` syntax in act/type/fillForm tool calls.
+     *
+     * Accepts both simple values and rich objects with descriptions (same type as `act`).
+     *
+     * **Note:** Not supported in CUA mode (`mode: "cua"`). Requires `experimental: true`.
+     *
+     * @experimental
+     * @example
+     * ```typescript
+     * // Simple values
+     * variables: { username: "john@example.com", password: "secret123" }
+     *
+     * // Rich values with descriptions (helps the agent understand context)
+     * variables: {
+     *   username: { value: "john@example.com", description: "The login email" },
+     *   password: { value: "secret123", description: "The login password" },
+     * }
+     * ```
+     */
+    variables?: Variables;
+    /**
+     * Timeout in milliseconds for each agent tool call.
+     * If a tool call exceeds this duration, it will be aborted and
+     * reported back to the LLM as a timeout error so it can retry or adjust.
+     * For tools that call v3 methods (act, extract, fillForm, ariaTree), the
+     * timeout is also forwarded to the underlying v3 call for true cancellation.
+     * @default 45000 (45 seconds)
+     */
+    toolTimeout?: number;
 }
 /**
  * Options for non-streaming agent execution.
@@ -326,8 +382,8 @@ export interface AgentStreamExecuteOptions extends AgentExecuteOptionsBase {
      */
     callbacks?: AgentStreamCallbacks;
 }
-export type AgentType = "openai" | "anthropic" | "google" | "microsoft";
-export declare const AVAILABLE_CUA_MODELS: readonly ["openai/computer-use-preview", "openai/computer-use-preview-2025-03-11", "anthropic/claude-3-7-sonnet-latest", "anthropic/claude-opus-4-5-20251101", "anthropic/claude-opus-4-6", "anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-20250514", "anthropic/claude-sonnet-4-5-20250929", "google/gemini-2.5-computer-use-preview-10-2025", "google/gemini-3-flash-preview", "google/gemini-3-pro-preview", "microsoft/fara-7b"];
+export type AgentType = "openai" | "anthropic" | "google" | "microsoft" | "bedrock";
+export declare const AVAILABLE_CUA_MODELS: readonly ["openai/computer-use-preview", "openai/computer-use-preview-2025-03-11", "anthropic/claude-opus-4-5-20251101", "anthropic/claude-opus-4-6", "anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-20250514", "anthropic/claude-sonnet-4-5-20250929", "google/gemini-2.5-computer-use-preview-10-2025", "google/gemini-3-flash-preview", "google/gemini-3-pro-preview", "microsoft/fara-7b"];
 export type AvailableCuaModel = (typeof AVAILABLE_CUA_MODELS)[number];
 export interface AgentExecutionOptions<TOptions extends AgentExecuteOptions = AgentExecuteOptions> {
     options: TOptions;
@@ -584,6 +640,7 @@ export interface ScrollToolResult {
     success: boolean;
     message: string;
     scrolledPixels: number;
+    error?: string;
 }
 export interface ScrollVisionToolResult extends ScrollToolResult {
     screenshotBase64?: string;
@@ -592,4 +649,5 @@ export interface WaitToolResult {
     success: boolean;
     waited: number;
     screenshotBase64?: string;
+    error?: string;
 }

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

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AVAILABLE_CUA_MODELS = void 0;
+exports.AVAILABLE_CUA_MODELS = [
+    "openai/computer-use-preview",
+    "openai/computer-use-preview-2025-03-11",
+    "anthropic/claude-opus-4-5-20251101",
+    "anthropic/claude-opus-4-6",
+    "anthropic/claude-sonnet-4-6",
+    "anthropic/claude-haiku-4-5-20251001",
+    "anthropic/claude-sonnet-4-20250514",
+    "anthropic/claude-sonnet-4-5-20250929",
+    "google/gemini-2.5-computer-use-preview-10-2025",
+    "google/gemini-3-flash-preview",
+    "google/gemini-3-pro-preview",
+    "microsoft/fara-7b",
+];
+//# sourceMappingURL=agent.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/agent.ts"],"names":[],"mappings":";;;AAoba,QAAA,oBAAoB,GAAG;IAClC,6BAA6B;IAC7B,wCAAwC;IACxC,oCAAoC;IACpC,2BAA2B;IAC3B,6BAA6B;IAC7B,qCAAqC;IACrC,oCAAoC;IACpC,sCAAsC;IACtC,gDAAgD;IAChD,+BAA+B;IAC/B,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\";\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\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 BRAVE_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 BRAVE_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\"`). Requires `experimental: true`.\n   *\n   * @experimental\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\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\nexport const AVAILABLE_CUA_MODELS = [\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-sonnet-4-6\",\n  \"anthropic/claude-haiku-4-5-20251001\",\n  \"anthropic/claude-sonnet-4-20250514\",\n  \"anthropic/claude-sonnet-4-5-20250929\",\n  \"google/gemini-2.5-computer-use-preview-10-2025\",\n  \"google/gemini-3-flash-preview\",\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  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\";\n            image_url: string;\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/cjs/lib/v3/types/public/api.d.ts

@@ -35,6 +35,7 @@ export declare const LocalBrowserLaunchOptionsSchema: z.ZodObject<{
     hasTouch: z.ZodOptional<z.ZodBoolean>;
     ignoreHTTPSErrors: z.ZodOptional<z.ZodBoolean>;
     cdpUrl: z.ZodOptional<z.ZodString>;
+    cdpHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     connectTimeoutMs: z.ZodOptional<z.ZodNumber>;
     downloadsPath: z.ZodOptional<z.ZodString>;
     acceptDownloads: z.ZodOptional<z.ZodBoolean>;
@@ -46,6 +47,7 @@ export declare const ModelConfigObjectSchema: z.ZodObject<{
         anthropic: "anthropic";
         google: "google";
         microsoft: "microsoft";
+        bedrock: "bedrock";
     }>>;
     modelName: z.ZodString;
     apiKey: z.ZodOptional<z.ZodString>;
@@ -58,6 +60,7 @@ export declare const ModelConfigSchema: z.ZodObject<{
         anthropic: "anthropic";
         google: "google";
         microsoft: "microsoft";
+        bedrock: "bedrock";
     }>>;
     modelName: z.ZodString;
     apiKey: z.ZodOptional<z.ZodString>;
@@ -107,6 +110,7 @@ export declare const BrowserConfigSchema: z.ZodObject<{
         hasTouch: z.ZodOptional<z.ZodBoolean>;
         ignoreHTTPSErrors: z.ZodOptional<z.ZodBoolean>;
         cdpUrl: z.ZodOptional<z.ZodString>;
+        cdpHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         connectTimeoutMs: z.ZodOptional<z.ZodNumber>;
         downloadsPath: z.ZodOptional<z.ZodString>;
         acceptDownloads: z.ZodOptional<z.ZodBoolean>;
@@ -452,6 +456,7 @@ export declare const SessionStartRequestSchema: z.ZodObject<{
             hasTouch: z.ZodOptional<z.ZodBoolean>;
             ignoreHTTPSErrors: z.ZodOptional<z.ZodBoolean>;
             cdpUrl: z.ZodOptional<z.ZodString>;
+            cdpHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             connectTimeoutMs: z.ZodOptional<z.ZodNumber>;
             downloadsPath: z.ZodOptional<z.ZodString>;
             acceptDownloads: z.ZodOptional<z.ZodBoolean>;
@@ -490,6 +495,7 @@ export declare const ActOptionsSchema: z.ZodOptional<z.ZodObject<{
             anthropic: "anthropic";
             google: "google";
             microsoft: "microsoft";
+            bedrock: "bedrock";
         }>>;
         modelName: z.ZodString;
         apiKey: z.ZodOptional<z.ZodString>;
@@ -513,6 +519,7 @@ export declare const ActRequestSchema: z.ZodObject<{
                 anthropic: "anthropic";
                 google: "google";
                 microsoft: "microsoft";
+                bedrock: "bedrock";
             }>>;
             modelName: z.ZodString;
             apiKey: z.ZodOptional<z.ZodString>;
@@ -577,6 +584,7 @@ export declare const ExtractOptionsSchema: z.ZodOptional<z.ZodObject<{
             anthropic: "anthropic";
             google: "google";
             microsoft: "microsoft";
+            bedrock: "bedrock";
         }>>;
         modelName: z.ZodString;
         apiKey: z.ZodOptional<z.ZodString>;
@@ -595,6 +603,7 @@ export declare const ExtractRequestSchema: z.ZodObject<{
                 anthropic: "anthropic";
                 google: "google";
                 microsoft: "microsoft";
+                bedrock: "bedrock";
             }>>;
             modelName: z.ZodString;
             apiKey: z.ZodOptional<z.ZodString>;
@@ -624,6 +633,7 @@ export declare const ObserveOptionsSchema: z.ZodOptional<z.ZodObject<{
             anthropic: "anthropic";
             google: "google";
             microsoft: "microsoft";
+            bedrock: "bedrock";
         }>>;
         modelName: z.ZodString;
         apiKey: z.ZodOptional<z.ZodString>;
@@ -641,6 +651,7 @@ export declare const ObserveRequestSchema: z.ZodObject<{
                 anthropic: "anthropic";
                 google: "google";
                 microsoft: "microsoft";
+                bedrock: "bedrock";
             }>>;
             modelName: z.ZodString;
             apiKey: z.ZodOptional<z.ZodString>;
@@ -681,6 +692,7 @@ export declare const AgentConfigSchema: z.ZodObject<{
         anthropic: "anthropic";
         google: "google";
         microsoft: "microsoft";
+        bedrock: "bedrock";
     }>>;
     model: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         provider: z.ZodOptional<z.ZodEnum<{
@@ -688,6 +700,7 @@ export declare const AgentConfigSchema: z.ZodObject<{
             anthropic: "anthropic";
             google: "google";
             microsoft: "microsoft";
+            bedrock: "bedrock";
         }>>;
         modelName: z.ZodString;
         apiKey: z.ZodOptional<z.ZodString>;
@@ -706,6 +719,7 @@ export declare const AgentConfigSchema: z.ZodObject<{
             anthropic: "anthropic";
             google: "google";
             microsoft: "microsoft";
+            bedrock: "bedrock";
         }>>;
         modelName: z.ZodString;
         apiKey: z.ZodOptional<z.ZodString>;
@@ -771,6 +785,7 @@ export declare const AgentExecuteRequestSchema: z.ZodObject<{
             anthropic: "anthropic";
             google: "google";
             microsoft: "microsoft";
+            bedrock: "bedrock";
         }>>;
         model: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             provider: z.ZodOptional<z.ZodEnum<{
@@ -778,6 +793,7 @@ export declare const AgentExecuteRequestSchema: z.ZodObject<{
                 anthropic: "anthropic";
                 google: "google";
                 microsoft: "microsoft";
+                bedrock: "bedrock";
             }>>;
             modelName: z.ZodString;
             apiKey: z.ZodOptional<z.ZodString>;
@@ -796,6 +812,7 @@ export declare const AgentExecuteRequestSchema: z.ZodObject<{
                 anthropic: "anthropic";
                 google: "google";
                 microsoft: "microsoft";
+                bedrock: "bedrock";
             }>>;
             modelName: z.ZodString;
             apiKey: z.ZodOptional<z.ZodString>;