@ably/ai-transport 0.0.1 → 0.2.0

package/src/core/transport/types/tree.ts

@@ -0,0 +1,344 @@
+/** Conversation-tree types: nodes, the run-lifecycle event, output events, and the Tree contract. */
+
+import type * as Ably from 'ably';
+
+import type { CodecOutputEvent } from '../../codec/types.js';
+import type { RunEndReason } from './shared.js';
+
+// ---------------------------------------------------------------------------
+// Run lifecycle events
+// ---------------------------------------------------------------------------
+
+/**
+ * Fields common to every {@link RunLifecycleEvent} arm.
+ */
+interface RunLifecycleBase {
+  /** The run-id this lifecycle event concerns. */
+  runId: string;
+  /** The owning client's identity (Ably publisher `clientId`). */
+  clientId: string;
+  /**
+   * The invocation-id this lifecycle event was published under (wire
+   * `invocation-id`). Lets consumers correlate the run's lifecycle back to the
+   * invocation that drove it; on a run-start the Tree records it on the RunNode
+   * at first creation so an optimistic Run exposes the invocation synchronously.
+   * Empty string if the wire didn't carry an invocation-id.
+   */
+  invocationId: string;
+}
+
+/**
+ * A structured event describing a run starting, suspending, resuming, or
+ * ending. The `type` discriminator (`start` / `suspend` / `resume` / `end`) is
+ * the in-memory domain vocabulary and is intentionally distinct from the wire
+ * message names (`ai-run-start` / `ai-run-suspend` / `ai-run-resume` /
+ * `ai-run-end`) those events are decoded from.
+ */
+export type RunLifecycleEvent =
+  | (RunLifecycleBase & {
+      type: 'start';
+      /**
+       * Ably channel serial of the run-start message, or `undefined` for an
+       * optimistic local event (no serial assigned yet). The Tree reads it to
+       * promote the Run's startSerial.
+       */
+      serial: string | undefined;
+      /** The codec-message-id of the parent message, if known. Omitted for root runs. */
+      parent?: string;
+      /**
+       * The codec-message-id of the user prompt being forked, when the run is an
+       * edit. Carried verbatim from the `fork-of` wire header.
+       */
+      forkOf?: string;
+      /**
+       * The codec-message-id of the assistant message this run regenerates, when
+       * the run is a regenerate continuation. Carried verbatim from the
+       * `msg-regenerate` wire header. The Tree treats regenerates
+       * as continuations (no `forkOf` at the Run level) — the View
+       * realises the replacement when materialising messages.
+       */
+      regenerates?: string;
+    })
+  | (RunLifecycleBase & {
+      type: 'suspend';
+      /**
+       * Ably channel serial of the run-suspend message, or `undefined` for an
+       * optimistic local event. The Tree reads it to set the Run's endSerial
+       * (a suspended run carries the serial at which it paused).
+       */
+      serial: string | undefined;
+    })
+  | (RunLifecycleBase & {
+      type: 'resume';
+      /**
+       * Ably channel serial of the run-resume message, or `undefined` for an
+       * optimistic local event. A resume re-enters an existing run; it does not
+       * promote the Run's startSerial (the original run-start owns that).
+       */
+      serial: string | undefined;
+    })
+  | (RunLifecycleBase & {
+      type: 'end';
+      /**
+       * Ably channel serial of the run-end message, or `undefined` for an
+       * optimistic local event. The Tree reads it to set the Run's endSerial.
+       */
+      serial: string | undefined;
+      /**
+       * Why the run ended — the terminal reason the Tree records as the
+       * RunNode's status: `complete`, `cancelled`, or `error`.
+       */
+      reason: RunEndReason;
+    });
+
+// ---------------------------------------------------------------------------
+// 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 codec-message-id of this node — primary key in the tree. */
+  codecMessageId: string;
+  /** Parent node's codec-message-id (parent), or undefined for root messages. */
+  parentId: string | undefined;
+  /** The codec-message-id this node forks from (fork-of), or undefined if first version. */
+  forkOf: string | undefined;
+  /** The transport-tier headers (`extras.ai.transport`) for this message: the run/stream/identity/branching headers set and read by the transport layer. Codec-tier headers (`extras.ai.codec`) are not included. */
+  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;
+}
+
+/**
+ * A node in the conversation tree, representing a single Run.
+ *
+ * A RunNode is keyed by its agent-minted `runId`. Each RunNode owns a per-Run
+ * codec {@link TProjection} folded from every event published under that
+ * run-id; the SDK extracts the per-message list via {@link Codec.getMessages}
+ * when it needs to render messages for that Run.
+ *
+ * A regenerate is a sibling reply run: it shares its input-node parent
+ * ({@link parentCodecMessageId}) with the original reply, so same-parent reply
+ * runs form the regenerate group with no `forkOf` involved. (Editing a prompt
+ * instead produces a sibling {@link InputNode} via that node's `forkOf`.)
+ */
+export interface RunNode<TProjection> {
+  /** Discriminator — identifies this as a reply-run node within {@link ConversationNode}. */
+  kind: 'run';
+  /** The run-id of this Run — primary key in the tree. */
+  runId: string;
+  /**
+   * The codec-message-id this Run is rooted at — the `parent` header of the
+   * first observed message (or the run-start lifecycle event's `parent`
+   * field). This is the run's input node's codec-message-id: the user prompt
+   * the agent replied to. The Tree uses it for kind-blind reachability and to
+   * build the input→reply edge. `undefined` for the root Run.
+   */
+  parentCodecMessageId: string | undefined;
+  /**
+   * The node key of the node this Run replaces, or `undefined` if this Run is
+   * not a fork. Populated when the wire's `fork-of` header points at a
+   * codec-message-id that has been observed; the Tree resolves it through the
+   * codec-message-id → node-key index. Reply-run regenerate siblings do not
+   * use this (they group by shared parent) — it carries an explicit fork link
+   * when the wire stamps one.
+   */
+  forkOf: string | undefined;
+  /**
+   * The codec-message-id this Run regenerates, or `undefined` for non-regenerate
+   * Runs. Populated from the wire's `msg-regenerate` header (and the lifecycle
+   * event's `regenerates` field) verbatim — the Tree does not resolve it to a
+   * node key because the anchor is a message position, not a node.
+   *
+   * A regenerate run parents at the SAME input node as the reply it
+   * regenerates, so it joins that input's reply runs as a same-parent sibling;
+   * the message named by `regeneratesCodecMessageId` is replaced by this Run's
+   * content when the View materialises the chain into messages (Spec: AIT-CT13d).
+   */
+  regeneratesCodecMessageId: string | undefined;
+  /**
+   * Identity of the Ably client that started this Run, sourced from the
+   * `run-client-id` wire header (or the run-start lifecycle event's
+   * `clientId` field). Set once at Run creation and never updated; persists
+   * through the Run's lifecycle, including after `run-end`. Empty string if
+   * the wire didn't carry a client id.
+   */
+  clientId: string;
+  /**
+   * Run lifecycle status.
+   * - `'active'` — run-start observed, no terminal event yet.
+   * - `'suspended'` — run-suspend observed; the run is paused awaiting input
+   *   and stays live (a continuation re-activates it). Not terminal.
+   * - {@link RunEndReason} — terminal state reflecting the run-end reason.
+   */
+  status: 'active' | 'suspended' | RunEndReason;
+  /** Per-Run codec projection. Folded by the Tree from every event published under this run-id. */
+  projection: TProjection;
+  /**
+   * The agent-minted invocationId observed for this Run (wire `invocation-id`).
+   * The agent mints it, so an optimistic Run starts with an empty id; it is
+   * adopted from the agent's `ai-run-start` (or set at creation when the Run is
+   * first seen from a wire event carrying one) and never reassigned thereafter.
+   * Empty string until run-start arrives, or if the wire didn't carry an
+   * invocation-id.
+   */
+  invocationId: string;
+  /** Ably serial of the first observed message tagged with this run-id. Absent for optimistic Runs. */
+  startSerial: string | undefined;
+  /** Ably serial of the run-end lifecycle event, if observed. */
+  endSerial: string | undefined;
+}
+
+/**
+ * A node in the conversation tree, representing a single user input (prompt).
+ *
+ * An input node owns the user's prompt for one turn. It is keyed by the
+ * client-owned `codec-message-id` and never carries a run-id — the agent mints
+ * the run-id for the reply, which becomes a separate {@link RunNode} parented to
+ * this input node. An edit of a prompt is a sibling input node (via `forkOf`).
+ *
+ * Like a {@link RunNode}, it carries its own per-input codec {@link TProjection}
+ * folded from the input event(s) published under its codec-message-id; the SDK
+ * extracts the per-message list via {@link Codec.getMessages} when rendering.
+ */
+export interface InputNode<TProjection> {
+  /** Discriminator — identifies this as an input node within {@link ConversationNode}. */
+  kind: 'input';
+  /** The codec-message-id of this input — primary key in the tree. */
+  codecMessageId: string;
+  /**
+   * The codec-message-id of the node this input hangs off (its structural
+   * parent — the immediately preceding reply run on this chain), or `undefined`
+   * for the first input in a conversation. Used for kind-blind tree
+   * reachability alongside {@link RunNode.parentCodecMessageId}.
+   */
+  parentCodecMessageId: string | undefined;
+  /**
+   * The codec-message-id this input forks from when it is an edit of an earlier
+   * prompt, or `undefined` if it is the first version. Sibling input nodes
+   * (alternate prompts) share the same `forkOf` anchor.
+   */
+  forkOf: string | undefined;
+  /** Per-input codec projection. Folded by the Tree from every input event published under this codec-message-id. */
+  projection: TProjection;
+  /** Ably serial of the first observed message for this input. Absent for optimistic (locally-created) inputs. */
+  serial: string | undefined;
+}
+
+/**
+ * A node in the conversation tree: either a user {@link InputNode} or an agent
+ * {@link RunNode}. Narrow on `kind` (`'input'` vs `'run'`) before reading
+ * kind-specific fields.
+ */
+export type ConversationNode<TProjection> = InputNode<TProjection> | RunNode<TProjection>;
+
+/**
+ * Payload of the Tree's `output` event: the decoded agent outputs folded
+ * for a Run from a single inbound message, carrying the routing metadata a
+ * consumer needs to attribute or stream them.
+ */
+export interface OutputEvent<TOutput extends CodecOutputEvent> {
+  /**
+   * The runId the outputs were folded into, or `undefined` when the fold was
+   * into a user input node (which carries no run-id — the agent mints run-ids).
+   * An input fold always has empty {@link events}; consumers route by
+   * {@link inputCodecMessageId}, not this.
+   */
+  runId: string | undefined;
+  /**
+   * The codec-message-id of the input event that triggered this run — the
+   * agent's `input-codec-message-id` header. This is the stable key the client
+   * owns from send time (before the agent mints the runId), so the output
+   * stream can attribute outputs to the request that produced them. Distinct
+   * from {@link runId}: causal (which input produced these outputs) rather than
+   * the run's own identity. `undefined` when the carrying message had no such
+   * header — e.g. a purely-optimistic local fold with no wire echo yet.
+   */
+  inputCodecMessageId: string | undefined;
+  /**
+   * The `codec-message-id` the outputs were published under, or `undefined`
+   * when the message carried none.
+   */
+  codecMessageId: string | undefined;
+  /**
+   * Ably channel serial of the message that carried the outputs, or
+   * `undefined` for an optimistic local fold (no serial assigned yet).
+   */
+  serial: string | undefined;
+  /**
+   * The decoded agent outputs from this message, in wire order. Empty when
+   * the folded message carried only inputs (e.g. an optimistic user
+   * message); the event still fires so consumers can observe that the Run's
+   * projection changed.
+   */
+  events: TOutput[];
+}
+
+/**
+ * Materializes a branching conversation tree from a flat oplog of Ably
+ * messages. Each turn is two nodes: a user {@link InputNode} keyed by its
+ * client-owned codec-message-id and an agent {@link RunNode} keyed by the
+ * agent-minted run-id, parented to the input node.
+ *
+ * The Tree owns the complete conversation state across every observed node.
+ * Each node holds a per-node codec {@link TProjection} which the Tree folds
+ * from inbound events. The View walks the parent chain to extract a flat
+ * message list for rendering.
+ */
+export interface Tree<TOutput extends CodecOutputEvent, TProjection> {
+  /** Get a Run by runId, or undefined if not found. */
+  getRunNode(runId: string): RunNode<TProjection> | undefined;
+
+  /**
+   * Get the node that owns a given codec-message-id (via the Tree's
+   * codecMessageId index), or undefined if the codec-message-id hasn't been
+   * observed. The result is a {@link ConversationNode} union: narrow on `kind`
+   * (`'input'` vs `'run'`) before reading kind-specific fields.
+   */
+  getNodeByCodecMessageId(codecMessageId: string): ConversationNode<TProjection> | undefined;
+
+  /**
+   * Get the sibling group (both kinds) the node keyed by `key` belongs to:
+   * edit versions for an input node (forkOf-linked, same parent), regenerate
+   * runs for a reply run (same input-node parent). Ordered oldest-first by
+   * serial; a single-element array when the node has no siblings. Empty when
+   * `key` is unknown. Narrow each node on `kind` before reading kind-specific
+   * fields.
+   * @param key - The node key ({@link RunNode.runId} or {@link InputNode.codecMessageId}).
+   * @returns The ordered sibling nodes.
+   */
+  getSiblingNodes(key: string): ConversationNode<TProjection>[];
+
+  // --- Events ---
+
+  /**
+   * Subscribe to tree structural changes (Run insert, delete, sort-reorder,
+   * startSerial promotion, run-start metadata backfill). Does NOT fire on
+   * content-only folds (streaming chunks) or on run-end status changes —
+   * those flow through `output` and `run` respectively.
+   */
+  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 run lifecycle events (start, suspend, resume, and end). */
+  on(event: 'run', handler: (event: RunLifecycleEvent) => void): () => void;
+
+  /**
+   * Subscribe to decoded agent outputs as they are folded into a Run.
+   * Fires once per inbound message after its fold, carrying the message's
+   * output events plus routing metadata (runId, codec-message-id, serial).
+   * Fires with an empty `events` array for inputs-only folds so it can also
+   * serve as a projection-changed signal.
+   */
+  on(event: 'output', handler: (event: OutputEvent<TOutput>) => void): () => void;
+}

package/src/core/transport/types/view.ts

@@ -0,0 +1,259 @@
+/** View types: history pagination, branch selection, run info, and the windowed View contract. */
+
+import type * as Ably from 'ably';
+
+import type { CodecInputEvent, CodecMessage } from '../../codec/types.js';
+import type { ActiveRun, SendOptions } from './client.js';
+import type { RunEndReason } from './shared.js';
+import type { RunLifecycleEvent } from './tree.js';
+
+// ---------------------------------------------------------------------------
+// History / pagination
+// ---------------------------------------------------------------------------
+
+/** A page of raw history wires from the channel. Internal to View/decodeHistory. */
+export interface HistoryPage {
+  /** Raw Ably messages that produced this page, in chronological order (oldest first). */
+  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 | undefined>;
+}
+
+/** Options for loading channel history. */
+export interface LoadHistoryOptions {
+  /** Max messages per page. Default: 100. */
+  limit?: number;
+}
+
+// ---------------------------------------------------------------------------
+// View — windowed projection over the tree
+// ---------------------------------------------------------------------------
+
+/**
+ * Projection-free, View-facing snapshot of a Run.
+ *
+ * Exposes the Run facts a UI consumer needs (`runId`, owner `clientId`,
+ * lifecycle `status`, `invocationId`) without leaking the codec's
+ * opaque per-Run projection or the Tree's structural fields. Callers
+ * that need the full Run record (parent / fork relationships, serials,
+ * projection) reach `session.tree.getRunNode(runId)` directly.
+ */
+export interface RunInfo {
+  /** The Run's unique identifier. */
+  runId: string;
+  /**
+   * Identity of the Ably client that started this Run. Empty string
+   * when the wire didn't carry an owner client id.
+   */
+  clientId: string;
+  /**
+   * Run lifecycle status. `'active'` while the Run is streaming;
+   * `'suspended'` while it is paused awaiting input (still live, a
+   * continuation re-activates it); otherwise the {@link RunEndReason} the Run
+   * terminated with. Literal lifecycle vocabulary — UIs that want `'streaming'`
+   * rendering language translate at the component boundary.
+   */
+  status: 'active' | 'suspended' | RunEndReason;
+  /**
+   * The agent-minted `invocationId` observed for this Run, adopted from the
+   * wire `ai-run-start`. Stable across the Run's lifecycle once observed.
+   * Empty string until run-start arrives (the agent mints it, so an
+   * optimistic Run carries none) or when the wire didn't carry an
+   * invocation-id.
+   */
+  invocationId: string;
+}
+
+/**
+ * Bundle returned by {@link View.branchSelection} describing the
+ * sibling group anchored at a given codec-message-id.
+ *
+ * Total / always-defined — `view.branchSelection(id)` is safe to call
+ * for any message:
+ *
+ *  - **Branch anchor (N ≥ 2 siblings)**: `siblings` carries every
+ *    sibling Run's view of the anchor slot, `index` is the selected
+ *    sibling's position, `selected === siblings[index]`,
+ *    `hasSiblings: true`.
+ *  - **Known non-anchor message**: `siblings = [thisMessage]`,
+ *    `index: 0`, `selected: thisMessage`, `hasSiblings: false`.
+ *  - **Unknown codec-message-id**: `siblings: []`, `index: 0`,
+ *    `selected: undefined`, `hasSiblings: false`.
+ *
+ * Because `siblings` always contains the currently rendered message
+ * (for known ids), `siblings.length` is `1` for a plain bubble (not
+ * `0`) and the indexing space matches between read and write —
+ * passing `branch.index` back into {@link View.selectSibling} is a
+ * round-trip no-op.
+ */
+export interface BranchSelection<TMessage> {
+  /** True when the codec-message-id is a branch anchor with more than one sibling. Equivalent to `siblings.length > 1`. */
+  hasSiblings: boolean;
+  /**
+   * The selected sibling and any alternatives, in tree-order (oldest
+   * first). Always contains the currently rendered message itself for
+   * known codec-message-ids; empty only when the id is unknown to the
+   * view.
+   */
+  siblings: TMessage[];
+  /** Index of the selected sibling within `siblings`. `0` when there is no real branching or the id is unknown. */
+  index: number;
+  /** Convenience reference to `siblings[index]`. `undefined` only when `siblings` is empty. */
+  selected: TMessage | undefined;
+}
+
+/**
+ * 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<TInput extends CodecInputEvent, TMessage> {
+  /**
+   * The visible messages along the selected branch, each paired with its
+   * codec-message-id (see {@link CodecMessage}). Computed by walking the
+   * visible Run chain (newest to root) and concatenating each Run's
+   * `codec.getMessages(projection)` in chronological order.
+   *
+   * Correlate a message back to the transport — routing a continuation
+   * input, resolving a regenerate/edit target, looking up the owning Run —
+   * via its `codecMessageId`, which the SDK assigns and tracks
+   * independently of any identity the domain `message` may carry. Read the
+   * domain object from each entry's `message` field.
+   */
+  getMessages(): CodecMessage<TMessage>[];
+
+  /**
+   * Snapshot of the visible Runs along the selected branch, in
+   * chronological order — already filtered by this view's pagination
+   * window, branch selection, and regenerate substitution. The
+   * companion to {@link getMessages}: same scope, exposed as
+   * projection-free {@link RunInfo} so consumers can iterate Run
+   * identity (runId, clientId, status, invocationId) without touching
+   * the Tree.
+   */
+  runs(): RunInfo[];
+
+  /** Whether there are older Runs that can be loaded or revealed. */
+  hasOlder(): boolean;
+
+  /**
+   * Reveal older Runs. Loads from channel history if the tree doesn't have
+   * enough, then advances the pagination window by up to `limit` Runs.
+   * Emits 'update' when the visible list changes.
+   *
+   * The pagination unit is the **Run**, not the message. A single Run
+   * typically contributes more than one message to the flat list returned
+   * by {@link View.getMessages} (e.g. a user prompt + assistant reply
+   * pair). Revealing `limit` Runs may add 1..N messages each to the
+   * visible window.
+   * @param limit - Maximum number of older Runs to reveal. Defaults to 100.
+   */
+  loadOlder(limit?: number): Promise<void>;
+
+  // --- Run lookup ---
+
+  /**
+   * Look up the {@link RunInfo} for the Run that owns `codecMessageId`.
+   * For a user input node's codec-message-id, resolves to its
+   * currently-selected reply run. Returns `undefined` when the
+   * codec-message-id hasn't been observed by the view, or when it names
+   * an input node that has no reply run yet.
+   * @param codecMessageId - The codec-message-id to look up.
+   */
+  runOf(codecMessageId: string): RunInfo | undefined;
+
+  /**
+   * Direct lookup by Run id. Kept for symmetry with {@link runOf} so
+   * callers that hold a `runId` (e.g. cancel handlers) get a one-step
+   * lookup. Returns `undefined` when the Run hasn't been observed.
+   * @param runId - The Run id to look up.
+   */
+  run(runId: string): RunInfo | undefined;
+
+  // --- Branch navigation ---
+
+  /**
+   * Resolve the {@link BranchSelection} bundle anchored at
+   * `codecMessageId`. Always returns a safe object — see
+   * {@link BranchSelection} for the per-case shape.
+   *
+   * Per AITRFC-014, branch points are message-anchored: edit forks
+   * point at the user prompt's codec-message-id, regenerate forks
+   * point at the assistant message's codec-message-id.
+   * @param codecMessageId - The codec-message-id of the bubble being rendered.
+   */
+  branchSelection(codecMessageId: string): BranchSelection<TMessage>;
+
+  /**
+   * Select a sibling at the branch point anchored at
+   * `codecMessageId`. `index` is clamped to
+   * `[0, siblings.length - 1]`. Silent no-op when `codecMessageId`
+   * is not a branch anchor. Emits 'update' when the visible output
+   * changes.
+   * @param codecMessageId - The codec-message-id of the bubble being rendered.
+   * @param index - The index of the sibling to select.
+   */
+  selectSibling(codecMessageId: string, index: number): void;
+
+  // --- Write operations ---
+
+  /**
+   * Send one or more TInputs on the channel and fire a POST. Each TInput
+   * carries its own routing metadata (`parent` / `target` / `codecMessageId`)
+   * via the {@link CodecInputEvent} base; the SDK reads those fields
+   * directly without runtime classification.
+   *
+   * To send a fresh user message, wrap the domain message with
+   * {@link Codec.createUserMessage} and pass the result here, e.g.
+   * `view.send(codec.createUserMessage(message))`.
+   *
+   * Convention: a send containing at least one `UserMessage` is a
+   * fresh send (mints a new `runId`). A send containing only
+   * tool-resolution inputs is a continuation — pair with
+   * `options.runId` to extend a suspended run.
+   *
+   * 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 session's `on("error")` and the stream is errored.
+   */
+  send(events: TInput | TInput[], options?: SendOptions): Promise<ActiveRun>;
+
+  /**
+   * Regenerate an assistant message. Mints a codec `Regenerate` input
+   * carrying `target` (the assistant codec-message-id being regenerated)
+   * and `parent` (the preceding user prompt's codec-message-id), both
+   * auto-computed from this view's branch — there are no new user inputs.
+   * The new reply run is not a `forkOf` fork; it continues the
+   * regenerated message's run, and the message-level replacement (the new
+   * assistant superseding the original) happens at projection-extraction
+   * time.
+   */
+  regenerate(messageId: string, options?: SendOptions): Promise<ActiveRun>;
+
+  /**
+   * Edit a user message. Creates a new run that forks the target message
+   * with replacement content. Automatically computes `forkOf` (the edited
+   * message) and `parent` from this view's branch.
+   */
+  edit(messageId: string, inputs: TInput | TInput[], options?: SendOptions): Promise<ActiveRun>;
+
+  // --- Observation ---
+
+  /** 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 run event occurred for a run with visible messages in the window. */
+  on(event: 'run', handler: (event: RunLifecycleEvent) => void): () => void;
+
+  /** Tear down the view — unsubscribe from tree events and clear internal state. */
+  close(): void;
+}