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

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

@@ -0,0 +1,390 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CdpConnectionClosedError = exports.StagehandClosedError = exports.AgentAbortError = exports.StreamingCallbacksInNonStreamingModeError = exports.ConnectionTimeoutError = exports.PageNotFoundError = exports.ObserveTimeoutError = exports.ExtractTimeoutError = exports.ActTimeoutError = exports.TimeoutError = exports.ResponseParseError = exports.ResponseBodyError = exports.ElementNotVisibleError = exports.StagehandShadowSegmentNotFoundError = exports.StagehandShadowSegmentEmptyError = exports.StagehandShadowRootMissingError = exports.MCPConnectionError = exports.StagehandInitError = exports.ZodSchemaValidationError = exports.CuaModelRequiredError = exports.ExperimentalNotConfiguredError = exports.ExperimentalApiConflictError = exports.XPathResolutionError = exports.ContentFrameNotFoundError = exports.StagehandIframeError = exports.LLMResponseError = exports.StagehandClickError = exports.StagehandLocatorError = exports.StagehandDomProcessError = exports.StagehandEvalError = exports.CreateChatCompletionResponseError = exports.StagehandMissingArgumentError = exports.AgentScreenshotProviderError = exports.StagehandElementNotFoundError = exports.CookieSetError = exports.CookieValidationError = exports.StagehandInvalidArgumentError = exports.HandlerNotInitializedError = exports.MissingLLMConfigurationError = exports.CaptchaTimeoutError = exports.BrowserbaseSessionNotFoundError = exports.StagehandNotInitializedError = exports.InvalidAISDKModelFormatError = exports.UnsupportedAISDKModelProviderError = exports.UnsupportedModelProviderError = exports.UnsupportedModelError = exports.MissingEnvironmentVariableError = exports.StagehandEnvironmentError = exports.StagehandDefaultError = exports.StagehandError = void 0;
+exports.UnderstudyCommandException = exports.StagehandSnapshotError = exports.StagehandSetExtraHTTPHeadersError = void 0;
+// Avoid .js extension so bundlers resolve TS source
+const version_js_1 = require("../../../version.js");
+class StagehandError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = this.constructor.name;
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+exports.StagehandError = StagehandError;
+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: ${version_js_1.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}`);
+        }
+    }
+}
+exports.StagehandDefaultError = StagehandDefaultError;
+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}.`);
+    }
+}
+exports.StagehandEnvironmentError = StagehandEnvironmentError;
+class MissingEnvironmentVariableError extends StagehandError {
+    constructor(missingEnvironmentVariable, feature) {
+        super(`${missingEnvironmentVariable} is required to use ${feature}.` +
+            `Please set ${missingEnvironmentVariable} in your environment.`);
+    }
+}
+exports.MissingEnvironmentVariableError = MissingEnvironmentVariableError;
+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}`);
+    }
+}
+exports.UnsupportedModelError = UnsupportedModelError;
+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}`);
+    }
+}
+exports.UnsupportedModelProviderError = UnsupportedModelProviderError;
+class UnsupportedAISDKModelProviderError extends StagehandError {
+    constructor(provider, supportedProviders) {
+        super(`${provider} is not currently supported for aiSDK. please use one of the supported model providers: ${supportedProviders}`);
+    }
+}
+exports.UnsupportedAISDKModelProviderError = UnsupportedAISDKModelProviderError;
+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'\``);
+    }
+}
+exports.InvalidAISDKModelFormatError = InvalidAISDKModelFormatError;
+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.`);
+    }
+}
+exports.StagehandNotInitializedError = StagehandNotInitializedError;
+class BrowserbaseSessionNotFoundError extends StagehandError {
+    constructor() {
+        super("No Browserbase session ID found");
+    }
+}
+exports.BrowserbaseSessionNotFoundError = BrowserbaseSessionNotFoundError;
+class CaptchaTimeoutError extends StagehandError {
+    constructor() {
+        super("Captcha timeout");
+    }
+}
+exports.CaptchaTimeoutError = CaptchaTimeoutError;
+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.");
+    }
+}
+exports.MissingLLMConfigurationError = MissingLLMConfigurationError;
+class HandlerNotInitializedError extends StagehandError {
+    constructor(handlerType) {
+        super(`${handlerType} handler not initialized`);
+    }
+}
+exports.HandlerNotInitializedError = HandlerNotInitializedError;
+class StagehandInvalidArgumentError extends StagehandError {
+    constructor(message) {
+        super(`InvalidArgumentError: ${message}`);
+    }
+}
+exports.StagehandInvalidArgumentError = StagehandInvalidArgumentError;
+class CookieValidationError extends StagehandError {
+    constructor(message) {
+        super(message);
+    }
+}
+exports.CookieValidationError = CookieValidationError;
+class CookieSetError extends StagehandError {
+    constructor(message) {
+        super(message);
+    }
+}
+exports.CookieSetError = CookieSetError;
+class StagehandElementNotFoundError extends StagehandError {
+    constructor(xpaths) {
+        super(`Could not find an element for the given xPath(s): ${xpaths}`);
+    }
+}
+exports.StagehandElementNotFoundError = StagehandElementNotFoundError;
+class AgentScreenshotProviderError extends StagehandError {
+    constructor(message) {
+        super(`ScreenshotProviderError: ${message}`);
+    }
+}
+exports.AgentScreenshotProviderError = AgentScreenshotProviderError;
+class StagehandMissingArgumentError extends StagehandError {
+    constructor(message) {
+        super(`MissingArgumentError: ${message}`);
+    }
+}
+exports.StagehandMissingArgumentError = StagehandMissingArgumentError;
+class CreateChatCompletionResponseError extends StagehandError {
+    constructor(message) {
+        super(`CreateChatCompletionResponseError: ${message}`);
+    }
+}
+exports.CreateChatCompletionResponseError = CreateChatCompletionResponseError;
+class StagehandEvalError extends StagehandError {
+    constructor(message) {
+        super(`StagehandEvalError: ${message}`);
+    }
+}
+exports.StagehandEvalError = StagehandEvalError;
+class StagehandDomProcessError extends StagehandError {
+    constructor(message) {
+        super(`Error Processing Dom: ${message}`);
+    }
+}
+exports.StagehandDomProcessError = StagehandDomProcessError;
+class StagehandLocatorError extends StagehandError {
+    constructor(action, selector, message) {
+        super(`Error ${action} Element with selector: ${selector} Reason: ${message}`);
+    }
+}
+exports.StagehandLocatorError = StagehandLocatorError;
+class StagehandClickError extends StagehandError {
+    constructor(message, selector) {
+        super(`Error Clicking Element with selector: ${selector} Reason: ${message}`);
+    }
+}
+exports.StagehandClickError = StagehandClickError;
+class LLMResponseError extends StagehandError {
+    constructor(primitive, message) {
+        super(`${primitive} LLM response error: ${message}`);
+    }
+}
+exports.LLMResponseError = LLMResponseError;
+class StagehandIframeError extends StagehandError {
+    constructor(frameUrl, message) {
+        super(`Unable to resolve frameId for iframe with URL: ${frameUrl} Full error: ${message}`);
+    }
+}
+exports.StagehandIframeError = StagehandIframeError;
+class ContentFrameNotFoundError extends StagehandError {
+    constructor(selector) {
+        super(`Unable to obtain a content frame for selector: ${selector}`);
+    }
+}
+exports.ContentFrameNotFoundError = ContentFrameNotFoundError;
+class XPathResolutionError extends StagehandError {
+    constructor(xpath) {
+        super(`XPath "${xpath}" does not resolve in the current page or frames`);
+    }
+}
+exports.XPathResolutionError = XPathResolutionError;
+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.");
+    }
+}
+exports.ExperimentalApiConflictError = ExperimentalApiConflictError;
+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.`);
+    }
+}
+exports.ExperimentalNotConfiguredError = ExperimentalNotConfiguredError;
+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(", ")}`);
+    }
+}
+exports.CuaModelRequiredError = CuaModelRequiredError;
+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";
+    }
+}
+exports.ZodSchemaValidationError = ZodSchemaValidationError;
+class StagehandInitError extends StagehandError {
+    constructor(message) {
+        super(message);
+    }
+}
+exports.StagehandInitError = StagehandInitError;
+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;
+    }
+}
+exports.MCPConnectionError = MCPConnectionError;
+class StagehandShadowRootMissingError extends StagehandError {
+    constructor(detail) {
+        super(`No shadow root present on the resolved host` +
+            (detail ? `: ${detail}` : ""));
+    }
+}
+exports.StagehandShadowRootMissingError = StagehandShadowRootMissingError;
+class StagehandShadowSegmentEmptyError extends StagehandError {
+    constructor() {
+        super(`Empty selector segment after shadow-DOM hop ("//")`);
+    }
+}
+exports.StagehandShadowSegmentEmptyError = StagehandShadowSegmentEmptyError;
+class StagehandShadowSegmentNotFoundError extends StagehandError {
+    constructor(segment, hint) {
+        super(`Shadow segment '${segment}' matched no element inside shadow root` +
+            (hint ? ` ${hint}` : ""));
+    }
+}
+exports.StagehandShadowSegmentNotFoundError = StagehandShadowSegmentNotFoundError;
+class ElementNotVisibleError extends StagehandError {
+    constructor(selector) {
+        super(`Element not visible (no box model): ${selector}`);
+    }
+}
+exports.ElementNotVisibleError = ElementNotVisibleError;
+class ResponseBodyError extends StagehandError {
+    constructor(message) {
+        super(`Failed to retrieve response body: ${message}`);
+    }
+}
+exports.ResponseBodyError = ResponseBodyError;
+class ResponseParseError extends StagehandError {
+    constructor(message) {
+        super(`Failed to parse response: ${message}`);
+    }
+}
+exports.ResponseParseError = ResponseParseError;
+class TimeoutError extends StagehandError {
+    constructor(operation, timeoutMs) {
+        super(`${operation} timed out after ${timeoutMs}ms`);
+    }
+}
+exports.TimeoutError = TimeoutError;
+class ActTimeoutError extends TimeoutError {
+    constructor(timeoutMs) {
+        super("act()", timeoutMs);
+        this.name = "ActTimeoutError";
+    }
+}
+exports.ActTimeoutError = ActTimeoutError;
+class ExtractTimeoutError extends TimeoutError {
+    constructor(timeoutMs) {
+        super("extract()", timeoutMs);
+        this.name = "ExtractTimeoutError";
+    }
+}
+exports.ExtractTimeoutError = ExtractTimeoutError;
+class ObserveTimeoutError extends TimeoutError {
+    constructor(timeoutMs) {
+        super("observe()", timeoutMs);
+        this.name = "ObserveTimeoutError";
+    }
+}
+exports.ObserveTimeoutError = ObserveTimeoutError;
+class PageNotFoundError extends StagehandError {
+    constructor(identifier) {
+        super(`No Page found for ${identifier}`);
+    }
+}
+exports.PageNotFoundError = PageNotFoundError;
+class ConnectionTimeoutError extends StagehandError {
+    constructor(message) {
+        super(`Connection timeout: ${message}`);
+    }
+}
+exports.ConnectionTimeoutError = ConnectionTimeoutError;
+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;
+    }
+}
+exports.StreamingCallbacksInNonStreamingModeError = StreamingCallbacksInNonStreamingModeError;
+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";
+    }
+}
+exports.AgentAbortError = AgentAbortError;
+class StagehandClosedError extends StagehandError {
+    constructor() {
+        super("Stagehand session was closed");
+    }
+}
+exports.StagehandClosedError = StagehandClosedError;
+class CdpConnectionClosedError extends StagehandError {
+    constructor(reason) {
+        super(`CDP connection closed: ${reason}`);
+    }
+}
+exports.CdpConnectionClosedError = CdpConnectionClosedError;
+class StagehandSetExtraHTTPHeadersError extends StagehandError {
+    failures;
+    constructor(failures) {
+        super(`setExtraHTTPHeaders failed for ${failures.length} session(s): ${failures.join(", ")}`);
+        this.failures = failures;
+    }
+}
+exports.StagehandSetExtraHTTPHeadersError = StagehandSetExtraHTTPHeadersError;
+class StagehandSnapshotError extends StagehandError {
+    constructor(cause) {
+        const suffix = cause instanceof Error
+            ? `: ${cause.message}`
+            : cause
+                ? `: ${String(cause)}`
+                : "";
+        super(`error taking snapshot${suffix}`, cause);
+    }
+}
+exports.StagehandSnapshotError = StagehandSnapshotError;
+class UnderstudyCommandException extends StagehandError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = "UnderstudyCommandException";
+    }
+}
+exports.UnderstudyCommandException = UnderstudyCommandException;
+//# sourceMappingURL=sdkErrors.js.map

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

@@ -0,0 +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 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/cjs/lib/v3/understudy/a11y/snapshot/a11yTree.d.ts

@@ -0,0 +1,15 @@
+import type { Protocol } from "devtools-protocol";
+import type { CDPSessionLike } from "../../cdp.js";
+import type { A11yNode, A11yOptions, AccessibilityTreeResult } from "../../../types/private/snapshot.js";
+/**
+ * Fetch and prune the accessibility tree for a frame, optionally scoping the
+ * output to a selector root for faster targeted snapshots.
+ */
+export declare function a11yForFrame(session: CDPSessionLike, frameId: string | undefined, opts: A11yOptions): Promise<AccessibilityTreeResult>;
+export declare function decorateRoles(nodes: Protocol.Accessibility.AXNode[], opts: A11yOptions): A11yNode[];
+export declare function buildHierarchicalTree(nodes: A11yNode[], opts: A11yOptions): Promise<{
+    tree: A11yNode[];
+}>;
+export declare function isStructural(role: string): boolean;
+export declare function extractUrlFromAXNode(ax: Protocol.Accessibility.AXNode): string | undefined;
+export declare function removeRedundantStaticTextChildren(parent: A11yNode, children: A11yNode[]): A11yNode[];

package/dist/cjs/lib/v3/understudy/a11y/snapshot/a11yTree.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.a11yForFrame = a11yForFrame;
+exports.decorateRoles = decorateRoles;
+exports.buildHierarchicalTree = buildHierarchicalTree;
+exports.isStructural = isStructural;
+exports.extractUrlFromAXNode = extractUrlFromAXNode;
+exports.removeRedundantStaticTextChildren = removeRedundantStaticTextChildren;
+const focusSelectors_js_1 = require("./focusSelectors.js");
+const treeFormatUtils_js_1 = require("./treeFormatUtils.js");
+/**
+ * Fetch and prune the accessibility tree for a frame, optionally scoping the
+ * output to a selector root for faster targeted snapshots.
+ */
+async function a11yForFrame(session, frameId, opts) {
+    await session.send("Accessibility.enable").catch(() => { });
+    await session.send("Runtime.enable").catch(() => { });
+    await session.send("DOM.enable").catch(() => { });
+    let nodes = [];
+    try {
+        const params = frameId ? { frameId } : {};
+        ({ nodes } = await session.send("Accessibility.getFullAXTree", params));
+    }
+    catch (e) {
+        const msg = String(e?.message ?? e ?? "");
+        const isFrameScopeError = msg.includes("Frame with the given") ||
+            msg.includes("does not belong to the target") ||
+            msg.includes("is not found");
+        if (!isFrameScopeError || !frameId)
+            throw e;
+        ({ nodes } = await session.send("Accessibility.getFullAXTree"));
+    }
+    const urlMap = {};
+    for (const n of nodes) {
+        const be = n.backendDOMNodeId;
+        if (typeof be !== "number")
+            continue;
+        const url = extractUrlFromAXNode(n);
+        if (!url)
+            continue;
+        const enc = opts.encode(be);
+        urlMap[enc] = url;
+    }
+    let scopeApplied = false;
+    const nodesForOutline = await (async () => {
+        const sel = opts.focusSelector?.trim();
+        if (!sel)
+            return nodes;
+        try {
+            const looksLikeXPath = /^xpath=/i.test(sel) || sel.startsWith("/");
+            const objectId = looksLikeXPath
+                ? await (0, focusSelectors_js_1.resolveObjectIdForXPath)(session, sel, frameId)
+                : await (0, focusSelectors_js_1.resolveObjectIdForCss)(session, sel, frameId);
+            if (!objectId)
+                return nodes;
+            const desc = await session.send("DOM.describeNode", { objectId });
+            const be = desc.node?.backendNodeId;
+            if (typeof be !== "number")
+                return nodes;
+            const target = nodes.find((n) => n.backendDOMNodeId === be);
+            if (!target)
+                return nodes;
+            scopeApplied = true;
+            const keep = new Set([target.nodeId]);
+            const queue = [target];
+            while (queue.length) {
+                const cur = queue.shift();
+                for (const id of cur.childIds ?? []) {
+                    if (keep.has(id))
+                        continue;
+                    keep.add(id);
+                    const child = nodes.find((n) => n.nodeId === id);
+                    if (child)
+                        queue.push(child);
+                }
+            }
+            return nodes
+                .filter((n) => keep.has(n.nodeId))
+                .map((n) => n.nodeId === target.nodeId ? { ...n, parentId: undefined } : n);
+        }
+        catch {
+            return nodes;
+        }
+    })();
+    const decorated = decorateRoles(nodesForOutline, opts);
+    const { tree } = await buildHierarchicalTree(decorated, opts);
+    const simplified = tree.map((n) => (0, treeFormatUtils_js_1.formatTreeLine)(n)).join("\n");
+    return { outline: simplified.trimEnd(), urlMap, scopeApplied };
+}
+function decorateRoles(nodes, opts) {
+    const asRole = (n) => String(n.role?.value ?? "");
+    return nodes.map((n) => {
+        let encodedId;
+        if (typeof n.backendDOMNodeId === "number") {
+            try {
+                encodedId = opts.encode(n.backendDOMNodeId);
+            }
+            catch {
+                //
+            }
+        }
+        let role = asRole(n);
+        const domIsScrollable = encodedId
+            ? opts.scrollableMap[encodedId] === true
+            : false;
+        const tag = encodedId ? opts.tagNameMap[encodedId] : undefined;
+        const isHtmlElement = tag === "html";
+        if ((domIsScrollable || isHtmlElement) && tag !== "#document") {
+            const tagLabel = tag && tag.startsWith("#") ? tag.slice(1) : tag;
+            role = tagLabel
+                ? `scrollable, ${tagLabel}`
+                : `scrollable${role ? `, ${role}` : ""}`;
+        }
+        return {
+            role,
+            name: n.name?.value,
+            description: n.description?.value,
+            value: n.value?.value,
+            nodeId: n.nodeId,
+            backendDOMNodeId: n.backendDOMNodeId,
+            parentId: n.parentId,
+            childIds: n.childIds,
+            encodedId,
+        };
+    });
+}
+async function buildHierarchicalTree(nodes, opts) {
+    const nodeMap = new Map();
+    for (const n of nodes) {
+        const keep = !!(n.name && n.name.trim()) ||
+            !!(n.childIds && n.childIds.length) ||
+            !isStructural(n.role);
+        if (!keep)
+            continue;
+        nodeMap.set(n.nodeId, { ...n });
+    }
+    for (const n of nodes) {
+        if (!n.parentId)
+            continue;
+        const parent = nodeMap.get(n.parentId);
+        const cur = nodeMap.get(n.nodeId);
+        if (parent && cur)
+            (parent.children ??= []).push(cur);
+    }
+    const roots = nodes
+        .filter((n) => !n.parentId && nodeMap.has(n.nodeId))
+        .map((n) => nodeMap.get(n.nodeId));
+    const cleaned = (await Promise.all(roots.map(pruneStructuralSafe))).filter(Boolean);
+    return { tree: cleaned };
+    async function pruneStructuralSafe(node) {
+        if (+node.nodeId < 0)
+            return null;
+        const children = node.children ?? [];
+        if (!children.length) {
+            return isStructural(node.role) ? null : node;
+        }
+        const cleanedKids = (await Promise.all(children.map(pruneStructuralSafe))).filter(Boolean);
+        const prunedStatic = removeRedundantStaticTextChildren(node, cleanedKids);
+        if (isStructural(node.role)) {
+            if (prunedStatic.length === 1)
+                return prunedStatic[0];
+            if (prunedStatic.length === 0)
+                return null;
+        }
+        let newRole = node.role;
+        if ((newRole === "generic" || newRole === "none") && node.encodedId) {
+            const tagName = opts.tagNameMap[node.encodedId];
+            if (tagName)
+                newRole = tagName;
+        }
+        if (newRole === "combobox" && node.encodedId) {
+            const tagName = opts.tagNameMap[node.encodedId];
+            if (tagName === "select")
+                newRole = "select";
+        }
+        return { ...node, role: newRole, children: prunedStatic };
+    }
+}
+function isStructural(role) {
+    const r = role?.toLowerCase();
+    return r === "generic" || r === "none" || r === "inlinetextbox";
+}
+function extractUrlFromAXNode(ax) {
+    const props = ax.properties ?? [];
+    const urlProp = props.find((p) => p.name === "url");
+    const value = urlProp?.value?.value;
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function removeRedundantStaticTextChildren(parent, children) {
+    if (!parent.name)
+        return children;
+    const parentNorm = (0, treeFormatUtils_js_1.normaliseSpaces)(parent.name).trim();
+    let combined = "";
+    for (const c of children) {
+        if (c.role === "StaticText" && c.name) {
+            combined += (0, treeFormatUtils_js_1.normaliseSpaces)(c.name).trim();
+        }
+    }
+    if (combined === parentNorm) {
+        return children.filter((c) => c.role !== "StaticText");
+    }
+    return children;
+}
+//# sourceMappingURL=a11yTree.js.map