Local Chat Transport & SSE

Relevant source files

The following files were used as context for generating this wiki page:

• src/local-chat-transport.ts
• src/deterministic-local-commands.ts
• backend/src/handler.ts
• src/main.ts
• backend/tests/service.test.ts
• instructions/design-backend-prompt.txt

The Local Chat Transport and Server-Sent Events (SSE) system serves as the primary communication bridge between the Electron Desktop "Control Room" and the background loopback service. This architecture facilitates high-performance, real-time bidirectional-like behavior by using standard HTTP POST requests for commands and persistent EventStream connections for live system updates.

The transport layer is designed with a "Local-is-a-location" security principle, binding exclusively to loopback addresses (e.g., 127.0.0.1) and rejecting any non-allowlisted browser origins to ensure data privacy within the local machine environment.

Sources: instructions/design-backend-prompt.txt:130-137, backend/src/handler.ts:1094-1144

System Architecture

The architecture relies on a decoupled model where the Backend (Bun service) publishes minimized status data and the Frontend (Electron Renderer) consumes it via a typed capability bridge.

Core Components

1. Backend Handler: Manages the text/event-stream response and maintains a set of active subscribers to fan out events.
2. Electron Main Process: Acts as a proxy/relay, establishing the initial connection to the backend and forwarding events to the renderer processes via IPC.
3. Chat Session Registry: Tracks active chat requests to allow for cancellation and prevent overlapping responses.
4. Transport Utilities: Functions for normalizing loopback origins and parsing raw SSE streams into typed JavaScript objects.

Sources: src/local-chat-transport.ts:6-14, src/main.ts:503-515, backend/src/handler.ts:896-905

Data Flow Overview

The following diagram illustrates the lifecycle of a chat request and the parallel live event stream.

The system ensures that UI updates (like the Orb changing color) happen asynchronously through the SSE channel while text deltas stream through the active chat request.
Sources: src/main.ts:503-520, backend/src/handler.ts:167-187

Server-Sent Events (SSE) Implementation

The /v1/events endpoint implements the Server-Sent Events protocol to provide real-time updates.

Live Event Handling

The backend uses a Set of subscribers to manage client connections. Every 5 seconds, a ping event is emitted to keep the connection alive. The system emits specific events including:

• service.connected: Sent immediately upon establishing a connection.
• orb.state.changed: Updates the visual state of the JARVIS orb (e.g., thinking, responding).
• action.intent.updated: Notifies the frontend when a proposed system action (like opening a URL) changes status.
• diagnostics.updated: Provides periodic snapshots of system health and performance.

Sources: backend/src/handler.ts:1115-1144, backend/src/handler.ts:912-927

Main Process Relay

The Electron Main process manages the lifecycle of the SSE connection to the local service. It handles reconnection logic with exponential backoff (starting at 1s, capping at 15s) to ensure the HUD remains responsive if the backend service restarts.

Local Chat Transport

Chat interactions use an asynchronous streaming mechanism to provide immediate feedback to the user.

Chat Session Management

The ChatSessionRegistry class ensures that only one response is active per owner (renderer window) at a time. It uses AbortController to handle user-initiated cancellations.

Feature	Description
Request ID Tracking	Every chat request is assigned a unique UUID to route tokens correctly.
Cancellation	If a new chat starts before the previous one ends, the registry aborts the older session.
Stream Forwarding	The forwardJarvisChatStream function parses the chunked response into JarvisChatStreamEvent objects.

Sources: src/local-chat-transport.ts:16-52, src/local-chat-transport.ts:60-75

Response Types

The transport layer identifies several terminal and non-terminal events:

1. chat.start: Indicates the model has begun generating.
2. chat.delta: Contains a partial text fragment (token).
3. chat.done: Signals completion and provides the final consolidated message.
4. chat.error: Transmits failure codes (e.g., local_stream_error, max_tool_turns).

Sources: backend/src/handler.ts:167-187, backend/tests/service.test.ts:311-325

API Endpoints Summary

The following table outlines the transport endpoints used for real-time communication.

Endpoint	Method	Response Type	Purpose
/health	GET	JSON	Health check probe and uptime status.
/v1/events	GET	text/event-stream	Persistent live event channel.
/v1/chat	POST	text/event-stream	Token-streaming chat completions.
/v1/pairing/code	POST	JSON	Generates short-lived 6-digit OTP codes.

Sources: backend/src/handler.ts:1083-1144, backend/tests/service.test.ts:44-55

Conclusion

The Local Chat Transport and SSE system provides a robust, low-latency framework for the JARVIS desktop environment. By combining the immediate feedback of token streaming via /v1/chat with the event-driven updates of the /v1/events SSE channel, the project maintains a responsive UI that synchronizes with complex backend agent behaviors and system health metrics. This separation of concerns allows the frontend to remain a stateless "Control Room" while the backend manages the heavy lifting of model inference and action execution.

Sources: instructions/design-backend-prompt.txt:30-45, backend/src/handler.ts:101-115