@ably/ai-transport 0.2.0 → 0.3.0

package/src/core/codec/output-descriptors.ts

@@ -0,0 +1,307 @@
+/**
+ * Declarative output descriptors — the single source of truth for a codec's
+ * `ai-output` wire mapping, the output-side sibling of {@link import('./input-descriptors.js')}.
+ *
+ * A codec declares each ordinary output event once, as a descriptor built on the
+ * typed header-field bindings ({@link HeaderField}). The generic encode/decode
+ * drivers consume the descriptor set, so adding an ordinary event is one
+ * descriptor entry instead of three hand-synchronised switch arms (encoder,
+ * decoder, stream reconstruction).
+ *
+ * Authoring is cast-free: the {@link outputBuilder} factory hands the codec an
+ * `{ event, stream }` pair curried on the codec's output union, so every `data` /
+ * `encode` / `decode` callback receives the exact narrowed member. The descriptors
+ * are then erased to a heterogeneous {@link OutputDescriptor} via a single
+ * documented cast at each constructor boundary — never in author code.
+ */
+
+import type * as Ably from 'ably';
+
+import { wildcardMatcher } from './field-bag.js';
+import type { DataCodec, FieldFor, HeaderField } from './fields.js';
+import type { MessagePayload, StreamPayload, WriteOptions } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Type helpers
+// ---------------------------------------------------------------------------
+
+/** The string-valued keys of `C` — the only keys `idField`/`deltaField` may name. */
+export type StringKeyOf<C> = { [K in keyof C]-?: C[K] extends string ? K : never }[keyof C];
+
+/**
+ * Resolve the union member a descriptor `type` literal selects. An exact match
+ * wins; a wildcard literal (`'data-*'`) resolves to the template member
+ * (`data-${string}`), so wildcard descriptors still narrow to the real member.
+ */
+export type ResolveType<U extends { type: string }, T extends string> =
+  Extract<U, { type: T }> extends never
+    ? T extends `${infer P}-*`
+      ? Extract<U, { type: `${P}-${string}` }>
+      : never
+    : Extract<U, { type: T }>;
+
+// ---------------------------------------------------------------------------
+// Escape-hatch core surface
+// ---------------------------------------------------------------------------
+
+/**
+ * The narrowed view of the encoder core that escape-hatch `encode` functions
+ * receive — only the publish/stream operations a hatch legitimately needs. The
+ * full internal `EncoderCore` satisfies this structurally.
+ */
+export interface EscapeHatchCore {
+  /** Publish a single discrete message. */
+  publishDiscrete(payload: MessagePayload, opts?: WriteOptions): Promise<Ably.PublishResult>;
+  /** Start a streamed message. */
+  startStream(streamId: string, payload: StreamPayload, opts?: WriteOptions): Promise<void>;
+  /** Append a fragment to an in-flight stream (fire-and-forget). */
+  appendStream(streamId: string, data: string): void;
+  /** Close a streamed message. */
+  closeStream(streamId: string, payload: StreamPayload): Promise<void>;
+  /** Cancel all in-progress streams. */
+  cancelAllStreams(opts?: WriteOptions): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Header builder + contexts
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds a codec headers record from a chunk through the descriptor's declared
+ * fields, stamping the dispatch `type` plus each field read off `chunk`. An
+ * optional `keys` subset restricts which declared fields are written; the keys
+ * are checked against the chunk so the imperative path can't drift.
+ * @template C - The narrowed chunk member.
+ */
+export type HeaderBuilder<C> = <K extends keyof C & string>(chunk: C, keys?: readonly K[]) => Record<string, string>;
+
+/**
+ * Context passed to an escape-hatch `encode` function.
+ * @template C - The narrowed chunk member.
+ */
+export interface OutputEncodeHatchContext<C> {
+  /** Header builder bound to the descriptor's declared fields. */
+  h: HeaderBuilder<C>;
+  /** The wire message name for this direction (`ai-output` / `ai-input`). */
+  name: string;
+  /** The encoder's configured fallback message id, if any. */
+  messageId: string | undefined;
+  /** Per-write overrides to thread into the hatch's publish/cancel calls. */
+  opts: WriteOptions | undefined;
+}
+
+/** Context passed to a discrete escape-hatch `decode` function. */
+export interface OutputDecodeContext {
+  /** The codec `kind` header value the message dispatched on (mirrors the input context's `codecKind`). */
+  codecKind: string;
+  /** The inbound codec-tier headers. */
+  codecHeaders: Record<string, string>;
+  /** The inbound transport-tier headers. */
+  transportHeaders: Record<string, string>;
+  /** The inbound message data. */
+  data: unknown;
+}
+
+/** Context passed to a stream descriptor's `decodeEnd` escape hatch. */
+export interface OutputStreamEndContext {
+  /** The stream identifier (e.g. chunk id, toolCallId). */
+  streamId: string;
+  /** The full accumulated stream text. */
+  accumulated: string;
+  /** The stream's persistent (start) codec headers. */
+  codecHeaders: Record<string, string>;
+  /** The codec headers carried on close (may differ from the start headers). */
+  closingCodecHeaders: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Data codec
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Author-facing specs (narrowed)
+// ---------------------------------------------------------------------------
+
+/**
+ * A discrete (non-streaming) output event descriptor spec, narrowed to chunk member `C`.
+ * @template C - The narrowed chunk member.
+ */
+export interface OutputEventSpec<C> {
+  /**
+   * Declared header fields, written on encode and read on decode. Each field's
+   * key names both the wire header and the chunk property it carries (see
+   * {@link FieldFor}). Omit for a header-less event.
+   */
+  fields?: readonly FieldFor<C>[];
+  /** Wire `data` codec. Omit when the event carries no data (`data: ''`). */
+  data?: DataCodec<C>;
+  /** Whether the publish is ephemeral (not persisted). Default false. */
+  ephemeral?: (chunk: C) => boolean;
+  /** Escape-hatch encode — overrides the default discrete publish. */
+  encode?: (chunk: C, core: EscapeHatchCore, ctx: OutputEncodeHatchContext<C>) => Promise<void>;
+}
+
+/**
+ * A streamed-family descriptor spec. `start`/`delta`/`end` are the domain chunk
+ * `type` literals; the family id (the {@link OutputBuilder.stream} first argument)
+ * is the wire `kind` header all three phases stamp.
+ * @template U - The codec's event union.
+ * @template S - The start chunk `type` literal.
+ * @template D - The delta chunk `type` literal.
+ * @template E - The end chunk `type` literal.
+ */
+export interface OutputStreamSpec<
+  U extends { type: string },
+  S extends U['type'],
+  D extends U['type'],
+  E extends U['type'],
+> {
+  /** The start chunk `type` literal. */
+  start: S;
+  /** The delta chunk `type` literal. */
+  delta: D;
+  /** The end chunk `type` literal. */
+  end: E;
+  /** The string-valued chunk key carrying the stream id (e.g. `id`, `toolCallId`). */
+  idField: StringKeyOf<ResolveType<U, S>> & StringKeyOf<ResolveType<U, D>> & StringKeyOf<ResolveType<U, E>>;
+  /** The string-valued delta chunk key carrying the appended fragment. */
+  deltaField: StringKeyOf<ResolveType<U, D>>;
+  /**
+   * Declared header fields written/read on the start and end chunks. Each
+   * field's key names both the wire header and the chunk property (see
+   * {@link FieldFor}); a field may bind a property carried by either phase.
+   */
+  fields: readonly (FieldFor<ResolveType<U, S>> | FieldFor<ResolveType<U, E>>)[];
+  /** Escape-hatch override for the stream-close step only (e.g. close-or-discrete fallback). */
+  onEnd?: (
+    chunk: ResolveType<U, E>,
+    core: EscapeHatchCore,
+    ctx: OutputEncodeHatchContext<ResolveType<U, E>>,
+  ) => Promise<void>;
+  /** Escape-hatch override for the end-chunk rebuild (e.g. input from accumulated text). */
+  decodeEnd?: (ctx: OutputStreamEndContext) => ResolveType<U, E>[];
+  /**
+   * Escape-hatch decode for when the family arrives as a discrete (non-streamed)
+   * message — the wire `kind` equals the family id but the wire wasn't streamed
+   * (e.g. history compaction). Reconstructs the start/end chunk pair.
+   */
+  decodeDiscrete?: (ctx: OutputDecodeContext) => ResolveType<U, S | E>[];
+}
+
+// ---------------------------------------------------------------------------
+// Erased descriptor (heterogeneous array element)
+// ---------------------------------------------------------------------------
+
+/** A discrete output event descriptor erased to the codec's union `U`. */
+export interface OutputEventDescriptor<U> {
+  /** Discriminator — the construct this descriptor was built with. */
+  construct: 'event';
+  /** The dispatch `type` literal (or wildcard sentinel), stamped as the wire `kind` header. */
+  type: string;
+  /** Declared header fields. */
+  fields: readonly HeaderField<unknown>[];
+  /** Wire `data` codec, if any. */
+  data?: DataCodec<U>;
+  /** Ephemeral predicate, if any. */
+  ephemeral?: (chunk: U) => boolean;
+  /** Wildcard dispatch predicate (both directions), derived by the builder from a `-*` type literal. */
+  match?: (type: string) => boolean;
+  /** Escape-hatch encode, if any. */
+  encode?: (chunk: U, core: EscapeHatchCore, ctx: OutputEncodeHatchContext<U>) => Promise<void>;
+}
+
+/** A streamed-family descriptor erased to the codec's union `U`. */
+export interface OutputStreamDescriptor<U> {
+  /** Discriminator — the construct this descriptor was built with. */
+  construct: 'stream';
+  /** The stream family id, stamped as the wire `kind` header on every phase. */
+  kind: string;
+  /** The start chunk `type`. */
+  start: string;
+  /** The delta chunk `type`. */
+  delta: string;
+  /** The end chunk `type`. */
+  end: string;
+  /** The chunk key carrying the stream id. */
+  idField: string;
+  /** The delta chunk key carrying the appended fragment. */
+  deltaField: string;
+  /** Declared header fields. */
+  fields: readonly HeaderField<unknown>[];
+  /** Escape-hatch close override, if any. */
+  onEnd?: (chunk: U, core: EscapeHatchCore, ctx: OutputEncodeHatchContext<U>) => Promise<void>;
+  /** Escape-hatch end-rebuild override, if any. */
+  decodeEnd?: (ctx: OutputStreamEndContext) => U[];
+  /** Escape-hatch non-streamed decode, if any. */
+  decodeDiscrete?: (ctx: OutputDecodeContext) => U[];
+}
+
+/** An erased output descriptor — a discrete event or a streamed family. */
+export type OutputDescriptor<U> = OutputEventDescriptor<U> | OutputStreamDescriptor<U>;
+
+// ---------------------------------------------------------------------------
+// Builder factory
+// ---------------------------------------------------------------------------
+
+/**
+ * The direction-scoped output builder `defineCodec` injects into the `output`
+ * config function — `event` (single discrete) and `stream` (streamed family),
+ * both curried on the codec's output union so author entries narrow cast-free.
+ * @template U - The codec's output union.
+ */
+export interface OutputBuilder<U extends { type: string }> {
+  /**
+   * Declare a single discrete output event. Curried on the output union; narrows
+   * `spec` to the member the `type` literal selects. The `type` literal is stamped
+   * as the wire `kind` dispatch header.
+   * @param type - The event's `type` literal (or a `*-*` wildcard); stamped as the wire `kind` header.
+   * @param spec - The narrowed output event spec. Omit for a header-less event with no data.
+   * @returns An erased {@link OutputDescriptor}.
+   */
+  event: <T extends U['type'] | `${string}-*`>(
+    type: T,
+    spec?: OutputEventSpec<ResolveType<U, T>>,
+  ) => OutputDescriptor<U>;
+  /**
+   * Declare a streamed output family (start / delta / end). `start`/`delta`/`end`
+   * are domain chunk `type` literals; the first argument is the family id, stamped
+   * as the wire `kind` dispatch header on every phase.
+   * @param kind - The stream family id, stamped as the wire `kind` header on every phase.
+   * @param spec - The narrowed stream spec.
+   * @returns An erased {@link OutputDescriptor}.
+   */
+  stream: <S extends U['type'], D extends U['type'], E extends U['type']>(
+    kind: string,
+    spec: OutputStreamSpec<U, S, D, E>,
+  ) => OutputDescriptor<U>;
+}
+
+/**
+ * Build the curried `{ event, stream }` output builder for a codec's output union.
+ * `defineCodec` calls this once and hands the result to the `output` config
+ * function; mirrors the input side's {@link import('./input-descriptors.js').inputBuilder}.
+ * @template U - The codec's output union.
+ * @returns The direction-scoped {@link OutputBuilder}.
+ */
+export const outputBuilder = <U extends { type: string }>(): OutputBuilder<U> => ({
+  event: (type, spec) =>
+    // CAST: `spec` is narrowed to the member selected by `type`; the descriptor
+    // erases that to the codec's union `U` so heterogeneous descriptors share one
+    // array type. The drivers only ever invoke a descriptor's callbacks with the
+    // matching member, so the erasure is sound by construction. `fields` defaults
+    // to `[]` so a header-less event needs no spec (mirrors the input `event` builder).
+    ({
+      construct: 'event',
+      type,
+      fields: spec?.fields ?? [],
+      data: spec?.data,
+      ephemeral: spec?.ephemeral,
+      // A `-*` literal declares a wildcard family; the dispatch predicate is
+      // derived from the literal so the two can never disagree (see wildcardMatcher).
+      match: wildcardMatcher(type),
+      encode: spec?.encode,
+    }) as unknown as OutputDescriptor<U>,
+  stream: (kind, spec) =>
+    // CAST: see `event` — the narrowed stream spec erases to `OutputDescriptor<U>`.
+    ({ construct: 'stream', kind, ...spec }) as unknown as OutputDescriptor<U>,
+});

package/src/core/codec/types.ts

@@ -51,8 +51,6 @@ export interface Extras {
 
 /** Per-write overrides for encoder operations. */
 export interface WriteOptions {
-  /** Override the default clientId for this write. */
-  clientId?: string;
   /** Override the default extras for this write. */
   extras?: Extras;
   /** Message identity for projection routing. Stamped as `codec-message-id`. */
@@ -66,7 +64,7 @@ export interface WriteOptions {
 /**
  * A codec-agnostic description of a discrete Ably message. Used on both sides:
  * - **Encode:** the domain encoder describes what to publish; the encoder core
- *   handles header merging, clientId resolution, and the actual publish.
+ *   handles header merging and the actual publish.
  * - **Decode:** the decoder core extracts these fields from an
  *   `Ably.InboundMessage` before calling domain hooks, keeping hooks free of
  *   Ably SDK types.
@@ -75,7 +73,7 @@ export interface WriteOptions {
  * (strings, objects, etc.) — Ably handles serialization natively.
  */
 export interface MessagePayload {
-  /** Ably message name (e.g. "text", "tool-input", "user-message"). */
+  /** Ably message name — the wire direction (`ai-output` / `ai-input`). */
   name: string;
   /** Message data. Ably handles serialization — strings, objects, and arrays are all valid. */
   data: unknown;
@@ -97,7 +95,7 @@ export interface MessagePayload {
  * concatenated for recovery and prefix-matching on the decoder.
  */
 export interface StreamPayload {
-  /** Ably message name (e.g. "text", "reasoning", "tool-input"). */
+  /** Ably message name — `ai-output` (only outputs stream); not the codec `kind` / stream family. */
   name: string;
   /** Initial or closing data for the stream. Must be a string for append/accumulate semantics. */
   data: string;
@@ -119,7 +117,7 @@ export interface StreamPayload {
  * Accumulates text across appends and tracks lifecycle (open/closed).
  */
 export interface StreamTrackerState {
-  /** Ably message name (e.g. "text", "reasoning", "tool-input"). */
+  /** Ably message name — `ai-output` (only outputs stream); not the codec `kind` / stream family. */
   name: string;
   /** Stream identifier (e.g. chunk.id for text, toolCallId for tool-input). */
   streamId: string;
@@ -135,6 +133,16 @@ export interface StreamTrackerState {
    * Initially set from the first publish, but may be replaced on update.
    */
   transportHeaders: Record<string, string>;
+  /**
+   * Highest `Message.version.serial` incorporated into this tracker.
+   * Versions are lexicographically comparable within one message serial, so
+   * a delivery carrying a version at or below this value is already
+   * incorporated and decodes to nothing. Stamped at first contact (a
+   * never-mutated message's version serial equals the message serial, which
+   * is also the fallback when the version carries no serial) and advanced by
+   * each version-bearing delivery.
+   */
+  version: string;
   /** Whether this stream has been closed (complete or cancelled). */
   closed: boolean;
 }
@@ -149,9 +157,12 @@ export interface StreamTrackerState {
  */
 export interface ReducerMeta {
   /**
-   * Ably channel serial of the message that produced this event. The reducer
-   * uses this for idempotency / dedup: events at or below the projection's
-   * high-water-mark serial must be skipped (no-op return).
+   * Ably channel serial of the wire message that produced this event, or `''`
+   * for a not-yet-sequenced optimistic (local) fold. Ordering context only:
+   * the transport invokes `fold` in canonical serial order and exactly once
+   * per event, so the reducer must not treat a same-or-lower serial as a
+   * replay to skip — ordering and dedup are the transport's job, not the
+   * reducer's.
    */
   serial: string;
   /**
@@ -168,9 +179,14 @@ export interface ReducerMeta {
  * result every time — `fold` is a pure function and the reducer holds no
  * instance state.
  *
- * Idempotency: 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.
+ * Ordering, deduplication, and replay are the transport's responsibility, not
+ * the reducer's. The transport invokes `fold` exactly once per event, in
+ * canonical order — wire messages ascending by serial, events within a wire in
+ * decode order — refolding a node from a fresh `init` when a late wire would
+ * otherwise land out of order. The reducer therefore folds unconditionally: it
+ * must not keep a serial high-water-mark or skip "already-seen" events.
+ * Last-writer-wins for events competing over the same state falls out of fold
+ * order, since the highest-serial event folds last.
  *
  * Mutation: `fold` is allowed to mutate the projection passed in and return
  * it. The caller treats the projection as single-owner and never retains a
@@ -180,31 +196,56 @@ export interface Reducer<TEvent, TProjection> {
   /**
    * Build an empty initial projection. Called once per conversation node — a
    * Run node or a run-less input node — before any of that node's events are
-   * folded.
+   * folded, and again on every refold of that node.
    */
   init(): TProjection;
   /**
    * Fold one TEvent into the projection and return the updated projection.
-   * The reducer may mutate `state` in place.
+   * Invoked exactly once per event, in canonical order; the reducer may mutate
+   * `state` in place.
    */
   fold(state: TProjection, event: TEvent, meta: ReducerMeta): TProjection;
 }
 
+/**
+ * A decoded event tagged with the wire direction it arrived on. The reducer
+ * folds this union (not a bare `TInput | TOutput`) so it can dispatch on
+ * `direction` rather than inspecting the event's shape. Direction is derived
+ * once, from the Ably message name, at decode time (see `toCodecEvents`) — the
+ * authoritative signal, since a single message is either `ai-input` or
+ * `ai-output` but never both.
+ * @template TInput - The codec's input union.
+ * @template TOutput - The codec's output union.
+ */
+export type CodecEvent<TInput, TOutput> =
+  | {
+      /** The event arrived on the `ai-input` wire. */
+      readonly direction: 'input';
+      /** The decoded input event. */
+      readonly event: TInput;
+    }
+  | {
+      /** The event arrived on the `ai-output` wire. */
+      readonly direction: 'output';
+      /** The decoded output event. */
+      readonly event: TOutput;
+    };
+
 // ---------------------------------------------------------------------------
 // Encoder — direction-typed publication API
 // ---------------------------------------------------------------------------
 
 /** Options passed to a codec's `createEncoder` factory. */
 export interface EncoderOptions {
-  /** Default clientId for all writes. */
-  clientId?: string;
   /** Default extras (e.g. headers) merged into every Ably message. */
   extras?: Extras;
   /** Hook called before each Ably message is published. Mutate the message in place to add transport-level headers under `extras.ai`. */
   onMessage?: (message: Ably.Message) => void;
   /**
-   * Default `codec-message-id` for messages where the event payload doesn't
-   * supply one. Overridden by `WriteOptions.messageId` per-publish.
+   * Fallback domain message id surfaced to output escape hatches as
+   * `ctx.messageId` (e.g. the Vercel `start` hatch injects it when a chunk
+   * carries no `messageId` of its own). Unrelated to the wire
+   * codec-message-id transport header, which `WriteOptions.messageId` stamps.
    */
   messageId?: string;
 }
@@ -219,24 +260,24 @@ export interface EncoderOptions {
 export interface Encoder<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent> {
   /**
    * Encode and publish a single client input on the `ai-input` wire.
-   * Throws synchronously if the codec cannot encode the given input
+   * Rejects if the codec cannot encode the given input
    * variant.
    */
   publishInput(input: TInput, options?: WriteOptions): Promise<void>;
   /**
    * Encode and publish a single agent output on the `ai-output` wire.
-   * Throws synchronously if the codec cannot encode the given output
+   * Rejects if the codec cannot encode the given output
    * variant.
    */
   publishOutput(output: TOutput, options?: WriteOptions): Promise<void>;
   /**
-   * Cancel any in-progress streams and emit a codec-specific cancel signal.
-   * Idempotent across repeated calls — a second `cancel` is a no-op. Must not
-   * be called after `close`; doing so throws because the encoder is already
-   * closed.
-   * @param reason - Optional reason string for the cancellation (e.g. 'cancelled').
+   * Close all in-progress streamed messages as cancelled (status:cancelled) and
+   * flush pending appends. Pure transport mechanics — emits no codec output.
+   * Idempotent: streams already cancelled are not re-appended. Must not be
+   * called after `close`; doing so throws because the encoder is already closed.
+   * Run termination is signalled separately by the transport `ai-run-end` event.
    */
-  cancel(reason?: string): Promise<void>;
+  cancelStreams(): Promise<void>;
   /** Flush pending appends and release encoder resources. */
   close(): Promise<void>;
 }
@@ -263,6 +304,12 @@ export interface DecodedMessage<TInput extends CodecInputEvent, TOutput extends
  * compaction, partial-history page boundary, rewind miss) synthesizes any
  * missing start events before deltas reach the SDK — the reducer always
  * sees a clean `(start, delta*, end)` sequence.
+ *
+ * Trackers are version-guarded: a delivery whose `Message.version.serial`
+ * is at or below the version already incorporated decodes to nothing. One
+ * decoder instance can therefore be shared by the live subscription and
+ * history hydration — whichever route delivers a message's content first
+ * wins, and the other route's covered deliveries are no-ops.
  */
 export interface Decoder<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent> {
   /** Decode one Ably inbound message into the input/output halves. */
@@ -302,10 +349,11 @@ export interface CodecInputEvent {
    * Pointer to another codec-message this input references. The semantic
    * depends on `kind` — for `regenerate`, the assistant codec-message to
    * regenerate; codec-specific `kind`s may give it other meanings. The
-   * input event itself does not create a fork — it requests one. The fork
+   * input event itself does not create a fork — it requests one: the
+   * transport reads `target` off the input (e.g. the client session maps a
+   * regenerate's target into its transport headers) and the fork
    * relationship is established on the agent's response (and on
-   * `ai-run-start`), which the codec encoder maps `target` to via the
-   * wire's `fork-of` header.
+   * `ai-run-start`).
    */
   target?: string;
   /**
@@ -359,7 +407,7 @@ export interface Regenerate extends CodecInputEvent {
  * The core is domain-independent: it knows only that this input amends the
  * assistant at `codecMessageId` and carries a codec-defined `payload`. The
  * shape of `payload` (e.g. the tool-call id and output value) is supplied
- * by the codec via `TPayload` — see the Vercel layer's payload type.
+ * by the codec via `TPayload` (e.g. a tool-call id and output value).
  *
  * Codecs opt in to client-side tool resolution by including this variant
  * in their `TInput` union. Codecs whose domain model doesn't natively
@@ -382,7 +430,7 @@ export interface ToolResult<TPayload> extends CodecInputEvent {
  * Well-known input variant: client-published tool result (failure). The
  * tool ran and failed. Mutates the assistant codec-message addressed by
  * `codecMessageId`. The failure detail (e.g. tool-call id and error text)
- * is the codec's domain `payload` — see the Vercel layer's payload type.
+ * is the codec's domain `payload`.
  * @template TPayload - The codec's domain payload for a tool-result failure.
  */
 export interface ToolResultError<TPayload> extends CodecInputEvent {
@@ -400,7 +448,7 @@ export interface ToolResultError<TPayload> extends CodecInputEvent {
  * codec-message addressed by `codecMessageId` — flipping the targeted
  * tool call from pending-approval to approved or denied. The decision
  * detail (e.g. tool-call id, approved flag, reason) is the codec's domain
- * `payload` — see the Vercel layer's payload type.
+ * `payload`.
  *
  * Codecs may layer approval semantics on top of domain models that don't
  * natively support gating tool execution behind an approval — the codec
@@ -439,6 +487,16 @@ export type ToolResultErrorPayloadOf<TInput> = TInput extends ToolResultError<in
  */
 export type ToolApprovalResponsePayloadOf<TInput> = TInput extends ToolApprovalResponse<infer P> ? P : never;
 
+/**
+ * Extract the domain message type (`TMessage`) carried by a codec's
+ * {@link UserMessage} member from its `TInput` union, or `never` if the codec
+ * has no user-message variant. Lets the core well-known input factories type
+ * `createUserMessage` from `TInput` alone, without a separate message type
+ * parameter.
+ * @template TInput - The codec's input union.
+ */
+export type UserMessageOf<TInput> = TInput extends UserMessage<infer M> ? M : never;
+
 // ---------------------------------------------------------------------------
 // Codec output events — base shape for the output side
 // ---------------------------------------------------------------------------
@@ -451,9 +509,8 @@ export type ToolApprovalResponsePayloadOf<TInput> = TInput extends ToolApprovalR
  * fields on outputs without a breaking generic-arity change.
  *
  * The `type` discriminator is required on every variant so the codec's
- * reducer can switch on it. `AI.UIMessageChunk` already satisfies this
- * constraint structurally — its `type` literal is assignable to
- * `string` — so the Vercel codec needs no implementation changes.
+ * reducer can switch on it — any domain union whose members carry a `type`
+ * string literal satisfies it structurally.
  *
  * No routing fields today: outputs carry no per-event `codecMessageId` /
  * `parent` / `forkOf` overrides. Those move onto this base when a concrete
@@ -512,7 +569,13 @@ export interface Codec<
   TOutput extends CodecOutputEvent,
   TProjection,
   TMessage,
-> extends Reducer<TInput | TOutput, TProjection> {
+> extends Reducer<CodecEvent<TInput, TOutput>, TProjection> {
+  /**
+   * Optional Ably-Agent identifier. When present, the agent-registration path
+   * registers it on the channel (so traffic is attributed to this codec); when
+   * absent, the codec opts out of registration. Read directly by `registerAgent`.
+   */
+  readonly adapterTag?: string;
   /** Create a stateful encoder bound to the given channel. */
   createEncoder(channel: ChannelWriter, options?: EncoderOptions): Encoder<TInput, TOutput>;
   /** Create a stateful decoder for converting Ably inbound messages into typed inputs and outputs. */