@browserbasehq/orca 3.2.0-preview.4 → 3.2.1-preview.0

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

@@ -1,12 +1,19 @@
+import type { LanguageModelV2Middleware } from "@ai-sdk/provider";
 import { z } from "zod";
 import { InferStagehandSchema, StagehandZodSchema } from "./zodCompat.js";
 import { LLMClient } from "./llm/LLMClient.js";
 import { AgentReplayStep } from "./types/private/index.js";
-import { AgentConfig, AgentExecuteOptions, AgentStreamExecuteOptions, AgentResult, LogLine, StagehandMetrics, Action, ActOptions, ActResult, defaultExtractSchema, ExtractOptions, HistoryEntry, ObserveOptions, pageTextSchema, V3FunctionName, V3Options, AgentStreamResult } from "./types/public/index.js";
+import { AgentConfig, AgentExecuteOptions, AgentStreamExecuteOptions, AgentResult, LogLine, StagehandMetrics, Action, ActOptions, ActResult, defaultExtractSchema, ExtractOptions, HistoryEntry, ObserveOptions, pageTextSchema, V3FunctionName, AvailableModel, ClientOptions, V3Options, AgentStreamResult } from "./types/public/index.js";
 import { V3Context } from "./understudy/context.js";
 import { type FlowLoggerContext } from "./flowlogger/FlowLogger.js";
 import { EventEmitterWithWildcardSupport } from "./flowlogger/EventEmitter.js";
 import { EventStore } from "./flowlogger/EventStore.js";
+type ResolvedModelConfiguration = {
+    modelName: AvailableModel;
+    clientOptions?: ClientOptions;
+    middleware?: LanguageModelV2Middleware;
+};
+export declare function resolveModelConfiguration(model?: V3Options["model"]): ResolvedModelConfiguration;
 /**
  * V3
  *
@@ -52,7 +59,18 @@ export declare class V3 {
      */
     get isBrowserbase(): boolean;
     /**
-     * Returns true if advancedStealth is enabled in Browserbase settings.
+     * Returns true if captcha auto-solving is enabled on Browserbase.
+     * Defaults to true when not explicitly set to false.
+     */
+    get isCaptchaAutoSolveEnabled(): boolean;
+    /**
+     * Returns true if Browserbase Verified mode is enabled in settings.
+     * Legacy `advancedStealth` is treated as equivalent for backwards compatibility.
+     */
+    get isVerified(): boolean;
+    /**
+     * Backwards-compatible alias for Browserbase managed fingerprinting mode.
+     * @deprecated Use `isVerified` instead. This alias will be removed in a future version.
      */
     get isAdvancedStealth(): boolean;
     /**
@@ -90,6 +108,8 @@ export declare class V3 {
      * When using API mode, fetches metrics from the API. Otherwise returns local metrics.
      */
     get metrics(): Promise<StagehandMetrics>;
+    private mergeAgentMetricsWithLocalFallback;
+    private updateAgentMetricsFromUsage;
     private resolveLlmClient;
     private beginAgentReplayRecording;
     private endAgentReplayRecording;
@@ -199,3 +219,4 @@ export declare class V3 {
         execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
     };
 }
+export {};

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

@@ -49,6 +49,7 @@ import { ExtractHandler } from "./handlers/extractHandler.js";
 import { ObserveHandler } from "./handlers/observeHandler.js";
 import { V3AgentHandler } from "./handlers/v3AgentHandler.js";
 import { V3CuaAgentHandler } from "./handlers/v3CuaAgentHandler.js";
+import { CAPTCHA_CUA_SYSTEM_PROMPT_NOTE } from "./agent/utils/captchaSolver.js";
 import { createBrowserbaseSession } from "./launch/browserbase.js";
 import { launchLocalChrome } from "./launch/local.js";
 import { LLMProvider } from "./llm/LLMProvider.js";
@@ -70,7 +71,7 @@ import { ActTimeoutError } from "./types/public/sdkErrors.js";
 const DEFAULT_MODEL_NAME = "openai/gpt-4.1-mini";
 const DEFAULT_VIEWPORT = { width: 1288, height: 711 };
 const DEFAULT_AGENT_TOOL_TIMEOUT_MS = 45000;
-function resolveModelConfiguration(model) {
+export function resolveModelConfiguration(model) {
     if (!model) {
         return { modelName: DEFAULT_MODEL_NAME };
     }
@@ -78,13 +79,14 @@ function resolveModelConfiguration(model) {
         return { modelName: model };
     }
     if (model && typeof model === "object") {
-        const { modelName, ...clientOptions } = model;
+        const { modelName, middleware, ...clientOptions } = model;
         if (!modelName) {
             throw new StagehandInvalidArgumentError("model.modelName is required when providing client options.");
         }
         return {
             modelName,
             clientOptions: clientOptions,
+            middleware,
         };
     }
     return { modelName: DEFAULT_MODEL_NAME };
@@ -163,11 +165,29 @@ let V3 = (() => {
             return this.state.kind === "BROWSERBASE";
         }
         /**
-         * Returns true if advancedStealth is enabled in Browserbase settings.
+         * Returns true if captcha auto-solving is enabled on Browserbase.
+         * Defaults to true when not explicitly set to false.
+         */
+        get isCaptchaAutoSolveEnabled() {
+            return (this.isBrowserbase &&
+                this.opts.browserbaseSessionCreateParams?.browserSettings
+                    ?.solveCaptchas !== false);
+        }
+        /**
+         * Returns true if Browserbase Verified mode is enabled in settings.
+         * Legacy `advancedStealth` is treated as equivalent for backwards compatibility.
+         */
+        get isVerified() {
+            const browserSettings = this.opts.browserbaseSessionCreateParams?.browserSettings;
+            return (browserSettings?.verified === true ||
+                browserSettings?.advancedStealth === true);
+        }
+        /**
+         * Backwards-compatible alias for Browserbase managed fingerprinting mode.
+         * @deprecated Use `isVerified` instead. This alias will be removed in a future version.
          */
         get isAdvancedStealth() {
-            return (this.opts.browserbaseSessionCreateParams?.browserSettings
-                ?.advancedStealth === true);
+            return this.isVerified;
         }
         /**
          * Returns the configured viewport dimensions from launch options.
@@ -279,11 +299,11 @@ let V3 = (() => {
             catch {
                 // ignore
             }
-            const { modelName, clientOptions } = resolveModelConfiguration(opts.model);
+            const { modelName, clientOptions, middleware } = resolveModelConfiguration(opts.model);
             this.modelName = modelName;
             this.experimental = opts.experimental ?? false;
             this.logInferenceToFile = opts.logInferenceToFile ?? false;
-            this.llmProvider = new LLMProvider(this.logger);
+            this.llmProvider = new LLMProvider(this.logger, middleware);
             this.domSettleTimeoutMs = opts.domSettleTimeout;
             this.disableAPI = opts.disableAPI ?? false;
             const baseClientOptions = clientOptions
@@ -342,7 +362,7 @@ let V3 = (() => {
             this.opts = opts;
             // FlowLogger always gets a per-instance session context and shared event
             // bus. The attached EventStore decides which sinks are active:
-            // `verbose: 2` or `BROWSERBASE_FLOW_LOGS=1` enables pretty stderr output,
+            // `BROWSERBASE_FLOW_LOGS=1` enables pretty stderr output,
             // and `BROWSERBASE_CONFIG_DIR` enables the pretty/jsonl file sinks for this session.
             this.eventStore = new EventStore(this.sessionId, opts);
             this.flowLoggerContext = FlowLogger.init(this.sessionId, this.bus);
@@ -365,7 +385,10 @@ let V3 = (() => {
         get metrics() {
             if (this.apiClient) {
                 // Fetch metrics from the API
-                return this.apiClient.getReplayMetrics().catch((error) => {
+                return this.apiClient
+                    .getReplayMetrics()
+                    .then((metrics) => this.mergeAgentMetricsWithLocalFallback(metrics))
+                    .catch((error) => {
                     this.logger({
                         category: "metrics",
                         message: `Failed to fetch metrics from API: ${error}`,
@@ -378,21 +401,78 @@ let V3 = (() => {
             // Return local metrics wrapped in a Promise for consistency
             return Promise.resolve(this.stagehandMetrics);
         }
+        mergeAgentMetricsWithLocalFallback(remoteMetrics) {
+            // In API mode, agent.execute() is the only path that returns trusted inline
+            // usage today, so only repair the agent bucket from local state.
+            const agentPromptTokens = Math.max(remoteMetrics.agentPromptTokens, this.stagehandMetrics.agentPromptTokens);
+            const agentCompletionTokens = Math.max(remoteMetrics.agentCompletionTokens, this.stagehandMetrics.agentCompletionTokens);
+            const agentReasoningTokens = Math.max(remoteMetrics.agentReasoningTokens, this.stagehandMetrics.agentReasoningTokens);
+            const agentCachedInputTokens = Math.max(remoteMetrics.agentCachedInputTokens, this.stagehandMetrics.agentCachedInputTokens);
+            const agentInferenceTimeMs = Math.max(remoteMetrics.agentInferenceTimeMs, this.stagehandMetrics.agentInferenceTimeMs);
+            const metrics = {
+                ...remoteMetrics,
+                agentPromptTokens,
+                agentCompletionTokens,
+                agentReasoningTokens,
+                agentCachedInputTokens,
+                agentInferenceTimeMs,
+                totalPromptTokens: 0,
+                totalCompletionTokens: 0,
+                totalReasoningTokens: 0,
+                totalCachedInputTokens: 0,
+                totalInferenceTimeMs: 0,
+            };
+            metrics.totalPromptTokens =
+                metrics.actPromptTokens +
+                    metrics.extractPromptTokens +
+                    metrics.observePromptTokens +
+                    metrics.agentPromptTokens;
+            metrics.totalCompletionTokens =
+                metrics.actCompletionTokens +
+                    metrics.extractCompletionTokens +
+                    metrics.observeCompletionTokens +
+                    metrics.agentCompletionTokens;
+            metrics.totalReasoningTokens =
+                metrics.actReasoningTokens +
+                    metrics.extractReasoningTokens +
+                    metrics.observeReasoningTokens +
+                    metrics.agentReasoningTokens;
+            metrics.totalCachedInputTokens =
+                metrics.actCachedInputTokens +
+                    metrics.extractCachedInputTokens +
+                    metrics.observeCachedInputTokens +
+                    metrics.agentCachedInputTokens;
+            metrics.totalInferenceTimeMs =
+                metrics.actInferenceTimeMs +
+                    metrics.extractInferenceTimeMs +
+                    metrics.observeInferenceTimeMs +
+                    metrics.agentInferenceTimeMs;
+            return metrics;
+        }
+        updateAgentMetricsFromUsage(usage) {
+            if (!usage) {
+                return;
+            }
+            this.updateMetrics(V3FunctionName.AGENT, usage.input_tokens, usage.output_tokens, usage.reasoning_tokens ?? 0, usage.cached_input_tokens ?? 0, usage.inference_time_ms);
+        }
         resolveLlmClient(model) {
             if (!model) {
                 return this.llmClient;
             }
             let modelName;
             let clientOptions;
+            let perCallMiddleware;
             if (typeof model === "string") {
                 modelName = model;
             }
             else {
-                const { modelName: overrideModelName, ...rest } = model;
+                const { modelName: overrideModelName, middleware, ...rest } = model;
                 modelName = overrideModelName;
                 clientOptions = rest;
+                perCallMiddleware = middleware;
             }
             if (modelName === this.modelName &&
+                !perCallMiddleware &&
                 (!clientOptions || Object.keys(clientOptions).length === 0)) {
                 return this.llmClient;
             }
@@ -409,6 +489,13 @@ let V3 = (() => {
                     mergedOptions.apiKey = apiKey;
                 }
             }
+            if (perCallMiddleware) {
+                return this.llmProvider.getClient(modelName, mergedOptions, {
+                    experimental: this.experimental,
+                    disableAPI: this.disableAPI,
+                    middleware: perCallMiddleware,
+                });
+            }
             const cacheKey = JSON.stringify({
                 modelName,
                 clientOptions: mergedOptions,
@@ -417,7 +504,10 @@ let V3 = (() => {
             if (cached) {
                 return cached;
             }
-            const client = this.llmProvider.getClient(modelName, mergedOptions, { experimental: this.experimental, disableAPI: this.disableAPI });
+            const client = this.llmProvider.getClient(modelName, mergedOptions, {
+                experimental: this.experimental,
+                disableAPI: this.disableAPI,
+            });
             this.overrideLlmClients.set(cacheKey, client);
             return client;
         }
@@ -1053,6 +1143,7 @@ let V3 = (() => {
                 const handlerParams = {
                     instruction,
                     model: options?.model,
+                    variables: options?.variables,
                     timeout: options?.timeout,
                     selector: options?.selector,
                     page: page,
@@ -1072,6 +1163,7 @@ let V3 = (() => {
                 // history: record observe call (omit page object)
                 this.addToHistory("observe", {
                     instruction,
+                    variables: options?.variables,
                     timeout: options?.timeout,
                 }, results);
                 return results;
@@ -1339,7 +1431,7 @@ let V3 = (() => {
                 ? this.resolveLlmClient(options.model)
                 : this.llmClient;
             const resolvedExecutionModel = options?.executionModel ?? options?.model;
-            const handler = new V3AgentHandler(this, this.logger, agentLlmClient, resolvedExecutionModel, options?.systemPrompt, tools, options?.mode);
+            const handler = new V3AgentHandler(this, this.logger, agentLlmClient, resolvedExecutionModel, options?.systemPrompt, tools, options?.mode, this.isCaptchaAutoSolveEnabled);
             const resolvedOptions = typeof instructionOrOptions === "string"
                 ? {
                     instruction: instructionOrOptions,
@@ -1442,8 +1534,11 @@ let V3 = (() => {
                     const handler = new V3CuaAgentHandler(this, this.logger, {
                         modelName,
                         clientOptions,
-                        userProvidedInstructions: options.systemPrompt ??
-                            `You are a helpful assistant that can use a web browser.\nDo not ask follow up questions, the user will trust your judgement.`,
+                        userProvidedInstructions: (options.systemPrompt ??
+                            `You are a helpful assistant that can use a web browser.\nDo not ask follow up questions, the user will trust your judgement.`) +
+                            (this.isCaptchaAutoSolveEnabled
+                                ? CAPTCHA_CUA_SYSTEM_PROMPT_NOTE
+                                : ""),
                     }, tools);
                     const resolvedOptions = typeof instructionOrOptions === "string"
                         ? {
@@ -1489,6 +1584,7 @@ let V3 = (() => {
                         if (this.apiClient && !this.experimental) {
                             const page = await this.ctx.awaitActivePage();
                             result = await this.apiClient.agentExecute(options, resolvedOptions, page.mainFrameId(), !!cacheContext);
+                            this.updateAgentMetricsFromUsage(result.usage);
                             if (cacheContext) {
                                 const transferredEntry = this.apiClient.consumeLatestAgentCacheEntry();
                                 await this.agentCache.storeTransferredEntry(transferredEntry);
@@ -1572,6 +1668,7 @@ let V3 = (() => {
                     if (this.apiClient && !this.experimental) {
                         const page = await this.ctx.awaitActivePage();
                         result = await this.apiClient.agentExecute(options ?? {}, resolvedOptions, page.mainFrameId(), !!cacheContext);
+                        this.updateAgentMetricsFromUsage(result.usage);
                         if (cacheContext) {
                             const transferredEntry = this.apiClient.consumeLatestAgentCacheEntry();
                             await this.agentCache.storeTransferredEntry(transferredEntry);