@browserbasehq/orca 3.1.0-patch.4 → 3.2.0-middleware.1

package/dist/cjs/lib/v3/v3.js

@@ -71,7 +71,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.V3 = void 0;
-const events_1 = require("events");
+exports.resolveModelConfiguration = resolveModelConfiguration;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
@@ -89,6 +89,7 @@ const extractHandler_js_1 = require("./handlers/extractHandler.js");
 const observeHandler_js_1 = require("./handlers/observeHandler.js");
 const v3AgentHandler_js_1 = require("./handlers/v3AgentHandler.js");
 const v3CuaAgentHandler_js_1 = require("./handlers/v3CuaAgentHandler.js");
+const captchaSolver_js_1 = require("./agent/utils/captchaSolver.js");
 const browserbase_js_1 = require("./launch/browserbase.js");
 const local_js_1 = require("./launch/local.js");
 const LLMProvider_js_1 = require("./llm/LLMProvider.js");
@@ -102,11 +103,14 @@ const modelUtils_js_2 = require("../modelUtils.js");
 const api_js_1 = require("./api.js");
 const validateExperimentalFeatures_js_1 = require("./agent/utils/validateExperimentalFeatures.js");
 const variables_js_1 = require("./agent/utils/variables.js");
-const flowLogger_js_1 = require("./flowLogger.js");
+const FlowLogger_js_1 = require("./flowlogger/FlowLogger.js");
+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 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) {
     if (!model) {
         return { modelName: DEFAULT_MODEL_NAME };
@@ -115,13 +119,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 index_js_1.StagehandInvalidArgumentError("model.modelName is required when providing client options.");
         }
         return {
             modelName,
             clientOptions: clientOptions,
+            middleware,
         };
     }
     return { modelName: DEFAULT_MODEL_NAME };
@@ -149,9 +154,15 @@ let V3 = (() => {
     return class V3 {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
-            _act_decorators = [(0, flowLogger_js_1.logStagehandStep)("Stagehand.act", "ACT")];
-            _extract_decorators = [(0, flowLogger_js_1.logStagehandStep)("Stagehand.extract", "EXTRACT")];
-            _observe_decorators = [(0, flowLogger_js_1.logStagehandStep)("Stagehand.observe", "OBSERVE")];
+            _act_decorators = [FlowLogger_js_1.FlowLogger.wrapWithLogging({
+                    eventType: "StagehandAct",
+                })];
+            _extract_decorators = [FlowLogger_js_1.FlowLogger.wrapWithLogging({
+                    eventType: "StagehandExtract",
+                })];
+            _observe_decorators = [FlowLogger_js_1.FlowLogger.wrapWithLogging({
+                    eventType: "StagehandObserve",
+                })];
             __esDecorate(this, null, _act_decorators, { kind: "method", name: "act", static: false, private: false, access: { has: obj => "act" in obj, get: obj => obj.act }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _extract_decorators, { kind: "method", name: "extract", static: false, private: false, access: { has: obj => "extract" in obj, get: obj => obj.extract }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _observe_decorators, { kind: "method", name: "observe", static: false, private: false, access: { has: obj => "observe" in obj, get: obj => obj.observe }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -168,7 +179,7 @@ let V3 = (() => {
          * Event bus for internal communication.
          * Emits events like 'screenshot' when screenshots are captured during agent execution.
          */
-        bus = new events_1.EventEmitter();
+        bus = new EventEmitter_js_1.EventEmitterWithWildcardSupport();
         modelName;
         modelClientOptions;
         llmProvider;
@@ -193,6 +204,15 @@ let V3 = (() => {
         get isBrowserbase() {
             return this.state.kind === "BROWSERBASE";
         }
+        /**
+         * 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 advancedStealth is enabled in Browserbase settings.
          */
@@ -236,6 +256,9 @@ let V3 = (() => {
         stagehandLogger;
         _history = [];
         instanceId;
+        sessionId;
+        eventStore;
+        flowLoggerContext;
         static _processGuardsInstalled = false;
         static _instances = new Set();
         cacheStorage;
@@ -275,6 +298,7 @@ let V3 = (() => {
             this.externalLogger = opts.logger;
             this.verbose = opts.verbose ?? 1;
             this.instanceId = (0, uuid_1.v7)();
+            this.sessionId = opts.sessionId ?? this.instanceId;
             this.keepAlive =
                 opts.keepAlive ?? opts.browserbaseSessionCreateParams?.keepAlive;
             // Create per-instance StagehandLogger (handles usePino, verbose, externalLogger)
@@ -306,11 +330,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_js_1.LLMProvider(this.logger);
+            this.llmProvider = new LLMProvider_js_1.LLMProvider(this.logger, middleware);
             this.domSettleTimeoutMs = opts.domSettleTimeout;
             this.disableAPI = opts.disableAPI ?? false;
             const baseClientOptions = clientOptions
@@ -367,8 +391,21 @@ let V3 = (() => {
                 act: this.act.bind(this),
             });
             this.opts = opts;
-            // Initialize session file logger
-            flowLogger_js_1.SessionFileLogger.init(this.instanceId, opts);
+            // FlowLogger always gets a per-instance session context and shared event
+            // bus. The attached EventStore decides which sinks are active:
+            // `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_js_1.EventStore(this.sessionId, opts);
+            this.flowLoggerContext = FlowLogger_js_1.FlowLogger.init(this.sessionId, this.bus);
+            // Flow event pipeline:
+            // FlowLogger -> this.bus -> this.eventStore -> configured sinks/query history.
+            // V3 owns the bus for this session. EventStore is not another bus; it just
+            // receives already-emitted FlowEvents here, then fans them out to sinks and
+            // keeps the queryable per-session history used by /v4/log, parent/ancestor lookups, and tests.
+            // `on()` stores a strong reference to the handler, so the EventStore
+            // stays alive until this bus is garbage-collected with the rest of the V3
+            // object graph.
+            this.bus.on("*", this.eventStore.emit);
             // Track instance for global process guard handling
             V3._instances.add(this);
         }
@@ -398,15 +435,18 @@ let V3 = (() => {
             }
             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;
             }
@@ -431,7 +471,11 @@ 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,
+                middleware: perCallMiddleware,
+            });
             this.overrideLlmClients.set(cacheKey, client);
             return client;
         }
@@ -591,6 +635,13 @@ let V3 = (() => {
                             }
                         }
                         const lbo = this.opts.localBrowserLaunchOptions ?? {};
+                        if (lbo.cdpHeaders && !lbo.cdpUrl) {
+                            this.logger({
+                                category: "init",
+                                message: "`cdpHeaders` was provided but `cdpUrl` is not set — cdpHeaders will be ignored. Set `cdpUrl` to connect to an existing browser via CDP.",
+                                level: 2,
+                            });
+                        }
                         // If a CDP URL is provided, attach instead of launching.
                         if (lbo.cdpUrl) {
                             this.logger({
@@ -600,10 +651,9 @@ let V3 = (() => {
                             });
                             this.ctx = await context_js_1.V3Context.create(lbo.cdpUrl, {
                                 env: "LOCAL",
+                                cdpHeaders: lbo.cdpHeaders,
                             });
-                            const logCtx = flowLogger_js_1.SessionFileLogger.getContext();
-                            this.ctx.conn.cdpLogger = (info) => flowLogger_js_1.SessionFileLogger.logCdpCallEvent(info, logCtx);
-                            this.ctx.conn.cdpEventLogger = (info) => flowLogger_js_1.SessionFileLogger.logCdpMessageEvent(info, logCtx);
+                            this.ctx.conn.flowLoggerContext = this.flowLoggerContext;
                             this.ctx.conn.onTransportClosed(this._onCdpClosed);
                             this.state = {
                                 kind: "LOCAL",
@@ -699,9 +749,7 @@ let V3 = (() => {
                             env: "LOCAL",
                             localBrowserLaunchOptions: lbo,
                         });
-                        const logCtx = flowLogger_js_1.SessionFileLogger.getContext();
-                        this.ctx.conn.cdpLogger = (info) => flowLogger_js_1.SessionFileLogger.logCdpCallEvent(info, logCtx);
-                        this.ctx.conn.cdpEventLogger = (info) => flowLogger_js_1.SessionFileLogger.logCdpMessageEvent(info, logCtx);
+                        this.ctx.conn.flowLoggerContext = this.flowLoggerContext;
                         this.ctx.conn.onTransportClosed(this._onCdpClosed);
                         this.state = {
                             kind: "LOCAL",
@@ -728,9 +776,6 @@ let V3 = (() => {
                     }
                     if (this.opts.env === "BROWSERBASE") {
                         const { apiKey, projectId } = this.requireBrowserbaseCreds();
-                        if (!apiKey || !projectId) {
-                            throw new index_js_1.MissingEnvironmentVariableError("BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID", "Browserbase environment");
-                        }
                         this.logger({
                             category: "init",
                             message: "Starting browserbase session",
@@ -739,9 +784,13 @@ let V3 = (() => {
                         const baseSessionParams = this.opts.browserbaseSessionCreateParams ?? {};
                         const resolvedKeepAlive = this.keepAlive;
                         const keepAlive = this.keepAlive === true;
-                        const effectiveSessionParams = resolvedKeepAlive !== undefined
-                            ? { ...baseSessionParams, keepAlive: resolvedKeepAlive }
-                            : baseSessionParams;
+                        let effectiveSessionParams = baseSessionParams;
+                        if (resolvedKeepAlive !== undefined) {
+                            effectiveSessionParams = {
+                                ...baseSessionParams,
+                                keepAlive: resolvedKeepAlive,
+                            };
+                        }
                         if (!this.disableAPI && !this.experimental) {
                             this.apiClient = new api_js_1.StagehandAPIClient({
                                 apiKey,
@@ -749,18 +798,20 @@ let V3 = (() => {
                                 logger: this.logger,
                                 serverCache: this.opts.serverCache,
                             });
+                            const { projectId: overrideProjectId, browserSettings, userMetadata, ...restSessionParams } = effectiveSessionParams;
+                            const resolvedProjectId = overrideProjectId ?? projectId;
                             const createSessionPayload = {
-                                projectId: effectiveSessionParams.projectId ?? projectId,
-                                ...effectiveSessionParams,
+                                ...(resolvedProjectId ? { projectId: resolvedProjectId } : {}),
+                                ...restSessionParams,
                                 browserSettings: {
-                                    ...(effectiveSessionParams.browserSettings ?? {}),
-                                    viewport: effectiveSessionParams.browserSettings?.viewport ?? {
+                                    ...(browserSettings ?? {}),
+                                    viewport: browserSettings?.viewport ?? {
                                         width: 1288,
                                         height: 711,
                                     },
                                 },
                                 userMetadata: {
-                                    ...(effectiveSessionParams.userMetadata ?? {}),
+                                    ...(userMetadata ?? {}),
                                     stagehand: "true",
                                 },
                             };
@@ -784,9 +835,7 @@ let V3 = (() => {
                             env: "BROWSERBASE",
                             apiClient: this.apiClient,
                         });
-                        const logCtx = flowLogger_js_1.SessionFileLogger.getContext();
-                        this.ctx.conn.cdpLogger = (info) => flowLogger_js_1.SessionFileLogger.logCdpCallEvent(info, logCtx);
-                        this.ctx.conn.cdpEventLogger = (info) => flowLogger_js_1.SessionFileLogger.logCdpMessageEvent(info, logCtx);
+                        this.ctx.conn.flowLoggerContext = this.flowLoggerContext;
                         this.ctx.conn.onTransportClosed(this._onCdpClosed);
                         this.state = { kind: "BROWSERBASE", sessionId, ws, bb };
                         this.browserbaseSessionId = sessionId;
@@ -908,10 +957,7 @@ let V3 = (() => {
                         });
                     }
                     else {
-                        const effectiveTimeoutMs = typeof options?.timeout === "number" && options.timeout > 0
-                            ? options.timeout
-                            : undefined;
-                        const ensureTimeRemaining = (0, timeoutGuard_js_1.createTimeoutGuard)(effectiveTimeoutMs, (ms) => new sdkErrors_js_1.ActTimeoutError(ms));
+                        const ensureTimeRemaining = (0, timeoutGuard_js_1.createTimeoutGuard)(options?.timeout, (ms) => new sdkErrors_js_1.ActTimeoutError(ms));
                         actResult = await this.actHandler.takeDeterministicAction({ ...input, selector }, v3Page, this.domSettleTimeoutMs, this.resolveLlmClient(options?.model), ensureTimeRemaining, options?.variables);
                     }
                     // history: record ObserveResult-based act call
@@ -1132,7 +1178,7 @@ let V3 = (() => {
             try {
                 // Close session file logger
                 try {
-                    await flowLogger_js_1.SessionFileLogger.close();
+                    await FlowLogger_js_1.FlowLogger.close(this.flowLoggerContext);
                 }
                 catch {
                     // ignore
@@ -1168,6 +1214,12 @@ let V3 = (() => {
                 catch {
                     // ignore
                 }
+                try {
+                    await this.eventStore.destroy();
+                }
+                catch {
+                    // ignore
+                }
                 try {
                     this.bus.removeAllListeners();
                 }
@@ -1181,6 +1233,13 @@ let V3 = (() => {
                 V3._instances.delete(this);
             }
         }
+        /**
+         * Resolves the Browserbase API key from options or environment variables.
+         * Returns undefined if no key is found (does not throw).
+         */
+        get browserbaseApiKey() {
+            return this.opts.apiKey || process_1.default.env.BROWSERBASE_API_KEY;
+        }
         /** Guard: ensure Browserbase credentials exist in options. */
         requireBrowserbaseCreds() {
             let { apiKey, projectId } = this.opts;
@@ -1190,17 +1249,13 @@ let V3 = (() => {
             if (!projectId)
                 projectId =
                     process_1.default.env.BROWSERBASE_PROJECT_ID ?? process_1.default.env.BB_PROJECT_ID;
-            if (!apiKey || !projectId) {
-                const missing = [];
-                if (!apiKey)
-                    missing.push("BROWSERBASE_API_KEY");
-                if (!projectId)
-                    missing.push("BROWSERBASE_PROJECT_ID");
-                throw new index_js_1.MissingEnvironmentVariableError(missing.join(", "), "Browserbase");
+            if (!apiKey) {
+                throw new index_js_1.MissingEnvironmentVariableError("BROWSERBASE_API_KEY", "Browserbase");
             }
             // Cache resolved values back into opts for consistency
             this.opts.apiKey = apiKey;
-            this.opts.projectId = projectId;
+            if (projectId)
+                this.opts.projectId = projectId;
             // Informational log
             this.logger({
                 category: "init",
@@ -1342,10 +1397,16 @@ let V3 = (() => {
                 ? this.resolveLlmClient(options.model)
                 : this.llmClient;
             const resolvedExecutionModel = options?.executionModel ?? options?.model;
-            const handler = new v3AgentHandler_js_1.V3AgentHandler(this, this.logger, agentLlmClient, resolvedExecutionModel, options?.systemPrompt, tools, options?.mode);
+            const handler = new v3AgentHandler_js_1.V3AgentHandler(this, this.logger, agentLlmClient, resolvedExecutionModel, options?.systemPrompt, tools, options?.mode, this.isCaptchaAutoSolveEnabled);
             const resolvedOptions = typeof instructionOrOptions === "string"
-                ? { instruction: instructionOrOptions }
-                : instructionOrOptions;
+                ? {
+                    instruction: instructionOrOptions,
+                    toolTimeout: DEFAULT_AGENT_TOOL_TIMEOUT_MS,
+                }
+                : {
+                    ...instructionOrOptions,
+                    toolTimeout: instructionOrOptions.toolTimeout ?? DEFAULT_AGENT_TOOL_TIMEOUT_MS,
+                };
             const callbacksWithSafety = resolvedOptions.callbacks;
             if (callbacksWithSafety?.onSafetyConfirmation) {
                 throw new index_js_1.StagehandInvalidArgumentError('onSafetyConfirmation callback is only supported when using mode: "cua" agents.');
@@ -1425,145 +1486,59 @@ let V3 = (() => {
                     throw new index_js_1.CuaModelRequiredError(index_js_1.AVAILABLE_CUA_MODELS);
                 }
                 const agentConfigSignature = this.agentCache.buildConfigSignature(options);
-                return {
-                    execute: async (instructionOrOptions) => (0, logger_js_2.withInstanceLogContext)(this.instanceId, async () => {
-                        (0, validateExperimentalFeatures_js_1.validateExperimentalFeatures)({
-                            isExperimental: this.experimental,
-                            agentConfig: options,
-                            executeOptions: typeof instructionOrOptions === "object"
-                                ? instructionOrOptions
-                                : null,
-                        });
-                        flowLogger_js_1.SessionFileLogger.logAgentTaskStarted({
-                            invocation: "Agent.execute",
-                            args: [instructionOrOptions],
-                        });
-                        const tools = options?.integrations
-                            ? await (0, utils_js_2.resolveTools)(options.integrations, options.tools)
-                            : (options?.tools ?? {});
-                        const handler = new v3CuaAgentHandler_js_1.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.`,
-                        }, tools);
-                        const resolvedOptions = typeof instructionOrOptions === "string"
-                            ? { instruction: instructionOrOptions }
-                            : instructionOrOptions;
-                        if (resolvedOptions.page) {
-                            const normalizedPage = await this.normalizeToV3Page(resolvedOptions.page);
-                            this.ctx.setActivePage(normalizedPage);
-                        }
-                        const instruction = resolvedOptions.instruction.trim();
-                        const sanitizedOptions = this.agentCache.sanitizeExecuteOptions(resolvedOptions);
-                        const cacheVariables = (0, variables_js_1.flattenVariables)(resolvedOptions.variables);
-                        let cacheContext = null;
-                        if (this.agentCache.shouldAttemptCache(instruction)) {
-                            const startPage = await this.ctx.awaitActivePage();
-                            cacheContext = await this.agentCache.prepareContext({
-                                instruction,
-                                options: sanitizedOptions,
-                                configSignature: agentConfigSignature,
-                                page: startPage,
-                                variables: cacheVariables,
-                            });
-                            if (cacheContext) {
-                                const replayed = await this.agentCache.tryReplay(cacheContext);
-                                if (replayed) {
-                                    flowLogger_js_1.SessionFileLogger.logAgentTaskCompleted({ cacheHit: true });
-                                    return replayed;
-                                }
-                            }
-                        }
-                        let agentSteps = [];
-                        const shouldRecordLocally = !!cacheContext && (!this.apiClient || this.experimental);
-                        if (shouldRecordLocally) {
-                            this.beginAgentReplayRecording();
-                        }
-                        let result;
-                        try {
-                            if (this.apiClient && !this.experimental) {
-                                const page = await this.ctx.awaitActivePage();
-                                result = await this.apiClient.agentExecute(options, resolvedOptions, page.mainFrameId(), !!cacheContext);
-                                if (cacheContext) {
-                                    const transferredEntry = this.apiClient.consumeLatestAgentCacheEntry();
-                                    await this.agentCache.storeTransferredEntry(transferredEntry);
-                                }
-                            }
-                            else {
-                                result = await handler.execute(instructionOrOptions);
-                            }
-                            if (shouldRecordLocally) {
-                                agentSteps = this.endAgentReplayRecording();
-                            }
-                            if (shouldRecordLocally &&
-                                cacheContext &&
-                                result.success &&
-                                agentSteps.length > 0) {
-                                await this.agentCache.store(cacheContext, agentSteps, result);
-                            }
-                            return result;
-                        }
-                        catch (err) {
-                            if (shouldRecordLocally)
-                                this.discardAgentReplayRecording();
-                            throw err;
-                        }
-                        finally {
-                            if (shouldRecordLocally) {
-                                this.discardAgentReplayRecording();
-                            }
-                            flowLogger_js_1.SessionFileLogger.logAgentTaskCompleted();
-                        }
-                    }),
-                };
-            }
-            // Default: AISDK tools-based agent
-            const agentConfigSignature = this.agentCache.buildConfigSignature(options);
-            const isStreaming = options?.stream ?? false;
-            return {
-                execute: async (instructionOrOptions) => (0, logger_js_2.withInstanceLogContext)(this.instanceId, async () => {
+                const execute = async (instructionOrOptions) => (0, logger_js_2.withInstanceLogContext)(this.instanceId, async () => {
                     (0, validateExperimentalFeatures_js_1.validateExperimentalFeatures)({
                         isExperimental: this.experimental,
                         agentConfig: options,
                         executeOptions: typeof instructionOrOptions === "object"
                             ? instructionOrOptions
                             : null,
-                        isStreaming,
                     });
-                    flowLogger_js_1.SessionFileLogger.logAgentTaskStarted({
-                        invocation: "Agent.execute",
-                        args: [instructionOrOptions],
-                    });
-                    // Streaming mode
-                    if (isStreaming) {
-                        const { handler, resolvedOptions, cacheContext, llmClient } = await this.prepareAgentExecution(options, instructionOrOptions, agentConfigSignature);
+                    const tools = options?.integrations
+                        ? await (0, utils_js_2.resolveTools)(options.integrations, options.tools)
+                        : (options?.tools ?? {});
+                    const handler = new v3CuaAgentHandler_js_1.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.`) +
+                            (this.isCaptchaAutoSolveEnabled
+                                ? captchaSolver_js_1.CAPTCHA_CUA_SYSTEM_PROMPT_NOTE
+                                : ""),
+                    }, tools);
+                    const resolvedOptions = typeof instructionOrOptions === "string"
+                        ? {
+                            instruction: instructionOrOptions,
+                            toolTimeout: DEFAULT_AGENT_TOOL_TIMEOUT_MS,
+                        }
+                        : {
+                            ...instructionOrOptions,
+                            toolTimeout: instructionOrOptions.toolTimeout ??
+                                DEFAULT_AGENT_TOOL_TIMEOUT_MS,
+                        };
+                    if (resolvedOptions.page) {
+                        const normalizedPage = await this.normalizeToV3Page(resolvedOptions.page);
+                        this.ctx.setActivePage(normalizedPage);
+                    }
+                    const instruction = resolvedOptions.instruction.trim();
+                    const sanitizedOptions = this.agentCache.sanitizeExecuteOptions(resolvedOptions);
+                    const cacheVariables = (0, variables_js_1.flattenVariables)(resolvedOptions.variables);
+                    let cacheContext = null;
+                    if (this.agentCache.shouldAttemptCache(instruction)) {
+                        const startPage = await this.ctx.awaitActivePage();
+                        cacheContext = await this.agentCache.prepareContext({
+                            instruction,
+                            options: sanitizedOptions,
+                            configSignature: agentConfigSignature,
+                            page: startPage,
+                            variables: cacheVariables,
+                        });
                         if (cacheContext) {
-                            const replayed = await this.agentCache.tryReplayAsStream(cacheContext, llmClient);
+                            const replayed = await this.agentCache.tryReplay(cacheContext);
                             if (replayed) {
-                                flowLogger_js_1.SessionFileLogger.logAgentTaskCompleted({ cacheHit: true });
                                 return replayed;
                             }
                         }
-                        const streamResult = await handler.stream(resolvedOptions);
-                        if (cacheContext) {
-                            const wrappedStream = this.agentCache.wrapStreamForCaching(cacheContext, streamResult, () => this.beginAgentReplayRecording(), () => this.endAgentReplayRecording(), () => this.discardAgentReplayRecording());
-                            // Log completion when stream is returned (stream completes asynchronously)
-                            flowLogger_js_1.SessionFileLogger.logAgentTaskCompleted();
-                            return wrappedStream;
-                        }
-                        // Log completion when stream is returned (stream completes asynchronously)
-                        flowLogger_js_1.SessionFileLogger.logAgentTaskCompleted();
-                        return streamResult;
-                    }
-                    // Non-streaming mode (default)
-                    const { handler, resolvedOptions, cacheContext, llmClient } = await this.prepareAgentExecution(options, instructionOrOptions, agentConfigSignature);
-                    if (cacheContext) {
-                        const replayed = await this.agentCache.tryReplay(cacheContext, llmClient);
-                        if (replayed) {
-                            flowLogger_js_1.SessionFileLogger.logAgentTaskCompleted({ cacheHit: true });
-                            return replayed;
-                        }
                     }
                     let agentSteps = [];
                     const shouldRecordLocally = !!cacheContext && (!this.apiClient || this.experimental);
@@ -1574,14 +1549,14 @@ let V3 = (() => {
                     try {
                         if (this.apiClient && !this.experimental) {
                             const page = await this.ctx.awaitActivePage();
-                            result = await this.apiClient.agentExecute(options ?? {}, resolvedOptions, page.mainFrameId(), !!cacheContext);
+                            result = await this.apiClient.agentExecute(options, resolvedOptions, page.mainFrameId(), !!cacheContext);
                             if (cacheContext) {
                                 const transferredEntry = this.apiClient.consumeLatestAgentCacheEntry();
                                 await this.agentCache.storeTransferredEntry(transferredEntry);
                             }
                         }
                         else {
-                            result = await handler.execute(resolvedOptions);
+                            result = await handler.execute(instructionOrOptions);
                         }
                         if (shouldRecordLocally) {
                             agentSteps = this.endAgentReplayRecording();
@@ -1603,9 +1578,96 @@ let V3 = (() => {
                         if (shouldRecordLocally) {
                             this.discardAgentReplayRecording();
                         }
-                        flowLogger_js_1.SessionFileLogger.logAgentTaskCompleted();
                     }
-                }),
+                });
+                return {
+                    execute: FlowLogger_js_1.FlowLogger.wrapWithLogging({
+                        eventType: "AgentExecute",
+                        context: this.flowLoggerContext,
+                    })(execute),
+                };
+            }
+            // Default: AISDK tools-based agent
+            const agentConfigSignature = this.agentCache.buildConfigSignature(options);
+            const isStreaming = options?.stream ?? false;
+            const execute = async (instructionOrOptions) => (0, logger_js_2.withInstanceLogContext)(this.instanceId, async () => {
+                (0, validateExperimentalFeatures_js_1.validateExperimentalFeatures)({
+                    isExperimental: this.experimental,
+                    agentConfig: options,
+                    executeOptions: typeof instructionOrOptions === "object"
+                        ? instructionOrOptions
+                        : null,
+                    isStreaming,
+                });
+                // Streaming mode
+                if (isStreaming) {
+                    const { handler, resolvedOptions, cacheContext, llmClient } = await this.prepareAgentExecution(options, instructionOrOptions, agentConfigSignature);
+                    if (cacheContext) {
+                        const replayed = await this.agentCache.tryReplayAsStream(cacheContext, llmClient);
+                        if (replayed) {
+                            return replayed;
+                        }
+                    }
+                    const streamResult = await handler.stream(resolvedOptions);
+                    if (cacheContext) {
+                        const wrappedStream = this.agentCache.wrapStreamForCaching(cacheContext, streamResult, () => this.beginAgentReplayRecording(), () => this.endAgentReplayRecording(), () => this.discardAgentReplayRecording());
+                        return wrappedStream;
+                    }
+                    return streamResult;
+                }
+                // Non-streaming mode (default)
+                const { handler, resolvedOptions, cacheContext, llmClient } = await this.prepareAgentExecution(options, instructionOrOptions, agentConfigSignature);
+                if (cacheContext) {
+                    const replayed = await this.agentCache.tryReplay(cacheContext, llmClient);
+                    if (replayed) {
+                        return replayed;
+                    }
+                }
+                let agentSteps = [];
+                const shouldRecordLocally = !!cacheContext && (!this.apiClient || this.experimental);
+                if (shouldRecordLocally) {
+                    this.beginAgentReplayRecording();
+                }
+                let result;
+                try {
+                    if (this.apiClient && !this.experimental) {
+                        const page = await this.ctx.awaitActivePage();
+                        result = await this.apiClient.agentExecute(options ?? {}, resolvedOptions, page.mainFrameId(), !!cacheContext);
+                        if (cacheContext) {
+                            const transferredEntry = this.apiClient.consumeLatestAgentCacheEntry();
+                            await this.agentCache.storeTransferredEntry(transferredEntry);
+                        }
+                    }
+                    else {
+                        result = await handler.execute(resolvedOptions);
+                    }
+                    if (shouldRecordLocally) {
+                        agentSteps = this.endAgentReplayRecording();
+                    }
+                    if (shouldRecordLocally &&
+                        cacheContext &&
+                        result.success &&
+                        agentSteps.length > 0) {
+                        await this.agentCache.store(cacheContext, agentSteps, result);
+                    }
+                    return result;
+                }
+                catch (err) {
+                    if (shouldRecordLocally)
+                        this.discardAgentReplayRecording();
+                    throw err;
+                }
+                finally {
+                    if (shouldRecordLocally) {
+                        this.discardAgentReplayRecording();
+                    }
+                }
+            });
+            return {
+                execute: FlowLogger_js_1.FlowLogger.wrapWithLogging({
+                    eventType: "AgentExecute",
+                    context: this.flowLoggerContext,
+                })(execute),
             };
         }
     };