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

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

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { LLMClient } from "../../llm/LLMClient.js";
+import { ModelConfiguration } from "./model.js";
+import { LogLine } from "./logs.js";
+import { type BrowserbaseSessionCreateParams, LocalBrowserLaunchOptionsSchema } from "./api.js";
+export type V3Env = "LOCAL" | "BROWSERBASE";
+export declare const localBrowserLaunchOptionsSchema: z.ZodObject<{
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    executablePath: z.ZodOptional<z.ZodString>;
+    port: z.ZodOptional<z.ZodNumber>;
+    userDataDir: z.ZodOptional<z.ZodString>;
+    preserveUserDataDir: z.ZodOptional<z.ZodBoolean>;
+    headless: z.ZodOptional<z.ZodBoolean>;
+    devtools: z.ZodOptional<z.ZodBoolean>;
+    chromiumSandbox: z.ZodOptional<z.ZodBoolean>;
+    ignoreDefaultArgs: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+    proxy: z.ZodOptional<z.ZodObject<{
+        server: z.ZodString;
+        bypass: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    locale: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    deviceScaleFactor: z.ZodOptional<z.ZodNumber>;
+    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>;
+}, z.core.$strict>;
+export type LocalBrowserLaunchOptions = z.infer<typeof LocalBrowserLaunchOptionsSchema>;
+/** Constructor options for V3 */
+export interface V3Options {
+    env: V3Env;
+    apiKey?: string;
+    projectId?: string;
+    /**
+     * Optional: fine-tune Browserbase session creation or resume an existing session.
+     */
+    browserbaseSessionCreateParams?: BrowserbaseSessionCreateParams;
+    browserbaseSessionID?: string;
+    /**
+     * Controls browser keepalive behavior. When set, it overrides any value in
+     * browserbaseSessionCreateParams.keepAlive.
+     */
+    keepAlive?: boolean;
+    localBrowserLaunchOptions?: LocalBrowserLaunchOptions;
+    model?: ModelConfiguration;
+    llmClient?: LLMClient;
+    systemPrompt?: string;
+    logInferenceToFile?: boolean;
+    experimental?: boolean;
+    verbose?: 0 | 1 | 2;
+    selfHeal?: boolean;
+    waitForCaptchaSolves?: boolean;
+    actTimeoutMs?: number;
+    /** Disable pino logging backend (useful for tests or minimal environments). */
+    disablePino?: boolean;
+    /** Optional external logger hook for integrating with host apps. */
+    logger?: (line: LogLine) => void;
+    /** Directory used to persist cached actions for act(). */
+    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

@@ -0,0 +1,4 @@
+import { LocalBrowserLaunchOptionsSchema, } from "./api.js";
+// Re-export for backwards compatibility (camelCase alias)
+export const localBrowserLaunchOptionsSchema = LocalBrowserLaunchOptionsSchema;
+//# sourceMappingURL=options.js.map

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

@@ -0,0 +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   * 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/page.d.ts

@@ -0,0 +1,18 @@
+import { Page } from "../../understudy/page.js";
+import { Page as PlaywrightPage } from "playwright-core";
+import { Page as PatchrightPage } from "patchright-core";
+import { Page as PuppeteerPage } from "puppeteer-core";
+export type { PlaywrightPage, PatchrightPage, PuppeteerPage, Page };
+export type AnyPage = PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
+export { ConsoleMessage } from "../../understudy/consoleMessage.js";
+export type { ConsoleListener } from "../../understudy/consoleMessage.js";
+export type LoadState = "load" | "domcontentloaded" | "networkidle";
+export { Response } from "../../understudy/response.js";
+export type SnapshotResult = {
+    formattedTree: string;
+    xpathMap: Record<string, string>;
+    urlMap: Record<string, string>;
+};
+export type PageSnapshotOptions = {
+    includeIframes?: boolean;
+};

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

@@ -0,0 +1,3 @@
+export { ConsoleMessage } from "../../understudy/consoleMessage.js";
+export { Response } from "../../understudy/response.js";
+//# sourceMappingURL=page.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"page.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/page.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAIpE,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC","sourcesContent":["import { Page } from \"../../understudy/page.js\";\nimport { Page as PlaywrightPage } from \"playwright-core\";\nimport { Page as PatchrightPage } from \"patchright-core\";\nimport { Page as PuppeteerPage } from \"puppeteer-core\";\n\nexport type { PlaywrightPage, PatchrightPage, PuppeteerPage, Page };\nexport type AnyPage = PlaywrightPage | PuppeteerPage | PatchrightPage | Page;\n\nexport { ConsoleMessage } from \"../../understudy/consoleMessage.js\";\nexport type { ConsoleListener } from \"../../understudy/consoleMessage.js\";\n\nexport type LoadState = \"load\" | \"domcontentloaded\" | \"networkidle\";\nexport { Response } from \"../../understudy/response.js\";\n\nexport type SnapshotResult = {\n  formattedTree: string;\n  xpathMap: Record<string, string>;\n  urlMap: Record<string, string>;\n};\n\nexport type PageSnapshotOptions = {\n  includeIframes?: boolean;\n};\n"]}

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

@@ -0,0 +1,25 @@
+import type { Locator } from "../../understudy/locator.js";
+export type ScreenshotAnimationsOption = "disabled" | "allow";
+export type ScreenshotCaretOption = "hide" | "initial";
+export type ScreenshotScaleOption = "css" | "device";
+export interface ScreenshotClip {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ScreenshotOptions {
+    animations?: ScreenshotAnimationsOption;
+    caret?: ScreenshotCaretOption;
+    clip?: ScreenshotClip;
+    fullPage?: boolean;
+    mask?: Locator[];
+    maskColor?: string;
+    omitBackground?: boolean;
+    path?: string;
+    quality?: number;
+    scale?: ScreenshotScaleOption;
+    style?: string;
+    timeout?: number;
+    type?: "png" | "jpeg";
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"screenshotTypes.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/screenshotTypes.ts"],"names":[],"mappings":"","sourcesContent":["import type { Locator } from \"../../understudy/locator.js\";\n\nexport type ScreenshotAnimationsOption = \"disabled\" | \"allow\";\nexport type ScreenshotCaretOption = \"hide\" | \"initial\";\nexport type ScreenshotScaleOption = \"css\" | \"device\";\n\nexport interface ScreenshotClip {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\nexport interface ScreenshotOptions {\n  animations?: ScreenshotAnimationsOption;\n  caret?: ScreenshotCaretOption;\n  clip?: ScreenshotClip;\n  fullPage?: boolean;\n  mask?: Locator[];\n  maskColor?: string;\n  omitBackground?: boolean;\n  path?: string;\n  quality?: number;\n  scale?: ScreenshotScaleOption;\n  style?: string;\n  timeout?: number;\n  type?: \"png\" | \"jpeg\";\n}\n"]}

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

@@ -0,0 +1,168 @@
+import { ZodError } from "zod";
+export declare class StagehandError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare class StagehandDefaultError extends StagehandError {
+    constructor(error?: unknown);
+}
+export declare class StagehandEnvironmentError extends StagehandError {
+    constructor(currentEnvironment: string, requiredEnvironment: string, feature: string);
+}
+export declare class MissingEnvironmentVariableError extends StagehandError {
+    constructor(missingEnvironmentVariable: string, feature: string);
+}
+export declare class UnsupportedModelError extends StagehandError {
+    constructor(supportedModels: string[], feature?: string);
+}
+export declare class UnsupportedModelProviderError extends StagehandError {
+    constructor(supportedProviders: string[], feature?: string);
+}
+export declare class UnsupportedAISDKModelProviderError extends StagehandError {
+    constructor(provider: string, supportedProviders: string[]);
+}
+export declare class InvalidAISDKModelFormatError extends StagehandError {
+    constructor(modelName: string);
+}
+export declare class StagehandNotInitializedError extends StagehandError {
+    constructor(prop: string);
+}
+export declare class BrowserbaseSessionNotFoundError extends StagehandError {
+    constructor();
+}
+export declare class CaptchaTimeoutError extends StagehandError {
+    constructor();
+}
+export declare class MissingLLMConfigurationError extends StagehandError {
+    constructor();
+}
+export declare class HandlerNotInitializedError extends StagehandError {
+    constructor(handlerType: string);
+}
+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[]);
+}
+export declare class AgentScreenshotProviderError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandMissingArgumentError extends StagehandError {
+    constructor(message: string);
+}
+export declare class CreateChatCompletionResponseError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandEvalError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandDomProcessError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StagehandLocatorError extends StagehandError {
+    constructor(action: string, selector: string, message: string);
+}
+export declare class StagehandClickError extends StagehandError {
+    constructor(message: string, selector: string);
+}
+export declare class LLMResponseError extends StagehandError {
+    constructor(primitive: string, message: string);
+}
+export declare class StagehandIframeError extends StagehandError {
+    constructor(frameUrl: string, message: string);
+}
+export declare class ContentFrameNotFoundError extends StagehandError {
+    constructor(selector: string);
+}
+export declare class XPathResolutionError extends StagehandError {
+    constructor(xpath: string);
+}
+export declare class ExperimentalApiConflictError extends StagehandError {
+    constructor();
+}
+export declare class ExperimentalNotConfiguredError extends StagehandError {
+    constructor(featureName: string);
+}
+export declare class CuaModelRequiredError extends StagehandError {
+    constructor(availableModels: readonly string[]);
+}
+export declare class ZodSchemaValidationError extends Error {
+    readonly received: unknown;
+    readonly issues: ReturnType<ZodError["format"]>;
+    constructor(received: unknown, issues: ReturnType<ZodError["format"]>);
+}
+export declare class StagehandInitError extends StagehandError {
+    constructor(message: string);
+}
+export declare class MCPConnectionError extends StagehandError {
+    readonly serverUrl: string;
+    readonly originalError: unknown;
+    constructor(serverUrl: string, originalError: unknown);
+}
+export declare class StagehandShadowRootMissingError extends StagehandError {
+    constructor(detail?: string);
+}
+export declare class StagehandShadowSegmentEmptyError extends StagehandError {
+    constructor();
+}
+export declare class StagehandShadowSegmentNotFoundError extends StagehandError {
+    constructor(segment: string, hint?: string);
+}
+export declare class ElementNotVisibleError extends StagehandError {
+    constructor(selector: string);
+}
+export declare class ResponseBodyError extends StagehandError {
+    constructor(message: string);
+}
+export declare class ResponseParseError extends StagehandError {
+    constructor(message: string);
+}
+export declare class TimeoutError extends StagehandError {
+    constructor(operation: string, timeoutMs: number);
+}
+export declare class ActTimeoutError extends TimeoutError {
+    constructor(timeoutMs: number);
+}
+export declare class ExtractTimeoutError extends TimeoutError {
+    constructor(timeoutMs: number);
+}
+export declare class ObserveTimeoutError extends TimeoutError {
+    constructor(timeoutMs: number);
+}
+export declare class PageNotFoundError extends StagehandError {
+    constructor(identifier: string);
+}
+export declare class ConnectionTimeoutError extends StagehandError {
+    constructor(message: string);
+}
+export declare class StreamingCallbacksInNonStreamingModeError extends StagehandError {
+    readonly invalidCallbacks: string[];
+    constructor(invalidCallbacks: string[]);
+}
+export declare class AgentAbortError extends StagehandError {
+    readonly reason: string;
+    constructor(reason?: string);
+}
+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);
+}
+export declare class UnderstudyCommandException extends StagehandError {
+    constructor(message: string, cause?: unknown);
+}

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

@@ -0,0 +1,333 @@
+// Avoid .js extension so bundlers resolve TS source
+import { STAGEHAND_VERSION } from "../../../version.js";
+export class StagehandError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = this.constructor.name;
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+export class StagehandDefaultError extends StagehandError {
+    constructor(error) {
+        if (error instanceof Error || error instanceof StagehandError) {
+            super(`\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}`);
+        }
+    }
+}
+export class StagehandEnvironmentError extends StagehandError {
+    constructor(currentEnvironment, requiredEnvironment, feature) {
+        super(`You seem to be setting the current environment to ${currentEnvironment}.` +
+            `Ensure the environment is set to ${requiredEnvironment} if you want to use ${feature}.`);
+    }
+}
+export class MissingEnvironmentVariableError extends StagehandError {
+    constructor(missingEnvironmentVariable, feature) {
+        super(`${missingEnvironmentVariable} is required to use ${feature}.` +
+            `Please set ${missingEnvironmentVariable} in your environment.`);
+    }
+}
+export class UnsupportedModelError extends StagehandError {
+    constructor(supportedModels, feature) {
+        const message = feature
+            ? `${feature} requires a valid model.`
+            : `Unsupported model.`;
+        const guidance = `\n\nPlease use the provider/model format (e.g., "openai/gpt-4o", "anthropic/claude-sonnet-4-5", "google/gemini-3-flash-preview").` +
+            `\n\nFor a complete list of supported models and providers, see: https://docs.stagehand.dev/v3/configuration/models#configuration-setup`;
+        super(`${message}${guidance}`);
+    }
+}
+export class UnsupportedModelProviderError extends StagehandError {
+    constructor(supportedProviders, feature) {
+        super(feature
+            ? `${feature} requires one of the following model providers: ${supportedProviders}`
+            : `please use one of the supported model providers: ${supportedProviders}`);
+    }
+}
+export class UnsupportedAISDKModelProviderError extends StagehandError {
+    constructor(provider, supportedProviders) {
+        super(`${provider} is not currently supported for aiSDK. please use one of the supported model providers: ${supportedProviders}`);
+    }
+}
+export class InvalidAISDKModelFormatError extends StagehandError {
+    constructor(modelName) {
+        super(`${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'\``);
+    }
+}
+export class StagehandNotInitializedError extends StagehandError {
+    constructor(prop) {
+        super(`You seem to be calling \`${prop}\` on a page in an uninitialized \`Stagehand\` object. ` +
+            `Ensure you are running \`await stagehand.init()\` on the Stagehand object before ` +
+            `referencing the \`page\` object.`);
+    }
+}
+export class BrowserbaseSessionNotFoundError extends StagehandError {
+    constructor() {
+        super("No Browserbase session ID found");
+    }
+}
+export class CaptchaTimeoutError extends StagehandError {
+    constructor() {
+        super("Captcha timeout");
+    }
+}
+export class MissingLLMConfigurationError extends StagehandError {
+    constructor() {
+        super("No LLM API key or LLM Client configured. An LLM API key or a custom LLM Client " +
+            "is required to use act, extract, or observe.");
+    }
+}
+export class HandlerNotInitializedError extends StagehandError {
+    constructor(handlerType) {
+        super(`${handlerType} handler not initialized`);
+    }
+}
+export class StagehandInvalidArgumentError extends StagehandError {
+    constructor(message) {
+        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}`);
+    }
+}
+export class AgentScreenshotProviderError extends StagehandError {
+    constructor(message) {
+        super(`ScreenshotProviderError: ${message}`);
+    }
+}
+export class StagehandMissingArgumentError extends StagehandError {
+    constructor(message) {
+        super(`MissingArgumentError: ${message}`);
+    }
+}
+export class CreateChatCompletionResponseError extends StagehandError {
+    constructor(message) {
+        super(`CreateChatCompletionResponseError: ${message}`);
+    }
+}
+export class StagehandEvalError extends StagehandError {
+    constructor(message) {
+        super(`StagehandEvalError: ${message}`);
+    }
+}
+export class StagehandDomProcessError extends StagehandError {
+    constructor(message) {
+        super(`Error Processing Dom: ${message}`);
+    }
+}
+export class StagehandLocatorError extends StagehandError {
+    constructor(action, selector, message) {
+        super(`Error ${action} Element with selector: ${selector} Reason: ${message}`);
+    }
+}
+export class StagehandClickError extends StagehandError {
+    constructor(message, selector) {
+        super(`Error Clicking Element with selector: ${selector} Reason: ${message}`);
+    }
+}
+export class LLMResponseError extends StagehandError {
+    constructor(primitive, message) {
+        super(`${primitive} LLM response error: ${message}`);
+    }
+}
+export class StagehandIframeError extends StagehandError {
+    constructor(frameUrl, message) {
+        super(`Unable to resolve frameId for iframe with URL: ${frameUrl} Full error: ${message}`);
+    }
+}
+export class ContentFrameNotFoundError extends StagehandError {
+    constructor(selector) {
+        super(`Unable to obtain a content frame for selector: ${selector}`);
+    }
+}
+export class XPathResolutionError extends StagehandError {
+    constructor(xpath) {
+        super(`XPath "${xpath}" does not resolve in the current page or frames`);
+    }
+}
+export class ExperimentalApiConflictError extends StagehandError {
+    constructor() {
+        super("`experimental` mode cannot be used together with the Stagehand API. " +
+            "To use experimental features, set experimental: true and disableAPI: true in the stagehand constructor. " +
+            "To use the Stagehand API, set experimental: false and disableAPI: false (or omit it) in the stagehand constructor.");
+    }
+}
+export class ExperimentalNotConfiguredError extends StagehandError {
+    constructor(featureName) {
+        super(`Feature "${featureName}" is an experimental feature, and cannot be configured when disableAPI: false.
+    Please set experimental: true and disableAPI: true in the stagehand constructor to use this feature.
+    If you wish to use the Stagehand API, please ensure ${featureName} is not defined in your function call,
+    and set experimental: false, disableAPI: false (or omit it) in the Stagehand constructor.`);
+    }
+}
+export class CuaModelRequiredError extends StagehandError {
+    constructor(availableModels) {
+        super(`To use the computer use agent (CUA), please provide a CUA model in the agent constructor or stagehand config. ` +
+            `Try one of our supported CUA models: ${availableModels.join(", ")}`);
+    }
+}
+export class ZodSchemaValidationError extends Error {
+    received;
+    issues;
+    constructor(received, issues) {
+        super(`Zod schema validation failed
+
+— Received —
+${JSON.stringify(received, null, 2)}
+
+— Issues —
+${JSON.stringify(issues, null, 2)}`);
+        this.received = received;
+        this.issues = issues;
+        this.name = "ZodSchemaValidationError";
+    }
+}
+export class StagehandInitError extends StagehandError {
+    constructor(message) {
+        super(message);
+    }
+}
+export class MCPConnectionError extends StagehandError {
+    serverUrl;
+    originalError;
+    constructor(serverUrl, originalError) {
+        const errorMessage = originalError instanceof Error
+            ? originalError.message
+            : String(originalError);
+        super(`Failed to connect to MCP server at "${serverUrl}". ${errorMessage}. ` +
+            `Please verify the server URL is correct and the server is running.`);
+        this.serverUrl = serverUrl;
+        this.originalError = originalError;
+    }
+}
+export class StagehandShadowRootMissingError extends StagehandError {
+    constructor(detail) {
+        super(`No shadow root present on the resolved host` +
+            (detail ? `: ${detail}` : ""));
+    }
+}
+export class StagehandShadowSegmentEmptyError extends StagehandError {
+    constructor() {
+        super(`Empty selector segment after shadow-DOM hop ("//")`);
+    }
+}
+export class StagehandShadowSegmentNotFoundError extends StagehandError {
+    constructor(segment, hint) {
+        super(`Shadow segment '${segment}' matched no element inside shadow root` +
+            (hint ? ` ${hint}` : ""));
+    }
+}
+export class ElementNotVisibleError extends StagehandError {
+    constructor(selector) {
+        super(`Element not visible (no box model): ${selector}`);
+    }
+}
+export class ResponseBodyError extends StagehandError {
+    constructor(message) {
+        super(`Failed to retrieve response body: ${message}`);
+    }
+}
+export class ResponseParseError extends StagehandError {
+    constructor(message) {
+        super(`Failed to parse response: ${message}`);
+    }
+}
+export class TimeoutError extends StagehandError {
+    constructor(operation, timeoutMs) {
+        super(`${operation} timed out after ${timeoutMs}ms`);
+    }
+}
+export class ActTimeoutError extends TimeoutError {
+    constructor(timeoutMs) {
+        super("act()", timeoutMs);
+        this.name = "ActTimeoutError";
+    }
+}
+export class ExtractTimeoutError extends TimeoutError {
+    constructor(timeoutMs) {
+        super("extract()", timeoutMs);
+        this.name = "ExtractTimeoutError";
+    }
+}
+export class ObserveTimeoutError extends TimeoutError {
+    constructor(timeoutMs) {
+        super("observe()", timeoutMs);
+        this.name = "ObserveTimeoutError";
+    }
+}
+export class PageNotFoundError extends StagehandError {
+    constructor(identifier) {
+        super(`No Page found for ${identifier}`);
+    }
+}
+export class ConnectionTimeoutError extends StagehandError {
+    constructor(message) {
+        super(`Connection timeout: ${message}`);
+    }
+}
+export class StreamingCallbacksInNonStreamingModeError extends StagehandError {
+    invalidCallbacks;
+    constructor(invalidCallbacks) {
+        super(`Streaming-only callback(s) "${invalidCallbacks.join('", "')}" cannot be used in non-streaming mode. ` +
+            `Set 'stream: true' in AgentConfig to use these callbacks.`);
+        this.invalidCallbacks = invalidCallbacks;
+    }
+}
+export class AgentAbortError extends StagehandError {
+    reason;
+    constructor(reason) {
+        const message = reason
+            ? `Agent execution was aborted: ${reason}`
+            : "Agent execution was aborted";
+        super(message);
+        this.reason = reason || "aborted";
+    }
+}
+export class StagehandClosedError extends StagehandError {
+    constructor() {
+        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
+            ? `: ${cause.message}`
+            : cause
+                ? `: ${String(cause)}`
+                : "";
+        super(`error taking snapshot${suffix}`, cause);
+    }
+}
+export class UnderstudyCommandException extends StagehandError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = "UnderstudyCommandException";
+    }
+}
+//# sourceMappingURL=sdkErrors.js.map