@ably/ai-transport 0.0.1

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

@@ -0,0 +1,62 @@
+import { Logger } from '../../logger.js';
+import { DecoderOutput, 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.
+ *
+ * Domain decoders call `createDecoderCore(hooks, options)` and provide hooks
+ * for stream classification, event building, and discrete decoding.
+ */
+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. */
+    onStreamUpdate?: (tracker: StreamTrackerState) => void;
+    /** Called when a message is deleted. Receives the serial and tracker (if one exists). */
+    onStreamDelete?: (serial: string, tracker: StreamTrackerState | undefined) => void;
+    /** Logger instance for diagnostic output. */
+    logger?: Logger;
+}
+/** Hooks that a domain codec provides to the decoder core for stream classification and event building. */
+export interface DecoderCoreHooks<TEvent, TMessage> {
+    /**
+     * 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>[];
+    /** Build domain events for a text delta received on a stream. */
+    buildDeltaEvents(tracker: StreamTrackerState, delta: string): DecoderOutput<TEvent, TMessage>[];
+    /**
+     * 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.
+     */
+    buildEndEvents(tracker: StreamTrackerState, closingHeaders: Record<string, string>): DecoderOutput<TEvent, TMessage>[];
+    /**
+     * 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.
+     */
+    decodeDiscrete(input: MessagePayload): DecoderOutput<TEvent, TMessage>[];
+}
+/** 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>[];
+}
+/**
+ * Create a decoder core with the given domain hooks.
+ * @param hooks - Domain-specific hooks for stream classification, event building, and discrete decoding.
+ * @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>;

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

@@ -0,0 +1,56 @@
+import { Logger } from '../../logger.js';
+import { ChannelWriter, EncoderOptions, MessagePayload, StreamPayload, WriteOptions } from './types.js';
+/**
+ * Encoder core — message append lifecycle machinery.
+ *
+ * Provides Ably primitives (publish, append, close, abort, flush) that
+ * domain-specific encoders wire their event types to.
+ *
+ * Domain encoders call `createEncoderCore(writer, options)` and use the
+ * returned core to map domain events to Ably operations without
+ * reimplementing the message append lifecycle.
+ */
+import * as Ably from 'ably';
+/** Options for creating an encoder core. Extends {@link EncoderOptions} with a logger. */
+export interface EncoderCoreOptions extends EncoderOptions {
+    /** Logger instance for diagnostic output. */
+    logger?: Logger;
+}
+/** The core encoder primitives that domain codec encoders delegate to. */
+export interface EncoderCore {
+    /** Publish a single discrete (non-streaming) message described by a payload. */
+    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. */
+    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}.
+     */
+    appendStream(streamId: string, data: string): void;
+    /**
+     * Close a streamed message with x-ably-status:finished. Flushes all pending
+     * appends for recovery before returning. Repeats persistent and payload headers.
+     */
+    closeStream(streamId: string, payload: StreamPayload): Promise<void>;
+    /**
+     * Abort a single in-progress stream (x-ably-status:aborted) 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>;
+    /** 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).
+ * @returns A new {@link EncoderCore} instance.
+ */
+export declare const createEncoderCore: (writer: ChannelWriter, options?: EncoderCoreOptions) => EncoderCore;

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

@@ -0,0 +1,8 @@
+export { eventOutput } from './decoder.js';
+export type { ChannelWriter, Codec, DecoderOutput, DiscreteEncoder, EncoderOptions, Extras, MessageAccumulator, MessagePayload, StreamDecoder, StreamEncoder, StreamPayload, StreamTrackerState, 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';

package/dist/core/codec/lifecycle-tracker.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Generic lifecycle tracker for codec decoders.
+ *
+ * Manages per-scope (typically per-turn) tracking of lifecycle phases that
+ * must be emitted before content events. When a phase has not been emitted
+ * (e.g. mid-stream join), the tracker synthesizes the missing events using
+ * codec-provided build functions.
+ *
+ * Codecs configure the tracker with an ordered list of phases, then compose
+ * it into their decoder hooks. The tracker is independent of any specific
+ * codec or event type.
+ */
+/**
+ * Configuration for a single lifecycle phase that may need to be
+ * synthesized when missing from the wire stream.
+ */
+export interface PhaseConfig<TEvent> {
+    /** Unique key identifying this phase (e.g. "start", "start-step"). */
+    key: string;
+    /**
+     * Build the synthetic event(s) for this phase. Called with a context
+     * record that codecs populate at the call site — the tracker passes
+     * it through without interpreting it.
+     * @param context - Key-value pairs from the call site (e.g. headers).
+     * @returns One or more synthetic events to emit for this phase.
+     */
+    build(context: Record<string, string | undefined>): TEvent[];
+}
+/**
+ * Per-scope lifecycle tracker that ensures required phases are emitted
+ * before content events, synthesizing missing ones for mid-stream joins.
+ *
+ * Scoped by an arbitrary string key (typically a turn ID). Each scope
+ * tracks independently which phases have been emitted.
+ */
+export interface LifecycleTracker<TEvent> {
+    /**
+     * Ensure all configured phases have been emitted for the given scope.
+     * Returns synthetic events for any phases not yet marked as emitted,
+     * then marks them. Returns an empty array if all phases are current.
+     * @param scopeId - The scope to check (e.g. turn ID).
+     * @param context - Key-value pairs passed through to phase build functions.
+     * @returns Synthetic events for missing phases, in configuration order.
+     */
+    ensurePhases(scopeId: string, context: Record<string, string | undefined>): TEvent[];
+    /**
+     * Mark a phase as emitted from the wire (not synthetic). Call this
+     * when the real event arrives so the tracker does not re-synthesize it.
+     * @param scopeId - The scope (e.g. turn ID).
+     * @param phaseKey - The phase key to mark.
+     */
+    markEmitted(scopeId: string, phaseKey: string): void;
+    /**
+     * Reset a phase so it will be re-synthesized on the next
+     * {@link ensurePhases} call. Used for repeating phases (e.g. "start-step"
+     * resets after "finish-step").
+     * @param scopeId - The scope (e.g. turn ID).
+     * @param phaseKey - The phase key to reset.
+     */
+    resetPhase(scopeId: string, phaseKey: string): void;
+    /**
+     * Remove all tracking state for a scope. Call on turn completion
+     * (finish, abort) to free memory.
+     * @param scopeId - The scope to clear.
+     */
+    clearScope(scopeId: string): void;
+}
+/**
+ * Create a lifecycle tracker configured with the given phases.
+ * Phases are checked and synthesized in array order.
+ * @param phases - Ordered phase configurations.
+ * @returns A new {@link LifecycleTracker} instance.
+ */
+export declare const createLifecycleTracker: <TEvent>(phases: PhaseConfig<TEvent>[]) => LifecycleTracker<TEvent>;

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

@@ -0,0 +1,188 @@
+/**
+ * Core codec interfaces as defined in the general codec specification.
+ *
+ * These types define the contract between domain event streams and Ably's
+ * native message primitives (publish, append, update, delete).
+ */
+import type * as Ably from 'ably';
+/**
+ * The I/O interface that encoders use to publish to a channel.
+ * An `Ably.RealtimeChannel` satisfies this directly, but the interface
+ * allows mocking, batching, logging, or any other decorator.
+ */
+export interface ChannelWriter {
+    /** Publish one or more discrete messages to the channel. */
+    publish(message: Ably.Message | Ably.Message[], options?: Ably.PublishOptions): Promise<Ably.PublishResult>;
+    /** Append data to an existing message identified by its serial. */
+    appendMessage(message: Ably.Message, operation?: Ably.MessageOperation, options?: Ably.PublishOptions): Promise<Ably.UpdateDeleteResult>;
+    /** Replace the data of an existing message identified by its serial. */
+    updateMessage(message: Ably.Message, operation?: Ably.MessageOperation, options?: Ably.PublishOptions): Promise<Ably.UpdateDeleteResult>;
+}
+/** Shape of the extras object passed through WriteOptions and EncoderOptions. */
+export interface Extras {
+    /** Headers to attach to the Ably message extras. */
+    headers?: Record<string, string>;
+}
+/** 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 accumulator correlation. Stamped as `x-ably-msg-id`. */
+    messageId?: string;
+}
+/**
+ * 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.
+ * - **Decode:** the decoder core extracts these fields from an `Ably.InboundMessage`
+ *   before calling domain hooks, keeping hooks free of Ably SDK types.
+ *
+ * Data is `unknown` because discrete messages can carry arbitrary payloads
+ * (strings, objects, etc.) — Ably handles serialization natively.
+ */
+export interface MessagePayload {
+    /** Ably message name (e.g. "text", "tool-input", "user-message"). */
+    name: string;
+    /** Message data. Ably handles serialization — strings, objects, and arrays are all valid. */
+    data: unknown;
+    /** Headers from the Ably message extras. */
+    headers?: Record<string, string>;
+    /** Mark this message as ephemeral (not persisted in channel history). Only meaningful on encode. */
+    ephemeral?: boolean;
+}
+/**
+ * Payload for streamed messages. Data must be a string because
+ * the message append lifecycle uses text append/accumulate semantics —
+ * deltas are concatenated for recovery and prefix-matching on the decoder.
+ */
+export interface StreamPayload {
+    /** Ably message name (e.g. "text", "reasoning", "tool-input"). */
+    name: string;
+    /** Initial or closing data for the stream. Must be a string for append/accumulate semantics. */
+    data: string;
+    /** Headers from the Ably message extras. */
+    headers?: Record<string, string>;
+}
+/**
+ * Running state of a streamed message tracked by the decoder core.
+ * Accumulates text across appends and tracks lifecycle (open/closed).
+ */
+export interface StreamTrackerState {
+    /** Ably message name (e.g. "text", "reasoning", "tool-input"). */
+    name: string;
+    /** Stream identifier (e.g. chunk.id for text, toolCallId for tool-input). */
+    streamId: string;
+    /** Full accumulated text so far. */
+    accumulated: string;
+    /** Current headers for this stream. Initially set from the first publish, but may be replaced on update. */
+    headers: Record<string, string>;
+    /** Whether this stream has been closed (finished or aborted). */
+    closed: boolean;
+}
+/**
+ * The subset of encoder operations that are stateless — safe for long-lived
+ * reuse across turns. Publishes complete messages and discrete events without
+ * any streaming lifecycle (no trackers, no pending appends, no close).
+ *
+ * The server transport calls `writeMessages` to publish user messages to the
+ * channel. All messages in a single call are published atomically and share
+ * a single `x-ably-msg-id`, forming one node in the conversation tree.
+ * `writeEvent` is a public API for consumers to publish standalone discrete
+ * events outside the streaming flow — it is not called by the transport internally.
+ */
+export interface DiscreteEncoder<TEvent, TMessage> {
+    /**
+     * Encode and publish one or more domain messages atomically in a single
+     * channel publish. All messages share the encoder's transport headers
+     * (including `x-ably-msg-id`), so they form one logical unit in the
+     * conversation tree.
+     */
+    writeMessages(messages: TMessage[], options?: WriteOptions): Promise<Ably.PublishResult>;
+    /**
+     * Encode and publish a single domain event as a standalone discrete message.
+     * Available for consumers to publish events outside the streaming flow.
+     * Implementations should throw for event types that are only meaningful
+     * within a stream (e.g. text deltas).
+     */
+    writeEvent(event: TEvent, options?: WriteOptions): Promise<Ably.PublishResult>;
+}
+/**
+ * Full streaming encoder with single-turn lifecycle. Extends
+ * `DiscreteEncoder` with stateful streaming operations (`appendEvent` for
+ * content streams, `close` to flush). Used by the server transport.
+ */
+export interface StreamEncoder<TEvent, TMessage> extends DiscreteEncoder<TEvent, TMessage> {
+    /** Encode and append a streaming domain event to an in-progress stream (delta semantics). */
+    appendEvent(event: TEvent, options?: WriteOptions): Promise<void>;
+    /**
+     * Abort all in-progress streams and publish a codec-specific abort signal.
+     * Called by the transport when a turn is cancelled. Idempotent — calling
+     * abort after all streams are already aborted is a no-op.
+     * @param reason - Optional reason string for the abort (e.g. 'cancelled').
+     */
+    abort(reason?: string): Promise<void>;
+    /** Flush all pending appends and close the encoder. */
+    close(): Promise<void>;
+}
+/**
+ * A single output from the decoder: either a domain event or a complete domain message.
+ * Event outputs may carry a `messageId` read from the `x-ably-msg-id` header, which the
+ * accumulator uses to route events to the correct in-progress message.
+ */
+export type DecoderOutput<TEvent, TMessage> = {
+    kind: 'event';
+    event: TEvent;
+    messageId?: string;
+} | {
+    kind: 'message';
+    message: TMessage;
+};
+/** Decodes Ably messages into domain events and messages. */
+export interface StreamDecoder<TEvent, TMessage> {
+    /** Decode a single Ably message into zero or more domain outputs. */
+    decode(message: Ably.InboundMessage): DecoderOutput<TEvent, TMessage>[];
+}
+/** Accumulates decoder outputs into a list of domain messages, tracking active streams. */
+export interface MessageAccumulator<TEvent, TMessage> {
+    /** Process a batch of decoder outputs, updating internal message state. */
+    processOutputs(outputs: DecoderOutput<TEvent, TMessage>[]): void;
+    /** Apply an external update to a message (e.g. from an update callback). */
+    updateMessage(message: TMessage): void;
+    /** All messages accumulated so far (in-progress and completed). */
+    readonly messages: TMessage[];
+    /** Only messages whose streams have finished. */
+    readonly completedMessages: TMessage[];
+    /** Whether any stream is still actively receiving data. */
+    readonly hasActiveStream: boolean;
+}
+/** Options passed to a codec's `createEncoder` factory to configure default identity and message hooks. */
+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. */
+    onMessage?: (message: Ably.Message) => void;
+}
+/**
+ * The complete codec contract that a core transport needs.
+ *
+ * Combines factory methods (createEncoder, createDecoder, createAccumulator)
+ * with protocol knowledge (isTerminal). Transport-level concerns like turn
+ * correlation, optimistic reconciliation, and cancel signals
+ * are handled by the transport layer using standard `x-ably-*` headers.
+ */
+export interface Codec<TEvent, TMessage> {
+    /** Create a streaming encoder bound to the given channel. */
+    createEncoder(channel: ChannelWriter, options?: EncoderOptions): StreamEncoder<TEvent, TMessage>;
+    /** Create a decoder for converting Ably messages back into domain outputs. */
+    createDecoder(): StreamDecoder<TEvent, TMessage>;
+    /** Create an accumulator for building domain messages from decoder outputs. */
+    createAccumulator(): MessageAccumulator<TEvent, TMessage>;
+    /** Whether an event signals stream completion (finish, error, abort). */
+    isTerminal(event: TEvent): boolean;
+    /** Return a stable key for a message (used by MessageStore for upsert/delete). */
+    getMessageKey(message: TMessage): string;
+}

package/dist/core/transport/client-transport.d.ts

@@ -0,0 +1,10 @@
+import { ClientTransport, ClientTransportOptions } from './types.js';
+/**
+ * Create a client-side transport that manages conversation state over an Ably channel.
+ *
+ * Subscribes to the channel immediately (before attach per RTL7g). The caller should
+ * ensure the channel is attached or will be attached shortly after creation.
+ * @param options - Configuration for the client transport.
+ * @returns A new {@link ClientTransport} instance.
+ */
+export declare const createClientTransport: <TEvent, TMessage>(options: ClientTransportOptions<TEvent, TMessage>) => ClientTransport<TEvent, TMessage>;

package/dist/core/transport/conversation-tree.d.ts

@@ -0,0 +1,9 @@
+import { Logger } from '../../logger.js';
+import { ConversationTree } from './types.js';
+/**
+ * Create a ConversationTree that materializes branching history from a flat oplog.
+ * @param getKey - Codec function that returns a stable key for a domain message.
+ * @param logger - Logger for diagnostic output.
+ * @returns A new {@link ConversationTree} instance.
+ */
+export declare const createConversationTree: <TMessage>(getKey: (message: TMessage) => string, logger: Logger) => ConversationTree<TMessage>;

package/dist/core/transport/decode-history.d.ts

@@ -0,0 +1,41 @@
+import { Logger } from '../../logger.js';
+import { Codec } from '../codec/types.js';
+import { LoadHistoryOptions, PaginatedMessages } from './types.js';
+/**
+ * decodeHistory — load conversation history from an Ably channel and
+ * return decoded messages as a PaginatedMessages result.
+ *
+ * Uses a fresh decoder (not shared with the live subscription) to avoid
+ * state conflicts. Per-turn accumulators handle interleaved turns correctly.
+ *
+ * The `limit` option controls the number of **messages** returned,
+ * not the number of Ably wire messages fetched. The implementation pages
+ * back through Ably history until `limit` complete messages have
+ * been assembled. Partial turns (incomplete at the page boundary) are
+ * buffered internally and completed when `next()` fetches more pages.
+ *
+ * Only completed messages appear in `items`. A message is complete when
+ * its terminal event (finish/abort/error) has been received.
+ *
+ * Because Ably history returns newest-first while the decoder requires
+ * chronological order, all collected Ably messages are re-decoded from
+ * oldest to newest after each page fetch. This handles turns that span
+ * page boundaries correctly.
+ */
+import type * as Ably from 'ably';
+/**
+ * Load conversation history from a channel and return decoded messages.
+ *
+ * Attaches the channel if not already attached, then calls
+ * `channel.history({ untilAttach: true })` to guarantee no gap between
+ * historical and live messages. The attach is idempotent.
+ *
+ * The `limit` option controls the number of complete messages
+ * returned per page, not the number of Ably wire messages fetched.
+ * @param channel - The Ably channel to load history from.
+ * @param codec - The codec for decoding wire messages into domain messages.
+ * @param options - Pagination options.
+ * @param logger - Logger for diagnostic output.
+ * @returns The first page of decoded history messages.
+ */
+export declare const decodeHistory: <TEvent, TMessage>(channel: Ably.RealtimeChannel, codec: Codec<TEvent, TMessage>, options: LoadHistoryOptions | undefined, logger: Logger) => Promise<PaginatedMessages<TMessage>>;

package/dist/core/transport/headers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Transport header builder.
+ *
+ * Single source of truth for which `x-ably-*` headers every transport
+ * message carries. Used by the server transport (addMessages, streamResponse)
+ * and will be used by the client transport (optimistic message stamping).
+ */
+/**
+ * Build the standard transport header set for a message.
+ * @param opts - The header values to include.
+ * @param opts.role - Message role (e.g. "user", "assistant").
+ * @param opts.turnId - Turn correlation ID.
+ * @param opts.msgId - Message identity.
+ * @param opts.turnClientId - ClientId of the turn initiator.
+ * @param opts.parent - Preceding message's msg-id (for branching). Null means root.
+ * @param opts.forkOf - Forked message's msg-id (for edit/regen).
+ * @returns A headers record with the `x-ably-*` transport headers set.
+ */
+export declare const buildTransportHeaders: (opts: {
+    role: string;
+    turnId: string;
+    msgId: string;
+    turnClientId?: string;
+    parent?: string | null;
+    forkOf?: string;
+}) => Record<string, string>;

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

@@ -0,0 +1,4 @@
+export type { ActiveTurn, AddMessageOptions, AddMessagesResult, CancelFilter, CancelRequest, ClientTransport, ClientTransportOptions, CloseOptions, ConversationNode, ConversationTree, LoadHistoryOptions, MessageWithHeaders, NewTurnOptions, PaginatedMessages, SendOptions, ServerTransport, ServerTransportOptions, StreamResponseOptions, StreamResult, Turn, TurnEndReason, TurnLifecycleEvent, } from './types.js';
+export { createServerTransport } from './server-transport.js';
+export { createClientTransport } from './client-transport.js';
+export { buildTransportHeaders } from './headers.js';

package/dist/core/transport/pipe-stream.d.ts

@@ -0,0 +1,16 @@
+import { Logger } from '../../logger.js';
+import { StreamEncoder } from '../codec/types.js';
+import { StreamResult } from './types.js';
+/**
+ * Pipe an event stream through an encoder to the channel.
+ *
+ * Returns when the stream completes, is cancelled (via signal), or errors.
+ * The `reason` field of the result indicates which case occurred.
+ * @param stream - The event stream to read from.
+ * @param encoder - The streaming encoder to write events through.
+ * @param signal - Abort signal to monitor for cancellation.
+ * @param onAbort - Optional callback invoked when the stream is cancelled, before the stream ends.
+ * @param logger - Optional logger for diagnostic output.
+ * @returns The reason the pipe ended.
+ */
+export declare const pipeStream: <TEvent, TMessage>(stream: ReadableStream<TEvent>, encoder: StreamEncoder<TEvent, TMessage>, signal: AbortSignal | undefined, onAbort?: (write: (event: TEvent) => Promise<void>) => void | Promise<void>, logger?: Logger) => Promise<StreamResult>;

package/dist/core/transport/server-transport.d.ts

@@ -0,0 +1,7 @@
+import { ServerTransport, ServerTransportOptions } from './types.js';
+/**
+ * Create a server transport bound to the given channel and codec.
+ * @param options - Transport configuration.
+ * @returns A new {@link ServerTransport} instance.
+ */
+export declare const createServerTransport: <TEvent, TMessage>(options: ServerTransportOptions<TEvent, TMessage>) => ServerTransport<TEvent, TMessage>;

package/dist/core/transport/stream-router.d.ts

@@ -0,0 +1,19 @@
+import { Logger } from '../../logger.js';
+/** Routes decoded events to the correct turn's ReadableStream. */
+export interface StreamRouter<TEvent> {
+    /** Register a new stream for a turnId. Returns the ReadableStream the consumer reads from. */
+    createStream(turnId: string): ReadableStream<TEvent>;
+    /** Close the stream for a turnId. Returns true if a stream was closed. */
+    closeStream(turnId: string): boolean;
+    /** Enqueue an event to the correct stream. Returns true if routed successfully. */
+    route(turnId: string, event: TEvent): boolean;
+    /** Whether a specific turnId has an active stream. */
+    has(turnId: string): boolean;
+}
+/**
+ * Create a StreamRouter that routes decoded events to per-turn ReadableStreams.
+ * @param isTerminal - Predicate that returns true for events that close the stream.
+ * @param logger - Logger for diagnostic output.
+ * @returns A new {@link StreamRouter} instance.
+ */
+export declare const createStreamRouter: <TEvent>(isTerminal: (event: TEvent) => boolean, logger: Logger) => StreamRouter<TEvent>;

package/dist/core/transport/turn-manager.d.ts

@@ -0,0 +1,34 @@
+import { Logger } from '../../logger.js';
+import { TurnEndReason } from './types.js';
+/**
+ * Server-side turn state management and lifecycle event publishing.
+ *
+ * Owns the authoritative turn lifecycle. Tracks active turns with their
+ * AbortControllers and clientIds. Publishes turn-start and turn-end events
+ * on the Ably channel so all clients can react to turn state changes.
+ */
+import type * as Ably from 'ably';
+/** Manages active turns and publishes turn lifecycle events on the channel. */
+export interface TurnManager {
+    /** Register a new turn. Publishes turn-start on the channel. Returns AbortSignal. */
+    startTurn(turnId: string, clientId?: string, controller?: AbortController): Promise<AbortSignal>;
+    /** End a turn. Publishes turn-end on the channel. Cleans up internal state. */
+    endTurn(turnId: string, reason: TurnEndReason): Promise<void>;
+    /** Get the AbortSignal for a turn. */
+    getSignal(turnId: string): AbortSignal | undefined;
+    /** Get the clientId that owns a turn. */
+    getClientId(turnId: string): string | undefined;
+    /** Abort the signal for a turn. */
+    abort(turnId: string): void;
+    /** Get all active turn IDs. */
+    getActiveTurnIds(): string[];
+    /** Abort all active turns and clear state. */
+    close(): void;
+}
+/**
+ * Create a turn manager bound to the given channel.
+ * @param channel - The Ably channel to publish lifecycle events on.
+ * @param logger - Optional logger for diagnostic output.
+ * @returns A new {@link TurnManager} instance.
+ */
+export declare const createTurnManager: (channel: Ably.RealtimeChannel, logger?: Logger) => TurnManager;