Events and streaming

Canonical events, native frames, and the two server-sent streams that carry a run to the browser.

The event log is the product. This page covers what an event is, why there are two shapes of it, and how events reach the UI.

From engine output to the browser: raw provider events are claimed, sealed, and translated by the canonical lane, persisted to canonical_events, then streamed per thread and merged by the UI reducer.

Canonical event

UseAgent’s provider-neutral representation of engine output. Canonicalization is what lets Codex, Claude, and OpenCode render through one UI contract: each engine’s native stream is translated into the same canonical shape, so the timeline components never need to know which engine produced a run.

Native frame

The original engine event, retained alongside the canonical one for fidelity and debugging when the canonical shape cannot yet express every provider detail. The backend event log and each live provider remain authoritative for persisted and native runtime state; the shared packages define the public schema on top.

The two streams

UseAgent uses two distinct server-sent event streams, and it is important not to conflate them:

The thread stream replays missed history from the durable snapshot. The org-change stream does not replay; it only tells ambient views (Automations, Provider Connections, and similar) that something changed so they can refetch.

How the UI consumes events

The browser-side agent-client package reconnects to the thread stream, reduces the event sequence into thread state, and exposes selectors to the UI. The session grammar then renders each step as a card or row: work-entry tool groups with folds, reasoning disclosures, recall receipts, live todo and plan cards, per-file diffs, and artifact cards after the answer text.