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

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

@@ -0,0 +1,32 @@
+/** A cookie as returned by the browser. */
+export interface Cookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    /** Unix time in seconds. -1 means session cookie. */
+    expires: number;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "Strict" | "Lax" | "None";
+}
+/** Parameters for setting a cookie. Provide `url` OR `domain`+`path`, not both. */
+export interface CookieParam {
+    name: string;
+    value: string;
+    /** Convenience: if provided, domain/path/secure are derived from this URL. */
+    url?: string;
+    domain?: string;
+    path?: string;
+    /** Unix timestamp in seconds. -1 or omitted = session cookie. */
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+}
+/** Filter options for clearing cookies selectively. */
+export interface ClearCookieOptions {
+    name?: string | RegExp;
+    domain?: string | RegExp;
+    path?: string | RegExp;
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

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

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

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

@@ -9,5 +9,6 @@ export * from "./model.js";
 export * from "./options.js";
 export * from "./page.js";
 export * from "./sdkErrors.js";
+export * from "./context.js";
 export { AISdkClient } from "../../external_clients/aisdk.js";
 export { CustomOpenAIClient } from "../../external_clients/customOpenAI.js";

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

@@ -9,6 +9,7 @@ export * from "./model.js";
 export * from "./options.js";
 export * from "./page.js";
 export * from "./sdkErrors.js";
+export * from "./context.js";
 export { AISdkClient } from "../../external_clients/aisdk.js";
 export { CustomOpenAIClient } from "../../external_clients/customOpenAI.js";
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,yEAAyE;AACzE,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAGhC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC","sourcesContent":["export * from \"./agent.js\";\n// Export api.ts under namespace to avoid conflicts with methods.ts types\nexport * as Api from \"./api.js\";\n// Also export BrowserbaseRegion directly for convenience\nexport type { BrowserbaseRegion } from \"./api.js\";\nexport * from \"./apiErrors.js\";\nexport * from \"./logs.js\";\nexport * from \"./methods.js\";\nexport * from \"./metrics.js\";\nexport * from \"./model.js\";\nexport * from \"./options.js\";\nexport * from \"./page.js\";\nexport * from \"./sdkErrors.js\";\nexport { AISdkClient } from \"../../external_clients/aisdk.js\";\nexport { CustomOpenAIClient } from \"../../external_clients/customOpenAI.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,yEAAyE;AACzE,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAGhC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC","sourcesContent":["export * from \"./agent.js\";\n// Export api.ts under namespace to avoid conflicts with methods.ts types\nexport * as Api from \"./api.js\";\n// Also export BrowserbaseRegion directly for convenience\nexport type { BrowserbaseRegion } from \"./api.js\";\nexport * from \"./apiErrors.js\";\nexport * from \"./logs.js\";\nexport * from \"./methods.js\";\nexport * from \"./metrics.js\";\nexport * from \"./model.js\";\nexport * from \"./options.js\";\nexport * from \"./page.js\";\nexport * from \"./sdkErrors.js\";\nexport * from \"./context.js\";\nexport { AISdkClient } from \"../../external_clients/aisdk.js\";\nexport { CustomOpenAIClient } from \"../../external_clients/customOpenAI.js\";\n"]}

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

@@ -5,19 +5,29 @@ import { z } from "zod";
 import type { InferStagehandSchema, StagehandZodSchema } from "../../zodCompat.js";
 import { Page } from "../../understudy/page.js";
 import { ModelConfiguration } from "../public/model.js";
+import type { Variables } from "./agent.js";
 export interface ActOptions {
     model?: ModelConfiguration;
-    variables?: Record<string, string>;
+    variables?: Variables;
     timeout?: number;
     page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+    /**
+     * Override the instance-level serverCache setting for this request.
+     * When true, enables server-side caching.
+     * When false, disables server-side caching.
+     */
+    serverCache?: boolean;
 }
 export interface ActResult {
     success: boolean;
     message: string;
     actionDescription: string;
     actions: Action[];
+    cacheStatus?: "HIT" | "MISS";
 }
-export type ExtractResult<T extends StagehandZodSchema> = InferStagehandSchema<T>;
+export type ExtractResult<T extends StagehandZodSchema> = InferStagehandSchema<T> & {
+    cacheStatus?: "HIT" | "MISS";
+};
 export interface Action {
     selector: string;
     description: string;
@@ -35,6 +45,12 @@ export interface ExtractOptions {
     timeout?: number;
     selector?: string;
     page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+    /**
+     * Override the instance-level serverCache setting for this request.
+     * When true, enables server-side caching.
+     * When false, disables server-side caching.
+     */
+    serverCache?: boolean;
 }
 export declare const defaultExtractSchema: z.ZodObject<{
     extraction: z.ZodString;
@@ -47,7 +63,22 @@ export interface ObserveOptions {
     timeout?: number;
     selector?: string;
     page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+    /**
+     * Override the instance-level serverCache setting for this request.
+     * When true, enables server-side caching.
+     * When false, disables server-side caching.
+     */
+    serverCache?: boolean;
 }
+/**
+ * Observe returns an array of candidate actions. The optional `cacheStatus`
+ * property is attached when the server responds with a
+ * `browserbase-cache-status` header so callers can tell whether the result
+ * was served from the server-side cache.
+ */
+export type ObserveResult = Action[] & {
+    cacheStatus?: "HIT" | "MISS";
+};
 export declare enum V3FunctionName {
     ACT = "ACT",
     EXTRACT = "EXTRACT",

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

@@ -1 +1 @@
-{"version":3,"file":"methods.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/methods.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA8CxB,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;CACrB,CAAC,CAAC;AASH,MAAM,CAAN,IAAY,cAKX;AALD,WAAY,cAAc;IACxB,6BAAW,CAAA;IACX,qCAAmB,CAAA;IACnB,qCAAmB,CAAA;IACnB,iCAAe,CAAA;AACjB,CAAC,EALW,cAAc,KAAd,cAAc,QAKzB","sourcesContent":["import { Page as PatchrightPage } from \"patchright-core\";\nimport { Page as PlaywrightPage } from \"playwright-core\";\nimport { Page as PuppeteerPage } from \"puppeteer-core\";\nimport { z } from \"zod\";\nimport type {\n  InferStagehandSchema,\n  StagehandZodSchema,\n} from \"../../zodCompat.js\";\nimport { Page } from \"../../understudy/page.js\";\nimport { ModelConfiguration } from \"../public/model.js\";\n\nexport interface ActOptions {\n  model?: ModelConfiguration;\n  variables?: Record<string, string>;\n  timeout?: number;\n  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;\n}\n\nexport interface ActResult {\n  success: boolean;\n  message: string;\n  actionDescription: string;\n  actions: Action[];\n}\n\nexport type ExtractResult<T extends StagehandZodSchema> =\n  InferStagehandSchema<T>;\n\nexport interface Action {\n  selector: string;\n  description: string;\n  method?: string;\n  arguments?: string[];\n}\n\nexport interface HistoryEntry {\n  method: \"act\" | \"extract\" | \"observe\" | \"navigate\" | \"agent\";\n  parameters: unknown;\n  result: unknown;\n  timestamp: string;\n}\n\nexport interface ExtractOptions {\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;\n}\n\nexport const defaultExtractSchema = z.object({\n  extraction: z.string(),\n});\n\nexport const pageTextSchema = z.object({\n  pageText: z.string(),\n});\n\nexport interface ObserveOptions {\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;\n}\n\nexport enum V3FunctionName {\n  ACT = \"ACT\",\n  EXTRACT = \"EXTRACT\",\n  OBSERVE = \"OBSERVE\",\n  AGENT = \"AGENT\",\n}\n"]}
+{"version":3,"file":"methods.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/methods.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA8DxB,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;CACrB,CAAC,CAAC;AAuBH,MAAM,CAAN,IAAY,cAKX;AALD,WAAY,cAAc;IACxB,6BAAW,CAAA;IACX,qCAAmB,CAAA;IACnB,qCAAmB,CAAA;IACnB,iCAAe,CAAA;AACjB,CAAC,EALW,cAAc,KAAd,cAAc,QAKzB","sourcesContent":["import { Page as PatchrightPage } from \"patchright-core\";\nimport { Page as PlaywrightPage } from \"playwright-core\";\nimport { Page as PuppeteerPage } from \"puppeteer-core\";\nimport { z } from \"zod\";\nimport type {\n  InferStagehandSchema,\n  StagehandZodSchema,\n} from \"../../zodCompat.js\";\nimport { Page } from \"../../understudy/page.js\";\nimport { ModelConfiguration } from \"../public/model.js\";\nimport type { Variables } from \"./agent.js\";\n\nexport interface ActOptions {\n  model?: ModelConfiguration;\n  variables?: Variables;\n  timeout?: number;\n  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;\n  /**\n   * Override the instance-level serverCache setting for this request.\n   * When true, enables server-side caching.\n   * When false, disables server-side caching.\n   */\n  serverCache?: boolean;\n}\n\nexport interface ActResult {\n  success: boolean;\n  message: string;\n  actionDescription: string;\n  actions: Action[];\n  cacheStatus?: \"HIT\" | \"MISS\";\n}\n\nexport type ExtractResult<T extends StagehandZodSchema> =\n  InferStagehandSchema<T> & {\n    cacheStatus?: \"HIT\" | \"MISS\";\n  };\n\nexport interface Action {\n  selector: string;\n  description: string;\n  method?: string;\n  arguments?: string[];\n}\n\nexport interface HistoryEntry {\n  method: \"act\" | \"extract\" | \"observe\" | \"navigate\" | \"agent\";\n  parameters: unknown;\n  result: unknown;\n  timestamp: string;\n}\n\nexport interface ExtractOptions {\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;\n  /**\n   * Override the instance-level serverCache setting for this request.\n   * When true, enables server-side caching.\n   * When false, disables server-side caching.\n   */\n  serverCache?: boolean;\n}\n\nexport const defaultExtractSchema = z.object({\n  extraction: z.string(),\n});\n\nexport const pageTextSchema = z.object({\n  pageText: z.string(),\n});\n\nexport interface ObserveOptions {\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;\n  /**\n   * Override the instance-level serverCache setting for this request.\n   * When true, enables server-side caching.\n   * When false, disables server-side caching.\n   */\n  serverCache?: boolean;\n}\n\n/**\n * Observe returns an array of candidate actions. The optional `cacheStatus`\n * property is attached when the server responds with a\n * `browserbase-cache-status` header so callers can tell whether the result\n * was served from the server-side cache.\n */\nexport type ObserveResult = Action[] & { cacheStatus?: \"HIT\" | \"MISS\" };\n\nexport enum V3FunctionName {\n  ACT = \"ACT\",\n  EXTRACT = \"EXTRACT\",\n  OBSERVE = \"OBSERVE\",\n  AGENT = \"AGENT\",\n}\n"]}

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

@@ -18,7 +18,7 @@ export interface GoogleServiceAccountCredentials {
     client_x509_cert_url?: string;
     universe_domain?: string;
 }
-export type GoogleVertexProviderSettings = Pick<GoogleVertexProviderSettingsBase, "project" | "location"> & {
+export type GoogleVertexProviderSettings = Pick<GoogleVertexProviderSettingsBase, "project" | "location" | "headers"> & {
     googleAuthOptions?: {
         credentials?: GoogleServiceAccountCredentials;
     };
@@ -41,7 +41,7 @@ export interface LLMTool {
 }
 export type AISDKProvider = (modelName: string) => LanguageModelV2;
 export type AISDKCustomProvider = (options: ClientOptions) => AISDKProvider;
-export type AvailableModel = "gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "o4-mini" | "o3" | "o3-mini" | "o1" | "o1-mini" | "gpt-4o" | "gpt-4o-mini" | "gpt-4o-2024-08-06" | "gpt-4.5-preview" | "o1-preview" | "claude-3-5-sonnet-latest" | "claude-3-5-sonnet-20241022" | "claude-3-5-sonnet-20240620" | "claude-3-7-sonnet-latest" | "claude-3-7-sonnet-20250219" | "cerebras-llama-3.3-70b" | "cerebras-llama-3.1-8b" | "groq-llama-3.3-70b-versatile" | "groq-llama-3.3-70b-specdec" | "gemini-1.5-flash" | "gemini-1.5-pro" | "gemini-1.5-flash-8b" | "gemini-2.0-flash-lite" | "gemini-2.0-flash" | "gemini-2.5-flash-preview-04-17" | "gemini-2.5-pro-preview-03-25" | string;
+export type AvailableModel = "gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "o4-mini" | "o3" | "o3-mini" | "o1" | "o1-mini" | "gpt-4o" | "gpt-4o-mini" | "gpt-4o-2024-08-06" | "gpt-4.5-preview" | "o1-preview" | "cerebras-llama-3.3-70b" | "cerebras-llama-3.1-8b" | "groq-llama-3.3-70b-versatile" | "groq-llama-3.3-70b-specdec" | "gemini-1.5-flash" | "gemini-1.5-pro" | "gemini-1.5-flash-8b" | "gemini-2.0-flash-lite" | "gemini-2.0-flash" | "gemini-2.5-flash-preview-04-17" | "gemini-2.5-pro-preview-03-25" | string;
 export type ModelProvider = "openai" | "anthropic" | "cerebras" | "groq" | "google" | "aisdk";
 export type ClientOptions = (OpenAIClientOptions | AnthropicClientOptions | GoogleVertexProviderSettings) & {
     apiKey?: string;
@@ -59,6 +59,8 @@ export type ClientOptions = (OpenAIClientOptions | AnthropicClientOptions | Goog
     maxImages?: number;
     /** Temperature for model inference */
     temperature?: number;
+    /** Custom headers sent with every request to the provider */
+    headers?: Record<string, string>;
 };
 export type ModelConfiguration = AvailableModel | (ClientOptions & {
     modelName: AvailableModel;

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

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/model.ts"],"names":[],"mappings":"","sourcesContent":["import type { ClientOptions as AnthropicClientOptionsBase } from \"@anthropic-ai/sdk\";\nimport type { GoogleVertexProviderSettings as GoogleVertexProviderSettingsBase } from \"@ai-sdk/google-vertex\";\nimport type { LanguageModelV2 } from \"@ai-sdk/provider\";\nimport type { ClientOptions as OpenAIClientOptionsBase } from \"openai\";\nimport type { AgentProviderType } from \"./agent.js\";\n\nexport type OpenAIClientOptions = Pick<\n  OpenAIClientOptionsBase,\n  \"baseURL\" | \"apiKey\"\n>;\n\nexport type AnthropicClientOptions = Pick<\n  AnthropicClientOptionsBase,\n  \"baseURL\" | \"apiKey\"\n>;\n\nexport interface GoogleServiceAccountCredentials {\n  type?: string;\n  project_id?: string;\n  private_key_id?: string;\n  private_key?: string;\n  client_email?: string;\n  client_id?: string;\n  auth_uri?: string;\n  token_uri?: string;\n  auth_provider_x509_cert_url?: string;\n  client_x509_cert_url?: string;\n  universe_domain?: string;\n}\n\nexport type GoogleVertexProviderSettings = Pick<\n  GoogleVertexProviderSettingsBase,\n  \"project\" | \"location\"\n> & {\n  googleAuthOptions?: {\n    credentials?: GoogleServiceAccountCredentials;\n  };\n};\n\nexport type AnthropicJsonSchemaObject = {\n  definitions?: {\n    MySchema?: {\n      properties?: Record<string, unknown>;\n      required?: string[];\n    };\n  };\n  properties?: Record<string, unknown>;\n  required?: string[];\n} & Record<string, unknown>;\n\nexport interface LLMTool {\n  type: \"function\";\n  name: string;\n  description: string;\n  parameters: Record<string, unknown>;\n}\n\nexport type AISDKProvider = (modelName: string) => LanguageModelV2;\n// Represents a function that takes options (like apiKey) and returns an AISDKProvider\nexport type AISDKCustomProvider = (options: ClientOptions) => AISDKProvider;\n\nexport type AvailableModel =\n  | \"gpt-4.1\"\n  | \"gpt-4.1-mini\"\n  | \"gpt-4.1-nano\"\n  | \"o4-mini\"\n  | \"o3\"\n  | \"o3-mini\"\n  | \"o1\"\n  | \"o1-mini\"\n  | \"gpt-4o\"\n  | \"gpt-4o-mini\"\n  | \"gpt-4o-2024-08-06\"\n  | \"gpt-4.5-preview\"\n  | \"o1-preview\"\n  | \"claude-3-5-sonnet-latest\"\n  | \"claude-3-5-sonnet-20241022\"\n  | \"claude-3-5-sonnet-20240620\"\n  | \"claude-3-7-sonnet-latest\"\n  | \"claude-3-7-sonnet-20250219\"\n  | \"cerebras-llama-3.3-70b\"\n  | \"cerebras-llama-3.1-8b\"\n  | \"groq-llama-3.3-70b-versatile\"\n  | \"groq-llama-3.3-70b-specdec\"\n  | \"gemini-1.5-flash\"\n  | \"gemini-1.5-pro\"\n  | \"gemini-1.5-flash-8b\"\n  | \"gemini-2.0-flash-lite\"\n  | \"gemini-2.0-flash\"\n  | \"gemini-2.5-flash-preview-04-17\"\n  | \"gemini-2.5-pro-preview-03-25\"\n  | string;\n\nexport type ModelProvider =\n  | \"openai\"\n  | \"anthropic\"\n  | \"cerebras\"\n  | \"groq\"\n  | \"google\"\n  | \"aisdk\";\n\nexport type ClientOptions = (\n  | OpenAIClientOptions\n  | AnthropicClientOptions\n  | GoogleVertexProviderSettings\n) & {\n  apiKey?: string;\n  provider?: AgentProviderType;\n  baseURL?: string;\n  /** OpenAI organization ID */\n  organization?: string;\n  /** Delay between agent actions in ms */\n  waitBetweenActions?: number;\n  /** Anthropic thinking budget for extended thinking */\n  thinkingBudget?: number;\n  /** Environment type for CUA agents (browser, mac, windows, ubuntu) */\n  environment?: string;\n  /** Max images for Microsoft FARA agent */\n  maxImages?: number;\n  /** Temperature for model inference */\n  temperature?: number;\n};\n\nexport type ModelConfiguration =\n  | AvailableModel\n  | (ClientOptions & { modelName: AvailableModel });\n"]}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/model.ts"],"names":[],"mappings":"","sourcesContent":["import type { ClientOptions as AnthropicClientOptionsBase } from \"@anthropic-ai/sdk\";\nimport type { GoogleVertexProviderSettings as GoogleVertexProviderSettingsBase } from \"@ai-sdk/google-vertex\";\nimport type { LanguageModelV2 } from \"@ai-sdk/provider\";\nimport type { ClientOptions as OpenAIClientOptionsBase } from \"openai\";\nimport type { AgentProviderType } from \"./agent.js\";\n\nexport type OpenAIClientOptions = Pick<\n  OpenAIClientOptionsBase,\n  \"baseURL\" | \"apiKey\"\n>;\n\nexport type AnthropicClientOptions = Pick<\n  AnthropicClientOptionsBase,\n  \"baseURL\" | \"apiKey\"\n>;\n\nexport interface GoogleServiceAccountCredentials {\n  type?: string;\n  project_id?: string;\n  private_key_id?: string;\n  private_key?: string;\n  client_email?: string;\n  client_id?: string;\n  auth_uri?: string;\n  token_uri?: string;\n  auth_provider_x509_cert_url?: string;\n  client_x509_cert_url?: string;\n  universe_domain?: string;\n}\n\nexport type GoogleVertexProviderSettings = Pick<\n  GoogleVertexProviderSettingsBase,\n  \"project\" | \"location\" | \"headers\"\n> & {\n  googleAuthOptions?: {\n    credentials?: GoogleServiceAccountCredentials;\n  };\n};\n\nexport type AnthropicJsonSchemaObject = {\n  definitions?: {\n    MySchema?: {\n      properties?: Record<string, unknown>;\n      required?: string[];\n    };\n  };\n  properties?: Record<string, unknown>;\n  required?: string[];\n} & Record<string, unknown>;\n\nexport interface LLMTool {\n  type: \"function\";\n  name: string;\n  description: string;\n  parameters: Record<string, unknown>;\n}\n\nexport type AISDKProvider = (modelName: string) => LanguageModelV2;\n// Represents a function that takes options (like apiKey) and returns an AISDKProvider\nexport type AISDKCustomProvider = (options: ClientOptions) => AISDKProvider;\n\nexport type AvailableModel =\n  | \"gpt-4.1\"\n  | \"gpt-4.1-mini\"\n  | \"gpt-4.1-nano\"\n  | \"o4-mini\"\n  | \"o3\"\n  | \"o3-mini\"\n  | \"o1\"\n  | \"o1-mini\"\n  | \"gpt-4o\"\n  | \"gpt-4o-mini\"\n  | \"gpt-4o-2024-08-06\"\n  | \"gpt-4.5-preview\"\n  | \"o1-preview\"\n  | \"cerebras-llama-3.3-70b\"\n  | \"cerebras-llama-3.1-8b\"\n  | \"groq-llama-3.3-70b-versatile\"\n  | \"groq-llama-3.3-70b-specdec\"\n  | \"gemini-1.5-flash\"\n  | \"gemini-1.5-pro\"\n  | \"gemini-1.5-flash-8b\"\n  | \"gemini-2.0-flash-lite\"\n  | \"gemini-2.0-flash\"\n  | \"gemini-2.5-flash-preview-04-17\"\n  | \"gemini-2.5-pro-preview-03-25\"\n  | string;\n\nexport type ModelProvider =\n  | \"openai\"\n  | \"anthropic\"\n  | \"cerebras\"\n  | \"groq\"\n  | \"google\"\n  | \"aisdk\";\n\nexport type ClientOptions = (\n  | OpenAIClientOptions\n  | AnthropicClientOptions\n  | GoogleVertexProviderSettings\n) & {\n  apiKey?: string;\n  provider?: AgentProviderType;\n  baseURL?: string;\n  /** OpenAI organization ID */\n  organization?: string;\n  /** Delay between agent actions in ms */\n  waitBetweenActions?: number;\n  /** Anthropic thinking budget for extended thinking */\n  thinkingBudget?: number;\n  /** Environment type for CUA agents (browser, mac, windows, ubuntu) */\n  environment?: string;\n  /** Max images for Microsoft FARA agent */\n  maxImages?: number;\n  /** Temperature for model inference */\n  temperature?: number;\n  /** Custom headers sent with every request to the provider */\n  headers?: Record<string, string>;\n};\n\nexport type ModelConfiguration =\n  | AvailableModel\n  | (ClientOptions & { modelName: AvailableModel });\n"]}

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

@@ -29,6 +29,7 @@ export declare const localBrowserLaunchOptionsSchema: z.ZodObject<{
     hasTouch: z.ZodOptional<z.ZodBoolean>;
     ignoreHTTPSErrors: z.ZodOptional<z.ZodBoolean>;
     cdpUrl: z.ZodOptional<z.ZodString>;
+    cdpHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     connectTimeoutMs: z.ZodOptional<z.ZodNumber>;
     downloadsPath: z.ZodOptional<z.ZodString>;
     acceptDownloads: z.ZodOptional<z.ZodBoolean>;
@@ -67,4 +68,11 @@ export interface V3Options {
     cacheDir?: string;
     domSettleTimeout?: number;
     disableAPI?: boolean;
+    /**
+     * When true, enables server-side caching for API 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;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/options.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,+BAA+B,GAChC,MAAM,UAAU,CAAC;AAIlB,0DAA0D;AAC1D,MAAM,CAAC,MAAM,+BAA+B,GAAG,+BAA+B,CAAC","sourcesContent":["import { z } from \"zod\";\nimport { LLMClient } from \"../../llm/LLMClient.js\";\nimport { ModelConfiguration } from \"./model.js\";\nimport { LogLine } from \"./logs.js\";\nimport {\n  type BrowserbaseSessionCreateParams,\n  LocalBrowserLaunchOptionsSchema,\n} from \"./api.js\";\n\nexport type V3Env = \"LOCAL\" | \"BROWSERBASE\";\n\n// Re-export for backwards compatibility (camelCase alias)\nexport const localBrowserLaunchOptionsSchema = LocalBrowserLaunchOptionsSchema;\n\nexport type LocalBrowserLaunchOptions = z.infer<\n  typeof LocalBrowserLaunchOptionsSchema\n>;\n\n/** Constructor options for V3 */\nexport interface V3Options {\n  env: V3Env;\n  // Browserbase (required when env = \"BROWSERBASE\")\n  apiKey?: string;\n  projectId?: string;\n  /**\n   * Optional: fine-tune Browserbase session creation or resume an existing session.\n   */\n  browserbaseSessionCreateParams?: BrowserbaseSessionCreateParams;\n  browserbaseSessionID?: string;\n  /**\n   * Controls browser keepalive behavior. When set, it overrides any value in\n   * browserbaseSessionCreateParams.keepAlive.\n   */\n  keepAlive?: boolean;\n\n  // Local Chromium (optional)\n  localBrowserLaunchOptions?: LocalBrowserLaunchOptions;\n\n  model?: ModelConfiguration;\n  llmClient?: LLMClient; // allow user to pass their own\n  systemPrompt?: string;\n  logInferenceToFile?: boolean;\n  experimental?: boolean;\n  verbose?: 0 | 1 | 2;\n  selfHeal?: boolean;\n  // V2 compatibility fields - only included because the server imports this type and supports V2\n  waitForCaptchaSolves?: boolean;\n  actTimeoutMs?: number;\n  /** Disable pino logging backend (useful for tests or minimal environments). */\n  disablePino?: boolean;\n  /** Optional external logger hook for integrating with host apps. */\n  logger?: (line: LogLine) => void;\n  /** Directory used to persist cached actions for act(). */\n  cacheDir?: string;\n  domSettleTimeout?: number;\n  disableAPI?: boolean;\n}\n"]}
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/options.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,+BAA+B,GAChC,MAAM,UAAU,CAAC;AAIlB,0DAA0D;AAC1D,MAAM,CAAC,MAAM,+BAA+B,GAAG,+BAA+B,CAAC","sourcesContent":["import { z } from \"zod\";\nimport { LLMClient } from \"../../llm/LLMClient.js\";\nimport { ModelConfiguration } from \"./model.js\";\nimport { LogLine } from \"./logs.js\";\nimport {\n  type BrowserbaseSessionCreateParams,\n  LocalBrowserLaunchOptionsSchema,\n} from \"./api.js\";\n\nexport type V3Env = \"LOCAL\" | \"BROWSERBASE\";\n\n// Re-export for backwards compatibility (camelCase alias)\nexport const localBrowserLaunchOptionsSchema = LocalBrowserLaunchOptionsSchema;\n\nexport type LocalBrowserLaunchOptions = z.infer<\n  typeof LocalBrowserLaunchOptionsSchema\n>;\n\n/** Constructor options for V3 */\nexport interface V3Options {\n  env: V3Env;\n  // Browserbase (required when env = \"BROWSERBASE\")\n  apiKey?: string;\n  projectId?: string;\n  /**\n   * Optional: fine-tune Browserbase session creation or resume an existing session.\n   */\n  browserbaseSessionCreateParams?: BrowserbaseSessionCreateParams;\n  browserbaseSessionID?: string;\n  /**\n   * Controls browser keepalive behavior. When set, it overrides any value in\n   * browserbaseSessionCreateParams.keepAlive.\n   */\n  keepAlive?: boolean;\n\n  // Local Chromium (optional)\n  localBrowserLaunchOptions?: LocalBrowserLaunchOptions;\n\n  model?: ModelConfiguration;\n  llmClient?: LLMClient; // allow user to pass their own\n  systemPrompt?: string;\n  logInferenceToFile?: boolean;\n  experimental?: boolean;\n  verbose?: 0 | 1 | 2;\n  selfHeal?: boolean;\n  // V2 compatibility fields - only included because the server imports this type and supports V2\n  waitForCaptchaSolves?: boolean;\n  actTimeoutMs?: number;\n  /** Disable pino logging backend (useful for tests or minimal environments). */\n  disablePino?: boolean;\n  /** Optional external logger hook for integrating with host apps. */\n  logger?: (line: LogLine) => void;\n  /** Directory used to persist cached actions for act(). */\n  cacheDir?: string;\n  domSettleTimeout?: number;\n  disableAPI?: boolean;\n  /**\n   * When true, enables server-side caching for API requests.\n   * When false, disables server-side caching.\n   * Defaults to true (caching enabled).\n   * Can be overridden per-method in act(), extract(), and observe() options.\n   */\n  serverCache?: boolean;\n}\n"]}

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

@@ -42,6 +42,12 @@ export declare class HandlerNotInitializedError extends StagehandError {
 export declare class StagehandInvalidArgumentError extends StagehandError {
     constructor(message: string);
 }
+export declare class CookieValidationError extends StagehandError {
+    constructor(message: string);
+}
+export declare class CookieSetError extends StagehandError {
+    constructor(message: string);
+}
 export declare class StagehandElementNotFoundError extends StagehandError {
     constructor(xpaths: string[]);
 }
@@ -147,6 +153,13 @@ export declare class AgentAbortError extends StagehandError {
 export declare class StagehandClosedError extends StagehandError {
     constructor();
 }
+export declare class CdpConnectionClosedError extends StagehandError {
+    constructor(reason: string);
+}
+export declare class StagehandSetExtraHTTPHeadersError extends StagehandError {
+    readonly failures: string[];
+    constructor(failures: string[]);
+}
 export declare class StagehandSnapshotError extends StagehandError {
     constructor(cause?: unknown);
 }

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

@@ -89,6 +89,16 @@ export class StagehandInvalidArgumentError extends StagehandError {
         super(`InvalidArgumentError: ${message}`);
     }
 }
+export class CookieValidationError extends StagehandError {
+    constructor(message) {
+        super(message);
+    }
+}
+export class CookieSetError extends StagehandError {
+    constructor(message) {
+        super(message);
+    }
+}
 export class StagehandElementNotFoundError extends StagehandError {
     constructor(xpaths) {
         super(`Could not find an element for the given xPath(s): ${xpaths}`);
@@ -292,6 +302,18 @@ export class StagehandClosedError extends StagehandError {
         super("Stagehand session was closed");
     }
 }
+export class CdpConnectionClosedError extends StagehandError {
+    constructor(reason) {
+        super(`CDP connection closed: ${reason}`);
+    }
+}
+export class StagehandSetExtraHTTPHeadersError extends StagehandError {
+    failures;
+    constructor(failures) {
+        super(`setExtraHTTPHeaders failed for ${failures.length} session(s): ${failures.join(", ")}`);
+        this.failures = failures;
+    }
+}
 export class StagehandSnapshotError extends StagehandError {
     constructor(cause) {
         const suffix = cause instanceof Error

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

@@ -1 +1 @@
-{"version":3,"file":"sdkErrors.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/sdkErrors.ts"],"names":[],"mappings":"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","sourcesContent":["import { ZodError } from \"zod\";\n// Avoid .js extension so bundlers resolve TS source\nimport { STAGEHAND_VERSION } from \"../../../version.js\";\n\nexport class StagehandError extends Error {\n  public readonly cause?: unknown;\n\n  constructor(message: string, cause?: unknown) {\n    super(message);\n    this.name = this.constructor.name;\n    if (cause !== undefined) {\n      this.cause = cause;\n    }\n  }\n}\n\nexport class StagehandDefaultError extends StagehandError {\n  constructor(error?: unknown) {\n    if (error instanceof Error || error instanceof StagehandError) {\n      super(\n        `\\nHey! We're sorry you ran into an error. \\nStagehand version: ${STAGEHAND_VERSION} \\nIf you need help, please open a Github issue or reach out to us on Discord: https://stagehand.dev/discord\\n\\nFull error:\\n${error.message}`,\n      );\n    }\n  }\n}\n\nexport class StagehandEnvironmentError extends StagehandError {\n  constructor(\n    currentEnvironment: string,\n    requiredEnvironment: string,\n    feature: string,\n  ) {\n    super(\n      `You seem to be setting the current environment to ${currentEnvironment}.` +\n        `Ensure the environment is set to ${requiredEnvironment} if you want to use ${feature}.`,\n    );\n  }\n}\n\nexport class MissingEnvironmentVariableError extends StagehandError {\n  constructor(missingEnvironmentVariable: string, feature: string) {\n    super(\n      `${missingEnvironmentVariable} is required to use ${feature}.` +\n        `Please set ${missingEnvironmentVariable} in your environment.`,\n    );\n  }\n}\n\nexport class UnsupportedModelError extends StagehandError {\n  constructor(supportedModels: string[], feature?: string) {\n    const message = feature\n      ? `${feature} requires a valid model.`\n      : `Unsupported model.`;\n\n    const guidance =\n      `\\n\\nPlease use the provider/model format (e.g., \"openai/gpt-4o\", \"anthropic/claude-sonnet-4-5\", \"google/gemini-3-flash-preview\").` +\n      `\\n\\nFor a complete list of supported models and providers, see: https://docs.stagehand.dev/v3/configuration/models#configuration-setup`;\n\n    super(`${message}${guidance}`);\n  }\n}\n\nexport class UnsupportedModelProviderError extends StagehandError {\n  constructor(supportedProviders: string[], feature?: string) {\n    super(\n      feature\n        ? `${feature} requires one of the following model providers: ${supportedProviders}`\n        : `please use one of the supported model providers: ${supportedProviders}`,\n    );\n  }\n}\n\nexport class UnsupportedAISDKModelProviderError extends StagehandError {\n  constructor(provider: string, supportedProviders: string[]) {\n    super(\n      `${provider} is not currently supported for aiSDK. please use one of the supported model providers: ${supportedProviders}`,\n    );\n  }\n}\n\nexport class InvalidAISDKModelFormatError extends StagehandError {\n  constructor(modelName: string) {\n    super(\n      `${modelName} does not follow correct format for specifying aiSDK models. Please define your model as 'provider/model-name'. For example: \\`model: 'openai/gpt-4o-mini'\\``,\n    );\n  }\n}\n\nexport class StagehandNotInitializedError extends StagehandError {\n  constructor(prop: string) {\n    super(\n      `You seem to be calling \\`${prop}\\` on a page in an uninitialized \\`Stagehand\\` object. ` +\n        `Ensure you are running \\`await stagehand.init()\\` on the Stagehand object before ` +\n        `referencing the \\`page\\` object.`,\n    );\n  }\n}\n\nexport class BrowserbaseSessionNotFoundError extends StagehandError {\n  constructor() {\n    super(\"No Browserbase session ID found\");\n  }\n}\n\nexport class CaptchaTimeoutError extends StagehandError {\n  constructor() {\n    super(\"Captcha timeout\");\n  }\n}\n\nexport class MissingLLMConfigurationError extends StagehandError {\n  constructor() {\n    super(\n      \"No LLM API key or LLM Client configured. An LLM API key or a custom LLM Client \" +\n        \"is required to use act, extract, or observe.\",\n    );\n  }\n}\n\nexport class HandlerNotInitializedError extends StagehandError {\n  constructor(handlerType: string) {\n    super(`${handlerType} handler not initialized`);\n  }\n}\n\nexport class StagehandInvalidArgumentError extends StagehandError {\n  constructor(message: string) {\n    super(`InvalidArgumentError: ${message}`);\n  }\n}\n\nexport class StagehandElementNotFoundError extends StagehandError {\n  constructor(xpaths: string[]) {\n    super(`Could not find an element for the given xPath(s): ${xpaths}`);\n  }\n}\n\nexport class AgentScreenshotProviderError extends StagehandError {\n  constructor(message: string) {\n    super(`ScreenshotProviderError: ${message}`);\n  }\n}\n\nexport class StagehandMissingArgumentError extends StagehandError {\n  constructor(message: string) {\n    super(`MissingArgumentError: ${message}`);\n  }\n}\n\nexport class CreateChatCompletionResponseError extends StagehandError {\n  constructor(message: string) {\n    super(`CreateChatCompletionResponseError: ${message}`);\n  }\n}\n\nexport class StagehandEvalError extends StagehandError {\n  constructor(message: string) {\n    super(`StagehandEvalError: ${message}`);\n  }\n}\n\nexport class StagehandDomProcessError extends StagehandError {\n  constructor(message: string) {\n    super(`Error Processing Dom: ${message}`);\n  }\n}\n\nexport class StagehandLocatorError extends StagehandError {\n  constructor(action: string, selector: string, message: string) {\n    super(\n      `Error ${action} Element with selector: ${selector} Reason: ${message}`,\n    );\n  }\n}\n\nexport class StagehandClickError extends StagehandError {\n  constructor(message: string, selector: string) {\n    super(\n      `Error Clicking Element with selector: ${selector} Reason: ${message}`,\n    );\n  }\n}\n\nexport class LLMResponseError extends StagehandError {\n  constructor(primitive: string, message: string) {\n    super(`${primitive} LLM response error: ${message}`);\n  }\n}\n\nexport class StagehandIframeError extends StagehandError {\n  constructor(frameUrl: string, message: string) {\n    super(\n      `Unable to resolve frameId for iframe with URL: ${frameUrl} Full error: ${message}`,\n    );\n  }\n}\n\nexport class ContentFrameNotFoundError extends StagehandError {\n  constructor(selector: string) {\n    super(`Unable to obtain a content frame for selector: ${selector}`);\n  }\n}\n\nexport class XPathResolutionError extends StagehandError {\n  constructor(xpath: string) {\n    super(`XPath \"${xpath}\" does not resolve in the current page or frames`);\n  }\n}\n\nexport class ExperimentalApiConflictError extends StagehandError {\n  constructor() {\n    super(\n      \"`experimental` mode cannot be used together with the Stagehand API. \" +\n        \"To use experimental features, set experimental: true and disableAPI: true in the stagehand constructor. \" +\n        \"To use the Stagehand API, set experimental: false and disableAPI: false (or omit it) in the stagehand constructor.\",\n    );\n  }\n}\n\nexport class ExperimentalNotConfiguredError extends StagehandError {\n  constructor(featureName: string) {\n    super(`Feature \"${featureName}\" is an experimental feature, and cannot be configured when disableAPI: false.\n    Please set experimental: true and disableAPI: true in the stagehand constructor to use this feature.\n    If you wish to use the Stagehand API, please ensure ${featureName} is not defined in your function call,\n    and set experimental: false, disableAPI: false (or omit it) in the Stagehand constructor.`);\n  }\n}\n\nexport class CuaModelRequiredError extends StagehandError {\n  constructor(availableModels: readonly string[]) {\n    super(\n      `To use the computer use agent (CUA), please provide a CUA model in the agent constructor or stagehand config. ` +\n        `Try one of our supported CUA models: ${availableModels.join(\", \")}`,\n    );\n  }\n}\n\nexport class ZodSchemaValidationError extends Error {\n  constructor(\n    public readonly received: unknown,\n    public readonly issues: ReturnType<ZodError[\"format\"]>,\n  ) {\n    super(`Zod schema validation failed\n\n— Received —\n${JSON.stringify(received, null, 2)}\n\n— Issues —\n${JSON.stringify(issues, null, 2)}`);\n    this.name = \"ZodSchemaValidationError\";\n  }\n}\n\nexport class StagehandInitError extends StagehandError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n\nexport class MCPConnectionError extends StagehandError {\n  public readonly serverUrl: string;\n  public readonly originalError: unknown;\n\n  constructor(serverUrl: string, originalError: unknown) {\n    const errorMessage =\n      originalError instanceof Error\n        ? originalError.message\n        : String(originalError);\n\n    super(\n      `Failed to connect to MCP server at \"${serverUrl}\". ${errorMessage}. ` +\n        `Please verify the server URL is correct and the server is running.`,\n    );\n\n    this.serverUrl = serverUrl;\n    this.originalError = originalError;\n  }\n}\n\nexport class StagehandShadowRootMissingError extends StagehandError {\n  constructor(detail?: string) {\n    super(\n      `No shadow root present on the resolved host` +\n        (detail ? `: ${detail}` : \"\"),\n    );\n  }\n}\n\nexport class StagehandShadowSegmentEmptyError extends StagehandError {\n  constructor() {\n    super(`Empty selector segment after shadow-DOM hop (\"//\")`);\n  }\n}\n\nexport class StagehandShadowSegmentNotFoundError extends StagehandError {\n  constructor(segment: string, hint?: string) {\n    super(\n      `Shadow segment '${segment}' matched no element inside shadow root` +\n        (hint ? ` ${hint}` : \"\"),\n    );\n  }\n}\n\nexport class ElementNotVisibleError extends StagehandError {\n  constructor(selector: string) {\n    super(`Element not visible (no box model): ${selector}`);\n  }\n}\n\nexport class ResponseBodyError extends StagehandError {\n  constructor(message: string) {\n    super(`Failed to retrieve response body: ${message}`);\n  }\n}\n\nexport class ResponseParseError extends StagehandError {\n  constructor(message: string) {\n    super(`Failed to parse response: ${message}`);\n  }\n}\n\nexport class TimeoutError extends StagehandError {\n  constructor(operation: string, timeoutMs: number) {\n    super(`${operation} timed out after ${timeoutMs}ms`);\n  }\n}\n\nexport class ActTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"act()\", timeoutMs);\n    this.name = \"ActTimeoutError\";\n  }\n}\n\nexport class ExtractTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"extract()\", timeoutMs);\n    this.name = \"ExtractTimeoutError\";\n  }\n}\n\nexport class ObserveTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"observe()\", timeoutMs);\n    this.name = \"ObserveTimeoutError\";\n  }\n}\n\nexport class PageNotFoundError extends StagehandError {\n  constructor(identifier: string) {\n    super(`No Page found for ${identifier}`);\n  }\n}\n\nexport class ConnectionTimeoutError extends StagehandError {\n  constructor(message: string) {\n    super(`Connection timeout: ${message}`);\n  }\n}\n\nexport class StreamingCallbacksInNonStreamingModeError extends StagehandError {\n  public readonly invalidCallbacks: string[];\n\n  constructor(invalidCallbacks: string[]) {\n    super(\n      `Streaming-only callback(s) \"${invalidCallbacks.join('\", \"')}\" cannot be used in non-streaming mode. ` +\n        `Set 'stream: true' in AgentConfig to use these callbacks.`,\n    );\n    this.invalidCallbacks = invalidCallbacks;\n  }\n}\n\nexport class AgentAbortError extends StagehandError {\n  public readonly reason: string;\n\n  constructor(reason?: string) {\n    const message = reason\n      ? `Agent execution was aborted: ${reason}`\n      : \"Agent execution was aborted\";\n    super(message);\n    this.reason = reason || \"aborted\";\n  }\n}\n\nexport class StagehandClosedError extends StagehandError {\n  constructor() {\n    super(\"Stagehand session was closed\");\n  }\n}\n\nexport class StagehandSnapshotError extends StagehandError {\n  constructor(cause?: unknown) {\n    const suffix =\n      cause instanceof Error\n        ? `: ${cause.message}`\n        : cause\n          ? `: ${String(cause)}`\n          : \"\";\n    super(`error taking snapshot${suffix}`, cause);\n  }\n}\n\nexport class UnderstudyCommandException extends StagehandError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = \"UnderstudyCommandException\";\n  }\n}\n"]}
+{"version":3,"file":"sdkErrors.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/sdkErrors.ts"],"names":[],"mappings":"AACA,oDAAoD;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvB,KAAK,CAAW;IAEhC,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAClC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACrB,CAAC;IACH,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IACvD,YAAY,KAAe;QACzB,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;YAC9D,KAAK,CACH,kEAAkE,iBAAiB,gIAAgI,KAAK,CAAC,OAAO,EAAE,CACnO,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAED,MAAM,OAAO,yBAA0B,SAAQ,cAAc;IAC3D,YACE,kBAA0B,EAC1B,mBAA2B,EAC3B,OAAe;QAEf,KAAK,CACH,qDAAqD,kBAAkB,GAAG;YACxE,oCAAoC,mBAAmB,uBAAuB,OAAO,GAAG,CAC3F,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,+BAAgC,SAAQ,cAAc;IACjE,YAAY,0BAAkC,EAAE,OAAe;QAC7D,KAAK,CACH,GAAG,0BAA0B,uBAAuB,OAAO,GAAG;YAC5D,cAAc,0BAA0B,uBAAuB,CAClE,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IACvD,YAAY,eAAyB,EAAE,OAAgB;QACrD,MAAM,OAAO,GAAG,OAAO;YACrB,CAAC,CAAC,GAAG,OAAO,0BAA0B;YACtC,CAAC,CAAC,oBAAoB,CAAC;QAEzB,MAAM,QAAQ,GACZ,mIAAmI;YACnI,wIAAwI,CAAC;QAE3I,KAAK,CAAC,GAAG,OAAO,GAAG,QAAQ,EAAE,CAAC,CAAC;IACjC,CAAC;CACF;AAED,MAAM,OAAO,6BAA8B,SAAQ,cAAc;IAC/D,YAAY,kBAA4B,EAAE,OAAgB;QACxD,KAAK,CACH,OAAO;YACL,CAAC,CAAC,GAAG,OAAO,mDAAmD,kBAAkB,EAAE;YACnF,CAAC,CAAC,oDAAoD,kBAAkB,EAAE,CAC7E,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,kCAAmC,SAAQ,cAAc;IACpE,YAAY,QAAgB,EAAE,kBAA4B;QACxD,KAAK,CACH,GAAG,QAAQ,2FAA2F,kBAAkB,EAAE,CAC3H,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,4BAA6B,SAAQ,cAAc;IAC9D,YAAY,SAAiB;QAC3B,KAAK,CACH,GAAG,SAAS,8JAA8J,CAC3K,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,4BAA6B,SAAQ,cAAc;IAC9D,YAAY,IAAY;QACtB,KAAK,CACH,4BAA4B,IAAI,yDAAyD;YACvF,mFAAmF;YACnF,kCAAkC,CACrC,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,+BAAgC,SAAQ,cAAc;IACjE;QACE,KAAK,CAAC,iCAAiC,CAAC,CAAC;IAC3C,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,cAAc;IACrD;QACE,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,4BAA6B,SAAQ,cAAc;IAC9D;QACE,KAAK,CACH,iFAAiF;YAC/E,8CAA8C,CACjD,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,0BAA2B,SAAQ,cAAc;IAC5D,YAAY,WAAmB;QAC7B,KAAK,CAAC,GAAG,WAAW,0BAA0B,CAAC,CAAC;IAClD,CAAC;CACF;AAED,MAAM,OAAO,6BAA8B,SAAQ,cAAc;IAC/D,YAAY,OAAe;QACzB,KAAK,CAAC,yBAAyB,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IACvD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,cAAc;IAChD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED,MAAM,OAAO,6BAA8B,SAAQ,cAAc;IAC/D,YAAY,MAAgB;QAC1B,KAAK,CAAC,qDAAqD,MAAM,EAAE,CAAC,CAAC;IACvE,CAAC;CACF;AAED,MAAM,OAAO,4BAA6B,SAAQ,cAAc;IAC9D,YAAY,OAAe;QACzB,KAAK,CAAC,4BAA4B,OAAO,EAAE,CAAC,CAAC;IAC/C,CAAC;CACF;AAED,MAAM,OAAO,6BAA8B,SAAQ,cAAc;IAC/D,YAAY,OAAe;QACzB,KAAK,CAAC,yBAAyB,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;CACF;AAED,MAAM,OAAO,iCAAkC,SAAQ,cAAc;IACnE,YAAY,OAAe;QACzB,KAAK,CAAC,sCAAsC,OAAO,EAAE,CAAC,CAAC;IACzD,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,cAAc;IACpD,YAAY,OAAe;QACzB,KAAK,CAAC,uBAAuB,OAAO,EAAE,CAAC,CAAC;IAC1C,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,cAAc;IAC1D,YAAY,OAAe;QACzB,KAAK,CAAC,yBAAyB,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IACvD,YAAY,MAAc,EAAE,QAAgB,EAAE,OAAe;QAC3D,KAAK,CACH,SAAS,MAAM,2BAA2B,QAAQ,YAAY,OAAO,EAAE,CACxE,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,cAAc;IACrD,YAAY,OAAe,EAAE,QAAgB;QAC3C,KAAK,CACH,yCAAyC,QAAQ,YAAY,OAAO,EAAE,CACvE,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,cAAc;IAClD,YAAY,SAAiB,EAAE,OAAe;QAC5C,KAAK,CAAC,GAAG,SAAS,wBAAwB,OAAO,EAAE,CAAC,CAAC;IACvD,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,cAAc;IACtD,YAAY,QAAgB,EAAE,OAAe;QAC3C,KAAK,CACH,kDAAkD,QAAQ,gBAAgB,OAAO,EAAE,CACpF,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,yBAA0B,SAAQ,cAAc;IAC3D,YAAY,QAAgB;QAC1B,KAAK,CAAC,kDAAkD,QAAQ,EAAE,CAAC,CAAC;IACtE,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,cAAc;IACtD,YAAY,KAAa;QACvB,KAAK,CAAC,UAAU,KAAK,kDAAkD,CAAC,CAAC;IAC3E,CAAC;CACF;AAED,MAAM,OAAO,4BAA6B,SAAQ,cAAc;IAC9D;QACE,KAAK,CACH,sEAAsE;YACpE,0GAA0G;YAC1G,oHAAoH,CACvH,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,8BAA+B,SAAQ,cAAc;IAChE,YAAY,WAAmB;QAC7B,KAAK,CAAC,YAAY,WAAW;;0DAEyB,WAAW;8FACyB,CAAC,CAAC;IAC9F,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IACvD,YAAY,eAAkC;QAC5C,KAAK,CACH,gHAAgH;YAC9G,wCAAwC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACvE,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAE/B;IACA;IAFlB,YACkB,QAAiB,EACjB,MAAsC;QAEtD,KAAK,CAAC;;;EAGR,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;;;EAGjC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QATjB,aAAQ,GAAR,QAAQ,CAAS;QACjB,WAAM,GAAN,MAAM,CAAgC;QAStD,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,cAAc;IACpD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,cAAc;IACpC,SAAS,CAAS;IAClB,aAAa,CAAU;IAEvC,YAAY,SAAiB,EAAE,aAAsB;QACnD,MAAM,YAAY,GAChB,aAAa,YAAY,KAAK;YAC5B,CAAC,CAAC,aAAa,CAAC,OAAO;YACvB,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QAE5B,KAAK,CACH,uCAAuC,SAAS,MAAM,YAAY,IAAI;YACpE,oEAAoE,CACvE,CAAC;QAEF,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;CACF;AAED,MAAM,OAAO,+BAAgC,SAAQ,cAAc;IACjE,YAAY,MAAe;QACzB,KAAK,CACH,6CAA6C;YAC3C,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAChC,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,gCAAiC,SAAQ,cAAc;IAClE;QACE,KAAK,CAAC,oDAAoD,CAAC,CAAC;IAC9D,CAAC;CACF;AAED,MAAM,OAAO,mCAAoC,SAAQ,cAAc;IACrE,YAAY,OAAe,EAAE,IAAa;QACxC,KAAK,CACH,mBAAmB,OAAO,yCAAyC;YACjE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAC3B,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,sBAAuB,SAAQ,cAAc;IACxD,YAAY,QAAgB;QAC1B,KAAK,CAAC,uCAAuC,QAAQ,EAAE,CAAC,CAAC;IAC3D,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,cAAc;IACnD,YAAY,OAAe;QACzB,KAAK,CAAC,qCAAqC,OAAO,EAAE,CAAC,CAAC;IACxD,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,cAAc;IACpD,YAAY,OAAe;QACzB,KAAK,CAAC,6BAA6B,OAAO,EAAE,CAAC,CAAC;IAChD,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,cAAc;IAC9C,YAAY,SAAiB,EAAE,SAAiB;QAC9C,KAAK,CAAC,GAAG,SAAS,oBAAoB,SAAS,IAAI,CAAC,CAAC;IACvD,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,YAAY;IAC/C,YAAY,SAAiB;QAC3B,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IACnD,YAAY,SAAiB;QAC3B,KAAK,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IACnD,YAAY,SAAiB;QAC3B,KAAK,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,cAAc;IACnD,YAAY,UAAkB;QAC5B,KAAK,CAAC,qBAAqB,UAAU,EAAE,CAAC,CAAC;IAC3C,CAAC;CACF;AAED,MAAM,OAAO,sBAAuB,SAAQ,cAAc;IACxD,YAAY,OAAe;QACzB,KAAK,CAAC,uBAAuB,OAAO,EAAE,CAAC,CAAC;IAC1C,CAAC;CACF;AAED,MAAM,OAAO,yCAA0C,SAAQ,cAAc;IAC3D,gBAAgB,CAAW;IAE3C,YAAY,gBAA0B;QACpC,KAAK,CACH,+BAA+B,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,0CAA0C;YACpG,2DAA2D,CAC9D,CAAC;QACF,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;IAC3C,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,cAAc;IACjC,MAAM,CAAS;IAE/B,YAAY,MAAe;QACzB,MAAM,OAAO,GAAG,MAAM;YACpB,CAAC,CAAC,gCAAgC,MAAM,EAAE;YAC1C,CAAC,CAAC,6BAA6B,CAAC;QAClC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,SAAS,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,cAAc;IACtD;QACE,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACxC,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,cAAc;IAC1D,YAAY,MAAc;QACxB,KAAK,CAAC,0BAA0B,MAAM,EAAE,CAAC,CAAC;IAC5C,CAAC;CACF;AAED,MAAM,OAAO,iCAAkC,SAAQ,cAAc;IACnD,QAAQ,CAAW;IAEnC,YAAY,QAAkB;QAC5B,KAAK,CACH,kCAAkC,QAAQ,CAAC,MAAM,gBAAgB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACvF,CAAC;QACF,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,sBAAuB,SAAQ,cAAc;IACxD,YAAY,KAAe;QACzB,MAAM,MAAM,GACV,KAAK,YAAY,KAAK;YACpB,CAAC,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE;YACtB,CAAC,CAAC,KAAK;gBACL,CAAC,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE;gBACtB,CAAC,CAAC,EAAE,CAAC;QACX,KAAK,CAAC,wBAAwB,MAAM,EAAE,EAAE,KAAK,CAAC,CAAC;IACjD,CAAC;CACF;AAED,MAAM,OAAO,0BAA2B,SAAQ,cAAc;IAC5D,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF","sourcesContent":["import { ZodError } from \"zod\";\n// Avoid .js extension so bundlers resolve TS source\nimport { STAGEHAND_VERSION } from \"../../../version.js\";\n\nexport class StagehandError extends Error {\n  public readonly cause?: unknown;\n\n  constructor(message: string, cause?: unknown) {\n    super(message);\n    this.name = this.constructor.name;\n    if (cause !== undefined) {\n      this.cause = cause;\n    }\n  }\n}\n\nexport class StagehandDefaultError extends StagehandError {\n  constructor(error?: unknown) {\n    if (error instanceof Error || error instanceof StagehandError) {\n      super(\n        `\\nHey! We're sorry you ran into an error. \\nStagehand version: ${STAGEHAND_VERSION} \\nIf you need help, please open a Github issue or reach out to us on Discord: https://stagehand.dev/discord\\n\\nFull error:\\n${error.message}`,\n      );\n    }\n  }\n}\n\nexport class StagehandEnvironmentError extends StagehandError {\n  constructor(\n    currentEnvironment: string,\n    requiredEnvironment: string,\n    feature: string,\n  ) {\n    super(\n      `You seem to be setting the current environment to ${currentEnvironment}.` +\n        `Ensure the environment is set to ${requiredEnvironment} if you want to use ${feature}.`,\n    );\n  }\n}\n\nexport class MissingEnvironmentVariableError extends StagehandError {\n  constructor(missingEnvironmentVariable: string, feature: string) {\n    super(\n      `${missingEnvironmentVariable} is required to use ${feature}.` +\n        `Please set ${missingEnvironmentVariable} in your environment.`,\n    );\n  }\n}\n\nexport class UnsupportedModelError extends StagehandError {\n  constructor(supportedModels: string[], feature?: string) {\n    const message = feature\n      ? `${feature} requires a valid model.`\n      : `Unsupported model.`;\n\n    const guidance =\n      `\\n\\nPlease use the provider/model format (e.g., \"openai/gpt-4o\", \"anthropic/claude-sonnet-4-5\", \"google/gemini-3-flash-preview\").` +\n      `\\n\\nFor a complete list of supported models and providers, see: https://docs.stagehand.dev/v3/configuration/models#configuration-setup`;\n\n    super(`${message}${guidance}`);\n  }\n}\n\nexport class UnsupportedModelProviderError extends StagehandError {\n  constructor(supportedProviders: string[], feature?: string) {\n    super(\n      feature\n        ? `${feature} requires one of the following model providers: ${supportedProviders}`\n        : `please use one of the supported model providers: ${supportedProviders}`,\n    );\n  }\n}\n\nexport class UnsupportedAISDKModelProviderError extends StagehandError {\n  constructor(provider: string, supportedProviders: string[]) {\n    super(\n      `${provider} is not currently supported for aiSDK. please use one of the supported model providers: ${supportedProviders}`,\n    );\n  }\n}\n\nexport class InvalidAISDKModelFormatError extends StagehandError {\n  constructor(modelName: string) {\n    super(\n      `${modelName} does not follow correct format for specifying aiSDK models. Please define your model as 'provider/model-name'. For example: \\`model: 'openai/gpt-4o-mini'\\``,\n    );\n  }\n}\n\nexport class StagehandNotInitializedError extends StagehandError {\n  constructor(prop: string) {\n    super(\n      `You seem to be calling \\`${prop}\\` on a page in an uninitialized \\`Stagehand\\` object. ` +\n        `Ensure you are running \\`await stagehand.init()\\` on the Stagehand object before ` +\n        `referencing the \\`page\\` object.`,\n    );\n  }\n}\n\nexport class BrowserbaseSessionNotFoundError extends StagehandError {\n  constructor() {\n    super(\"No Browserbase session ID found\");\n  }\n}\n\nexport class CaptchaTimeoutError extends StagehandError {\n  constructor() {\n    super(\"Captcha timeout\");\n  }\n}\n\nexport class MissingLLMConfigurationError extends StagehandError {\n  constructor() {\n    super(\n      \"No LLM API key or LLM Client configured. An LLM API key or a custom LLM Client \" +\n        \"is required to use act, extract, or observe.\",\n    );\n  }\n}\n\nexport class HandlerNotInitializedError extends StagehandError {\n  constructor(handlerType: string) {\n    super(`${handlerType} handler not initialized`);\n  }\n}\n\nexport class StagehandInvalidArgumentError extends StagehandError {\n  constructor(message: string) {\n    super(`InvalidArgumentError: ${message}`);\n  }\n}\n\nexport class CookieValidationError extends StagehandError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n\nexport class CookieSetError extends StagehandError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n\nexport class StagehandElementNotFoundError extends StagehandError {\n  constructor(xpaths: string[]) {\n    super(`Could not find an element for the given xPath(s): ${xpaths}`);\n  }\n}\n\nexport class AgentScreenshotProviderError extends StagehandError {\n  constructor(message: string) {\n    super(`ScreenshotProviderError: ${message}`);\n  }\n}\n\nexport class StagehandMissingArgumentError extends StagehandError {\n  constructor(message: string) {\n    super(`MissingArgumentError: ${message}`);\n  }\n}\n\nexport class CreateChatCompletionResponseError extends StagehandError {\n  constructor(message: string) {\n    super(`CreateChatCompletionResponseError: ${message}`);\n  }\n}\n\nexport class StagehandEvalError extends StagehandError {\n  constructor(message: string) {\n    super(`StagehandEvalError: ${message}`);\n  }\n}\n\nexport class StagehandDomProcessError extends StagehandError {\n  constructor(message: string) {\n    super(`Error Processing Dom: ${message}`);\n  }\n}\n\nexport class StagehandLocatorError extends StagehandError {\n  constructor(action: string, selector: string, message: string) {\n    super(\n      `Error ${action} Element with selector: ${selector} Reason: ${message}`,\n    );\n  }\n}\n\nexport class StagehandClickError extends StagehandError {\n  constructor(message: string, selector: string) {\n    super(\n      `Error Clicking Element with selector: ${selector} Reason: ${message}`,\n    );\n  }\n}\n\nexport class LLMResponseError extends StagehandError {\n  constructor(primitive: string, message: string) {\n    super(`${primitive} LLM response error: ${message}`);\n  }\n}\n\nexport class StagehandIframeError extends StagehandError {\n  constructor(frameUrl: string, message: string) {\n    super(\n      `Unable to resolve frameId for iframe with URL: ${frameUrl} Full error: ${message}`,\n    );\n  }\n}\n\nexport class ContentFrameNotFoundError extends StagehandError {\n  constructor(selector: string) {\n    super(`Unable to obtain a content frame for selector: ${selector}`);\n  }\n}\n\nexport class XPathResolutionError extends StagehandError {\n  constructor(xpath: string) {\n    super(`XPath \"${xpath}\" does not resolve in the current page or frames`);\n  }\n}\n\nexport class ExperimentalApiConflictError extends StagehandError {\n  constructor() {\n    super(\n      \"`experimental` mode cannot be used together with the Stagehand API. \" +\n        \"To use experimental features, set experimental: true and disableAPI: true in the stagehand constructor. \" +\n        \"To use the Stagehand API, set experimental: false and disableAPI: false (or omit it) in the stagehand constructor.\",\n    );\n  }\n}\n\nexport class ExperimentalNotConfiguredError extends StagehandError {\n  constructor(featureName: string) {\n    super(`Feature \"${featureName}\" is an experimental feature, and cannot be configured when disableAPI: false.\n    Please set experimental: true and disableAPI: true in the stagehand constructor to use this feature.\n    If you wish to use the Stagehand API, please ensure ${featureName} is not defined in your function call,\n    and set experimental: false, disableAPI: false (or omit it) in the Stagehand constructor.`);\n  }\n}\n\nexport class CuaModelRequiredError extends StagehandError {\n  constructor(availableModels: readonly string[]) {\n    super(\n      `To use the computer use agent (CUA), please provide a CUA model in the agent constructor or stagehand config. ` +\n        `Try one of our supported CUA models: ${availableModels.join(\", \")}`,\n    );\n  }\n}\n\nexport class ZodSchemaValidationError extends Error {\n  constructor(\n    public readonly received: unknown,\n    public readonly issues: ReturnType<ZodError[\"format\"]>,\n  ) {\n    super(`Zod schema validation failed\n\n— Received —\n${JSON.stringify(received, null, 2)}\n\n— Issues —\n${JSON.stringify(issues, null, 2)}`);\n    this.name = \"ZodSchemaValidationError\";\n  }\n}\n\nexport class StagehandInitError extends StagehandError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n\nexport class MCPConnectionError extends StagehandError {\n  public readonly serverUrl: string;\n  public readonly originalError: unknown;\n\n  constructor(serverUrl: string, originalError: unknown) {\n    const errorMessage =\n      originalError instanceof Error\n        ? originalError.message\n        : String(originalError);\n\n    super(\n      `Failed to connect to MCP server at \"${serverUrl}\". ${errorMessage}. ` +\n        `Please verify the server URL is correct and the server is running.`,\n    );\n\n    this.serverUrl = serverUrl;\n    this.originalError = originalError;\n  }\n}\n\nexport class StagehandShadowRootMissingError extends StagehandError {\n  constructor(detail?: string) {\n    super(\n      `No shadow root present on the resolved host` +\n        (detail ? `: ${detail}` : \"\"),\n    );\n  }\n}\n\nexport class StagehandShadowSegmentEmptyError extends StagehandError {\n  constructor() {\n    super(`Empty selector segment after shadow-DOM hop (\"//\")`);\n  }\n}\n\nexport class StagehandShadowSegmentNotFoundError extends StagehandError {\n  constructor(segment: string, hint?: string) {\n    super(\n      `Shadow segment '${segment}' matched no element inside shadow root` +\n        (hint ? ` ${hint}` : \"\"),\n    );\n  }\n}\n\nexport class ElementNotVisibleError extends StagehandError {\n  constructor(selector: string) {\n    super(`Element not visible (no box model): ${selector}`);\n  }\n}\n\nexport class ResponseBodyError extends StagehandError {\n  constructor(message: string) {\n    super(`Failed to retrieve response body: ${message}`);\n  }\n}\n\nexport class ResponseParseError extends StagehandError {\n  constructor(message: string) {\n    super(`Failed to parse response: ${message}`);\n  }\n}\n\nexport class TimeoutError extends StagehandError {\n  constructor(operation: string, timeoutMs: number) {\n    super(`${operation} timed out after ${timeoutMs}ms`);\n  }\n}\n\nexport class ActTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"act()\", timeoutMs);\n    this.name = \"ActTimeoutError\";\n  }\n}\n\nexport class ExtractTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"extract()\", timeoutMs);\n    this.name = \"ExtractTimeoutError\";\n  }\n}\n\nexport class ObserveTimeoutError extends TimeoutError {\n  constructor(timeoutMs: number) {\n    super(\"observe()\", timeoutMs);\n    this.name = \"ObserveTimeoutError\";\n  }\n}\n\nexport class PageNotFoundError extends StagehandError {\n  constructor(identifier: string) {\n    super(`No Page found for ${identifier}`);\n  }\n}\n\nexport class ConnectionTimeoutError extends StagehandError {\n  constructor(message: string) {\n    super(`Connection timeout: ${message}`);\n  }\n}\n\nexport class StreamingCallbacksInNonStreamingModeError extends StagehandError {\n  public readonly invalidCallbacks: string[];\n\n  constructor(invalidCallbacks: string[]) {\n    super(\n      `Streaming-only callback(s) \"${invalidCallbacks.join('\", \"')}\" cannot be used in non-streaming mode. ` +\n        `Set 'stream: true' in AgentConfig to use these callbacks.`,\n    );\n    this.invalidCallbacks = invalidCallbacks;\n  }\n}\n\nexport class AgentAbortError extends StagehandError {\n  public readonly reason: string;\n\n  constructor(reason?: string) {\n    const message = reason\n      ? `Agent execution was aborted: ${reason}`\n      : \"Agent execution was aborted\";\n    super(message);\n    this.reason = reason || \"aborted\";\n  }\n}\n\nexport class StagehandClosedError extends StagehandError {\n  constructor() {\n    super(\"Stagehand session was closed\");\n  }\n}\n\nexport class CdpConnectionClosedError extends StagehandError {\n  constructor(reason: string) {\n    super(`CDP connection closed: ${reason}`);\n  }\n}\n\nexport class StagehandSetExtraHTTPHeadersError extends StagehandError {\n  public readonly failures: string[];\n\n  constructor(failures: string[]) {\n    super(\n      `setExtraHTTPHeaders failed for ${failures.length} session(s): ${failures.join(\", \")}`,\n    );\n    this.failures = failures;\n  }\n}\n\nexport class StagehandSnapshotError extends StagehandError {\n  constructor(cause?: unknown) {\n    const suffix =\n      cause instanceof Error\n        ? `: ${cause.message}`\n        : cause\n          ? `: ${String(cause)}`\n          : \"\";\n    super(`error taking snapshot${suffix}`, cause);\n  }\n}\n\nexport class UnderstudyCommandException extends StagehandError {\n  constructor(message: string, cause?: unknown) {\n    super(message, cause);\n    this.name = \"UnderstudyCommandException\";\n  }\n}\n"]}

package/dist/esm/lib/v3/understudy/a11y/snapshot/focusSelectors.d.ts

@@ -8,6 +8,7 @@ import type { FrameParentIndex, ResolvedCssFocus, ResolvedFocusFrame, Step } fro
 export declare function parseXPathToSteps(path: string): Step[];
 /** Rebuild an XPath string from parsed steps. */
 export declare function buildXPathFromSteps(steps: ReadonlyArray<Step>): string;
+export declare const IFRAME_STEP_RE: RegExp;
 /**
  * Given a cross-frame XPath, walk iframe steps to resolve:
  * - the target frameId (last iframe hop)

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

@@ -40,7 +40,7 @@ export function buildXPathFromSteps(steps) {
     }
     return out || "/";
 }
-const IFRAME_STEP_RE = /^iframe(?:\[\d+])?$/i;
+export const IFRAME_STEP_RE = /^i?frame(?:\[\d+])?$/i;
 /**
  * Given a cross-frame XPath, walk iframe steps to resolve:
  * - the target frameId (last iframe hop)

package/dist/esm/lib/v3/understudy/a11y/snapshot/focusSelectors.js.map

@@ -1 +1 @@
-{"version":3,"file":"focusSelectors.js","sourceRoot":"","sources":["../../../../../../../lib/v3/understudy/a11y/snapshot/focusSelectors.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport type { CDPSessionLike } from \"../../cdp.js\";\nimport { Page } from \"../../page.js\";\nimport { executionContexts } from \"../../executionContextRegistry.js\";\nimport { buildLocatorInvocation } from \"../../locatorInvocation.js\";\nimport { StagehandIframeError } from \"../../../types/public/sdkErrors.js\";\nimport type {\n  Axis,\n  FrameParentIndex,\n  ResolvedCssFocus,\n  ResolvedFocusFrame,\n  Step,\n} from \"../../../types/private/snapshot.js\";\nimport { prefixXPath } from \"./xpathUtils.js\";\n\n/**\n * Parse a cross-frame XPath into discrete steps. Each step tracks whether it\n * represents a descendant hop (“//”) or a single-child hop (“/”).\n */\nexport function parseXPathToSteps(path: string): Step[] {\n  const s = path.trim();\n  let i = 0;\n  const steps: Step[] = [];\n  while (i < s.length) {\n    let axis: Axis = \"child\";\n    if (s.startsWith(\"//\", i)) {\n      axis = \"desc\";\n      i += 2;\n    } else if (s[i] === \"/\") {\n      axis = \"child\";\n      i += 1;\n    }\n\n    const start = i;\n    while (i < s.length && s[i] !== \"/\") i++;\n    const raw = s.slice(start, i).trim();\n    if (!raw) continue;\n    const name = raw.replace(/\\[\\d+\\]\\s*$/u, \"\").toLowerCase();\n    steps.push({ axis, raw, name });\n  }\n  return steps;\n}\n\n/** Rebuild an XPath string from parsed steps. */\nexport function buildXPathFromSteps(steps: ReadonlyArray<Step>): string {\n  let out = \"\";\n  for (const st of steps) {\n    out += st.axis === \"desc\" ? \"//\" : \"/\";\n    out += st.raw;\n  }\n  return out || \"/\";\n}\n\nconst IFRAME_STEP_RE = /^iframe(?:\\[\\d+])?$/i;\n\n/**\n * Given a cross-frame XPath, walk iframe steps to resolve:\n * - the target frameId (last iframe hop)\n * - the tail XPath (within the target frame)\n * - the absolute XPath prefix up to the iframe element hosting that frame\n */\nexport async function resolveFocusFrameAndTail(\n  page: Page,\n  absoluteXPath: string,\n  parentByFrame: FrameParentIndex,\n  rootId: string,\n): Promise<ResolvedFocusFrame> {\n  const steps = parseXPathToSteps(absoluteXPath);\n  let ctxFrameId = rootId;\n  let buf: Step[] = [];\n  let absPrefix = \"\";\n\n  const flushIntoChild = async (): Promise<void> => {\n    if (!buf.length) return;\n    const selectorForIframe = buildXPathFromSteps(buf);\n    const parentSess = page.getSessionForFrame(ctxFrameId);\n    const objectId = await resolveObjectIdForXPath(\n      parentSess,\n      selectorForIframe,\n      ctxFrameId,\n    );\n    if (!objectId)\n      throw new StagehandIframeError(\n        selectorForIframe,\n        \"Failed to resolve iframe element by XPath\",\n      );\n\n    try {\n      await parentSess.send(\"DOM.enable\").catch(() => {});\n      const desc = await parentSess.send<Protocol.DOM.DescribeNodeResponse>(\n        \"DOM.describeNode\",\n        { objectId },\n      );\n      const iframeBackendNodeId = desc.node.backendNodeId;\n\n      let childFrameId: string | undefined;\n      for (const fid of listChildrenOf(parentByFrame, ctxFrameId)) {\n        try {\n          const { backendNodeId } = await parentSess.send<{\n            backendNodeId: number;\n          }>(\"DOM.getFrameOwner\", { frameId: fid });\n          if (backendNodeId === iframeBackendNodeId) {\n            childFrameId = fid;\n            break;\n          }\n        } catch {\n          continue;\n        }\n      }\n      if (!childFrameId)\n        throw new StagehandIframeError(\n          selectorForIframe,\n          \"Could not map iframe to child frameId\",\n        );\n\n      absPrefix = prefixXPath(absPrefix || \"/\", selectorForIframe);\n      ctxFrameId = childFrameId;\n    } finally {\n      await parentSess\n        .send(\"Runtime.releaseObject\", { objectId })\n        .catch(() => {});\n    }\n\n    buf = [];\n  };\n\n  for (const st of steps) {\n    buf.push(st);\n    if (IFRAME_STEP_RE.test(st.name)) {\n      await flushIntoChild();\n    }\n  }\n\n  const tailXPath = buildXPathFromSteps(buf);\n  return { targetFrameId: ctxFrameId, tailXPath, absPrefix };\n}\n\n/** Resolve focus frame and tail CSS selector using '>>' to hop iframes. */\nexport async function resolveCssFocusFrameAndTail(\n  page: Page,\n  rawSelector: string,\n  parentByFrame: FrameParentIndex,\n  rootId: string,\n): Promise<ResolvedCssFocus> {\n  const parts = rawSelector\n    .split(\">>\")\n    .map((s) => s.trim())\n    .filter(Boolean);\n  let ctxFrameId = rootId;\n  const absPrefix = \"\";\n\n  for (let i = 0; i < Math.max(0, parts.length - 1); i++) {\n    const parentSess = page.getSessionForFrame(ctxFrameId);\n    const objectId = await resolveObjectIdForCss(\n      parentSess,\n      parts[i]!,\n      ctxFrameId,\n    );\n    if (!objectId)\n      throw new StagehandIframeError(\n        parts[i]!,\n        \"Failed to resolve iframe via CSS hop\",\n      );\n    try {\n      await parentSess.send(\"DOM.enable\").catch(() => {});\n      const desc = await parentSess.send<Protocol.DOM.DescribeNodeResponse>(\n        \"DOM.describeNode\",\n        { objectId },\n      );\n      const iframeBackendNodeId = desc.node.backendNodeId;\n      let childFrameId: string | undefined;\n      for (const fid of listChildrenOf(parentByFrame, ctxFrameId)) {\n        try {\n          const { backendNodeId } = await parentSess.send<{\n            backendNodeId: number;\n          }>(\"DOM.getFrameOwner\", { frameId: fid });\n          if (backendNodeId === iframeBackendNodeId) {\n            childFrameId = fid;\n            break;\n          }\n        } catch {\n          continue;\n        }\n      }\n      if (!childFrameId)\n        throw new StagehandIframeError(\n          parts[i]!,\n          \"Could not map CSS iframe hop to child frameId\",\n        );\n      ctxFrameId = childFrameId;\n    } finally {\n      await parentSess\n        .send(\"Runtime.releaseObject\", { objectId })\n        .catch(() => {});\n    }\n  }\n\n  const tailSelector = parts[parts.length - 1] ?? \"*\";\n  return { targetFrameId: ctxFrameId, tailSelector, absPrefix };\n}\n\n/** Resolve an XPath to a Runtime remoteObjectId in the given CDP session. */\nexport async function resolveObjectIdForXPath(\n  session: CDPSessionLike,\n  xpath: string,\n  frameId?: string,\n): Promise<string | null> {\n  let contextId: number | undefined;\n  try {\n    if (frameId) {\n      contextId = await executionContexts\n        .waitForMainWorld(session, frameId, 800)\n        .catch(\n          () => executionContexts.getMainWorld(session, frameId) ?? undefined,\n        );\n    }\n  } catch {\n    contextId = undefined;\n  }\n  const expr = buildLocatorInvocation(\"resolveXPathMainWorld\", [\n    JSON.stringify(xpath),\n    \"0\",\n  ]);\n  const { result, exceptionDetails } = await session.send<{\n    result: { objectId?: string | undefined };\n    exceptionDetails?: Protocol.Runtime.ExceptionDetails;\n  }>(\"Runtime.evaluate\", {\n    expression: expr,\n    returnByValue: false,\n    contextId,\n    awaitPromise: true,\n  });\n  if (exceptionDetails) return null;\n  return result?.objectId ?? null;\n}\n\n/** Resolve a CSS selector (supports '>>' within the same frame only) to a Runtime objectId. */\nexport async function resolveObjectIdForCss(\n  session: CDPSessionLike,\n  selector: string,\n  frameId?: string,\n): Promise<string | null> {\n  let contextId: number | undefined;\n  try {\n    if (frameId) {\n      contextId = await executionContexts\n        .waitForMainWorld(session, frameId, 800)\n        .catch(\n          () => executionContexts.getMainWorld(session, frameId) ?? undefined,\n        );\n    }\n  } catch {\n    contextId = undefined;\n  }\n  const primaryExpr = buildLocatorInvocation(\"resolveCssSelector\", [\n    JSON.stringify(selector),\n    \"0\",\n  ]);\n  const fallbackExpr = buildLocatorInvocation(\"resolveCssSelectorPierce\", [\n    JSON.stringify(selector),\n    \"0\",\n  ]);\n\n  const evaluate = async (expression: string): Promise<string | null> => {\n    const { result, exceptionDetails } = await session.send<{\n      result: { objectId?: string | undefined };\n      exceptionDetails?: Protocol.Runtime.ExceptionDetails;\n    }>(\"Runtime.evaluate\", {\n      expression,\n      returnByValue: false,\n      contextId,\n      awaitPromise: true,\n    });\n    if (exceptionDetails) return null;\n    return result?.objectId ?? null;\n  };\n\n  const primary = await evaluate(primaryExpr);\n  if (primary) return primary;\n  return evaluate(fallbackExpr);\n}\n\nexport function listChildrenOf(\n  parentByFrame: FrameParentIndex,\n  parentId: string,\n): string[] {\n  const out: string[] = [];\n  for (const [fid, p] of parentByFrame.entries()) {\n    if (p === parentId) out.push(fid);\n  }\n  return out;\n}\n"]}
+{"version":3,"file":"focusSelectors.js","sourceRoot":"","sources":["../../../../../../../lib/v3/understudy/a11y/snapshot/focusSelectors.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport type { CDPSessionLike } from \"../../cdp.js\";\nimport { Page } from \"../../page.js\";\nimport { executionContexts } from \"../../executionContextRegistry.js\";\nimport { buildLocatorInvocation } from \"../../locatorInvocation.js\";\nimport { StagehandIframeError } from \"../../../types/public/sdkErrors.js\";\nimport type {\n  Axis,\n  FrameParentIndex,\n  ResolvedCssFocus,\n  ResolvedFocusFrame,\n  Step,\n} from \"../../../types/private/snapshot.js\";\nimport { prefixXPath } from \"./xpathUtils.js\";\n\n/**\n * Parse a cross-frame XPath into discrete steps. Each step tracks whether it\n * represents a descendant hop (“//”) or a single-child hop (“/”).\n */\nexport function parseXPathToSteps(path: string): Step[] {\n  const s = path.trim();\n  let i = 0;\n  const steps: Step[] = [];\n  while (i < s.length) {\n    let axis: Axis = \"child\";\n    if (s.startsWith(\"//\", i)) {\n      axis = \"desc\";\n      i += 2;\n    } else if (s[i] === \"/\") {\n      axis = \"child\";\n      i += 1;\n    }\n\n    const start = i;\n    while (i < s.length && s[i] !== \"/\") i++;\n    const raw = s.slice(start, i).trim();\n    if (!raw) continue;\n    const name = raw.replace(/\\[\\d+\\]\\s*$/u, \"\").toLowerCase();\n    steps.push({ axis, raw, name });\n  }\n  return steps;\n}\n\n/** Rebuild an XPath string from parsed steps. */\nexport function buildXPathFromSteps(steps: ReadonlyArray<Step>): string {\n  let out = \"\";\n  for (const st of steps) {\n    out += st.axis === \"desc\" ? \"//\" : \"/\";\n    out += st.raw;\n  }\n  return out || \"/\";\n}\n\nexport const IFRAME_STEP_RE = /^i?frame(?:\\[\\d+])?$/i;\n\n/**\n * Given a cross-frame XPath, walk iframe steps to resolve:\n * - the target frameId (last iframe hop)\n * - the tail XPath (within the target frame)\n * - the absolute XPath prefix up to the iframe element hosting that frame\n */\nexport async function resolveFocusFrameAndTail(\n  page: Page,\n  absoluteXPath: string,\n  parentByFrame: FrameParentIndex,\n  rootId: string,\n): Promise<ResolvedFocusFrame> {\n  const steps = parseXPathToSteps(absoluteXPath);\n  let ctxFrameId = rootId;\n  let buf: Step[] = [];\n  let absPrefix = \"\";\n\n  const flushIntoChild = async (): Promise<void> => {\n    if (!buf.length) return;\n    const selectorForIframe = buildXPathFromSteps(buf);\n    const parentSess = page.getSessionForFrame(ctxFrameId);\n    const objectId = await resolveObjectIdForXPath(\n      parentSess,\n      selectorForIframe,\n      ctxFrameId,\n    );\n    if (!objectId)\n      throw new StagehandIframeError(\n        selectorForIframe,\n        \"Failed to resolve iframe element by XPath\",\n      );\n\n    try {\n      await parentSess.send(\"DOM.enable\").catch(() => {});\n      const desc = await parentSess.send<Protocol.DOM.DescribeNodeResponse>(\n        \"DOM.describeNode\",\n        { objectId },\n      );\n      const iframeBackendNodeId = desc.node.backendNodeId;\n\n      let childFrameId: string | undefined;\n      for (const fid of listChildrenOf(parentByFrame, ctxFrameId)) {\n        try {\n          const { backendNodeId } = await parentSess.send<{\n            backendNodeId: number;\n          }>(\"DOM.getFrameOwner\", { frameId: fid });\n          if (backendNodeId === iframeBackendNodeId) {\n            childFrameId = fid;\n            break;\n          }\n        } catch {\n          continue;\n        }\n      }\n      if (!childFrameId)\n        throw new StagehandIframeError(\n          selectorForIframe,\n          \"Could not map iframe to child frameId\",\n        );\n\n      absPrefix = prefixXPath(absPrefix || \"/\", selectorForIframe);\n      ctxFrameId = childFrameId;\n    } finally {\n      await parentSess\n        .send(\"Runtime.releaseObject\", { objectId })\n        .catch(() => {});\n    }\n\n    buf = [];\n  };\n\n  for (const st of steps) {\n    buf.push(st);\n    if (IFRAME_STEP_RE.test(st.name)) {\n      await flushIntoChild();\n    }\n  }\n\n  const tailXPath = buildXPathFromSteps(buf);\n  return { targetFrameId: ctxFrameId, tailXPath, absPrefix };\n}\n\n/** Resolve focus frame and tail CSS selector using '>>' to hop iframes. */\nexport async function resolveCssFocusFrameAndTail(\n  page: Page,\n  rawSelector: string,\n  parentByFrame: FrameParentIndex,\n  rootId: string,\n): Promise<ResolvedCssFocus> {\n  const parts = rawSelector\n    .split(\">>\")\n    .map((s) => s.trim())\n    .filter(Boolean);\n  let ctxFrameId = rootId;\n  const absPrefix = \"\";\n\n  for (let i = 0; i < Math.max(0, parts.length - 1); i++) {\n    const parentSess = page.getSessionForFrame(ctxFrameId);\n    const objectId = await resolveObjectIdForCss(\n      parentSess,\n      parts[i]!,\n      ctxFrameId,\n    );\n    if (!objectId)\n      throw new StagehandIframeError(\n        parts[i]!,\n        \"Failed to resolve iframe via CSS hop\",\n      );\n    try {\n      await parentSess.send(\"DOM.enable\").catch(() => {});\n      const desc = await parentSess.send<Protocol.DOM.DescribeNodeResponse>(\n        \"DOM.describeNode\",\n        { objectId },\n      );\n      const iframeBackendNodeId = desc.node.backendNodeId;\n      let childFrameId: string | undefined;\n      for (const fid of listChildrenOf(parentByFrame, ctxFrameId)) {\n        try {\n          const { backendNodeId } = await parentSess.send<{\n            backendNodeId: number;\n          }>(\"DOM.getFrameOwner\", { frameId: fid });\n          if (backendNodeId === iframeBackendNodeId) {\n            childFrameId = fid;\n            break;\n          }\n        } catch {\n          continue;\n        }\n      }\n      if (!childFrameId)\n        throw new StagehandIframeError(\n          parts[i]!,\n          \"Could not map CSS iframe hop to child frameId\",\n        );\n      ctxFrameId = childFrameId;\n    } finally {\n      await parentSess\n        .send(\"Runtime.releaseObject\", { objectId })\n        .catch(() => {});\n    }\n  }\n\n  const tailSelector = parts[parts.length - 1] ?? \"*\";\n  return { targetFrameId: ctxFrameId, tailSelector, absPrefix };\n}\n\n/** Resolve an XPath to a Runtime remoteObjectId in the given CDP session. */\nexport async function resolveObjectIdForXPath(\n  session: CDPSessionLike,\n  xpath: string,\n  frameId?: string,\n): Promise<string | null> {\n  let contextId: number | undefined;\n  try {\n    if (frameId) {\n      contextId = await executionContexts\n        .waitForMainWorld(session, frameId, 800)\n        .catch(\n          () => executionContexts.getMainWorld(session, frameId) ?? undefined,\n        );\n    }\n  } catch {\n    contextId = undefined;\n  }\n  const expr = buildLocatorInvocation(\"resolveXPathMainWorld\", [\n    JSON.stringify(xpath),\n    \"0\",\n  ]);\n  const { result, exceptionDetails } = await session.send<{\n    result: { objectId?: string | undefined };\n    exceptionDetails?: Protocol.Runtime.ExceptionDetails;\n  }>(\"Runtime.evaluate\", {\n    expression: expr,\n    returnByValue: false,\n    contextId,\n    awaitPromise: true,\n  });\n  if (exceptionDetails) return null;\n  return result?.objectId ?? null;\n}\n\n/** Resolve a CSS selector (supports '>>' within the same frame only) to a Runtime objectId. */\nexport async function resolveObjectIdForCss(\n  session: CDPSessionLike,\n  selector: string,\n  frameId?: string,\n): Promise<string | null> {\n  let contextId: number | undefined;\n  try {\n    if (frameId) {\n      contextId = await executionContexts\n        .waitForMainWorld(session, frameId, 800)\n        .catch(\n          () => executionContexts.getMainWorld(session, frameId) ?? undefined,\n        );\n    }\n  } catch {\n    contextId = undefined;\n  }\n  const primaryExpr = buildLocatorInvocation(\"resolveCssSelector\", [\n    JSON.stringify(selector),\n    \"0\",\n  ]);\n  const fallbackExpr = buildLocatorInvocation(\"resolveCssSelectorPierce\", [\n    JSON.stringify(selector),\n    \"0\",\n  ]);\n\n  const evaluate = async (expression: string): Promise<string | null> => {\n    const { result, exceptionDetails } = await session.send<{\n      result: { objectId?: string | undefined };\n      exceptionDetails?: Protocol.Runtime.ExceptionDetails;\n    }>(\"Runtime.evaluate\", {\n      expression,\n      returnByValue: false,\n      contextId,\n      awaitPromise: true,\n    });\n    if (exceptionDetails) return null;\n    return result?.objectId ?? null;\n  };\n\n  const primary = await evaluate(primaryExpr);\n  if (primary) return primary;\n  return evaluate(fallbackExpr);\n}\n\nexport function listChildrenOf(\n  parentByFrame: FrameParentIndex,\n  parentId: string,\n): string[] {\n  const out: string[] = [];\n  for (const [fid, p] of parentByFrame.entries()) {\n    if (p === parentId) out.push(fid);\n  }\n  return out;\n}\n"]}

package/dist/esm/lib/v3/understudy/cdp.d.ts

@@ -23,6 +23,7 @@ export declare class CdpConnection implements CDPSessionLike {
     private sessions;
     /** Maps sessionId -> targetId (1:1 mapping) */
     private sessionToTarget;
+    private sessionDispatchWaiters;
     readonly id: string | null;
     private transportCloseHandlers;
     /** Optional CDP logger - set this to receive all outgoing CDP method calls */
@@ -41,13 +42,17 @@ export declare class CdpConnection implements CDPSessionLike {
     offTransportClosed(handler: (why: string) => void): void;
     private emitTransportClosed;
     private constructor();
-    static connect(wsUrl: string): Promise<CdpConnection>;
+    static connect(wsUrl: string, options?: {
+        headers?: Record<string, string>;
+    }): Promise<CdpConnection>;
     enableAutoAttach(): Promise<void>;
     send<R = unknown>(method: string, params?: object): Promise<R>;
     on<P = unknown>(event: string, handler: (params: P) => void): void;
     off<P = unknown>(event: string, handler: (params: P) => void): void;
     close(): Promise<void>;
+    private rejectAllInflight;
     getSession(sessionId: string): CdpSession | undefined;
+    waitForSessionDispatch(sessionId: string, method: string, match?: (params?: object) => boolean): Promise<void>;
     attachToTarget(targetId: string): Promise<CdpSession>;
     getTargets(): Promise<Protocol.Target.TargetInfo[]>;
     private onMessage;