@ably/ai-transport 0.2.0 → 0.3.0

package/dist/constants.d.ts

@@ -116,13 +116,13 @@ export declare const EVENT_RUN_END = "ai-run-end";
  * Message name: every agent-published codec event (text, reasoning, tool calls,
  * tool outputs, lifecycle helpers, file / source parts, data-* chunks) rides
  * this single wire name. The codec event's own `type` is carried in the
- * codec-level `type` header so the decoder can dispatch.
+ * SDK-controlled codec-level `kind` header so the decoder can dispatch.
  */
 export declare const EVENT_AI_OUTPUT = "ai-output";
 /**
  * Message name: every client-published codec event (user-message parts,
  * tool-approval responses, regenerate signals) rides this single wire
- * name. The codec event's own kind is carried in the codec-level `type`
+ * name. The codec event's own kind is carried in the codec-level `kind`
  * header so the decoder can dispatch.
  */
 export declare const EVENT_AI_INPUT = "ai-input";

package/dist/core/agent.d.ts

@@ -9,20 +9,35 @@
  * `RealtimeWithOptions` shape to write it.
  */
 import type * as Ably from 'ably';
+/**
+ * The space-separated `params.agent` string this SDK stamps on channel ATTACH —
+ * `ai-transport-js/<version>` plus the codec's adapter tag when present. Pure:
+ * unlike {@link registerAgent} it does not mutate the client. Use it to seed a
+ * `<ChannelProvider options>` so ably-js's React hooks append their own agent
+ * additively (`channelOptionsForReactHooks`) rather than overwriting this SDK's.
+ * @param codec - The codec instance whose optional identifier opts into registration.
+ * @param codec.adapterTag - The optional Ably-Agent identifier; registered as an agent when present.
+ * @returns The channel `params.agent` string.
+ */
+export declare const channelAgent: (codec?: {
+    readonly adapterTag?: string;
+}) => string;
 /**
  * Register this SDK (and optionally a codec) on the supplied Realtime client
  * and return the channel options the caller should pass to
  * `client.channels.get(...)` so the agent is also carried on channel ATTACH.
- * Sets `options.agents['ai-transport-js'] = VERSION`. When the codec carries
- * an internal `adapterTag` field (via {@link AdapterTagHolder}), also sets
- * `options.agents[adapterTag] = VERSION`.
+ * Sets `options.agents['ai-transport-js'] = VERSION`. When the codec carries an
+ * `adapterTag`, also sets `options.agents[adapterTag] = VERSION`.
  * Idempotent — repeated calls with the same client and codec produce the same keys/values.
  * Spec: AIT-CT1a, AIT-CT1a2, AIT-CT1a3, AIT-ST1a, AIT-ST1a2, AIT-ST1a3.
  * @param client - The Ably Realtime client to register on.
- * @param codec - The codec instance; cast to {@link AdapterTagHolder} to detect an optional identifier.
+ * @param codec - The codec instance whose optional identifier opts into registration.
+ * @param codec.adapterTag - The optional Ably-Agent identifier; registered as an agent when present.
  * @returns Channel options containing `params.agent` for `channels.get`.
  */
-export declare const registerAgent: (client: Ably.Realtime, codec?: unknown) => {
+export declare const registerAgent: (client: Ably.Realtime, codec?: {
+    readonly adapterTag?: string;
+}) => {
     params: {
         agent: string;
     };

package/dist/core/channel-options.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Channel-mode resolution shared by the sessions and the React provider.
+ *
+ * Presence, pub/sub, and annotation publishing are all part of the server's
+ * default channel-mode set, so a channel attached with no mode flags is granted
+ * them automatically. LiveObjects is different: object operations require the
+ * `object_subscribe` / `object_publish` modes, which are NOT in the default
+ * set, so the channel must be attached with explicit modes to use them.
+ *
+ * Setting `modes` on the wire is a full replacement, not additive: the moment
+ * an ATTACH carries any mode flag the server takes that bitfield verbatim and
+ * never falls back to its default set. So requesting object modes means also
+ * requesting everything the default set would grant, plus the object modes.
+ * {@link AIT_BASE_MODES} is exactly the server default, so opting into extra
+ * modes adds the extras and changes nothing else.
+ *
+ * Every place that resolves the session's channel options — both session
+ * constructors and the React `<ChannelProvider>` — must funnel through
+ * {@link resolveChannelModes} so they all request the SAME modes in the SAME
+ * order. ably-js compares modes order- and duplicate-sensitively when deciding
+ * whether a `setOptions` call needs a reattach; identical arrays compare equal,
+ * so consistent resolution avoids both spurious reattaches and silent mode
+ * reversion when one writer omits modes another set.
+ */
+import type * as Ably from 'ably';
+/**
+ * The modes AI Transport always needs — byte-for-byte the server's default
+ * channel-mode set (`PUBLISH | SUBSCRIBE | PRESENCE | PRESENCE_SUBSCRIBE |
+ * ANNOTATION_PUBLISH`). Because this equals the default, requesting it plus
+ * extra modes (e.g. {@link OBJECT_MODES}) grants the same access as the default
+ * set plus those extras.
+ */
+export declare const AIT_BASE_MODES: readonly Ably.ChannelMode[];
+/**
+ * The channel modes required to read and write Ably LiveObjects. Pass as the
+ * session's `channelModes` option (`channelModes: OBJECT_MODES`) to enable the
+ * `object` accessor on a session and the LiveObjects channel hooks under a
+ * `<ClientSessionProvider>`.
+ */
+export declare const OBJECT_MODES: readonly Ably.ChannelMode[];
+/**
+ * Resolve the channel modes AI Transport should request on its channel.
+ *
+ * Returns `undefined` when the caller asks for no extra modes, so the channel
+ * attaches with no mode flags and the server applies its default set. When
+ * extra modes are supplied (e.g. {@link OBJECT_MODES}),
+ * returns {@link AIT_BASE_MODES} unioned with them, de-duplicated and in a
+ * fixed canonical order so repeated resolutions compare equal.
+ *
+ * Modes outside {@link MODE_ORDER} (which should not occur for a valid
+ * {@link Ably.ChannelMode}, but is possible with the type's lowercase aliases)
+ * are appended after the canonical modes, sorted alphabetically, so the result
+ * is still deterministic.
+ * @param extraModes - Additional modes to request on top of {@link AIT_BASE_MODES}. Omit or pass an empty array to request no modes at all.
+ * @returns The canonically-ordered, de-duplicated mode set, or `undefined` when no extra modes were requested.
+ */
+export declare const resolveChannelModes: (extraModes?: readonly Ably.ChannelMode[]) => Ably.ChannelMode[] | undefined;

package/dist/core/codec/codec-event.d.ts

@@ -0,0 +1,9 @@
+import { CodecEvent, CodecInputEvent, CodecOutputEvent, DecodedMessage } from './types.js';
+/**
+ * Tag a decoded message's events with their wire direction.
+ * @template TInput - The codec's input union.
+ * @template TOutput - The codec's output union.
+ * @param decoded - The decoder's input/output split for one inbound message.
+ * @returns The events as a direction-tagged {@link CodecEvent} list, inputs first.
+ */
+export declare const toCodecEvents: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent>(decoded: DecodedMessage<TInput, TOutput>) => CodecEvent<TInput, TOutput>[];

package/dist/core/codec/decoder.d.ts

@@ -5,7 +5,10 @@ import { MessagePayload, StreamTrackerState } from './types.js';
  *
  * Handles the Ably message action patterns (create, append, update, delete)
  * and delegates to domain-specific hooks for event building and discrete
- * event decoding.
+ * event decoding. Stream trackers are version-guarded: a delivery whose
+ * `Message.version.serial` the tracker has already incorporated decodes to
+ * nothing, so the same decoder instance can serve both the live
+ * subscription and history hydration without double-decoding.
  *
  * Domain decoders call `createDecoderCore(hooks, options)` and provide hooks
  * for stream classification, event building, and discrete decoding. Hooks

package/dist/core/codec/define-codec.d.ts

@@ -0,0 +1,100 @@
+import { InputBuilder, InputDescriptor } from './input-descriptors.js';
+import { OutputBuilder, OutputDescriptor } from './output-descriptors.js';
+import { Codec, CodecEvent, CodecInputEvent, CodecMessage, CodecOutputEvent, ReducerMeta, StreamTrackerState } from './types.js';
+import { WellKnownInputFactories } from './well-known-inputs.js';
+export type { InputBuilder } from './input-descriptors.js';
+export type { OutputBuilder } from './output-descriptors.js';
+/** Context passed to a {@link LifecyclePolicy} `onDiscrete` repair function. */
+export interface LifecycleDiscreteContext {
+    /** The inbound codec-tier headers (e.g. to recover a stream's message id). */
+    codecHeaders: Record<string, string>;
+}
+/**
+ * Declarative decode-time lifecycle repair, applied when joining a stream
+ * mid-flight (history compaction, rewind miss, partial page). Each function
+ * performs its side effect on the codec's lifecycle tracker (captured by the
+ * factory that builds the policy) and RETURNS lead-in events to PREPEND; the
+ * generic decoder ALWAYS runs the descriptor driver after and appends its
+ * output, so the policy never replaces a decode. A codec with no repair
+ * supplies no policy.
+ * @template TOutput - The codec's output union.
+ */
+export interface LifecyclePolicy<TOutput> {
+    /**
+     * Keyed on the discrete codec `kind`. Returns lead-in events to prepend
+     * (empty array = none) after applying any tracker side effect.
+     */
+    onDiscrete?: Record<string, (runId: string, ctx: LifecycleDiscreteContext) => TOutput[]>;
+    /** Lead-in prepended to a stream's start events (mid-stream-join pre-roll). */
+    onStreamStart?: (runId: string, tracker: StreamTrackerState) => TOutput[];
+}
+/**
+ * The reducer parts a codec supplies. `TProjection` and `TMessage` infer from
+ * these, so `defineCodec` callers need not spell them out.
+ * @template TInput - The codec's input union.
+ * @template TOutput - The codec's output union.
+ * @template TProjection - The per-node projection the reducer folds into.
+ * @template TMessage - The per-message domain type.
+ */
+export interface CodecReducer<TInput, TOutput, TProjection, TMessage> {
+    /** Build an empty projection for a node. */
+    init: () => TProjection;
+    /** Fold one direction-tagged input or output event into the projection. */
+    fold: (state: TProjection, event: CodecEvent<TInput, TOutput>, meta: ReducerMeta) => TProjection;
+    /** Extract the per-message list (each paired with its codec-message-id). */
+    getMessages: (projection: TProjection) => CodecMessage<TMessage>[];
+}
+/**
+ * The parts a codec supplies to {@link defineCodec}.
+ * @template TInput - The codec's input union.
+ * @template TOutput - The codec's output union.
+ * @template TProjection - The per-node projection the reducer folds into.
+ * @template TMessage - The per-message domain type.
+ */
+export interface DefineCodecConfig<TInput extends {
+    kind: string;
+}, TOutput extends {
+    type: string;
+}, TProjection, TMessage> {
+    /** Optional Ably-Agent identifier registered on the channel; omit to opt out. */
+    adapterTag?: string;
+    /** Reducer parts; `TProjection` / `TMessage` infer from here. */
+    reducer: CodecReducer<TInput, TOutput, TProjection, TMessage>;
+    /**
+     * The declarative output (`ai-output`) descriptor table, returned from the
+     * injected `{ event, stream }` builder (both curried on `TOutput`).
+     */
+    output: (b: OutputBuilder<TOutput>) => readonly OutputDescriptor<TOutput>[];
+    /**
+     * The declarative input (`ai-input`) descriptor table, returned from the
+     * injected `{ event, batch }` builder (both curried on `TInput`).
+     */
+    input: (b: InputBuilder<TInput>) => readonly InputDescriptor<TInput>[];
+    /**
+     * Factory for a fresh decode lifecycle policy per decoder instance (the
+     * policy's closures capture a fresh, per-decoder lifecycle tracker). Omit
+     * for a codec with no mid-stream-join repair.
+     */
+    decodeLifecycle?: () => LifecyclePolicy<TOutput>;
+}
+/**
+ * A codec assembled by {@link defineCodec}: a conforming {@link Codec} whose
+ * well-known input factories are typed concretely by {@link WellKnownInputFactories}
+ * (so `createToolResult` etc. are callable without a guard). The factory methods
+ * are sourced from `WellKnownInputFactories` rather than `Codec` because the
+ * former types them against `UserMessageOf<TInput>` / `ToolResultPayloadOf<TInput>`
+ * — equal to the codec's `TMessage` / payloads for every real codec, but not
+ * provably so to the generic type system. At a concrete call site a
+ * `DefinedCodec` is assignable to the corresponding `Codec`.
+ */
+export type DefinedCodec<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> = Omit<Codec<TInput, TOutput, TProjection, TMessage>, keyof WellKnownInputFactories<TInput>> & WellKnownInputFactories<TInput>;
+/**
+ * Assemble a fully-formed {@link Codec} from a codec's parts. Curried on the
+ * input/output unions so `TProjection` / `TMessage` infer from `config.reducer`
+ * — a caller writes `defineCodec<TInput, TOutput>()({ ... })` and never spells
+ * out the projection or message types.
+ * @template TInput - The codec's input union.
+ * @template TOutput - The codec's output union.
+ * @returns A function taking the codec's parts and returning the assembled codec.
+ */
+export declare const defineCodec: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent>() => <TProjection, TMessage>(config: DefineCodecConfig<TInput, TOutput, TProjection, TMessage>) => DefinedCodec<TInput, TOutput, TProjection, TMessage>;

package/dist/core/codec/encoder.d.ts

@@ -26,7 +26,7 @@ export interface EncoderCore {
     startStream(streamId: string, payload: StreamPayload, opts?: WriteOptions): Promise<void>;
     /**
      * Append data to an in-flight streamed message. Fire-and-forget: errors are
-     * collected internally and surfaced by {@link closeStream}, {@link cancelStream},
+     * collected internally and surfaced by {@link closeStream},
      * {@link cancelAllStreams} or {@link close}.
      * @throws {Ably.ErrorInfo} InvalidArgument if there is no active stream for `streamId` or the core is closed.
      */
@@ -37,11 +37,6 @@ export interface EncoderCore {
      * @throws {Ably.ErrorInfo} InvalidArgument if there is no active stream for `streamId`, or the encoder has been closed; EncoderRecoveryFailed if a failed append cannot be recovered during the flush.
      */
     closeStream(streamId: string, payload: StreamPayload): Promise<void>;
-    /**
-     * Cancel a single in-progress stream (status:cancelled) and flush all
-     * pending appends for recovery before returning.
-     */
-    cancelStream(streamId: string, opts?: WriteOptions): Promise<void>;
     /**
      * Cancel all in-progress streams (status:cancelled) and flush all
      * pending appends for recovery before returning.
@@ -53,7 +48,7 @@ export interface EncoderCore {
 /**
  * Create an encoder core bound to the given channel writer.
  * @param writer - The channel writer to publish messages through.
- * @param options - Encoder configuration (clientId, extras, hooks, logger).
+ * @param options - Encoder configuration (extras, hooks, logger).
  * @returns A new {@link EncoderCore} instance.
  */
 export declare const createEncoderCore: (writer: ChannelWriter, options?: EncoderCoreOptions) => EncoderCore;

package/dist/core/codec/field-bag.d.ts

@@ -0,0 +1,85 @@
+import { HeaderField } from './fields.js';
+import { OutputDescriptor, OutputEventDescriptor } from './output-descriptors.js';
+/** The codec header carrying the SDK-controlled dispatch kind / stream family id. */
+export declare const KIND_HEADER = "kind";
+/**
+ * Derive a wildcard dispatch predicate from a descriptor literal: a literal
+ * ending in `-*` matches any value sharing its prefix, so the literal and its
+ * predicate can never disagree. Returns `undefined` for an exact literal.
+ * Shared by the output event builder and the input part builder so the `-*`
+ * sentinel rule lives in one place, next to the {@link partFor} that consumes it.
+ * @param literal - The declared descriptor literal (`type` / `partType`).
+ * @returns A prefix-match predicate for a wildcard literal, else `undefined`.
+ */
+export declare const wildcardMatcher: (literal: string) => ((value: string) => boolean) | undefined;
+/**
+ * The codec header carrying a batch part's sub-discriminator. A batch stamps it
+ * on every exploded part on encode; the decoder reads it back to resolve the
+ * matching part descriptor. Centralised so the key has one home across the
+ * input encode and decode drivers and cannot drift between them.
+ */
+export declare const PART_TYPE_HEADER = "partType";
+/**
+ * Read the value at a declared field key off a source object.
+ * @param source - The object to index (a chunk, or a lensed sub-object such as a payload).
+ * @param key - The declared field key.
+ * @returns The value at `key`, typed `unknown`.
+ */
+export declare const prop: (source: object, key: string) => unknown;
+/**
+ * Build a codec-headers record from a source object through declared fields,
+ * seeded with the dispatch `kind`. Each field writes the value at its key on
+ * `source`; an optional `keys` subset restricts which fields are written.
+ * @param fields - The declared header fields.
+ * @param kindValue - The dispatch kind / stream family id to seed under {@link KIND_HEADER}.
+ * @param source - The object to read field values from (a chunk, or a lensed payload).
+ * @param keys - Optional subset of field keys to write; omit to write all.
+ * @returns The codec-headers record.
+ */
+export declare const writeFields: (fields: readonly HeaderField<unknown>[], kindValue: string, source: object, keys?: readonly string[]) => Record<string, string>;
+/**
+ * Read declared fields out of a codec-headers record into a bag keyed by field key.
+ * A field that reads `undefined` (absent, with no default) contributes no key — the
+ * bag carries only the values that are actually present.
+ * @param fields - The declared header fields.
+ * @param headers - The inbound codec-tier headers.
+ * @returns A bag of the present field values, keyed by each field's key.
+ */
+/** The structural slice of a part descriptor {@link partFor} dispatches on. */
+interface PartDispatch {
+    /** The exact `partType` literal, or the `-*` wildcard literal for a family. */
+    partType: string;
+    /** Wildcard dispatch predicate; absent for an exact part. */
+    match?: (partType: string) => boolean;
+}
+/**
+ * Resolve the part descriptor for a `partType`: an exact non-wildcard match,
+ * else a wildcard whose derived predicate accepts it. Wildcards are excluded
+ * from the exact pass — only their predicate may route to them. Shared by the
+ * input encode and decode drivers.
+ * @param parts - The batch's part descriptor sub-table.
+ * @param partType - The `partType` to resolve (from `partTypeOf` on encode, the wire header on decode).
+ * @returns The matching part descriptor, or undefined when none matches.
+ */
+export declare const partFor: <P extends PartDispatch>(parts: readonly P[], partType: string) => P | undefined;
+/** An output descriptor set's event descriptors, split for dispatch. */
+export interface OutputEventDispatch<U> {
+    /** Exact (non-wildcard) event descriptors, keyed by `type`. */
+    discreteByType: Map<string, OutputEventDescriptor<U>>;
+    /** Wildcard event descriptors, dispatched by their `match` predicate. */
+    wildcards: OutputEventDescriptor<U>[];
+}
+/**
+ * Partition an output descriptor set's `event` descriptors into an exact-type
+ * map and a wildcard list. Stream descriptors are skipped — each driver indexes
+ * those by its own key (phase on encode, kind on decode). Shared by the output
+ * encode and decode drivers so the exact-vs-wildcard split has one home.
+ * @template U - The codec's event union.
+ * @param descriptors - The full descriptor set (events + streamed families).
+ * @returns The event descriptors split into {@link OutputEventDispatch}.
+ */
+export declare const partitionOutputEvents: <U extends {
+    type: string;
+}>(descriptors: readonly OutputDescriptor<U>[]) => OutputEventDispatch<U>;
+export declare const readFields: (fields: readonly HeaderField<unknown>[], headers: Record<string, string>) => Record<string, unknown>;
+export {};

package/dist/core/codec/fields.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Typed header-field bindings.
+ *
+ * A {@link HeaderField} binds a codec header key to its value type **once**,
+ * and exposes a symmetric {@link HeaderField.read | read} / {@link
+ * HeaderField.write | write} pair over a raw `Record<string, string>` headers
+ * record. Because a single binding drives both the encode and decode side, the
+ * header key and its value type stay in lockstep across directions — a key
+ * cannot be misspelled on one side and silently read as absent on the other.
+ *
+ * This is deliberately **not** a schema library: it is a thin bidirectional
+ * string (de)serializer over the headers record. The SDK ships no hard runtime
+ * dependencies, and a schema approach would force re-declaring peer-SDK-owned
+ * types. The four constructors cover every header value shape the codecs use:
+ *
+ * - {@link strField} — string values, optional default.
+ * - {@link boolField} — `"true"`/`"false"` booleans, optional default.
+ * - {@link jsonField} — JSON-serialized structured values.
+ * - {@link enumField} — string values validated against an allow-list with a
+ *   fallback (e.g. a finish reason).
+ *
+ * Passing a default to `strField`/`boolField` makes the field **total**: its
+ * `read` returns `V` rather than `V | undefined`, for required headers that
+ * should always decode to a concrete value.
+ */
+/**
+ * A header key bound to its value type, with symmetric read/write over a raw
+ * headers record. Created via {@link strField}, {@link boolField}, {@link
+ * jsonField}, or {@link enumField}.
+ *
+ * The `key` plays a dual role in descriptor `fields` tables: it is the wire
+ * header key AND the property name the drivers read off the source object on
+ * encode and write back into the rebuilt object on decode. {@link FieldFor}
+ * enforces this — a declared field's key must name a real property of the
+ * member it lenses onto.
+ * @template V - The decoded value type this field reads and writes.
+ * @template K - The header key literal (preserved so {@link FieldFor} can match it against the member's property names).
+ */
+export interface HeaderField<V, K extends string = string> {
+    /** The raw header key this field reads from and writes to — also the source/rebuilt property name in descriptor tables. */
+    readonly key: K;
+    /**
+     * Read and decode this field's value from a headers record.
+     * @param headers - The raw codec headers record to read from.
+     * @returns The decoded value. For defaulted/validated fields this is total
+     * (the default/fallback is returned when the header is absent or invalid);
+     * otherwise `undefined` when the header is absent.
+     */
+    read(headers: Record<string, string>): V;
+    /**
+     * Encode and write this field's value into a headers record, mutating it in
+     * place. `undefined` (and `null`, for JSON values), and values whose runtime
+     * type doesn't match the field, are skipped — the key is left unset rather
+     * than written. The parameter is `unknown` (not `V`) so a field keeps `V` in
+     * a single covariant position (`read`); this lets heterogeneous fields share a
+     * `HeaderField<unknown>[]` array, which the descriptor drivers rely on. At a
+     * typed call site the caller still passes a `V`.
+     * @param headers - The headers record to mutate.
+     * @param value - The value to encode and set.
+     */
+    write(headers: Record<string, string>, value: unknown): void;
+}
+/**
+ * Symmetric codec for a descriptor's wire `data`. Many wire payloads are object
+ * envelopes a decode reads several chunk props out of (e.g. `{ errorText, input }`),
+ * so a single field can't model them. `encode` produces the wire data from the
+ * chunk; `decode` returns the chunk props the envelope contributes, merged into
+ * the rebuilt chunk by the driver.
+ * @template C - The narrowed chunk member.
+ */
+export interface DataCodec<C> {
+    /** Produce the wire `data` from the chunk. */
+    encode: (chunk: C) => unknown;
+    /**
+     * Extract the chunk props this envelope contributes from the wire `data`.
+     * Undefined-valued props are stripped when the driver rebuilds the object —
+     * every rebuild seam (output chunk, input payload, batch part) applies the
+     * same rule, since absent and undefined are indistinguishable on the wire.
+     */
+    decode: (data: unknown) => Partial<C>;
+}
+/**
+ * The header fields a descriptor may declare against member `C`. For each
+ * string-keyed property of `C`, a field is acceptable when its key IS that
+ * property name and its value type can hold the property. A mistyped key or a
+ * wrong-typed field (e.g. a `boolField` on a string property) is a compile
+ * error instead of a silently absent header.
+ * @template C - The member (chunk, payload, or part) the fields lens onto.
+ */
+export type FieldFor<C> = {
+    [K in keyof C & string]-?: HeaderField<C[K] | undefined, K>;
+}[keyof C & string];
+/**
+ * Bind a string-valued header field.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @returns A field whose `read` yields `string | undefined` (absent → `undefined`).
+ */
+export declare function strField<K extends string>(key: K): HeaderField<string | undefined, K>;
+/**
+ * Bind a string-valued header field with a default, making it total.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @param fallback - Value returned by `read` when the header is absent.
+ * @returns A field whose `read` yields `string` (absent → `fallback`).
+ */
+export declare function strField<K extends string>(key: K, fallback: string): HeaderField<string, K>;
+/**
+ * Bind a boolean-valued header field, serialized as `"true"`/`"false"`.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @returns A field whose `read` yields `boolean | undefined` (absent → `undefined`).
+ */
+export declare function boolField<K extends string>(key: K): HeaderField<boolean | undefined, K>;
+/**
+ * Bind a boolean-valued header field with a default, making it total.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @param fallback - Value returned by `read` when the header is absent.
+ * @returns A field whose `read` yields `boolean` (absent → `fallback`).
+ */
+export declare function boolField<K extends string>(key: K, fallback: boolean): HeaderField<boolean, K>;
+/**
+ * Bind a JSON-serialized header field. The value is written with
+ * `JSON.stringify` and read back with `JSON.parse`; malformed JSON reads as
+ * `undefined`. The decoded shape is a trust boundary — the caller asserts it
+ * via the `V` type parameter.
+ * @template V - The expected decoded shape of the JSON value.
+ * @template K - The header key literal. Inferred when `V` is omitted; pass it explicitly alongside `V` when the field participates in a typed descriptor `fields` table.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @returns A field whose `read` yields `V | undefined` (absent or malformed → `undefined`).
+ */
+export declare const jsonField: <V, K extends string = string>(key: K) => HeaderField<V | undefined, K>;
+/**
+ * Bind a string-valued header field validated against a fixed allow-list,
+ * falling back to a given value when the header is absent or unrecognized. Use
+ * for headers with a small closed set of valid values (e.g. a finish reason).
+ * @template T - The union of allowed string literals, inferred from `allowed`.
+ * @template K - The header key literal, inferred from `key`.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @param allowed - The exhaustive list of valid values.
+ * @param fallback - Value returned by `read` when the header is absent or not in `allowed`.
+ * @returns A total field whose `read` yields one of the allowed literals.
+ */
+export declare const enumField: <const T extends string, K extends string>(key: K, allowed: readonly T[], fallback: NoInfer<T>) => HeaderField<T, K>;

package/dist/core/codec/index.d.ts

@@ -1,7 +1,14 @@
-export type { ChannelWriter, Codec, CodecInputEvent, CodecMessage, CodecOutputEvent, DecodedMessage, Decoder, Encoder, EncoderOptions, Extras, MessagePayload, Reducer, ReducerMeta, Regenerate, StreamPayload, StreamTrackerState, ToolApprovalResponse, ToolResult, ToolResultError, UserMessage, WriteOptions, } from './types.js';
+export type { ChannelWriter, Codec, CodecEvent, CodecInputEvent, CodecMessage, CodecOutputEvent, DecodedMessage, Decoder, Encoder, EncoderOptions, Extras, MessagePayload, Reducer, ReducerMeta, Regenerate, StreamPayload, StreamTrackerState, ToolApprovalResponse, ToolResult, ToolResultError, UserMessage, WriteOptions, } from './types.js';
 export type { EncoderCore, EncoderCoreOptions } from './encoder.js';
 export { createEncoderCore } from './encoder.js';
 export type { DecoderCore, DecoderCoreHooks, DecoderCoreOptions } from './decoder.js';
 export { createDecoderCore } from './decoder.js';
 export type { LifecycleTracker, PhaseConfig } from './lifecycle-tracker.js';
 export { createLifecycleTracker } from './lifecycle-tracker.js';
+export type { DataCodec, FieldFor, HeaderField } from './fields.js';
+export { boolField, enumField, jsonField, strField } from './fields.js';
+export type { WellKnownInputFactories } from './well-known-inputs.js';
+export type { EscapeHatchCore, HeaderBuilder, OutputDecodeContext, OutputDescriptor, OutputEncodeHatchContext, OutputEventSpec, OutputStreamEndContext, OutputStreamSpec, } from './output-descriptors.js';
+export type { BatchAssembleContext, BatchMessageHeaders, BatchSpec, InputDescriptor, InputEventSpec, PartBuilder, PartSpec, } from './input-descriptors.js';
+export type { CodecReducer, DefineCodecConfig, DefinedCodec, InputBuilder, LifecycleDiscreteContext, LifecyclePolicy, OutputBuilder, } from './define-codec.js';
+export { defineCodec } from './define-codec.js';

package/dist/core/codec/input-descriptor-decoder.d.ts

@@ -0,0 +1,19 @@
+import { InputDecodeContext, InputDescriptor } from './input-descriptors.js';
+/** Decodes inbound `ai-input` messages of union `U` from an input descriptor set. */
+export interface InputDescriptorDecoder<U> {
+    /**
+     * Rebuild zero or more inputs from one inbound `ai-input` message.
+     * @param ctx - The inbound message context (codec kind, data, header tiers).
+     * @returns The decoded inputs (empty when no descriptor matches or the input is wire-only).
+     */
+    decode(ctx: InputDecodeContext): U[];
+}
+/**
+ * Build an input decode driver for an input descriptor set.
+ * @template U - The codec's input union.
+ * @param descriptors - The input descriptor set (events + batches).
+ * @returns An {@link InputDescriptorDecoder} that reconstructs inputs from the wire.
+ */
+export declare const createInputDescriptorDecoder: <U extends {
+    kind: string;
+}>(descriptors: readonly InputDescriptor<U>[]) => InputDescriptorDecoder<U>;

package/dist/core/codec/input-descriptor-encoder.d.ts

@@ -0,0 +1,22 @@
+import { InputDescriptor, InputEncodeContext, InputEncoderCore } from './input-descriptors.js';
+/** Encodes inputs of union `U` to channel operations via an input descriptor set. */
+export interface InputDescriptorEncoder<U> {
+    /**
+     * Encode one input through its descriptor.
+     * @param input - The input to encode.
+     * @param core - The input encoder core to publish through.
+     * @param ctx - Per-write context (write options, carrying the codec-message-id).
+     * @returns A promise resolving when the publish operation completes.
+     */
+    encode(input: U, core: InputEncoderCore, ctx: InputEncodeContext): Promise<void>;
+}
+/**
+ * Build an input encode driver for an input descriptor set bound to a wire name.
+ * @template U - The codec's input union.
+ * @param descriptors - The input descriptor set (events + batches).
+ * @param wireName - The Ably message name for the input direction (`ai-input`).
+ * @returns An {@link InputDescriptorEncoder} routing each input through its descriptor.
+ */
+export declare const createInputDescriptorEncoder: <U extends {
+    kind: string;
+}>(descriptors: readonly InputDescriptor<U>[], wireName: string) => InputDescriptorEncoder<U>;