Codec

The Codec interface encodes an AI framework's events as Ably channel messages, and decodes those messages back into events. It describes the wire as a flat stream of input and output events and merges those events into one projection per node of the conversation tree, which the SDK extracts messages from.

Implement Codec<TInput, TOutput, TProjection, TMessage> to integrate any AI framework with AI Transport. The SDK ships two codecs that implement it: createUIMessageSessionCodec() for the Vercel AI SDK, and ResponsesSessionCodec from @ably/ai-transport/openai for the OpenAI Responses API. Each ships alongside a wire codec of the same framework, which carries the encoder and decoder without the reducer. For other frameworks, implement the methods below.

// The interface is the contract a codec satisfies. Its type is not exported yet,
// so annotate against your own types rather than importing `Codec`.
const myCodec = {
  init() { /* ... */ },
  fold(state, event, meta) { /* ... */ },
  createEncoder(channel, options) { /* ... */ },
  createDecoder() { /* ... */ },
  getMessages(projection) { /* ... */ },
  createUserMessage(message) { /* ... */ },
  createRegenerate(target, parent) { /* ... */ },
};

Properties

Codec extends Reducer<CodecEvent<TInput, TOutput>, TProjection> and adds factories for encoders, decoders, and the message-extraction step the SDK uses to populate the tree.

Merge an event into a projection

The reducer contract: merge one event into the projection. The same (state, event, meta) triple must produce the same result every time, and the reducer holds no state of its own between calls.

The event arrives direction-tagged as a CodecEvent, so read event.event for the payload and branch on event.direction when a reducer treats client and agent events differently.

Merge unconditionally. Ordering, deduplication, and replay belong to the transport, which invokes fold exactly once per event in canonical order and rebuilds a node from a fresh init when a late message would otherwise merge out of order. A reducer that keeps a serial high-water-mark, or that skips an event it thinks it has already seen, produces a wrong projection every time the transport rebuilds the node. Events competing over the same state get last-writer-wins from the merge order, because the highest-serial event merges last.

fold may mutate the projection it is passed and return it. The caller treats the projection as single-owner and never keeps a reference to an old state.

Parameters

Returns

TProjection. The updated projection.

Create an encoder

Build a stateful encoder bound to a channel. The encoder owns the message-append lifecycle for both directions on a single channel.

Parameters

Returns

Encoder<TInput, TOutput>. A stateful encoder bound to the supplied channel.

Create a decoder

Build a stateful decoder for a single channel subscription. The decoder maintains stream-tracker state across messages, so when a client joins mid-stream the decoder synthesises any missing start events before deltas reach the SDK. The reducer always sees a clean (start, delta*, end) sequence.

Returns

Decoder<TInput, TOutput>. A stateful decoder for the channel.

Encoder

A stateful encoder for a single channel. Two publish methods enforce direction at the call site. publishInput writes to the ai-input wire, publishOutput writes to the ai-output wire. Stream-tracker state lives inside the encoder and is shared across both directions.

Properties

Publish an input

Encode and publish a single client input on the ai-input wire. Per-write overrides live in WriteOptions, shown in the parameters below.

Parameters

Publish an output

Encode and publish a single agent output on the ai-output wire.

Parameters

Decoder

A stateful decoder for a single channel subscription. Decodes one Ably inbound message into the input and output halves.

Decode a message

Tagged result of decoding one inbound Ably message. The codec routes by the wire name and returns inputs and outputs separately, so the SDK reads the direction off whichever field is populated.

Returns

DecodedMessage<TInput, TOutput>. Tagged inputs and outputs.

Well-known input variants

Codec input variants extend the CodecInputEvent base. The SDK reserves a handful of well-known kind literals, so callers can publish a user message, regenerate an assistant message, or resolve a tool call with shapes the SDK already defines. Codec-specific variants pick any other literal. (Edits go on the user-message path with a forkOf routing header; there is no separate 'edit' kind on the wire.)

The full input union is the codec author's responsibility. Use the variants below directly or extend them with extra fields.

UserMessage

A new user message. Produced by Codec.createUserMessage and surfaced via View.send (wrap a domain message via codec.createUserMessage(message) or build the literal directly).

Regenerate

A signal to regenerate an existing assistant codec-message. Produced by Codec.createRegenerate and surfaced via View.regenerate.

ToolResult

A client-published tool result for a successful execution. The tool result mutates the assistant codec-message addressed by codecMessageId.

ToolResultError

A client-published tool result for a failed execution.

ToolApprovalResponse

A client-published response to an agent-emitted tool-approval request. The response flips the targeted tool call from pending-approval to approved or denied.

Codec output base

Every codec output variant must satisfy CodecOutputEvent. The SDK reads type so it can reliably narrow TInput | TOutput (inputs carry kind, outputs carry type).

Wire payloads

The encoder and decoder cores describe Ably messages with two payload shapes, used internally by createEncoderCore and createDecoderCore. Custom codec implementations that build on those cores work with these shapes directly.

MessagePayload describes a discrete Ably message.

StreamPayload describes a streamed message. Data must be a string because the append lifecycle uses text append semantics. Deltas are concatenated for recovery and prefix-matching on the decoder.

Reducer

The reducer is a pure, stateless merge contract that Codec extends.

Example

A minimal codec skeleton that merges a single input and output variant and extracts a flat message list.

import type { CodecInputEvent, CodecOutputEvent, CodecMessage } from '@ably/ai-transport';

interface MyInput extends CodecInputEvent { kind: 'user-message'; message: MyMessage }
interface MyOutput extends CodecOutputEvent { type: 'text-delta'; text: string }
interface MyProjection { messages: CodecMessage<MyMessage>[] }
interface MyMessage { id: string; role: 'user' | 'assistant'; text: string }

const myCodec = {
  init: () => ({ messages: [] }),
  fold: (state, event, meta) => {
    if ('kind' in event && event.kind === 'user-message') {
      state.messages.push({ codecMessageId: meta.messageId ?? event.message.id, message: event.message });
    } else if ('type' in event && event.type === 'text-delta') {
      const last = state.messages.at(-1);
      if (last?.message.role === 'assistant') last.message.text += event.text;
    }
    return state;
  },
  createEncoder: (channel, options) => buildEncoder(channel, options),
  createDecoder: () => buildDecoder(),
  getMessages: (projection) => projection.messages,
  createUserMessage: (message) => ({ kind: 'user-message', message }),
  createRegenerate: (target, parent) => ({ kind: 'regenerate', target, parent }),
};