Skip to content

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

A chat WebSocket connection, from request to live streamSequence 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.ChatManagerEvent store (Neo4j)ws_authenticate/ws/chat/{id} handlerDashboard(chatWebSocket.ts)the session was created overREST, never over the WebSocketreplay phaselive phase, one select loopbroadcast lagging givesevents_lagged: reconnect andreplay the gapbroadcast closed givessession_dormant: resubscribeafter resumeGET /ws/chat/{id} withlast_event=N1cookie, else a one-time ticket2claims, or 401 before the upgrade3upgrade, then auth_ok4get_events_since(last_event)5persisted ChatEvents6subscribe (local broadcast)7get_streaming_snapshot8events, then partial_text andreplay_complete9broadcast ChatEvent10ChatEvent with seq11user_message, interrupt,cancel_tools12route_user_message, interrupt, cancel_running_tools13permission_response,set_permission_mode, set_model14route_permission_response, set_session_permission_mode, set_session_model15

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.

Zoom outZoom inFull screen
Redrawn from the verified diagram po-chat-transport (verified 878281ca). Labels are the names used in the code.
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

  1. 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.

  2. 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.

  3. Step 3. Replay

    After auth_ok, the handler reads the events persisted since last_event from the graph store and sends them.

  4. 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.

  5. Step 5. The live loop

    One select loop merges the broadcast, remote events, pings and client frames. Each chat event carries a sequence number.

  6. 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.

  7. 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.