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

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

@@ -0,0 +1,583 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { v7 as uuidv7 } from "uuid";
+import { z } from "zod";
+// =============================================================================
+// Flow Event Model
+// =============================================================================
+export const FlowEventDataSchema = z.record(z.string(), z.unknown());
+export const FlowEventInputSchema = z.object({
+    eventType: z.string(),
+    eventId: z.string().optional(),
+    eventParentIds: z.array(z.string()).optional(),
+    eventCreatedAt: z.string().optional(),
+    sessionId: z.string().optional(),
+    data: FlowEventDataSchema.optional(),
+});
+export class FlowEvent {
+    // "ModuleMethodSomethingEvent" -> hashToSmallInt("Modu) -> 5. eventId = "...5"
+    static deriveEventIdSuffix(eventType) {
+        const prefixMatch = eventType.match(/^[A-Z][a-z0-9]*/);
+        const prefix = prefixMatch?.[0] ?? eventType.slice(0, 4);
+        let hash = 0;
+        for (const ch of prefix.slice(0, 4)) {
+            hash = (hash * 31 + ch.charCodeAt(0)) % 10;
+        }
+        return String(hash); // e.g. "0" or "9"
+    }
+    // Builds a sortable UUID-like event id while preserving a stable, human-friendly suffix derived from the event family.
+    static createEventId(eventType) {
+        const rawEventId = uuidv7();
+        return `${rawEventId.slice(0, -1)}${FlowEvent.deriveEventIdSuffix(eventType)}`;
+    }
+    // Base required fields for all events:
+    eventType;
+    eventId;
+    eventParentIds;
+    eventCreatedAt;
+    // `sessionId` usually matches `browserbaseSessionId` today, but FlowLogger treats it as a generic Stagehand session identifier because those may diverge in the future.
+    sessionId;
+    data; // event payload (e.g. params, action, result, error, etc.)
+    // Normalizes the event shape used everywhere in the flow logger pipeline. This is called at emission time right before an event is attached to the event bus and any sinks.
+    constructor(input) {
+        if (!input.sessionId) {
+            throw new Error("FlowEvent.sessionId is required.");
+        }
+        if (input.eventType.endsWith("Event")) {
+            this.eventType = input.eventType;
+        }
+        else {
+            this.eventType = `${input.eventType}Event`;
+        }
+        this.eventId = input.eventId ?? FlowEvent.createEventId(this.eventType);
+        this.eventParentIds = input.eventParentIds ?? [];
+        this.eventCreatedAt = input.eventCreatedAt ?? new Date().toISOString();
+        this.sessionId = input.sessionId;
+        this.data = input.data ?? {};
+    }
+}
+// AsyncLocalStorage is the authoritative source for the active flow parent stack inside a single async call-chain.
+const loggerContext = new AsyncLocalStorage();
+// Converts raw inline image/base64 payload lengths into a compact kb string for LLM prompt summaries.
+function dataToKb(data) {
+    return ((data.length * 0.75) / 1024).toFixed(1);
+}
+const CDP_EVENT_NAMES = {
+    call: "CdpCallEvent",
+    response: "CdpResponseEvent",
+    responseError: "CdpResponseErrorEvent",
+    message: "CdpMessageEvent",
+};
+export class FlowLogger {
+    // Copies the mutable parts of a context before it is re-entered in a later async callback. This prevents later parent-stack mutations from leaking backward into stored snapshots.
+    static cloneContext(ctx) {
+        return {
+            ...ctx,
+            parentEvents: ctx.parentEvents.map((event) => ({
+                ...event,
+                eventParentIds: [...event.eventParentIds],
+            })),
+        };
+    }
+    // Chooses the safest context to re-enter when callers already have a stored context
+    // and ALS may or may not already contain one for the same session.
+    // If the current ALS stack extends the stored stack, we keep the richer ALS view.
+    // If the stored stack is deeper, we preserve that instead.
+    // If they diverge, we prefer the current ALS view because it reflects the currently executing call-chain.
+    static resolveReentryContext(context) {
+        const currentContext = loggerContext.getStore() ?? null;
+        // If ALS is empty or belongs to another session, the caller's stored
+        // snapshot is the only safe context we can re-enter.
+        if (!currentContext || currentContext.sessionId !== context.sessionId) {
+            return FlowLogger.cloneContext(context);
+        }
+        const providedParentIds = context.parentEvents.map((event) => event.eventId);
+        const currentParentIds = currentContext.parentEvents.map((event) => event.eventId);
+        const currentExtendsProvided = providedParentIds.every((eventId, index) => currentParentIds[index] === eventId);
+        // ALS already has the provided chain as a prefix, so we keep the richer
+        // currently-executing stack instead of truncating it.
+        if (currentExtendsProvided) {
+            return FlowLogger.cloneContext(currentContext);
+        }
+        const providedExtendsCurrent = currentParentIds.every((eventId, index) => providedParentIds[index] === eventId);
+        // The stored snapshot is deeper than the current ALS stack, which usually
+        // means we are re-entering from a later async callback and need to restore
+        // the missing parent chain.
+        if (providedExtendsCurrent) {
+            return FlowLogger.cloneContext(context);
+        }
+        // If the two chains diverged, prefer the live ALS chain because it reflects
+        // the work currently executing on this async path.
+        return FlowLogger.cloneContext(currentContext);
+    }
+    // Materializes and emits a single flow event on the active ALS context.
+    // This is the lowest-level write path used by all higher-level logging helpers
+    // after they have decided which parent chain and session the event belongs to.
+    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;
+    }
+    // Wraps a unit of async work with started/completed/error events while maintaining
+    // the parent stack inside the active context.
+    static async runWithAutoStatusEventLogging(options, originalMethod) {
+        const ctx = FlowLogger.currentContext;
+        const { data, eventParentIds, eventType } = 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 = [];
+        }
+        const startedEvent = FlowLogger.emit({
+            eventType,
+            data,
+            eventParentIds,
+        });
+        // Push after emitting so nested work sees this event as its direct parent
+        // for the rest of the wrapped method's lifetime.
+        ctx.parentEvents.push(startedEvent);
+        try {
+            return await originalMethod();
+        }
+        catch (error) {
+            caughtError = error;
+            // Error events attach directly under the started event even though the
+            // stack is still live, so the failure edge is explicit in the tree.
+            FlowLogger.emit({
+                eventType: `${eventType}ErrorEvent`,
+                eventParentIds: [...startedEvent.eventParentIds, startedEvent.eventId],
+                data: {
+                    error: error instanceof Error ? error.message : String(error),
+                    durationMs: Date.now() - new Date(startedEvent.eventCreatedAt).getTime(),
+                },
+            });
+            throw error;
+        }
+        finally {
+            // Pop only the frame owned by this wrapper. If nested code has already
+            // mutated the stack unexpectedly, we skip the completed event rather than
+            // emitting a misleading lifecycle edge.
+            const parentEvent = ctx.parentEvents.pop();
+            if (parentEvent?.eventId === startedEvent.eventId && !caughtError) {
+                FlowLogger.emit({
+                    eventType: `${eventType}CompletedEvent`,
+                    eventParentIds: [
+                        ...startedEvent.eventParentIds,
+                        startedEvent.eventId,
+                    ],
+                    data: {
+                        durationMs: Date.now() - new Date(startedEvent.eventCreatedAt).getTime(),
+                    },
+                });
+            }
+        }
+    }
+    // Emits a CDP event under a caller-supplied context. CDP transport code uses this
+    // instead of `runWithLogging()` because request/response/message events
+    // are separate lifecycle edges with explicit parent ids.
+    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({
+            eventType: CDP_EVENT_NAMES[eventType],
+            eventParentIds,
+            data: {
+                method,
+                params,
+                result,
+                error,
+                targetId,
+            },
+        }));
+    }
+    // Emits an LLM request/response event only when a flow context is active.
+    // LLM logging is best-effort, so callers should not fail if it is invoked outside a tracked async chain.
+    static emitLlmEvent(event) {
+        const context = FlowLogger.resolveContext();
+        if (!context) {
+            return;
+        }
+        loggerContext.run(context, () => {
+            FlowLogger.emit(event);
+        });
+    }
+    // Builds the one-line prompt summary used in LLM request events for AI SDK middleware calls.
+    static buildMiddlewarePromptSummary(params) {
+        const toolCount = Array.isArray(params.tools) ? params.tools.length : 0;
+        const messages = (params.prompt ?? []);
+        const lastMsg = messages
+            .filter((message) => message.role !== "system")
+            .pop();
+        let rolePrefix = lastMsg?.role ?? "?";
+        let promptSummary = `(no text) +{${toolCount} tools}`;
+        if (!lastMsg) {
+            return `?: ${promptSummary}`;
+        }
+        if (typeof lastMsg.content === "string") {
+            promptSummary = `${lastMsg.content} +{${toolCount} tools}`;
+        }
+        else if (Array.isArray(lastMsg.content)) {
+            const toolResult = lastMsg.content.find((part) => part.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}`;
+                }
+                else if (Array.isArray(toolResult.output?.value)) {
+                    promptSummary = `${extractLlmMessageSummary({
+                        content: toolResult.output.value,
+                    }) ?? "(no text)"} +{${toolCount} tools}`;
+                }
+            }
+            else {
+                promptSummary = `${extractLlmMessageSummary({ content: lastMsg.content }) ?? "(no text)"} +{${toolCount} tools}`;
+            }
+        }
+        return `${rolePrefix}: ${promptSummary}`;
+    }
+    // Builds the one-line output summary used in LLM response events for AI SDK middleware calls.
+    static buildMiddlewareOutputSummary(result) {
+        let outputSummary = result.text || "";
+        if (!outputSummary && result.content) {
+            if (typeof result.content === "string") {
+                outputSummary = result.content;
+            }
+            else if (Array.isArray(result.content)) {
+                outputSummary = result.content
+                    .map((contentPart) => {
+                    if (contentPart.text) {
+                        return contentPart.text;
+                    }
+                    if (contentPart.type === "tool-call") {
+                        return `tool call: ${contentPart.toolName}()`;
+                    }
+                    return `[${contentPart.type}]`;
+                })
+                    .join(" ");
+            }
+        }
+        if (!outputSummary && result.toolCalls?.length) {
+            return `[${result.toolCalls.length} tool calls]`;
+        }
+        return outputSummary || "[empty]";
+    }
+    // =============================================================================
+    // Flow Logger Public Lifecycle API
+    // =============================================================================
+    // Initialize a new logging context. Call this at the start of a session.
+    static init(sessionId, eventBus) {
+        const ctx = {
+            sessionId,
+            eventBus,
+            parentEvents: [],
+        };
+        loggerContext.enterWith(ctx);
+        return ctx;
+    }
+    // Clears the parent stack for a session when a V3 instance shuts down.
+    // This does not emit a final event; it just tears down in-memory context.
+    static async close(context) {
+        const ctx = context ?? loggerContext.getStore() ?? null;
+        if (!ctx)
+            return;
+        ctx.parentEvents = [];
+    }
+    // Returns the current ALS-backed flow context and throws when code
+    // executes outside a tracked flow. Use `resolveContext()` for best-effort lookups.
+    static get currentContext() {
+        const ctx = loggerContext.getStore() ?? null;
+        if (!ctx) {
+            throw new Error("FlowLogger context is missing.");
+        }
+        return ctx;
+    }
+    // Returns a cloned FlowLogger context for the current async call-chain when one exists,
+    // otherwise falls back to the provided instance-owned context.
+    // This is the non-throwing lookup for callers that can continue without ALS.
+    static resolveContext(fallbackContext) {
+        const currentContext = loggerContext.getStore() ?? null;
+        if (currentContext) {
+            return FlowLogger.cloneContext(currentContext);
+        }
+        return fallbackContext ? FlowLogger.cloneContext(fallbackContext) : null;
+    }
+    // Decorator-style wrapper used on class methods that should emit their own started/completed/error envelope.
+    // It resolves the flow context from either the decorator options or `this.flowLoggerContext`,
+    // then delegates the actual lifecycle handling to `runWithLogging()`.
+    static wrapWithLogging(options) {
+        return function (originalMethod) {
+            const wrappedMethod = async function (...args) {
+                let context = options.context;
+                if (!context) {
+                    context = this?.flowLoggerContext;
+                }
+                return await FlowLogger.runWithLogging({
+                    ...options,
+                    context,
+                }, (...boundArgs) => originalMethod.apply(this, boundArgs), args);
+            };
+            return wrappedMethod;
+        };
+    }
+    static runWithLogging(options, originalMethod, params) {
+        const eventData = {
+            ...(options.data ?? {}),
+            params: [...params],
+        };
+        const execute = () => FlowLogger.runWithAutoStatusEventLogging({
+            ...options,
+            data: eventData,
+        }, () => originalMethod(...params));
+        // No explicit context and no active ALS means there is nothing to attach
+        // this work to, so we leave execution untouched instead of fabricating a
+        // root event.
+        if (!options.context && !(loggerContext.getStore() ?? null)) {
+            return originalMethod(...params);
+        }
+        if (options.context) {
+            // Re-enter the caller-owned context so wrapper events land under the same
+            // session tree even when this code executes outside the original ALS
+            // chain.
+            return loggerContext.run(FlowLogger.resolveReentryContext(options.context), execute);
+        }
+        return execute();
+    }
+    // Re-enters an existing FlowLogger context without emitting wrapper events.
+    // Use this when work already belongs to a known parent and needs AsyncLocalStorage set manually.
+    static withContext(context, fn) {
+        return loggerContext.run(FlowLogger.resolveReentryContext(context), fn);
+    }
+    // ===========================================================================
+    // CDP 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",
+    ]);
+    // Logs the start of a CDP command. CDP transport calls this before sending a
+    // message over the websocket so the eventual response can attach to it.
+    static logCdpCallEvent(context, data) {
+        return FlowLogger.logCdpEvent(context, "call", data);
+    }
+    // Logs the terminal response for a previously emitted CDP call event.
+    static logCdpResponseEvent(context, parentEvent, data) {
+        FlowLogger.logCdpEvent(context, data.error ? "responseError" : "response", data, [...parentEvent.eventParentIds, parentEvent.eventId]);
+    }
+    // Logs an unsolicited CDP message under the most recent related call event.
+    static logCdpMessageEvent(context, parentEvent, data) {
+        FlowLogger.logCdpEvent(context, "message", data, [
+            ...parentEvent.eventParentIds,
+            parentEvent.eventId,
+        ]);
+    }
+    // ===========================================================================
+    // LLM Events
+    // ===========================================================================
+    // Emits a best-effort LLM request event when logging occurs inside an active flow context.
+    static logLlmRequest({ requestId, model, prompt, }) {
+        FlowLogger.emitLlmEvent({
+            eventType: "LlmRequestEvent",
+            data: {
+                requestId,
+                model,
+                prompt,
+            },
+        });
+    }
+    // Emits a best-effort LLM response event when logging occurs inside an active flow context.
+    static logLlmResponse({ requestId, model, output, inputTokens, outputTokens, }) {
+        FlowLogger.emitLlmEvent({
+            eventType: "LlmResponseEvent",
+            data: {
+                requestId,
+                model,
+                output,
+                inputTokens,
+                outputTokens,
+            },
+        });
+    }
+    // ===========================================================================
+    // LLM Logging Middleware
+    // ===========================================================================
+    // Creates AI SDK middleware that wraps a generate call with FlowLogger LLM request/response events
+    // while leaving model execution behavior unchanged.
+    static createLlmLoggingMiddleware(modelId) {
+        return {
+            wrapGenerate: async ({ doGenerate, params }) => {
+                const llmRequestId = uuidv7();
+                FlowLogger.logLlmRequest({
+                    requestId: llmRequestId,
+                    model: modelId,
+                    prompt: FlowLogger.buildMiddlewarePromptSummary(params),
+                });
+                const result = await doGenerate();
+                const res = result;
+                FlowLogger.logLlmResponse({
+                    requestId: llmRequestId,
+                    model: modelId,
+                    output: FlowLogger.buildMiddlewareOutputSummary(res),
+                    inputTokens: result.usage?.inputTokens,
+                    outputTokens: result.usage?.outputTokens,
+                });
+                return result;
+            },
+        };
+    }
+}
+// Extracts text and image markers from an LLM content array.
+// This is shared by the request-summary helpers below so different provider message
+// shapes render consistently in the flow log.
+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`);
+        }
+        // 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;
+            }
+            result.extras.push(...nested.extras);
+        }
+    }
+    return result;
+}
+// Produces a single compact summary from a provider-specific message payload
+// so request and tool-result logs stay readable.
+function extractLlmMessageSummary(input, options) {
+    const result = {
+        text: undefined,
+        extras: [...(options?.extras ?? [])],
+    };
+    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;
+}
+// Formats the last user-facing prompt into the one-line form used by standard LLM request logs,
+// for example: `some text +{5.8kb image} +{schema}`.
+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. This accepts Anthropic, OpenAI, and Google-style payloads.
+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;
+    }
+}
+// Formats the response side of a CUA exchange into a single short log line.
+export function extractLlmCuaResponseSummary(output) {
+    try {
+        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]";
+    }
+}
+//# sourceMappingURL=FlowLogger.js.map