RFC: browser event capture

[rgarcia]

Summary

Design document for a configurable browser event streaming system on the image server.

• Captures CDP events (console, network, DOM, layout shifts, screenshots, interactions) via raw WebSocket to Chrome
• Tags every event with tab/frame/target context (session ID, target ID, frame ID) using Target.setAutoAttach with flatten: true
• Computes meta-events for smart waiting: network_idle, layout_settled, navigation_settled (composite of dom_content_loaded + network_idle + layout_settled)
• Dual-writes events to S2 streams (durable, multi-consumer) and a local ring buffer (SSE endpoint)
• All capture is off by default; turned on/reconfigured via POST /events/start with a config body
• Events capped at 1MB (S2 limit); large network response bodies truncated with a truncated flag

The full RFC is in .cursor/plans/2026-02-05-events.md. Also adds devtools-protocol/ as a reference for CDP domain definitions.

Test plan

• Review RFC for completeness and correctness
• Validate event schema covers agent use cases
• Validate computed settling signals are useful wait primitives
• Confirm S2 integration approach matches existing kernel patterns

Made with Cursor

---

Note

Low Risk
Documentation-only change that adds no runtime code or API surface; low risk aside from potentially setting expectations for future implementation.

Overview
Adds a new RFC document (.cursor/plans/2026-02-05-events.md) describing a proposed browser event capture/streaming system for the image server.

The doc specifies the intended event schema, capture configuration and endpoints (/events/start, /events/stop, /events/stream), computed “settling” events, multi-target CDP strategy, screenshot/S2 streaming approach, and a planned testing matrix.

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