Live events
Live events are how the runtime tells you what is happening as it happens. Every operation a circle runs emits a lifecycle stream — started, progress, terminal — without anyone writing emit code, and both the UI and your own code can subscribe. This page is the runtime’s reference entry; the concept that teaches the model is live-events.
The lifecycle contract
The shape is fixed for every operation: one Started before the work dispatches,
exactly one terminal at the end (Completed, Failed, or Cancelled), and zero
or more Progress events in between. Each event carries an invocation_id stable
across the whole lifecycle (so progress and terminal correlate to their start), an
actor (user / agent / system / external), and a trace_id matching the
operation’s SigNoz span — the live stream and the trace history are two views of one
event.
The terminal is load-bearing: unique per invocation, and emitted after the
underlying state commits, so a watcher never acts on a result a concurrent reader
cannot yet see. Progress is best-effort — human-meaningful checkpoints, not a
per-iteration firehose — and a dropped one never changes the outcome the terminal
reports.
Apply vs. invalidate
When the portal receives a Completed event it does one of two things, decided per
operation by generated policy — never by hand-matching on element type:
- Apply — when the operation’s output is the element’s full new state, write it straight into the cache. No refetch, no flicker.
- Invalidate — otherwise, drop the cached copy and let the next reader refetch.
This is the safe default;
FailedandCancelledalways invalidate.
The same discipline binds authoring: if you declare that an operation’s output replaces the element, that output must be the element’s complete shape — otherwise the cache silently corrupts. When in doubt, let the portal invalidate.
Subscribing
The authenticated stream is one Server-Sent Events endpoint, scoped to a single circle. It is the live counterpart to a run: you read a run to see what happened; you subscribe to live events to watch it happen. The wire-level endpoint shape is reference material in the API docs.
Related
- Concept: live-events — the full model (the teaching home)
- Concept: runs — the execution the events narrate
- Pillar: Runtime — what emits the lifecycle stream