Realtime
========

Agency projects database changes to browsers over Channels. The socket is a
**projection**, not the system of record.

The browser-side routing, canonical envelope and namespaced topics are described
in :doc:`../ui/event-bus`.

Three publishers
----------------

Defined in ``agency.channel.protocol``:

Messenger
  User-facing conversation stream: human / assistant / tool / system style
  messages (LangChain ``BaseMessage`` payloads).

Monitor
  Runtime telemetry for a Run, for example:

  * ``run_start``, ``run_status``, ``run_end``, ``run_error``
  * ``model_request``, ``model_response``
  * ``tool_call``, ``tool_result``, ``tool_error``, ``tool_interrupt``, …
  * ``checkpoint_created``, ``run_interrupt``, ``interruption_resolved``

  Exact names: ``Monitor.Event`` in code / :doc:`../../framework/connections`.

Catalog
  CRUD projections for explorers (catalog bus envelope) when Agents, Missions,
  Documents, etc. are saved or deleted — separate from conversation and from
  Run telemetry.

Pipeline
--------

::

   DB write
     → transaction commit
     → Django signal / producer
     → Channels group send
     → UI store / overlay

Rules of thumb:

* **DB** = authoritative state (hydrate on connect / refresh via REST).
* **WebSocket** = best-effort realtime; designed for reconnect and duplicate-tolerant
  handling on the client, not exactly-once delivery guarantees.
* Do not mix Messenger frames with Monitor telemetry in the same UI concern.

Session / Room / Message
------------------------

Package models also persist browser **Session**, shared **Room**, and
**Message** rows for presence and durable chat-like history. Product Mission
Control primarily uses ``/channel/`` + Execution REST; see models for details.

Contract reference
------------------

Socket paths, group naming, and HITL answer frames:
:doc:`../../framework/connections`.