@ably/ai-transport 0.2.0 → 0.3.0

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

@@ -1,12 +1,14 @@
 /** Agent (server-side) session types: options, run runtime, and the Run / AgentSession contracts. */
 
 import type * as Ably from 'ably';
+// Also augments RealtimeChannel with `.object` (ably/liveobjects side-effect).
+import type * as AblyObjects from 'ably/liveobjects';
 
 import type { Logger } from '../../../logger.js';
 import type { Codec, CodecInputEvent, CodecOutputEvent, WriteOptions } from '../../codec/types.js';
 import type { Invocation } from '../invocation.js';
 import type { CancelRequest, RunEndReason } from './shared.js';
-import type { MessageNode } from './tree.js';
+import type { MessageNode, Tree } from './tree.js';
 
 // ---------------------------------------------------------------------------
 // Agent session options
@@ -43,8 +45,9 @@ export interface AgentSessionOptions<
 
   /**
    * How long `Run.start()` will wait for the input event(s) tagged with
-   * the run's `invocationId` to arrive on the channel (rewind + live wait)
-   * before rejecting with `InputEventNotFound`. The rejection bubbles up to the
+   * the run's `invocationId` to arrive on the channel — across both the
+   * post-attach live subscription and the bounded history scan — before
+   * rejecting with `InputEventNotFound`. The rejection bubbles up to the
    * developer's HTTP handler, which should surface it as a non-2xx response
    * so the client's pending send fails.
    * Default: 30000 (30 seconds).
@@ -52,60 +55,41 @@ export interface AgentSessionOptions<
   inputEventLookupTimeoutMs?: number;
 
   /**
-   * Maximum number of distinct invocation-ids whose input events
-   * may be buffered while waiting for `Run.start()` to register a lookup
-   * listener. Channel rewind on attach can replay input events before any
-   * run has been created for them; this buffer holds those events so
-   * that subsequent `start()` calls can drain them on registration.
+   * How far back in time `Run.start()` scans channel history for the
+   * triggering input event. Implements the lookback bound for the
+   * input-event scan — anything older than `Date.now() - inputEventLookbackMs`
+   * is treated as outside the lookup window.
    *
-   * Each entry corresponds to one invocation-id regardless of how many
-   * events that invocation buffered. When the limit is exceeded the
-   * oldest invocation entry (and all its buffered events) is FIFO-evicted
-   * — the client whose input was dropped will fail their lookup with
-   * `InputEventNotFound`. The eviction is logged at warn level so operators
-   * can correlate capacity pressure with `InputEventNotFound` errors.
+   * History is fetched with `untilAttach: true` so the scan composes
+   * with the live subscription by serial boundary — together they cover
+   * every message within `inputEventLookbackMs` of attach.
    *
-   * Default: 200.
+   * Increase this for long-suspended runs whose continuation may arrive
+   * many minutes after the original publish. Decrease it for stricter
+   * recency.
+   *
+   * Default: 120000 (2 minutes).
    */
-  inputEventBufferLimit?: number;
+  inputEventLookbackMs?: number;
 
   /**
-   * The channel rewind applied when the agent attaches. Replays the whole
-   * channel subscription on attach (not just input events) so the lookup
-   * can catch input events published before the session attached. Passed
-   * through verbatim to Ably's `params.rewind` channel parameter — accepts
-   * duration strings (`"2m"`, `"30s"`) or a count of messages as a string
-   * (e.g. `"50"`). Malformed values surface as a channel attach error from
-   * Ably; the SDK does not pre-validate.
-   *
-   * A longer window improves the chances of catching an input event for an
-   * agent that takes a while to come up after the client published, but
-   * also increases the buffer pressure on `inputEventBufferLimit` because
-   * more events may be replayed on attach.
+   * Extra Ably channel modes to request on the session's channel, on top of the
+   * modes AI Transport always needs. Pass `OBJECT_MODES` (or
+   * `['OBJECT_SUBSCRIBE', 'OBJECT_PUBLISH']`) to use Ably LiveObjects via
+   * {@link AgentSession.object}. Omit to attach with the default mode set.
    *
-   * Default: `"2m"`.
+   * The session requests the union of these modes with the modes it always
+   * needs, so passing extra modes never drops the SDK's required modes. The
+   * connection's token/key capability must permit the requested operations,
+   * otherwise the server grants only the permitted subset.
    */
-  rewindWindow?: string;
+  channelModes?: readonly Ably.ChannelMode[];
 }
 
 // ---------------------------------------------------------------------------
 // Run options
 // ---------------------------------------------------------------------------
 
-/**
- * A batch of events targeting an existing message.
- * Each node specifies the target message and the events to apply to it.
- * Used for cross-run updates such as tool result delivery.
- */
-export interface EventsNode<TOutput extends CodecOutputEvent> {
-  /** Discriminator — identifies this as an events node. */
-  kind: 'event';
-  /** The `codec-message-id` of the existing message to update. */
-  codecMessageId: string;
-  /** Outputs to apply to the target message. */
-  events: TOutput[];
-}
-
 /**
  * Options for `Run.pipe` — per-operation overrides for the assistant message.
  * @template TOutput - The codec output type carried by the stream; used by the `resolveWriteOptions` hook.
@@ -206,7 +190,7 @@ export interface RunRuntime<TOutput extends CodecOutputEvent> {
    *   `Ably.ErrorInfo` (code `StreamError`) for standardized observability.
    * - Failures in the `onCancel` handler.
    *
-   * Publish failures in `start`, `addEvents`, and `end`
+   * Publish failures in `start` 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. Run errors never render the session unusable, but the run may
@@ -240,23 +224,47 @@ export interface RunView<TMessage> {
 /** Options for {@link Run.loadConversation}. */
 export interface LoadConversationOptions {
   /**
-   * Number of wire messages to request per history page.
-   * Default: 200.
-   */
-  pageLimit?: number;
-  /**
-   * Maximum total wire messages to collect across all pages before
-   * stopping pagination. A safety bound so a long-lived channel
-   * doesn't exhaust memory.
-   * Default: 2000.
+   * Maximum number of ANCESTOR reply RunNodes to walk back through the
+   * chain. Input nodes encountered alongside don't count toward the bound,
+   * and neither does the current run's own node (it is the conversation
+   * tail, not ancestor context). Default unbounded (walks to the
+   * conversation root).
+   *
+   * Set this to bound the LLM context window — `maxRuns: 5` returns the
+   * 5 most-recent prior reply runs and their associated input nodes
+   * (each bounded run's triggering input included, so the chain never
+   * starts assistant-first), in chronological order.
    */
-  maxMessages?: number;
+  maxRuns?: number;
 }
 
+/**
+ * How a run terminates, passed to {@link Run.end}. Discriminated on `reason`:
+ * an `'error'` end may carry a terminal `error`; any other reason carries none.
+ */
+export type RunEndParams =
+  | {
+      /** Why the run ended — any terminal reason other than `'error'`. */
+      reason: Exclude<RunEndReason, 'error'>;
+    }
+  | {
+      /** The run ended in error. */
+      reason: 'error';
+      /**
+       * Optional terminal error to surface to clients. Omit to end in error
+       * without detail.
+       */
+      error?: Ably.ErrorInfo;
+    };
+
 /**
  * A server-side run with explicit lifecycle methods. Generic over the codec's
- * output, projection, and message types.
+ * output, projection, and message types. `TProjection` is retained for
+ * parameter symmetry with {@link AgentSession.createRun}; it does not
+ * appear in the Run's public surface today but keeps the type slot
+ * available for future per-Run projection accessors.
  */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- see JSDoc
 export interface Run<TOutput extends CodecOutputEvent, TProjection, TMessage> {
   /** The run's unique identifier. */
   readonly runId: string;
@@ -295,7 +303,7 @@ export interface Run<TOutput extends CodecOutputEvent, TProjection, TMessage> {
   /**
    * Publish the run's opening lifecycle event to the channel (run-start, or
    * run-resume for a continuation). Must be called before any other run method
-   * (pipe, addEvents, suspend, end).
+   * (pipe, suspend, end).
    */
   start(): Promise<void>;
 
@@ -306,47 +314,26 @@ export interface Run<TOutput extends CodecOutputEvent, TProjection, TMessage> {
    */
   pipe(stream: ReadableStream<TOutput>, options?: PipeOptions<TOutput>): Promise<StreamResult>;
 
-  /**
-   * Publish events targeting existing messages in the tree. Each node
-   * specifies a target message (by `codecMessageId`) and the events to apply.
-   * Events are encoded and published with the target's `codec-message-id`,
-   * so receiving clients apply them to the existing node rather than
-   * creating a new one.
-   *
-   * Used for cross-run updates such as tool result delivery after
-   * approval or client-side tool execution.
-   */
-  addEvents(nodes: EventsNode<TOutput>[]): Promise<void>;
-
-  /**
-   * Fetch every channel message bound to this run and fold them through
-   * the codec into a single projection. Used by the agent to reconstruct
-   * the run's full state — including client-published tool-output amends
-   * the agent didn't observe live — when resuming a suspended run.
-   *
-   * Uses `channel.history()` (no `untilAttach`) so messages published
-   * after the channel was originally attached are still included. Each
-   * call paginates until either there are no more pages or an internal
-   * safety bound is reached.
-   * @returns The TProjection produced by folding every event for this run
-   *   in serial order. The caller extracts what they need via
-   *   {@link Codec.getMessages}.
-   */
-  loadProjection(): Promise<TProjection>;
-
   /**
    * Reconstruct the full multi-turn conversation by walking the ancestor
-   * run chain and concatenating each run's messages, oldest turn first.
+   * run chain over the session's Tree, concatenating each ancestor's
+   * projection (oldest turn first) plus the current run's projection.
    *
-   * Performs a single `channel.history()` scan and builds projections for
-   * all ancestor runs plus the current run. After this call:
-   * - {@link Run.messages} returns the complete conversation (all ancestor
-   *   turns followed by the current run's messages), making it ready to
-   *   pass directly to the LLM.
-   * - The current run's projection is cached so {@link Run.pipe} works
-   *   correctly without a separate {@link Run.loadProjection} call.
-   * @param options - Optional tuning for history pagination.
-   * @returns The same message list now accessible via {@link Run.messages}.
+   * Hydrates the Tree as needed from channel history if the chain from
+   * the run's structural-parent anchor isn't already fully present;
+   * subsequent reads of {@link Run.messages} re-walk the same Tree and
+   * reflect any further folds (e.g. live arrivals from concurrent runs).
+   * No cache: every call computes a fresh snapshot from the live Tree.
+   *
+   * Walks to the conversation root by default; bound the walk via the
+   * optional {@link LoadConversationOptions.maxRuns} cap. If channel
+   * retention has expired older turns, the walk stops at what is available.
+   * @param options - Optional walk bounds.
+   * @returns The conversation messages in chronological order, ready to pass to an LLM.
+   * @throws {Ably.ErrorInfo} `HistoryFetchFailed` — or the underlying Ably
+   *   code when the failure carried one — when the history fetch fails after
+   *   retries (the conversation is never silently truncated on fetch
+   *   failure); `InvalidArgument` when the run's signal aborts.
    */
   loadConversation(options?: LoadConversationOptions): Promise<TMessage[]>;
 
@@ -362,8 +349,11 @@ export interface Run<TOutput extends CodecOutputEvent, TProjection, TMessage> {
    */
   suspend(): Promise<void>;
 
-  /** Publish run-end event to the channel and clean up. Terminal. */
-  end(reason: RunEndReason): Promise<void>;
+  /**
+   * Publish run-end event to the channel and clean up. Terminal.
+   * @param params - How the run ended; see {@link RunEndParams}.
+   */
+  end(params: RunEndParams): Promise<void>;
 }
 
 // ---------------------------------------------------------------------------
@@ -372,13 +362,50 @@ export interface Run<TOutput extends CodecOutputEvent, TProjection, TMessage> {
 
 /** Server-side session that manages run lifecycles over an Ably channel. */
 export interface AgentSession<TOutput extends CodecOutputEvent, TProjection, TMessage> {
+  /**
+   * The Ably presence object for this session's channel.
+   *
+   * Exposed as a convenience so the agent can track and publish presence
+   * (`enter`/`leave`/`update`/`get`/`subscribe`) — for example, to detect
+   * whether the requesting user is still connected — without obtaining the
+   * channel separately. This is the same `Ably.RealtimePresence` instance the
+   * underlying channel exposes; the session applies no additional semantics.
+   * Presence operations implicitly attach the channel and do not require
+   * {@link connect} to have been called first.
+   */
+  readonly presence: Ably.RealtimePresence;
+
+  /**
+   * The Ably LiveObjects entry point for this session's channel.
+   *
+   * Exposed as a convenience so the agent can read and mutate shared objects
+   * (LiveMap / LiveCounter) on the same channel the session uses, without
+   * obtaining the channel separately. This is the same `RealtimeObject`
+   * instance the underlying channel exposes; the session applies no additional
+   * semantics. Operating on it requires (a) the Realtime client to have been
+   * constructed with the `LiveObjects` plugin from `ably/liveobjects` and
+   * (b) the object channel modes to have been requested via
+   * {@link AgentSessionOptions.channelModes}. When either is absent the
+   * underlying SDK throws; the session does not suppress the error.
+   */
+  readonly object: AblyObjects.RealtimeObject;
+
+  /**
+   * The session's materialisation tree. Every Ably message received on the channel
+   * (live + history) folds into this tree; consumers can introspect hydrated
+   * conversation state via {@link Tree.getNodeByCodecMessageId} /
+   * {@link Tree.getRunNode} etc. Mirrors `ClientSession.tree` so both
+   * sessions share one materialisation engine.
+   */
+  readonly tree: Tree<TOutput, TProjection>;
+
   /**
    * Subscribe (unfiltered) to the shared channel and (implicitly) attach. The
-   * subscribe is deliberately unfiltered so channel-rewind-replayed input
-   * events also reach the dispatcher, which routes by name (cancel vs. input
-   * event). Idempotent — subsequent calls return the same promise. All run
-   * methods (`start`, `addEvents`, `pipe`, `loadProjection`,
-   * `loadConversation`, `suspend`, `end`) throw `InvalidArgument` until
+   * subscribe is deliberately unfiltered so channel-history-replayed input
+   * events reach the materialisation engine, which the input-event lookup
+   * queries via the Tree. Idempotent — subsequent calls return the same
+   * promise. All run methods (`start`, `pipe`, `loadConversation`,
+   * `suspend`, `end`) throw `InvalidArgument` until
    * `connect()` has been *called*; once it has, they await the in-flight
    * connect promise rather than throwing.
    */

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

@@ -1,6 +1,8 @@
 /** Client session types: options, send options, the ActiveRun handle, and the ClientSession contract. */
 
 import type * as Ably from 'ably';
+// Also augments RealtimeChannel with `.object` (ably/liveobjects side-effect).
+import type * as AblyObjects from 'ably/liveobjects';
 
 import type { Logger } from '../../../logger.js';
 import type { Codec, CodecInputEvent, CodecOutputEvent } from '../../codec/types.js';
@@ -22,6 +24,12 @@ export interface ClientSessionOptions<
   /**
    * The Ably Realtime client. The caller owns its lifecycle —
    * `session.close()` does not close the client.
+   *
+   * The session's identity is taken from this client's `auth.clientId` (set
+   * via the Ably token or `ClientOptions.clientId`) — it is read at publish
+   * time and stamped on the wire as the run/input client id so other clients
+   * can attribute messages. A connection without a concrete clientId
+   * (anonymous, or a wildcard `*` token) publishes without one.
    */
   client: Ably.Realtime;
 
@@ -35,16 +43,22 @@ export interface ClientSessionOptions<
   /** The codec to use for encoding/decoding. */
   codec: Codec<TInput, TOutput, TProjection, TMessage>;
 
-  /**
-   * The client's identity, used as the Ably publisher `clientId` on
-   * everything this session publishes. Surfaces on the wire as the
-   * run/input client id so other clients can attribute messages.
-   */
-  clientId?: string;
-
   /** Initial messages to seed the conversation tree with. Forms a linear chain. */
   messages?: TMessage[];
 
+  /**
+   * Extra Ably channel modes to request on the session's channel, on top of the
+   * modes AI Transport always needs. Pass `OBJECT_MODES` (or
+   * `['OBJECT_SUBSCRIBE', 'OBJECT_PUBLISH']`) to use Ably LiveObjects via
+   * {@link ClientSession.object}. Omit to attach with the default mode set.
+   *
+   * The session requests the union of these modes with the modes it always
+   * needs, so passing extra modes never drops the SDK's required modes. The
+   * connection's token/key capability must permit the requested operations,
+   * otherwise the server grants only the permitted subset.
+   */
+  channelModes?: readonly Ably.ChannelMode[];
+
   /** Logger instance for diagnostic output. */
   logger?: Logger;
 }
@@ -75,12 +89,6 @@ export interface SendOptions {
    * agent, which mints a distinct `invocationId` per HTTP request.
    */
   runId?: string;
-  /**
-   * Currently non-functional: the send path always mints each input's
-   * `inputEventId` with `crypto.randomUUID()` (no override is read), so a
-   * value supplied here has no effect.
-   */
-  inputEventId?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -171,6 +179,34 @@ export interface ClientSession<
   /** The default paginated, branch-aware view for rendering — events scoped to visible messages. */
   readonly view: View<TInput, TMessage>;
 
+  /**
+   * The Ably presence object for this session's channel.
+   *
+   * Exposed as a convenience so callers can track and publish presence
+   * (`enter`/`leave`/`update`/`get`/`subscribe`) — for example, to detect
+   * whether an agent is online — without obtaining the channel separately.
+   * This is the same `Ably.RealtimePresence` instance the underlying channel
+   * exposes; the session applies no additional semantics. Presence operations
+   * implicitly attach the channel and do not require {@link connect} to have
+   * been called first.
+   */
+  readonly presence: Ably.RealtimePresence;
+
+  /**
+   * The Ably LiveObjects entry point for this session's channel.
+   *
+   * Exposed as a convenience so callers can read and mutate shared objects
+   * (LiveMap / LiveCounter) on the same channel the session uses, without
+   * obtaining the channel separately. This is the same `RealtimeObject`
+   * instance the underlying channel exposes; the session applies no additional
+   * semantics. Operating on it requires (a) the Realtime client to have been
+   * constructed with the `LiveObjects` plugin from `ably/liveobjects` and
+   * (b) the object channel modes to have been requested via
+   * {@link ClientSessionOptions.channelModes}. When either is absent the
+   * underlying SDK throws; the session does not suppress the error.
+   */
+  readonly object: AblyObjects.RealtimeObject;
+
   /**
    * Subscribe to the channel and (implicitly) attach. Idempotent —
    * subsequent calls return the same promise. The View's write operations

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

@@ -25,6 +25,12 @@ interface RunLifecycleBase {
    * Empty string if the wire didn't carry an invocation-id.
    */
   invocationId: string;
+  /**
+   * Ably server timestamp (epoch ms) of the lifecycle message; absent for an
+   * optimistic local event. Advances the Tree's event-log retention clock and
+   * the target run's last-activity time.
+   */
+  timestamp?: number;
 }
 
 /**
@@ -84,12 +90,23 @@ export type RunLifecycleEvent =
        * 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;
-    });
+    } & (
+        | {
+            /** Why the run ended — any terminal reason other than `'error'`. */
+            reason: Exclude<RunEndReason, 'error'>;
+          }
+        | {
+            /** The run ended in error. */
+            reason: 'error';
+            /**
+             * Terminal error detail, reconstructed from the run-end's
+             * `error-code` / `error-message` headers (or a generic fallback
+             * when the run ended in error without detail). The Tree records it
+             * on the RunNode and exposes it via `RunInfo.error`.
+             */
+            error: Ably.ErrorInfo;
+          }
+      ));
 
 // ---------------------------------------------------------------------------
 // Conversation tree (branching history)
@@ -117,6 +134,27 @@ export interface MessageNode<TMessage> {
   serial: string | undefined;
 }
 
+/**
+ * A Run's lifecycle state, modelled as one discriminated value so the terminal
+ * `error` is carried exactly when `status` is `'error'`. A RunNode is mutated
+ * in place, so status and its dependent error move together — transitions
+ * reassign `node.state` wholesale rather than setting fields individually.
+ */
+export type RunNodeState =
+  | {
+      /** `'active'` (streaming), `'suspended'` (paused), or a non-error terminal reason. */
+      status: 'active' | 'suspended' | Exclude<RunEndReason, 'error'>;
+    }
+  | {
+      /** Terminal error status. */
+      status: 'error';
+      /**
+       * The run-end's stamped error (or a generic fallback). Exposed to
+       * consumers via `RunInfo.error`.
+       */
+      error: Ably.ErrorInfo;
+    };
+
 /**
  * A node in the conversation tree, representing a single Run.
  *
@@ -173,13 +211,12 @@ export interface RunNode<TProjection> {
    */
   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.
+   * Run lifecycle state — see {@link RunNodeState}. `'active'` until a terminal
+   * event; `'suspended'` while paused (a continuation re-activates it);
+   * otherwise the run-end reason, carrying `error` when that reason is
+   * `'error'`.
    */
-  status: 'active' | 'suspended' | RunEndReason;
+  state: RunNodeState;
   /** Per-Run codec projection. Folded by the Tree from every event published under this run-id. */
   projection: TProjection;
   /**
@@ -317,6 +354,18 @@ export interface Tree<TOutput extends CodecOutputEvent, TProjection> {
    */
   getSiblingNodes(key: string): ConversationNode<TProjection>[];
 
+  /**
+   * Look up the raw Ably message that carried the given `event-id` header,
+   * if the Tree has observed it. Populated incrementally as messages arrive
+   * through the Tree's `ably-message` channel; not bounded except by the
+   * Tree's lifetime. Used by the agent's input-event lookup to find a
+   * triggering input message by id without scanning a separate buffer.
+   * @param eventId - The `event-id` header value to look up.
+   * @returns The matching raw Ably message, or undefined when the Tree has
+   *   not observed an event with that id.
+   */
+  findAblyMessageByEventId(eventId: string): Ably.InboundMessage | undefined;
+
   // --- Events ---
 
   /**

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

@@ -31,16 +31,8 @@ export interface LoadHistoryOptions {
 // 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 {
+/** Fields common to every {@link RunInfo} arm. */
+interface RunInfoBase {
   /** The Run's unique identifier. */
   runId: string;
   /**
@@ -48,14 +40,6 @@ export interface RunInfo {
    * 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.
@@ -66,6 +50,48 @@ export interface RunInfo {
   invocationId: string;
 }
 
+/**
+ * Projection-free, View-facing snapshot of a Run.
+ *
+ * Exposes the Run facts a UI consumer needs (`runId`, owner `clientId`,
+ * lifecycle `status`, `invocationId`, and — only when it failed — the terminal
+ * `error`) 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.
+ *
+ * Discriminated on `status`: a Run with `status: 'error'` carries the terminal
+ * `error`; every other status has no `error`. So `info.error` is defined
+ * exactly when `info.status === 'error'`.
+ */
+export type RunInfo =
+  | (RunInfoBase & {
+      /**
+       * 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 non-error terminal
+       * {@link RunEndReason} (`'complete'` or `'cancelled'`). Literal lifecycle
+       * vocabulary — UIs that want `'streaming'` rendering language translate
+       * at the component boundary. The `'error'` terminal status lives on the
+       * other arm of this union, where it is paired with the terminal `error`.
+       */
+      status: 'active' | 'suspended' | Exclude<RunEndReason, 'error'>;
+      /** Never present for a non-error status. */
+      error?: never;
+    })
+  | (RunInfoBase & {
+      /** Terminal error status — the Run ended with {@link RunEndReason} `'error'`, carrying the terminal `error` below. */
+      status: 'error';
+      /**
+       * The terminal error. Carries the agent-stamped `error-code` /
+       * `error-message` detail (or a generic fallback when the run ended in
+       * error without detail), so a UI can show *why* a run failed alongside
+       * its `'error'` status. Mirrors the `Ably.ErrorInfo` delivered via
+       * `ClientSession.on('error')`.
+       */
+      error: Ably.ErrorInfo;
+    });
+
 /**
  * Bundle returned by {@link View.branchSelection} describing the
  * sibling group anchored at a given codec-message-id.
@@ -138,20 +164,23 @@ export interface View<TInput extends CodecInputEvent, TMessage> {
    */
   runs(): RunInfo[];
 
-  /** Whether there are older Runs that can be loaded or revealed. */
+  /** Whether there are older messages 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.
+   * Reveal exactly `limit` older codecMessages — fewer only when channel history
+   * is exhausted. Loads from channel history when the tree doesn't already hold
+   * `limit` hidden messages, then advances the pagination window. 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.
+   * The pagination unit is the **codecMessage**. A node (a user prompt, or a
+   * reply Run) contributes 1..N messages to the flat list returned by
+   * {@link View.getMessages}; the window counts those messages, so a node
+   * straddling the boundary is **partially revealed** — only its newest messages
+   * enter the window — and the page lands exactly on `limit` rather than on a
+   * node boundary. Such a partially-revealed run still appears in
+   * {@link View.runs} and is event-scoped.
+   * @param limit - Number of older codecMessages to reveal. Defaults to 10.
    */
   loadOlder(limit?: number): Promise<void>;