[kernel-1116] browser logging: Event Schema & Pipeline

[archandatta]

Note

Medium Risk
Adds a new concurrent event ingestion pipeline with file I/O and truncation behavior; risks are mainly around correctness under load (dropped-event signaling, write ordering, and silent file-write failures).

Overview
Introduces a new server/lib/events package implementing the browser logging pipeline end-to-end: a canonical BrowserEvent schema with category routing and size-based truncation, a non-blocking fan-out RingBuffer that can emit a synthetic events_dropped event when readers fall behind, and a per-category JSONL FileWriter that lazily opens and appends to *.log files.

Adds a Pipeline wrapper that stamps CaptureSessionID, monotonic Seq, and Ts, applies truncation before both sinks, writes durably to disk before publishing in-memory, and provides reader subscriptions; comprehensive tests cover JSON encoding, routing, concurrency, overflow/drop behavior, and truncation limits.

^{Written by Cursor Bugbot for commit 29f2bbf. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

RingBuffer count field is maintained but never read

Low Severity

The count field in RingBuffer is declared, incremented in Publish, but its value is never consumed by any reader-facing logic. The oldestSeq function — the only place that needs to know buffer occupancy — derives the answer from written and len(rb.buf) instead. This makes count dead state that adds confusion about the ring buffer's invariants.

Additional Locations (1)

• server/lib/events/ringbuffer.go#L37-L39

 

[rgarcia]

nice direction on the pipeline/schema. one thing i'd consider before cementing BrowserEvent v1: if this is eventually going to drive both capture controls (for example: "turn on cdp console only" or "turn on network request/response capture at headers-only detail") and subscriptions, it might be worth making those selector dimensions first-class in the envelope instead of encoding too much into a single type string.

concretely, i think i'd lean toward:

• keeping the primary event identity semantic, e.g. console.log, network.request, input.click
• adding explicit provenance fields like source_kind (cdp, kernel_api, extension, local_process) plus source_name / source_event (for example Runtime.consoleAPICalled)
• adding an explicit detail_level (minimal, default, verbose, raw)
• possibly making category first-class too instead of deriving it from the type prefix

i probably would not use raw Runtime.* / Network.* as the primary type, since that makes future non-cdp producers feel awkward/second-class. i think the semantic-type + provenance split ages better if we later want to emit events from things like:

• third-party extensions running in the browser and talking to localhost
• vm-local helper processes/programs running alongside the browser
• server/api-driven tool actions like screenshot/input/recording events

that shape also gives the system a much more natural control surface for both capture config and subscriptions, since selectors can operate directly on stable fields like category, topic, source_kind, and detail_level instead of needing to parse overloaded event names.

[Sayan-]

focused review on the pipeline since raf had some feedback to the event schema!

[Sayan-]

makes sense to handroll. the combination of non-blocking writes with eviction, multi-reader fan-out with independent positions, synthetic drop notification, and context-aware blocking reads is pretty niche, no standard Go library covers it without significant wrapping.

[Sayan-]

doc comment says "serialises concurrent writes within a category" but the mutex is global across all categories. worth either making the comment accurate or switching to per-category mutexes.

[Sayan-]

nit: the bytes.Buffer alloc per write is unnecessary since we're under the mutex. can just f.Write(data) + f.Write([]byte{'\n'}) directly.

[Sayan-]

would be good to add a test where publishing and reading happen in parallel to exercise the locking/contention paths under go test -race.