Real FlowLogger PR (several big commits were missing from #1824)

Merged
PI
8mo ago
+4085-1518

why

This is the real, recovered FlowLogger PR + improvements based on yesterday's review session.

I accidentally force-pushed an earlier, incomplete branch state onto the original flow logger PR and dropped several days of work. This PR replaces that broken state with the actual recovered branch and the follow-up fixes needed to make the design correct again.

image

what this PR does

This restores the intended v3 FlowLogger/EventStore design:

  • every V3 instance owns exactly one FlowLogger session
  • every V3 instance owns exactly one EventStore
  • FlowLogger produces structured FlowEvents on the instance bus
  • EventStore consumes those events and fans them out to sinks
  • the default query history is shallow and bounded so logging does not grow memory without limit

The goal is a stable, queryable execution tree for Stagehand/agent/CDP/LLM work that preserves parent/child relationships, survives ALS re-entry, and does not let sink failures break main execution.

architecture

FlowLogger

packages/core/lib/v3/flowlogger/FlowLogger.ts

FlowLogger owns:

  • the FlowEvent model
  • the FlowLoggerContext stored in AsyncLocalStorage
  • method/closure wrappers: wrapWithLogging(...), runWithLogging(...)
  • re-entry helpers: withContext(...), resolveContext(...)
  • CDP event helpers
  • LLM request/response helpers and middleware

FlowLogger is the event producer. It is responsible for building the execution tree and maintaining the active parent stack. It is not responsible for persistence or output destinations.

EventStore

packages/core/lib/v3/flowlogger/EventStore.ts

EventStore owns:

  • per-session sink registration
  • query routing
  • file-backed session directory setup
  • bounded in-memory ancestry retention
  • store lifecycle and teardown

Sink implementations live in packages/core/lib/v3/flowlogger/EventSink.ts, and prettifying/sanitization lives in packages/core/lib/v3/flowlogger/prettify.ts.

EventStore is the consumer/router layer. It is intentionally per-instance and single-session.

V3 wiring

packages/core/lib/v3/v3.ts

In the V3 constructor:

  • this.eventStore = new EventStore(this.sessionId, opts)
  • this.flowLoggerContext = FlowLogger.init(this.sessionId, this.bus)
  • this.bus.on("*", this.eventStore.emit)

So FlowLogger always has a per-instance context, and the bus is the handoff point between FlowLogger and EventStore.

lifecycle

FlowLogger lifecycle

  1. V3 creates the per-instance FlowLoggerContext
  2. instrumented methods enter through wrapWithLogging(...) or runWithLogging(...)
  3. a started event is emitted
  4. that event is pushed onto parentEvents
  5. nested work inherits that parent stack through ALS
  6. completed/error events are emitted on unwind
  7. V3.close() clears the in-memory flow context

EventStore lifecycle

  1. V3 creates one EventStore(sessionId, opts)
  2. the default shallow in-memory query sink is attached immediately
  3. optional sinks are attached based on runtime config
  4. V3 forwards wildcard bus events into the store
  5. destroy() tears down the configured sinks

config / runtime options

always-on pieces

Every V3 instance always gets:

  • FlowLogger context
  • shared event bus
  • one EventStore
  • one default shallow in-memory query sink

So instrumentation exists even if no human-visible sink is active.

stderr sink

Enabled automatically when:

  • verbose: 2
  • BROWSERBASE_FLOW_LOGS=1

Behavior:

  • writes prettified logs to stderr
  • suppresses CDP events to keep interactive output high-signal
  • does not retain history
  • is best-effort only

file sinks

Enabled automatically when:

  • BROWSERBASE_CONFIG_DIR is set

Behavior:

  • JsonlFileEventSink writes full events to session_events.jsonl
  • PrettyLogFileEventSink writes prettified lines to session_events.log
  • session.json is written with sanitized options
  • sessions/latest is maintained best-effort
  • file sinks are write-only; query() returns []

queryable in-memory history

Default behavior:

  • EventStore attaches a ShallowInMemoryEventSink
  • retention limit is 500 events per session
  • retained events keep ancestry metadata only
  • retained data is intentionally stripped in the default sink

That shallow history is what pretty formatting uses to recover recent ancestry without retaining screenshots/base64 payloads forever.

memory impact

The main memory constraint is the default query sink.

What it retains:

  • up to 500 recent shallow events per V3 instance
  • ids, timestamps, event types, parent ids, session id

What it does not retain by default:

  • full screenshots
  • large base64 blobs
  • full historical payloads

Implications:

  • memory scales roughly with number_of_sessions * 500 shallow events
  • stderr sink does not retain history
  • file sinks do not materially retain history in process memory beyond normal stream buffering
  • attaching InMemoryEventSink explicitly is an opt-in to full-payload retention

usage patterns

use wrapWithLogging(...)

For class methods that should emit their own started/completed/error envelope:

  • V3.act
  • V3.extract
  • V3.observe
  • page/understudy methods
  • agent execute entrypoints

use runWithLogging(...)

For closures or non-decorator code paths that still need a lifecycle envelope.

use withContext(...) / resolveContext(...)

For callback-driven or later async work:

  • websocket callbacks
  • CDP response/message dispatch
  • detached async continuations

currentContext is strict and may throw when ALS is missing. resolveContext(...) is the non-throwing lookup for “active ALS if present, otherwise instance-owned fallback”.

LLM logging is best-effort

If no flow context is active, LLM logging should no-op. Missing context must not break model execution.

reviewer expectations / edge cases

Please review this PR with these expectations in mind:

  • ALS can legitimately be missing in later callbacks or detached async work; that should not break execution unless a caller explicitly uses strict currentContext
  • there should be no global or multi-session fallback store; logging belongs to a real V3 instance/session
  • parent-chain correctness matters more than sink behavior; events must land under the right parent chain
  • sink failures should not break the main library; sinks are intentionally best-effort
  • completion/error pretty lines should resolve back to the original started-event ancestry, not synthetic completion ids
  • sessionId often matches browserbaseSessionId today, but code should not rely on that as a permanent invariant
  • this PR is about FlowLogger/EventStore architecture and correctness, not a model-default migration