@ably/ai-transport 0.0.1 → 0.1.0

package/dist/constants.d.ts

@@ -14,6 +14,8 @@ export declare const HEADER_STREAM = "x-ably-stream";
 export declare const HEADER_STATUS = "x-ably-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";
+/** 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";
 /** Header: message identity. Assigned per message (user or assistant). Used for optimistic reconciliation on the client. */
@@ -22,6 +24,8 @@ export declare const HEADER_MSG_ID = "x-ably-msg-id";
 export declare const HEADER_TURN_CLIENT_ID = "x-ably-turn-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. */

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

@@ -150,6 +150,19 @@ export interface MessageAccumulator<TEvent, TMessage> {
     processOutputs(outputs: DecoderOutput<TEvent, TMessage>[]): void;
     /** Apply an external update to a message (e.g. from an update callback). */
     updateMessage(message: TMessage): void;
+    /**
+     * Ensure the accumulator is ready to process events for the given message.
+     * If not already active, creates internal tracking state from the message.
+     * If already active, syncs internal state with the provided message
+     * (picking up external changes like cross-turn amendments).
+     * Idempotent — safe to call before every processOutputs.
+     */
+    initMessage(messageId: string, message: TMessage): void;
+    /**
+     * Mark a message as completed. Removes it from active tracking so it
+     * appears in {@link completedMessages}. No-op if not active.
+     */
+    completeMessage(messageId: string): void;
     /** All messages accumulated so far (in-progress and completed). */
     readonly messages: TMessage[];
     /** Only messages whose streams have finished. */
@@ -165,6 +178,12 @@ export interface EncoderOptions {
     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;
+    /**
+     * Domain-level message identity. Domain encoders use this as a fallback
+     * messageId when a lifecycle chunk (e.g. `start`) does not provide one,
+     * ensuring useChat and the transport accumulator assign the same ID.
+     */
+    messageId?: string;
 }
 /**
  * The complete codec contract that a core transport needs.
@@ -183,6 +202,4 @@ export interface Codec<TEvent, TMessage> {
     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/decode-history.d.ts

@@ -1,9 +1,9 @@
 import { Logger } from '../../logger.js';
 import { Codec } from '../codec/types.js';
-import { LoadHistoryOptions, PaginatedMessages } from './types.js';
+import { HistoryPage, LoadHistoryOptions } from './types.js';
 /**
  * decodeHistory — load conversation history from an Ably channel and
- * return decoded messages as a PaginatedMessages result.
+ * return decoded messages as a paginated HistoryPage result.
  *
  * Uses a fresh decoder (not shared with the live subscription) to avoid
  * state conflicts. Per-turn accumulators handle interleaved turns correctly.
@@ -19,8 +19,10 @@ import { LoadHistoryOptions, PaginatedMessages } from './types.js';
  *
  * 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.
+ * oldest to newest at the point a result is built. This handles turns
+ * that span page boundaries correctly. The fetch loop uses a cheap
+ * header-based completion counter to decide when to stop paging, so the
+ * full decode runs exactly once per traversal regardless of page count.
  */
 import type * as Ably from 'ably';
 /**
@@ -36,6 +38,6 @@ import type * as Ably from 'ably';
  * @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.
+ * @returns The first page of decoded history.
  */
-export declare const decodeHistory: <TEvent, TMessage>(channel: Ably.RealtimeChannel, codec: Codec<TEvent, TMessage>, options: LoadHistoryOptions | undefined, logger: Logger) => Promise<PaginatedMessages<TMessage>>;
+export declare const decodeHistory: <TEvent, TMessage>(channel: Ably.RealtimeChannel, codec: Codec<TEvent, TMessage>, options: LoadHistoryOptions | undefined, logger: Logger) => Promise<HistoryPage<TMessage>>;

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

@@ -12,8 +12,9 @@
  * @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.parent - Preceding message's msg-id (for branching).
  * @param opts.forkOf - Forked message's msg-id (for edit/regen).
+ * @param opts.amend - The msg-id of the existing message this message targets (cross-turn events).
  * @returns A headers record with the `x-ably-*` transport headers set.
  */
 export declare const buildTransportHeaders: (opts: {
@@ -21,6 +22,7 @@ export declare const buildTransportHeaders: (opts: {
     turnId: string;
     msgId: string;
     turnClientId?: string;
-    parent?: string | null;
+    parent?: string;
     forkOf?: string;
+    amend?: string;
 }) => Record<string, string>;

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

@@ -1,4 +1,7 @@
-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 type { ActiveTurn, AddMessageOptions, AddMessagesResult, CancelFilter, CancelRequest, ClientTransport, ClientTransportOptions, CloseOptions, EventsNode, MessageNode, NewTurnOptions, SendOptions, ServerTransport, ServerTransportOptions, StreamResponseOptions, StreamResult, Tree, Turn, TurnEndReason, TurnLifecycleEvent, View, } from './types.js';
+export type { EventNode } from './types.js';
+export type { TreeNode } from './types.js';
+export type { TreeInternal } from './tree.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

@@ -1,5 +1,5 @@
 import { Logger } from '../../logger.js';
-import { StreamEncoder } from '../codec/types.js';
+import { StreamEncoder, WriteOptions } from '../codec/types.js';
 import { StreamResult } from './types.js';
 /**
  * Pipe an event stream through an encoder to the channel.
@@ -10,7 +10,8 @@ import { StreamResult } from './types.js';
  * @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 resolveWriteOptions - Optional per-event hook returning {@link WriteOptions} overrides to pass to `encoder.appendEvent`.
  * @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>;
+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>, resolveWriteOptions?: (event: TEvent) => WriteOptions | undefined, logger?: Logger) => Promise<StreamResult>;

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

@@ -1,10 +1,20 @@
 import { Logger } from '../../logger.js';
+/**
+ * Client-side stream routing.
+ *
+ * Maintains a map of turnId to ReadableStreamController. Routes decoded events
+ * to the correct stream. Closes streams on terminal events, explicit close, or
+ * error.
+ */
+import * as Ably from 'ably';
 /** 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. */
+    /** Close the stream for a turnId. Returns true if a stream existed. */
     closeStream(turnId: string): boolean;
+    /** Error the stream for a turnId. The consumer's reader will reject with the given error. Returns true if a stream existed. */
+    errorStream(turnId: string, error: Ably.ErrorInfo): 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. */

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

@@ -0,0 +1,171 @@
+import { Logger } from '../../logger.js';
+import { MessageNode, Tree, TurnLifecycleEvent } from './types.js';
+/**
+ * Tree — materializes a branching conversation from a flat
+ * oplog of Ably messages using serial-first ordering.
+ *
+ * Serial order (the total order assigned by Ably) is the primary mechanism
+ * for linear message sequences. `x-ably-parent` and `x-ably-fork-of` headers
+ * are only structurally meaningful at branch points — where the user is
+ * interacting with a visible message and the client always has it loaded.
+ *
+ * `upsert()` is the sole mutation method. Messages can arrive in any order
+ * (live subscription, history pages, seed data) and the tree produces the
+ * correct `flattenNodes()` output once all messages are present.
+ *
+ * The tree owns conversation state. `flattenNodes()` returns the linear node
+ * list for the currently selected branches — this is what the transport's
+ * `getMessages()` delegates to.
+ */
+import type * as Ably from 'ably';
+/** Internal tree surface used by View — not part of the public Tree API. */
+export interface TreeInternal<TMessage> extends Tree<TMessage> {
+    /**
+     * Monotonic counter that increments on structural changes (node insert,
+     * delete, serial promotion/reorder) but NOT on content-only updates
+     * (existing node's message replaced). Allows the View to skip full
+     * tree walks when only message content changed.
+     */
+    readonly structuralVersion: number;
+    /**
+     * Flatten the tree along selected branches into a linear node list.
+     * The `selections` map provides the selected sibling's msgId at each
+     * fork point, keyed by group root msgId. Fork points not present in
+     * the map default to the latest sibling. If a selectedMsgId is not
+     * found in the sibling group (stale/deleted), falls back to latest.
+     */
+    flattenNodes(selections: Map<string, string>): MessageNode<TMessage>[];
+    /**
+     * Get the "group root" msgId for a sibling group — the original message
+     * that all forks in the group trace back to.
+     */
+    getGroupRoot(msgId: string): string;
+    /**
+     * Get the sibling group that `msgId` belongs to, as full MessageNode objects.
+     * Allows callers to resolve index ↔ msgId without losing identity.
+     */
+    getSiblingNodes(msgId: string): MessageNode<TMessage>[];
+    /** Forward a raw Ably message event to tree subscribers. */
+    emitAblyMessage(msg: Ably.InboundMessage): void;
+    /** Forward a turn lifecycle event to tree subscribers. */
+    emitTurn(event: TurnLifecycleEvent): void;
+    /** Register an active turn. */
+    trackTurn(turnId: string, clientId: string): void;
+    /** Unregister an active turn. */
+    untrackTurn(turnId: string): void;
+}
+export declare class DefaultTree<TMessage> implements TreeInternal<TMessage> {
+    /** All nodes indexed by msgId (x-ably-msg-id). */
+    private readonly _nodeIndex;
+    /**
+     * All nodes sorted by serial (lexicographic). Null-serial messages
+     * (optimistic inserts, seed data) sort after all serial-bearing messages,
+     * ordered among themselves by insertion sequence.
+     */
+    private readonly _sortedList;
+    /**
+     * Parent index: parentId to set of child msgIds.
+     * Nodes with no parent are indexed under the key `null`.
+     */
+    private readonly _parentIndex;
+    private readonly _emitter;
+    private readonly _logger;
+    /** Active turns: turnId → clientId. */
+    private readonly _turnClientIds;
+    /** Monotonically increasing counter for insertion sequence. */
+    private _seqCounter;
+    /** Incremented on structural changes; unchanged on content-only updates. */
+    private _structuralVersion;
+    get structuralVersion(): number;
+    constructor(logger: Logger);
+    /**
+     * Compare two nodes for sorted list ordering.
+     * Serial-bearing nodes sort by serial (lexicographic).
+     * Null-serial nodes sort after all serial-bearing nodes.
+     * Among null-serial nodes, sort by insertion sequence.
+     * @param a - First node to compare.
+     * @param b - Second node to compare.
+     * @returns Negative if a sorts before b, positive if after, zero if equal.
+     */
+    private _compareNodes;
+    /**
+     * Insert a node into sortedList at the correct position via binary search.
+     * @param internal - The node to insert.
+     */
+    private _insertSorted;
+    /**
+     * Remove a node from sortedList.
+     * @param internal - The node to remove.
+     */
+    private _removeSorted;
+    private _addToParentIndex;
+    private _removeFromParentIndex;
+    /**
+     * Get the sibling group that `msgId` belongs to.
+     *
+     * A sibling group is: the original message + all messages whose `forkOf`
+     * points to the original (or transitively to a sibling). We find the
+     * group root by following `forkOf` chains to the earliest ancestor that
+     * has no `forkOf` (or whose `forkOf` target doesn't share the same parent).
+     * @param msgId - The msg-id to look up the sibling group for.
+     * @returns The ordered list of sibling nodes.
+     */
+    private _getSiblingGroup;
+    /**
+     * Check if `node` belongs to the sibling group rooted at `originalId`.
+     * A node is a sibling if it IS the original or its forkOf chain leads
+     * to the original (with the same parentId).
+     * @param node - The node to check.
+     * @param originalId - The group root to match against.
+     * @returns True if the node belongs to the sibling group.
+     */
+    private _isSiblingOf;
+    /**
+     * Get the "group root" msgId for a sibling group — the original message
+     * that all forks trace back to.
+     * @param msgId - Any msg-id in the sibling group.
+     * @returns The msg-id of the group root.
+     */
+    getGroupRoot(msgId: string): string;
+    flattenNodes(selections: Map<string, string>): MessageNode<TMessage>[];
+    getSiblings(msgId: string): TMessage[];
+    getSiblingNodes(msgId: string): MessageNode<TMessage>[];
+    hasSiblings(msgId: string): boolean;
+    getNode(msgId: string): MessageNode<TMessage> | undefined;
+    getHeaders(msgId: string): Record<string, string> | undefined;
+    upsert(msgId: string, message: TMessage, headers: Record<string, string>, serial?: string): void;
+    delete(msgId: string): void;
+    getActiveTurnIds(): Map<string, Set<string>>;
+    on(event: 'update', handler: () => void): () => void;
+    on(event: 'ably-message', handler: (msg: Ably.InboundMessage) => void): () => void;
+    on(event: 'turn', handler: (event: TurnLifecycleEvent) => void): () => void;
+    /**
+     * Forward a raw Ably message event to tree subscribers.
+     * @param msg - The raw Ably message to emit.
+     */
+    emitAblyMessage(msg: Ably.InboundMessage): void;
+    /**
+     * Forward a turn lifecycle event to tree subscribers.
+     * @param event - The turn lifecycle event to emit.
+     */
+    emitTurn(event: TurnLifecycleEvent): void;
+    /**
+     * Register an active turn.
+     * @param turnId - The turn's unique identifier.
+     * @param clientId - The client that owns the turn.
+     */
+    trackTurn(turnId: string, clientId: string): void;
+    /**
+     * Unregister an active turn.
+     * @param turnId - The turn to untrack.
+     */
+    untrackTurn(turnId: string): void;
+}
+/**
+ * Create a Tree that materializes branching history from a flat oplog.
+ * @param logger - Logger for diagnostic output.
+ * @returns A new {@link DefaultTree} instance. The transport uses DefaultTree
+ *   directly for internal methods (emitAblyMessage, emitTurn, trackTurn, untrackTurn).
+ *   Public consumers see the narrower {@link Tree} interface.
+ */
+export declare const createTree: <TMessage>(logger: Logger) => DefaultTree<TMessage>;

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

@@ -11,7 +11,10 @@ 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>;
+    startTurn(turnId: string, clientId?: string, controller?: AbortController, metadata?: {
+        parent?: string;
+        forkOf?: string;
+    }): 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. */