AblyDocs

Internals

The wire protocol, codec architecture, conversation tree, and transport patterns that make up AI Transport under the hood. For senior engineers and codec implementers.

The internals section is for engineers who want to understand the system before betting on it, and for anyone building a custom codec. Nothing here is required to use the SDK.

Four layers fit together, from the application-facing model down to the SDK plumbing:

  • Conversation tree: the highest-level structure. Every session is a tree of ConversationNodes (InputNodes keyed by codec-message-id for user prompts and RunNodes keyed by runId for agent replies), joined by parent and fork-of pointers. The View walks the tree to produce a flat message list for rendering.
  • Codec architecture: the encoder converts client-published TInputs and agent-published TOutputs into Ably publish operations. The decoder converts inbound Ably messages back into typed events. The codec is what makes AI Transport framework-agnostic.
  • Wire protocol: the Ably channel format. Two header tiers (extras.ai.transport for run and message identity; extras.ai.codec for stream and status metadata), four Run lifecycle event names (ai-run-start, ai-run-suspend, ai-run-resume, ai-run-end), one cancel signal (ai-cancel), and two content event names (ai-input for client publishes, ai-output for agent publishes).
  • Transport patterns: the SDK-internal components that drive the codec over the wire: the stream router that fans inbound channel messages out to per-Run streams, the input-event lookup that resolves a POSTed invocation to its channel events, and the cancel-routing pipeline.

Topics

Wire protocol

The Ably channel wire format: header tiers, lifecycle events, content event names, and message identity.

Codec architecture

How the codec bridges TInput and TOutput to Ably messages. Encoder, decoder, and the input/output type split.

Conversation tree

The branching Run tree. Sibling resolution, regenerate groups, and message-anchored branch selection.

Transport patterns

Internal transport components: stream router, input-event lookup, and cancel routing.