@browserbasehq/orca 3.6.0-gemini-cua → 3.7.1-preview.0

package/dist/esm/lib/v3/understudy/domainPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domainPolicy.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/domainPolicy.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport { StagehandInvalidArgumentError } from \"../types/public/sdkErrors.js\";\nimport type { DomainPolicy } from \"../types/public/context.js\";\n\ntype DomainRule =\n  | { type: \"exact\"; hostname: string }\n  | { type: \"wildcard\"; hostname: string };\n\nexport type NormalizedDomainPolicy = {\n  allowedDomains: string[];\n  blockedDomains: string[];\n  allowedDomainRules: DomainRule[];\n  blockedDomainRules: DomainRule[];\n  fetchPatterns: Protocol.Fetch.RequestPattern[];\n};\n\nexport type DomainPolicyDecision =\n  | { action: \"continue\" }\n  | { action: \"block\"; reason: \"allowedDomains\" | \"blockedDomains\" };\n\nconst DOMAIN_LABEL_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;\nconst HTTP_SCHEMES = [\"http\", \"https\"] as const;\ntype DomainPolicyKey = \"allowedDomains\" | \"blockedDomains\";\n\nfunction canonicalizeHostname(hostname: string): string {\n  return hostname.toLowerCase().replace(/\\.+$/, \"\");\n}\n\nfunction validateHostname(\n  hostname: string,\n  original: string,\n  kind: \"allowedDomains\" | \"blockedDomains\",\n): void {\n  const label = kind === \"allowedDomains\" ? \"allowed\" : \"blocked\";\n\n  if (!hostname || hostname.length > 253) {\n    throw new StagehandInvalidArgumentError(\n      `Invalid ${label} domain pattern: \"${original}\"`,\n    );\n  }\n\n  const labels = hostname.split(\".\");\n  if (\n    labels.length < 2 ||\n    labels.some((label) => !DOMAIN_LABEL_RE.test(label))\n  ) {\n    throw new StagehandInvalidArgumentError(\n      `Invalid ${label} domain pattern: \"${original}\"`,\n    );\n  }\n}\n\nfunction normalizeDomainPattern(\n  pattern: unknown,\n  kind: \"allowedDomains\" | \"blockedDomains\",\n): DomainRule {\n  const label = kind === \"allowedDomains\" ? \"allowed\" : \"blocked\";\n  const capitalizedLabel = kind === \"allowedDomains\" ? \"Allowed\" : \"Blocked\";\n\n  if (typeof pattern !== \"string\") {\n    throw new StagehandInvalidArgumentError(\n      `${capitalizedLabel} domain patterns must be strings`,\n    );\n  }\n\n  const original = pattern;\n  const normalized = canonicalizeHostname(pattern.trim());\n\n  if (!normalized) {\n    throw new StagehandInvalidArgumentError(\n      `Invalid ${label} domain pattern: \"${original}\"`,\n    );\n  }\n\n  if (\n    normalized.includes(\"://\") ||\n    normalized.includes(\"/\") ||\n    normalized.includes(\":\") ||\n    normalized.includes(\"?\") ||\n    normalized.includes(\"#\")\n  ) {\n    throw new StagehandInvalidArgumentError(\n      `${capitalizedLabel} domain patterns must be domain-only values: \"${original}\"`,\n    );\n  }\n\n  if (normalized.startsWith(\"*.\")) {\n    const hostname = normalized.slice(2);\n    validateHostname(hostname, original, kind);\n    return { type: \"wildcard\", hostname };\n  }\n\n  if (normalized.includes(\"*\")) {\n    throw new StagehandInvalidArgumentError(\n      `Wildcards are only supported as a leading \"*.\": \"${original}\"`,\n    );\n  }\n\n  validateHostname(normalized, original, kind);\n  return { type: \"exact\", hostname: normalized };\n}\n\nfunction normalizeDomainPatterns(\n  patterns: unknown[] | undefined,\n  kind: DomainPolicyKey,\n): DomainRule[] {\n  if (!patterns?.length) return [];\n\n  const rulesByKey = new Map<string, DomainRule>();\n  for (const pattern of patterns) {\n    const rule = normalizeDomainPattern(pattern, kind);\n    rulesByKey.set(`${rule.type}:${rule.hostname}`, rule);\n  }\n\n  return Array.from(rulesByKey.values());\n}\n\nfunction getDomainPatterns(\n  policy: DomainPolicy | null | undefined,\n  key: DomainPolicyKey,\n): string[] {\n  if (policy === null) return [];\n\n  // Passing undefined usually means the caller accidentally omitted the policy\n  // argument or passed through an unset variable. Clearing must be explicit.\n  if (policy === undefined) {\n    throw new StagehandInvalidArgumentError(\n      \"Domain policy must be an object or null\",\n    );\n  }\n\n  const patterns = policy[key];\n  if (patterns === undefined) return [];\n\n  // Empty arrays intentionally clear that side of the policy, but malformed\n  // runtime values should fail fast rather than silently disabling interception.\n  if (!Array.isArray(patterns)) {\n    throw new StagehandInvalidArgumentError(\n      `${key} must be an array of strings`,\n    );\n  }\n\n  return patterns;\n}\n\nfunction patternHost(rule: DomainRule): string {\n  return rule.type === \"wildcard\" ? `*.${rule.hostname}` : rule.hostname;\n}\n\nfunction fetchPatternHosts(rule: DomainRule): string[] {\n  const host = patternHost(rule);\n  return [host, `${host}.`];\n}\n\nfunction toBlocklistFetchPatterns(\n  rules: DomainRule[],\n): Protocol.Fetch.RequestPattern[] {\n  const patterns: Protocol.Fetch.RequestPattern[] = [];\n\n  for (const rule of rules) {\n    for (const host of fetchPatternHosts(rule)) {\n      for (const scheme of HTTP_SCHEMES) {\n        patterns.push({\n          urlPattern: `${scheme}://${host}/*`,\n          requestStage: \"Request\",\n        });\n        patterns.push({\n          urlPattern: `${scheme}://${host}:*/*`,\n          requestStage: \"Request\",\n        });\n      }\n    }\n  }\n\n  return patterns;\n}\n\nfunction toAllowlistFetchPatterns(): Protocol.Fetch.RequestPattern[] {\n  return HTTP_SCHEMES.map((scheme) => ({\n    urlPattern: `${scheme}://*/*`,\n    requestStage: \"Request\",\n  }));\n}\n\nexport function normalizeDomainPolicy(\n  policy: DomainPolicy | null | undefined,\n): NormalizedDomainPolicy | null {\n  const allowedDomains = getDomainPatterns(policy, \"allowedDomains\");\n  const blockedDomains = getDomainPatterns(policy, \"blockedDomains\");\n\n  if (!allowedDomains.length && !blockedDomains.length) return null;\n\n  const allowedDomainRules = normalizeDomainPatterns(\n    allowedDomains,\n    \"allowedDomains\",\n  );\n  const blockedDomainRules = normalizeDomainPatterns(\n    blockedDomains,\n    \"blockedDomains\",\n  );\n\n  return {\n    allowedDomains: allowedDomainRules.map(patternHost),\n    blockedDomains: blockedDomainRules.map(patternHost),\n    allowedDomainRules,\n    blockedDomainRules,\n    fetchPatterns: allowedDomainRules.length\n      ? toAllowlistFetchPatterns()\n      : toBlocklistFetchPatterns(blockedDomainRules),\n  };\n}\n\nfunction hostnameFromHttpUrl(url: string): string | null {\n  try {\n    const parsed = new URL(url);\n    if (parsed.protocol !== \"http:\" && parsed.protocol !== \"https:\") {\n      return null;\n    }\n    return canonicalizeHostname(parsed.hostname);\n  } catch {\n    return null;\n  }\n}\n\nfunction matchesDomainRules(hostname: string, rules: DomainRule[]): boolean {\n  return rules.some((rule) => {\n    if (rule.type === \"exact\") {\n      return hostname === rule.hostname;\n    }\n    return hostname.endsWith(`.${rule.hostname}`);\n  });\n}\n\nexport function getDomainPolicyDecision(\n  url: string,\n  policy: NormalizedDomainPolicy | null,\n): DomainPolicyDecision {\n  if (!policy) return { action: \"continue\" };\n\n  const hostname = hostnameFromHttpUrl(url);\n  if (!hostname) return { action: \"continue\" };\n\n  if (matchesDomainRules(hostname, policy.blockedDomainRules)) {\n    return { action: \"block\", reason: \"blockedDomains\" };\n  }\n\n  if (\n    policy.allowedDomainRules.length &&\n    !matchesDomainRules(hostname, policy.allowedDomainRules)\n  ) {\n    return { action: \"block\", reason: \"allowedDomains\" };\n  }\n\n  return { action: \"continue\" };\n}\n"]}

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

@@ -60,7 +60,7 @@ import { resolveTools } from "./mcp/utils.js";
 import { HYBRID_CAPABLE_MODEL_PATTERNS } from "./types/private/agent.js";
 import { AVAILABLE_CUA_MODELS, defaultExtractSchema, V3FunctionName, CuaModelRequiredError, StagehandInvalidArgumentError, StagehandNotInitializedError, MissingEnvironmentVariableError, StagehandInitError, } from "./types/public/index.js";
 import { V3Context } from "./understudy/context.js";
-import { resolveModel } from "../modelUtils.js";
+import { AUTO_MODEL_NAME, isAutoModel, resolveModel } from "../modelUtils.js";
 import { StagehandAPIClient } from "./api.js";
 import { validateExperimentalFeatures } from "./agent/utils/validateExperimentalFeatures.js";
 import { flattenVariables } from "./agent/utils/variables.js";
@@ -69,6 +69,7 @@ import { EventEmitterWithWildcardSupport } from "./flowlogger/EventEmitter.js";
 import { EventStore } from "./flowlogger/EventStore.js";
 import { createTimeoutGuard } from "./handlers/handlerUtils/timeoutGuard.js";
 import { ActTimeoutError } from "./types/public/sdkErrors.js";
+const AUTO_MODEL_API_ONLY_MESSAGE = `model: "${AUTO_MODEL_NAME}" is only supported when running through the Stagehand API (env: "BROWSERBASE" with disableAPI: false and experimental: false). Specify a concrete model (e.g. "openai/gpt-5") instead.`;
 const DEFAULT_MODEL_NAME = "openai/gpt-4.1-mini";
 const DEFAULT_VIEWPORT = { width: 1288, height: 711 };
 const DEFAULT_AGENT_TOOL_TIMEOUT_MS = 45000;
@@ -310,7 +311,18 @@ let V3 = (() => {
             const baseClientOptions = clientOptions
                 ? { ...clientOptions }
                 : {};
-            if (opts.llmClient) {
+            if (isAutoModel(this.modelName)) {
+                if (opts.llmClient ||
+                    opts.env !== "BROWSERBASE" ||
+                    this.disableAPI ||
+                    this.experimental) {
+                    throw new StagehandInvalidArgumentError(AUTO_MODEL_API_ONLY_MESSAGE);
+                }
+                // "auto" delegates model selection to the Stagehand API, so no local
+                // LLM client is created and no provider API key is required.
+                this.modelClientOptions = baseClientOptions;
+            }
+            else if (opts.llmClient) {
                 this.llmClient = opts.llmClient;
                 this.modelClientOptions = baseClientOptions;
                 this.disableAPI = true;
@@ -486,6 +498,15 @@ let V3 = (() => {
                 clientOptions = rest;
                 perCallMiddleware = middleware;
             }
+            if (isAutoModel(modelName)) {
+                if (!this.apiClient) {
+                    throw new StagehandInvalidArgumentError(AUTO_MODEL_API_ONLY_MESSAGE);
+                }
+                // The Stagehand API resolves "auto" server-side and intercepts every
+                // act/extract/observe, so the local client is never dereferenced here.
+                // Note it is undefined when the session's base model is also "auto".
+                return this.llmClient;
+            }
             if (modelName === this.modelName &&
                 !perCallMiddleware &&
                 (!clientOptions || Object.keys(clientOptions).length === 0)) {
@@ -842,6 +863,16 @@ let V3 = (() => {
                                 browserbaseSessionID: this.opts.browserbaseSessionID,
                             });
                             if (!available) {
+                                if (isAutoModel(this.modelName)) {
+                                    // "auto" has no local fallback; end the just-created session
+                                    // best-effort before surfacing the error. Never end a
+                                    // caller-supplied (resumed) session we didn't create.
+                                    if (!this.opts.browserbaseSessionID) {
+                                        await this.apiClient.end().catch(() => { });
+                                    }
+                                    this.apiClient = null;
+                                    throw new StagehandInitError(`model: "${AUTO_MODEL_NAME}" requires the Stagehand API, but it is unavailable for this session (sessionId: ${sessionId}). Specify a concrete model (e.g. "openai/gpt-5") instead.`);
+                                }
                                 this.apiClient = null;
                             }
                             this.opts.browserbaseSessionID = sessionId;
@@ -994,7 +1025,10 @@ let V3 = (() => {
                 let actCacheContext = null;
                 const canUseCache = typeof input === "string" &&
                     !this.isAgentReplayRecording() &&
-                    this.actCache.enabled;
+                    this.actCache.enabled &&
+                    // "auto" sessions have no local LLM client for replay self-heal;
+                    // rely on the API (and its server-side cache) instead.
+                    !isAutoModel(this.modelName);
                 if (canUseCache) {
                     actCacheContext = await this.actCache.prepareContext(input, page, flattenVariables(options?.variables));
                     if (actCacheContext) {
@@ -1478,14 +1512,19 @@ let V3 = (() => {
                     cua: { value: isCuaMode ? "true" : "false", type: "boolean" },
                     mode: { value: loggedMode, type: "string" },
                     model: {
-                        value: extractModelName(options?.model) ?? this.llmClient.modelName,
+                        value: extractModelName(options?.model) ??
+                            this.llmClient?.modelName ??
+                            this.modelName,
                         type: "string",
                     },
                     systemPrompt: { value: options?.systemPrompt ?? "", type: "string" },
                     tools: { value: JSON.stringify(options?.tools ?? {}), type: "object" },
                     ...(options?.integrations && {
                         integrations: {
-                            value: JSON.stringify(options.integrations),
+                            // Integrations may contain live MCP `Client` instances (from
+                            // connectToMCPServer), which are circular and throw in JSON.stringify.
+                            // Log a safe descriptor instead: keep URL strings, summarize clients.
+                            value: JSON.stringify(options.integrations.map((integration) => typeof integration === "string" ? integration : "[mcp client]")),
                             type: "object",
                         },
                     }),