Codec

The Codec interface is the bridge between an AI framework and Ably channel messages. It describes the wire as a flat stream of input and output events and folds those events into a per-Run projection that the SDK extracts messages from for the conversation tree.

Implement Codec<TInput, TOutput, TProjection, TMessage> to integrate any AI framework with AI Transport. The SDK ships UIMessageCodec for the Vercel AI SDK. For other frameworks, implement the methods below.

import type { Codec } from '@ably/ai-transport';

const myCodec: Codec<MyInput, MyOutput, MyProjection, MyMessage> = {
  init() { /* ... */ },
  fold(state, event, meta) { /* ... */ },
  createEncoder(channel, options) { /* ... */ },
  createDecoder() { /* ... */ },
  getMessages(projection) { /* ... */ },
  createUserMessage(message) { /* ... */ },
  createRegenerate(target, parent) { /* ... */ },
};

Properties

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

Fold an event into a projection

The reducer contract: fold one event into the projection. The same (state, event, meta) triple must produce the same result every time. Re-folding an event whose serial has already been incorporated must be a no-op. The reducer is free to store a high-water-mark inside the projection.

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 that mid-stream join 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.

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 never has to introspect direction.

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 without inventing their own shapes. Codec-specific variants pick any other literal. (Edits ride 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. 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. 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 folding contract that Codec extends.

Example

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

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

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

const myCodec: Codec<MyInput, MyOutput, MyProjection, MyMessage> = {
  init: () => ({ highWater: '', messages: [] }),
  fold: (state, event, meta: ReducerMeta) => {
    if (meta.serial <= state.highWater) return state;
    state.highWater = meta.serial;
    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 }),
};