@ably/ai-transport 0.0.1 → 0.1.0

package/src/core/transport/types.ts

@@ -8,7 +8,7 @@
 import type * as Ably from 'ably';
 
 import type { Logger } from '../../logger.js';
-import type { Codec } from '../codec/types.js';
+import type { Codec, WriteOptions } from '../codec/types.js';
 
 // ---------------------------------------------------------------------------
 // Shared types
@@ -45,18 +45,6 @@ export interface CancelRequest {
   turnOwners: Map<string, string>;
 }
 
-// ---------------------------------------------------------------------------
-// Message with headers
-// ---------------------------------------------------------------------------
-
-/** A domain message paired with its Ably transport headers. Used on the read path to snapshot conversation state (e.g. for HTTP POST bodies). */
-export interface MessageWithHeaders<TMessage> {
-  /** The domain message. */
-  message: TMessage;
-  /** Ably headers associated with this message (transport metadata, domain headers). */
-  headers?: Record<string, string>;
-}
-
 // ---------------------------------------------------------------------------
 // Server transport options
 // ---------------------------------------------------------------------------
@@ -71,7 +59,9 @@ export interface ServerTransportOptions<TEvent, TMessage> {
   logger?: Logger;
   /**
    * Called with non-fatal transport-level errors not scoped to any turn.
-   * Examples: cancel listener subscription failure, channel attach errors.
+   * Examples: cancel listener subscription failure, channel attach errors,
+   * channel continuity loss (FAILED/SUSPENDED/DETACHED or re-attach with
+   * `resumed: false`).
    */
   onError?: (error: Ably.ErrorInfo) => void;
 }
@@ -80,14 +70,10 @@ export interface ServerTransportOptions<TEvent, TMessage> {
 // Turn options
 // ---------------------------------------------------------------------------
 
-/** Options for addMessages — per-operation overrides for message identity and branching. */
+/** Options for addMessages — per-operation overrides for attribution. */
 export interface AddMessageOptions {
   /** The user's clientId for attribution. */
   clientId?: string;
-  /** The msg-id of the immediately preceding message in this branch. */
-  parent?: string | null;
-  /** The msg-id of the message this one replaces (creates a fork). */
-  forkOf?: string;
 }
 
 /** Result of publishing user messages via addMessages. */
@@ -96,18 +82,63 @@ export interface AddMessagesResult {
   msgIds: string[];
 }
 
-/** Options for streamResponse — per-operation overrides for the assistant message. */
-export interface StreamResponseOptions {
+/**
+ * A batch of events targeting an existing message.
+ * Each node specifies the target message and the events to apply to it.
+ * Used for cross-turn updates such as tool result delivery.
+ */
+export interface EventsNode<TEvent> {
+  /** Discriminator — identifies this as an events node. */
+  kind: 'event';
+  /** The `x-ably-msg-id` of the existing message to update. */
+  msgId: string;
+  /** Events to apply to the target message. */
+  events: TEvent[];
+}
+
+/** @deprecated Use {@link EventsNode} instead. */
+export type EventNode<TEvent> = EventsNode<TEvent>;
+
+/**
+ * Options for streamResponse — per-operation overrides for the assistant message.
+ * @template TEvent - The codec event type carried by the stream; used by the `resolveWriteOptions` hook.
+ */
+export interface StreamResponseOptions<TEvent> {
   /** The msg-id of the immediately preceding message in this branch. */
-  parent?: string | null;
+  parent?: string;
   /** The msg-id of the message this response replaces (for regeneration). */
   forkOf?: string;
+  /**
+   * Optional per-event hook invoked before each event is encoded. The
+   * returned {@link WriteOptions} (if any) override the stream's default
+   * headers and `msgId` for that one encode call only; return `undefined`
+   * to use the stream defaults.
+   *
+   * Used to carry a subset of events within the stream to a different
+   * message (e.g. `tool-output-available` chunks that belong on a prior
+   * assistant message, stamped with `x-ably-amend`). Must not be used
+   * for events that participate in the encoder's stream-append pipeline
+   * — streaming state (stream tracker, append ordering) is anchored to
+   * the stream's default identity and is not affected by per-event
+   * overrides.
+   * @param event - The event about to be encoded.
+   * @returns Per-write overrides for this event, or undefined.
+   */
+  resolveWriteOptions?: (event: TEvent) => WriteOptions | undefined;
 }
 
 /** The result of streaming a response through the encoder. */
 export interface StreamResult {
   /** Why the stream ended. */
   reason: TurnEndReason;
+  /**
+   * The error that caused the stream to fail, present when `reason` is
+   * `'error'`. This is the original error (e.g. from the LLM provider)
+   * preserved so the caller can inspect provider-specific fields. The
+   * turn's `onError` callback also fires with a wrapped `Ably.ErrorInfo`
+   * (code `StreamError`) for standardized observability.
+   */
+  error?: Error;
 }
 
 /** Options passed to newTurn for configuring the turn lifecycle. */
@@ -123,7 +154,7 @@ export interface NewTurnOptions<TEvent> {
    * Used as the default parent for user messages (via addMessages) and
    * assistant messages (via streamResponse) when not overridden per-operation.
    */
-  parent?: string | null;
+  parent?: string;
 
   /**
    * The msg-id of the message this turn replaces (creates a fork).
@@ -153,10 +184,33 @@ export interface NewTurnOptions<TEvent> {
   onCancel?: (request: CancelRequest) => Promise<boolean>;
 
   /**
-   * Called with non-fatal errors scoped to this turn. Examples: turn-start
-   * publish failure, encoder recovery failure, stream encoding errors.
+   * Called with non-fatal turn-scoped errors that have no other delivery
+   * path. Fires in two scenarios:
+   * - Stream failures in `streamResponse` — the underlying error is also
+   *   returned on `StreamResult.error`, but this callback delivers it
+   *   wrapped as an `Ably.ErrorInfo` (code `StreamError`) for standardized
+   *   observability.
+   * - Failures in the `onCancel` handler.
+   *
+   * Publish failures in `start`, `addMessages`, `addEvents`, and `end`
+   * are not delivered here — those methods reject their returned promise
+   * with an `Ably.ErrorInfo`, and the caller should handle it at the await
+   * site. Turn errors never render the transport unusable, but the turn
+   * may be in an inconsistent state; the caller should typically `end` it
+   * with reason `'error'`.
+   *
+   * Channel-wide events (e.g. continuity loss) are delivered via the
+   * transport-level `onError` on {@link ServerTransportOptions}, not here.
    */
   onError?: (error: Ably.ErrorInfo) => void;
+
+  /**
+   * An external abort signal (typically the HTTP request's `req.signal`) that,
+   * when fired, aborts this turn. This allows platform-level cancellation —
+   * request cancellation, serverless function timeout — to stop LLM generation
+   * and stream piping gracefully.
+   */
+  signal?: AbortSignal;
 }
 
 // ---------------------------------------------------------------------------
@@ -176,19 +230,31 @@ export interface Turn<TEvent, TMessage> {
 
   /**
    * Publish user messages to the channel, scoped to this turn.
-   * Each message is published with its own headers (including `x-ably-msg-id`
-   * for optimistic reconciliation with the client's inserts). Per-message
-   * headers from `MessageWithHeaders` override transport-generated defaults.
+   * Each node's `msgId`, `parentId`, and `forkOf` are used for message identity
+   * and branching. The node's `headers` override transport-generated defaults
+   * (e.g. for optimistic reconciliation with the client's inserts).
    * @returns The msg-ids of all published messages, in order.
    */
-  addMessages(messages: MessageWithHeaders<TMessage>[], options?: AddMessageOptions): Promise<AddMessagesResult>;
+  addMessages(messages: MessageNode<TMessage>[], options?: AddMessageOptions): Promise<AddMessagesResult>;
 
   /**
    * Pipe a ReadableStream through the encoder to the channel.
    * Returns when the stream completes, is cancelled, or errors.
    * Does NOT call end() — the caller must call end() after streamResponse returns.
    */
-  streamResponse(stream: ReadableStream<TEvent>, options?: StreamResponseOptions): Promise<StreamResult>;
+  streamResponse(stream: ReadableStream<TEvent>, options?: StreamResponseOptions<TEvent>): Promise<StreamResult>;
+
+  /**
+   * Publish events targeting existing messages in the tree. Each node
+   * specifies a target message (by `msgId`) and the events to apply.
+   * Events are encoded and published with the target's `x-ably-msg-id`,
+   * so receiving clients apply them to the existing node rather than
+   * creating a new one.
+   *
+   * Used for cross-turn updates such as tool result delivery after
+   * approval or client-side tool execution.
+   */
+  addEvents(nodes: EventsNode<TEvent>[]): Promise<void>;
 
   /** Publish turn-end event to the channel and clean up. */
   end(reason: TurnEndReason): Promise<void>;
@@ -226,8 +292,8 @@ export interface ClientTransportOptions<TEvent, TMessage> {
   /** The client's identity. Sent to the server in the POST body. */
   clientId?: string;
 
-  /** Server endpoint URL for the HTTP POST. Defaults to `"/api/chat"`. */
-  api?: string;
+  /** Server endpoint URL for the HTTP POST. */
+  api: string;
 
   /** Headers for the HTTP POST. Function form for dynamic values (e.g. auth tokens). */
   headers?: Record<string, string> | (() => Record<string, string>);
@@ -266,10 +332,10 @@ export interface SendOptions {
   forkOf?: string;
   /**
    * The msg-id of the message that precedes this one in the
-   * conversation thread. Null means the message is a root.
-   * If omitted, auto-computed from the last message in the tree.
+   * conversation thread. If omitted, auto-computed from the last
+   * message in the view.
    */
-  parent?: string | null;
+  parent?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -278,7 +344,15 @@ export interface SendOptions {
 
 /** A structured event describing a turn starting or ending. */
 export type TurnLifecycleEvent =
-  | { type: 'x-ably-turn-start'; turnId: string; clientId: string }
+  | {
+      type: 'x-ably-turn-start';
+      turnId: string;
+      clientId: string;
+      /** The msg-id of the parent message, if known. Omitted for root turns. */
+      parent?: string;
+      /** The msg-id being forked/replaced, if this is a regeneration or edit. */
+      forkOf?: string;
+    }
   | { type: 'x-ably-turn-end'; turnId: string; clientId: string; reason: TurnEndReason };
 
 // ---------------------------------------------------------------------------
@@ -287,12 +361,18 @@ export type TurnLifecycleEvent =
 
 /** A handle to an active client-side turn, returned by `send()`, `regenerate()`, and `edit()`. */
 export interface ActiveTurn<TEvent> {
-  /** The decoded event stream for this turn. */
+  /** The decoded event stream for this turn. May error if the delivery guarantee is broken (e.g. POST failure, channel continuity loss). */
   stream: ReadableStream<TEvent>;
   /** The turn's unique identifier. */
   turnId: string;
   /** Cancel this specific turn. Publishes a cancel message and closes the local stream. */
   cancel(): Promise<void>;
+  /**
+   * The msg-ids of optimistically inserted user messages, in order.
+   * Present when the send included user messages (edit); empty for
+   * regeneration (no user messages to insert optimistically).
+   */
+  optimisticMsgIds: string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -309,20 +389,26 @@ export interface CloseOptions {
 // History / pagination
 // ---------------------------------------------------------------------------
 
-/** A page of decoded messages from channel history. */
-export interface PaginatedMessages<TMessage> {
-  /** Decoded messages in chronological order (oldest first). */
-  items: TMessage[];
-  /** Headers for each item, parallel to `items`. Used by the transport to populate the tree. */
-  itemHeaders?: Record<string, string>[];
-  /** Ably serial for each item, parallel to `items`. Used by the transport for tree ordering. */
-  itemSerials?: string[];
+/** A single decoded history item with its transport metadata. */
+export interface HistoryItem<TMessage> {
+  /** The decoded domain message. */
+  message: TMessage;
+  /** Transport headers for tree identity and ordering. */
+  headers: Record<string, string>;
+  /** Ably serial for tree ordering. */
+  serial: string;
+}
+
+/** A page of decoded history from the channel. Internal to View/decodeHistory. */
+export interface HistoryPage<TMessage> {
+  /** Decoded items in chronological order (oldest first). */
+  items: HistoryItem<TMessage>[];
   /** Raw Ably messages that produced this page, in chronological order. */
-  rawMessages?: Ably.InboundMessage[];
+  rawMessages: Ably.InboundMessage[];
   /** Whether there are older pages available. */
   hasNext(): boolean;
   /** Fetch the next (older) page. Returns undefined if no more pages. */
-  next(): Promise<PaginatedMessages<TMessage> | undefined>;
+  next(): Promise<HistoryPage<TMessage> | undefined>;
 }
 
 /** Options for loading channel history. */
@@ -336,7 +422,9 @@ export interface LoadHistoryOptions {
 // ---------------------------------------------------------------------------
 
 /** A node in the conversation tree, representing a single domain message. */
-export interface ConversationNode<TMessage> {
+export interface MessageNode<TMessage> {
+  /** Discriminator — identifies this as a message node. */
+  kind: 'message';
   /** The domain message. */
   message: TMessage;
   /** The x-ably-msg-id of this node — primary key in the tree. */
@@ -355,20 +443,17 @@ export interface ConversationNode<TMessage> {
   serial: string | undefined;
 }
 
+/** @deprecated Use {@link MessageNode} instead. */
+export type TreeNode<TMessage> = MessageNode<TMessage>;
+
 /**
  * Materializes a branching conversation tree from a flat oplog.
  *
- * Owns the conversation state — `flatten()` returns the linear message list
- * for the currently selected branches. The transport's `getMessages()` delegates
- * to `flatten()`.
+ * Owns the complete conversation state — every node from live messages and
+ * history. `flattenNodes()` returns the linear message list for the currently
+ * selected branches. Events fire for any change across the full tree.
  */
-export interface ConversationTree<TMessage> {
-  /**
-   * Flatten the tree along the currently selected branches into
-   * a linear message list. This is what getMessages() returns.
-   */
-  flatten(): TMessage[];
-
+export interface Tree<TMessage> {
   /**
    * Get all messages that are siblings (alternatives) at a given
    * fork point. Returns an array ordered chronologically by serial.
@@ -379,24 +464,8 @@ export interface ConversationTree<TMessage> {
   /** Whether a message has sibling alternatives (i.e., show navigation arrows). */
   hasSiblings(msgId: string): boolean;
 
-  /** Get the index of the currently selected sibling at a fork point. */
-  getSelectedIndex(msgId: string): number;
-
-  /**
-   * Select a sibling at a fork point by index. Updates the active branch.
-   * Calling flatten() after this returns the new linear thread.
-   * Index is clamped to `[0, siblings.length - 1]`.
-   */
-  select(msgId: string, index: number): void;
-
   /** Get a node by msgId, or undefined if not found. */
-  getNode(msgId: string): ConversationNode<TMessage> | undefined;
-
-  /**
-   * Get a node by codec message key (e.g. UIMessage.id), or undefined if
-   * not found. Uses a secondary index since the tree is keyed by x-ably-msg-id.
-   */
-  getNodeByKey(key: string): ConversationNode<TMessage> | undefined;
+  getNode(msgId: string): MessageNode<TMessage> | undefined;
 
   /** Get the stored headers for a node by msgId, or undefined if not found. */
   getHeaders(msgId: string): Record<string, string> | undefined;
@@ -413,114 +482,224 @@ export interface ConversationTree<TMessage> {
 
   /** Remove a message from the tree. */
   delete(msgId: string): void;
-}
 
-// ---------------------------------------------------------------------------
-// Internal sub-component types
-// ---------------------------------------------------------------------------
+  // --- Events ---
 
-/** Entry in the StreamRouter's turn map. Not part of the public API. */
-export interface TurnEntry<TEvent> {
-  /** The ReadableStream controller for this turn. */
-  controller: ReadableStreamDefaultController<TEvent>;
-  /** The turn's unique identifier. */
-  turnId: string;
+  /** Active turn IDs grouped by clientId (all turns, not just visible). */
+  getActiveTurnIds(): Map<string, Set<string>>;
+
+  /** Subscribe to tree structure changes (insert, update, delete). */
+  on(event: 'update', handler: () => void): () => void;
+
+  /** Subscribe to raw Ably messages arriving on the channel. */
+  on(event: 'ably-message', handler: (msg: Ably.InboundMessage) => void): () => void;
+
+  /** Subscribe to turn lifecycle events (start and end). */
+  on(event: 'turn', handler: (event: TurnLifecycleEvent) => void): () => void;
 }
 
 // ---------------------------------------------------------------------------
-// Client transport interface
+// View — windowed projection over the tree
 // ---------------------------------------------------------------------------
 
-/** Client-side transport that manages conversation state over an Ably channel. */
-export interface ClientTransport<TEvent, TMessage> {
+/**
+ * A paginated, branch-aware projection of the conversation tree.
+ *
+ * Returns only the visible portion of the selected branch. New live messages
+ * appear immediately; older messages are revealed progressively via
+ * `loadOlder()`. Events are scoped to the visible window — subscribers
+ * are only notified when the visible output changes.
+ */
+export interface View<TEvent, TMessage> {
+  /** The visible domain messages along the selected branch. Shorthand for `flattenNodes().map(n => n.message)`. */
+  getMessages(): TMessage[];
+
+  /** Visible nodes along the selected branch, filtered by the pagination window. */
+  flattenNodes(): MessageNode<TMessage>[];
+
+  /** Whether there are older messages that can be loaded or revealed. */
+  hasOlder(): boolean;
+
   /**
-   * Send one or more messages and start a new turn. Returns a handle to the
-   * active turn with the decoded event stream and a cancel function.
-   *
+   * Reveal older messages. Loads from channel history if the tree doesn't
+   * have enough, then advances the window to show up to `limit` more messages.
+   * Emits 'update' when the visible list changes.
+   * @param limit - Maximum number of older messages to reveal. Defaults to 100.
+   */
+  loadOlder(limit?: number): Promise<void>;
+
+  // --- Branch navigation ---
+
+  /**
+   * Select a sibling at a fork point by index. Updates this view's
+   * branch selection. Index is clamped to `[0, siblings.length - 1]`.
+   * Emits 'update' when the visible output changes.
+   */
+  select(msgId: string, index: number): void;
+
+  /** Get the index of the currently selected sibling at a fork point. */
+  getSelectedIndex(msgId: string): number;
+
+  /**
+   * Get all messages that are siblings (alternatives) at a given
+   * fork point. Returns an array ordered chronologically by serial.
+   */
+  getSiblings(msgId: string): TMessage[];
+
+  /** Whether a message has sibling alternatives (i.e., show navigation arrows). */
+  hasSiblings(msgId: string): boolean;
+
+  /** Get a node by msgId, or undefined if not found. */
+  getNode(msgId: string): MessageNode<TMessage> | undefined;
+
+  // --- Write operations ---
+
+  /**
+   * Send one or more messages and start a new turn. The parent is
+   * auto-computed from this view's selected branch unless overridden.
    * The HTTP POST is fire-and-forget — the returned stream is available
-   * immediately. If the POST fails, the error is surfaced via `on("error")`.
+   * immediately. If the POST fails, the error is surfaced via the
+   * transport's `on("error")` and the stream is errored.
    */
   send(messages: TMessage | TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>>;
 
   /**
    * Regenerate an assistant message. Creates a new turn that forks the
    * target message with no new user messages. Automatically computes
-   * `forkOf`, `parent`, and truncated `history` from the tree.
-   *
-   * Pass `options.body.history` to override the default truncated history.
+   * `forkOf`, `parent`, and truncated `history` from this view's branch.
    */
   regenerate(messageId: string, options?: SendOptions): Promise<ActiveTurn<TEvent>>;
 
   /**
    * Edit a user message. Creates a new turn that forks the target message
    * with replacement content. Automatically computes `forkOf`, `parent`,
-   * and `history` from the tree.
+   * and `history` from this view's branch.
    */
   edit(messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>>;
 
   /**
-   * Access the conversation tree for branch navigation.
-   * The tree is updated in real-time by the transport's channel subscription.
+   * Update an existing message and start a continuation turn.
+   * The local tree is updated optimistically, then the events are sent
+   * to the server in the POST body. The server publishes them to the channel
+   * and streams a continuation response.
+   * @param msgId - The `x-ably-msg-id` of the existing message to amend.
+   * @param events - Events to apply to the target message (e.g. tool output).
+   * @param options - Optional send options (body, headers).
+   * @returns An active turn with the continuation response stream.
    */
-  getTree(): ConversationTree<TMessage>;
+  update(msgId: string, events: TEvent[], options?: SendOptions): Promise<ActiveTurn<TEvent>>;
 
-  /** Cancel turns matching the filter. Defaults to `{ own: true }` (all own turns). */
-  cancel(filter?: CancelFilter): Promise<void>;
+  // --- Observation ---
 
-  /**
-   * Returns a promise that resolves when all active turns matching the filter
-   * have completed. Resolves immediately if no matching turns are active.
-   * Defaults to `{ own: true }`.
-   */
-  waitForTurn(filter?: CancelFilter): Promise<void>;
+  /** Active turn IDs for turns with visible messages, grouped by clientId. */
+  getActiveTurnIds(): Map<string, Set<string>>;
 
-  /**
-   * Subscribe to message store changes or raw Ably message additions.
-   * The handler is called with no arguments — call `getMessages()` or
-   * `getAblyMessages()` for the current state. Returns an unsubscribe function.
-   */
-  on(event: 'message' | 'ably-message', handler: () => void): () => void;
+  /** The visible message list changed (new visible node, branch switch, window shift). */
+  on(event: 'update', handler: () => void): () => void;
 
-  /** Subscribe to turn lifecycle events (start, end). Returns an unsubscribe function. */
+  /** A raw Ably message arrived that corresponds to a visible node. */
+  on(event: 'ably-message', handler: (msg: Ably.InboundMessage) => void): () => void;
+
+  /** A turn event occurred for a turn with visible messages in the window. */
   on(event: 'turn', handler: (event: TurnLifecycleEvent) => void): () => void;
 
-  /**
-   * Subscribe to non-fatal transport errors. These indicate something went
-   * wrong but the transport is still operational. Returns an unsubscribe function.
-   */
-  on(event: 'error', handler: (error: Ably.ErrorInfo) => void): () => void;
+  /** Tear down the view — unsubscribe from tree events and clear internal state. */
+  close(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Internal sub-component types
+// ---------------------------------------------------------------------------
+
+/** Entry in the StreamRouter's turn map. Not part of the public API. */
+export interface TurnEntry<TEvent> {
+  /** The ReadableStream controller for this turn. */
+  controller: ReadableStreamDefaultController<TEvent>;
+  /** The turn's unique identifier. */
+  turnId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Client transport interface
+// ---------------------------------------------------------------------------
+
+/** Client-side transport that manages conversation state over an Ably channel. */
+export interface ClientTransport<TEvent, TMessage> {
+  /** The complete conversation tree — all known nodes, events for any change. */
+  readonly tree: Tree<TMessage>;
+
+  /** The default paginated, branch-aware view for rendering — events scoped to visible messages. */
+  readonly view: View<TEvent, TMessage>;
 
   /**
-   * Get the accumulated raw Ably messages, in chronological order.
-   * Includes both live messages and history-loaded messages.
+   * Create an additional view over the same conversation tree.
+   * Each view has independent branch selections and pagination state.
+   * The caller is responsible for calling `close()` on the returned view
+   * when it is no longer needed, or it will be closed when the transport closes.
    */
-  getAblyMessages(): Ably.InboundMessage[];
+  createView(): View<TEvent, TMessage>;
 
-  /** Get all currently active turns, keyed by clientId. */
-  getActiveTurnIds(): Map<string, Set<string>>;
+  /** Cancel turns matching the filter. Defaults to `{ own: true }` (all own turns). */
+  cancel(filter?: CancelFilter): Promise<void>;
 
-  /** Get Ably headers associated with a message via the conversation tree. */
-  getMessageHeaders(message: TMessage): Record<string, string> | undefined;
+  /**
+   * Apply events to an existing tree message locally and queue them for
+   * delivery on the next send.
+   *
+   * Use for cross-turn updates where the event value is produced on the
+   * client (e.g. after `addToolResult` resolves a client-executed tool) and
+   * must appear in the tree immediately so downstream observers — such as a
+   * destructive `setMessages(...)` mirror — cannot wipe it before it lands
+   * on the wire.
+   *
+   * The events are applied to the tree via the codec's accumulator
+   * (tree `update` fires once with the merged message) and queued on the
+   * transport. The next send operation flushes the queue into the POST
+   * body's `events` field so the server can republish them over the channel.
+   *
+   * If `msgId` is not present in the tree, the call is a no-op and a
+   * warning is logged.
+   * @param msgId - The x-ably-msg-id of the existing message to amend.
+   * @param events - Events to apply and later ship.
+   */
+  stageEvents(msgId: string, events: TEvent[]): void;
 
-  /** Get the current message list (follows selected branches). Updated by message lifecycle events. */
-  getMessages(): TMessage[];
+  /**
+   * Replace the tree's copy of an existing message with a caller-provided
+   * version, preserving headers and serial.
+   *
+   * Use for useChat-style state transitions the codec can't express as
+   * chunks — the canonical example is `addToolApprovalResponse`, which
+   * sets `state: 'approval-responded'` on a `dynamic-tool` part directly
+   * on the UIMessage and has no corresponding chunk variant.
+   *
+   * Unlike {@link stageEvents}, staged messages are NOT queued for the
+   * next send: the tree is authoritative for the POST body's history,
+   * so updating it is sufficient.
+   *
+   * Runs synchronously. Subsequent tree observers (e.g. useMessageSync)
+   * see the patched state on the next tick, so an interleaved
+   * observer-turn sync can't clobber it back.
+   *
+   * If `msgId` is not present in the tree, the call is a no-op and a
+   * warning is logged.
+   * @param msgId - The x-ably-msg-id of the existing message to replace.
+   * @param message - The patched message to store.
+   */
+  stageMessage(msgId: string, message: TMessage): void;
 
   /**
-   * Snapshot the current message list as message + headers pairs.
-   * Convenience for building the `history` body field in HTTP POSTs.
+   * Returns a promise that resolves when all active turns matching the filter
+   * have completed. Resolves immediately if no matching turns are active.
+   * Defaults to `{ own: true }`.
    */
-  getMessagesWithHeaders(): MessageWithHeaders<TMessage>[];
+  waitForTurn(filter?: CancelFilter): Promise<void>;
 
   /**
-   * Load a page of conversation history from the channel, decoded through
-   * the transport's codec. Uses `untilAttach` for gapless continuity with
-   * the live subscription.
-   *
-   * History messages are inserted into the conversation tree and trigger
-   * a notification. Returns a PaginatedMessages handle — call `next()`
-   * for older pages.
+   * Subscribe to non-fatal transport errors. These indicate something went
+   * wrong but the transport is still operational. Returns an unsubscribe function.
    */
-  history(options?: LoadHistoryOptions): Promise<PaginatedMessages<TMessage>>;
+  on(event: 'error', handler: (error: Ably.ErrorInfo) => void): () => void;
 
   /**
    * Tear down the transport: unsubscribe from the channel, close active