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

package/dist/cjs/lib/v3/flowLogger.d.ts

@@ -1,76 +1,124 @@
-import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import pino from "pino";
 import type { LanguageModelMiddleware } from "ai";
-export type FlowEventData = Record<string, unknown>;
-export type FlowEventInput = Omit<FlowEvent, "eventId" | "createdAt" | "sessionId" | "eventParentIds" | "data"> & {
-    eventId?: string;
-    eventIdSuffix?: string;
-    createdAt?: string;
-    sessionId?: string;
-    eventParentIds?: string[];
-    data?: FlowEventData;
-};
-export declare class FlowEvent {
-    static createEventId(eventIdSuffix: string): string;
-    eventType: string;
-    eventId: string;
-    eventParentIds: string[];
-    createdAt: string;
-    sessionId: string;
-    data: FlowEventData;
-    constructor(input: FlowEventInput);
+import type { V3Options } from "./types/public/index.js";
+interface FlowLoggerMetrics {
+    taskStartTime?: number;
+    stepStartTime?: number;
+    actionStartTime?: number;
+    llmRequests: number;
+    llmInputTokens: number;
+    llmOutputTokens: number;
+    cdpEvents: number;
 }
 export interface FlowLoggerContext {
+    logger: pino.Logger;
+    metrics: FlowLoggerMetrics;
     sessionId: string;
-    eventBus: EventEmitter;
-    parentEvents: FlowEvent[];
+    sessionDir: string;
+    configDir: string;
+    initPromise: Promise<void>;
+    initialized: boolean;
+    taskId: string | null;
+    stepId: string | null;
+    stepLabel: string | null;
+    actionId: string | null;
+    actionLabel: string | null;
+    fileStreams: {
+        agent: fs.WriteStream | null;
+        stagehand: fs.WriteStream | null;
+        understudy: fs.WriteStream | null;
+        cdp: fs.WriteStream | null;
+        llm: fs.WriteStream | null;
+        jsonl: fs.WriteStream | null;
+    };
 }
-type AsyncOriginalMethod<TArgs extends unknown[] = unknown[], TResult = unknown, TThis = unknown> = (this: TThis, ...args: TArgs) => Promise<TResult>;
-type FlowLoggerLogOptions = FlowEventInput & {
-    context?: FlowLoggerContext;
-};
-export declare class FlowLogger {
-    private static cloneContext;
-    private static emit;
-    private static runWithAutoStatusEventLogging;
+/**
+ * Get the config directory. Returns empty string if logging is disabled.
+ */
+export declare function getConfigDir(): string;
+/**
+ * Format a prompt preview from LLM messages for logging.
+ * Returns format like: "some text... +{5.8kb image} +{schema} +{12 tools}"
+ */
+export declare function formatLlmPromptPreview(messages: Array<{
+    role: string;
+    content: unknown;
+}>, options?: {
+    toolCount?: number;
+    hasSchema?: boolean;
+}): string | undefined;
+/**
+ * Extract a text preview from CUA-style messages.
+ * Accepts various message formats (Anthropic, OpenAI, Google).
+ */
+export declare function formatCuaPromptPreview(messages: unknown[], maxLen?: number): string | undefined;
+/** Format CUA response output for logging */
+export declare function formatCuaResponsePreview(output: unknown, maxLen?: number): string;
+export declare class SessionFileLogger {
     /**
      * Initialize a new logging context. Call this at the start of a session.
+     * If BROWSERBASE_CONFIG_DIR is not set, logging is disabled.
+     */
+    static init(sessionId: string, v3Options?: V3Options): void;
+    private static initAsync;
+    static close(): Promise<void>;
+    static get sessionId(): string | null;
+    static get sessionDir(): string | null;
+    /**
+     * Get the current logger context object.
+     */
+    static getContext(): FlowLoggerContext | null;
+    /**
+     * Start a new task and log it.
      */
-    static init(sessionId: string, eventBus: EventEmitter): FlowLoggerContext;
-    static close(context?: FlowLoggerContext | null): Promise<void>;
-    static get currentContext(): FlowLoggerContext;
-    static wrapWithLogging<TMethod extends AsyncOriginalMethod>(options: FlowLoggerLogOptions): <TWrappedMethod extends AsyncOriginalMethod<Parameters<TMethod>, Awaited<ReturnType<TMethod>>, ThisParameterType<TMethod>>>(originalMethod: TWrappedMethod) => TWrappedMethod;
-    static runWithLogging<TMethod extends AsyncOriginalMethod>(options: FlowLoggerLogOptions, originalMethod: TMethod, params: Readonly<Parameters<TMethod>>): Promise<Awaited<ReturnType<TMethod>>>;
-    static runWithLogging<TResult>(options: FlowLoggerLogOptions, originalMethod: AsyncOriginalMethod<[], TResult>, params: ReadonlyArray<unknown>): Promise<Awaited<TResult>>;
-    private static readonly NOISY_CDP_EVENTS;
+    static logAgentTaskStarted({ invocation, args, }: {
+        invocation: string;
+        args?: unknown | unknown[];
+    }): void;
+    /**
+     * Log task completion with metrics summary.
+     */
+    static logAgentTaskCompleted(options?: {
+        cacheHit?: boolean;
+    }): void;
+    static logStagehandStepEvent({ invocation, args, label, }: {
+        invocation: string;
+        args?: unknown | unknown[];
+        label: string;
+    }): string;
+    static logStagehandStepCompleted(): void;
+    static logUnderstudyActionEvent({ actionType, target, args, }: {
+        actionType: string;
+        target?: string;
+        args?: unknown | unknown[];
+    }): string;
+    static logUnderstudyActionCompleted(): void;
     private static logCdpEvent;
-    static logCdpCallEvent(context: FlowLoggerContext, data: {
+    static logCdpCallEvent(data: {
         method: string;
         params?: object;
         targetId?: string | null;
-    }): FlowEvent | null;
-    static logCdpResponseEvent(context: FlowLoggerContext, parentEvent: Pick<FlowEvent, "eventId" | "eventParentIds">, data: {
-        method: string;
-        result?: unknown;
-        error?: string;
-        targetId?: string | null;
-    }): void;
-    static logCdpMessageEvent(context: FlowLoggerContext, parentEvent: Pick<FlowEvent, "eventId" | "eventParentIds">, data: {
+    }, ctx?: FlowLoggerContext | null): void;
+    static logCdpMessageEvent(data: {
         method: string;
         params?: unknown;
         targetId?: string | null;
-    }): void;
+    }, ctx?: FlowLoggerContext | null): void;
     static logLlmRequest({ requestId, model, prompt, }: {
         requestId: string;
         model: string;
+        operation: string;
         prompt?: string;
-    }): void;
+    }, explicitCtx?: FlowLoggerContext | null): void;
     static logLlmResponse({ requestId, model, output, inputTokens, outputTokens, }: {
         requestId: string;
         model: string;
+        operation: string;
         output?: string;
         inputTokens?: number;
         outputTokens?: number;
-    }): void;
+    }, explicitCtx?: FlowLoggerContext | null): void;
     /**
      * Create middleware for wrapping language models with LLM call logging.
      * Returns a no-op middleware when logging is disabled.
@@ -78,21 +126,14 @@ export declare class FlowLogger {
     static createLlmLoggingMiddleware(modelId: string): Pick<LanguageModelMiddleware, "wrapGenerate">;
 }
 /**
- * Format a prompt summary from LLM messages for logging.
- * Returns format like: "some text +{5.8kb image} +{schema} +{12 tools}"
+ * Method decorator for logging understudy actions with automatic start/complete.
+ * Logs all arguments automatically. No-op when CONFIG_DIR is empty.
  */
-export declare function extractLlmPromptSummary(messages: Array<{
-    role: string;
-    content: unknown;
-}>, options?: {
-    toolCount?: number;
-    hasSchema?: boolean;
-}): string | undefined;
+export declare function logAction(actionType: string): <T extends (...args: never[]) => Promise<unknown>>(originalMethod: T) => T;
 /**
- * Extract a text summary from CUA-style messages.
- * Accepts various message formats (Anthropic, OpenAI, Google).
+ * Method decorator for logging Stagehand step events (act, extract, observe).
+ * Only adds logging - does NOT wrap with withInstanceLogContext (caller handles that).
+ * No-op when CONFIG_DIR is empty.
  */
-export declare function extractLlmCuaPromptSummary(messages: unknown[]): string | undefined;
-/** Format a CUA response summary for logging */
-export declare function extractLlmCuaResponseSummary(output: unknown): string;
+export declare function logStagehandStep(invocation: string, label: string): <T extends (...args: never[]) => Promise<unknown>>(originalMethod: T) => T;
 export {};