@browserbasehq/orca 3.0.9-alpha-3 → 3.1.0-headers

package/dist/cjs/lib/v3/agent/utils/screenshotHandler.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitAndCaptureScreenshot = waitAndCaptureScreenshot;
+/**
+ * Default delay in milliseconds to wait after vision actions before capturing screenshot.
+ * Allows the page to settle after interactions.
+ */
+const DEFAULT_DELAY_MS = 500;
+/**
+ * Waits for the page to settle and captures a screenshot.
+ * If the screenshot fails (e.g., page closed, navigation in progress),
+ * returns undefined instead of throwing - allowing the action to still succeed.
+ *
+ * @param page - The page to capture
+ * @param delayMs - Delay before capturing (default: 500ms, pass 0 to skip delay)
+ */
+async function waitAndCaptureScreenshot(page, delayMs = DEFAULT_DELAY_MS) {
+    if (delayMs > 0) {
+        await page.waitForTimeout(delayMs);
+    }
+    try {
+        const buffer = await page.screenshot({ fullPage: false });
+        return buffer.toString("base64");
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=screenshotHandler.js.map

package/dist/cjs/lib/v3/agent/utils/screenshotHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshotHandler.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/screenshotHandler.ts"],"names":[],"mappings":";;AAgBA,4DAcC;AA5BD;;;GAGG;AACH,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B;;;;;;;GAOG;AACI,KAAK,UAAU,wBAAwB,CAC5C,IAAU,EACV,UAAkB,gBAAgB;IAElC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1D,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC","sourcesContent":["import type { Page } from \"../../understudy/page.js\";\n\n/**\n * Default delay in milliseconds to wait after vision actions before capturing screenshot.\n * Allows the page to settle after interactions.\n */\nconst DEFAULT_DELAY_MS = 500;\n\n/**\n * Waits for the page to settle and captures a screenshot.\n * If the screenshot fails (e.g., page closed, navigation in progress),\n * returns undefined instead of throwing - allowing the action to still succeed.\n *\n * @param page - The page to capture\n * @param delayMs - Delay before capturing (default: 500ms, pass 0 to skip delay)\n */\nexport async function waitAndCaptureScreenshot(\n  page: Page,\n  delayMs: number = DEFAULT_DELAY_MS,\n): Promise<string | undefined> {\n  if (delayMs > 0) {\n    await page.waitForTimeout(delayMs);\n  }\n\n  try {\n    const buffer = await page.screenshot({ fullPage: false });\n    return buffer.toString(\"base64\");\n  } catch {\n    return undefined;\n  }\n}\n"]}

package/dist/cjs/lib/v3/agent/utils/validateExperimentalFeatures.d.ts

@@ -0,0 +1,26 @@
+import type { AgentConfig, AgentExecuteOptionsBase } from "../../types/public/index.js";
+export interface AgentValidationOptions {
+    /** Whether experimental mode is enabled */
+    isExperimental: boolean;
+    /** Agent config options (integrations, tools, stream, cua, etc.) */
+    agentConfig?: Partial<AgentConfig>;
+    /** Execute options (callbacks, signal, messages, etc.) */
+    executeOptions?: (Partial<AgentExecuteOptionsBase> & {
+        callbacks?: unknown;
+    }) | null;
+    /** Whether this is streaming mode (can be derived from agentConfig.stream) */
+    isStreaming?: boolean;
+}
+/**
+ * Validates agent configuration and experimental feature usage.
+ *
+ * This utility consolidates all validation checks for both CUA and non-CUA agent paths:
+ * - Invalid argument errors for CUA (streaming, abort signal, message continuation, excludeTools, output schema are not supported)
+ * - Experimental feature checks for integrations and tools (both CUA and non-CUA)
+ * - Experimental feature checks for hybrid mode (requires experimental: true)
+ * - Experimental feature checks for non-CUA only (callbacks, signal, messages, streaming, excludeTools, output schema)
+ *
+ * Throws StagehandInvalidArgumentError for invalid/unsupported configurations.
+ * Throws ExperimentalNotConfiguredError if experimental features are used without experimental mode.
+ */
+export declare function validateExperimentalFeatures(options: AgentValidationOptions): void;

package/dist/cjs/lib/v3/agent/utils/validateExperimentalFeatures.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateExperimentalFeatures = validateExperimentalFeatures;
+const sdkErrors_js_1 = require("../../types/public/sdkErrors.js");
+/**
+ * Validates agent configuration and experimental feature usage.
+ *
+ * This utility consolidates all validation checks for both CUA and non-CUA agent paths:
+ * - Invalid argument errors for CUA (streaming, abort signal, message continuation, excludeTools, output schema are not supported)
+ * - Experimental feature checks for integrations and tools (both CUA and non-CUA)
+ * - Experimental feature checks for hybrid mode (requires experimental: true)
+ * - Experimental feature checks for non-CUA only (callbacks, signal, messages, streaming, excludeTools, output schema)
+ *
+ * Throws StagehandInvalidArgumentError for invalid/unsupported configurations.
+ * Throws ExperimentalNotConfiguredError if experimental features are used without experimental mode.
+ */
+function validateExperimentalFeatures(options) {
+    const { isExperimental, agentConfig, executeOptions, isStreaming } = options;
+    // Check if CUA mode is enabled (via mode: "cua" or deprecated cua: true)
+    const isCuaMode = agentConfig?.mode !== undefined
+        ? agentConfig.mode === "cua"
+        : agentConfig?.cua === true;
+    // CUA-specific validation: certain features are not available at all
+    if (isCuaMode) {
+        const unsupportedFeatures = [];
+        if (agentConfig?.stream) {
+            unsupportedFeatures.push("streaming");
+        }
+        if (executeOptions?.signal) {
+            unsupportedFeatures.push("abort signal");
+        }
+        if (executeOptions?.messages) {
+            unsupportedFeatures.push("message continuation");
+        }
+        if (executeOptions?.excludeTools &&
+            executeOptions.excludeTools.length > 0) {
+            unsupportedFeatures.push("excludeTools");
+        }
+        if (executeOptions?.output) {
+            unsupportedFeatures.push("output schema");
+        }
+        if (executeOptions?.variables &&
+            Object.keys(executeOptions.variables).length > 0) {
+            unsupportedFeatures.push("variables");
+        }
+        if (unsupportedFeatures.length > 0) {
+            throw new sdkErrors_js_1.StagehandInvalidArgumentError(`${unsupportedFeatures.join(", ")} ${unsupportedFeatures.length === 1 ? "is" : "are"} not supported with CUA (Computer Use Agent) mode.`);
+        }
+    }
+    // Skip experimental checks if already in experimental mode
+    if (isExperimental)
+        return;
+    const features = [];
+    // Check agent config features (check array length to avoid false positives for empty arrays)
+    const hasIntegrations = agentConfig?.integrations && agentConfig.integrations.length > 0;
+    const hasTools = agentConfig?.tools && Object.keys(agentConfig.tools).length > 0;
+    if (hasIntegrations || hasTools) {
+        features.push("MCP integrations and custom tools");
+    }
+    // Check streaming mode (either explicit or derived from config) - only for non-CUA
+    if (!isCuaMode && (isStreaming || agentConfig?.stream)) {
+        features.push("streaming");
+    }
+    // Check execute options features - only for non-CUA
+    if (executeOptions && !isCuaMode) {
+        if (executeOptions.callbacks) {
+            features.push("callbacks");
+        }
+        if (executeOptions.signal) {
+            features.push("abort signal");
+        }
+        if (executeOptions.messages) {
+            features.push("message continuation");
+        }
+        if (executeOptions.excludeTools && executeOptions.excludeTools.length > 0) {
+            features.push("excludeTools");
+        }
+        if (executeOptions.output) {
+            features.push("output schema");
+        }
+        if (executeOptions.variables &&
+            Object.keys(executeOptions.variables).length > 0) {
+            features.push("variables");
+        }
+    }
+    if (features.length > 0) {
+        throw new sdkErrors_js_1.ExperimentalNotConfiguredError(`Agent ${features.join(", ")}`);
+    }
+}
+//# sourceMappingURL=validateExperimentalFeatures.js.map

package/dist/cjs/lib/v3/agent/utils/validateExperimentalFeatures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateExperimentalFeatures.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/validateExperimentalFeatures.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  ExperimentalNotConfiguredError,\n  StagehandInvalidArgumentError,\n} from \"../../types/public/sdkErrors.js\";\nimport type {\n  AgentConfig,\n  AgentExecuteOptionsBase,\n} from \"../../types/public/index.js\";\n\nexport interface AgentValidationOptions {\n  /** Whether experimental mode is enabled */\n  isExperimental: boolean;\n  /** Agent config options (integrations, tools, stream, cua, etc.) */\n  agentConfig?: Partial<AgentConfig>;\n  /** Execute options (callbacks, signal, messages, etc.) */\n  executeOptions?:\n    | (Partial<AgentExecuteOptionsBase> & { callbacks?: unknown })\n    | null;\n  /** Whether this is streaming mode (can be derived from agentConfig.stream) */\n  isStreaming?: boolean;\n}\n\n/**\n * Validates agent configuration and experimental feature usage.\n *\n * This utility consolidates all validation checks for both CUA and non-CUA agent paths:\n * - Invalid argument errors for CUA (streaming, abort signal, message continuation, excludeTools, output schema are not supported)\n * - Experimental feature checks for integrations and tools (both CUA and non-CUA)\n * - Experimental feature checks for hybrid mode (requires experimental: true)\n * - Experimental feature checks for non-CUA only (callbacks, signal, messages, streaming, excludeTools, output schema)\n *\n * Throws StagehandInvalidArgumentError for invalid/unsupported configurations.\n * Throws ExperimentalNotConfiguredError if experimental features are used without experimental mode.\n */\nexport function validateExperimentalFeatures(\n  options: AgentValidationOptions,\n): void {\n  const { isExperimental, agentConfig, executeOptions, isStreaming } = options;\n\n  // Check if CUA mode is enabled (via mode: \"cua\" or deprecated cua: true)\n  const isCuaMode =\n    agentConfig?.mode !== undefined\n      ? agentConfig.mode === \"cua\"\n      : agentConfig?.cua === true;\n\n  // CUA-specific validation: certain features are not available at all\n  if (isCuaMode) {\n    const unsupportedFeatures: string[] = [];\n\n    if (agentConfig?.stream) {\n      unsupportedFeatures.push(\"streaming\");\n    }\n    if (executeOptions?.signal) {\n      unsupportedFeatures.push(\"abort signal\");\n    }\n    if (executeOptions?.messages) {\n      unsupportedFeatures.push(\"message continuation\");\n    }\n    if (\n      executeOptions?.excludeTools &&\n      executeOptions.excludeTools.length > 0\n    ) {\n      unsupportedFeatures.push(\"excludeTools\");\n    }\n    if (executeOptions?.output) {\n      unsupportedFeatures.push(\"output schema\");\n    }\n    if (\n      executeOptions?.variables &&\n      Object.keys(executeOptions.variables).length > 0\n    ) {\n      unsupportedFeatures.push(\"variables\");\n    }\n\n    if (unsupportedFeatures.length > 0) {\n      throw new StagehandInvalidArgumentError(\n        `${unsupportedFeatures.join(\", \")} ${unsupportedFeatures.length === 1 ? \"is\" : \"are\"} not supported with CUA (Computer Use Agent) mode.`,\n      );\n    }\n  }\n\n  // Skip experimental checks if already in experimental mode\n  if (isExperimental) return;\n\n  const features: string[] = [];\n\n  // Check agent config features (check array length to avoid false positives for empty arrays)\n  const hasIntegrations =\n    agentConfig?.integrations && agentConfig.integrations.length > 0;\n  const hasTools =\n    agentConfig?.tools && Object.keys(agentConfig.tools).length > 0;\n  if (hasIntegrations || hasTools) {\n    features.push(\"MCP integrations and custom tools\");\n  }\n\n  // Check streaming mode (either explicit or derived from config) - only for non-CUA\n  if (!isCuaMode && (isStreaming || agentConfig?.stream)) {\n    features.push(\"streaming\");\n  }\n\n  // Check execute options features - only for non-CUA\n  if (executeOptions && !isCuaMode) {\n    if (executeOptions.callbacks) {\n      features.push(\"callbacks\");\n    }\n    if (executeOptions.signal) {\n      features.push(\"abort signal\");\n    }\n    if (executeOptions.messages) {\n      features.push(\"message continuation\");\n    }\n    if (executeOptions.excludeTools && executeOptions.excludeTools.length > 0) {\n      features.push(\"excludeTools\");\n    }\n    if (executeOptions.output) {\n      features.push(\"output schema\");\n    }\n    if (\n      executeOptions.variables &&\n      Object.keys(executeOptions.variables).length > 0\n    ) {\n      features.push(\"variables\");\n    }\n  }\n\n  if (features.length > 0) {\n    throw new ExperimentalNotConfiguredError(`Agent ${features.join(\", \")}`);\n  }\n}\n"]}

package/dist/cjs/lib/v3/agent/utils/variables.d.ts

@@ -0,0 +1,21 @@
+import type { Variables, VariableValue } from "../../types/public/agent.js";
+/**
+ * Resolves a VariableValue to its primitive string value.
+ * Handles both simple primitives ("secret") and rich objects ({ value: "secret", description: "..." }).
+ */
+export declare function resolveVariableValue(v: VariableValue): string;
+/**
+ * Extracts the optional description from a VariableValue.
+ * Returns undefined for simple primitive values.
+ */
+export declare function getVariableDescription(v: VariableValue): string | undefined;
+/**
+ * Substitutes %variableName% tokens in text with resolved variable values.
+ * Works with both simple and rich variable formats.
+ */
+export declare function substituteVariables(text: string, variables?: Variables): string;
+/**
+ * Flattens Variables to Record<string, string> for internal consumers
+ * that only need key→value mappings (e.g., actHandler, cache replay).
+ */
+export declare function flattenVariables(variables?: Variables): Record<string, string> | undefined;

package/dist/cjs/lib/v3/agent/utils/variables.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVariableValue = resolveVariableValue;
+exports.getVariableDescription = getVariableDescription;
+exports.substituteVariables = substituteVariables;
+exports.flattenVariables = flattenVariables;
+/**
+ * Resolves a VariableValue to its primitive string value.
+ * Handles both simple primitives ("secret") and rich objects ({ value: "secret", description: "..." }).
+ */
+function resolveVariableValue(v) {
+    if (typeof v === "object" && v !== null && "value" in v) {
+        return String(v.value);
+    }
+    return String(v);
+}
+/**
+ * Extracts the optional description from a VariableValue.
+ * Returns undefined for simple primitive values.
+ */
+function getVariableDescription(v) {
+    if (typeof v === "object" && v !== null && "value" in v) {
+        return v.description;
+    }
+    return undefined;
+}
+/**
+ * Substitutes %variableName% tokens in text with resolved variable values.
+ * Works with both simple and rich variable formats.
+ */
+function substituteVariables(text, variables) {
+    if (!variables)
+        return text;
+    let result = text;
+    for (const [key, v] of Object.entries(variables)) {
+        const token = `%${key}%`;
+        result = result.split(token).join(resolveVariableValue(v));
+    }
+    return result;
+}
+/**
+ * Flattens Variables to Record<string, string> for internal consumers
+ * that only need key→value mappings (e.g., actHandler, cache replay).
+ */
+function flattenVariables(variables) {
+    if (!variables || Object.keys(variables).length === 0)
+        return undefined;
+    const result = {};
+    for (const [key, v] of Object.entries(variables)) {
+        result[key] = resolveVariableValue(v);
+    }
+    return result;
+}
+//# sourceMappingURL=variables.js.map

package/dist/cjs/lib/v3/agent/utils/variables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/variables.ts"],"names":[],"mappings":";;AAMA,oDAKC;AAMD,wDAKC;AAMD,kDAWC;AAMD,4CASC;AApDD;;;GAGG;AACH,SAAgB,oBAAoB,CAAC,CAAgB;IACnD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QACxD,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAgB,sBAAsB,CAAC,CAAgB;IACrD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QACxD,OAAO,CAAC,CAAC,WAAW,CAAC;IACvB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAgB,mBAAmB,CACjC,IAAY,EACZ,SAAqB;IAErB,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,IAAI,GAAG,GAAG,CAAC;QACzB,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAC9B,SAAqB;IAErB,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACxE,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACjD,MAAM,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import type { Variables, VariableValue } from \"../../types/public/agent.js\";\n\n/**\n * Resolves a VariableValue to its primitive string value.\n * Handles both simple primitives (\"secret\") and rich objects ({ value: \"secret\", description: \"...\" }).\n */\nexport function resolveVariableValue(v: VariableValue): string {\n  if (typeof v === \"object\" && v !== null && \"value\" in v) {\n    return String(v.value);\n  }\n  return String(v);\n}\n\n/**\n * Extracts the optional description from a VariableValue.\n * Returns undefined for simple primitive values.\n */\nexport function getVariableDescription(v: VariableValue): string | undefined {\n  if (typeof v === \"object\" && v !== null && \"value\" in v) {\n    return v.description;\n  }\n  return undefined;\n}\n\n/**\n * Substitutes %variableName% tokens in text with resolved variable values.\n * Works with both simple and rich variable formats.\n */\nexport function substituteVariables(\n  text: string,\n  variables?: Variables,\n): string {\n  if (!variables) return text;\n  let result = text;\n  for (const [key, v] of Object.entries(variables)) {\n    const token = `%${key}%`;\n    result = result.split(token).join(resolveVariableValue(v));\n  }\n  return result;\n}\n\n/**\n * Flattens Variables to Record<string, string> for internal consumers\n * that only need key→value mappings (e.g., actHandler, cache replay).\n */\nexport function flattenVariables(\n  variables?: Variables,\n): Record<string, string> | undefined {\n  if (!variables || Object.keys(variables).length === 0) return undefined;\n  const result: Record<string, string> = {};\n  for (const [key, v] of Object.entries(variables)) {\n    result[key] = resolveVariableValue(v);\n  }\n  return result;\n}\n"]}

package/dist/cjs/lib/v3/agent/utils/xpath.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Utility functions for XPath handling in agent tools.
+ */
+/**
+ * Ensures a value is properly formatted as an XPath selector.
+ * Returns null if the value is not a valid string.
+ *
+ * @param value - The value to normalize as an XPath
+ * @returns The normalized XPath string prefixed with "xpath=" or null
+ */
+export declare function ensureXPath(value: unknown): string | null;

package/dist/cjs/lib/v3/agent/utils/xpath.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Utility functions for XPath handling in agent tools.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureXPath = ensureXPath;
+/**
+ * Ensures a value is properly formatted as an XPath selector.
+ * Returns null if the value is not a valid string.
+ *
+ * @param value - The value to normalize as an XPath
+ * @returns The normalized XPath string prefixed with "xpath=" or null
+ */
+function ensureXPath(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    return trimmed.startsWith("xpath=") ? trimmed : `xpath=${trimmed}`;
+}
+//# sourceMappingURL=xpath.js.map

package/dist/cjs/lib/v3/agent/utils/xpath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xpath.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/xpath.ts"],"names":[],"mappings":";AAAA;;GAEG;;AASH,kCAKC;AAZD;;;;;;GAMG;AACH,SAAgB,WAAW,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAO,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC;AACrE,CAAC","sourcesContent":["/**\n * Utility functions for XPath handling in agent tools.\n */\n\n/**\n * Ensures a value is properly formatted as an XPath selector.\n * Returns null if the value is not a valid string.\n *\n * @param value - The value to normalize as an XPath\n * @returns The normalized XPath string prefixed with \"xpath=\" or null\n */\nexport function ensureXPath(value: unknown): string | null {\n  if (typeof value !== \"string\") return null;\n  const trimmed = value.trim();\n  if (!trimmed) return null;\n  return trimmed.startsWith(\"xpath=\") ? trimmed : `xpath=${trimmed}`;\n}\n"]}

package/dist/cjs/lib/v3/api.d.ts

@@ -0,0 +1,119 @@
+import type { ActResult, AgentConfig, AgentExecuteOptions, AgentResult, ExtractResult, ObserveResult, LogLine, StagehandMetrics, BrowserbaseRegion, ActOptions, ExtractOptions, ObserveOptions, Api } from "./types/public/index.js";
+import type { SerializableResponse, AgentCacheTransferPayload } from "./types/private/index.js";
+import type { StagehandZodSchema } from "./zodCompat.js";
+/**
+ * Mapping of Browserbase regions to their corresponding Stagehand API base URLs.
+ * Users should configure their client to hit the API endpoint that matches
+ * the region where their browser session is running.
+ */
+export declare const REGION_API_URLS: Record<BrowserbaseRegion, string>;
+/**
+ * Returns the full API URL (with /v1 suffix) for a given Browserbase region.
+ * If no region is specified or the region is unknown, defaults to us-west-2.
+ *
+ * @param region - The Browserbase region (e.g., "us-west-2", "eu-central-1")
+ * @returns The full API URL including /v1 suffix
+ */
+export declare function getApiUrlForRegion(region: BrowserbaseRegion | undefined): string;
+/**
+ * Constructor parameters for StagehandAPIClient
+ */
+interface StagehandAPIConstructorParams {
+    apiKey: string;
+    projectId?: string;
+    logger: (message: LogLine) => void;
+    /**
+     * When true, enables server-side caching by default for all requests.
+     * When false, disables server-side caching.
+     * Defaults to true (caching enabled).
+     * Can be overridden per-method in act(), extract(), and observe() options.
+     */
+    serverCache?: boolean;
+}
+/**
+ * Parameters for starting a session via the API client.
+ * Extends Api.SessionStartRequest with client-specific field (modelApiKey).
+ *
+ * Wire format: Api.SessionStartRequest (modelApiKey sent via header, not body)
+ */
+interface ClientSessionStartParams extends Api.SessionStartRequest {
+    /** Model API key - sent via x-model-api-key header, not in request body */
+    modelApiKey: string;
+}
+/**
+ * Client parameters for act() method.
+ * Derives structure from Api.ActRequest but uses SDK's ActOptions (which includes `page`).
+ * Before serialization, `page` is stripped to produce Api.ActRequest wire format.
+ */
+interface ClientActParameters {
+    input: Api.ActRequest["input"];
+    options?: ActOptions;
+    frameId?: Api.ActRequest["frameId"];
+}
+/**
+ * Client parameters for extract() method.
+ * Derives structure from Api.ExtractRequest but uses SDK's ExtractOptions (which includes `page`)
+ * and accepts Zod schema (converted to JSON schema for wire format).
+ */
+interface ClientExtractParameters {
+    instruction?: Api.ExtractRequest["instruction"];
+    schema?: StagehandZodSchema;
+    options?: ExtractOptions;
+    frameId?: Api.ExtractRequest["frameId"];
+}
+/**
+ * Client parameters for observe() method.
+ * Derives structure from Api.ObserveRequest but uses SDK's ObserveOptions (which includes `page`).
+ * Before serialization, `page` is stripped to produce Api.ObserveRequest wire format.
+ */
+interface ClientObserveParameters {
+    instruction?: Api.ObserveRequest["instruction"];
+    options?: ObserveOptions;
+    frameId?: Api.ObserveRequest["frameId"];
+}
+export declare class StagehandAPIClient {
+    private apiKey;
+    private projectId?;
+    private sessionId?;
+    private modelApiKey;
+    private modelProvider?;
+    private region?;
+    private logger;
+    private fetchWithCookies;
+    private serverCache;
+    private lastFinishedEventData;
+    private latestAgentCacheEntry;
+    constructor({ apiKey, projectId, logger, serverCache, }: StagehandAPIConstructorParams);
+    init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, systemPrompt, selfHeal, browserbaseSessionCreateParams, browserbaseSessionID, }: ClientSessionStartParams): Promise<Api.SessionStartResult>;
+    act({ input, options, frameId, }: ClientActParameters): Promise<ActResult>;
+    extract<T extends StagehandZodSchema>({ instruction, schema: zodSchema, options, frameId, }: ClientExtractParameters): Promise<ExtractResult<T>>;
+    observe({ instruction, options, frameId, }: ClientObserveParameters): Promise<ObserveResult>;
+    goto(url: string, options?: Api.NavigateRequest["options"], frameId?: string): Promise<SerializableResponse | null>;
+    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions | string, frameId?: string, shouldCache?: boolean): Promise<AgentResult>;
+    consumeLatestAgentCacheEntry(): AgentCacheTransferPayload | null;
+    end(): Promise<Response>;
+    getReplayMetrics(): Promise<StagehandMetrics>;
+    /**
+     * Prepares a model configuration for the API payload by ensuring the `apiKey`
+     * is included. If the model is passed as a string, converts it to an object
+     * with `modelName` and `apiKey`.
+     *
+     * In API mode, we only attempt to load an API key from env vars when the
+     * model provider differs from the one used to init the session.
+     */
+    private prepareModelConfig;
+    private consumeFinishedEventData;
+    private execute;
+    /**
+     * Resolves the final cache status from the response header or SSE event data,
+     * logs it, and attaches it to act/extract results before returning.
+     */
+    private attachCacheStatus;
+    /**
+     * Determine if caching should be enabled for a request.
+     * Method-level setting takes precedence over instance-level setting.
+     */
+    private shouldUseCache;
+    private request;
+}
+export {};