Transport Contract

The platform exposes two real-time transports for browser clients. Both deliver the same event envelope; the only difference is the connection mechanism.

SSE Endpoints

SSE Stream Query Parameters

SSE Event Catalog

Each SSE frame carries an event name (transport route) and a JSON data payload with a semantic type. The event name tells the browser which listener fires; the payload type tells your code what the event means.

SSE Event Names

Common Envelope Shape

All chat events share this JSON structure:

{
  "type": "chat.step",
  "timestamp": "2026-02-26T21:14:05.267Z",
  "ts": 1700000000000,
  "service": {
    "request_id": "...", "tenant": "...",
    "user": "...", "user_type": "registered"
  },
  "conversation": {
    "session_id": "...", "conversation_id": "...",
    "turn_id": "..."
  },
  "event": {
    "agent": "...", "step": "...",
    "status": "started|running|completed|error",
    "title": "...", "markdown": "..."
  },
  "data": { },
  "delta": { },
  "extra": { }
}

Delta Markers

Streaming chunks (chat_delta) use a marker field to fan out to different UI channels:

Each delta chunk looks like:

{
  "delta": {
    "text": "Here is the answer.",
    "index": 0,
    "marker": "answer",
    "completed": false
  },
  "extra": {
    "format": "markdown",
    "artifact_name": "...",
    "sub_type": "..."
  }
}

Usage and Token Counting

After a turn completes, the server emits an accounting.usage event (on the chat_step route) containing a cost breakdown:

{
  "type": "accounting.usage",
  "data": {
    "breakdown": [ ... ],
    "cost_total_usd": 0.0042
  },
  "event": {
    "step": "accounting",
    "markdown": "Token usage: 1,240 in / 380 out"
  }
}

Socket.IO Events

Connection Setup

Connect to the platform namespace and pass authentication fields in the auth payload:

const socket = io(baseUrl, {
  auth: {
    bearer_token: accessToken,
    id_token: idToken,
    user_session_id: sessionId,   // optional: reuse existing session
    tenant: "my-tenant",          // optional override
    project: "my-project"         // optional override
  }
});

On successful connection, the server assigns a sid that acts as the peer stream identifier for targeted event delivery (equivalent to SSE's stream_id).

Event Names and Payloads

Socket.IO events use the same semantic envelope as SSE. The event names match the SSE transport routes:

Namespace and Room Patterns

Events are scoped to the authenticated session. The server manages rooms internally based on session_id. Clients do not join or leave rooms manually. Broadcast events go to all peers in the session room; peer-targeted events go only to the specific sid.

Authentication for Clients

The server resolves credentials in a fixed priority order. The first source that provides a token wins.

Useful Request Headers

Response Headers to Observe

Token Refresh Pattern

When you receive a 401 or 403, refresh your access token through your identity provider and retry the request. For SSE streams, close the current EventSource, obtain fresh tokens, and reconnect with the new credentials. Keep stream_id stable across reconnects so the server can associate the new connection with the same peer.

Error Handling & Reconnection

SSE Reconnect Strategy

Use exponential backoff with jitter. The server does not guarantee sticky connections — any replica may serve your reconnect.

delay = min(30s, 2attempt + jitter(0..1s))

Rate Limit Responses

Rate limits arrive as chat_service events and/or HTTP status codes:

In-stream rate-limit events (rate_limit.denied, rate_limit.warning) include a data.rate_limit object with retry_after_sec, reset_text, and a ready-to-display user_message. Prefer showing user_message directly.

Backpressure Signals

Gateway-level rejections arrive on chat_service with types such as gateway.backpressure, gateway.rate_limit, and gateway.circuit_breaker. These indicate the ingress is protecting the backend. Back off and retry.

Turn Interruption

If the processing worker dies after a turn has started, you may have already rendered partial chat_delta content. The server signals interruption with:

• conv_status with data.completion = "interrupted"
• chat_error with data.error_type = "turn_interrupted"

Keep partial output visible, mark the turn as failed, and offer the user a manual retry. Do not auto-resubmit.

Multi-Tab Coordination

Draining / Maintenance Mode

When the platform enters a drain cycle, active SSE streams receive a server_shutdown event with reason: "draining". REST endpoints return 503. This is expected, not fatal. Close connections gracefully and reconnect after a short delay. The load balancer will route you to a healthy replica.