Transport Contract

This page describes the runtime contract used by bundle-defined browser surfaces: the default chat UI, custom bundle main UI, and widget UI. The platform owns transport and session routing; the bundle owns what the UI does with that surface.

KDCube serves bundle UI surfaces through the same integrations layer that serves bundle operations and static assets. A client can render a widget or main UI directly, or embed it inside another shell. The KDCube control plane may use iframes for isolation, but "iframe" is not the bundle surface; @ui_widget(...), @ui_main, and static assets are.

The platform exposes three integration families. Browser chat uses SSE or Socket.IO. Bundle widgets, main views, and admin frontends use the integrations REST routes. MCP-capable clients can call bundle-served MCP endpoints declared with @mcp(...).

Integration Surface Matrix

Runtime-Disabled Bundle Surfaces

Bundle widgets, REST operations, and MCP endpoints can be disabled at runtime through bundle props. When that happens the route is still part of the bundle contract, but the processor treats it as unavailable and returns 404.

• Treat 404 on a bundle widget, operation, or MCP endpoint as feature unavailable, not only as transport failure.
• This can change without a redeploy, so dynamic clients should refresh their available actions and widgets when bundle props change.
• If the whole bundle is disabled, all its inbound surfaces become unavailable together.

SSE Endpoints

SSE Stream Query Parameters

Shared Chat Send Contract

POST /sse/chat and Socket.IO chat_message carry the same logical chat request. The transport wrapper differs, but the admitted request semantics are shared.

Logical Message Shape

{
  "message": "Hello",
  "chat_history": [],
  "project": "demo-project",
  "tenant": "demo-tenant",
  "turn_id": "turn_123",
  "conversation_id": "conv_123",
  "bundle_id": "my.bundle@1-0",
  "message_kind": "regular|followup|steer",
  "continuation_kind": "regular|followup|steer",
  "active_turn_id": "turn_current",
  "target_turn_id": "turn_current",
  "steer": true,
  "followup": false
}

Attachments travel alongside this logical message rather than inside it.

Attachments on SSE

When POST /sse/chat includes attachments, it uses multipart form data:

• message — JSON string of the logical request
• attachment_meta — JSON array of attachment descriptors
• files — repeated binary file parts

Without attachments, POST /sse/chat may be plain JSON.

Attachments on Socket.IO

Socket.IO wraps the same logical request as:

{
  "message": { ...logical request... },
  "attachment_meta": [
    { "filename": "a.txt" }
  ]
}

Binary buffers are sent as additional event arguments.

Synchronous Acknowledgement

Both send paths return an immediate acknowledgement before the turn necessarily starts. Current status values are:

Chat Stream Event Catalog

The chat stream uses one shared semantic event envelope across SSE and Socket.IO. SSE frames carry an event name and JSON data; Socket.IO delivers the same envelopes as named events. The transport route tells the client which listener fires, and the payload type tells your code what the event means.

Transport Event Names

chat_compaction is a progress route, not a completion route. Append it to the in-progress activity timeline or progress card and keep listening for later deltas, steps, completion, or error events. The payload includes event.status plus data.kind, data.compaction_id, and token estimates when available.

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": "..."
  }
}

Hosted File Events

Incoming user attachments and outgoing hosted files are different surfaces. User attachments arrive with the chat request. Files produced by tools, rendering, or isolated execution are emitted back to clients as chat.files.

A hosted-file event uses the normal event envelope and carries file rows under data.items:

{
  "type": "chat.files",
  "event": {
    "step": "files",
    "status": "completed",
    "title": "Files Ready (1)"
  },
  "data": {
    "count": 1,
    "items": [
      {
        "filename": "report.pdf",
        "mime": "application/pdf",
        "hosted_uri": "...",
        "rn": "...",
        "key": "...",
        "meta": { }
      }
    ]
  }
}

Clients should render download/open affordances from hosted_uri, rn, or key according to their environment. Files may come from built-in rendering tools, the exec/runtime tool family, strict custom tool results using ret.artifact_type == "files", or trusted catalog tools that call host_files(...).

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 the chat stream catalog above. The named events match the shared 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

MCP auth note: @mcp(route="operations") uses header-only JWT auth. Use the normal Authorization: Bearer ... header. Cookie fallback and query-param token injection are not part of the MCP operations contract.

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.