1.4 socketio

1.4. Socket.IO Real-time Layer

REST hands off work; Socket.IO delivers the experience. Every streaming answer, phase change, and error travels over a single Socket.IO connection managed by @ehildt/nestjs-socket.io using KeyDB as the shared adapter backbone.

Concepts

• Room — the dashboard joins a roomId per active request/conversation scope; the server streams into that room (emitToRoom) or, rarely, broadcasts (emitToAll).
• Event name — the client chooses the event it listens on and passes it as the event query param of POST /harness; the 202 response echoes it so both sides always agree.
• Correlation — every payload carries requestId (and usually conversationId), so multiple concurrent exchanges in one room stay attributable.

Server-side emission lives in modules/socket-io/services/socket-io-events.service.ts and degrades gracefully: if the socket instance is not yet available it logs rather than throwing, and failed emissions are logged with the event name.

Event contract

Payloads emitted during a harness run (see 1.2 — Streaming):

Payload kind	Meaning
text / stream	Incremental assistant output (append to the live exchange)
original	The pre-compaction/original variant of an answer (rendered behind a toggle)
assistant	Completed assistant message object
clarification	The harness asks the user for clarification instead of answering
compacting	Compaction progress/final summary for long threads
result	Terminal, validated structured result (schema-bound)
error	Something failed — renderable inline error object
cancel_result	Outcome of a POST /harness/cancel request

Phase markers and step progress also appear in the structured payloads; the dashboard's debug panel mirrors the raw event stream for inspection.

Configuration

SOCKET_IO_* env group: connect timeout, max HTTP buffer size, transports, CORS origin/methods/credentials, ping interval/timeout, EIO3 compatibility. Production deployments behind a proxy must enable sticky sessions or rely on the KeyDB adapter (default here) for cross-instance room routing.

Dashboard counterpart

The dashboard owns a socket Pinia store that maintains the connection (VITE_SOCKET_URL, default http://localhost:3000), dispatches incoming events into the messages/conversation stores, and keeps a socket debug journal. See 2.1 and 2.2.