# 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.
<img width="1569" height="1015" alt="image"
src="https://github.com/user-attachments/assets/f99171fe-27df-488c-a87a-75605c2a3c1b"
/>
## 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 `FlowEvent`s 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
---------
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>