Docs · Internals
How the chat reaches your screen
The dashboard talks to a chat session over one WebSocket. This page follows a connection from the first request to live messages, including what happens when you reconnect.
What it does
The session is created over REST; the WebSocket at /ws/chat/{session_id} only attaches to it. Authentication happens before the upgrade, with a cookie or a one-time ticket.
On connect the server replays every persisted event after the last one the client saw, then sends the text being streamed, then goes live.
The wire format is a committed contract: more than thirty server events, 9 client messages and 5 control frames, with fixtures checked by tests and copied by the frontend with a checksum.
The diagram
Drag to move. Pinch, Ctrl + wheel or the + and - keys to zoom; arrow keys to move; 0 to fit; double-click to fit. Select a node to light up its links.
Text description of the diagram
Sequence diagram with five participants: the dashboard, the chat handler, ws_authenticate, the event store in Neo4j and the ChatManager. The dashboard requests the WebSocket with the last event number. The handler authenticates with a cookie or a one-time ticket before upgrading, then answers auth_ok. In the replay phase it reads the persisted events since that number, subscribes to the local broadcast, fetches the streaming snapshot and sends partial_text and replay_complete. In the live phase the ChatManager broadcasts events, which the handler forwards with a sequence number, and client frames such as user_message, interrupt and permission_response are routed to the ChatManager. A closing note explains events_lagged and session_dormant.
Guided reading
Step 1. Create, then attach
The session is created over REST (or by an MCP tool), never over the WebSocket. The client connects to /ws/chat/{id} and passes last_event, the sequence number of the last event it has.
Step 2. Authenticate before the upgrade
The handler tries the cookie first, then a one-time ticket (a fallback for desktop web views). With neither, the request is rejected with 401 before the upgrade. If the server runs without authentication configured, the connection is anonymous.
Step 3. Replay
After auth_ok, the handler reads the events persisted since last_event from the graph store and sends them.
Step 4. Subscribe, snapshot, ready
It subscribes to the session broadcast (or to NATS when the session lives on another instance), fetches the streaming snapshot, sends partial_text and then replay_complete.
Step 5. The live loop
One select loop merges the broadcast, remote events, pings and client frames. Each chat event carries a sequence number.
Step 6. Client frames
user_message, interrupt, cancel_tools, permission_response, set_permission_mode, set_model and set_auto_continue are routed to the ChatManager. A permission response is de-duplicated per connection.
Step 7. Lag and dormancy
A slow client receives events_lagged and reconnects to replay the gap. If the broadcast closes because the session process was cleaned up, the client receives session_dormant, and the server subscribes again once the session resumes.
Why it is built this way
Everything recovers through replay
A network drop, a lagging client and a dormant session all lead to the same path: reconnect and replay from a sequence number. One recovery mechanism keeps the server simple.
No socket for the unauthenticated
Authentication runs before the upgrade, and the ticket is single-use, so there is no connected-but-unknown state to manage.
A contract with checksums
The chat contract in the backend docs holds JSON fixtures and a checksum file. A test regenerates the contract from the code and fails if the committed fixtures differ.
Closing is not disconnecting
Closing a session removes its channel, so clients see session_dormant and stay connected. A session_closed event exists in the contract, but the handler does not emit it and the frontend treats it as reserved.
What is not established
- The NATS path (a session running on another instance) has not been tested against a real NATS. The control frames are static copies that no test ties to the handler.
Public sources
Where to check each statement, in the public repositories.