@ably/ai-transport 0.0.1

package/src/core/transport/turn-manager.ts

@@ -0,0 +1,147 @@
+/**
+ * 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';
+
+import {
+  EVENT_TURN_END,
+  EVENT_TURN_START,
+  HEADER_TURN_CLIENT_ID,
+  HEADER_TURN_ID,
+  HEADER_TURN_REASON,
+} from '../../constants.js';
+import type { Logger } from '../../logger.js';
+import type { TurnEndReason } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Interface
+// ---------------------------------------------------------------------------
+
+/** 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;
+}
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+interface TurnState {
+  controller: AbortController;
+  clientId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+class DefaultTurnManager implements TurnManager {
+  private readonly _channel: Ably.RealtimeChannel;
+  private readonly _logger: Logger | undefined;
+  private readonly _activeTurns = new Map<string, TurnState>();
+
+  constructor(channel: Ably.RealtimeChannel, logger?: Logger) {
+    this._channel = channel;
+    this._logger = logger?.withContext({ component: 'TurnManager' });
+  }
+
+  async startTurn(turnId: string, clientId?: string, externalController?: AbortController): Promise<AbortSignal> {
+    this._logger?.trace('DefaultTurnManager.startTurn();', { turnId, clientId });
+
+    const controller = externalController ?? new AbortController();
+    const resolvedClientId = clientId ?? '';
+    this._activeTurns.set(turnId, { controller, clientId: resolvedClientId });
+
+    await this._channel.publish({
+      name: EVENT_TURN_START,
+      extras: {
+        headers: {
+          [HEADER_TURN_ID]: turnId,
+          [HEADER_TURN_CLIENT_ID]: resolvedClientId,
+        },
+      },
+    });
+
+    this._logger?.debug('DefaultTurnManager.startTurn(); turn started', { turnId });
+    return controller.signal;
+  }
+
+  async endTurn(turnId: string, reason: TurnEndReason): Promise<void> {
+    this._logger?.trace('DefaultTurnManager.endTurn();', { turnId, reason });
+
+    const state = this._activeTurns.get(turnId);
+    const resolvedClientId = state?.clientId ?? '';
+
+    // Publish before deleting local state so that if publish fails,
+    // the turn remains in the active set and can be retried or cleaned up.
+    await this._channel.publish({
+      name: EVENT_TURN_END,
+      extras: {
+        headers: {
+          [HEADER_TURN_ID]: turnId,
+          [HEADER_TURN_CLIENT_ID]: resolvedClientId,
+          [HEADER_TURN_REASON]: reason,
+        },
+      },
+    });
+
+    this._activeTurns.delete(turnId);
+    this._logger?.debug('DefaultTurnManager.endTurn(); turn ended', { turnId, reason });
+  }
+
+  getSignal(turnId: string): AbortSignal | undefined {
+    return this._activeTurns.get(turnId)?.controller.signal;
+  }
+
+  getClientId(turnId: string): string | undefined {
+    return this._activeTurns.get(turnId)?.clientId;
+  }
+
+  abort(turnId: string): void {
+    this._logger?.debug('DefaultTurnManager.abort();', { turnId });
+    this._activeTurns.get(turnId)?.controller.abort();
+  }
+
+  getActiveTurnIds(): string[] {
+    return [...this._activeTurns.keys()];
+  }
+
+  close(): void {
+    this._logger?.trace('DefaultTurnManager.close();', { activeTurns: this._activeTurns.size });
+    for (const state of this._activeTurns.values()) {
+      state.controller.abort();
+    }
+    this._activeTurns.clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 const createTurnManager = (channel: Ably.RealtimeChannel, logger?: Logger): TurnManager =>
+  new DefaultTurnManager(channel, logger);

package/src/core/transport/types.ts

@@ -0,0 +1,533 @@
+/**
+ * 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 } 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>;
+}
+
+// ---------------------------------------------------------------------------
+// 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
+// ---------------------------------------------------------------------------
+
+/** 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.
+   */
+  onError?: (error: Ably.ErrorInfo) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Turn options
+// ---------------------------------------------------------------------------
+
+/** Options for addMessages — per-operation overrides for message identity and branching. */
+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. */
+export interface AddMessagesResult {
+  /** The `x-ably-msg-id` of each published message, in order. */
+  msgIds: string[];
+}
+
+/** Options for streamResponse — per-operation overrides for the assistant message. */
+export interface StreamResponseOptions {
+  /** The msg-id of the immediately preceding message in this branch. */
+  parent?: string | null;
+  /** The msg-id of the message this response replaces (for regeneration). */
+  forkOf?: string;
+}
+
+/** The result of streaming a response through the encoder. */
+export interface StreamResult {
+  /** Why the stream ended. */
+  reason: TurnEndReason;
+}
+
+/** 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 | null;
+
+  /**
+   * 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 errors scoped to this turn. Examples: turn-start
+   * publish failure, encoder recovery failure, stream encoding errors.
+   */
+  onError?: (error: Ably.ErrorInfo) => void;
+}
+
+// ---------------------------------------------------------------------------
+// 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 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.
+   * @returns The msg-ids of all published messages, in order.
+   */
+  addMessages(messages: MessageWithHeaders<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>;
+
+  /** 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. Defaults to `"/api/chat"`. */
+  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. Null means the message is a root.
+   * If omitted, auto-computed from the last message in the tree.
+   */
+  parent?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Turn lifecycle events
+// ---------------------------------------------------------------------------
+
+/** 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-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. */
+  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>;
+}
+
+// ---------------------------------------------------------------------------
+// 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 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[];
+  /** 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<PaginatedMessages<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 ConversationNode<TMessage> {
+  /** 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;
+}
+
+/**
+ * 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()`.
+ */
+export interface ConversationTree<TMessage> {
+  /**
+   * Flatten the tree along the currently selected branches into
+   * a linear message list. This is what getMessages() returns.
+   */
+  flatten(): 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 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;
+
+  /** 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;
+}
+
+// ---------------------------------------------------------------------------
+// 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> {
+  /**
+   * 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.
+   *
+   * The HTTP POST is fire-and-forget — the returned stream is available
+   * immediately. If the POST fails, the error is surfaced via `on("error")`.
+   */
+  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.
+   */
+  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.
+   */
+  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.
+   */
+  getTree(): ConversationTree<TMessage>;
+
+  /** Cancel turns matching the filter. Defaults to `{ own: true }` (all own turns). */
+  cancel(filter?: CancelFilter): Promise<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 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;
+
+  /** Subscribe to turn lifecycle events (start, end). Returns an unsubscribe function. */
+  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;
+
+  /**
+   * Get the accumulated raw Ably messages, in chronological order.
+   * Includes both live messages and history-loaded messages.
+   */
+  getAblyMessages(): Ably.InboundMessage[];
+
+  /** Get all currently active turns, keyed by clientId. */
+  getActiveTurnIds(): Map<string, Set<string>>;
+
+  /** Get Ably headers associated with a message via the conversation tree. */
+  getMessageHeaders(message: TMessage): Record<string, string> | undefined;
+
+  /** Get the current message list (follows selected branches). Updated by message lifecycle events. */
+  getMessages(): TMessage[];
+
+  /**
+   * Snapshot the current message list as message + headers pairs.
+   * Convenience for building the `history` body field in HTTP POSTs.
+   */
+  getMessagesWithHeaders(): MessageWithHeaders<TMessage>[];
+
+  /**
+   * 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.
+   */
+  history(options?: LoadHistoryOptions): Promise<PaginatedMessages<TMessage>>;
+
+  /**
+   * 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>;
+}