@browserbasehq/orca 3.2.0-preview.2 → 3.2.0-preview.3

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

@@ -5,7 +5,6 @@ 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 { V3Context } from "./understudy/context.js";
-import { type FlowLoggerContext } from "./flowLogger.js";
 /**
  * V3
  *
@@ -71,8 +70,6 @@ export declare class V3 {
     private stagehandLogger;
     private _history;
     private readonly instanceId;
-    private readonly sessionId;
-    readonly flowLoggerContext: FlowLoggerContext;
     private static _processGuardsInstalled;
     private static _instances;
     private cacheStorage;
@@ -81,8 +78,6 @@ export declare class V3 {
     private apiClient;
     private keepAlive?;
     private shutdownSupervisor;
-    private detachEventStoreListener;
-    private withLoggingContext;
     stagehandMetrics: StagehandMetrics;
     constructor(opts: V3Options);
     /**

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

@@ -63,8 +63,7 @@ import { resolveModel } from "../modelUtils.js";
 import { StagehandAPIClient } from "./api.js";
 import { validateExperimentalFeatures } from "./agent/utils/validateExperimentalFeatures.js";
 import { flattenVariables } from "./agent/utils/variables.js";
-import { FlowLogger } from "./flowLogger.js";
-import { getEventStore } from "./eventStore.js";
+import { SessionFileLogger, logStagehandStep } from "./flowLogger.js";
 import { createTimeoutGuard } from "./handlers/handlerUtils/timeoutGuard.js";
 import { ActTimeoutError } from "./types/public/sdkErrors.js";
 const DEFAULT_MODEL_NAME = "openai/gpt-4.1-mini";
@@ -112,18 +111,9 @@ let V3 = (() => {
     return class V3 {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
-            _act_decorators = [FlowLogger.wrapWithLogging({
-                    eventType: "StagehandAct",
-                    eventIdSuffix: "4",
-                })];
-            _extract_decorators = [FlowLogger.wrapWithLogging({
-                    eventType: "StagehandExtract",
-                    eventIdSuffix: "4",
-                })];
-            _observe_decorators = [FlowLogger.wrapWithLogging({
-                    eventType: "StagehandObserve",
-                    eventIdSuffix: "4",
-                })];
+            _act_decorators = [logStagehandStep("Stagehand.act", "ACT")];
+            _extract_decorators = [logStagehandStep("Stagehand.extract", "EXTRACT")];
+            _observe_decorators = [logStagehandStep("Stagehand.observe", "OBSERVE")];
             __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);
@@ -208,8 +198,6 @@ let V3 = (() => {
         stagehandLogger;
         _history = [];
         instanceId;
-        sessionId;
-        flowLoggerContext;
         static _processGuardsInstalled = false;
         static _instances = new Set();
         cacheStorage;
@@ -218,10 +206,6 @@ let V3 = (() => {
         apiClient = null;
         keepAlive;
         shutdownSupervisor = null;
-        detachEventStoreListener = null;
-        withLoggingContext(fn) {
-            return withInstanceLogContext(this.instanceId, fn);
-        }
         stagehandMetrics = {
             actPromptTokens: 0,
             actCompletionTokens: 0,
@@ -253,7 +237,6 @@ let V3 = (() => {
             this.externalLogger = opts.logger;
             this.verbose = opts.verbose ?? 1;
             this.instanceId = uuidv7();
-            this.sessionId = opts.sessionId ?? this.instanceId;
             this.keepAlive =
                 opts.keepAlive ?? opts.browserbaseSessionCreateParams?.keepAlive;
             // Create per-instance StagehandLogger (handles usePino, verbose, externalLogger)
@@ -346,9 +329,8 @@ let V3 = (() => {
                 act: this.act.bind(this),
             });
             this.opts = opts;
-            void getEventStore().initializeSession(this.sessionId, opts);
-            this.flowLoggerContext = FlowLogger.init(this.sessionId, this.bus);
-            this.detachEventStoreListener = getEventStore().attachBus(this.sessionId, this.bus);
+            // Initialize session file logger
+            SessionFileLogger.init(this.instanceId, opts);
             // Track instance for global process guard handling
             V3._instances.add(this);
         }
@@ -555,7 +537,7 @@ let V3 = (() => {
          */
         async init() {
             try {
-                return await this.withLoggingContext(async () => {
+                return await withInstanceLogContext(this.instanceId, async () => {
                     this.actHandler = new ActHandler(this.llmClient, this.modelName, this.modelClientOptions, (model) => this.resolveLlmClient(model), this.opts.systemPrompt ?? "", this.logInferenceToFile, this.opts.selfHeal ?? true, (functionName, promptTokens, completionTokens, reasoningTokens, cachedInputTokens, inferenceTimeMs) => this.updateMetrics(functionName, promptTokens, completionTokens, reasoningTokens, cachedInputTokens, inferenceTimeMs), this.domSettleTimeoutMs);
                     this.extractHandler = new ExtractHandler(this.llmClient, this.modelName, this.modelClientOptions, (model) => this.resolveLlmClient(model), this.opts.systemPrompt ?? "", this.logInferenceToFile, this.experimental, (functionName, promptTokens, completionTokens, reasoningTokens, cachedInputTokens, inferenceTimeMs) => this.updateMetrics(functionName, promptTokens, completionTokens, reasoningTokens, cachedInputTokens, inferenceTimeMs));
                     this.observeHandler = new ObserveHandler(this.llmClient, this.modelName, this.modelClientOptions, (model) => this.resolveLlmClient(model), this.opts.systemPrompt ?? "", this.logInferenceToFile, this.experimental, (functionName, promptTokens, completionTokens, reasoningTokens, cachedInputTokens, inferenceTimeMs) => this.updateMetrics(functionName, promptTokens, completionTokens, reasoningTokens, cachedInputTokens, inferenceTimeMs));
@@ -589,7 +571,9 @@ let V3 = (() => {
                                 env: "LOCAL",
                                 cdpHeaders: lbo.cdpHeaders,
                             });
-                            this.ctx.conn.flowLoggerContext = this.flowLoggerContext;
+                            const logCtx = SessionFileLogger.getContext();
+                            this.ctx.conn.cdpLogger = (info) => SessionFileLogger.logCdpCallEvent(info, logCtx);
+                            this.ctx.conn.cdpEventLogger = (info) => SessionFileLogger.logCdpMessageEvent(info, logCtx);
                             this.ctx.conn.onTransportClosed(this._onCdpClosed);
                             this.state = {
                                 kind: "LOCAL",
@@ -685,7 +669,9 @@ let V3 = (() => {
                             env: "LOCAL",
                             localBrowserLaunchOptions: lbo,
                         });
-                        this.ctx.conn.flowLoggerContext = this.flowLoggerContext;
+                        const logCtx = SessionFileLogger.getContext();
+                        this.ctx.conn.cdpLogger = (info) => SessionFileLogger.logCdpCallEvent(info, logCtx);
+                        this.ctx.conn.cdpEventLogger = (info) => SessionFileLogger.logCdpMessageEvent(info, logCtx);
                         this.ctx.conn.onTransportClosed(this._onCdpClosed);
                         this.state = {
                             kind: "LOCAL",
@@ -767,7 +753,9 @@ let V3 = (() => {
                             env: "BROWSERBASE",
                             apiClient: this.apiClient,
                         });
-                        this.ctx.conn.flowLoggerContext = this.flowLoggerContext;
+                        const logCtx = SessionFileLogger.getContext();
+                        this.ctx.conn.cdpLogger = (info) => SessionFileLogger.logCdpCallEvent(info, logCtx);
+                        this.ctx.conn.cdpEventLogger = (info) => SessionFileLogger.logCdpMessageEvent(info, logCtx);
                         this.ctx.conn.onTransportClosed(this._onCdpClosed);
                         this.state = { kind: "BROWSERBASE", sessionId, ws, bb };
                         this.browserbaseSessionId = sessionId;
@@ -829,13 +817,6 @@ let V3 = (() => {
                         // ignore cleanup errors
                     }
                 }
-                try {
-                    this.detachEventStoreListener?.();
-                    this.detachEventStoreListener = null;
-                }
-                catch {
-                    // ignore cleanup errors
-                }
                 throw error;
             }
         }
@@ -879,7 +860,7 @@ let V3 = (() => {
             this.browserbaseDebugUrl = undefined;
         }
         async act(input, options) {
-            return await this.withLoggingContext(async () => {
+            return await withInstanceLogContext(this.instanceId, async () => {
                 if (!this.actHandler)
                     throw new StagehandNotInitializedError("act()");
                 let actResult;
@@ -963,7 +944,7 @@ let V3 = (() => {
             });
         }
         async extract(a, b, c) {
-            return await this.withLoggingContext(async () => {
+            return await withInstanceLogContext(this.instanceId, async () => {
                 if (!this.extractHandler) {
                     throw new StagehandNotInitializedError("extract()");
                 }
@@ -1031,7 +1012,7 @@ let V3 = (() => {
             });
         }
         async observe(a, b) {
-            return await this.withLoggingContext(async () => {
+            return await withInstanceLogContext(this.instanceId, async () => {
                 if (!this.observeHandler) {
                     throw new StagehandNotInitializedError("observe()");
                 }
@@ -1117,7 +1098,7 @@ let V3 = (() => {
             try {
                 // Close session file logger
                 try {
-                    await FlowLogger.close(this.flowLoggerContext);
+                    await SessionFileLogger.close();
                 }
                 catch {
                     // ignore
@@ -1153,13 +1134,6 @@ let V3 = (() => {
                 catch {
                     // ignore
                 }
-                try {
-                    this.detachEventStoreListener?.();
-                    this.detachEventStoreListener = null;
-                }
-                catch {
-                    // ignore
-                }
                 try {
                     this.bus.removeAllListeners();
                 }
@@ -1426,59 +1400,152 @@ let V3 = (() => {
                     throw new CuaModelRequiredError(AVAILABLE_CUA_MODELS);
                 }
                 const agentConfigSignature = this.agentCache.buildConfigSignature(options);
-                const execute = FlowLogger.wrapWithLogging({
-                    eventType: "AgentExecute",
-                    eventIdSuffix: "3",
-                })(async (instructionOrOptions) => this.withLoggingContext(async () => {
+                return {
+                    execute: async (instructionOrOptions) => withInstanceLogContext(this.instanceId, async () => {
+                        validateExperimentalFeatures({
+                            isExperimental: this.experimental,
+                            agentConfig: options,
+                            executeOptions: typeof instructionOrOptions === "object"
+                                ? instructionOrOptions
+                                : null,
+                        });
+                        SessionFileLogger.logAgentTaskStarted({
+                            invocation: "Agent.execute",
+                            args: [instructionOrOptions],
+                        });
+                        const tools = options?.integrations
+                            ? await resolveTools(options.integrations, options.tools)
+                            : (options?.tools ?? {});
+                        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.`,
+                        }, 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 = 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) {
+                                    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();
+                            }
+                            SessionFileLogger.logAgentTaskCompleted();
+                        }
+                    }),
+                };
+            }
+            // Default: AISDK tools-based agent
+            const agentConfigSignature = this.agentCache.buildConfigSignature(options);
+            const isStreaming = options?.stream ?? false;
+            return {
+                execute: async (instructionOrOptions) => withInstanceLogContext(this.instanceId, async () => {
                     validateExperimentalFeatures({
                         isExperimental: this.experimental,
                         agentConfig: options,
                         executeOptions: typeof instructionOrOptions === "object"
                             ? instructionOrOptions
                             : null,
+                        isStreaming,
                     });
-                    const tools = options?.integrations
-                        ? await resolveTools(options.integrations, options.tools)
-                        : (options?.tools ?? {});
-                    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.`,
-                    }, 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 = 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,
-                        });
+                    SessionFileLogger.logAgentTaskStarted({
+                        invocation: "Agent.execute",
+                        args: [instructionOrOptions],
+                    });
+                    // Streaming mode
+                    if (isStreaming) {
+                        const { handler, resolvedOptions, cacheContext, llmClient } = await this.prepareAgentExecution(options, instructionOrOptions, agentConfigSignature);
                         if (cacheContext) {
-                            const replayed = await this.agentCache.tryReplay(cacheContext);
+                            const replayed = await this.agentCache.tryReplayAsStream(cacheContext, llmClient);
                             if (replayed) {
+                                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)
+                            SessionFileLogger.logAgentTaskCompleted();
+                            return wrappedStream;
+                        }
+                        // Log completion when stream is returned (stream completes asynchronously)
+                        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) {
+                            SessionFileLogger.logAgentTaskCompleted({ cacheHit: true });
+                            return replayed;
+                        }
                     }
                     let agentSteps = [];
                     const shouldRecordLocally = !!cacheContext && (!this.apiClient || this.experimental);
@@ -1489,14 +1556,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(instructionOrOptions);
+                            result = await handler.execute(resolvedOptions);
                         }
                         if (shouldRecordLocally) {
                             agentSteps = this.endAgentReplayRecording();
@@ -1518,93 +1585,9 @@ let V3 = (() => {
                         if (shouldRecordLocally) {
                             this.discardAgentReplayRecording();
                         }
+                        SessionFileLogger.logAgentTaskCompleted();
                     }
-                }));
-                return {
-                    execute,
-                };
-            }
-            // Default: AISDK tools-based agent
-            const agentConfigSignature = this.agentCache.buildConfigSignature(options);
-            const isStreaming = options?.stream ?? false;
-            const execute = FlowLogger.wrapWithLogging({
-                eventType: "AgentExecute",
-                eventIdSuffix: "3",
-            })(async (instructionOrOptions) => this.withLoggingContext(async () => {
-                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,
+                }),
             };
         }
     };