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

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

@@ -1,242 +1,724 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import fs from "node:fs";
+import { Writable } from "node:stream";
 import { v7 as uuidv7 } from "uuid";
-export class FlowEvent {
-    static createEventId(eventIdSuffix) {
-        const rawEventId = uuidv7();
-        return `${rawEventId.slice(0, -1)}${eventIdSuffix || "0"}`;
-    }
-    // base required fields for all events:
-    eventType;
-    eventId;
-    eventParentIds;
-    createdAt;
-    sessionId;
-    data; // event payload (e.g. params, action, result, error, etc.)
-    constructor(input) {
-        if (!input.sessionId) {
-            throw new Error("FlowEvent.sessionId is required.");
+import path from "node:path";
+import pino from "pino";
+// =============================================================================
+// Constants
+// =============================================================================
+const MAX_LINE_LENGTH = 160;
+// Flow logging config dir - empty string disables logging entirely
+const CONFIG_DIR = process.env.BROWSERBASE_CONFIG_DIR || "";
+const NOISY_CDP_EVENTS = new Set([
+    "Target.targetInfoChanged",
+    "Runtime.executionContextCreated",
+    "Runtime.executionContextDestroyed",
+    "Runtime.executionContextsCleared",
+    "Page.lifecycleEvent",
+    "Network.dataReceived",
+    "Network.loadingFinished",
+    "Network.requestWillBeSentExtraInfo",
+    "Network.responseReceivedExtraInfo",
+    "Network.requestWillBeSent",
+    "Network.responseReceived",
+]);
+const loggerContext = new AsyncLocalStorage();
+// =============================================================================
+// Formatting Utilities (used by pretty streams)
+// =============================================================================
+/** Calculate base64 data size in KB */
+const dataToKb = (data) => ((data.length * 0.75) / 1024).toFixed(1);
+/** Truncate CDP IDs: frameId:363F03EB...EF8 → frameId:363F…5EF8 */
+function truncateCdpIds(value) {
+    return value.replace(/([iI]d:?"?)([0-9A-F]{32})(?="?[,})\s]|$)/g, (_, pre, id) => `${pre}${id.slice(0, 4)}…${id.slice(-4)}`);
+}
+/** Truncate line showing start...end */
+function truncateLine(value, maxLen) {
+    const collapsed = value.replace(/\s+/g, " ");
+    if (collapsed.length <= maxLen)
+        return collapsed;
+    const endLen = Math.floor(maxLen * 0.3);
+    const startLen = maxLen - endLen - 1;
+    return `${collapsed.slice(0, startLen)}…${collapsed.slice(-endLen)}`;
+}
+function formatValue(value) {
+    if (typeof value === "string")
+        return `'${value}'`;
+    if (value == null || typeof value !== "object")
+        return String(value);
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "[unserializable]";
+    }
+}
+function formatArgs(args) {
+    if (args === undefined)
+        return "";
+    return (Array.isArray(args) ? args : [args])
+        .filter((e) => e !== undefined)
+        .map(formatValue)
+        .filter((e) => e.length > 0)
+        .join(", ");
+}
+const shortId = (id) => id ? id.slice(-4) : "-";
+function formatTag(label, id, icon) {
+    return id ? `[${icon} #${shortId(id)}${label ? " " + label : ""}]` : "⤑";
+}
+let nonce = 0;
+function formatTimestamp() {
+    const d = new Date();
+    const pad = (n, w = 2) => String(n).padStart(w, "0");
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}${pad(nonce++ % 100)}`;
+}
+const SENSITIVE_KEYS = /apikey|api_key|key|secret|token|password|passwd|pwd|credential|auth/i;
+function sanitizeOptions(options) {
+    const sanitize = (obj) => {
+        if (typeof obj !== "object" || obj === null)
+            return obj;
+        if (Array.isArray(obj))
+            return obj.map(sanitize);
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            result[key] = SENSITIVE_KEYS.test(key) ? "******" : sanitize(value);
+        }
+        return result;
+    };
+    return sanitize({ ...options });
+}
+/** Remove unescaped quotes for cleaner log output */
+function removeQuotes(str) {
+    return str
+        .replace(/([^\\])["']/g, "$1")
+        .replace(/^["']|["']$/g, "")
+        .trim();
+}
+// =============================================================================
+// Pretty Formatting (converts FlowEvent to human-readable log line)
+// =============================================================================
+function prettifyEvent(event) {
+    const parts = [];
+    // Build context tags - always add parent span tags (formatTag returns ⤑ for null IDs)
+    if (event.category === "AgentTask") {
+        parts.push(formatTag("", event.taskId, "🅰"));
+    }
+    else if (event.category === "StagehandStep") {
+        parts.push(formatTag("", event.taskId, "🅰"));
+        parts.push(formatTag(event.stepLabel, event.stepId, "🆂"));
+    }
+    else if (event.category === "UnderstudyAction") {
+        parts.push(formatTag("", event.taskId, "🅰"));
+        parts.push(formatTag(event.stepLabel, event.stepId, "🆂"));
+        parts.push(formatTag(event.actionLabel, event.actionId, "🆄"));
+    }
+    else if (event.category === "CDP") {
+        parts.push(formatTag("", event.taskId, "🅰"));
+        parts.push(formatTag(event.stepLabel, event.stepId, "🆂"));
+        parts.push(formatTag(event.actionLabel, event.actionId, "🆄"));
+        parts.push(formatTag("CDP", event.targetId, "🅲"));
+    }
+    else if (event.category === "LLM") {
+        parts.push(formatTag("", event.taskId, "🅰"));
+        parts.push(formatTag(event.stepLabel, event.stepId, "🆂"));
+        parts.push(formatTag("LLM", event.requestId, "🧠"));
+    }
+    // Build details based on event type
+    let details = "";
+    const argsStr = event.params ? formatArgs(event.params) : "";
+    if (event.category === "AgentTask") {
+        if (event.event === "started") {
+            details = `▷ ${event.method}(${argsStr})`;
+        }
+        else if (event.event === "completed") {
+            const m = event.metrics;
+            const durationSec = m?.durationMs
+                ? (m.durationMs / 1000).toFixed(1)
+                : "?";
+            const llmStats = `${m?.llmRequests ?? 0} LLM calls ꜛ${m?.inputTokens ?? 0} ꜜ${m?.outputTokens ?? 0} tokens`;
+            const cdpStats = `${m?.cdpEvents ?? 0} CDP msgs`;
+            details = `✓ Agent.execute() DONE in ${durationSec}s | ${llmStats} | ${cdpStats}`;
+        }
+    }
+    else if (event.category === "StagehandStep") {
+        if (event.event === "started") {
+            details = `▷ ${event.method}(${argsStr})`;
+        }
+        else if (event.event === "completed") {
+            const durationSec = event.metrics?.durationMs
+                ? (event.metrics.durationMs / 1000).toFixed(2)
+                : "?";
+            details = `✓ ${event.stepLabel || "STEP"} completed in ${durationSec}s`;
+        }
+    }
+    else if (event.category === "UnderstudyAction") {
+        if (event.event === "started") {
+            details = `▷ ${event.method}(${argsStr})`;
+        }
+        else if (event.event === "completed") {
+            const durationSec = event.metrics?.durationMs
+                ? (event.metrics.durationMs / 1000).toFixed(2)
+                : "?";
+            details = `✓ ${event.actionLabel || "ACTION"} completed in ${durationSec}s`;
+        }
+    }
+    else if (event.category === "CDP") {
+        const icon = event.event === "call" ? "⏵" : "⏴";
+        details = `${icon} ${event.method}(${argsStr})`;
+    }
+    else if (event.category === "LLM") {
+        if (event.event === "request") {
+            const promptStr = event.prompt ? " " + String(event.prompt) : "";
+            details = `${event.model} ⏴${promptStr}`;
         }
-        if (input.eventId &&
-            input.eventIdSuffix &&
-            !input.eventId.endsWith(input.eventIdSuffix)) {
-            throw new Error("FlowEvent cannot take both eventId and eventIdSuffix.");
+        else if (event.event === "response") {
+            const hasTokens = event.inputTokens !== undefined || event.outputTokens !== undefined;
+            const tokenStr = hasTokens
+                ? ` ꜛ${event.inputTokens ?? 0} ꜜ${event.outputTokens ?? 0} |`
+                : "";
+            const outputStr = event.output ? " " + String(event.output) : "";
+            details = `${event.model} ↳${tokenStr}${outputStr}`;
         }
-        this.eventType = input.eventType.endsWith("Event")
-            ? input.eventType
-            : `${input.eventType}Event`;
-        this.eventId =
-            input.eventId ?? FlowEvent.createEventId(input.eventIdSuffix ?? "0");
-        this.eventParentIds = input.eventParentIds ?? [];
-        this.createdAt = input.createdAt ?? new Date().toISOString();
-        this.sessionId = input.sessionId;
-        this.data = input.data ?? {};
     }
+    if (!details)
+        return null;
+    // Assemble line and apply final truncation
+    const fullLine = `${formatTimestamp()} ${parts.join(" ")} ${details}`;
+    const cleaned = removeQuotes(fullLine);
+    const processed = event.category === "CDP" ? truncateCdpIds(cleaned) : cleaned;
+    return truncateLine(processed, MAX_LINE_LENGTH);
 }
-const loggerContext = new AsyncLocalStorage();
-function dataToKb(data) {
-    return ((data.length * 0.75) / 1024).toFixed(1);
+/** Check if a CDP event should be filtered from pretty output */
+function shouldFilterCdpEvent(event) {
+    if (event.category !== "CDP")
+        return false;
+    if (event.method?.endsWith(".enable") || event.method === "enable")
+        return true;
+    return event.event === "message" && NOISY_CDP_EVENTS.has(event.method);
 }
 // =============================================================================
-// Flow Logger - Main API
+// Stream Creation
 // =============================================================================
-export class FlowLogger {
-    static cloneContext(ctx) {
-        return {
-            ...ctx,
-            parentEvents: ctx.parentEvents.map((event) => ({
-                ...event,
-                eventParentIds: [...event.eventParentIds],
-            })),
+const isWritable = (s) => !!(s && !s.destroyed && s.writable);
+function createJsonlStream(ctx) {
+    return new Writable({
+        objectMode: true,
+        write(chunk, _, cb) {
+            if (ctx.initialized && isWritable(ctx.fileStreams.jsonl)) {
+                ctx.fileStreams.jsonl.write(chunk, cb);
+            }
+            else
+                cb();
+        },
+    });
+}
+function createPrettyStream(ctx, category, streamKey) {
+    return new Writable({
+        objectMode: true,
+        write(chunk, _, cb) {
+            const stream = ctx.fileStreams[streamKey];
+            if (!ctx.initialized || !isWritable(stream))
+                return cb();
+            try {
+                const event = JSON.parse(chunk);
+                if (event.category !== category || shouldFilterCdpEvent(event))
+                    return cb();
+                const line = prettifyEvent(event);
+                if (line)
+                    stream.write(line + "\n", cb);
+                else
+                    cb();
+            }
+            catch {
+                cb();
+            }
+        },
+    });
+}
+// =============================================================================
+// Public Helpers (used by external callers)
+// =============================================================================
+/**
+ * Get the config directory. Returns empty string if logging is disabled.
+ */
+export function getConfigDir() {
+    return CONFIG_DIR ? path.resolve(CONFIG_DIR) : "";
+}
+/** Extract text and image info from a content array (handles nested tool_result) */
+function extractFromContent(content, result) {
+    for (const part of content) {
+        const p = part;
+        // Text
+        if (!result.text && p.text) {
+            result.text = p.type === "text" || !p.type ? p.text : undefined;
+        }
+        // Images - various formats
+        if (p.type === "image" || p.type === "image_url") {
+            const url = p.image_url?.url;
+            if (url?.startsWith("data:"))
+                result.extras.push(`${dataToKb(url)}kb image`);
+            else if (p.source?.data)
+                result.extras.push(`${dataToKb(p.source.data)}kb image`);
+            else
+                result.extras.push("image");
+        }
+        else if (p.source?.data) {
+            result.extras.push(`${dataToKb(p.source.data)}kb image`);
+        }
+        else if (p.inlineData?.data) {
+            result.extras.push(`${dataToKb(p.inlineData.data)}kb image`);
+        }
+        // Recurse into tool_result content
+        if (p.type === "tool_result" && Array.isArray(p.content)) {
+            extractFromContent(p.content, result);
+        }
+    }
+}
+/** Build final preview string with extras */
+function buildPreview(text, extras, maxLen) {
+    if (!text && extras.length === 0)
+        return undefined;
+    let result = text || "";
+    if (maxLen && result.length > maxLen)
+        result = result.slice(0, maxLen) + "...";
+    if (extras.length > 0) {
+        const extrasStr = extras.map((e) => `+{${e}}`).join(" ");
+        result = result ? `${result} ${extrasStr}` : extrasStr;
+    }
+    return result || undefined;
+}
+/**
+ * Format a prompt preview from LLM messages for logging.
+ * Returns format like: "some text... +{5.8kb image} +{schema} +{12 tools}"
+ */
+export function formatLlmPromptPreview(messages, options) {
+    try {
+        const lastUserMsg = messages.filter((m) => m.role === "user").pop();
+        if (!lastUserMsg)
+            return undefined;
+        const result = {
+            text: undefined,
+            extras: [],
         };
+        if (typeof lastUserMsg.content === "string") {
+            result.text = lastUserMsg.content;
+        }
+        else if (Array.isArray(lastUserMsg.content)) {
+            extractFromContent(lastUserMsg.content, result);
+        }
+        else {
+            return undefined;
+        }
+        // Clean instruction prefix
+        if (result.text) {
+            result.text = result.text.replace(/^[Ii]nstruction: /, "");
+        }
+        if (options?.hasSchema)
+            result.extras.push("schema");
+        if (options?.toolCount)
+            result.extras.push(`${options.toolCount} tools`);
+        return buildPreview(result.text, result.extras);
     }
-    static emit(event) {
-        const ctx = FlowLogger.currentContext;
-        const emittedEvent = new FlowEvent({
-            ...event,
-            eventParentIds: event.eventParentIds ??
-                ctx.parentEvents.map((parent) => parent.eventId),
-            sessionId: ctx.sessionId,
-        });
-        ctx.eventBus.emit(emittedEvent.eventType, emittedEvent);
-        return emittedEvent;
-    }
-    static async runWithAutoStatusEventLogging(options, originalMethod) {
-        const ctx = FlowLogger.currentContext;
-        const { data, eventParentIds, eventType, eventIdSuffix } = options;
-        let caughtError = null;
-        // if eventParentIds is explicitly [], this is a root event, clear the parent events in context
-        if (eventParentIds && eventParentIds.length === 0) {
-            ctx.parentEvents = [];
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Extract a text preview from CUA-style messages.
+ * Accepts various message formats (Anthropic, OpenAI, Google).
+ */
+export function formatCuaPromptPreview(messages, maxLen = 100) {
+    try {
+        const lastMsg = messages
+            .filter((m) => {
+            const msg = m;
+            return msg.role === "user" || msg.type === "tool_result";
+        })
+            .pop();
+        if (!lastMsg)
+            return undefined;
+        const result = {
+            text: undefined,
+            extras: [],
+        };
+        if (typeof lastMsg.content === "string") {
+            result.text = lastMsg.content;
         }
-        const startedEvent = FlowLogger.emit({
-            eventIdSuffix,
-            eventType,
-            data,
-            eventParentIds,
-        });
-        ctx.parentEvents.push(startedEvent);
-        try {
-            return await originalMethod();
+        else if (typeof lastMsg.text === "string") {
+            result.text = lastMsg.text;
         }
-        catch (error) {
-            caughtError = error;
-            FlowLogger.emit({
-                eventIdSuffix,
-                eventType: `${eventType}ErrorEvent`,
-                eventParentIds: [...startedEvent.eventParentIds, startedEvent.eventId],
-                data: {
-                    error: error instanceof Error ? error.message : String(error),
-                    durationMs: Date.now() - new Date(startedEvent.createdAt).getTime(),
-                },
-            });
-            throw error;
+        else if (Array.isArray(lastMsg.parts)) {
+            extractFromContent(lastMsg.parts, result);
         }
-        finally {
-            const parentEvent = ctx.parentEvents.pop();
-            if (parentEvent?.eventId === startedEvent.eventId && !caughtError) {
-                FlowLogger.emit({
-                    eventIdSuffix,
-                    eventType: `${eventType}CompletedEvent`,
-                    eventParentIds: [
-                        ...startedEvent.eventParentIds,
-                        startedEvent.eventId,
-                    ],
-                    data: {
-                        durationMs: Date.now() - new Date(startedEvent.createdAt).getTime(),
-                    },
-                });
-            }
+        else if (Array.isArray(lastMsg.content)) {
+            extractFromContent(lastMsg.content, result);
         }
+        return buildPreview(result.text, result.extras, maxLen);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Format CUA response output for logging */
+export function formatCuaResponsePreview(output, maxLen = 100) {
+    try {
+        // Handle Google format or array
+        const items = output
+            ?.candidates?.[0]?.content?.parts ??
+            (Array.isArray(output) ? output : []);
+        const preview = items
+            .map((item) => {
+            const i = item;
+            if (i.text)
+                return i.text.slice(0, 50);
+            if (i.functionCall?.name)
+                return `fn:${i.functionCall.name}`;
+            if (i.type === "tool_use" && i.name)
+                return `tool_use:${i.name}`;
+            return i.type ? `[${i.type}]` : "[item]";
+        })
+            .join(" ");
+        return preview.slice(0, maxLen);
     }
+    catch {
+        return "[error]";
+    }
+}
+// =============================================================================
+// SessionFileLogger - Main API
+// =============================================================================
+export 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, eventBus) {
+    static init(sessionId, v3Options) {
+        const configDir = getConfigDir();
+        if (!configDir)
+            return; // Logging disabled
+        const sessionDir = path.join(configDir, "sessions", sessionId);
+        // Create context with placeholder logger (will be replaced after streams init)
         const ctx = {
+            logger: pino({ level: "silent" }), // Placeholder, replaced below
+            metrics: {
+                llmRequests: 0,
+                llmInputTokens: 0,
+                llmOutputTokens: 0,
+                cdpEvents: 0,
+            },
             sessionId,
-            eventBus,
-            parentEvents: [],
+            sessionDir,
+            configDir,
+            initPromise: Promise.resolve(),
+            initialized: false,
+            // Span context - mutable, injected into every log via mixin
+            taskId: null,
+            stepId: null,
+            stepLabel: null,
+            actionId: null,
+            actionLabel: null,
+            fileStreams: {
+                agent: null,
+                stagehand: null,
+                understudy: null,
+                cdp: null,
+                llm: null,
+                jsonl: null,
+            },
         };
+        // Store init promise for awaiting in log methods
+        ctx.initPromise = SessionFileLogger.initAsync(ctx, v3Options);
         loggerContext.enterWith(ctx);
-        return ctx;
     }
-    static async close(context) {
-        const ctx = context ?? loggerContext.getStore() ?? null;
+    static async initAsync(ctx, v3Options) {
+        try {
+            await fs.promises.mkdir(ctx.sessionDir, { recursive: true });
+            if (v3Options) {
+                const sanitizedOptions = sanitizeOptions(v3Options);
+                const sessionJsonPath = path.join(ctx.sessionDir, "session.json");
+                await fs.promises.writeFile(sessionJsonPath, JSON.stringify(sanitizedOptions, null, 2), "utf-8");
+            }
+            // Create symlink to latest session
+            const latestLink = path.join(ctx.configDir, "sessions", "latest");
+            try {
+                try {
+                    await fs.promises.unlink(latestLink);
+                }
+                catch {
+                    // Ignore if doesn't exist
+                }
+                await fs.promises.symlink(ctx.sessionId, latestLink, "dir");
+            }
+            catch {
+                // Symlink creation can fail on Windows or due to permissions
+            }
+            // Create file streams
+            const dir = ctx.sessionDir;
+            ctx.fileStreams.agent = fs.createWriteStream(path.join(dir, "agent_events.log"), { flags: "a" });
+            ctx.fileStreams.stagehand = fs.createWriteStream(path.join(dir, "stagehand_events.log"), { flags: "a" });
+            ctx.fileStreams.understudy = fs.createWriteStream(path.join(dir, "understudy_events.log"), { flags: "a" });
+            ctx.fileStreams.cdp = fs.createWriteStream(path.join(dir, "cdp_events.log"), { flags: "a" });
+            ctx.fileStreams.llm = fs.createWriteStream(path.join(dir, "llm_events.log"), { flags: "a" });
+            ctx.fileStreams.jsonl = fs.createWriteStream(path.join(dir, "session_events.jsonl"), { flags: "a" });
+            ctx.initialized = true;
+            // Create pino multistream: JSONL + pretty streams per category
+            const streams = [
+                { stream: createJsonlStream(ctx) },
+                { stream: createPrettyStream(ctx, "AgentTask", "agent") },
+                { stream: createPrettyStream(ctx, "StagehandStep", "stagehand") },
+                { stream: createPrettyStream(ctx, "UnderstudyAction", "understudy") },
+                { stream: createPrettyStream(ctx, "CDP", "cdp") },
+                { stream: createPrettyStream(ctx, "LLM", "llm") },
+            ];
+            // Create logger with mixin that injects span context from AsyncLocalStorage
+            ctx.logger = pino({
+                level: "info",
+                // Mixin adds eventId and current span context to every log
+                mixin() {
+                    const store = loggerContext.getStore();
+                    return {
+                        eventId: uuidv7(),
+                        sessionId: store?.sessionId,
+                        taskId: store?.taskId,
+                        stepId: store?.stepId,
+                        stepLabel: store?.stepLabel,
+                        actionId: store?.actionId,
+                        actionLabel: store?.actionLabel,
+                    };
+                },
+            }, pino.multistream(streams));
+        }
+        catch {
+            // Fail silently
+        }
+    }
+    static async close() {
+        const ctx = loggerContext.getStore();
         if (!ctx)
             return;
-        ctx.parentEvents = [];
+        await ctx.initPromise;
+        SessionFileLogger.logAgentTaskCompleted();
+        await Promise.all(Object.values(ctx.fileStreams)
+            .filter(Boolean)
+            .map((s) => new Promise((r) => s.end(r)))).catch(() => { });
     }
-    static get currentContext() {
-        const ctx = loggerContext.getStore() ?? null;
-        if (!ctx) {
-            throw new Error("FlowLogger context is missing.");
-        }
-        return ctx;
+    static get sessionId() {
+        return loggerContext.getStore()?.sessionId ?? null;
     }
-    // decorator method to wrap a class method with automatic started/completed/error events
-    static wrapWithLogging(options) {
-        return function (originalMethod) {
-            const wrappedMethod = async function (...args) {
-                return await FlowLogger.runWithLogging(options, (...boundArgs) => originalMethod.apply(this, boundArgs), args);
-            };
-            return wrappedMethod;
+    static get sessionDir() {
+        return loggerContext.getStore()?.sessionDir ?? null;
+    }
+    /**
+     * Get the current logger context object.
+     */
+    static getContext() {
+        return loggerContext.getStore() ?? null;
+    }
+    // ===========================================================================
+    // Agent Task Events
+    // ===========================================================================
+    /**
+     * Start a new task and log it.
+     */
+    static logAgentTaskStarted({ invocation, args, }) {
+        const ctx = loggerContext.getStore();
+        if (!ctx)
+            return;
+        // Set up task context
+        ctx.taskId = uuidv7();
+        ctx.stepId = null;
+        ctx.stepLabel = null;
+        ctx.actionId = null;
+        ctx.actionLabel = null;
+        // Reset metrics for new task
+        ctx.metrics = {
+            taskStartTime: Date.now(),
+            llmRequests: 0,
+            llmInputTokens: 0,
+            llmOutputTokens: 0,
+            cdpEvents: 0,
         };
+        ctx.logger.info({
+            category: "AgentTask",
+            event: "started",
+            method: invocation,
+            params: args,
+        });
     }
-    static runWithLogging(options, originalMethod, params) {
-        const eventData = {
-            ...(options.data ?? {}),
-            params: [...params],
+    /**
+     * Log task completion with metrics summary.
+     */
+    static logAgentTaskCompleted(options) {
+        const ctx = loggerContext.getStore();
+        if (!ctx || !ctx.metrics.taskStartTime)
+            return;
+        const durationMs = Date.now() - ctx.metrics.taskStartTime;
+        const event = {
+            category: "AgentTask",
+            event: "completed",
+            method: "Agent.execute",
+            metrics: {
+                durationMs,
+                llmRequests: ctx.metrics.llmRequests,
+                inputTokens: ctx.metrics.llmInputTokens,
+                outputTokens: ctx.metrics.llmOutputTokens,
+                cdpEvents: ctx.metrics.cdpEvents,
+            },
         };
-        const execute = () => FlowLogger.runWithAutoStatusEventLogging({
-            ...options,
-            data: eventData,
-        }, () => originalMethod(...params));
-        if (!options.context && !(loggerContext.getStore() ?? null)) {
-            return originalMethod(...params);
+        if (options?.cacheHit) {
+            event.msg = "CACHE HIT, NO LLM NEEDED";
         }
-        return options.context
-            ? loggerContext.run(FlowLogger.cloneContext(options.context), execute)
-            : execute();
+        ctx.logger.info(event);
+        // Clear task context
+        ctx.taskId = null;
+        ctx.stepId = null;
+        ctx.stepLabel = null;
+        ctx.actionId = null;
+        ctx.actionLabel = null;
+        ctx.metrics.taskStartTime = undefined;
     }
     // ===========================================================================
-    // CDP Events
+    // Stagehand Step Events
     // ===========================================================================
-    static NOISY_CDP_EVENTS = new Set([
-        "Target.targetInfoChanged",
-        "Runtime.executionContextCreated",
-        "Runtime.executionContextDestroyed",
-        "Runtime.executionContextsCleared",
-        "Page.lifecycleEvent",
-        "Network.dataReceived",
-        "Network.loadingFinished",
-        "Network.requestWillBeSentExtraInfo",
-        "Network.responseReceivedExtraInfo",
-        "Network.requestWillBeSent",
-        "Network.responseReceived",
-    ]);
-    static logCdpEvent(context, eventType, { method, params, result, error, targetId, }, eventParentIds) {
-        if (method.endsWith(".enable") || method === "enable") {
-            return null;
-        }
-        if (eventType === "message" && FlowLogger.NOISY_CDP_EVENTS.has(method)) {
-            return null;
-        }
-        return loggerContext.run(FlowLogger.cloneContext(context), () => FlowLogger.emit({
-            eventIdSuffix: "6",
-            eventType: eventType === "call"
-                ? "CdpCallEvent"
-                : eventType === "response"
-                    ? "CdpResponseEvent"
-                    : eventType === "responseError"
-                        ? "CdpResponseErrorEvent"
-                        : "CdpMessageEvent",
-            eventParentIds,
-            data: {
-                method,
-                params,
-                result,
-                error,
-                targetId,
-            },
-        }));
+    static logStagehandStepEvent({ invocation, args, label, }) {
+        const ctx = loggerContext.getStore();
+        if (!ctx)
+            return uuidv7();
+        // Set up step context
+        ctx.stepId = uuidv7();
+        ctx.stepLabel = label.toUpperCase();
+        ctx.actionId = null;
+        ctx.actionLabel = null;
+        ctx.metrics.stepStartTime = Date.now();
+        ctx.logger.info({
+            category: "StagehandStep",
+            event: "started",
+            method: invocation,
+            params: args,
+        });
+        return ctx.stepId;
+    }
+    static logStagehandStepCompleted() {
+        const ctx = loggerContext.getStore();
+        if (!ctx || !ctx.stepId)
+            return;
+        const durationMs = ctx.metrics.stepStartTime
+            ? Date.now() - ctx.metrics.stepStartTime
+            : 0;
+        ctx.logger.info({
+            category: "StagehandStep",
+            event: "completed",
+            metrics: { durationMs },
+        });
+        // Clear step context
+        ctx.stepId = null;
+        ctx.stepLabel = null;
+        ctx.actionId = null;
+        ctx.actionLabel = null;
+        ctx.metrics.stepStartTime = undefined;
+    }
+    // ===========================================================================
+    // Understudy Action Events
+    // ===========================================================================
+    static logUnderstudyActionEvent({ actionType, target, args, }) {
+        const ctx = loggerContext.getStore();
+        if (!ctx)
+            return uuidv7();
+        // Set up action context
+        ctx.actionId = uuidv7();
+        ctx.actionLabel = actionType
+            .toUpperCase()
+            .replace("UNDERSTUDY.", "")
+            .replace("PAGE.", "");
+        ctx.metrics.actionStartTime = Date.now();
+        const params = {};
+        if (target)
+            params.target = target;
+        if (args)
+            params.args = args;
+        ctx.logger.info({
+            category: "UnderstudyAction",
+            event: "started",
+            method: actionType,
+            params: Object.keys(params).length > 0 ? params : undefined,
+        });
+        return ctx.actionId;
     }
-    static logCdpCallEvent(context, data) {
-        return FlowLogger.logCdpEvent(context, "call", data);
+    static logUnderstudyActionCompleted() {
+        const ctx = loggerContext.getStore();
+        if (!ctx || !ctx.actionId)
+            return;
+        const durationMs = ctx.metrics.actionStartTime
+            ? Date.now() - ctx.metrics.actionStartTime
+            : 0;
+        ctx.logger.info({
+            category: "UnderstudyAction",
+            event: "completed",
+            metrics: { durationMs },
+        });
+        // Clear action context
+        ctx.actionId = null;
+        ctx.actionLabel = null;
+        ctx.metrics.actionStartTime = undefined;
+    }
+    // ===========================================================================
+    // CDP Events
+    // ===========================================================================
+    static logCdpEvent(eventType, { method, params, targetId, }, explicitCtx) {
+        const ctx = explicitCtx ?? loggerContext.getStore();
+        if (!ctx)
+            return;
+        if (eventType === "call")
+            ctx.metrics.cdpEvents++;
+        ctx.logger.info({
+            category: "CDP",
+            event: eventType,
+            method,
+            params,
+            targetId,
+        });
     }
-    static logCdpResponseEvent(context, parentEvent, data) {
-        FlowLogger.logCdpEvent(context, data.error ? "responseError" : "response", data, [...parentEvent.eventParentIds, parentEvent.eventId]);
+    static logCdpCallEvent(data, ctx) {
+        SessionFileLogger.logCdpEvent("call", data, ctx);
     }
-    static logCdpMessageEvent(context, parentEvent, data) {
-        FlowLogger.logCdpEvent(context, "message", data, [
-            ...parentEvent.eventParentIds,
-            parentEvent.eventId,
-        ]);
+    static logCdpMessageEvent(data, ctx) {
+        SessionFileLogger.logCdpEvent("message", data, ctx);
     }
     // ===========================================================================
     // LLM Events
     // ===========================================================================
-    static logLlmRequest({ requestId, model, prompt, }) {
-        FlowLogger.emit({
-            eventIdSuffix: "7",
-            eventType: "LlmRequestEvent",
-            data: {
-                requestId,
-                model,
-                prompt,
-            },
+    static logLlmRequest({ requestId, model, prompt, }, explicitCtx) {
+        const ctx = explicitCtx ?? loggerContext.getStore();
+        if (!ctx)
+            return;
+        // Track LLM requests for task metrics
+        ctx.metrics.llmRequests++;
+        ctx.logger.info({
+            category: "LLM",
+            event: "request",
+            requestId,
+            method: "LLM.request",
+            model,
+            prompt,
         });
     }
-    static logLlmResponse({ requestId, model, output, inputTokens, outputTokens, }) {
-        FlowLogger.emit({
-            eventIdSuffix: "7",
-            eventType: "LlmResponseEvent",
-            data: {
-                requestId,
-                model,
-                output,
-                inputTokens,
-                outputTokens,
-            },
+    static logLlmResponse({ requestId, model, output, inputTokens, outputTokens, }, explicitCtx) {
+        const ctx = explicitCtx ?? loggerContext.getStore();
+        if (!ctx)
+            return;
+        // Track tokens for task metrics
+        ctx.metrics.llmInputTokens += inputTokens ?? 0;
+        ctx.metrics.llmOutputTokens += outputTokens ?? 0;
+        ctx.logger.info({
+            category: "LLM",
+            event: "response",
+            requestId,
+            method: "LLM.response",
+            model,
+            output,
+            inputTokens,
+            outputTokens,
         });
     }
     // ===========================================================================
@@ -247,57 +729,69 @@ export class FlowLogger {
      * Returns a no-op middleware when logging is disabled.
      */
     static createLlmLoggingMiddleware(modelId) {
+        // No-op middleware when logging is disabled
+        if (!CONFIG_DIR) {
+            return {
+                wrapGenerate: async ({ doGenerate }) => doGenerate(),
+            };
+        }
         return {
             wrapGenerate: async ({ doGenerate, params }) => {
+                const ctx = SessionFileLogger.getContext();
+                // Skip logging overhead if no context (shouldn't happen but be safe)
+                if (!ctx) {
+                    return doGenerate();
+                }
                 const llmRequestId = uuidv7();
                 const toolCount = Array.isArray(params.tools) ? params.tools.length : 0;
+                // Extract prompt preview from last non-system message
                 const messages = (params.prompt ?? []);
                 const lastMsg = messages.filter((m) => m.role !== "system").pop();
+                const extracted = {
+                    text: undefined,
+                    extras: [],
+                };
                 let rolePrefix = lastMsg?.role ?? "?";
-                let promptSummary = `(no text) +{${toolCount} tools}`;
                 if (lastMsg) {
                     if (typeof lastMsg.content === "string") {
-                        promptSummary = `${lastMsg.content} +{${toolCount} tools}`;
+                        extracted.text = lastMsg.content;
                     }
                     else if (Array.isArray(lastMsg.content)) {
-                        const toolResult = lastMsg.content.find((part) => part.type === "tool-result");
+                        // Check for tool-result first
+                        const toolResult = lastMsg.content.find((p) => p.type === "tool-result");
                         if (toolResult) {
                             rolePrefix = `tool result: ${toolResult.toolName}()`;
-                            if (toolResult.output?.type === "json" &&
-                                toolResult.output.value) {
-                                promptSummary = `${JSON.stringify(toolResult.output.value)} +{${toolCount} tools}`;
+                            const out = toolResult.output;
+                            if (out?.type === "json" && out.value) {
+                                extracted.text = JSON.stringify(out.value).slice(0, 150);
                             }
-                            else if (Array.isArray(toolResult.output?.value)) {
-                                promptSummary = `${extractLlmMessageSummary({
-                                    content: toolResult.output.value,
-                                }) ?? "(no text)"} +{${toolCount} tools}`;
+                            else if (Array.isArray(out?.value)) {
+                                extractFromContent(out.value, extracted);
                             }
                         }
                         else {
-                            promptSummary = `${extractLlmMessageSummary({ content: lastMsg.content }) ??
-                                "(no text)"} +{${toolCount} tools}`;
+                            extractFromContent(lastMsg.content, extracted);
                         }
                     }
-                    promptSummary = `${rolePrefix}: ${promptSummary}`;
                 }
-                else {
-                    promptSummary = `?: ${promptSummary}`;
-                }
-                FlowLogger.logLlmRequest({
+                const promptText = extracted.text || "(no text)";
+                const promptPreview = `${rolePrefix}: ${promptText} +{${toolCount} tools}`;
+                SessionFileLogger.logLlmRequest({
                     requestId: llmRequestId,
                     model: modelId,
-                    prompt: promptSummary,
-                });
+                    operation: "generateText",
+                    prompt: promptPreview,
+                }, ctx);
                 const result = await doGenerate();
-                // Extract output summary
+                // Extract output preview
                 const res = result;
-                let outputSummary = res.text || "";
-                if (!outputSummary && res.content) {
+                let outputPreview = res.text || "";
+                if (!outputPreview && res.content) {
                     if (typeof res.content === "string") {
-                        outputSummary = res.content;
+                        outputPreview = res.content;
                     }
                     else if (Array.isArray(res.content)) {
-                        outputSummary = res.content
+                        outputPreview = res.content
                             .map((c) => c.text ||
                             (c.type === "tool-call"
                                 ? `tool call: ${c.toolName}()`
@@ -305,158 +799,70 @@ export class FlowLogger {
                             .join(" ");
                     }
                 }
-                if (!outputSummary && res.toolCalls?.length) {
-                    outputSummary = `[${res.toolCalls.length} tool calls]`;
+                if (!outputPreview && res.toolCalls?.length) {
+                    outputPreview = `[${res.toolCalls.length} tool calls]`;
                 }
-                FlowLogger.logLlmResponse({
+                SessionFileLogger.logLlmResponse({
                     requestId: llmRequestId,
                     model: modelId,
-                    output: outputSummary || "[empty]",
+                    operation: "generateText",
+                    output: outputPreview || "[empty]",
                     inputTokens: result.usage?.inputTokens,
                     outputTokens: result.usage?.outputTokens,
-                });
+                }, ctx);
                 return result;
             },
         };
     }
 }
-/** Extract text and image info from a content array (handles nested tool_result) */
-function extractLlmMessageContent(content) {
-    const result = {
-        text: undefined,
-        extras: [],
-    };
-    for (const part of content) {
-        const p = part;
-        // Text
-        if (!result.text && p.text) {
-            result.text = p.type === "text" || !p.type ? p.text : undefined;
-        }
-        // Images - various formats
-        if (p.type === "image" || p.type === "image_url") {
-            const url = p.image_url?.url;
-            if (url?.startsWith("data:"))
-                result.extras.push(`${dataToKb(url)}kb image`);
-            else if (p.source?.data)
-                result.extras.push(`${dataToKb(p.source.data)}kb image`);
-            else
-                result.extras.push("image");
-        }
-        else if (p.source?.data) {
-            result.extras.push(`${dataToKb(p.source.data)}kb image`);
-        }
-        else if (p.inlineData?.data) {
-            result.extras.push(`${dataToKb(p.inlineData.data)}kb image`);
+/**
+ * Method decorator for logging understudy actions with automatic start/complete.
+ * Logs all arguments automatically. No-op when CONFIG_DIR is empty.
+ */
+export function logAction(actionType) {
+    return function (originalMethod) {
+        // No-op when logging is disabled
+        if (!CONFIG_DIR) {
+            return originalMethod;
         }
-        // Recurse into tool_result content
-        if (p.type === "tool_result" && Array.isArray(p.content)) {
-            const nested = extractLlmMessageContent(p.content);
-            if (!result.text && nested.text) {
-                result.text = nested.text;
+        return async function (...args) {
+            SessionFileLogger.logUnderstudyActionEvent({
+                actionType,
+                args: args.length > 0 ? args : undefined,
+            });
+            try {
+                return await originalMethod.apply(this, args);
             }
-            result.extras.push(...nested.extras);
-        }
-    }
-    return result;
-}
-function extractLlmMessageSummary(input, options) {
-    const result = {
-        text: undefined,
-        extras: [...(options?.extras ?? [])],
+            finally {
+                SessionFileLogger.logUnderstudyActionCompleted();
+            }
+        };
     };
-    if (typeof input.content === "string") {
-        result.text = input.content;
-    }
-    else if (typeof input.text === "string") {
-        result.text = input.text;
-    }
-    else if (Array.isArray(input.parts)) {
-        const summary = extractLlmMessageContent(input.parts);
-        result.text = summary.text;
-        result.extras.push(...summary.extras);
-    }
-    else if (Array.isArray(input.content)) {
-        const summary = extractLlmMessageContent(input.content);
-        result.text = summary.text;
-        result.extras.push(...summary.extras);
-    }
-    if (options?.trimInstructionPrefix && result.text) {
-        result.text = result.text.replace(/^[Ii]nstruction: /, "");
-    }
-    const text = result.text;
-    if (!text && result.extras.length === 0)
-        return undefined;
-    let summary = text || "";
-    if (result.extras.length > 0) {
-        const extrasStr = result.extras.map((e) => `+{${e}}`).join(" ");
-        summary = summary ? `${summary} ${extrasStr}` : extrasStr;
-    }
-    return summary || undefined;
-}
-/**
- * Format a prompt summary from LLM messages for logging.
- * Returns format like: "some text +{5.8kb image} +{schema} +{12 tools}"
- */
-export function extractLlmPromptSummary(messages, options) {
-    try {
-        const lastUserMsg = messages.filter((m) => m.role === "user").pop();
-        if (!lastUserMsg)
-            return undefined;
-        return extractLlmMessageSummary(lastUserMsg, {
-            trimInstructionPrefix: true,
-            extras: [
-                ...(options?.hasSchema ? ["schema"] : []),
-                ...(options?.toolCount ? [`${options.toolCount} tools`] : []),
-            ],
-        });
-    }
-    catch {
-        return undefined;
-    }
 }
 /**
- * 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 function extractLlmCuaPromptSummary(messages) {
-    try {
-        const lastMsg = messages
-            .filter((m) => {
-            const msg = m;
-            return msg.role === "user" || msg.type === "tool_result";
-        })
-            .pop();
-        if (!lastMsg)
-            return undefined;
-        return extractLlmMessageSummary(lastMsg);
-    }
-    catch {
-        return undefined;
-    }
-}
-/** Format a CUA response summary for logging */
-export function extractLlmCuaResponseSummary(output) {
-    try {
-        // Handle Google format or array
-        const items = output
-            ?.candidates?.[0]?.content?.parts ??
-            (Array.isArray(output) ? output : []);
-        const summary = items
-            .map((item) => {
-            const i = item;
-            if (i.text)
-                return i.text;
-            if (i.functionCall?.name)
-                return i.functionCall.name;
-            if (i.type === "tool_use" && i.name)
-                return i.name;
-            return i.type ?? "[item]";
-        })
-            .join(" ");
-        return summary;
-    }
-    catch {
-        return "[error]";
-    }
+export function logStagehandStep(invocation, label) {
+    return function (originalMethod) {
+        // No-op when logging is disabled
+        if (!CONFIG_DIR) {
+            return originalMethod;
+        }
+        return async function (...args) {
+            SessionFileLogger.logStagehandStepEvent({
+                invocation,
+                args: args.length > 0 ? args : undefined,
+                label,
+            });
+            try {
+                return await originalMethod.apply(this, args);
+            }
+            finally {
+                SessionFileLogger.logStagehandStepCompleted();
+            }
+        };
+    };
 }
 //# sourceMappingURL=flowLogger.js.map