@browserbasehq/orca 3.1.0-patch.0 → 3.1.0-patch.2

package/dist/cjs/tests/zod-enum-compatibility.test.js

@@ -0,0 +1,119 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var import_vitest = require("vitest");
+var z3 = __toESM(require("zod/v3"), 1);
+var import_zod = require("zod");
+var import_handlers = require("../lib/v3/types/private/handlers.js");
+(0, import_vitest.describe)("SupportedUnderstudyAction enum Zod compatibility", () => {
+  const testInput = {
+    elementId: "1-2",
+    method: "click",
+    arguments: []
+  };
+  const invalidInput = {
+    elementId: "1-2",
+    method: "invalidMethod",
+    arguments: []
+  };
+  (0, import_vitest.it)("Object.values(SupportedUnderstudyAction) produces correct array for z.enum()", () => {
+    const enumValues = Object.values(
+      import_handlers.SupportedUnderstudyAction
+    );
+    (0, import_vitest.expect)(enumValues).toContain("click");
+    (0, import_vitest.expect)(enumValues).toContain("fill");
+    (0, import_vitest.expect)(enumValues).toContain("type");
+    (0, import_vitest.expect)(enumValues).toContain("press");
+    (0, import_vitest.expect)(enumValues).toContain("scrollTo");
+    (0, import_vitest.expect)(enumValues).toContain("nextChunk");
+    (0, import_vitest.expect)(enumValues).toContain("prevChunk");
+    (0, import_vitest.expect)(enumValues).toContain("selectOptionFromDropdown");
+    (0, import_vitest.expect)(enumValues).toContain("hover");
+    (0, import_vitest.expect)(enumValues).toContain("doubleClick");
+    (0, import_vitest.expect)(enumValues).toContain("dragAndDrop");
+    (0, import_vitest.expect)(enumValues.length).toBe(11);
+  });
+  (0, import_vitest.it)("Zod v3 z.enum() with Object.values(SupportedUnderstudyAction) works correctly", () => {
+    const enumValues = Object.values(
+      import_handlers.SupportedUnderstudyAction
+    );
+    const schema = z3.z.object({
+      elementId: z3.z.string(),
+      method: z3.z.enum(enumValues),
+      arguments: z3.z.array(z3.z.string())
+    });
+    const validResult = schema.safeParse(testInput);
+    (0, import_vitest.expect)(validResult.success).toBe(true);
+    if (validResult.success) {
+      (0, import_vitest.expect)(validResult.data.method).toBe("click");
+    }
+    const invalidResult = schema.safeParse(invalidInput);
+    (0, import_vitest.expect)(invalidResult.success).toBe(false);
+  });
+  (0, import_vitest.it)("Zod v4 z.enum() with Object.values(SupportedUnderstudyAction) works correctly", () => {
+    const enumValues = Object.values(
+      import_handlers.SupportedUnderstudyAction
+    );
+    const schema = import_zod.z.object({
+      elementId: import_zod.z.string(),
+      method: import_zod.z.enum(enumValues),
+      arguments: import_zod.z.array(import_zod.z.string())
+    });
+    const validResult = schema.safeParse(testInput);
+    (0, import_vitest.expect)(validResult.success).toBe(true);
+    if (validResult.success) {
+      (0, import_vitest.expect)(validResult.data.method).toBe("click");
+    }
+    const invalidResult = schema.safeParse(invalidInput);
+    (0, import_vitest.expect)(invalidResult.success).toBe(false);
+  });
+  (0, import_vitest.it)("Zod v3 z.enum() with raw TypeScript enum throws error on parse", () => {
+    const schema = z3.z.object({
+      elementId: z3.z.string(),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      method: z3.z.enum(import_handlers.SupportedUnderstudyAction),
+      arguments: z3.z.array(z3.z.string())
+    });
+    (0, import_vitest.expect)(() => schema.safeParse(testInput)).toThrow("object is not iterable");
+  });
+  (0, import_vitest.it)("Zod v4 z.enum() with raw TypeScript enum works (but not v3 compatible)", () => {
+    const schema = import_zod.z.object({
+      elementId: import_zod.z.string(),
+      method: import_zod.z.enum(import_handlers.SupportedUnderstudyAction),
+      arguments: import_zod.z.array(import_zod.z.string())
+    });
+    const validResult = schema.safeParse(testInput);
+    (0, import_vitest.expect)(validResult.success).toBe(true);
+  });
+  (0, import_vitest.it)("All SupportedUnderstudyAction values are valid enum options", () => {
+    const enumValues = Object.values(
+      import_handlers.SupportedUnderstudyAction
+    );
+    const v3Schema = z3.z.enum(enumValues);
+    const v4Schema = import_zod.z.enum(enumValues);
+    for (const action of enumValues) {
+      (0, import_vitest.expect)(v3Schema.safeParse(action).success).toBe(true);
+      (0, import_vitest.expect)(v4Schema.safeParse(action).success).toBe(true);
+    }
+  });
+});
+//# sourceMappingURL=zod-enum-compatibility.test.js.map

package/dist/cjs/tests/zod-enum-compatibility.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/zod-enum-compatibility.test.ts"],
+  "sourcesContent": ["import { describe, expect, it } from \"vitest\";\nimport * as z3 from \"zod/v3\";\nimport { z as z4 } from \"zod\";\nimport { SupportedUnderstudyAction } from \"../lib/v3/types/private/handlers.js\";\n\n/**\n * Tests for Zod v3/v4 compatibility with the SupportedUnderstudyAction enum.\n *\n * This test ensures that z.enum() works correctly with both Zod v3 and v4.\n * The key issue is that z.enum() in Zod v3 does NOT accept TypeScript enums directly -\n * it only accepts string literal tuples. For TypeScript enums, you need to use\n * Object.values() to convert the enum to an array first.\n *\n * In Zod v4, z.enum() was updated to accept TypeScript enums directly, but for\n * backwards compatibility, we should use Object.values() which works with both.\n *\n * See PR #1613: https://github.com/browserbase/stagehand/pull/1613\n */\ndescribe(\"SupportedUnderstudyAction enum Zod compatibility\", () => {\n  const testInput = {\n    elementId: \"1-2\",\n    method: \"click\",\n    arguments: [] as string[],\n  };\n\n  const invalidInput = {\n    elementId: \"1-2\",\n    method: \"invalidMethod\",\n    arguments: [] as string[],\n  };\n\n  it(\"Object.values(SupportedUnderstudyAction) produces correct array for z.enum()\", () => {\n    const enumValues = Object.values(\n      SupportedUnderstudyAction,\n    ) as unknown as readonly [string, ...string[]];\n\n    expect(enumValues).toContain(\"click\");\n    expect(enumValues).toContain(\"fill\");\n    expect(enumValues).toContain(\"type\");\n    expect(enumValues).toContain(\"press\");\n    expect(enumValues).toContain(\"scrollTo\");\n    expect(enumValues).toContain(\"nextChunk\");\n    expect(enumValues).toContain(\"prevChunk\");\n    expect(enumValues).toContain(\"selectOptionFromDropdown\");\n    expect(enumValues).toContain(\"hover\");\n    expect(enumValues).toContain(\"doubleClick\");\n    expect(enumValues).toContain(\"dragAndDrop\");\n    expect(enumValues.length).toBe(11);\n  });\n\n  it(\"Zod v3 z.enum() with Object.values(SupportedUnderstudyAction) works correctly\", () => {\n    const enumValues = Object.values(\n      SupportedUnderstudyAction,\n    ) as unknown as readonly [string, ...string[]];\n\n    const schema = z3.z.object({\n      elementId: z3.z.string(),\n      method: z3.z.enum(enumValues),\n      arguments: z3.z.array(z3.z.string()),\n    });\n\n    // Valid input should pass\n    const validResult = schema.safeParse(testInput);\n    expect(validResult.success).toBe(true);\n    if (validResult.success) {\n      expect(validResult.data.method).toBe(\"click\");\n    }\n\n    // Invalid input should fail\n    const invalidResult = schema.safeParse(invalidInput);\n    expect(invalidResult.success).toBe(false);\n  });\n\n  it(\"Zod v4 z.enum() with Object.values(SupportedUnderstudyAction) works correctly\", () => {\n    const enumValues = Object.values(\n      SupportedUnderstudyAction,\n    ) as unknown as readonly [string, ...string[]];\n\n    const schema = z4.object({\n      elementId: z4.string(),\n      method: z4.enum(enumValues),\n      arguments: z4.array(z4.string()),\n    });\n\n    // Valid input should pass\n    const validResult = schema.safeParse(testInput);\n    expect(validResult.success).toBe(true);\n    if (validResult.success) {\n      expect(validResult.data.method).toBe(\"click\");\n    }\n\n    // Invalid input should fail\n    const invalidResult = schema.safeParse(invalidInput);\n    expect(invalidResult.success).toBe(false);\n  });\n\n  it(\"Zod v3 z.enum() with raw TypeScript enum throws error on parse\", () => {\n    // This demonstrates the bug that PR #1613 would introduce\n    // In Zod v3, z.enum() does NOT accept TypeScript enums directly\n    // The schema creation might succeed, but parsing will fail\n\n    const schema = z3.z.object({\n      elementId: z3.z.string(),\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      method: z3.z.enum(SupportedUnderstudyAction as any),\n      arguments: z3.z.array(z3.z.string()),\n    });\n\n    // This should throw an error because the enum is not iterable\n    expect(() => schema.safeParse(testInput)).toThrow(\"object is not iterable\");\n  });\n\n  it(\"Zod v4 z.enum() with raw TypeScript enum works (but not v3 compatible)\", () => {\n    // Zod v4 allows passing TypeScript enums directly to z.enum()\n    // But this approach is NOT backwards compatible with v3\n\n    const schema = z4.object({\n      elementId: z4.string(),\n      method: z4.enum(SupportedUnderstudyAction),\n      arguments: z4.array(z4.string()),\n    });\n\n    // In v4, this works fine\n    const validResult = schema.safeParse(testInput);\n    expect(validResult.success).toBe(true);\n  });\n\n  it(\"All SupportedUnderstudyAction values are valid enum options\", () => {\n    const enumValues = Object.values(\n      SupportedUnderstudyAction,\n    ) as unknown as readonly [string, ...string[]];\n\n    // Test with both v3 and v4 schemas\n    const v3Schema = z3.z.enum(enumValues);\n    const v4Schema = z4.enum(enumValues);\n\n    for (const action of enumValues) {\n      expect(v3Schema.safeParse(action).success).toBe(true);\n      expect(v4Schema.safeParse(action).success).toBe(true);\n    }\n  });\n});\n"],
+  "mappings": "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",
+  "names": ["z4"]
+}

package/dist/esm/index.d.ts

@@ -1,3 +1,3 @@
-import * as Stagehand from "./lib/v3/index";
-export * from "./lib/v3/index";
+import * as Stagehand from "./lib/v3/index.js";
+export * from "./lib/v3/index.js";
 export default Stagehand;

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

@@ -1,6 +1,20 @@
-import type { Action, ActResult, AgentConfig, AgentExecuteOptions, AgentResult, ExtractResult, LogLine, StagehandMetrics, ActOptions, ExtractOptions, ObserveOptions, Api } from "./types/public/index.js";
+import type { Action, ActResult, AgentConfig, AgentExecuteOptions, AgentResult, ExtractResult, 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
  */
@@ -56,6 +70,7 @@ export declare class StagehandAPIClient {
     private sessionId?;
     private modelApiKey;
     private modelProvider?;
+    private region?;
     private logger;
     private fetchWithCookies;
     private lastFinishedEventData;

package/dist/esm/lib/v3/api.js

@@ -3,12 +3,39 @@ import { loadApiKeyFromEnv } from "../utils.js";
 import { STAGEHAND_VERSION } from "../version.js";
 import { StagehandAPIError, StagehandAPIUnauthorizedError, StagehandHttpError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, ExperimentalNotConfiguredError, } from "./types/public/index.js";
 import { toJsonSchema } from "./zodCompat.js";
+// =============================================================================
+// Multi-region API URL mapping
+// =============================================================================
+/**
+ * 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 const REGION_API_URLS = {
+    "us-west-2": "https://api.stagehand.browserbase.com",
+    "us-east-1": "https://api.use1.stagehand.browserbase.com",
+    "eu-central-1": "https://api.euc1.stagehand.browserbase.com",
+    "ap-southeast-1": "https://api.apse1.stagehand.browserbase.com",
+};
+/**
+ * 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 function getApiUrlForRegion(region) {
+    const baseUrl = REGION_API_URLS[region] ??
+        REGION_API_URLS["us-west-2"];
+    return `${baseUrl}/v1`;
+}
 export class StagehandAPIClient {
     apiKey;
     projectId;
     sessionId;
     modelApiKey;
     modelProvider;
+    region;
     logger;
     fetchWithCookies;
     lastFinishedEventData = null;
@@ -31,10 +58,8 @@ export class StagehandAPIClient {
         this.modelProvider = modelName?.includes("/")
             ? modelName.split("/")[0]
             : undefined;
-        const region = browserbaseSessionCreateParams?.region;
-        if (region && region !== "us-west-2") {
-            return { sessionId: browserbaseSessionID ?? null, available: false };
-        }
+        // Store the region for multi-region API URL resolution
+        this.region = browserbaseSessionCreateParams?.region;
         this.logger({
             category: "init",
             message: "Creating new browserbase session...",
@@ -471,7 +496,18 @@ export class StagehandAPIClient {
         if (options.method === "POST" && options.body) {
             defaultHeaders["Content-Type"] = "application/json";
         }
-        const response = await this.fetchWithCookies(`${process.env.STAGEHAND_API_URL ?? "https://api.stagehand.browserbase.com/v1"}${path}`, {
+        // Use STAGEHAND_API_URL env var if set, otherwise use region-based URL
+        // Ensure /v1 suffix is present for consistency
+        let baseUrl;
+        if (process.env.STAGEHAND_API_URL) {
+            const envUrl = process.env.STAGEHAND_API_URL.replace(/\/+$/, "");
+            // Append /v1 if not already present
+            baseUrl = envUrl.endsWith("/v1") ? envUrl : `${envUrl}/v1`;
+        }
+        else {
+            baseUrl = getApiUrlForRegion(this.region);
+        }
+        const response = await this.fetchWithCookies(`${baseUrl}${path}`, {
             ...options,
             headers: {
                 ...defaultHeaders,

package/dist/esm/lib/v3/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../../lib/v3/api.ts"],"names":[],"mappings":"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","sourcesContent":["import makeFetchCookie from \"fetch-cookie\";\nimport { loadApiKeyFromEnv } from \"../utils.js\";\nimport { STAGEHAND_VERSION } from \"../version.js\";\nimport {\n  StagehandAPIError,\n  StagehandAPIUnauthorizedError,\n  StagehandHttpError,\n  StagehandResponseBodyError,\n  StagehandResponseParseError,\n  StagehandServerError,\n  ExperimentalNotConfiguredError,\n} from \"./types/public/index.js\";\nimport type {\n  Action,\n  ActResult,\n  AgentConfig,\n  AgentExecuteOptions,\n  AgentResult,\n  ExtractResult,\n  LogLine,\n  StagehandMetrics,\n  ActOptions,\n  ExtractOptions,\n  ObserveOptions,\n  Api,\n} from \"./types/public/index.js\";\nimport type {\n  SerializableResponse,\n  AgentCacheTransferPayload,\n} from \"./types/private/index.js\";\nimport type { ModelConfiguration } from \"./types/public/model.js\";\nimport { toJsonSchema } from \"./zodCompat.js\";\nimport type { StagehandZodSchema } from \"./zodCompat.js\";\n\n// =============================================================================\n// Client-specific types (can't be Zod schemas due to functions/Page objects)\n// =============================================================================\n//\n// These types mirror the Api.* schemas from types/public/api.ts but include\n// non-serializable SDK fields (like Page objects) that get stripped before\n// sending requests over the wire.\n//\n// Relationship to wire format:\n// - Client accepts: SDK types (ActOptions, ExtractOptions, etc.) with optional `page`\n// - Wire sends: Api.* types (page stripped, Zod schema converted to JSON schema)\n// - Client returns: SDK result types (ActResult, ExtractResult, etc.)\n// =============================================================================\n\n/**\n * Constructor parameters for StagehandAPIClient\n */\ninterface StagehandAPIConstructorParams {\n  apiKey: string;\n  projectId: string;\n  logger: (message: LogLine) => void;\n}\n\n/**\n * Parameters for starting a session via the API client.\n * Extends Api.SessionStartRequest with client-specific field (modelApiKey).\n *\n * Wire format: Api.SessionStartRequest (modelApiKey sent via header, not body)\n */\ninterface ClientSessionStartParams extends Api.SessionStartRequest {\n  /** Model API key - sent via x-model-api-key header, not in request body */\n  modelApiKey: string;\n}\n\n/**\n * Generic API response wrapper matching Api.*Response schemas\n */\ntype ApiResponse<T> =\n  | { success: true; data: T }\n  | { success: false; message: string };\n\n/**\n * Union of all API request body types for type-safe execute() calls\n */\ntype ApiRequestBody =\n  | Api.ActRequest\n  | Api.ExtractRequest\n  | Api.ObserveRequest\n  | Api.NavigateRequest\n  | Api.AgentExecuteRequest;\n\n/**\n * Parameters for executing an action via the streaming API\n */\ninterface ExecuteActionParams {\n  method: \"act\" | \"extract\" | \"observe\" | \"navigate\" | \"end\" | \"agentExecute\";\n  args?: ApiRequestBody;\n  params?: Record<string, string>;\n}\n\n/**\n * Client parameters for act() method.\n * Derives structure from Api.ActRequest but uses SDK's ActOptions (which includes `page`).\n * Before serialization, `page` is stripped to produce Api.ActRequest wire format.\n */\ninterface ClientActParameters {\n  input: Api.ActRequest[\"input\"];\n  options?: ActOptions;\n  frameId?: Api.ActRequest[\"frameId\"];\n}\n\n/**\n * Client parameters for extract() method.\n * Derives structure from Api.ExtractRequest but uses SDK's ExtractOptions (which includes `page`)\n * and accepts Zod schema (converted to JSON schema for wire format).\n */\ninterface ClientExtractParameters {\n  instruction?: Api.ExtractRequest[\"instruction\"];\n  schema?: StagehandZodSchema;\n  options?: ExtractOptions;\n  frameId?: Api.ExtractRequest[\"frameId\"];\n}\n\n/**\n * Client parameters for observe() method.\n * Derives structure from Api.ObserveRequest but uses SDK's ObserveOptions (which includes `page`).\n * Before serialization, `page` is stripped to produce Api.ObserveRequest wire format.\n */\ninterface ClientObserveParameters {\n  instruction?: Api.ObserveRequest[\"instruction\"];\n  options?: ObserveOptions;\n  frameId?: Api.ObserveRequest[\"frameId\"];\n}\n\nexport class StagehandAPIClient {\n  private apiKey: string;\n  private projectId: string;\n  private sessionId?: string;\n  private modelApiKey: string;\n  private modelProvider?: string;\n  private logger: (message: LogLine) => void;\n  private fetchWithCookies;\n  private lastFinishedEventData: Record<string, unknown> | null = null;\n  private latestAgentCacheEntry: AgentCacheTransferPayload | null = null;\n\n  constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams) {\n    this.apiKey = apiKey;\n    this.projectId = projectId;\n    this.logger = logger;\n    // Create a single cookie jar instance that will persist across all requests\n    this.fetchWithCookies = makeFetchCookie(fetch);\n  }\n\n  async init({\n    modelName,\n    modelApiKey,\n    domSettleTimeoutMs,\n    verbose,\n    systemPrompt,\n    selfHeal,\n    browserbaseSessionCreateParams,\n    browserbaseSessionID,\n    // browser,  TODO for local browsers\n  }: ClientSessionStartParams): Promise<Api.SessionStartResult> {\n    if (!modelApiKey) {\n      throw new StagehandAPIError(\"modelApiKey is required\");\n    }\n    this.modelApiKey = modelApiKey;\n    // Extract provider from modelName (e.g., \"openai/gpt-5-nano\" -> \"openai\")\n    this.modelProvider = modelName?.includes(\"/\")\n      ? modelName.split(\"/\")[0]\n      : undefined;\n\n    const region = browserbaseSessionCreateParams?.region;\n    if (region && region !== \"us-west-2\") {\n      return { sessionId: browserbaseSessionID ?? null, available: false };\n    }\n\n    this.logger({\n      category: \"init\",\n      message: \"Creating new browserbase session...\",\n      level: 1,\n    });\n\n    // Build wire-format request body (Api.SessionStartRequest shape)\n    const requestBody: Api.SessionStartRequest = {\n      modelName,\n      domSettleTimeoutMs,\n      verbose,\n      systemPrompt,\n      selfHeal,\n      browserbaseSessionCreateParams,\n      browserbaseSessionID,\n      // browser, TODO: only send when connected to local fastify\n    };\n\n    const sessionResponse = await this.request(\"/sessions/start\", {\n      method: \"POST\",\n      body: JSON.stringify(requestBody),\n    });\n\n    if (sessionResponse.status === 401) {\n      throw new StagehandAPIUnauthorizedError(\n        \"Unauthorized. Ensure you provided a valid API key.\",\n      );\n    } else if (sessionResponse.status !== 200) {\n      const errorText = await sessionResponse.text();\n      this.logger({\n        category: \"api\",\n        message: `API error (${sessionResponse.status}): ${errorText}`,\n        level: 0,\n      });\n      throw new StagehandHttpError(`Unknown error: ${sessionResponse.status}`);\n    }\n\n    const sessionResponseBody =\n      (await sessionResponse.json()) as ApiResponse<Api.SessionStartResult>;\n\n    if (sessionResponseBody.success === false) {\n      throw new StagehandAPIError(sessionResponseBody.message);\n    }\n\n    // Temporary reroute for rollout\n    if (!sessionResponseBody.data?.available && browserbaseSessionID) {\n      sessionResponseBody.data.sessionId = browserbaseSessionID;\n    }\n\n    this.sessionId = sessionResponseBody.data.sessionId;\n\n    return sessionResponseBody.data;\n  }\n\n  async act({\n    input,\n    options,\n    frameId,\n  }: ClientActParameters): Promise<ActResult> {\n    // Strip non-serializable `page` from options before wire serialization\n    let wireOptions: Api.ActRequest[\"options\"];\n    if (options) {\n      // eslint-disable-next-line @typescript-eslint/no-unused-vars\n      const { page: _, ...restOptions } = options;\n      if (Object.keys(restOptions).length > 0) {\n        if (restOptions.model) {\n          restOptions.model = this.prepareModelConfig(restOptions.model);\n        }\n        wireOptions = restOptions as unknown as Api.ActRequest[\"options\"];\n      }\n    }\n\n    // Build wire-format request body\n    const requestBody: Api.ActRequest = {\n      input,\n      options: wireOptions,\n      frameId,\n    };\n\n    return this.execute<ActResult>({\n      method: \"act\",\n      args: requestBody,\n    });\n  }\n\n  async extract<T extends StagehandZodSchema>({\n    instruction,\n    schema: zodSchema,\n    options,\n    frameId,\n  }: ClientExtractParameters): Promise<ExtractResult<T>> {\n    // Convert Zod schema to JSON schema for wire format\n    const jsonSchema = zodSchema ? toJsonSchema(zodSchema) : undefined;\n\n    // Strip non-serializable `page` from options before wire serialization\n    let wireOptions: Api.ExtractRequest[\"options\"];\n    if (options) {\n      // eslint-disable-next-line @typescript-eslint/no-unused-vars\n      const { page: _, ...restOptions } = options;\n      if (Object.keys(restOptions).length > 0) {\n        if (restOptions.model) {\n          restOptions.model = this.prepareModelConfig(restOptions.model);\n        }\n        wireOptions = restOptions as unknown as Api.ExtractRequest[\"options\"];\n      }\n    }\n\n    // Build wire-format request body\n    const requestBody: Api.ExtractRequest = {\n      instruction,\n      schema: jsonSchema,\n      options: wireOptions,\n      frameId,\n    };\n\n    return this.execute<ExtractResult<T>>({\n      method: \"extract\",\n      args: requestBody,\n    });\n  }\n\n  async observe({\n    instruction,\n    options,\n    frameId,\n  }: ClientObserveParameters): Promise<Action[]> {\n    // Strip non-serializable `page` from options before wire serialization\n    let wireOptions: Api.ObserveRequest[\"options\"];\n    if (options) {\n      // eslint-disable-next-line @typescript-eslint/no-unused-vars\n      const { page: _, ...restOptions } = options;\n      if (Object.keys(restOptions).length > 0) {\n        if (restOptions.model) {\n          restOptions.model = this.prepareModelConfig(restOptions.model);\n        }\n        wireOptions = restOptions as unknown as Api.ObserveRequest[\"options\"];\n      }\n    }\n\n    // Build wire-format request body\n    const requestBody: Api.ObserveRequest = {\n      instruction,\n      options: wireOptions,\n      frameId,\n    };\n\n    return this.execute<Action[]>({\n      method: \"observe\",\n      args: requestBody,\n    });\n  }\n\n  async goto(\n    url: string,\n    options?: Api.NavigateRequest[\"options\"],\n    frameId?: string,\n  ): Promise<SerializableResponse | null> {\n    const requestBody: Api.NavigateRequest = { url, options, frameId };\n\n    return this.execute<SerializableResponse | null>({\n      method: \"navigate\",\n      args: requestBody,\n    });\n  }\n\n  async agentExecute(\n    agentConfig: AgentConfig,\n    executeOptions: AgentExecuteOptions | string,\n    frameId?: string,\n    shouldCache?: boolean,\n  ): Promise<AgentResult> {\n    // Check if integrations are being used in API mode (not supported)\n    if (agentConfig.integrations && agentConfig.integrations.length > 0) {\n      throw new ExperimentalNotConfiguredError(\"MCP integrations\");\n    }\n\n    // Strip non-serializable `page` from executeOptions before wire serialization\n    let wireExecuteOptions: Api.AgentExecuteRequest[\"executeOptions\"];\n    if (typeof executeOptions === \"string\") {\n      wireExecuteOptions = { instruction: executeOptions };\n    } else if (executeOptions.page) {\n      // eslint-disable-next-line @typescript-eslint/no-unused-vars\n      const { page: _, ...rest } = executeOptions;\n      wireExecuteOptions = rest;\n    } else {\n      wireExecuteOptions = executeOptions;\n    }\n\n    const wireAgentConfig: Api.AgentExecuteRequest[\"agentConfig\"] = {\n      systemPrompt: agentConfig.systemPrompt,\n      mode: agentConfig.mode ?? (agentConfig.cua === true ? \"cua\" : undefined),\n      cua: agentConfig.mode === undefined ? agentConfig.cua : undefined,\n      model: agentConfig.model\n        ? this.prepareModelConfig(agentConfig.model)\n        : undefined,\n      executionModel: agentConfig.executionModel\n        ? this.prepareModelConfig(agentConfig.executionModel)\n        : undefined,\n    };\n\n    // Build wire-format request body\n    const requestBody: Api.AgentExecuteRequest = {\n      agentConfig: wireAgentConfig,\n      executeOptions: wireExecuteOptions,\n      frameId,\n      shouldCache,\n    };\n\n    const result = await this.execute<AgentResult>({\n      method: \"agentExecute\",\n      args: requestBody,\n    });\n\n    const finishedData =\n      this.consumeFinishedEventData<Api.AgentExecuteResult>() ?? null;\n    this.latestAgentCacheEntry =\n      finishedData?.cacheEntry !== undefined\n        ? (finishedData.cacheEntry as AgentCacheTransferPayload)\n        : null;\n    return result;\n  }\n\n  consumeLatestAgentCacheEntry(): AgentCacheTransferPayload | null {\n    const entry = this.latestAgentCacheEntry;\n    this.latestAgentCacheEntry = null;\n    return entry;\n  }\n\n  async end(): Promise<Response> {\n    const url = `/sessions/${this.sessionId}/end`;\n    const response = await this.request(url, {\n      method: \"POST\",\n    });\n    return response;\n  }\n\n  async getReplayMetrics(): Promise<StagehandMetrics> {\n    if (!this.sessionId) {\n      throw new StagehandAPIError(\"sessionId is required to fetch metrics.\");\n    }\n\n    const response = await this.request(`/sessions/${this.sessionId}/replay`, {\n      method: \"GET\",\n    });\n\n    if (response.status !== 200) {\n      const errorText = await response.text();\n      this.logger({\n        category: \"api\",\n        message: `Failed to fetch metrics. Status ${response.status}: ${errorText}`,\n        level: 0,\n      });\n      throw new StagehandHttpError(\n        `Failed to fetch metrics with status ${response.status}: ${errorText}`,\n      );\n    }\n\n    const data = (await response.json()) as\n      | Api.ReplayResponse\n      | { success: false; error?: string };\n\n    if (!data.success) {\n      const errorData = data as { success: false; error?: string };\n      throw new StagehandAPIError(\n        `Failed to fetch metrics: ${errorData.error || \"Unknown error\"}`,\n      );\n    }\n\n    // Parse the API data into StagehandMetrics format\n    const apiData = (data as Api.ReplayResponse).data;\n    const metrics: StagehandMetrics = {\n      actPromptTokens: 0,\n      actCompletionTokens: 0,\n      actReasoningTokens: 0,\n      actCachedInputTokens: 0,\n      actInferenceTimeMs: 0,\n      extractPromptTokens: 0,\n      extractCompletionTokens: 0,\n      extractReasoningTokens: 0,\n      extractCachedInputTokens: 0,\n      extractInferenceTimeMs: 0,\n      observePromptTokens: 0,\n      observeCompletionTokens: 0,\n      observeReasoningTokens: 0,\n      observeCachedInputTokens: 0,\n      observeInferenceTimeMs: 0,\n      agentPromptTokens: 0,\n      agentCompletionTokens: 0,\n      agentReasoningTokens: 0,\n      agentCachedInputTokens: 0,\n      agentInferenceTimeMs: 0,\n      totalPromptTokens: 0,\n      totalCompletionTokens: 0,\n      totalReasoningTokens: 0,\n      totalCachedInputTokens: 0,\n      totalInferenceTimeMs: 0,\n    };\n\n    // Parse pages and their actions\n    const pages = apiData?.pages || [];\n    for (const page of pages) {\n      const actions = page.actions || [];\n      for (const action of actions) {\n        // Get method name and token usage\n        const method = (action.method || \"\").toLowerCase();\n        const tokenUsage = action.tokenUsage;\n\n        if (tokenUsage) {\n          const inputTokens = tokenUsage.inputTokens || 0;\n          const outputTokens = tokenUsage.outputTokens || 0;\n          const reasoningTokens =\n            \"reasoningTokens\" in tokenUsage\n              ? Number(\n                  (tokenUsage as { reasoningTokens?: number })\n                    .reasoningTokens ?? 0,\n                )\n              : 0;\n          const cachedInputTokens =\n            \"cachedInputTokens\" in tokenUsage\n              ? Number(\n                  (tokenUsage as { cachedInputTokens?: number })\n                    .cachedInputTokens ?? 0,\n                )\n              : 0;\n          const timeMs = tokenUsage.timeMs || 0;\n\n          // Map method to metrics fields\n          if (method === \"act\") {\n            metrics.actPromptTokens += inputTokens;\n            metrics.actCompletionTokens += outputTokens;\n            metrics.actReasoningTokens += reasoningTokens;\n            metrics.actCachedInputTokens += cachedInputTokens;\n            metrics.actInferenceTimeMs += timeMs;\n          } else if (method === \"extract\") {\n            metrics.extractPromptTokens += inputTokens;\n            metrics.extractCompletionTokens += outputTokens;\n            metrics.extractReasoningTokens += reasoningTokens;\n            metrics.extractCachedInputTokens += cachedInputTokens;\n            metrics.extractInferenceTimeMs += timeMs;\n          } else if (method === \"observe\") {\n            metrics.observePromptTokens += inputTokens;\n            metrics.observeCompletionTokens += outputTokens;\n            metrics.observeReasoningTokens += reasoningTokens;\n            metrics.observeCachedInputTokens += cachedInputTokens;\n            metrics.observeInferenceTimeMs += timeMs;\n          } else if (method === \"agent\") {\n            metrics.agentPromptTokens += inputTokens;\n            metrics.agentCompletionTokens += outputTokens;\n            metrics.agentReasoningTokens += reasoningTokens;\n            metrics.agentCachedInputTokens += cachedInputTokens;\n            metrics.agentInferenceTimeMs += timeMs;\n          }\n\n          // Always update totals for any method with token usage\n          metrics.totalPromptTokens += inputTokens;\n          metrics.totalCompletionTokens += outputTokens;\n          metrics.totalReasoningTokens += reasoningTokens;\n          metrics.totalCachedInputTokens += cachedInputTokens;\n          metrics.totalInferenceTimeMs += timeMs;\n        }\n      }\n    }\n\n    return metrics;\n  }\n\n  /**\n   * Prepares a model configuration for the API payload by ensuring the `apiKey`\n   * is included. If the model is passed as a string, converts it to an object\n   * with `modelName` and `apiKey`.\n   *\n   * In API mode, we only attempt to load an API key from env vars when the\n   * model provider differs from the one used to init the session.\n   */\n  private prepareModelConfig(\n    model: ModelConfiguration,\n  ): { modelName: string; apiKey: string } & Record<string, unknown> {\n    if (typeof model === \"string\") {\n      // Extract provider from model string (e.g., \"openai/gpt-5-nano\" -> \"openai\")\n      const provider = model.includes(\"/\") ? model.split(\"/\")[0] : undefined;\n      const apiKey =\n        provider && provider !== this.modelProvider\n          ? (loadApiKeyFromEnv(provider, this.logger) ?? this.modelApiKey)\n          : this.modelApiKey;\n      return {\n        modelName: model,\n        apiKey,\n      };\n    }\n\n    if (!model.apiKey) {\n      const provider = model.modelName?.includes(\"/\")\n        ? model.modelName.split(\"/\")[0]\n        : undefined;\n      const apiKey =\n        provider && provider !== this.modelProvider\n          ? (loadApiKeyFromEnv(provider, this.logger) ?? this.modelApiKey)\n          : this.modelApiKey;\n      return {\n        ...model,\n        apiKey,\n      };\n    }\n\n    return model as { modelName: string; apiKey: string } & Record<\n      string,\n      unknown\n    >;\n  }\n\n  private consumeFinishedEventData<T>(): T | null {\n    const data = this.lastFinishedEventData as T | null;\n    this.lastFinishedEventData = null;\n    return data;\n  }\n\n  private async execute<T>({\n    method,\n    args,\n    params,\n  }: ExecuteActionParams): Promise<T> {\n    this.lastFinishedEventData = null;\n    const urlParams = new URLSearchParams(params as Record<string, string>);\n    const queryString = urlParams.toString();\n    const url = `/sessions/${this.sessionId}/${method}${queryString ? `?${queryString}` : \"\"}`;\n\n    const response = await this.request(url, {\n      method: \"POST\",\n      body: JSON.stringify(args),\n    });\n\n    if (!response.ok) {\n      const errorBody = await response.text();\n      throw new StagehandHttpError(\n        `HTTP error! status: ${response.status}, body: ${errorBody}`,\n      );\n    }\n\n    if (!response.body) {\n      throw new StagehandResponseBodyError();\n    }\n\n    const reader = response.body.getReader();\n    const decoder = new TextDecoder();\n    let buffer = \"\";\n\n    while (true) {\n      const { value, done } = await reader.read();\n\n      if (done && !buffer) {\n        throw new StagehandServerError(\n          \"Stream ended without completion signal\",\n        );\n      }\n\n      buffer += decoder.decode(value, { stream: true });\n      const lines = buffer.split(\"\\n\\n\");\n      buffer = lines.pop() || \"\";\n\n      for (const line of lines) {\n        if (!line.startsWith(\"data: \")) continue;\n\n        try {\n          const eventData = JSON.parse(line.slice(6));\n\n          if (eventData.type === \"system\") {\n            if (eventData.data.status === \"error\") {\n              const { error: errorMsg } = eventData.data;\n              // Throw plain Error to match local SDK behavior (useApi: false)\n              throw new Error(errorMsg);\n            }\n            if (eventData.data.status === \"finished\") {\n              this.lastFinishedEventData = eventData.data;\n              return eventData.data.result as T;\n            }\n          } else if (eventData.type === \"log\") {\n            const msg = eventData.data.message;\n            // Skip server-side internal logs that don't apply to API mode\n            if (msg?.message === \"Connecting to local browser\") {\n              continue;\n            }\n            this.logger(eventData.data.message);\n          }\n        } catch (e) {\n          // Let Error instances pass through (server errors thrown above)\n          // Only wrap SyntaxError from JSON.parse as parse errors\n          if (e instanceof Error && !(e instanceof SyntaxError)) {\n            throw e;\n          }\n\n          const errorMessage = e instanceof Error ? e.message : String(e);\n          this.logger({\n            category: \"api\",\n            message: `Failed to parse SSE event: ${errorMessage}`,\n            level: 0,\n          });\n          throw new StagehandResponseParseError(\n            `Failed to parse server response: ${errorMessage}`,\n          );\n        }\n      }\n\n      if (done) {\n        // Process any remaining data in buffer before exiting\n        if (buffer.trim() && buffer.startsWith(\"data: \")) {\n          try {\n            const eventData = JSON.parse(buffer.slice(6));\n            if (\n              eventData.type === \"system\" &&\n              eventData.data.status === \"finished\"\n            ) {\n              return eventData.data.result as T;\n            }\n          } catch {\n            this.logger({\n              category: \"api\",\n              message: `Incomplete data in final buffer: ${buffer.substring(0, 100)}`,\n              level: 0,\n            });\n          }\n        }\n        throw new StagehandServerError(\n          \"Stream ended without completion signal\",\n        );\n      }\n    }\n  }\n\n  private async request(path: string, options: RequestInit): Promise<Response> {\n    const defaultHeaders: Record<string, string> = {\n      \"x-bb-api-key\": this.apiKey,\n      \"x-bb-project-id\": this.projectId,\n      \"x-bb-session-id\": this.sessionId,\n      // we want real-time logs, so we stream the response\n      \"x-stream-response\": \"true\",\n      \"x-model-api-key\": this.modelApiKey,\n      \"x-language\": \"typescript\",\n      \"x-sdk-version\": STAGEHAND_VERSION,\n    };\n    if (options.method === \"POST\" && options.body) {\n      defaultHeaders[\"Content-Type\"] = \"application/json\";\n    }\n\n    const response = await this.fetchWithCookies(\n      `${process.env.STAGEHAND_API_URL ?? \"https://api.stagehand.browserbase.com/v1\"}${path}`,\n      {\n        ...options,\n        headers: {\n          ...defaultHeaders,\n          ...options.headers,\n        },\n      },\n    );\n\n    return response;\n  }\n}\n"]}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../../lib/v3/api.ts"],"names":[],"mappings":"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","sourcesContent":["import makeFetchCookie from \"fetch-cookie\";\nimport { loadApiKeyFromEnv } from \"../utils.js\";\nimport { STAGEHAND_VERSION } from \"../version.js\";\nimport {\n  StagehandAPIError,\n  StagehandAPIUnauthorizedError,\n  StagehandHttpError,\n  StagehandResponseBodyError,\n  StagehandResponseParseError,\n  StagehandServerError,\n  ExperimentalNotConfiguredError,\n} from \"./types/public/index.js\";\nimport type {\n  Action,\n  ActResult,\n  AgentConfig,\n  AgentExecuteOptions,\n  AgentResult,\n  ExtractResult,\n  LogLine,\n  StagehandMetrics,\n  BrowserbaseRegion,\n  ActOptions,\n  ExtractOptions,\n  ObserveOptions,\n  Api,\n} from \"./types/public/index.js\";\nimport type {\n  SerializableResponse,\n  AgentCacheTransferPayload,\n} from \"./types/private/index.js\";\nimport type { ModelConfiguration } from \"./types/public/model.js\";\nimport { toJsonSchema } from \"./zodCompat.js\";\nimport type { StagehandZodSchema } from \"./zodCompat.js\";\n\n// =============================================================================\n// Multi-region API URL mapping\n// =============================================================================\n\n/**\n * Mapping of Browserbase regions to their corresponding Stagehand API base URLs.\n * Users should configure their client to hit the API endpoint that matches\n * the region where their browser session is running.\n */\nexport const REGION_API_URLS: Record<BrowserbaseRegion, string> = {\n  \"us-west-2\": \"https://api.stagehand.browserbase.com\",\n  \"us-east-1\": \"https://api.use1.stagehand.browserbase.com\",\n  \"eu-central-1\": \"https://api.euc1.stagehand.browserbase.com\",\n  \"ap-southeast-1\": \"https://api.apse1.stagehand.browserbase.com\",\n};\n\n/**\n * Returns the full API URL (with /v1 suffix) for a given Browserbase region.\n * If no region is specified or the region is unknown, defaults to us-west-2.\n *\n * @param region - The Browserbase region (e.g., \"us-west-2\", \"eu-central-1\")\n * @returns The full API URL including /v1 suffix\n */\nexport function getApiUrlForRegion(\n  region: BrowserbaseRegion | undefined,\n): string {\n  const baseUrl =\n    REGION_API_URLS[region as BrowserbaseRegion] ??\n    REGION_API_URLS[\"us-west-2\"];\n  return `${baseUrl}/v1`;\n}\n\n// =============================================================================\n// Client-specific types (can't be Zod schemas due to functions/Page objects)\n// =============================================================================\n//\n// These types mirror the Api.* schemas from types/public/api.ts but include\n// non-serializable SDK fields (like Page objects) that get stripped before\n// sending requests over the wire.\n//\n// Relationship to wire format:\n// - Client accepts: SDK types (ActOptions, ExtractOptions, etc.) with optional `page`\n// - Wire sends: Api.* types (page stripped, Zod schema converted to JSON schema)\n// - Client returns: SDK result types (ActResult, ExtractResult, etc.)\n// =============================================================================\n\n/**\n * Constructor parameters for StagehandAPIClient\n */\ninterface StagehandAPIConstructorParams {\n  apiKey: string;\n  projectId: string;\n  logger: (message: LogLine) => void;\n}\n\n/**\n * Parameters for starting a session via the API client.\n * Extends Api.SessionStartRequest with client-specific field (modelApiKey).\n *\n * Wire format: Api.SessionStartRequest (modelApiKey sent via header, not body)\n */\ninterface ClientSessionStartParams extends Api.SessionStartRequest {\n  /** Model API key - sent via x-model-api-key header, not in request body */\n  modelApiKey: string;\n}\n\n/**\n * Generic API response wrapper matching Api.*Response schemas\n */\ntype ApiResponse<T> =\n  | { success: true; data: T }\n  | { success: false; message: string };\n\n/**\n * Union of all API request body types for type-safe execute() calls\n */\ntype ApiRequestBody =\n  | Api.ActRequest\n  | Api.ExtractRequest\n  | Api.ObserveRequest\n  | Api.NavigateRequest\n  | Api.AgentExecuteRequest;\n\n/**\n * Parameters for executing an action via the streaming API\n */\ninterface ExecuteActionParams {\n  method: \"act\" | \"extract\" | \"observe\" | \"navigate\" | \"end\" | \"agentExecute\";\n  args?: ApiRequestBody;\n  params?: Record<string, string>;\n}\n\n/**\n * Client parameters for act() method.\n * Derives structure from Api.ActRequest but uses SDK's ActOptions (which includes `page`).\n * Before serialization, `page` is stripped to produce Api.ActRequest wire format.\n */\ninterface ClientActParameters {\n  input: Api.ActRequest[\"input\"];\n  options?: ActOptions;\n  frameId?: Api.ActRequest[\"frameId\"];\n}\n\n/**\n * Client parameters for extract() method.\n * Derives structure from Api.ExtractRequest but uses SDK's ExtractOptions (which includes `page`)\n * and accepts Zod schema (converted to JSON schema for wire format).\n */\ninterface ClientExtractParameters {\n  instruction?: Api.ExtractRequest[\"instruction\"];\n  schema?: StagehandZodSchema;\n  options?: ExtractOptions;\n  frameId?: Api.ExtractRequest[\"frameId\"];\n}\n\n/**\n * Client parameters for observe() method.\n * Derives structure from Api.ObserveRequest but uses SDK's ObserveOptions (which includes `page`).\n * Before serialization, `page` is stripped to produce Api.ObserveRequest wire format.\n */\ninterface ClientObserveParameters {\n  instruction?: Api.ObserveRequest[\"instruction\"];\n  options?: ObserveOptions;\n  frameId?: Api.ObserveRequest[\"frameId\"];\n}\n\nexport class StagehandAPIClient {\n  private apiKey: string;\n  private projectId: string;\n  private sessionId?: string;\n  private modelApiKey: string;\n  private modelProvider?: string;\n  private region?: BrowserbaseRegion;\n  private logger: (message: LogLine) => void;\n  private fetchWithCookies;\n  private lastFinishedEventData: Record<string, unknown> | null = null;\n  private latestAgentCacheEntry: AgentCacheTransferPayload | null = null;\n\n  constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams) {\n    this.apiKey = apiKey;\n    this.projectId = projectId;\n    this.logger = logger;\n    // Create a single cookie jar instance that will persist across all requests\n    this.fetchWithCookies = makeFetchCookie(fetch);\n  }\n\n  async init({\n    modelName,\n    modelApiKey,\n    domSettleTimeoutMs,\n    verbose,\n    systemPrompt,\n    selfHeal,\n    browserbaseSessionCreateParams,\n    browserbaseSessionID,\n    // browser,  TODO for local browsers\n  }: ClientSessionStartParams): Promise<Api.SessionStartResult> {\n    if (!modelApiKey) {\n      throw new StagehandAPIError(\"modelApiKey is required\");\n    }\n    this.modelApiKey = modelApiKey;\n    // Extract provider from modelName (e.g., \"openai/gpt-5-nano\" -> \"openai\")\n    this.modelProvider = modelName?.includes(\"/\")\n      ? modelName.split(\"/\")[0]\n      : undefined;\n\n    // Store the region for multi-region API URL resolution\n    this.region = browserbaseSessionCreateParams?.region;\n\n    this.logger({\n      category: \"init\",\n      message: \"Creating new browserbase session...\",\n      level: 1,\n    });\n\n    // Build wire-format request body (Api.SessionStartRequest shape)\n    const requestBody: Api.SessionStartRequest = {\n      modelName,\n      domSettleTimeoutMs,\n      verbose,\n      systemPrompt,\n      selfHeal,\n      browserbaseSessionCreateParams,\n      browserbaseSessionID,\n      // browser, TODO: only send when connected to local fastify\n    };\n\n    const sessionResponse = await this.request(\"/sessions/start\", {\n      method: \"POST\",\n      body: JSON.stringify(requestBody),\n    });\n\n    if (sessionResponse.status === 401) {\n      throw new StagehandAPIUnauthorizedError(\n        \"Unauthorized. Ensure you provided a valid API key.\",\n      );\n    } else if (sessionResponse.status !== 200) {\n      const errorText = await sessionResponse.text();\n      this.logger({\n        category: \"api\",\n        message: `API error (${sessionResponse.status}): ${errorText}`,\n        level: 0,\n      });\n      throw new StagehandHttpError(`Unknown error: ${sessionResponse.status}`);\n    }\n\n    const sessionResponseBody =\n      (await sessionResponse.json()) as ApiResponse<Api.SessionStartResult>;\n\n    if (sessionResponseBody.success === false) {\n      throw new StagehandAPIError(sessionResponseBody.message);\n    }\n\n    // Temporary reroute for rollout\n    if (!sessionResponseBody.data?.available && browserbaseSessionID) {\n      sessionResponseBody.data.sessionId = browserbaseSessionID;\n    }\n\n    this.sessionId = sessionResponseBody.data.sessionId;\n\n    return sessionResponseBody.data;\n  }\n\n  async act({\n    input,\n    options,\n    frameId,\n  }: ClientActParameters): Promise<ActResult> {\n    // Strip non-serializable `page` from options before wire serialization\n    let wireOptions: Api.ActRequest[\"options\"];\n    if (options) {\n      // eslint-disable-next-line @typescript-eslint/no-unused-vars\n      const { page: _, ...restOptions } = options;\n      if (Object.keys(restOptions).length > 0) {\n        if (restOptions.model) {\n          restOptions.model = this.prepareModelConfig(restOptions.model);\n        }\n        wireOptions = restOptions as unknown as Api.ActRequest[\"options\"];\n      }\n    }\n\n    // Build wire-format request body\n    const requestBody: Api.ActRequest = {\n      input,\n      options: wireOptions,\n      frameId,\n    };\n\n    return this.execute<ActResult>({\n      method: \"act\",\n      args: requestBody,\n    });\n  }\n\n  async extract<T extends StagehandZodSchema>({\n    instruction,\n    schema: zodSchema,\n    options,\n    frameId,\n  }: ClientExtractParameters): Promise<ExtractResult<T>> {\n    // Convert Zod schema to JSON schema for wire format\n    const jsonSchema = zodSchema ? toJsonSchema(zodSchema) : undefined;\n\n    // Strip non-serializable `page` from options before wire serialization\n    let wireOptions: Api.ExtractRequest[\"options\"];\n    if (options) {\n      // eslint-disable-next-line @typescript-eslint/no-unused-vars\n      const { page: _, ...restOptions } = options;\n      if (Object.keys(restOptions).length > 0) {\n        if (restOptions.model) {\n          restOptions.model = this.prepareModelConfig(restOptions.model);\n        }\n        wireOptions = restOptions as unknown as Api.ExtractRequest[\"options\"];\n      }\n    }\n\n    // Build wire-format request body\n    const requestBody: Api.ExtractRequest = {\n      instruction,\n      schema: jsonSchema,\n      options: wireOptions,\n      frameId,\n    };\n\n    return this.execute<ExtractResult<T>>({\n      method: \"extract\",\n      args: requestBody,\n    });\n  }\n\n  async observe({\n    instruction,\n    options,\n    frameId,\n  }: ClientObserveParameters): Promise<Action[]> {\n    // Strip non-serializable `page` from options before wire serialization\n    let wireOptions: Api.ObserveRequest[\"options\"];\n    if (options) {\n      // eslint-disable-next-line @typescript-eslint/no-unused-vars\n      const { page: _, ...restOptions } = options;\n      if (Object.keys(restOptions).length > 0) {\n        if (restOptions.model) {\n          restOptions.model = this.prepareModelConfig(restOptions.model);\n        }\n        wireOptions = restOptions as unknown as Api.ObserveRequest[\"options\"];\n      }\n    }\n\n    // Build wire-format request body\n    const requestBody: Api.ObserveRequest = {\n      instruction,\n      options: wireOptions,\n      frameId,\n    };\n\n    return this.execute<Action[]>({\n      method: \"observe\",\n      args: requestBody,\n    });\n  }\n\n  async goto(\n    url: string,\n    options?: Api.NavigateRequest[\"options\"],\n    frameId?: string,\n  ): Promise<SerializableResponse | null> {\n    const requestBody: Api.NavigateRequest = { url, options, frameId };\n\n    return this.execute<SerializableResponse | null>({\n      method: \"navigate\",\n      args: requestBody,\n    });\n  }\n\n  async agentExecute(\n    agentConfig: AgentConfig,\n    executeOptions: AgentExecuteOptions | string,\n    frameId?: string,\n    shouldCache?: boolean,\n  ): Promise<AgentResult> {\n    // Check if integrations are being used in API mode (not supported)\n    if (agentConfig.integrations && agentConfig.integrations.length > 0) {\n      throw new ExperimentalNotConfiguredError(\"MCP integrations\");\n    }\n\n    // Strip non-serializable `page` from executeOptions before wire serialization\n    let wireExecuteOptions: Api.AgentExecuteRequest[\"executeOptions\"];\n    if (typeof executeOptions === \"string\") {\n      wireExecuteOptions = { instruction: executeOptions };\n    } else if (executeOptions.page) {\n      // eslint-disable-next-line @typescript-eslint/no-unused-vars\n      const { page: _, ...rest } = executeOptions;\n      wireExecuteOptions = rest;\n    } else {\n      wireExecuteOptions = executeOptions;\n    }\n\n    const wireAgentConfig: Api.AgentExecuteRequest[\"agentConfig\"] = {\n      systemPrompt: agentConfig.systemPrompt,\n      mode: agentConfig.mode ?? (agentConfig.cua === true ? \"cua\" : undefined),\n      cua: agentConfig.mode === undefined ? agentConfig.cua : undefined,\n      model: agentConfig.model\n        ? this.prepareModelConfig(agentConfig.model)\n        : undefined,\n      executionModel: agentConfig.executionModel\n        ? this.prepareModelConfig(agentConfig.executionModel)\n        : undefined,\n    };\n\n    // Build wire-format request body\n    const requestBody: Api.AgentExecuteRequest = {\n      agentConfig: wireAgentConfig,\n      executeOptions: wireExecuteOptions,\n      frameId,\n      shouldCache,\n    };\n\n    const result = await this.execute<AgentResult>({\n      method: \"agentExecute\",\n      args: requestBody,\n    });\n\n    const finishedData =\n      this.consumeFinishedEventData<Api.AgentExecuteResult>() ?? null;\n    this.latestAgentCacheEntry =\n      finishedData?.cacheEntry !== undefined\n        ? (finishedData.cacheEntry as AgentCacheTransferPayload)\n        : null;\n    return result;\n  }\n\n  consumeLatestAgentCacheEntry(): AgentCacheTransferPayload | null {\n    const entry = this.latestAgentCacheEntry;\n    this.latestAgentCacheEntry = null;\n    return entry;\n  }\n\n  async end(): Promise<Response> {\n    const url = `/sessions/${this.sessionId}/end`;\n    const response = await this.request(url, {\n      method: \"POST\",\n    });\n    return response;\n  }\n\n  async getReplayMetrics(): Promise<StagehandMetrics> {\n    if (!this.sessionId) {\n      throw new StagehandAPIError(\"sessionId is required to fetch metrics.\");\n    }\n\n    const response = await this.request(`/sessions/${this.sessionId}/replay`, {\n      method: \"GET\",\n    });\n\n    if (response.status !== 200) {\n      const errorText = await response.text();\n      this.logger({\n        category: \"api\",\n        message: `Failed to fetch metrics. Status ${response.status}: ${errorText}`,\n        level: 0,\n      });\n      throw new StagehandHttpError(\n        `Failed to fetch metrics with status ${response.status}: ${errorText}`,\n      );\n    }\n\n    const data = (await response.json()) as\n      | Api.ReplayResponse\n      | { success: false; error?: string };\n\n    if (!data.success) {\n      const errorData = data as { success: false; error?: string };\n      throw new StagehandAPIError(\n        `Failed to fetch metrics: ${errorData.error || \"Unknown error\"}`,\n      );\n    }\n\n    // Parse the API data into StagehandMetrics format\n    const apiData = (data as Api.ReplayResponse).data;\n    const metrics: StagehandMetrics = {\n      actPromptTokens: 0,\n      actCompletionTokens: 0,\n      actReasoningTokens: 0,\n      actCachedInputTokens: 0,\n      actInferenceTimeMs: 0,\n      extractPromptTokens: 0,\n      extractCompletionTokens: 0,\n      extractReasoningTokens: 0,\n      extractCachedInputTokens: 0,\n      extractInferenceTimeMs: 0,\n      observePromptTokens: 0,\n      observeCompletionTokens: 0,\n      observeReasoningTokens: 0,\n      observeCachedInputTokens: 0,\n      observeInferenceTimeMs: 0,\n      agentPromptTokens: 0,\n      agentCompletionTokens: 0,\n      agentReasoningTokens: 0,\n      agentCachedInputTokens: 0,\n      agentInferenceTimeMs: 0,\n      totalPromptTokens: 0,\n      totalCompletionTokens: 0,\n      totalReasoningTokens: 0,\n      totalCachedInputTokens: 0,\n      totalInferenceTimeMs: 0,\n    };\n\n    // Parse pages and their actions\n    const pages = apiData?.pages || [];\n    for (const page of pages) {\n      const actions = page.actions || [];\n      for (const action of actions) {\n        // Get method name and token usage\n        const method = (action.method || \"\").toLowerCase();\n        const tokenUsage = action.tokenUsage;\n\n        if (tokenUsage) {\n          const inputTokens = tokenUsage.inputTokens || 0;\n          const outputTokens = tokenUsage.outputTokens || 0;\n          const reasoningTokens =\n            \"reasoningTokens\" in tokenUsage\n              ? Number(\n                  (tokenUsage as { reasoningTokens?: number })\n                    .reasoningTokens ?? 0,\n                )\n              : 0;\n          const cachedInputTokens =\n            \"cachedInputTokens\" in tokenUsage\n              ? Number(\n                  (tokenUsage as { cachedInputTokens?: number })\n                    .cachedInputTokens ?? 0,\n                )\n              : 0;\n          const timeMs = tokenUsage.timeMs || 0;\n\n          // Map method to metrics fields\n          if (method === \"act\") {\n            metrics.actPromptTokens += inputTokens;\n            metrics.actCompletionTokens += outputTokens;\n            metrics.actReasoningTokens += reasoningTokens;\n            metrics.actCachedInputTokens += cachedInputTokens;\n            metrics.actInferenceTimeMs += timeMs;\n          } else if (method === \"extract\") {\n            metrics.extractPromptTokens += inputTokens;\n            metrics.extractCompletionTokens += outputTokens;\n            metrics.extractReasoningTokens += reasoningTokens;\n            metrics.extractCachedInputTokens += cachedInputTokens;\n            metrics.extractInferenceTimeMs += timeMs;\n          } else if (method === \"observe\") {\n            metrics.observePromptTokens += inputTokens;\n            metrics.observeCompletionTokens += outputTokens;\n            metrics.observeReasoningTokens += reasoningTokens;\n            metrics.observeCachedInputTokens += cachedInputTokens;\n            metrics.observeInferenceTimeMs += timeMs;\n          } else if (method === \"agent\") {\n            metrics.agentPromptTokens += inputTokens;\n            metrics.agentCompletionTokens += outputTokens;\n            metrics.agentReasoningTokens += reasoningTokens;\n            metrics.agentCachedInputTokens += cachedInputTokens;\n            metrics.agentInferenceTimeMs += timeMs;\n          }\n\n          // Always update totals for any method with token usage\n          metrics.totalPromptTokens += inputTokens;\n          metrics.totalCompletionTokens += outputTokens;\n          metrics.totalReasoningTokens += reasoningTokens;\n          metrics.totalCachedInputTokens += cachedInputTokens;\n          metrics.totalInferenceTimeMs += timeMs;\n        }\n      }\n    }\n\n    return metrics;\n  }\n\n  /**\n   * Prepares a model configuration for the API payload by ensuring the `apiKey`\n   * is included. If the model is passed as a string, converts it to an object\n   * with `modelName` and `apiKey`.\n   *\n   * In API mode, we only attempt to load an API key from env vars when the\n   * model provider differs from the one used to init the session.\n   */\n  private prepareModelConfig(\n    model: ModelConfiguration,\n  ): { modelName: string; apiKey: string } & Record<string, unknown> {\n    if (typeof model === \"string\") {\n      // Extract provider from model string (e.g., \"openai/gpt-5-nano\" -> \"openai\")\n      const provider = model.includes(\"/\") ? model.split(\"/\")[0] : undefined;\n      const apiKey =\n        provider && provider !== this.modelProvider\n          ? (loadApiKeyFromEnv(provider, this.logger) ?? this.modelApiKey)\n          : this.modelApiKey;\n      return {\n        modelName: model,\n        apiKey,\n      };\n    }\n\n    if (!model.apiKey) {\n      const provider = model.modelName?.includes(\"/\")\n        ? model.modelName.split(\"/\")[0]\n        : undefined;\n      const apiKey =\n        provider && provider !== this.modelProvider\n          ? (loadApiKeyFromEnv(provider, this.logger) ?? this.modelApiKey)\n          : this.modelApiKey;\n      return {\n        ...model,\n        apiKey,\n      };\n    }\n\n    return model as { modelName: string; apiKey: string } & Record<\n      string,\n      unknown\n    >;\n  }\n\n  private consumeFinishedEventData<T>(): T | null {\n    const data = this.lastFinishedEventData as T | null;\n    this.lastFinishedEventData = null;\n    return data;\n  }\n\n  private async execute<T>({\n    method,\n    args,\n    params,\n  }: ExecuteActionParams): Promise<T> {\n    this.lastFinishedEventData = null;\n    const urlParams = new URLSearchParams(params as Record<string, string>);\n    const queryString = urlParams.toString();\n    const url = `/sessions/${this.sessionId}/${method}${queryString ? `?${queryString}` : \"\"}`;\n\n    const response = await this.request(url, {\n      method: \"POST\",\n      body: JSON.stringify(args),\n    });\n\n    if (!response.ok) {\n      const errorBody = await response.text();\n      throw new StagehandHttpError(\n        `HTTP error! status: ${response.status}, body: ${errorBody}`,\n      );\n    }\n\n    if (!response.body) {\n      throw new StagehandResponseBodyError();\n    }\n\n    const reader = response.body.getReader();\n    const decoder = new TextDecoder();\n    let buffer = \"\";\n\n    while (true) {\n      const { value, done } = await reader.read();\n\n      if (done && !buffer) {\n        throw new StagehandServerError(\n          \"Stream ended without completion signal\",\n        );\n      }\n\n      buffer += decoder.decode(value, { stream: true });\n      const lines = buffer.split(\"\\n\\n\");\n      buffer = lines.pop() || \"\";\n\n      for (const line of lines) {\n        if (!line.startsWith(\"data: \")) continue;\n\n        try {\n          const eventData = JSON.parse(line.slice(6));\n\n          if (eventData.type === \"system\") {\n            if (eventData.data.status === \"error\") {\n              const { error: errorMsg } = eventData.data;\n              // Throw plain Error to match local SDK behavior (useApi: false)\n              throw new Error(errorMsg);\n            }\n            if (eventData.data.status === \"finished\") {\n              this.lastFinishedEventData = eventData.data;\n              return eventData.data.result as T;\n            }\n          } else if (eventData.type === \"log\") {\n            const msg = eventData.data.message;\n            // Skip server-side internal logs that don't apply to API mode\n            if (msg?.message === \"Connecting to local browser\") {\n              continue;\n            }\n            this.logger(eventData.data.message);\n          }\n        } catch (e) {\n          // Let Error instances pass through (server errors thrown above)\n          // Only wrap SyntaxError from JSON.parse as parse errors\n          if (e instanceof Error && !(e instanceof SyntaxError)) {\n            throw e;\n          }\n\n          const errorMessage = e instanceof Error ? e.message : String(e);\n          this.logger({\n            category: \"api\",\n            message: `Failed to parse SSE event: ${errorMessage}`,\n            level: 0,\n          });\n          throw new StagehandResponseParseError(\n            `Failed to parse server response: ${errorMessage}`,\n          );\n        }\n      }\n\n      if (done) {\n        // Process any remaining data in buffer before exiting\n        if (buffer.trim() && buffer.startsWith(\"data: \")) {\n          try {\n            const eventData = JSON.parse(buffer.slice(6));\n            if (\n              eventData.type === \"system\" &&\n              eventData.data.status === \"finished\"\n            ) {\n              return eventData.data.result as T;\n            }\n          } catch {\n            this.logger({\n              category: \"api\",\n              message: `Incomplete data in final buffer: ${buffer.substring(0, 100)}`,\n              level: 0,\n            });\n          }\n        }\n        throw new StagehandServerError(\n          \"Stream ended without completion signal\",\n        );\n      }\n    }\n  }\n\n  private async request(path: string, options: RequestInit): Promise<Response> {\n    const defaultHeaders: Record<string, string> = {\n      \"x-bb-api-key\": this.apiKey,\n      \"x-bb-project-id\": this.projectId,\n      \"x-bb-session-id\": this.sessionId,\n      // we want real-time logs, so we stream the response\n      \"x-stream-response\": \"true\",\n      \"x-model-api-key\": this.modelApiKey,\n      \"x-language\": \"typescript\",\n      \"x-sdk-version\": STAGEHAND_VERSION,\n    };\n    if (options.method === \"POST\" && options.body) {\n      defaultHeaders[\"Content-Type\"] = \"application/json\";\n    }\n\n    // Use STAGEHAND_API_URL env var if set, otherwise use region-based URL\n    // Ensure /v1 suffix is present for consistency\n    let baseUrl: string;\n    if (process.env.STAGEHAND_API_URL) {\n      const envUrl = process.env.STAGEHAND_API_URL.replace(/\\/+$/, \"\");\n      // Append /v1 if not already present\n      baseUrl = envUrl.endsWith(\"/v1\") ? envUrl : `${envUrl}/v1`;\n    } else {\n      baseUrl = getApiUrlForRegion(this.region);\n    }\n\n    const response = await this.fetchWithCookies(`${baseUrl}${path}`, {\n      ...options,\n      headers: {\n        ...defaultHeaders,\n        ...options.headers,\n      },\n    });\n\n    return response;\n  }\n}\n"]}

package/dist/esm/lib/v3/handlers/handlerUtils/actHandlerUtils.d.ts

@@ -1,9 +1,6 @@
 import { Frame } from "../../understudy/frame.js";
 import { Locator } from "../../understudy/locator.js";
 import type { Page } from "../../understudy/page.js";
-export declare class UnderstudyCommandException extends Error {
-    constructor(message: string);
-}
 export interface UnderstudyMethodHandlerContext {
     method: string;
     locator: Locator;

package/dist/esm/lib/v3/handlers/handlerUtils/actHandlerUtils.js

@@ -1,13 +1,7 @@
 import { resolveLocatorWithHops } from "../../understudy/deepLocator.js";
 import { v3Logger } from "../../logger.js";
 import { SessionFileLogger } from "../../flowLogger.js";
-import { StagehandClickError } from "../../types/public/sdkErrors.js";
-export class UnderstudyCommandException extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "UnderstudyCommandException";
-    }
-}
+import { StagehandClickError, UnderstudyCommandException, } from "../../types/public/sdkErrors.js";
 // Normalize cases where the XPath is the root "/" to point to the HTML element.
 function normalizeRootXPath(input) {
     const s = String(input ?? "").trim();
@@ -91,7 +85,10 @@ export async function performUnderstudyMethod(page, frame, method, rawXPath, arg
                 args: { value: JSON.stringify(args), type: "object" },
             },
         });
-        throw new UnderstudyCommandException(msg);
+        if (e instanceof UnderstudyCommandException) {
+            throw e;
+        }
+        throw new UnderstudyCommandException(msg, e);
     }
     finally {
         SessionFileLogger.logUnderstudyActionCompleted();
@@ -123,17 +120,19 @@ export async function selectOption(ctx) {
         await locator.selectOption(text);
     }
     catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        const stack = e instanceof Error ? e.stack : undefined;
         v3Logger({
             category: "action",
             message: "error selecting option",
             level: 0,
             auxiliary: {
-                error: { value: e.message, type: "string" },
-                trace: { value: e.stack, type: "string" },
+                error: { value: msg, type: "string" },
+                trace: { value: stack ?? "", type: "string" },
                 xpath: { value: xpath, type: "string" },
             },
         });
-        throw new UnderstudyCommandException(e.message);
+        throw new UnderstudyCommandException(msg, e);
     }
 }
 async function scrollIntoView(ctx) {
@@ -175,7 +174,8 @@ async function scrollByPixelOffset(ctx) {
         await page.scroll(x, y, dx, dy);
     }
     catch (e) {
-        throw new UnderstudyCommandException(e.message);
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new UnderstudyCommandException(msg, e);
     }
 }
 async function wheelScroll(ctx) {
@@ -212,7 +212,7 @@ async function fillOrType(ctx) {
                 xpath: { value: xpath, type: "string" },
             },
         });
-        throw new UnderstudyCommandException(msg);
+        throw new UnderstudyCommandException(msg, e);
     }
 }
 async function typeText(ctx) {
@@ -231,7 +231,7 @@ async function typeText(ctx) {
                 xpath: { value: xpath, type: "string" },
             },
         });
-        throw new UnderstudyCommandException(msg);
+        throw new UnderstudyCommandException(msg, e);
     }
 }
 async function pressKey(ctx) {
@@ -261,7 +261,7 @@ async function pressKey(ctx) {
                 xpath: { value: xpath, type: "string" },
             },
         });
-        throw new UnderstudyCommandException(msg);
+        throw new UnderstudyCommandException(msg, e);
     }
 }
 async function clickElement(ctx) {
@@ -299,7 +299,7 @@ async function doubleClick(ctx) {
                 xpath: { value: xpath, type: "string" },
             },
         });
-        throw new UnderstudyCommandException(msg);
+        throw new UnderstudyCommandException(msg, e);
     }
 }
 async function dragAndDrop(ctx) {
@@ -365,7 +365,7 @@ async function dragAndDrop(ctx) {
                 to: { value: toXPath, type: "string" },
             },
         });
-        throw new UnderstudyCommandException(msg);
+        throw new UnderstudyCommandException(msg, e);
     }
 }
 async function scrollToNextChunk(ctx) {
@@ -430,17 +430,19 @@ export async function hover(ctx) {
         await locator.hover();
     }
     catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        const stack = e instanceof Error ? e.stack : undefined;
         v3Logger({
             category: "action",
             message: "error attempting to hover",
             level: 0,
             auxiliary: {
-                error: { value: e.message, type: "string" },
-                trace: { value: e.stack, type: "string" },
+                error: { value: msg, type: "string" },
+                trace: { value: stack ?? "", type: "string" },
                 xpath: { value: xpath, type: "string" },
             },
         });
-        throw new UnderstudyCommandException(e.message);
+        throw new UnderstudyCommandException(msg, e);
     }
 }
 /* ===================== Helpers ===================== */