@ably/ai-transport 0.2.0 → 0.3.0

package/src/core/transport/agent-session.ts

@@ -6,16 +6,17 @@
  * single channel subscription — no separate cancel manager needed.
  *
  * The session exposes a single factory method — `createRun()` — which returns
- * a Run object with explicit lifecycle methods: start(), pipe(), addEvents(),
- * suspend(), and end() (suspend() and end() are both terminal).
+ * a Run object with explicit lifecycle methods: start(), pipe(), suspend(),
+ * and end() (suspend() and end() are both terminal).
  */
 
 import * as Ably from 'ably';
+// Also augments RealtimeChannel with `.object` (ably/liveobjects side-effect).
+import type * as AblyObjects from 'ably/liveobjects';
 
 import {
   EVENT_CANCEL,
   HEADER_CODEC_MESSAGE_ID,
-  HEADER_EVENT_ID,
   HEADER_FORK_OF,
   HEADER_INPUT_CODEC_MESSAGE_ID,
   HEADER_MSG_REGENERATE,
@@ -24,264 +25,42 @@ import {
   HEADER_RUN_ID,
 } from '../../constants.js';
 import { ErrorCode } from '../../errors.js';
-import type { Logger } from '../../logger.js';
-import { compareBySerial, getTransportHeaders } from '../../utils.js';
+import { type Logger, LogLevel, makeLogger } from '../../logger.js';
+import { errorCause, errorMessage, getTransportHeaders } from '../../utils.js';
 import { registerAgent } from '../agent.js';
+import { resolveChannelModes } from '../channel-options.js';
 import type { Codec, CodecInputEvent, CodecOutputEvent } from '../codec/types.js';
+import { type AgentView, createAgentView } from './agent-view.js';
+import { createWireApplier, type WireApplier } from './decode-fold.js';
 import { buildTransportHeaders } from './headers.js';
 import { evictOldestIfFull } from './internal/bounded-map.js';
 import { Invocation } from './invocation.js';
-import { loadConversation, loadRunProjection } from './load-conversation.js';
 import { pipeStream } from './pipe-stream.js';
 import type { RunManager } from './run-manager.js';
 import { createRunManager } from './run-manager.js';
+import { bestEffortDetach, continuityLostError, isContinuityLost, requireConnected } from './session-support.js';
+import { createTree, type DefaultTree } from './tree.js';
 import type {
   AgentSession,
   AgentSessionOptions,
   CancelRequest,
-  EventsNode,
   LoadConversationOptions,
-  MessageNode,
   PipeOptions,
   Run,
-  RunEndReason,
+  RunEndParams,
   RunRuntime,
   RunView,
   StreamResult,
+  Tree,
 } from './types.js';
 
-// ---------------------------------------------------------------------------
-// Run-state lookup helpers
-// ---------------------------------------------------------------------------
-
 /**
- * Wait for every event-id in `expectedInputEventIds` to arrive as a channel
- * message before letting the run proceed to LLM work. Uses the session's
- * unfiltered channel dispatcher (registered in `connect()`) so that
- * messages replayed via channel rewind on attach reach the lookup — no
- * separate history fetch needed.
- *
- * Scope: this awaits the data-carrying input events a send publishes —
- * fresh prompts, edits, regenerates, tool results, and approvals. Control
- * events (cancel etc.) carry no `event-id`, are dispatched
- * separately, and never enter this lookup.
- *
- * Each client-published event in a send (user-message AND amend events
- * such as tool-approval responses and client tool outputs) is stamped
- * with its own `event-id`.
- * The lookup matches incoming messages against the expected set; ids
- * not in the set are ignored, duplicates (rewind redelivering a message
- * also seen live) are deduped by event-id. The wait completes when
- * every expected id has arrived, guaranteeing the channel state is
- * consistent with what the client promised before any downstream
- * processing (loadProjection, streamText) runs.
- *
- * User-message arrivals decode into MessageNodes that populate
- * `run.view.messages`; amend arrivals fold into a fresh projection that
- * has no target message, so they're orphaned and dropped — they only
- * count toward the wait. Collected nodes are returned sorted by Ably
- * `serial` ascending.
- *
- * Bounded by `timeoutMs` as a total budget across all N arrivals. The
- * caller's `signal` aborts the wait. On partial collection at timeout the
- * promise rejects with `InputEventNotFound` and an error message including
- * "received X of Y". If any decode throws mid-collection, the whole lookup
- * rejects with `InputEventNotFound` wrapping the decode error as cause —
- * already-collected messages are discarded.
- * @param opts - Lookup parameters.
- * @param opts.register - Session-provided registration that delivers the input events for the expected event-ids. Returns an unregister function.
- * @param opts.codec - Codec used to decode arriving messages.
- * @param opts.invocationId - Invocation identifier — used only for diagnostic logging and error messages.
- * @param opts.runId - Run identifier (used for logging and error messages).
- * @param opts.expectedInputEventIds - Input-event ids the lookup must observe before resolving.
- * @param opts.timeoutMs - Maximum total time to wait for all event-id arrivals.
- * @param opts.signal - AbortSignal that cancels the wait when the run is cancelled.
- * @param opts.logger - Optional logger for diagnostic output.
- * @returns The MessageNodes for arriving user-message events (sorted by Ably
- *   serial — empty when every input event was a tool-resolution wire message that
- *   decoded to a chunk and produced no node), and the transport headers of
- *   the first matched wire message. `firstHeaders` is the canonical source for
- *   run-level metadata (clientId, parent, forkOf, continuation flag) because
- *   it lands whether or not the decode produced a MessageNode. `firstClientId`
- *   carries the publisher's Ably-level `clientId` from that same message — the
- *   source of `inputClientId` re-stamping on the agent's published events.
+ * Upper bound on buffered deferred cancels. Deferred cancels are bounded so
+ * a pathological burst can't grow the map without bound. 200 outstanding
+ * fresh-send cancels in flight is ample — a typical agent process sees one
+ * per HTTP request.
  */
-interface InputEventLookupResult<TMessage> {
-  nodes: MessageNode<TMessage>[];
-  firstHeaders?: Record<string, string>;
-  firstClientId?: string;
-  /**
-   * Raw Ably messages observed live for the matched input-event ids, in
-   * arrival order. The agent forwards these to `loadRunProjection` so a
-   * continuation invocation can fold the just-published client wires
-   * (e.g. a tool-output-available) without waiting on Ably's channel
-   * history indexing window.
-   */
-  rawMessages: Ably.InboundMessage[];
-}
-
-const lookupInputEvents = async <
-  TInput extends CodecInputEvent,
-  TOutput extends CodecOutputEvent,
-  TProjection,
-  TMessage,
->(opts: {
-  register: (callback: (msg: Ably.InboundMessage) => void) => () => void;
-  codec: Codec<TInput, TOutput, TProjection, TMessage>;
-  invocationId: string;
-  runId: string;
-  expectedInputEventIds: readonly string[];
-  timeoutMs: number;
-  signal: AbortSignal;
-  logger: Logger | undefined;
-}): Promise<InputEventLookupResult<TMessage>> => {
-  const { register, codec, invocationId, runId, expectedInputEventIds, timeoutMs, signal, logger } = opts;
-  const expectedSet = new Set(expectedInputEventIds);
-  const expectedCount = expectedSet.size;
-
-  const collected: MessageNode<TMessage>[] = [];
-  const rawMessages: Ably.InboundMessage[] = [];
-  const matchedInputEventIds = new Set<string>();
-  let firstHeaders: Record<string, string> | undefined;
-  let firstClientId: string | undefined;
-
-  /**
-   * Decode an inbound Ably message into MessageNodes via the codec.
-   * @param m - The inbound Ably message to decode.
-   * @returns The decoded MessageNodes carrying transport headers and serial.
-   */
-  const decode = (m: Ably.InboundMessage): MessageNode<TMessage>[] => {
-    const decoder = codec.createDecoder();
-    const headers = getTransportHeaders(m);
-    const codecMessageId = headers[HEADER_CODEC_MESSAGE_ID] ?? '';
-    const { inputs, outputs } = decoder.decode(m);
-    const events: (TInput | TOutput)[] = [...inputs, ...outputs];
-    let projection = codec.init();
-    for (const event of events) {
-      projection = codec.fold(projection, event, { serial: m.serial ?? '', messageId: codecMessageId });
-    }
-    return codec.getMessages(projection).map(({ message }) => ({
-      kind: 'message' as const,
-      message,
-      codecMessageId,
-      parentId: headers[HEADER_PARENT],
-      forkOf: headers[HEADER_FORK_OF],
-      headers,
-      serial: m.serial,
-    }));
-  };
-
-  return new Promise<InputEventLookupResult<TMessage>>((resolve, reject) => {
-    let settled = false;
-    // Dedupe across rewind-redelivery: rewind may surface a message the
-    // listener also saw live. Scoped to the active lookup so it cannot
-    // grow unbounded.
-    const seenSerials = new Set<string>();
-    // Forward-declared so that cleanup() and onCancelled() can reference them
-    // before they are assigned. cleanup may run synchronously inside
-    // `register(...)` (when buffered input events drain on registration) before
-    // `unregister`/`timer` have been assigned — the no-op fallback for
-    // unregister and undefined-guard for timer handle that window. The
-    // settled-flag re-check after `register` returns reconciles the
-    // listener-detach that cleanup couldn't perform inside that window.
-    /* eslint-disable prefer-const, unicorn/consistent-function-scoping, @typescript-eslint/no-empty-function -- forward-declared state for the sync-drain reconciliation pattern; see comment above. */
-    let unregister: () => void = () => {};
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    /* eslint-enable */
-    const cleanup = (): void => {
-      unregister();
-      if (timer !== undefined) clearTimeout(timer);
-      signal.removeEventListener('abort', onCancelled);
-    };
-    const onCancelled = (): void => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      reject(
-        new Ably.ErrorInfo(`unable to look up input event; run ${runId} was cancelled`, ErrorCode.InvalidArgument, 400),
-      );
-    };
-    signal.addEventListener('abort', onCancelled, { once: true });
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- onCancelled may have settled the promise synchronously above when the signal was already aborted.
-    if (settled) return;
-    unregister = register((m) => {
-      if (settled) return;
-      if (m.serial !== undefined && seenSerials.has(m.serial)) return;
-      if (m.serial !== undefined) seenSerials.add(m.serial);
-
-      const wireHeaders = getTransportHeaders(m);
-
-      // Only count messages whose event-id is in the expected set.
-      const msgEventId = wireHeaders[HEADER_EVENT_ID];
-      if (!msgEventId || !expectedSet.has(msgEventId) || matchedInputEventIds.has(msgEventId)) return;
-      matchedInputEventIds.add(msgEventId);
-
-      // Capture the trigger event's headers AND its Ably channel-level `clientId`
-      // so run-level metadata (parent / forkOf / continuation flag from headers;
-      // `inputClientId` from the wire publisher) is available even when the decode
-      // produces zero MessageNodes — the case for continuation tool-resolution
-      // trigger events whose chunks fold into a fresh empty projection without
-      // an assistant to land on.
-      if (firstHeaders === undefined) {
-        firstHeaders = wireHeaders;
-        firstClientId = m.clientId;
-      }
-
-      let decoded: MessageNode<TMessage>[];
-      try {
-        decoded = decode(m);
-      } catch (error) {
-        settled = true;
-        cleanup();
-        const cause = error instanceof Ably.ErrorInfo ? error : undefined;
-        reject(
-          new Ably.ErrorInfo(
-            `unable to look up input event; decode failed for invocation ${invocationId}: ${error instanceof Error ? error.message : String(error)}`,
-            ErrorCode.InputEventNotFound,
-            504,
-            cause,
-          ),
-        );
-        return;
-      }
-      for (const node of decoded) collected.push(node);
-      rawMessages.push(m);
-      if (matchedInputEventIds.size < expectedCount) return;
-      settled = true;
-      cleanup();
-      // Sort by Ably serial ascending so callers see publish order regardless
-      // of interleaved rewind+live delivery. Null serials sort last (defensive
-      // — input events should always carry a serial).
-      collected.sort(compareBySerial);
-      logger?.debug('lookupInputEvents(); collected input events', {
-        runId,
-        invocationId,
-        count: collected.length,
-      });
-      resolve({ nodes: collected, firstHeaders, firstClientId, rawMessages });
-    });
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- the register callback may have settled the promise synchronously during buffered input-event drain.
-    if (settled) {
-      // Sync drain inside register settled the promise; cleanup ran but
-      // could not detach the listener because `unregister` was still the
-      // no-op. Detach it now.
-      unregister();
-      return;
-    }
-    timer = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      reject(
-        new Ably.ErrorInfo(
-          `unable to look up input event; received ${String(collected.length)} of ${String(expectedCount)} input events for invocation ${invocationId} within ${String(timeoutMs)}ms`,
-          ErrorCode.InputEventNotFound,
-          504,
-        ),
-      );
-    }, timeoutMs);
-  });
-};
+const DEFERRED_CANCEL_LIMIT = 200;
 
 // ---------------------------------------------------------------------------
 // Internal run record for cancel routing
@@ -325,7 +104,7 @@ class DefaultAgentSession<
   TMessage,
 > implements AgentSession<TOutput, TProjection, TMessage> {
   private readonly _channel: Ably.RealtimeChannel;
-  private readonly _codec: AgentSessionOptions<TInput, TOutput, TProjection, TMessage>['codec'];
+  private readonly _codec: Codec<TInput, TOutput, TProjection, TMessage>;
   private readonly _logger: Logger | undefined;
   private readonly _onError: ((error: Ably.ErrorInfo) => void) | undefined;
   private readonly _runManager: RunManager;
@@ -347,33 +126,39 @@ class DefaultAgentSession<
    * keyed by the input codec-message-id, and the `inputCodecMessageId → run`
    * linkage doesn't exist until the lookup completes. `Run.start()` consults
    * this buffer as a PULL once it resolves its `resolvedInputCodecMessageId`,
-   * honouring any cancel that arrived first. Mirrors `_inputEventBuffer`: FIFO
-   * eviction at `_inputEventBufferLimit` entries, cleared on `close()`.
+   * honouring any cancel that arrived first. Cleared on `close()`.
    */
   private readonly _deferredCancels = new Map<string, Ably.InboundMessage>();
   /**
-   * Active input-event lookups keyed by `event-id`. The channel listener
-   * dispatches each input event to the lookup that registered for its
-   * `event-id`, so that messages replayed via channel rewind (and live
-   * messages alike) reach the right lookup without each lookup having to
-   * subscribe separately, and without depending on a client-minted
-   * `invocation-id`.
+   * Session-owned materialisation tree. Every message (live + history) folds
+   * through `this._applier.apply(msg)`; conversation state is read by
+   * walking parent pointers from the input node.
+   *
+   * Replaced (not cleared in place) on channel continuity loss so that the
+   * fresh tree starts empty. The old tree is abandoned to GC once in-flight
+   * lookups have aborted.
+   */
+  private _tree: DefaultTree<TInput, TOutput, TProjection>;
+  /**
+   * The Tree's single decode-and-apply engine, binding one inbound decoder
+   * instance shared by every fold route (live + history). Streaming across
+   * pages folds correctly because the decoder keeps stream-tracker state
+   * across messages. Replaced alongside the Tree on continuity loss so the
+   * fresh Tree gets a fresh decoder. Outbound encoders (used by `Run.pipe`)
+   * manage their own decoders.
    */
-  private readonly _pendingInputEventLookups = new Map<string, (msg: Ably.InboundMessage) => void>();
+  private _applier: WireApplier;
   /**
-   * Input events buffered by `event-id` when no lookup callback was
-   * registered at delivery time. Rewind replays user messages on attach —
-   * before `run.start()` runs — so without buffering they would be dropped.
-   * Each `event-id` maps to an ordered array so rewind redelivery of the
-   * same event before registration is preserved (the lookup later dedupes by
-   * serial). `_registerInputEventListener` drains the buffer on registration.
-   * FIFO eviction at `_inputEventBufferLimit` event entries (each entry counts
-   * once regardless of array length).
+   * Internal server-side view: input-event lookup + conversation loading over
+   * the session Tree. Holds the Tree/applier directly (like the client's
+   * DefaultView), so it is RECREATED — not mutated — when the Tree is swapped
+   * on continuity loss.
    */
-  private readonly _inputEventBuffer = new Map<string, Ably.InboundMessage[]>();
-  private readonly _inputEventBufferLimit: number;
+  private _agentView: AgentView<TInput, TOutput, TProjection, TMessage>;
   private readonly _channelListener: (msg: Ably.InboundMessage) => void;
   private readonly _inputEventLookupTimeoutMs: number;
+  /** Lookback bound passed to the AgentView's input-event scan (see {@link _createAgentView}). */
+  private readonly _inputEventLookbackMs: number;
 
   private _state = SessionState.READY;
   private _connectPromise: Promise<void> | undefined;
@@ -386,20 +171,22 @@ class DefaultAgentSession<
     // (options.agents) and channel-attach (params.agent) paths. Idempotent
     // across sessions sharing one client.
     const registerOptions = registerAgent(options.client, options.codec);
-    // Attach with a rewind window (default 2m) so a freshly-constructed
-    // agent session can locate an input event that was published before it
-    // attached (closes the lookup race when a per-request agent is spun
-    // up after the client has already POSTed). Tunable via
-    // `AgentSessionOptions.rewindWindow`.
-    const channelOptions: Ably.ChannelOptions = {
-      params: { ...registerOptions.params, rewind: options.rewindWindow ?? '2m' },
-    };
+    const channelOptions: Ably.ChannelOptions = { ...registerOptions };
+    // Spec: AIT-ST16 — request object modes etc. when channelModes opts in.
+    const modes = resolveChannelModes(options.channelModes);
+    if (modes) channelOptions.modes = modes;
     this._channel = options.client.channels.get(options.channelName, channelOptions);
     this._logger = options.logger?.withContext({ component: 'AgentSession' });
     this._onError = options.onError;
     this._runManager = createRunManager(this._channel, this._logger);
     this._inputEventLookupTimeoutMs = options.inputEventLookupTimeoutMs ?? 30000;
-    this._inputEventBufferLimit = options.inputEventBufferLimit ?? 200;
+    this._inputEventLookbackMs = options.inputEventLookbackMs ?? 120_000;
+    this._tree = createTree<TInput, TOutput, TProjection>(
+      this._codec,
+      this._logger ?? makeLogger({ logLevel: LogLevel.Silent }),
+    );
+    this._applier = createWireApplier(this._tree, this._codec.createDecoder());
+    this._agentView = this._createAgentView();
 
     this._channelListener = (msg: Ably.InboundMessage) => {
       this._handleChannelMessage(msg);
@@ -421,6 +208,38 @@ class DefaultAgentSession<
     this._logger?.debug('DefaultAgentSession(); session created');
   }
 
+  /**
+   * Build an AgentView bound to the session's CURRENT Tree + applier. Called at
+   * construction and again after a continuity-loss swap — the AgentView holds
+   * the Tree/applier directly (like DefaultView), so a swap recreates it rather
+   * than mutating it in place.
+   * @returns A fresh AgentView over the current Tree/applier.
+   */
+  private _createAgentView(): AgentView<TInput, TOutput, TProjection, TMessage> {
+    return createAgentView<TInput, TOutput, TProjection, TMessage>({
+      tree: this._tree,
+      channel: this._channel,
+      codec: this._codec,
+      applier: this._applier,
+      logger: this._logger,
+      inputEventLookbackMs: this._inputEventLookbackMs,
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Public accessors
+  // -------------------------------------------------------------------------
+
+  // Spec: AIT-ST14
+  get presence(): Ably.RealtimePresence {
+    return this._channel.presence;
+  }
+
+  // Spec: AIT-ST15
+  get object(): AblyObjects.RealtimeObject {
+    return this._channel.object;
+  }
+
   // -------------------------------------------------------------------------
   // Public API
   // -------------------------------------------------------------------------
@@ -435,22 +254,19 @@ class DefaultAgentSession<
 
     this._logger?.trace('DefaultAgentSession.connect();');
     // Subscribe unfiltered (before attach, per RTL7g — subscribe implicitly
-    // attaches the channel). An unfiltered subscribe ensures that messages
-    // replayed via channel rewind reach the dispatcher so input-event
-    // lookups can match against them; the dispatcher then routes by name
-    // (cancel vs. input event). A name-filtered subscribe would silently
-    // drop replayed user messages because rewind delivers them to listeners
-    // registered at attach time only.
+    // attaches the channel). Unfiltered so the Tree folds every post-attach
+    // message regardless of name (cancel control messages are dispatched
+    // separately by the channel listener after the Tree fold).
     this._connectPromise = this._channel.subscribe(this._channelListener).then(
       () => {
         this._logger?.debug('DefaultAgentSession.connect(); subscribed and attached');
       },
       (error: unknown) => {
         const errInfo = new Ably.ErrorInfo(
-          `unable to subscribe to channel; ${error instanceof Error ? error.message : String(error)}`,
+          `unable to subscribe to channel; ${errorMessage(error)}`,
           ErrorCode.SessionSubscriptionError,
           500,
-          error instanceof Ably.ErrorInfo ? error : undefined,
+          errorCause(error),
         );
         this._logger?.error('DefaultAgentSession.connect(); subscribe failed');
         this._onError?.(errInfo);
@@ -461,47 +277,12 @@ class DefaultAgentSession<
   }
 
   /**
-   * Register a callback to receive the input events carrying any of the
-   * given `eventIds`. Lookups must share the session's unfiltered
-   * subscription rather than registering their own subscribe — Ably's
-   * rewind only delivers to listeners present at attach time.
-   *
-   * The listener remains registered after the initial buffer drain so a
-   * matching event that arrives live (rather than from the buffer) still
-   * reaches the lookup until it unregisters itself. Today the only caller
-   * registers a single trigger event-id; the array form keeps the
-   * registration capable of awaiting several ids without changing callers.
-   * @param eventIds - The `event-id`s this listener cares about.
-   * @param callback - Invoked once per matching Ably message, in buffer-insertion order for drained entries.
-   * @returns Unregister function. Safe to call multiple times.
+   * The session-owned materialisation tree. Mirrors `ClientSession.tree`
+   * for observability and parity.
+   * @returns The session's Tree.
    */
-  private _registerInputEventListener(
-    eventIds: readonly string[],
-    callback: (msg: Ably.InboundMessage) => void,
-  ): () => void {
-    for (const eventId of eventIds) {
-      this._pendingInputEventLookups.set(eventId, callback);
-    }
-    // Drain any buffered input events for these event-ids — rewind replays
-    // user messages on attach before run.start() can register the callback.
-    // Without this drain, the lookup waits the full
-    // `inputEventLookupTimeoutMs` for a live arrival that never comes. Set
-    // all listeners before draining so a drain that completes the lookup
-    // synchronously cannot leave a later event-id unmapped.
-    for (const eventId of eventIds) {
-      const buffered = this._inputEventBuffer.get(eventId);
-      if (buffered) {
-        this._inputEventBuffer.delete(eventId);
-        for (const m of buffered) callback(m);
-      }
-    }
-    return () => {
-      for (const eventId of eventIds) {
-        if (this._pendingInputEventLookups.get(eventId) === callback) {
-          this._pendingInputEventLookups.delete(eventId);
-        }
-      }
-    };
+  get tree(): Tree<TOutput, TProjection> {
+    return this._tree;
   }
 
   // Spec: AIT-ST3
@@ -525,23 +306,9 @@ class DefaultAgentSession<
     this._registeredRuns.clear();
     this._runIdByInputCodecMessageId.clear();
     this._deferredCancels.clear();
-    this._pendingInputEventLookups.clear();
-    this._inputEventBuffer.clear();
     this._runManager.close();
 
-    // Detach the channel this session attached. connect() subscribes (which
-    // implicitly attaches), so we only detach when connect() ran. Best-effort:
-    // a detach failure (e.g. the channel is already FAILED) must not throw out
-    // of close().
-    if (this._connectPromise) {
-      try {
-        await this._channel.detach();
-      } catch (error) {
-        // Swallowed (see above): a detach failure must not throw out of
-        // close(). Logged at debug for observability.
-        this._logger?.debug('DefaultAgentSession.close(); channel detach failed', { error });
-      }
-    }
+    await bestEffortDetach(this._channel, this._connectPromise, this._logger, 'DefaultAgentSession');
 
     this._logger?.debug('DefaultAgentSession.close(); session closed');
   }
@@ -593,17 +360,17 @@ class DefaultAgentSession<
   /**
    * Buffer a cancel that arrived before its target run was known, keyed by the
    * triggering input's codec-message-id. FIFO-evicts the oldest entry at
-   * `_inputEventBufferLimit` (mirroring `_inputEventBuffer`). A later cancel
-   * for the same input replaces the earlier one — the intent is identical.
+   * {@link DEFERRED_CANCEL_LIMIT}. A later cancel for the same input replaces the earlier
+   * one — the intent is identical.
    * @param inputCodecMessageId - The triggering input's codec-message-id.
    * @param msg - The raw cancel message (passed to `onCancel`).
    */
   private _bufferDeferredCancel(inputCodecMessageId: string, msg: Ably.InboundMessage): void {
-    const evicted = evictOldestIfFull(this._deferredCancels, inputCodecMessageId, this._inputEventBufferLimit);
+    const evicted = evictOldestIfFull(this._deferredCancels, inputCodecMessageId, DEFERRED_CANCEL_LIMIT);
     if (evicted !== undefined) {
       this._logger?.warn('DefaultAgentSession._bufferDeferredCancel(); deferred-cancel buffer full, dropping oldest', {
         evictedInputCodecMessageId: evicted,
-        limit: this._inputEventBufferLimit,
+        limit: DEFERRED_CANCEL_LIMIT,
       });
     }
     this._deferredCancels.set(inputCodecMessageId, msg);
@@ -661,10 +428,10 @@ class DefaultAgentSession<
       this._logger?.debug('DefaultAgentSession._cancelRegistration(); run cancelled', { runId });
     } catch (error) {
       const errInfo = new Ably.ErrorInfo(
-        `unable to process cancel for run ${runId}; onCancel handler threw: ${error instanceof Error ? error.message : String(error)}`,
+        `unable to process cancel for run ${runId}; onCancel handler threw: ${errorMessage(error)}`,
         ErrorCode.CancelListenerError,
         500,
-        error instanceof Ably.ErrorInfo ? error : undefined,
+        errorCause(error),
       );
       this._logger?.error('DefaultAgentSession._cancelRegistration(); onCancel threw', { runId });
       (reg.onError ?? this._onError)?.(errInfo);
@@ -681,19 +448,13 @@ class DefaultAgentSession<
 
     const { current, resumed } = stateChange;
 
-    // Track the initial attach so we don't treat it as a discontinuity
+    // Track the initial attach so we don't treat it as a discontinuity.
     if (current === 'attached' && !this._hasAttachedOnce) {
       this._hasAttachedOnce = true;
       return;
     }
 
-    // Continuity-breaking states:
-    // - FAILED, SUSPENDED, DETACHED: no more messages expected (or gap)
-    // - ATTACHED with resumed: false (UPDATE): messages were lost
-    const continuityLost =
-      current === 'failed' || current === 'suspended' || current === 'detached' || (current === 'attached' && !resumed);
-
-    if (!continuityLost) return;
+    if (!isContinuityLost(stateChange)) return;
 
     this._logger?.error('DefaultAgentSession._handleChannelStateChange(); channel continuity lost', {
       current,
@@ -701,18 +462,59 @@ class DefaultAgentSession<
       previous: stateChange.previous,
     });
 
-    const err = new Ably.ErrorInfo(
-      `unable to deliver cancel messages; channel continuity lost (${current}${current === 'attached' ? ', resumed: false' : ''})`,
-      ErrorCode.ChannelContinuityLost,
-      500,
-      stateChange.reason,
+    const continuityErr = continuityLostError(stateChange, 'continue');
+
+    // Abort every active run's controller FIRST so in-flight
+    // `loadConversation` / `findInputEvent` calls observe the abort before
+    // the Tree changes underneath them and reject (InvalidArgument from their
+    // signal checks; the session-level onError carries ChannelContinuityLost).
+    for (const reg of this._registeredRuns.values()) {
+      reg.controller.abort();
+    }
+
+    // Then swap the Tree for a fresh empty instance — abandons the old
+    // Tree's projections, indices, and ably-message listeners to GC. New
+    // runs use the fresh Tree; lingering closures on the old Tree from
+    // in-flight (now-aborted) lookups are bounded by the abort propagation.
+    this._tree = createTree<TInput, TOutput, TProjection>(
+      this._codec,
+      this._logger ?? makeLogger({ logLevel: LogLevel.Silent }),
     );
+    this._applier = createWireApplier(this._tree, this._codec.createDecoder());
+    // The AgentView holds the Tree/applier directly, so rebuild it against the
+    // fresh pair — this also resets its cursor and exhaustion state.
+    this._agentView = this._createAgentView();
 
-    // Session-level notification only: continuity loss is not scoped to any
+    // Session-level notification: continuity loss is not scoped to any one
     // run. Per-run onError handlers are reserved for errors from that run's
-    // own operations (publish failures, encoder errors). Developers that need
-    // per-run reaction can iterate active runs from the session handler.
-    this._onError?.(err);
+    // own operations (publish failures, encoder errors).
+    this._onError?.(continuityErr);
+  }
+
+  // -------------------------------------------------------------------------
+  // Wire fold
+  // -------------------------------------------------------------------------
+
+  /**
+   * Fold a single wire message into the session-owned Tree. Mirrors the
+   * ClientSession's live decode loop — same engine, same fold path. The
+   * applier decodes the message and applies the result to the Tree (or
+   * routes lifecycle messages through `applyRunLifecycle`);
+   * `emitAblyMessage` notifies Tree subscribers AND populates the event-id
+   * index used by the AgentView's input-event lookup.
+   *
+   * A message that surfaces via more than one path (the live listener and
+   * the AgentView's history walk) does not
+   * double-fold: the shared decoder's version-guarded trackers drop
+   * re-delivered stream content, and the Tree's per-entry `decodedThrough`
+   * high-water-mark drops whole-wire replays (including stateless discrete
+   * re-decodes) at the correct per-delivery granularity — same-serial live
+   * appends each carry their own version and fold exactly once.
+   * @param wire - The inbound Ably message to fold.
+   */
+  private _foldWire(wire: Ably.InboundMessage): void {
+    this._applier.apply(wire);
+    this._tree.emitAblyMessage(wire);
   }
 
   // -------------------------------------------------------------------------
@@ -721,67 +523,31 @@ class DefaultAgentSession<
 
   private _handleChannelMessage(msg: Ably.InboundMessage): void {
     try {
+      // Fold first (re-delivered content is dropped by the shared decoder's
+      // version guard and the Tree's replay guard), then dispatch cancel
+      // control messages.
+      this._foldWire(msg);
+
       if (msg.name === EVENT_CANCEL) {
         // Fire-and-forget async handler — errors are caught internally.
         this._handleCancelMessage(msg).catch((error: unknown) => {
           const errInfo = new Ably.ErrorInfo(
-            `unable to route cancel message; ${error instanceof Error ? error.message : String(error)}`,
+            `unable to route cancel message; ${errorMessage(error)}`,
             ErrorCode.CancelListenerError,
             500,
-            error instanceof Ably.ErrorInfo ? error : undefined,
+            errorCause(error),
           );
           this._logger?.error('DefaultAgentSession._handleChannelMessage(); cancel routing error');
           this._onError?.(errInfo);
         });
         return;
       }
-
-      // Dispatch client-published input events to the lookup registered
-      // for their `event-id`. Every client-originated event in an
-      // invocation (user-message AND amend events such as tool-approval
-      // responses and client tool outputs) carries `event-id`; the lookup
-      // waits for every promised id to arrive before letting the run start
-      // LLM work. Routing by `event-id` rather than `invocation-id` keeps
-      // the dispatcher independent of any client-minted invocation
-      // identity. Server-side lifecycle messages (run-start, run-end,
-      // cancel, error) never stamp `event-id`, so they're naturally
-      // excluded.
-      const headers = getTransportHeaders(msg);
-      const eventId = headers[HEADER_EVENT_ID];
-      if (eventId !== undefined) {
-        const listener = this._pendingInputEventLookups.get(eventId);
-        if (listener) {
-          listener(msg);
-        } else {
-          // Buffer for a future `_registerInputEventListener` call. This is
-          // load-bearing for the "agent attaches after publish" scenario
-          // where channel rewind delivers user messages before
-          // `run.start()` runs.
-          const existing = this._inputEventBuffer.get(eventId);
-          if (existing) {
-            existing.push(msg);
-          } else {
-            // FIFO eviction: drop the oldest event entry (and all its buffered
-            // redeliveries). Clients whose input event was evicted will fail
-            // their lookup with `InputEventNotFound` — this warn is the only
-            // operator-visible signal that capacity caused the failure.
-            const evicted = evictOldestIfFull(this._inputEventBuffer, eventId, this._inputEventBufferLimit);
-            if (evicted !== undefined) {
-              this._logger?.warn(
-                'DefaultAgentSession._handleChannelMessage(); input-event buffer full, dropping oldest entry',
-                { evictedEventId: evicted, limit: this._inputEventBufferLimit },
-              );
-            }
-            this._inputEventBuffer.set(eventId, [msg]);
-          }
-        }
-      }
     } catch (error) {
       const errInfo = new Ably.ErrorInfo(
-        `unable to process channel message; ${error instanceof Error ? error.message : String(error)}`,
+        `unable to process channel message; ${errorMessage(error)}`,
         ErrorCode.SessionSubscriptionError,
         500,
-        error instanceof Ably.ErrorInfo ? error : undefined,
+        errorCause(error),
       );
       this._logger?.error('DefaultAgentSession._handleChannelMessage(); subscription error');
       this._onError?.(errInfo);
@@ -793,14 +559,7 @@ class DefaultAgentSession<
   // -------------------------------------------------------------------------
 
   private async _requireConnected(method: string): Promise<void> {
-    if (!this._connectPromise) {
-      throw new Ably.ErrorInfo(
-        `unable to ${method}; connect() must be called before ${method}()`,
-        ErrorCode.InvalidArgument,
-        400,
-      );
-    }
-    return this._connectPromise;
+    return requireConnected(this._connectPromise, method);
   }
 
   // -------------------------------------------------------------------------
@@ -812,9 +571,15 @@ class DefaultAgentSession<
     // Mint a provisional id now (or take the `runtime.runId` override for
     // tests / in-process drivers) — this IS the id for a fresh run. A
     // continuation overrides it in `Run.start()` with the existing run-id read
-    // off the triggering input event's wire headers (the run it re-enters).
+    // off the triggering input event's message headers (the run it re-enters).
     // Mirrors the invocationId mint below.
     let runId = runtime.runId ?? crypto.randomUUID();
+    // Whether the run-id was supplied via the runtime override. Together with
+    // `resolvedContinuation` (set in start() when the triggering input carries
+    // a wire run-id) this decides whether the id is "adopted" — an adopted id
+    // can name a run that already exists in channel history; a freshly-minted
+    // UUID cannot, so hydration must not demand its node from history.
+    const runIdOverridden = runtime.runId !== undefined;
     // The agent mints the invocation id — one per HTTP request that invokes
     // it. A per-run override (runtime.invocationId) supports deterministic ids
     // in tests and in-process drivers.
@@ -854,29 +619,18 @@ class DefaultAgentSession<
     const runIdByInputCodecMessageId = this._runIdByInputCodecMessageId;
     const deferredCancels = this._deferredCancels;
     const requireConnected = this._requireConnected.bind(this);
-    const registerInputEventListener = this._registerInputEventListener.bind(this);
+    // Live accessor (not a captured ref): a continuity-loss swap recreates the
+    // AgentView, and reads after the swap must observe the fresh instance.
+    const getAgentView = (): AgentView<TInput, TOutput, TProjection, TMessage> => this._agentView;
     const pullDeferredCancel = this._pullDeferredCancel.bind(this);
     const inputEventId = invocation.inputEventId;
 
-    // `viewMessages` starts empty. `Run.start()` populates it via the
-    // channel-rewind input-event lookup, pulling in user-message MessageNodes
-    // as they arrive on the channel.
-    const viewMessages: MessageNode<TMessage>[] = [];
-    const view: RunView<TMessage> = {
-      get messages() {
-        return viewMessages;
-      },
-    };
-
     // Per-run metadata resolved from the input-event lookup result. The first
-    // matched wire message's headers carry the run's `clientId`, `parent`, and
+    // matched message message's headers carry the run's `clientId`, `parent`, and
     // `forkOf`, and — for a continuation — the `run-id` it re-enters (a fresh
     // input carries none; the client stamps a run-id only when re-entering a
     // run it already knows). Its Ably-level publisher `clientId` becomes the
-    // `inputClientId` re-stamped on the agent's own publishes. Captured
-    // separately from `viewMessages` because tool-resolution wire messages
-    // (`tool-output-available` etc.) decode to chunks and produce zero
-    // MessageNodes — the metadata still needs to surface.
+    // `inputClientId` re-stamped on the agent's own publishes.
     let resolvedClientId: string | undefined;
     let resolvedInputClientId: string | undefined;
     let resolvedParent: string | undefined;
@@ -885,23 +639,47 @@ class DefaultAgentSession<
     let resolvedInputCodecMessageId: string | undefined;
     let resolvedContinuation = false;
     let firstLookupHeaders: Record<string, string> | undefined;
+
+    // `Run.view.messages` is a LIVE read against the session's Tree:
+    // returns the trigger node's currently-folded messages, reflecting any
+    // amendments (tool resolutions etc.) that have arrived since
+    // `Run.start()`. No internal `viewMessages` array — the Tree is the
+    // single source of truth. The trigger node may be an input node (fresh
+    // send) or a reply run (continuation re-entry with run-id on the
+    // triggering message); both expose a projection the codec can read.
+    //
+    // Resolved via an arrow accessor so the closure picks up `this._tree`
+    // after a continuity-loss swap; capturing `this._tree` into a local at
+    // run-creation time would silently keep returning data from the
+    // abandoned Tree.
+    const getTree = (): DefaultTree<TInput, TOutput, TProjection> => this._tree;
+    const view: RunView<TMessage> = {
+      get messages() {
+        if (resolvedInputCodecMessageId === undefined) return [];
+        const node = getTree().getNodeByCodecMessageId(resolvedInputCodecMessageId);
+        if (!node) return [];
+        const sourceSerial = node.kind === 'input' ? node.serial : node.startSerial;
+        const sourceForkOf = node.kind === 'input' ? node.forkOf : undefined;
+        return codec.getMessages(node.projection).map((m) => ({
+          kind: 'message' as const,
+          message: m.message,
+          codecMessageId: m.codecMessageId,
+          parentId: node.parentCodecMessageId,
+          forkOf: sourceForkOf,
+          headers: {},
+          serial: sourceSerial,
+        }));
+      },
+    };
     /**
      * The reply run's structural-parent fallback, computed once in
-     * `Run.start()` (after the input-event lookup has populated `viewMessages`)
-     * and consumed by every `Run.pipe()` publish. A per-stream
-     * `streamOpts.parent` still overrides it. Storing it here keeps it stable
-     * across pipes and decouples the assistant's structural parent from the
-     * run-start wire's own `parent`.
+     * `Run.start()` once the input-event lookup resolves the triggering
+     * input's codec-message-id, and consumed by every `Run.pipe()` publish.
+     * A per-stream `streamOpts.parent` still overrides it. Storing it here
+     * keeps it stable across pipes and decouples the assistant's structural
+     * parent from the run-start message's own `parent`.
      */
     let assistantParentFallback: string | undefined;
-    /**
-     * Raw Ably messages observed live by the input-event lookup. Passed to
-     * `loadRunProjection` so the just-published client wires don't need
-     * to wait on Ably's channel history indexing window. Empty when no
-     * lookup ran or no messages matched.
-     */
-    let liveLookupMessages: readonly Ably.InboundMessage[] | undefined;
-
     /**
      * Remove this run from the session's routing maps. Drops the
      * `_registeredRuns` entry plus the `input-codec-message-id → run-id`
@@ -917,17 +695,33 @@ class DefaultAgentSession<
       }
     };
 
-    // Most recently loaded projection for this run only, cached by
-    // `Run.loadProjection()` and `Run.loadConversation()` so the `messages`
-    // getter can return the run's folded messages. `undefined` before any
-    // load call; the getter then falls back to the live `viewMessages`.
-    let cachedProjection: TProjection | undefined;
-
-    // Full multi-turn conversation, set by `Run.loadConversation()`. When set,
-    // it takes priority over `cachedProjection` in the `messages` getter —
-    // the getter then returns the complete ancestor-chain + current-run
-    // messages instead of the current run alone.
-    let cachedConversation: TMessage[] | undefined;
+    /**
+     * Run a run-lifecycle publish (run-start / run-suspend / run-end) and wrap
+     * any failure as a `RunLifecycleError`, logging at error and rethrowing.
+     * Shared by start(), suspend(), and end() so the three publishes can't
+     * drift on the error code, message shape, or cause preservation.
+     * @param phase - The lifecycle wire phase, used in the error message.
+     * @param method - The Run method name, used in the log prefix.
+     * @param publish - The RunManager publish to run.
+     */
+    const publishLifecycle = async (
+      phase: 'run-start' | 'run-suspend' | 'run-end',
+      method: 'start' | 'suspend' | 'end',
+      publish: () => Promise<void>,
+    ): Promise<void> => {
+      try {
+        await publish();
+      } catch (error) {
+        const errInfo = new Ably.ErrorInfo(
+          `unable to publish ${phase} for run ${runId}; ${errorMessage(error)}`,
+          ErrorCode.RunLifecycleError,
+          500,
+          errorCause(error),
+        );
+        logger?.error(`Run.${method}(); failed to publish ${phase}`, { runId });
+        throw errInfo;
+      }
+    };
 
     const run: Run<TOutput, TProjection, TMessage> = {
       get runId() {
@@ -943,13 +737,18 @@ class DefaultAgentSession<
         return view;
       },
       get messages() {
-        if (cachedConversation !== undefined) {
-          return [...cachedConversation];
-        }
-        if (cachedProjection !== undefined) {
-          return codec.getMessages(cachedProjection).map((m) => m.message);
-        }
-        return viewMessages.map((n) => n.message);
+        // Always derive live from the Tree via the AgentView. Walks the parent
+        // chain from the run's structural-parent anchor and concatenates each
+        // ancestor's projection, then appends the current reply run's messages
+        // at the tail. Uses `assistantParentFallback` (which falls back to the
+        // input message's `parent` for regenerate carriers whose own
+        // codec-message-id has no Tree node) — same anchor `loadConversation`
+        // uses, and passes `resolvedRegenerates` so a regenerate's history
+        // stops before the message being replaced. No cache: every read
+        // reflects the latest folded state. `getAgentView()` dereferences the
+        // live AgentView so a continuity-loss swap is observed instead of
+        // returning stale data from the abandoned tree.
+        return getAgentView().messages(runId, assistantParentFallback, resolvedRegenerates);
       },
 
       // Spec: AIT-ST4, AIT-ST4a, AIT-ST4b
@@ -976,26 +775,21 @@ class DefaultAgentSession<
         // when no inputEventId is set (invocation requires no channel lookup).
         if (inputEventId && inputEventLookupTimeoutMs > 0) {
           try {
-            const found = await lookupInputEvents<TInput, TOutput, TProjection, TMessage>({
-              register: (callback) => registerInputEventListener([inputEventId], callback),
-              codec,
+            const found = await getAgentView().findInputEvent({
               invocationId,
               runId,
-              expectedInputEventIds: [inputEventId],
+              expectedEventIds: [inputEventId],
               timeoutMs: inputEventLookupTimeoutMs,
               signal,
-              logger,
             });
-            for (const m of found.nodes) viewMessages.push(m);
             if (found.firstHeaders !== undefined) firstLookupHeaders = found.firstHeaders;
             if (found.firstClientId !== undefined) resolvedInputClientId = found.firstClientId;
-            liveLookupMessages = found.rawMessages;
           } catch (error) {
             const errInfo =
               error instanceof Ably.ErrorInfo
                 ? error
                 : new Ably.ErrorInfo(
-                    `unable to look up input event; ${error instanceof Error ? error.message : String(error)}`,
+                    `unable to look up input event; ${errorMessage(error)}`,
                     ErrorCode.InputEventNotFound,
                     504,
                   );
@@ -1010,16 +804,14 @@ class DefaultAgentSession<
           }
         }
 
-        // Resolve per-run metadata from the first matched wire message's
+        // Resolve per-run metadata from the first matched message message's
         // headers — they carry `clientId`, `parent`, and `forkOf`.
         // Continuations of a suspended run pick up the suspended assistant's
-        // parent in the same headers (the continuation wire message parents off
+        // parent in the same headers (the continuation message parents off
         // the assistant). A `run-id` on the triggering input marks a
         // continuation (re-entry via `ai-run-resume`); a fresh input carries
-        // none and opens the run with `ai-run-start`. Fall back to the first
-        // MessageNode's headers for the path where the lookup ran with
-        // `viewMessages` already populated and no `firstHeaders` was captured.
-        const sourceHeaders = firstLookupHeaders ?? viewMessages[0]?.headers;
+        // none and opens the run with `ai-run-start`.
+        const sourceHeaders = firstLookupHeaders;
         if (sourceHeaders) {
           resolvedClientId = sourceHeaders[HEADER_RUN_CLIENT_ID];
           resolvedParent = sourceHeaders[HEADER_PARENT];
@@ -1043,12 +835,17 @@ class DefaultAgentSession<
           }
         }
 
-        // Compute the reply run's structural-parent fallback now that the
-        // lookup has populated `viewMessages`: the triggering user message,
-        // or — for regenerate wires that match by inputEventId but produce no
-        // MessageNodes — the input wire's own `parent`. `Run.pipe()` consumes
-        // this for every assistant publish.
-        assistantParentFallback = viewMessages.at(-1)?.codecMessageId ?? resolvedParent;
+        // Compute the reply run's structural-parent fallback: the triggering
+        // user message's codec-message-id ONLY if that codec-message-id is
+        // backed by a real node in the Tree (i.e. the message decoded into at
+        // least one input event); otherwise — for regenerate carriers that
+        // are wire-only signals with no input events — fall back to the
+        // input message's own `parent` header.
+        assistantParentFallback =
+          resolvedInputCodecMessageId !== undefined &&
+          this._tree.getNodeByCodecMessageId(resolvedInputCodecMessageId) !== undefined
+            ? resolvedInputCodecMessageId
+            : resolvedParent;
 
         // The triggering input's codec-message-id is now resolved, so the
         // `input-codec-message-id → run` linkage exists: index it for live
@@ -1062,11 +859,11 @@ class DefaultAgentSession<
           await pullDeferredCancel(registration, resolvedInputCodecMessageId);
         }
 
-        try {
-          await runManager.startRun(runId, resolvedClientId, controller, {
+        await publishLifecycle('run-start', 'start', async () =>
+          runManager.startRun(runId, resolvedClientId, controller, {
             // Stamp the reply run's STRUCTURAL parent (its input node, M_user) —
-            // the same value the output path stamps — not the input wire's own
-            // parent. Makes `parent` structural on every wire so the Tree's two
+            // the same value the output path stamps — not the input message's own
+            // parent. Makes `parent` structural on every message so the Tree's two
             // creation paths agree regardless of arrival order. Valid only now
             // that M_user is a separate input node (the two-node flip).
             parent: assistantParentFallback,
@@ -1076,105 +873,48 @@ class DefaultAgentSession<
             inputClientId: resolvedInputClientId,
             inputCodecMessageId: resolvedInputCodecMessageId,
             continuation: resolvedContinuation,
+          }),
+        );
+
+        // Optimistically insert the fresh run's node into the session Tree so
+        // reads that follow start() (loadConversation, Run.messages) see the
+        // run immediately rather than depending on the channel echo of the
+        // run-start just published. The echo (or a history fold) reconciles
+        // through the Tree's run-start handling, promoting startSerial onto
+        // this serial-less node. Continuations re-enter an existing run via
+        // run-resume, which creates no structure — their node comes from
+        // history hydration instead.
+        if (!resolvedContinuation) {
+          getTree().applyRunLifecycle({
+            type: 'start',
+            runId,
+            clientId: resolvedClientId ?? '',
+            serial: undefined,
+            invocationId,
+            ...(assistantParentFallback !== undefined && { parent: assistantParentFallback }),
+            ...(resolvedForkOf !== undefined && { forkOf: resolvedForkOf }),
+            ...(resolvedRegenerates !== undefined && { regenerates: resolvedRegenerates }),
           });
-        } catch (error) {
-          const errInfo = new Ably.ErrorInfo(
-            `unable to publish run-start for run ${runId}; ${error instanceof Error ? error.message : String(error)}`,
-            ErrorCode.RunLifecycleError,
-            500,
-            error instanceof Ably.ErrorInfo ? error : undefined,
-          );
-          logger?.error('Run.start(); failed to publish run-start', { runId });
-          throw errInfo;
         }
 
         logger?.debug('Run.start(); run started', { runId, inputEventId });
       },
 
-      // Spec: AIT-ST5c
-      addEvents: async (nodes: EventsNode<TOutput>[]): Promise<void> => {
-        logger?.trace('Run.addEvents();', { runId, count: nodes.length });
-
-        await requireConnected('addEvents');
-
-        if (state === RunState.INITIALIZED) {
-          throw new Ably.ErrorInfo(
-            `unable to add events; start() must be called before addEvents() (run ${runId})`,
-            ErrorCode.InvalidArgument,
-            400,
-          );
-        }
-
-        const runOwnerClientId = runManager.getClientId(runId);
-
-        try {
-          for (const node of nodes) {
-            const headers = buildTransportHeaders({
-              role: 'assistant',
-              runId,
-              codecMessageId: node.codecMessageId,
-              runClientId: runOwnerClientId,
-              invocationId,
-              inputClientId: resolvedInputClientId,
-              inputCodecMessageId: resolvedInputCodecMessageId,
-            });
-
-            const encoder = codec.createEncoder(channel, {
-              extras: { headers },
-              onMessage,
-            });
-
-            for (const event of node.events) {
-              await encoder.publishOutput(event);
-            }
-
-            await encoder.close();
-          }
-        } catch (error) {
-          const errInfo = new Ably.ErrorInfo(
-            `unable to publish events for run ${runId}; ${error instanceof Error ? error.message : String(error)}`,
-            ErrorCode.RunLifecycleError,
-            500,
-            error instanceof Ably.ErrorInfo ? error : undefined,
-          );
-          logger?.error('Run.addEvents(); publish failed', { runId });
-          throw errInfo;
-        }
-
-        logger?.debug('Run.addEvents(); events published', { runId, count: nodes.length });
-      },
-
-      loadProjection: async (): Promise<TProjection> => {
-        logger?.trace('Run.loadProjection();', { runId });
-        await requireConnected('loadProjection');
-        const projection = await loadRunProjection<TInput, TOutput, TProjection, TMessage>({
-          channel,
-          codec,
-          runId,
-          signal,
-          logger,
-          liveMessages: liveLookupMessages,
-        });
-        cachedProjection = projection;
-        return projection;
-      },
-
       loadConversation: async (options?: LoadConversationOptions): Promise<TMessage[]> => {
         logger?.trace('Run.loadConversation();', { runId });
         await requireConnected('loadConversation');
-        const { messages, projection } = await loadConversation<TInput, TOutput, TProjection, TMessage>({
-          channel,
-          codec,
+        // No cache. Drives Tree hydration via the AgentView's conversation walk
+        // and computes a fresh snapshot of the parent-chain messages at
+        // return time. After this call, `Run.messages` continues to work
+        // as a live Tree read.
+        const { messages } = await getAgentView().loadConversation(
           runId,
-          signal,
-          logger,
-          liveMessages: liveLookupMessages,
           assistantParentFallback,
-          pageLimit: options?.pageLimit ?? 200,
-          maxMessages: options?.maxMessages ?? 2000,
-        });
-        cachedProjection = projection;
-        cachedConversation = messages;
+          signal,
+          options?.maxRuns,
+          runIdOverridden || resolvedContinuation,
+          resolvedRegenerates,
+        );
         return messages;
       },
 
@@ -1198,14 +938,14 @@ class DefaultAgentSession<
         // `streamOpts.parent` from the caller, else the reply run's
         // structural-parent fallback computed once at run-start
         // (`assistantParentFallback` — the triggering user message, or the
-        // input wire's own parent for regenerate wires that produced no
+        // input message's own parent for regenerate messages that produced no
         // MessageNodes). Owning the default here means agent routes don't have
         // to pass `{ parent: lastUserCodecMessageId }` to keep tree threading
         // correct; edit-then-regenerate sibling resolution relies on the
         // user→assistant chain being explicit.
         const assistantParent = streamOpts?.parent ?? assistantParentFallback;
         const assistantForkOf = streamOpts?.forkOf ?? resolvedForkOf;
-        // Echo `msg-regenerate` on the assistant wire so that a
+        // Echo `msg-regenerate` on the assistant message so that a
         // client receiving the assistant chunk before `ai-run-start`
         // (e.g. via history pagination across a page boundary, or a lost
         // lifecycle publish) can still populate `RunNode.regeneratesCodecMessageId`
@@ -1239,12 +979,25 @@ class DefaultAgentSession<
             `unable to pipe response for run ${runId}; ${result.error.message}`,
             ErrorCode.StreamError,
             500,
-            result.error instanceof Ably.ErrorInfo ? result.error : undefined,
+            errorCause(result.error),
           );
           logger?.error('Run.pipe(); stream error', { runId });
           runOnError?.(errInfo);
         }
 
+        // Run cancellation is transport-tier: guarantee the run-end terminal so
+        // every observer's stream closes even if the caller's handler omits
+        // run.end(). Best-effort — pipe must still return the StreamResult; a
+        // later run.end() is a no-op via the ENDED guard. The run is past
+        // INITIALIZED here (pipe requires start()), so end()'s guards pass.
+        if (result.reason === 'cancelled') {
+          try {
+            await run.end({ reason: 'cancelled' });
+          } catch {
+            logger?.error('Run.pipe(); run-end on cancel failed', { runId });
+          }
+        }
+
         logger?.debug('Run.pipe(); stream finished', { runId, reason: result.reason });
         return result;
       },
@@ -1267,16 +1020,9 @@ class DefaultAgentSession<
         state = RunState.ENDED;
 
         try {
-          await runManager.suspendRun(runId, invocationId, resolvedInputClientId, resolvedInputCodecMessageId);
-        } catch (error) {
-          const errInfo = new Ably.ErrorInfo(
-            `unable to publish run-suspend for run ${runId}; ${error instanceof Error ? error.message : String(error)}`,
-            ErrorCode.RunLifecycleError,
-            500,
-            error instanceof Ably.ErrorInfo ? error : undefined,
+          await publishLifecycle('run-suspend', 'suspend', async () =>
+            runManager.suspendRun(runId, invocationId, resolvedInputClientId, resolvedInputCodecMessageId),
           );
-          logger?.error('Run.suspend(); failed to publish run-suspend', { runId });
-          throw errInfo;
         } finally {
           deregisterRun();
         }
@@ -1285,7 +1031,9 @@ class DefaultAgentSession<
       },
 
       // Spec: AIT-ST7, AIT-ST7a, AIT-ST7b
-      end: async (reason: RunEndReason): Promise<void> => {
+      end: async (params: RunEndParams): Promise<void> => {
+        const { reason } = params;
+        const error = params.reason === 'error' ? params.error : undefined;
         logger?.trace('Run.end();', { runId, reason });
 
         await requireConnected('end');
@@ -1301,16 +1049,9 @@ class DefaultAgentSession<
         state = RunState.ENDED;
 
         try {
-          await runManager.endRun(runId, reason, invocationId, resolvedInputClientId, resolvedInputCodecMessageId);
-        } catch (error) {
-          const errInfo = new Ably.ErrorInfo(
-            `unable to publish run-end for run ${runId}; ${error instanceof Error ? error.message : String(error)}`,
-            ErrorCode.RunLifecycleError,
-            500,
-            error instanceof Ably.ErrorInfo ? error : undefined,
+          await publishLifecycle('run-end', 'end', async () =>
+            runManager.endRun(runId, reason, invocationId, resolvedInputClientId, resolvedInputCodecMessageId, error),
           );
-          logger?.error('Run.end(); failed to publish run-end', { runId });
-          throw errInfo;
         } finally {
           deregisterRun();
         }