@ably/ai-transport 0.1.0 → 0.3.0

package/dist/constants.d.ts

@@ -1,54 +1,128 @@
 /**
  * Shared constants used by both codec and transport layers.
  *
- * Header constants define the `x-ably-*` wire protocol. Message and event
- * name constants define the transport lifecycle signals on the channel.
+ * Header constants define the transport wire header names. Message and event
+ * name constants define the session lifecycle signals on the channel.
  *
  * These live at the top level (not in codec/ or transport/) because both
  * layers need them — the codec core reads/writes stream and status headers,
- * while the transport layer reads/writes turn, cancel, and role headers.
+ * while the transport layer reads/writes run, cancel, and role headers.
  */
 /** Header: whether this Ably message uses streaming (message appends) or is discrete. Always "true" or "false". */
-export declare const HEADER_STREAM = "x-ably-stream";
-/** Header: lifecycle status of a streamed message. Only set when x-ably-stream is "true". */
-export declare const HEADER_STATUS = "x-ably-status";
+export declare const HEADER_STREAM = "stream";
+/** Header: lifecycle status of a streamed message. Only set when stream is "true". One of "streaming", "complete", or "cancelled". */
+export declare const HEADER_STATUS = "status";
 /** Header: stream identity. Set by the encoder on every streamed message; read by the decoder to correlate streams. */
-export declare const HEADER_STREAM_ID = "x-ably-stream-id";
+export declare const HEADER_STREAM_ID = "stream-id";
 /** Header: marks a message as a discrete message part (from writeMessages). Set by publishDiscreteBatch; not set on lifecycle events from publishDiscrete. */
-export declare const HEADER_DISCRETE = "x-ably-discrete";
-/** Header: turn correlation ID. Set on every message in a turn. */
-export declare const HEADER_TURN_ID = "x-ably-turn-id";
+export declare const HEADER_DISCRETE = "discrete";
+/** Header: run correlation ID. Set on every agent-published message and on continuation client inputs, but omitted from the originating fresh client input (the agent mints the run-id at run-start). */
+export declare const HEADER_RUN_ID = "run-id";
+/** Header: invocation correlation ID; identifies a specific invocation under a run. Agent-minted and stamped by the agent on every event it publishes for the invocation — run lifecycle (run-start/resume/suspend/end) and assistant outputs. Never set by the client on its input. */
+export declare const HEADER_INVOCATION_ID = "invocation-id";
+/**
+ * Header: per-event identifier stamped by the client on every
+ * client-published event in a send — user-message events AND amend
+ * events (tool-approval responses, client tool outputs). Distinct from
+ * `codec-message-id` so it survives edits/retries that reuse the same
+ * codec-message-id, and so amend events that target an existing message can
+ * carry their own per-send identity. The invocation body lists every
+ * inputEventId the agent must observe on the channel before starting LLM
+ * work — see `Run.start()`'s input-event lookup.
+ */
+export declare const HEADER_EVENT_ID = "event-id";
 /** Header: message identity. Assigned per message (user or assistant). Used for optimistic reconciliation on the client. */
-export declare const HEADER_MSG_ID = "x-ably-msg-id";
-/** Header: clientId of the user who initiated the turn. Set by the server on stream messages. */
-export declare const HEADER_TURN_CLIENT_ID = "x-ably-turn-client-id";
+export declare const HEADER_CODEC_MESSAGE_ID = "codec-message-id";
+/** Header: clientId of the user who initiated the run. Stamped by the client on its user input and re-stamped by the agent on the run's lifecycle and stream messages. */
+export declare const HEADER_RUN_CLIENT_ID = "run-client-id";
+/**
+ * Header: clientId of the input event (the `ai-input`) that drove the
+ * current invocation. The agent reads the publisher's Ably-level `clientId`
+ * from the triggering input event on the channel and re-stamps it as
+ * `input-client-id` on every event it publishes for that invocation
+ * (run lifecycle and assistant outputs). May differ from
+ * `run-client-id` on continuation invocations driven by an input
+ * from a non-owner (e.g. a tool-result publish from a different client).
+ * Not stamped on `ai-input` events themselves — the wire publisher's
+ * Ably `clientId` already conveys that.
+ */
+export declare const HEADER_INPUT_CLIENT_ID = "input-client-id";
 /** Header: message role (e.g. "user", "assistant"). */
-export declare const HEADER_ROLE = "x-ably-role";
-/** Header: the msg-id of the existing message this Ably message amends. Present on cross-turn amendment events. */
-export declare const HEADER_AMEND = "x-ably-amend";
-/** Header: cancel a specific turn by ID. */
-export declare const HEADER_CANCEL_TURN_ID = "x-ably-cancel-turn-id";
-/** Header: cancel all turns belonging to the sender's clientId. */
-export declare const HEADER_CANCEL_OWN = "x-ably-cancel-own";
-/** Header: cancel all turns on the channel. */
-export declare const HEADER_CANCEL_ALL = "x-ably-cancel-all";
-/** Header: cancel all turns belonging to a specific clientId. */
-export declare const HEADER_CANCEL_CLIENT_ID = "x-ably-cancel-client-id";
-/** Header: the msg-id of the immediately preceding message in this branch. */
-export declare const HEADER_PARENT = "x-ably-parent";
-/** Header: the msg-id of the message this one replaces (creates a fork). */
-export declare const HEADER_FORK_OF = "x-ably-fork-of";
-/** Header: reason a turn ended (on x-ably-turn-end messages). */
-export declare const HEADER_TURN_REASON = "x-ably-turn-reason";
-/** Message name: client->server cancel signal. */
-export declare const EVENT_CANCEL = "x-ably-cancel";
-/** Message name: server publishes this to signal a turn has started. */
-export declare const EVENT_TURN_START = "x-ably-turn-start";
-/** Message name: server publishes this to signal a turn has ended. */
-export declare const EVENT_TURN_END = "x-ably-turn-end";
-/** Message name: transport-level abort signal (stream cancelled). */
-export declare const EVENT_ABORT = "x-ably-abort";
-/** Message name: transport-level error signal. */
-export declare const EVENT_ERROR = "x-ably-error";
-/** Prefix for domain-specific headers. Distinguishes codec-layer headers from transport `x-ably-*` headers. */
-export declare const DOMAIN_HEADER_PREFIX = "x-domain-";
+export declare const HEADER_ROLE = "role";
+/** Header: the codec-message-id of the immediately preceding message in this branch. */
+export declare const HEADER_PARENT = "parent";
+/** Header: the codec-message-id of the message this one replaces (creates a fork). */
+export declare const HEADER_FORK_OF = "fork-of";
+/**
+ * Header: the codec-message-id of the assistant message this run regenerates.
+ *
+ * Stamped on the regenerate wire (and echoed on `run-start`) when the
+ * client requested a regeneration. A regenerate run parents at the SAME input
+ * node as the reply it regenerates, so it joins that input's reply runs as a
+ * same-parent sibling (no fork-of). The View consults this header to resolve
+ * the message-level sibling group and to drop the regenerated message from
+ * earlier Runs in the visible chain (Spec: AIT-CT13d).
+ */
+export declare const HEADER_MSG_REGENERATE = "msg-regenerate";
+/** Header: reason a run ended (on ai-run-end messages). */
+export declare const HEADER_RUN_REASON = "run-reason";
+/**
+ * Header: the `codec-message-id` of the input event that triggered the run.
+ * The triggering input is the one whose `event-id` matches the invocation's
+ * `inputEventId` (the last input of the originating send). The agent
+ * re-stamps it on every event it publishes for the invocation (run
+ * lifecycle + assistant outputs), mirroring `input-client-id`. This is the
+ * codec-message-id the client owns at send time, so it lets the client
+ * correlate any of those events back to the originating input without
+ * depending on a client-minted run-id or invocation-id.
+ */
+export declare const HEADER_INPUT_CODEC_MESSAGE_ID = "input-codec-message-id";
+/** Header: numeric error code accompanying an `ai-run-end` with reason `error`. */
+export declare const HEADER_ERROR_CODE = "error-code";
+/** Header: human-readable error message accompanying an `ai-run-end` with reason `error`. */
+export declare const HEADER_ERROR_MESSAGE = "error-message";
+/**
+ * Message name: client->agent cancel intent. Targets a run by `run-id` (a
+ * continuation, whose run-id the client already knows) and/or by
+ * `input-codec-message-id` (a fresh send, whose run-id the agent mints at
+ * run-start — so the client can only key the cancel by the triggering input's
+ * codec-message-id it owns at send time). The agent resolves whichever is
+ * present to the registered run; a cancel that arrives before the run is known
+ * (the input-event lookup hasn't resolved the input id to a run yet) is
+ * buffered by `input-codec-message-id` and honoured when the run resolves it.
+ * Also carries an `event-id` so channel rewind redelivers it to a per-request /
+ * serverless agent that attaches after the cancel was published.
+ */
+export declare const EVENT_CANCEL = "ai-cancel";
+/** Message name: server publishes this to signal a run has started. */
+export declare const EVENT_RUN_START = "ai-run-start";
+/**
+ * Message name: server publishes this to signal a run has suspended — paused
+ * awaiting participant input (e.g. a client tool result or approval) without
+ * ending. The run stays live and may be resumed under the same `runId`.
+ * Distinct from `ai-run-end`, which is terminal.
+ */
+export declare const EVENT_RUN_SUSPEND = "ai-run-suspend";
+/**
+ * Message name: server publishes this when a subsequent invocation re-enters an
+ * already-started run (e.g. a tool-result follow-up under the same `runId`).
+ * A pure re-entry signal: unlike `ai-run-start` it carries no `parent` / `fork-of`
+ * (the original `ai-run-start` already established the run's structure).
+ */
+export declare const EVENT_RUN_RESUME = "ai-run-resume";
+/** Message name: server publishes this to signal a run has ended. */
+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
+ * 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 `kind`
+ * header so the decoder can dispatch.
+ */
+export declare const EVENT_AI_INPUT = "ai-input";

package/dist/core/agent.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Wraps the two paths chat-js uses (see ChatClient._addAgent): the
+ * `options.agents` mutation (read by ably-js when opening the initial
+ * WebSocket) and the `params.agent` channel option (sent on ATTACH so
+ * an already-open connection still carries the identifier).
+ *
+ * `options.agents` is a private API on the Realtime client — no public
+ * typed accessor exists in the `ably` package — so this module casts to a
+ * `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
+ * `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 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?: {
+    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

@@ -1,22 +1,22 @@
 import { Logger } from '../../logger.js';
-import { DecoderOutput, MessagePayload, StreamTrackerState } from './types.js';
+import { MessagePayload, StreamTrackerState } from './types.js';
 /**
  * Decoder core — action dispatch and serial tracking machinery.
  *
  * 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.
+ * for stream classification, event building, and discrete decoding. Hooks
+ * return a flat `TEvent[]` — no event-vs-message union. Per-message routing
+ * concerns (`codec-message-id`) are handled by the SDK via `ReducerMeta`, not
+ * here.
  */
 import type * as Ably from 'ably';
-/**
- * Wrap a domain event as a single-element decoder output array.
- * @param event - The domain event to wrap.
- * @returns A single-element array containing the event as a decoder output.
- */
-export declare const eventOutput: <TEvent, TMessage>(event: TEvent) => DecoderOutput<TEvent, TMessage>[];
 /** Options for creating a decoder core. */
 export interface DecoderCoreOptions {
     /** Called when a tracked stream is replaced (non-prefix update). Receives the tracker with updated state. */
@@ -27,31 +27,31 @@ export interface DecoderCoreOptions {
     logger?: Logger;
 }
 /** Hooks that a domain codec provides to the decoder core for stream classification and event building. */
-export interface DecoderCoreHooks<TEvent, TMessage> {
+export interface DecoderCoreHooks<TEvent> {
     /**
      * Build domain events emitted when a new stream starts. May return multiple
      * events (e.g. a start event and a start-step event).
      */
-    buildStartEvents(tracker: StreamTrackerState): DecoderOutput<TEvent, TMessage>[];
+    buildStartEvents(tracker: StreamTrackerState): TEvent[];
     /** Build domain events for a text delta received on a stream. */
-    buildDeltaEvents(tracker: StreamTrackerState, delta: string): DecoderOutput<TEvent, TMessage>[];
+    buildDeltaEvents(tracker: StreamTrackerState, delta: string): TEvent[];
     /**
-     * Build domain events emitted when a stream finishes (x-ably-status:finished).
-     * Not called for aborted streams. The closing headers may differ from
-     * tracker.headers if the closing append carried updated headers.
+     * Build domain events emitted when a stream completes (status:complete).
+     * Not called for cancelled streams. The closing codec headers may differ
+     * from tracker.codecHeaders if the closing append carried updated headers.
      */
-    buildEndEvents(tracker: StreamTrackerState, closingHeaders: Record<string, string>): DecoderOutput<TEvent, TMessage>[];
+    buildEndEvents(tracker: StreamTrackerState, closingCodecHeaders: Record<string, string>): TEvent[];
     /**
-     * Decode a discrete message (message.create where x-ably-stream is "false",
-     * or a non-streamable first-contact update). Handles user messages, lifecycle
-     * events, tool lifecycle, data-*, etc.
+     * Decode a discrete message (a `message.create` whose stream header is not
+     * "true", or a non-streamable first-contact update). Handles user messages,
+     * tool lifecycle, data-*, etc.
      */
-    decodeDiscrete(input: MessagePayload): DecoderOutput<TEvent, TMessage>[];
+    decodeDiscrete(input: MessagePayload): TEvent[];
 }
 /** The decoder core returned by {@link createDecoderCore}. */
-export interface DecoderCore<TEvent, TMessage> {
-    /** Decode a single Ably message into zero or more domain outputs. */
-    decode(message: Ably.InboundMessage): DecoderOutput<TEvent, TMessage>[];
+export interface DecoderCore<TEvent> {
+    /** Decode a single Ably message into zero or more domain TEvents. */
+    decode(message: Ably.InboundMessage): TEvent[];
 }
 /**
  * Create a decoder core with the given domain hooks.
@@ -59,4 +59,4 @@ export interface DecoderCore<TEvent, TMessage> {
  * @param options - Decoder configuration (callbacks, logger).
  * @returns A new {@link DecoderCore} instance.
  */
-export declare const createDecoderCore: <TEvent, TMessage>(hooks: DecoderCoreHooks<TEvent, TMessage>, options?: DecoderCoreOptions) => DecoderCore<TEvent, TMessage>;
+export declare const createDecoderCore: <TEvent>(hooks: DecoderCoreHooks<TEvent>, options?: DecoderCoreOptions) => DecoderCore<TEvent>;

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

@@ -3,7 +3,7 @@ import { ChannelWriter, EncoderOptions, MessagePayload, StreamPayload, WriteOpti
 /**
  * Encoder core — message append lifecycle machinery.
  *
- * Provides Ably primitives (publish, append, close, abort, flush) that
+ * Provides Ably primitives (publish, append, close, cancel, flush) that
  * domain-specific encoders wire their event types to.
  *
  * Domain encoders call `createEncoderCore(writer, options)` and use the
@@ -22,35 +22,33 @@ export interface EncoderCore {
     publishDiscrete(payload: MessagePayload, opts?: WriteOptions): Promise<Ably.PublishResult>;
     /** Publish multiple discrete messages atomically in a single channel publish. */
     publishDiscreteBatch(payloads: MessagePayload[], opts?: WriteOptions): Promise<Ably.PublishResult>;
-    /** Start a streamed message with x-ably-status:streaming. */
+    /** Start a streamed message with status:streaming. */
     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} or {@link close}.
+     * 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.
      */
     appendStream(streamId: string, data: string): void;
     /**
-     * Close a streamed message with x-ably-status:finished. Flushes all pending
+     * Close a streamed message with status:complete. Flushes all pending
      * appends for recovery before returning. Repeats persistent and payload headers.
+     * @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>;
     /**
-     * Abort a single in-progress stream (x-ably-status:aborted) and flush all
+     * Cancel all in-progress streams (status:cancelled) and flush all
      * pending appends for recovery before returning.
      */
-    abortStream(streamId: string, opts?: WriteOptions): Promise<void>;
-    /**
-     * Abort all in-progress streams (x-ably-status:aborted) and flush all
-     * pending appends for recovery before returning.
-     */
-    abortAllStreams(opts?: WriteOptions): Promise<void>;
+    cancelAllStreams(opts?: WriteOptions): Promise<void>;
     /** Flush + clear trackers. Idempotent. */
     close(): Promise<void>;
 }
 /**
  * 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 {};