SSE events

Jarvis uses Server-Sent Events (SSE) for long-running responses and live UI updates where one-way HTTP streaming is a good fit.

This page documents the behavior clients should rely on. It is intentionally higher level than backend implementation details.

Why Jarvis uses SSE

SSE lets Jarvis stream assistant output incrementally while keeping the backend model simple:

one HTTP request starts a turn
the server emits ordered event frames
the client can reconnect and continue from persisted state

This is a better fit than a one-shot JSON response for chat turns that may run for a while or call tools along the way.

High-level event model

At a minimum, a Jarvis chat stream may include events for:

token deltas from the assistant
tool activity
errors
terminal completion

Internally, Jarvis persists stream events before clients consume them. That is the important public behavior: the event log is the source of truth, and the live stream is a delivery mechanism layered on top of it.

Streaming behavior

For a streaming turn, clients should expect:

the request starts server-side work
the response emits SSE frames as the turn progresses
assistant text arrives incrementally rather than only at the end
the stream closes after a terminal event or terminal turn state

Clients should treat event order as meaningful and should process frames incrementally.

Reconnect behavior

Jarvis is built so that a client disconnect does not cancel the underlying turn by default.

That means:

refreshing the browser should not discard already produced output
a temporary network interruption should not erase the turn
reconnecting clients can replay missed events from persisted state

From the client point of view, the correct mental model is “reattach to the turn” rather than “restart the turn.”

Persistence model

Persistence is central to Jarvis streaming:

stream events are written to storage
subscribers consume from that stored event log
live notifications are best-effort wakeups, not the sole data path

This is why Jarvis can preserve output across refreshes and can recover after a viewer disconnects mid-turn.

Client expectations

When consuming Jarvis SSE:

expect normal SSE framing with event: and data: fields
handle multiple events over a single response
tolerate reconnects and repeated attachment
avoid assuming the client is the only active viewer
treat terminal events as the end of a turn stream

Clients should also be prepared for error events and partial output if a turn fails after producing some tokens.

Scope of this reference

This page describes the public contract at the semantic level:

streaming exists
events are ordered
reconnects are expected
persistence is part of the contract

It does not freeze every event name emitted by every internal pathway. For strict REST request and response shapes, use generated API reference material once the OpenAPI artifact is published.