@ably/ai-transport 0.1.0 → 0.2.0

package/src/core/transport/types.ts

@@ -1,712 +1,19 @@
 /**
  * Core transport types, parameterized by codec event and message types.
  *
- * These types define the contract for both client and server transport
- * implementations, independent of which codec (Vercel AI SDK, etc.) is used.
- */
-
-import type * as Ably from 'ably';
-
-import type { Logger } from '../../logger.js';
-import type { Codec, WriteOptions } from '../codec/types.js';
-
-// ---------------------------------------------------------------------------
-// Shared types
-// ---------------------------------------------------------------------------
-
-/** Why a turn ended. */
-export type TurnEndReason = 'complete' | 'cancelled' | 'error';
-
-/** Filter for cancel operations. At most one field should be set. */
-export interface CancelFilter {
-  /** Cancel a specific turn by ID. */
-  turnId?: string;
-  /** Cancel all turns belonging to the sender's clientId. */
-  own?: boolean;
-  /** Cancel all turns belonging to a specific clientId. */
-  clientId?: string;
-  /** Cancel all turns on the channel. */
-  all?: boolean;
-}
-
-/**
- * Passed to the server's `onCancel` hook for authorization decisions.
- * The hook inspects the incoming cancel message and decides whether to
- * allow each matched turn to be aborted.
- */
-export interface CancelRequest {
-  /** The raw Ably message that carried the cancel signal. */
-  message: Ably.InboundMessage;
-  /** The parsed cancel scope from the message headers. */
-  filter: CancelFilter;
-  /** Which active turnIds would be cancelled if allowed. */
-  matchedTurnIds: string[];
-  /** Map of turnId to the ownerClientId for the matched turns. */
-  turnOwners: Map<string, string>;
-}
-
-// ---------------------------------------------------------------------------
-// Server transport options
-// ---------------------------------------------------------------------------
-
-/** Options for creating a server transport. */
-export interface ServerTransportOptions<TEvent, TMessage> {
-  /** The Ably channel to publish to. Must match the client's channel. */
-  channel: Ably.RealtimeChannel;
-  /** The codec to use for encoding events and messages. */
-  codec: Codec<TEvent, TMessage>;
-  /** Logger instance for diagnostic output. */
-  logger?: Logger;
-  /**
-   * Called with non-fatal transport-level errors not scoped to any turn.
-   * 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;
-}
-
-// ---------------------------------------------------------------------------
-// Turn options
-// ---------------------------------------------------------------------------
-
-/** Options for addMessages — per-operation overrides for attribution. */
-export interface AddMessageOptions {
-  /** The user's clientId for attribution. */
-  clientId?: string;
-}
-
-/** Result of publishing user messages via addMessages. */
-export interface AddMessagesResult {
-  /** The `x-ably-msg-id` of each published message, in order. */
-  msgIds: string[];
-}
-
-/**
- * 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;
-  /** 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. */
-export interface NewTurnOptions<TEvent> {
-  /** The turn identifier (generated by the client transport or the server). */
-  turnId: string;
-
-  /** The user's clientId for attribution. */
-  clientId?: string;
-
-  /**
-   * The msg-id of the immediately preceding message in this branch.
-   * Used as the default parent for user messages (via addMessages) and
-   * assistant messages (via streamResponse) when not overridden per-operation.
-   */
-  parent?: string;
-
-  /**
-   * The msg-id of the message this turn replaces (creates a fork).
-   * Stamped on user messages (for edits) or assistant messages
-   * (for regeneration).
-   */
-  forkOf?: string;
-
-  /**
-   * Called before each Ably message is published in this turn.
-   * Mutate the Ably message in place to add custom extras.headers.
-   */
-  onMessage?: (message: Ably.Message) => void;
-
-  /**
-   * Called when the turn's stream is aborted (by cancel or server).
-   * Receives a write function to publish final events before the abort finalises.
-   */
-  onAbort?: (write: (event: TEvent) => Promise<void>) => void | Promise<void>;
-
-  /**
-   * Called when a cancel message arrives matching this turn.
-   * Return true to allow cancellation (fires abortSignal, stream aborts).
-   * Return false to reject (cancel ignored, stream continues).
-   * If not provided, all cancels are accepted.
-   */
-  onCancel?: (request: CancelRequest) => Promise<boolean>;
-
-  /**
-   * 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;
-}
-
-// ---------------------------------------------------------------------------
-// Turn interface
-// ---------------------------------------------------------------------------
-
-/** A server-side turn with explicit lifecycle methods. */
-export interface Turn<TEvent, TMessage> {
-  /** The turn's unique identifier. */
-  readonly turnId: string;
-
-  /** Abort signal scoped to this turn. Fires when a cancel event arrives for this turnId. */
-  readonly abortSignal: AbortSignal;
-
-  /** Publish turn-start event to the channel. Must be called before addMessages or streamResponse. */
-  start(): Promise<void>;
-
-  /**
-   * Publish user messages to the channel, scoped to this turn.
-   * 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: 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<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>;
-}
-
-// ---------------------------------------------------------------------------
-// Server transport interface
-// ---------------------------------------------------------------------------
-
-/** Server-side transport that manages turn lifecycles over an Ably channel. */
-export interface ServerTransport<TEvent, TMessage> {
-  /**
-   * Create a new turn. Synchronous — no channel activity until start() is called.
-   * The turn is registered for cancel routing immediately so that early cancels
-   * fire the abort signal.
-   */
-  newTurn(options: NewTurnOptions<TEvent>): Turn<TEvent, TMessage>;
-
-  /** Unsubscribe from cancel messages, abort all active turns, and clean up. */
-  close(): void;
-}
-
-// ---------------------------------------------------------------------------
-// Client transport options
-// ---------------------------------------------------------------------------
-
-/** Options for creating a client transport. */
-export interface ClientTransportOptions<TEvent, TMessage> {
-  /** The Ably channel to receive responses on and publish cancel signals to. */
-  channel: Ably.RealtimeChannel;
-
-  /** The codec to use for encoding/decoding. */
-  codec: Codec<TEvent, TMessage>;
-
-  /** The client's identity. Sent to the server in the POST body. */
-  clientId?: 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>);
-
-  /** Additional body fields merged into the HTTP POST. Function form for dynamic values. */
-  body?: Record<string, unknown> | (() => Record<string, unknown>);
-
-  /** Fetch credentials mode for the HTTP POST. */
-  credentials?: RequestCredentials;
-
-  /** Custom fetch implementation. Defaults to `globalThis.fetch`. */
-  fetch?: typeof globalThis.fetch;
-
-  /** Initial messages to seed the conversation tree with. Forms a linear chain. */
-  messages?: TMessage[];
-
-  /** Logger instance for diagnostic output. */
-  logger?: Logger;
-}
-
-// ---------------------------------------------------------------------------
-// Send options
-// ---------------------------------------------------------------------------
-
-/** Per-send options for customizing the HTTP POST and branching metadata. */
-export interface SendOptions {
-  /** Additional fields merged into the HTTP POST body. */
-  body?: Record<string, unknown>;
-  /** Additional headers for the HTTP POST. */
-  headers?: Record<string, string>;
-  /**
-   * The msg-id of the message this send replaces (fork).
-   * Set for regeneration (forkOf an assistant message) or
-   * edit (forkOf a user message).
-   */
-  forkOf?: string;
-  /**
-   * The msg-id of the message that precedes this one in the
-   * conversation thread. If omitted, auto-computed from the last
-   * message in the view.
-   */
-  parent?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Turn lifecycle events
-// ---------------------------------------------------------------------------
-
-/** A structured event describing a turn starting or ending. */
-export type TurnLifecycleEvent =
-  | {
-      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 };
-
-// ---------------------------------------------------------------------------
-// Active turn handle
-// ---------------------------------------------------------------------------
-
-/** 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. 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[];
-}
-
-// ---------------------------------------------------------------------------
-// Close options
-// ---------------------------------------------------------------------------
-
-/** Options for closing a client transport. */
-export interface CloseOptions {
-  /** Cancel in-progress turns before closing. Publishes a cancel message to the channel. */
-  cancel?: CancelFilter;
-}
-
-// ---------------------------------------------------------------------------
-// History / pagination
-// ---------------------------------------------------------------------------
-
-/** 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[];
-  /** Whether there are older pages available. */
-  hasNext(): boolean;
-  /** Fetch the next (older) page. Returns undefined if no more pages. */
-  next(): Promise<HistoryPage<TMessage> | undefined>;
-}
-
-/** Options for loading channel history. */
-export interface LoadHistoryOptions {
-  /** Max messages per page. Default: 100. */
-  limit?: number;
-}
-
-// ---------------------------------------------------------------------------
-// Conversation tree (branching history)
-// ---------------------------------------------------------------------------
-
-/** A node in the conversation tree, representing a single domain message. */
-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. */
-  msgId: string;
-  /** Parent node's msg-id (x-ably-parent), or undefined for root messages. */
-  parentId: string | undefined;
-  /** The msg-id this node forks from (x-ably-fork-of), or undefined if first version. */
-  forkOf: string | undefined;
-  /** Full Ably headers for this message. */
-  headers: Record<string, string>;
-  /**
-   * Ably serial for this message. Lexicographically comparable for total order.
-   * Used to sort siblings deterministically regardless of delivery/history order.
-   * Absent for optimistic messages (set when the server relay arrives).
-   */
-  serial: string | undefined;
-}
-
-/** @deprecated Use {@link MessageNode} instead. */
-export type TreeNode<TMessage> = MessageNode<TMessage>;
-
-/**
- * Materializes a branching conversation tree from a flat oplog.
+ * The definitions live in `./types/`, split along the Tree / View / Session
+ * boundary. This barrel re-exports them so consumers keep importing from a
+ * single module:
  *
- * 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.
+ * - `shared.ts` — cross-cutting (RunEndReason, CancelRequest).
+ * - `agent.ts` — agent session, run runtime, Run / AgentSession.
+ * - `tree.ts` — conversation-tree nodes, lifecycle events, Tree.
+ * - `view.ts` — history pagination, branch selection, View.
+ * - `client.ts` — client session options, ActiveRun, ClientSession.
  */
-export interface Tree<TMessage> {
-  /**
-   * Get all messages that are siblings (alternatives) at a given
-   * fork point. Returns an array ordered chronologically by serial.
-   * The message identified by msgId is always included.
-   */
-  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;
-
-  /** Get the stored headers for a node by msgId, or undefined if not found. */
-  getHeaders(msgId: string): Record<string, string> | undefined;
-
-  // --- Mutation (used by the transport, not the UI) ---
-
-  /**
-   * Insert or update a message in the tree. Reads parent/forkOf from the
-   * provided headers. If the message already exists (by msgId), updates
-   * it in place. The optional serial is the Ably message serial used for
-   * deterministic sibling ordering.
-   */
-  upsert(msgId: string, message: TMessage, headers: Record<string, string>, serial?: string): void;
-
-  /** Remove a message from the tree. */
-  delete(msgId: string): void;
-
-  // --- Events ---
-
-  /** 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;
-}
-
-// ---------------------------------------------------------------------------
-// View — windowed projection over the tree
-// ---------------------------------------------------------------------------
-
-/**
- * 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;
-
-  /**
-   * 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 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 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 this view's branch.
-   */
-  edit(messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>>;
-
-  /**
-   * 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.
-   */
-  update(msgId: string, events: TEvent[], options?: SendOptions): Promise<ActiveTurn<TEvent>>;
-
-  // --- Observation ---
-
-  /** Active turn IDs for turns with visible messages, grouped by clientId. */
-  getActiveTurnIds(): Map<string, Set<string>>;
-
-  /** The visible message list changed (new visible node, branch switch, window shift). */
-  on(event: 'update', handler: () => void): () => void;
-
-  /** 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;
-
-  /** 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>;
-
-  /**
-   * 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.
-   */
-  createView(): View<TEvent, TMessage>;
-
-  /** Cancel turns matching the filter. Defaults to `{ own: true }` (all own turns). */
-  cancel(filter?: CancelFilter): Promise<void>;
-
-  /**
-   * 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;
-
-  /**
-   * 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;
-
-  /**
-   * 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>;
-
-  /**
-   * 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 transport: unsubscribe from the channel, close active
-   * streams, clear all handlers, and prevent further operations.
-   *
-   * Pass `cancel` to publish a cancel message before closing. Without it,
-   * only local state is torn down (the server keeps streaming).
-   */
-  close(options?: CloseOptions): Promise<void>;
-}
+export type * from './types/agent.js';
+export type * from './types/client.js';
+export type * from './types/shared.js';
+export type * from './types/tree.js';
+export type * from './types/view.js';