@browserbasehq/orca 3.7.0-preview.1 → 3.7.2-preview.0

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

@@ -73,6 +73,14 @@ export declare class V3 {
      * @deprecated Use `isVerified` instead. This alias will be removed in a future version.
      */
     get isAdvancedStealth(): boolean;
+    /**
+     * Whether coordinate pointer actions should actuate as touch instead of mouse.
+     *
+     * Explicit opt-in via the `useTouch` option — no session-derived or probed
+     * detection, so the answer is known before the first action, is stable for the
+     * whole run, and never surprises a caller who didn't ask for touch.
+     */
+    get usesTouch(): boolean;
     /**
      * Returns the configured viewport dimensions from launch options.
      * Falls back to default 1288x711 if not configured.

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;
@@ -190,6 +191,16 @@ let V3 = (() => {
         get isAdvancedStealth() {
             return this.isVerified;
         }
+        /**
+         * Whether coordinate pointer actions should actuate as touch instead of mouse.
+         *
+         * Explicit opt-in via the `useTouch` option — no session-derived or probed
+         * detection, so the answer is known before the first action, is stable for the
+         * whole run, and never surprises a caller who didn't ask for touch.
+         */
+        get usesTouch() {
+            return this.opts.useTouch === true;
+        }
         /**
          * Returns the configured viewport dimensions from launch options.
          * Falls back to default 1288x711 if not configured.
@@ -310,7 +321,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 +508,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)) {
@@ -838,10 +869,21 @@ let V3 = (() => {
                                 verbose: this.verbose,
                                 systemPrompt: this.opts.systemPrompt,
                                 selfHeal: this.opts.selfHeal,
+                                useTouch: this.opts.useTouch,
                                 browserbaseSessionCreateParams: createSessionPayload,
                                 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 +1036,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,7 +1523,9 @@ 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" },