Realtime events

All control traffic is JSON on a reliable LiveKit data channel, discriminated by a type field. Use the map below; each SDK exposes the same events with language-native names (TypeScript session.on('transcript', …), Python TranscriptDeltaEvent, Swift case .transcript). Subscribing is one stream (or emitter) per session:

session.on('transcript', (event) => {
  if (event.isFinal) console.log(event.role, event.text);
});

from cosmo_ai import TranscriptDeltaEvent

async for event in session:
    if isinstance(event, TranscriptDeltaEvent) and event.is_final:
        print(event.role.value, event.text)

for try await event in session.events {
    if case .transcript(let delta) = event, delta.isFinal {
        print(delta.role, delta.text)
    }
}

Two framing rules apply to everything below:

• Oversized messages are chunked. Anything above 12,000 bytes travels as envelope-chunk / server-envelope-chunk frames and is reassembled before your handler fires. You never see chunks. See Envelope chunking.
• Unknown types aren't errors. SDKs surface unrecognized type values as an explicit unknown event and keep going. New server events never break old clients.

Client → server

Each client → server message and when to send it:

Server → client

Server messages fall into three families: lifecycle, transcripts, and tool traffic.

Session lifecycle

The following table lists the lifecycle events and what each one carries.

Every SDK guarantees a terminal session-ended item as the last event on the stream, synthesized locally if the transport died before the server said goodbye.

Transcripts and model text

The following table lists the transcript and model-text events.

Which one to display for which UI is covered in Transcripts.

Speech activity and model processing

These are informational, type-only markers — ideal for driving avatars, level meters, and "thinking…" indicators:

Tools

Four events cover both dispatch directions — see Tools:

The three observability events share a tool_call_id so you can render a timeline per invocation.

First-party extensions

Cosmo-specific events are namespaced cosmo.*:

Ordering guarantees

• ready always precedes transcripts, tool events, and speech markers.
• The three tool observability events arrive in order for a single tool_call_id, but events from different tool calls interleave.
• Transcript deltas for one turn arrive in order; turn-complete follows the final transcript of that turn.
• The terminal session-ended item is always last; nothing follows it.

Wire reference

Exact schemas for every message live in the wire protocol reference. The protocol evolves additively and session-config identifies the sending SDK; see Protocol compatibility for how changes ship without breaking deployed apps.