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

package/dist/cjs/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/cjs/lib/v3/v3.js

@@ -109,6 +109,7 @@ const EventEmitter_js_1 = require("./flowlogger/EventEmitter.js");
 const EventStore_js_1 = require("./flowlogger/EventStore.js");
 const timeoutGuard_js_1 = require("./handlers/handlerUtils/timeoutGuard.js");
 const sdkErrors_js_1 = require("./types/public/sdkErrors.js");
+const AUTO_MODEL_API_ONLY_MESSAGE = `model: "${modelUtils_js_2.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;
@@ -230,6 +231,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.
@@ -350,7 +361,18 @@ let V3 = (() => {
             const baseClientOptions = clientOptions
                 ? { ...clientOptions }
                 : {};
-            if (opts.llmClient) {
+            if ((0, modelUtils_js_2.isAutoModel)(this.modelName)) {
+                if (opts.llmClient ||
+                    opts.env !== "BROWSERBASE" ||
+                    this.disableAPI ||
+                    this.experimental) {
+                    throw new index_js_1.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;
@@ -526,6 +548,15 @@ let V3 = (() => {
                 clientOptions = rest;
                 perCallMiddleware = middleware;
             }
+            if ((0, modelUtils_js_2.isAutoModel)(modelName)) {
+                if (!this.apiClient) {
+                    throw new index_js_1.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)) {
@@ -878,10 +909,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 ((0, modelUtils_js_2.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 index_js_1.StagehandInitError(`model: "${modelUtils_js_2.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;
@@ -1034,7 +1076,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.
+                    !(0, modelUtils_js_2.isAutoModel)(this.modelName);
                 if (canUseCache) {
                     actCacheContext = await this.actCache.prepareContext(input, page, (0, variables_js_1.flattenVariables)(options?.variables));
                     if (actCacheContext) {
@@ -1518,7 +1563,9 @@ let V3 = (() => {
                     cua: { value: isCuaMode ? "true" : "false", type: "boolean" },
                     mode: { value: loggedMode, type: "string" },
                     model: {
-                        value: (0, modelUtils_js_1.extractModelName)(options?.model) ?? this.llmClient.modelName,
+                        value: (0, modelUtils_js_1.extractModelName)(options?.model) ??
+                            this.llmClient?.modelName ??
+                            this.modelName,
                         type: "string",
                     },
                     systemPrompt: { value: options?.systemPrompt ?? "", type: "string" },