Real FlowLogger PR (several big commits were missing from #1824)
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.
what this PR does
This restores the intended v3 FlowLogger/EventStore design:
- every
V3instance owns exactly one FlowLogger session - every
V3instance owns exactly oneEventStore - 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
FlowEventmodel - the
FlowLoggerContextstored 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
V3creates the per-instanceFlowLoggerContext- instrumented methods enter through
wrapWithLogging(...)orrunWithLogging(...) - a started event is emitted
- that event is pushed onto
parentEvents - nested work inherits that parent stack through ALS
- completed/error events are emitted on unwind
V3.close()clears the in-memory flow context
EventStore lifecycle
V3creates oneEventStore(sessionId, opts)- the default shallow in-memory query sink is attached immediately
- optional sinks are attached based on runtime config
V3forwards wildcard bus events into the storedestroy()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: 2BROWSERBASE_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_DIRis set
Behavior:
JsonlFileEventSinkwrites full events tosession_events.jsonlPrettyLogFileEventSinkwrites prettified lines tosession_events.logsession.jsonis written with sanitized optionssessions/latestis maintained best-effort- file sinks are write-only;
query()returns[]
queryable in-memory history
Default behavior:
- EventStore attaches a
ShallowInMemoryEventSink - retention limit is
500events per session - retained events keep ancestry metadata only
- retained
datais 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
V3instance - 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
InMemoryEventSinkexplicitly 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.actV3.extractV3.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
V3instance/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
sessionIdoften matchesbrowserbaseSessionIdtoday, 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