RFC 015 — Browser Event Source for ChatOps

Approved ChatOps extension

• Tracking ticket: backlogpending015rfcbrowsereventsource.md
• Depends on:
  • RFC 003 — Common Event Schema (Approved, 20260408) — extended here with koder.browser.* event types
  • RFC 004 — Common Control Plane (Approved) — defines the koder-jet admin API used to enable/disable browser tap per site
  • RFC 007 — ChatOps Pipeline (Approved, 20260414) — this RFC adds a third event source to the pipeline defined there
• Implementation home: infra/jet (injection + ingestion + enrichment) and platform/kortex (event ingestion + new chatops rules)
• Status: Approved (20260414)

1. Summary

This RFC defines the Browser Event Source — a new upstream for the Kortex ChatOps pipeline that captures clientside errors automatically and proactively from every web application served by `koderjet. It is the third event source after observe/log (server-side logs) and kodertalk` (chat screenshots), and it closes the "clientside blind spot" explicitly identified in RFC 007 §2.3.

The mechanism is straightforward: koder-jet, the reverse proxy that fronts every Koder web property, injects a small JavaScript payload (tap.js, ~35 KiB minified + gzipped) into every HTML response. The payload installs error listeners (window.onerror, unhandledrejection, console wrapping, ResourceTiming, CSP violations, Web Vitals) and beacons batched events back to a jetserved endpoint. Jet enriches each event with deployment context (service name, version, deploy id, environment), scrubs PII, deduplicates floods, and forwards to Kortex Senses as standard OTLP events with the new koder.browser.* event type family.

The key design principles are:

1. Proactive over reactive. Browser events are captured automatically, without the user having to remember to send a screenshot. Most users hit a bug and abandon the page; the bug is gone unless we caught it in the browser.
2. Zero application code. The mechanism is reverseproxylevel. Application teams do not need to install an SDK, link a library, or change their build. Optin is persite in sites.toml, applies immediately to the next request.
3. OTLP all the way. The wire format follows RFC 003 — Common Event Schema. No bespoke protocol. Events flow into Kortex Senses on the same OTLP endpoints already in production.
4. Privacy by default. No URL query strings, no input values, no cookies, no localStorage. Stack traces are resolved serverside via private source maps so the maps never leave the jet host. PII scrubbing happens before the event leaves the user's network in the case of selfhosted deployments.
5. Bounded cost. Persite sampling, pererror rate limiting, and per-user circuit breaking ensure that an application bug that triggers thousands of console errors per second cannot fill the Kortex queue or run up an LLM bill.

The output is a new, fully-supported source feeding RFC 007's existing chatops rules engine. The same autonomous/supervised mode switching, the same Kode invocation, the same chat feedback loop. From the rules engine's perspective, a koder.browser.error event is just another input — the same downstream pipeline that handles screenshot reports handles JS exceptions.

1.1 The pipeline at a glance

[ Browser ]                                          [ koder-jet ]                  [ Kortex Senses ]
   │                                                       │                              │
   │  GET /index.html ─────────────────────────────────────▶                              │
   │  ◀── HTML + injected <script src="/_jet/tap.js"> ─────│                              │
   │                                                       │                              │
   │  GET /_jet/tap.js ─────────────────────────────────────▶                              │
   │  ◀── tap.js (~3-5 KiB minified, gzipped, cached) ─────│                              │
   │                                                       │                              │
   │  [ tap.js installs listeners ]                        │                              │
   │   • window.onerror                                    │                              │
   │   • window.onunhandledrejection                       │                              │
   │   • console.error wrapper                             │                              │
   │   • PerformanceObserver (longtask, paint, lcp)        │                              │
   │   • ResourceTiming (failed CSS/JS/img/fetch)          │                              │
   │   • CSP violation reports                             │                              │
   │   • fetch / XHR monkey-patch (5xx, network errors)    │                              │
   │   • visibilitychange / beforeunload (final flush)     │                              │
   │                                                       │                              │
   │  POST /_jet/beacon ─[batched JSON, gzipped, sendBeacon]▶                             │
   │                                                       │                              │
   │                                                       │  [ jet enrichment ]          │
   │                                                       │   • add resource attrs:      │
   │                                                       │     service, version, env,   │
   │                                                       │     deploy id, build sha     │
   │                                                       │   • resolve stack traces     │
   │                                                       │     via private source maps  │
   │                                                       │   • PII scrub                │
   │                                                       │   • dedupe (error_hash + ttl)│
   │                                                       │   • per-user circuit break   │
   │                                                       │                              │
   │                                                       │  POST /v1/events ────────────▶ ChatOps rules engine
   │                                                       │   event_type:                │     (RFC 007)
   │                                                       │   "koder.browser.error"      │

2. Context and motivation

2.1 The client-side blind spot

RFC 007 §2.3 enumerated the gap explicitly:

Some errors are client-side only (JavaScript exceptions, UI glitches, rendering bugs) Some errors are transient and don't leave persistent log traces Some errors are configuration issues that don't throw exceptions Users often report behavioral bugs ("this button does nothing") that have no error log

Today the ChatOps pipeline has two event sources:

1. *observe/log`*— serverside logs. Catches anything that produces a log line on the backend. Misses everything that happens after the HTML is served: JavaScript exceptions, fetch failures the backend never saw, render bugs, asset 404s served from CDN, CSP violations, thirdparty widget breakage.
2. *koder-talk`*(RFC 007 §3) — screenshots posted in chat groups. Reactive: depends on a user noticing, taking a screenshot, opening the right group, and sending it. Even motivated users do this maybe one time in twenty.

The result is that the pipeline is blind to a significant fraction of real production bugs. A JavaScript exception that breaks a form submit will never reach Kortex unless the user manually reports it.

2.2 The PoC precedent (revisited)

The Pouso Alegre — MG PoC (MarchApril 2026) proved that autonomous monitoring + AI fix + autodeploy works for serverside logbased detection. The same loop should work for browserside detection — and arguably better, because clientside errors usually carry richer context (URL, user agent, full stack trace, the exact page state that triggered the bug) than a server log line typically does.

The PoC also established the trust model: users want fixes to happen automatically. The friction of reporting bugs is the bottleneck, not the willingness to receive fixes. Removing the reporting step entirely is the next obvious move.

2.3 Why koder-jet is the right home

koder-jet is the reverse proxy that fronts every Koder web property. Three properties make it the natural injection point:

1. It already touches every HTML response. Adding a <script> tag to the response body is trivial — the streaming HTML rewriter already exists for the benchmark and observability injections.
2. It already knows the deployment context. The site config in sites.toml knows which service the request is going to, what version is currently deployed, what environment, and which release artifact. Every browser event can be enriched with this metadata at the edge, with zero application participation.
3. It already talks to Kortex. Jet sends deploy events to Kortex on every release. The OTLP push channel is established. Adding a new event type is a config change.

2.4 Why not Sentry / Bugsnag / Datadog RUM

Three reasons:

1. Self-hosting requirement. Koder products are deployed in environments (PoC servers, on-prem hospital systems, regulated tenants) where sending raw browser data to a SaaS RUM provider is not acceptable on privacy or compliance grounds.
2. Pipeline integration. Offtheshelf RUM products produce dashboards. The Koder ChatOps pipeline produces fixes. The output of the RUM tool is the input of the autonomous fix loop — the connector between them is the interesting work, and we may as well own the whole stack.
3. Cost. SaaS RUM providers charge per session or per event. At Koder's planned scale (every customer site fronted by jet), the perevent cost of a SaaS solution dominates. A homegrown jetbased capture is a fixed cost.

This RFC does not preclude also shipping events to a third-party RUM tool when a customer wants it. The jet endpoint can fan out. But the canonical destination is Kortex.

3. Event categories

The browser tap captures events in the following categories. Each category maps to a specific koder.event.type value under the koder.browser.* namespace.

The first 6 categories (errors) are the high-value events that flow into the ChatOps fix pipeline. Categories 79 (perf) are signals that feed dashboards and trend analysis but do not normally trigger autonomous fixes. Categories 1012 (behavior) are user experience events that complement the technical signals — a rage click is the strongest possible signal that something is broken even when no exception fires.

3.1 Phasing

4. The BrowserEvent schema

The schema extends RFC 003 — Common Event Schema. Browser events ride on the standard OTLP Logs records with a structured body and the type discriminator under koder.event.type. This RFC defines the body shape and the resource attributes added by jet at the edge.

4.1 Resource attributes (added by jet)

These are attached to every event by koder-jet after it receives the beacon, before forwarding to Kortex. They are the same attributes already present on every other Koder OTLP event (RFC 003 §4) — reused without extension.

Note that koder.product.version, deploy_id, and build_sha come from jet's own deploy state, not from the browser. The browser cannot lie about which version is deployed — jet knows because it served the assets.

4.2 Body fields (browser-supplied)

The event body is a JSON object. Fields are conditionally present based on event category. The following table is the union; per-category required fields are noted.

4.3 Concrete example — JavaScript exception

{
  "resource_attributes": {
    "koder.product.name": "saude-publica",
    "koder.product.version": "v2.3.0",
    "koder.deployment.env": "production",
    "koder.deployment.deploy_id": "dpl-20260408-153022",
    "koder.deployment.build_sha": "a8f7c3d",
    "koder.event.type": "koder.browser.error.js",
    "koder.event.severity": "error"
  },
  "timestamp_unix_nano": 1712592623123456000,
  "body": {
    "event_id": "01HX4M2AWPY8Z5Q7K4F8R3N0Z6",
    "session_id": "sess-7f3a2b",
    "page_url": "https://saude.poc.vivver.com/agendamento",
    "page_route": "/agendamento",
    "referrer": "https://saude.poc.vivver.com/dashboard",
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) ...",
    "viewport": {"w": 1920, "h": 1080},
    "timestamp_ms": 1712592623123,
    "error_message": "Cannot read properties of null (reading 'patientId')",
    "error_name": "TypeError",
    "stack_trace": "TypeError: Cannot read properties of null (reading 'patientId')\n    at AgendamentoForm.handleSubmit (agendamento.js:142:21)\n    at HTMLFormElement.<anonymous> (agendamento.js:89:12)",
    "source_file": "src/components/AgendamentoForm.tsx",
    "source_line": 142,
    "source_column": 21,
    "error_hash": "a8f7c3d5b2e91047"
  }
}

4.4 Schema registration

This RFC requires registering the new event types in infra/observe/observability/schemas/browser/v1/. The schema lives there per RFC 003 §10. The Protobuf source becomes the canonical definition; jet vendors the generated Go SDK; tap.js uses a hand-authored TypeScript type that mirrors the schema (validated in CI against the JSON Schema generated from the Protobuf).

5. koder-jet — the injection and ingestion side

This section is the implementation contract for the infra/jet side of the work. It is intentionally specific so that ticket 071 (and follow-ups) can be implemented without ambiguity.

5.1 Persite optin

Browser tap is opt-in per site. Sites that already have SentryDatadogetc. or sites that handle highly sensitive content (banking, healthcare under strict compliance) can leave it off. The site config in sites.toml gains a new section:

[sites.routes."/"]
upstream = "http://127.0.0.1:8001"

[sites.browser_tap]
enabled = true
sample_rate = 1.0          # 0.0 to 1.0
exclude_routes = ["/admin