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

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

@@ -0,0 +1,44 @@
+import { FlowEvent } from "./FlowLogger.js";
+import type { EventStoreApi, EventStoreQuery } from "./EventStore.js";
+export interface EventSink {
+    emit(event: FlowEvent): Promise<void>;
+    query(query: EventStoreQuery): Promise<FlowEvent[]>;
+    destroy(): Promise<void>;
+}
+declare abstract class FileEventSink implements EventSink {
+    private readonly streamPromise;
+    constructor(sessionDirPromise: Promise<string | null>, fileName: string);
+    protected abstract serialize(event: FlowEvent): Promise<string | null>;
+    emit(event: FlowEvent): Promise<void>;
+    query(): Promise<FlowEvent[]>;
+    destroy(): Promise<void>;
+}
+export declare class JsonlFileEventSink extends FileEventSink {
+    constructor(sessionDirPromise: Promise<string | null>);
+    protected serialize(event: FlowEvent): Promise<string>;
+}
+export declare class PrettyLogFileEventSink extends FileEventSink {
+    private readonly store;
+    constructor(sessionDirPromise: Promise<string | null>, store: Pick<EventStoreApi, "query">);
+    protected serialize(event: FlowEvent): Promise<string | null>;
+}
+export declare class PrettyStderrEventSink implements EventSink {
+    private readonly store;
+    constructor(store: Pick<EventStoreApi, "query">);
+    emit(event: FlowEvent): Promise<void>;
+    query(): Promise<FlowEvent[]>;
+    destroy(): Promise<void>;
+}
+export declare class InMemoryEventSink implements EventSink {
+    protected readonly limit: number;
+    constructor(limit?: number);
+    protected readonly events: FlowEvent[];
+    protected storeEvent(event: FlowEvent): FlowEvent;
+    emit(event: FlowEvent): Promise<void>;
+    query(query: EventStoreQuery): Promise<FlowEvent[]>;
+    destroy(): Promise<void>;
+}
+export declare class ShallowInMemoryEventSink extends InMemoryEventSink {
+    protected storeEvent(event: FlowEvent): FlowEvent;
+}
+export {};

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

@@ -0,0 +1,206 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FlowEvent } from "./FlowLogger.js";
+import { prettifyColorStderrLine, prettifyEvent, prettifyIsCdpEvent, prettifySanitizeEvent, } from "./prettify.js";
+// Checks whether an event matches a query used by queryable sinks. `eventId` matches both the event itself and descendants of that event.
+function matchesEventStoreQuery(event, query) {
+    if (query.sessionId && event.sessionId !== query.sessionId)
+        return false;
+    if (query.eventId) {
+        const matchesEvent = event.eventId === query.eventId ||
+            event.eventParentIds.includes(query.eventId);
+        if (!matchesEvent) {
+            return false;
+        }
+    }
+    if (query.eventType) {
+        const pattern = new RegExp(`^${query.eventType
+            .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+            .replace(/\\\*/g, ".*")}$`);
+        if (!pattern.test(event.eventType)) {
+            return false;
+        }
+    }
+    return true;
+}
+// =============================================================================
+// File Sink Helpers
+// =============================================================================
+// Returns true when a file sink's stream is still open and writable.
+function isWritable(stream) {
+    return !!(stream && !stream.destroyed && stream.writable);
+}
+// Writes a serialized event to a file sink and converts callback-style stream completion into a promise.
+function writeToStream(stream, value) {
+    return new Promise((resolve, reject) => {
+        try {
+            stream.write(value, (error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+}
+// =============================================================================
+// Event Sink Implementations
+// =============================================================================
+class FileEventSink {
+    streamPromise; // Lazily opens the one file stream owned by this sink when the session directory resolves.
+    // Creates a best-effort file sink bound to a single session directory.
+    constructor(sessionDirPromise, fileName) {
+        this.streamPromise = sessionDirPromise.then((sessionDir) => sessionDir
+            ? fs.createWriteStream(path.join(sessionDir, fileName), { flags: "a" })
+            : null);
+    }
+    // Serializes and appends a single event. File sinks are intentionally best-effort and never allowed to affect library execution flow.
+    async emit(event) {
+        try {
+            const stream = await this.streamPromise;
+            if (!isWritable(stream)) {
+                return;
+            }
+            const serialized = await this.serialize(event);
+            if (!serialized) {
+                return;
+            }
+            await writeToStream(stream, serialized);
+        }
+        catch {
+            // best effort only
+        }
+    }
+    // File sinks are write-only and do not support query reads.
+    async query() {
+        return [];
+    }
+    // Closes the underlying file stream when the owning store shuts down.
+    async destroy() {
+        const stream = await this.streamPromise.catch(() => null);
+        if (!isWritable(stream)) {
+            return;
+        }
+        await new Promise((resolve) => {
+            stream.end(resolve);
+        });
+    }
+}
+export class JsonlFileEventSink extends FileEventSink {
+    // Writes full verbatim events to `session_events.jsonl`.
+    constructor(sessionDirPromise) {
+        super(sessionDirPromise, "session_events.jsonl");
+    }
+    // Serializes the full event for lossless machine-readable storage.
+    async serialize(event) {
+        return `${JSON.stringify(event)}\n`;
+    }
+}
+export class PrettyLogFileEventSink extends FileEventSink {
+    store;
+    // Writes human-readable pretty lines to `session_events.log`.
+    constructor(sessionDirPromise, store) {
+        super(sessionDirPromise, "session_events.log");
+        this.store = store;
+    }
+    // Pretty-prints the event using recent in-memory ancestry.
+    async serialize(event) {
+        const line = await prettifyEvent(this.store, prettifySanitizeEvent(event));
+        return line ? `${line}\n` : null;
+    }
+}
+export class PrettyStderrEventSink {
+    store;
+    // Writes pretty lines to stderr for verbose local debugging. CDP events are intentionally omitted here to keep stderr high-signal.
+    constructor(store) {
+        this.store = store;
+    } // Queried during prettification so stderr lines can include recent ancestry tags.
+    // Best-effort stderr writer used only for interactive debugging output.
+    async emit(event) {
+        try {
+            if (prettifyIsCdpEvent(event)) {
+                return;
+            }
+            const line = await prettifyEvent(this.store, prettifySanitizeEvent(event));
+            if (!line) {
+                return;
+            }
+            await new Promise((resolve, reject) => {
+                try {
+                    process.stderr.write(`${prettifyColorStderrLine(line)}\n`, (error) => {
+                        if (error) {
+                            reject(error);
+                            return;
+                        }
+                        resolve();
+                    });
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        }
+        catch {
+            // best effort only
+        }
+    }
+    // Stderr sink is write-only and does not support query reads.
+    async query() {
+        return [];
+    }
+    // No teardown is required for stderr.
+    async destroy() { }
+}
+export class InMemoryEventSink {
+    limit;
+    // Retains recent events for query lookups. Tests usually attach this sink explicitly when they need full historical payloads.
+    constructor(limit = Infinity) {
+        this.limit = limit;
+    }
+    events = []; // Retained history; `emit()` appends to it and trims old entries when `limit` is exceeded.
+    // Gives subclasses a hook to transform events before they are retained.
+    storeEvent(event) {
+        return event;
+    }
+    // Stores a new event and trims the oldest retained entries once the sink exceeds its configured limit.
+    async emit(event) {
+        this.events.push(this.storeEvent(event));
+        if (this.events.length > this.limit) {
+            this.events.splice(0, this.events.length - this.limit);
+        }
+    }
+    // Returns retained events that match the query, ordered by creation time.
+    async query(query) {
+        const filtered = this.events.filter((event) => matchesEventStoreQuery(event, query));
+        filtered.sort((left, right) => {
+            const createdAtOrder = left.eventCreatedAt.localeCompare(right.eventCreatedAt);
+            if (createdAtOrder !== 0) {
+                return createdAtOrder;
+            }
+            return left.eventId.localeCompare(right.eventId);
+        });
+        return query.limit ? filtered.slice(-query.limit) : filtered;
+    }
+    // Clears retained history when the owning store shuts down.
+    async destroy() {
+        this.events.length = 0;
+    }
+}
+export class ShallowInMemoryEventSink extends InMemoryEventSink {
+    // Retains only ancestry metadata for the default query sink so verbose or long-running sessions do not hold onto large payloads such as screenshots.
+    storeEvent(event) {
+        return new FlowEvent({
+            eventType: event.eventType,
+            eventId: event.eventId,
+            eventCreatedAt: event.eventCreatedAt,
+            sessionId: event.sessionId,
+            eventParentIds: [...event.eventParentIds],
+            data: {},
+        });
+    }
+}
+//# sourceMappingURL=EventSink.js.map

package/dist/esm/lib/v3/flowlogger/EventSink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventSink.js","sourceRoot":"","sources":["../../../../../lib/v3/flowlogger/EventSink.ts"],"names":[],"mappings":"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","sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { FlowEvent } from \"./FlowLogger.js\";\nimport type { EventStoreApi, EventStoreQuery } from \"./EventStore.js\";\nimport {\n  prettifyColorStderrLine,\n  prettifyEvent,\n  prettifyIsCdpEvent,\n  prettifySanitizeEvent,\n} from \"./prettify.js\";\n\n// =============================================================================\n// Event Sink Contracts\n// =============================================================================\n\nexport interface EventSink {\n  emit(event: FlowEvent): Promise<void>;\n  query(query: EventStoreQuery): Promise<FlowEvent[]>;\n  destroy(): Promise<void>;\n}\n\n// Checks whether an event matches a query used by queryable sinks. `eventId` matches both the event itself and descendants of that event.\nfunction matchesEventStoreQuery(\n  event: FlowEvent,\n  query: EventStoreQuery,\n): boolean {\n  if (query.sessionId && event.sessionId !== query.sessionId) return false;\n\n  if (query.eventId) {\n    const matchesEvent =\n      event.eventId === query.eventId ||\n      event.eventParentIds.includes(query.eventId);\n    if (!matchesEvent) {\n      return false;\n    }\n  }\n\n  if (query.eventType) {\n    const pattern = new RegExp(\n      `^${query.eventType\n        .replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\")\n        .replace(/\\\\\\*/g, \".*\")}$`,\n    );\n    if (!pattern.test(event.eventType)) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\n// =============================================================================\n// File Sink Helpers\n// =============================================================================\n\n// Returns true when a file sink's stream is still open and writable.\nfunction isWritable(stream: fs.WriteStream | null): stream is fs.WriteStream {\n  return !!(stream && !stream.destroyed && stream.writable);\n}\n\n// Writes a serialized event to a file sink and converts callback-style stream completion into a promise.\nfunction writeToStream(stream: fs.WriteStream, value: string): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    try {\n      stream.write(value, (error?: Error | null) => {\n        if (error) {\n          reject(error);\n          return;\n        }\n        resolve();\n      });\n    } catch (error) {\n      reject(error);\n    }\n  });\n}\n\n// =============================================================================\n// Event Sink Implementations\n// =============================================================================\n\nabstract class FileEventSink implements EventSink {\n  private readonly streamPromise: Promise<fs.WriteStream | null>; // Lazily opens the one file stream owned by this sink when the session directory resolves.\n\n  // Creates a best-effort file sink bound to a single session directory.\n  constructor(sessionDirPromise: Promise<string | null>, fileName: string) {\n    this.streamPromise = sessionDirPromise.then((sessionDir) =>\n      sessionDir\n        ? fs.createWriteStream(path.join(sessionDir, fileName), { flags: \"a\" })\n        : null,\n    );\n  }\n\n  protected abstract serialize(event: FlowEvent): Promise<string | null>;\n\n  // Serializes and appends a single event. File sinks are intentionally best-effort and never allowed to affect library execution flow.\n  async emit(event: FlowEvent): Promise<void> {\n    try {\n      const stream = await this.streamPromise;\n      if (!isWritable(stream)) {\n        return;\n      }\n\n      const serialized = await this.serialize(event);\n      if (!serialized) {\n        return;\n      }\n\n      await writeToStream(stream, serialized);\n    } catch {\n      // best effort only\n    }\n  }\n\n  // File sinks are write-only and do not support query reads.\n  async query(): Promise<FlowEvent[]> {\n    return [];\n  }\n\n  // Closes the underlying file stream when the owning store shuts down.\n  async destroy(): Promise<void> {\n    const stream = await this.streamPromise.catch((): null => null);\n    if (!isWritable(stream)) {\n      return;\n    }\n\n    await new Promise<void>((resolve) => {\n      stream.end(resolve);\n    });\n  }\n}\n\nexport class JsonlFileEventSink extends FileEventSink {\n  // Writes full verbatim events to `session_events.jsonl`.\n  constructor(sessionDirPromise: Promise<string | null>) {\n    super(sessionDirPromise, \"session_events.jsonl\");\n  }\n\n  // Serializes the full event for lossless machine-readable storage.\n  protected async serialize(event: FlowEvent): Promise<string> {\n    return `${JSON.stringify(event)}\\n`;\n  }\n}\n\nexport class PrettyLogFileEventSink extends FileEventSink {\n  // Writes human-readable pretty lines to `session_events.log`.\n  constructor(\n    sessionDirPromise: Promise<string | null>,\n    private readonly store: Pick<EventStoreApi, \"query\">, // Queried during prettification so each line can recover recent ancestry tags.\n  ) {\n    super(sessionDirPromise, \"session_events.log\");\n  }\n\n  // Pretty-prints the event using recent in-memory ancestry.\n  protected async serialize(event: FlowEvent): Promise<string | null> {\n    const line = await prettifyEvent(this.store, prettifySanitizeEvent(event));\n    return line ? `${line}\\n` : null;\n  }\n}\n\nexport class PrettyStderrEventSink implements EventSink {\n  // Writes pretty lines to stderr for verbose local debugging. CDP events are intentionally omitted here to keep stderr high-signal.\n  constructor(private readonly store: Pick<EventStoreApi, \"query\">) {} // Queried during prettification so stderr lines can include recent ancestry tags.\n\n  // Best-effort stderr writer used only for interactive debugging output.\n  async emit(event: FlowEvent): Promise<void> {\n    try {\n      if (prettifyIsCdpEvent(event)) {\n        return;\n      }\n\n      const line = await prettifyEvent(\n        this.store,\n        prettifySanitizeEvent(event),\n      );\n      if (!line) {\n        return;\n      }\n\n      await new Promise<void>((resolve, reject) => {\n        try {\n          process.stderr.write(\n            `${prettifyColorStderrLine(line)}\\n`,\n            (error?: Error | null) => {\n              if (error) {\n                reject(error);\n                return;\n              }\n              resolve();\n            },\n          );\n        } catch (error) {\n          reject(error);\n        }\n      });\n    } catch {\n      // best effort only\n    }\n  }\n\n  // Stderr sink is write-only and does not support query reads.\n  async query(): Promise<FlowEvent[]> {\n    return [];\n  }\n\n  // No teardown is required for stderr.\n  async destroy(): Promise<void> {}\n}\n\nexport class InMemoryEventSink implements EventSink {\n  // Retains recent events for query lookups. Tests usually attach this sink explicitly when they need full historical payloads.\n  constructor(protected readonly limit = Infinity) {}\n\n  protected readonly events: FlowEvent[] = []; // Retained history; `emit()` appends to it and trims old entries when `limit` is exceeded.\n\n  // Gives subclasses a hook to transform events before they are retained.\n  protected storeEvent(event: FlowEvent): FlowEvent {\n    return event;\n  }\n\n  // Stores a new event and trims the oldest retained entries once the sink exceeds its configured limit.\n  async emit(event: FlowEvent): Promise<void> {\n    this.events.push(this.storeEvent(event));\n    if (this.events.length > this.limit) {\n      this.events.splice(0, this.events.length - this.limit);\n    }\n  }\n\n  // Returns retained events that match the query, ordered by creation time.\n  async query(query: EventStoreQuery): Promise<FlowEvent[]> {\n    const filtered = this.events.filter((event) =>\n      matchesEventStoreQuery(event, query),\n    );\n    filtered.sort((left, right) => {\n      const createdAtOrder = left.eventCreatedAt.localeCompare(\n        right.eventCreatedAt,\n      );\n      if (createdAtOrder !== 0) {\n        return createdAtOrder;\n      }\n\n      return left.eventId.localeCompare(right.eventId);\n    });\n    return query.limit ? filtered.slice(-query.limit) : filtered;\n  }\n\n  // Clears retained history when the owning store shuts down.\n  async destroy(): Promise<void> {\n    this.events.length = 0;\n  }\n}\n\nexport class ShallowInMemoryEventSink extends InMemoryEventSink {\n  // Retains only ancestry metadata for the default query sink so verbose or long-running sessions do not hold onto large payloads such as screenshots.\n  protected override storeEvent(event: FlowEvent): FlowEvent {\n    return new FlowEvent({\n      eventType: event.eventType,\n      eventId: event.eventId,\n      eventCreatedAt: event.eventCreatedAt,\n      sessionId: event.sessionId,\n      eventParentIds: [...event.eventParentIds],\n      data: {},\n    });\n  }\n}\n"]}

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

@@ -0,0 +1,26 @@
+import type { V3Options } from "../types/public/index.js";
+import { EventSink } from "./EventSink.js";
+import { FlowEvent } from "./FlowLogger.js";
+export interface EventStoreQuery {
+    sessionId?: string;
+    eventId?: string;
+    eventType?: string;
+    limit?: number;
+}
+export interface EventStoreApi {
+    readonly sessionId: string;
+    emit(event: FlowEvent): Promise<void>;
+    query(query: EventStoreQuery): Promise<FlowEvent[]>;
+    destroy(): Promise<void>;
+}
+export declare function getConfigDir(): string;
+export declare class EventStore implements EventStoreApi {
+    readonly sessionId: string;
+    private readonly sinks;
+    private destroyed;
+    query: (query: EventStoreQuery) => Promise<FlowEvent[]>;
+    constructor(sessionId: string, options?: V3Options, querySink?: EventSink);
+    private registerSink;
+    emit: (event: FlowEvent) => Promise<void>;
+    destroy(): Promise<void>;
+}

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

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import path from "node:path";
+import { JsonlFileEventSink, PrettyLogFileEventSink, PrettyStderrEventSink, ShallowInMemoryEventSink, } from "./EventSink.js";
+import { FlowEvent } from "./FlowLogger.js";
+const DEFAULT_IN_MEMORY_EVENT_LIMIT = 500; // Per-session ancestry window retained by the default shallow query sink.
+const CONFIG_DIR = process.env.BROWSERBASE_CONFIG_DIR || ""; // Base directory for session metadata + file-backed flow logs.
+const FLOW_LOGS_ENABLED = process.env.BROWSERBASE_FLOW_LOGS === "1"; // Force-enables the pretty stderr flow sink even when `verbose !== 2`.
+const SENSITIVE_KEYS = /key|secret|token|api-key|apikey|api_key|password|passwd|pwd|credential|auth/i; // Redacts obvious secrets before session options are written to disk.
+// =============================================================================
+// Filesystem Helpers
+// =============================================================================
+// Redacts secrets before session options are written to `session.json` inside a config-dir-backed session directory.
+function sanitizeOptions(options) {
+    const sanitize = (value) => {
+        if (typeof value !== "object" || value === null)
+            return value;
+        if (Array.isArray(value))
+            return value.map(sanitize);
+        const result = {};
+        for (const [key, entry] of Object.entries(value)) {
+            result[key] = SENSITIVE_KEYS.test(key) ? "******" : sanitize(entry);
+        }
+        return result;
+    };
+    return sanitize({ ...options });
+}
+// Resolves the configured Browserbase config directory used by file sinks.
+export function getConfigDir() {
+    return CONFIG_DIR ? path.resolve(CONFIG_DIR) : "";
+}
+// Creates the per-session directory used by file sinks and writes best-effort metadata such as the sanitized `session.json` file and `latest` symlink.
+async function createSessionDir(sessionId, options) {
+    const configDir = getConfigDir();
+    if (!configDir) {
+        return null;
+    }
+    const sessionDir = path.join(configDir, "sessions", sessionId);
+    await fs.promises.mkdir(sessionDir, { recursive: true });
+    if (options) {
+        await fs.promises.writeFile(path.join(sessionDir, "session.json"), JSON.stringify(sanitizeOptions(options), null, 2), "utf-8");
+    }
+    const latestLink = path.join(configDir, "sessions", "latest");
+    try {
+        try {
+            await fs.promises.unlink(latestLink);
+        }
+        catch {
+            // ignore missing link
+        }
+        await fs.promises.symlink(sessionId, latestLink, "dir");
+    }
+    catch {
+        // symlink best effort only
+    }
+    return sessionDir;
+}
+// =============================================================================
+// Event Store
+// =============================================================================
+// Per-session flow event sink manager.
+// This is not an event bus. V3 forwards already-emitted FlowEvents into it so
+// the store can fan them out to configured sinks, answer `query()` calls from
+// its one query sink, and tear down its sinks when the session closes.
+// We keep this as a separate object instead of wiring sinks directly with
+// `v3.bus.on("*", sink.emit)` because pretty sinks need access to a shared
+// query interface while rendering. Prettified lines often need to look up
+// related parent/child events to recover the readable ancestry tags and labels.
+// Passing sinks into each other to share that state gets messy quickly, so the
+// EventStore contains the circular dependency: all sinks live here, and any
+// sink that needs historical context can call the one `EventStore.query()`
+// entrypoint backed by the main query sink for this session.
+export class EventStore {
+    sessionId;
+    sinks = new Set(); // All sinks attached for this session; constructor registers them here and `destroy()` tears them down.
+    destroyed = false; // Flipped by `destroy()` so later emits and teardown calls become no-ops.
+    query; // Always reads from the one query sink chosen at construction time.
+    // Creates the per-instance store owned by a single V3 session. This store is intentionally single-session; it ignores events for other session ids.
+    constructor(
+    // Usually matches `browserbaseSessionId` today, but it is the store's own Stagehand session identifier and may diverge in the future.
+    sessionId, options, querySink = new ShallowInMemoryEventSink(DEFAULT_IN_MEMORY_EVENT_LIMIT)) {
+        this.sessionId = sessionId;
+        const sessionDirPromise = createSessionDir(sessionId, options);
+        this.registerSink(querySink);
+        this.query = async (query) => {
+            if (query.sessionId && query.sessionId !== this.sessionId) {
+                return [];
+            }
+            return querySink.query({
+                ...query,
+                sessionId: this.sessionId,
+            });
+        };
+        if (getConfigDir()) {
+            this.registerSink(new JsonlFileEventSink(sessionDirPromise));
+            this.registerSink(new PrettyLogFileEventSink(sessionDirPromise, this));
+        }
+        if (options?.verbose === 2 || FLOW_LOGS_ENABLED) {
+            this.registerSink(new PrettyStderrEventSink(this));
+        }
+    }
+    // Adds a sink to the direct fanout list used by `emit()`.
+    registerSink(sink) {
+        this.sinks.add(sink);
+    }
+    // Emits an event to all attached sinks when it belongs to this store's single session.
+    emit = async (event) => {
+        if (!(event instanceof FlowEvent)) {
+            return;
+        }
+        if (this.destroyed || event.sessionId !== this.sessionId) {
+            return;
+        }
+        await Promise.allSettled([...this.sinks].map((sink) => sink.emit(event)));
+    };
+    // Tears down all sinks when the V3 instance is closed.
+    async destroy() {
+        if (this.destroyed) {
+            return;
+        }
+        this.destroyed = true;
+        await Promise.all([...this.sinks].map((sink) => sink.destroy().catch(() => {
+            // best effort cleanup
+        })));
+        this.sinks.clear();
+    }
+}
+//# sourceMappingURL=EventStore.js.map

package/dist/esm/lib/v3/flowlogger/EventStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventStore.js","sourceRoot":"","sources":["../../../../../lib/v3/flowlogger/EventStore.ts"],"names":[],"mappings":"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","sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport type { V3Options } from \"../types/public/index.js\";\nimport {\n  EventSink,\n  JsonlFileEventSink,\n  PrettyLogFileEventSink,\n  PrettyStderrEventSink,\n  ShallowInMemoryEventSink,\n} from \"./EventSink.js\";\nimport { FlowEvent } from \"./FlowLogger.js\";\n\nconst DEFAULT_IN_MEMORY_EVENT_LIMIT = 500; // Per-session ancestry window retained by the default shallow query sink.\nconst CONFIG_DIR = process.env.BROWSERBASE_CONFIG_DIR || \"\"; // Base directory for session metadata + file-backed flow logs.\nconst FLOW_LOGS_ENABLED = process.env.BROWSERBASE_FLOW_LOGS === \"1\"; // Force-enables the pretty stderr flow sink even when `verbose !== 2`.\nconst SENSITIVE_KEYS =\n  /key|secret|token|api-key|apikey|api_key|password|passwd|pwd|credential|auth/i; // Redacts obvious secrets before session options are written to disk.\n\n// =============================================================================\n// Public Contracts\n// =============================================================================\n\nexport interface EventStoreQuery {\n  sessionId?: string;\n  eventId?: string;\n  eventType?: string;\n  limit?: number;\n}\n\nexport interface EventStoreApi {\n  readonly sessionId: string;\n  emit(event: FlowEvent): Promise<void>;\n  query(query: EventStoreQuery): Promise<FlowEvent[]>;\n  destroy(): Promise<void>;\n}\n\n// =============================================================================\n// Filesystem Helpers\n// =============================================================================\n\n// Redacts secrets before session options are written to `session.json` inside a config-dir-backed session directory.\nfunction sanitizeOptions(options: V3Options): Record<string, unknown> {\n  const sanitize = (value: unknown): unknown => {\n    if (typeof value !== \"object\" || value === null) return value;\n    if (Array.isArray(value)) return value.map(sanitize);\n\n    const result: Record<string, unknown> = {};\n    for (const [key, entry] of Object.entries(value)) {\n      result[key] = SENSITIVE_KEYS.test(key) ? \"******\" : sanitize(entry);\n    }\n    return result;\n  };\n\n  return sanitize({ ...options }) as Record<string, unknown>;\n}\n\n// Resolves the configured Browserbase config directory used by file sinks.\nexport function getConfigDir(): string {\n  return CONFIG_DIR ? path.resolve(CONFIG_DIR) : \"\";\n}\n\n// Creates the per-session directory used by file sinks and writes best-effort metadata such as the sanitized `session.json` file and `latest` symlink.\nasync function createSessionDir(\n  sessionId: string,\n  options?: V3Options,\n): Promise<string | null> {\n  const configDir = getConfigDir();\n  if (!configDir) {\n    return null;\n  }\n\n  const sessionDir = path.join(configDir, \"sessions\", sessionId);\n  await fs.promises.mkdir(sessionDir, { recursive: true });\n\n  if (options) {\n    await fs.promises.writeFile(\n      path.join(sessionDir, \"session.json\"),\n      JSON.stringify(sanitizeOptions(options), null, 2),\n      \"utf-8\",\n    );\n  }\n\n  const latestLink = path.join(configDir, \"sessions\", \"latest\");\n  try {\n    try {\n      await fs.promises.unlink(latestLink);\n    } catch {\n      // ignore missing link\n    }\n    await fs.promises.symlink(sessionId, latestLink, \"dir\");\n  } catch {\n    // symlink best effort only\n  }\n\n  return sessionDir;\n}\n\n// =============================================================================\n// Event Store\n// =============================================================================\n\n// Per-session flow event sink manager.\n// This is not an event bus. V3 forwards already-emitted FlowEvents into it so\n// the store can fan them out to configured sinks, answer `query()` calls from\n// its one query sink, and tear down its sinks when the session closes.\n// We keep this as a separate object instead of wiring sinks directly with\n// `v3.bus.on(\"*\", sink.emit)` because pretty sinks need access to a shared\n// query interface while rendering. Prettified lines often need to look up\n// related parent/child events to recover the readable ancestry tags and labels.\n// Passing sinks into each other to share that state gets messy quickly, so the\n// EventStore contains the circular dependency: all sinks live here, and any\n// sink that needs historical context can call the one `EventStore.query()`\n// entrypoint backed by the main query sink for this session.\nexport class EventStore implements EventStoreApi {\n  private readonly sinks = new Set<EventSink>(); // All sinks attached for this session; constructor registers them here and `destroy()` tears them down.\n  private destroyed = false; // Flipped by `destroy()` so later emits and teardown calls become no-ops.\n  public query: (query: EventStoreQuery) => Promise<FlowEvent[]>; // Always reads from the one query sink chosen at construction time.\n\n  // Creates the per-instance store owned by a single V3 session. This store is intentionally single-session; it ignores events for other session ids.\n  constructor(\n    // Usually matches `browserbaseSessionId` today, but it is the store's own Stagehand session identifier and may diverge in the future.\n    public readonly sessionId: string,\n    options?: V3Options,\n    querySink: EventSink = new ShallowInMemoryEventSink(\n      DEFAULT_IN_MEMORY_EVENT_LIMIT,\n    ),\n  ) {\n    const sessionDirPromise = createSessionDir(sessionId, options);\n\n    this.registerSink(querySink);\n    this.query = async (query) => {\n      if (query.sessionId && query.sessionId !== this.sessionId) {\n        return [];\n      }\n\n      return querySink.query({\n        ...query,\n        sessionId: this.sessionId,\n      });\n    };\n\n    if (getConfigDir()) {\n      this.registerSink(new JsonlFileEventSink(sessionDirPromise));\n      this.registerSink(new PrettyLogFileEventSink(sessionDirPromise, this));\n    }\n\n    if (options?.verbose === 2 || FLOW_LOGS_ENABLED) {\n      this.registerSink(new PrettyStderrEventSink(this));\n    }\n  }\n\n  // Adds a sink to the direct fanout list used by `emit()`.\n  private registerSink(sink: EventSink): void {\n    this.sinks.add(sink);\n  }\n\n  // Emits an event to all attached sinks when it belongs to this store's single session.\n  emit = async (event: FlowEvent): Promise<void> => {\n    if (!(event instanceof FlowEvent)) {\n      return;\n    }\n\n    if (this.destroyed || event.sessionId !== this.sessionId) {\n      return;\n    }\n\n    await Promise.allSettled([...this.sinks].map((sink) => sink.emit(event)));\n  };\n\n  // Tears down all sinks when the V3 instance is closed.\n  async destroy(): Promise<void> {\n    if (this.destroyed) {\n      return;\n    }\n\n    this.destroyed = true;\n    await Promise.all(\n      [...this.sinks].map((sink) =>\n        sink.destroy().catch(() => {\n          // best effort cleanup\n        }),\n      ),\n    );\n    this.sinks.clear();\n  }\n}\n"]}

package/dist/{cjs/lib/v3/flowLogger.d.ts → esm/lib/v3/flowlogger/FlowLogger.d.ts}

@@ -1,27 +1,38 @@
-import { EventEmitter } from "node:events";
 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;
+import { z } from "zod";
+import { EventEmitterWithWildcardSupport } from "./EventEmitter.js";
+export declare const FlowEventDataSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const FlowEventInputSchema: z.ZodObject<{
+    eventType: z.ZodString;
+    eventId: z.ZodOptional<z.ZodString>;
+    eventParentIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    eventCreatedAt: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type FlowEventData = z.infer<typeof FlowEventDataSchema>;
+export type FlowEventInput = z.input<typeof FlowEventInputSchema>;
+type FlowEventFields = Omit<FlowEventInput, "eventId" | "eventParentIds" | "eventCreatedAt" | "sessionId" | "data"> & {
+    eventId: string;
+    eventParentIds: string[];
+    eventCreatedAt: string;
+    sessionId: string;
+    data: FlowEventData;
 };
-export declare class FlowEvent {
-    static createEventId(eventIdSuffix: string): string;
+export declare class FlowEvent implements FlowEventFields {
+    private static deriveEventIdSuffix;
+    static createEventId(eventType: string): string;
     eventType: string;
     eventId: string;
     eventParentIds: string[];
-    createdAt: string;
+    eventCreatedAt: string;
     sessionId: string;
     data: FlowEventData;
     constructor(input: FlowEventInput);
 }
 export interface FlowLoggerContext {
     sessionId: string;
-    eventBus: EventEmitter;
+    eventBus: EventEmitterWithWildcardSupport;
     parentEvents: FlowEvent[];
 }
 type AsyncOriginalMethod<TArgs extends unknown[] = unknown[], TResult = unknown, TThis = unknown> = (this: TThis, ...args: TArgs) => Promise<TResult>;
@@ -30,19 +41,22 @@ type FlowLoggerLogOptions = FlowEventInput & {
 };
 export declare class FlowLogger {
     private static cloneContext;
+    private static resolveReentryContext;
     private static emit;
     private static runWithAutoStatusEventLogging;
-    /**
-     * Initialize a new logging context. Call this at the start of a session.
-     */
-    static init(sessionId: string, eventBus: EventEmitter): FlowLoggerContext;
+    private static logCdpEvent;
+    private static emitLlmEvent;
+    private static buildMiddlewarePromptSummary;
+    private static buildMiddlewareOutputSummary;
+    static init(sessionId: string, eventBus: EventEmitterWithWildcardSupport): FlowLoggerContext;
     static close(context?: FlowLoggerContext | null): Promise<void>;
     static get currentContext(): FlowLoggerContext;
+    static resolveContext(fallbackContext?: FlowLoggerContext | null): FlowLoggerContext | null;
     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>>;
+    static withContext<T>(context: FlowLoggerContext, fn: () => T): T;
     private static readonly NOISY_CDP_EVENTS;
-    private static logCdpEvent;
     static logCdpCallEvent(context: FlowLoggerContext, data: {
         method: string;
         params?: object;
@@ -71,16 +85,8 @@ export declare class FlowLogger {
         inputTokens?: number;
         outputTokens?: number;
     }): void;
-    /**
-     * Create middleware for wrapping language models with LLM call logging.
-     * Returns a no-op middleware when logging is disabled.
-     */
     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}"
- */
 export declare function extractLlmPromptSummary(messages: Array<{
     role: string;
     content: unknown;
@@ -88,11 +94,6 @@ export declare function extractLlmPromptSummary(messages: Array<{
     toolCount?: number;
     hasSchema?: boolean;
 }): string | undefined;
-/**
- * Extract a text summary from CUA-style messages.
- * Accepts various message formats (Anthropic, OpenAI, Google).
- */
 export declare function extractLlmCuaPromptSummary(messages: unknown[]): string | undefined;
-/** Format a CUA response summary for logging */
 export declare function extractLlmCuaResponseSummary(output: unknown): string;
 export {};