1.0
protocol version
STREAM
One stream. Every event.
Tokens, tools, MCP, and errors travel one SSE pipe. The client asks for application/vnd.sveda.stream+json. The runtime answers with text/event-stream.
SSE
server Content-Type
11
event types
The problem
Custom copilots grow a websocket, a tool channel, and a model SDK that each invent event names. Failover restarts the pipe. The UI has to know which provider is live. One POST should carry tokens, tools, and errors to message.end.
Two pipes for one turn
Text on SSE, tools on a socket, MCP on a third client. Sveda keeps tool.call and tool.result on the same stream as text.delta.
Provider-shaped events
Swap Anthropic for Responses and the widget breaks. Sveda event types stay fixed. Failover does not rewrite the client.
Open-ended schemas
Ad-hoc JSON lines accumulate. The closed list is message.start through error, including reasoning.delta, context.usage, and max_steps.
How Sveda does it
The client sends Accept: application/vnd.sveda.stream+json. sveda-server answers Content-Type: text/event-stream and x-sveda-protocol-version: 1.0. Frames are data: lines. The list ends with data: [DONE].
Negotiate the media type
SvedaClient.streamAcceptHeaders sets the Sveda Accept. The runtime still speaks SSE on the wire.
- Accept application/vnd.sveda.stream+json
- Content-Type text/event-stream
- x-sveda-protocol-version: 1.0
Closed event list
Eleven types. Tokens, reasoning, tools, usage, title, step limits, completion, and errors share one parser.
- message.start, text.delta, reasoning.delta
- tool.call, tool.result, tool.progress
- context.usage, chat.title, max_steps, message.end, error
Tools are events
tool.call carries target backend or frontend. The host does not open a second socket to run a registry handler.
- target: backend | frontend
- tool.progress for spawn_tasks
- message.end closes the turn
SSE
message.startchatId
text.deltatoken
tool.callbackend | frontend
tool.resultoutput
message.enddone
One POST. One SSE response.
session.send posts to /sveda/stream. It does not call session.stream. The runtime writes message.start, then deltas, then any tool.call the catalog needs. Frontend targets pause in the client until SvedaToolRegistry returns; backend targets resolve in sveda-server.
chat.title, context.usage, and max_steps ride the same body so the UI never polls a side channel. error is a typed event, not a dropped TCP connection. Protocol version 1.0 is on the response header so proxies can pin the contract.
Event names and framing are in the stream protocol docs. Model failover keeps this event list when the catalog walks the next id.
turn.sse 1.0
POST /sveda/stream
Accept: application/vnd.sveda.stream+json
← Content-Type: text/event-stream
← x-sveda-protocol-version: 1.0
data: {"type":"message.start",…}
data: {"type":"text.delta","delta":"Hello"}
data: {"type":"message.end",…}
data: [DONE] Related
JS client
Accept is set by SvedaClient. The session API is still send.
Rust runtime
POST /sveda/stream is the required route on sveda-server.
MCP & tools
tool.call and tool.result are stream events, not a second protocol.
Stream docs
Framing, headers, and the StreamEvent list.
JS client docs
How session.send consumes the SSE body.
Model failover
Next model in line. Same event types. Stream held.
Parse one pipe.
Ask for application/vnd.sveda.stream+json. Read text/event-stream until message.end.