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

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.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

@@ -1,4 +1,4 @@
-import type { Action, ActResult, AgentConfig, AgentExecuteOptions, AgentResult, ExtractResult, LogLine, StagehandMetrics, BrowserbaseRegion, ActOptions, ExtractOptions, ObserveOptions, Api } from "./types/public/index.js";
+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";
 /**
@@ -20,8 +20,15 @@ export declare function getApiUrlForRegion(region: BrowserbaseRegion | undefined
  */
 interface StagehandAPIConstructorParams {
     apiKey: string;
-    projectId: 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.
@@ -66,20 +73,21 @@ interface ClientObserveParameters {
 }
 export declare class StagehandAPIClient {
     private apiKey;
-    private projectId;
+    private projectId?;
     private sessionId?;
     private modelApiKey;
     private modelProvider?;
     private region?;
     private logger;
     private fetchWithCookies;
+    private serverCache;
     private lastFinishedEventData;
     private latestAgentCacheEntry;
-    constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams);
+    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<Action[]>;
+    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;
@@ -96,6 +104,16 @@ export declare class StagehandAPIClient {
     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 {};