@ably/ai-transport 0.2.0 → 0.3.0

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

@@ -17,13 +17,13 @@
  */
 
 import * as Ably from 'ably';
+// Also augments RealtimeChannel with `.object` (ably/liveobjects side-effect).
+import type * as AblyObjects from 'ably/liveobjects';
 
 import {
   EVENT_CANCEL,
   EVENT_RUN_END,
   HEADER_CODEC_MESSAGE_ID,
-  HEADER_ERROR_CODE,
-  HEADER_ERROR_MESSAGE,
   HEADER_EVENT_ID,
   HEADER_INPUT_CODEC_MESSAGE_ID,
   HEADER_INVOCATION_ID,
@@ -36,12 +36,14 @@ import { ErrorCode } from '../../errors.js';
 import { EventEmitter } from '../../event-emitter.js';
 import type { Logger } from '../../logger.js';
 import { LogLevel, makeLogger } from '../../logger.js';
-import { getTransportHeaders } from '../../utils.js';
+import { errorCause, errorMessage, getTransportHeaders } from '../../utils.js';
 import { registerAgent } from '../agent.js';
-import type { CodecInputEvent, CodecOutputEvent, Decoder, Encoder } from '../codec/types.js';
-import { applyWireMessage } from './decode-fold.js';
-import { buildTransportHeaders } from './headers.js';
+import { resolveChannelModes } from '../channel-options.js';
+import type { Codec, CodecInputEvent, CodecOutputEvent, Encoder } from '../codec/types.js';
+import { createWireApplier, type WireApplier } from './decode-fold.js';
+import { buildRunEndError, buildTransportHeaders } from './headers.js';
 import { Invocation } from './invocation.js';
+import { bestEffortDetach, continuityLostError, isContinuityLost, requireConnected } from './session-support.js';
 import type { DefaultTree } from './tree.js';
 import { createTree } from './tree.js';
 import type { ActiveRun, ClientSession, ClientSessionOptions, RunEndReason, SendOptions, Tree, View } from './types.js';
@@ -83,8 +85,8 @@ class DefaultClientSession<
   TMessage,
 > implements ClientSession<TInput, TOutput, TProjection, TMessage> {
   private readonly _channel: Ably.RealtimeChannel;
-  private readonly _codec: ClientSessionOptions<TInput, TOutput, TProjection, TMessage>['codec'];
-  private readonly _clientId: string | undefined;
+  private readonly _client: Ably.Realtime;
+  private readonly _codec: Codec<TInput, TOutput, TProjection, TMessage>;
   private readonly _logger: Logger;
 
   // Typed event emitter — the session emits only 'error'; all data events live on Tree/View
@@ -94,7 +96,13 @@ class DefaultClientSession<
   private readonly _tree: DefaultTree<TInput, TOutput, TProjection>;
   private readonly _view: DefaultView<TInput, TOutput, TProjection, TMessage>;
   private readonly _views = new Set<DefaultView<TInput, TOutput, TProjection, TMessage>>();
-  private readonly _decoder: Decoder<TInput, TOutput>;
+  /**
+   * The Tree's single decode-and-apply engine, binding the session's one
+   * decoder instance. Shared by the live decode loop and every View's history
+   * replay so an attach-boundary in-flight stream is continued (not
+   * re-started) by hydration, and re-delivered content decodes to nothing.
+   */
+  private readonly _applier: WireApplier;
   /**
    * Shared encoder for the lifetime of the session. The client only ever
    * uses `publishInput` (input wire), so the encoder's stream tracker map
@@ -137,10 +145,13 @@ class DefaultClientSession<
     // Spec: AIT-CT1a, AIT-CT1a2 — register this SDK on both the connection
     // (options.agents) and channel-attach (params.agent) paths. Idempotent
     // across sessions sharing one client.
-    const channelOptions = registerAgent(options.client, options.codec);
+    const channelOptions: Ably.ChannelOptions = registerAgent(options.client, options.codec);
+    // Spec: AIT-CT23 — 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._client = options.client;
     this._codec = options.codec;
-    this._clientId = options.clientId;
     this._logger = (options.logger ?? makeLogger({ logLevel: LogLevel.Silent })).withContext({
       component: 'ClientSession',
     });
@@ -150,19 +161,17 @@ class DefaultClientSession<
 
     // Compose sub-components
     this._tree = createTree<TInput, TOutput, TProjection>(this._codec, this._logger);
+    this._applier = createWireApplier(this._tree, this._codec.createDecoder());
     this._view = createView<TInput, TOutput, TProjection, TMessage>({
       tree: this._tree,
       channel: this._channel,
       codec: this._codec,
+      applier: this._applier,
       sendDelegate: this._internalSend.bind(this),
       logger: this._logger,
       onClose: () => this._views.delete(this._view),
     });
-    this._decoder = this._codec.createDecoder();
-    this._encoder = this._codec.createEncoder(
-      this._channel,
-      this._clientId === undefined ? undefined : { clientId: this._clientId },
-    );
+    this._encoder = this._codec.createEncoder(this._channel);
 
     this._views.add(this._view);
 
@@ -204,6 +213,20 @@ class DefaultClientSession<
     this._channel.on(this._onChannelStateChange);
   }
 
+  // ---------------------------------------------------------------------------
+  // Public accessors
+  // ---------------------------------------------------------------------------
+
+  // Spec: AIT-CT21
+  get presence(): Ably.RealtimePresence {
+    return this._channel.presence;
+  }
+
+  // Spec: AIT-CT22
+  get object(): AblyObjects.RealtimeObject {
+    return this._channel.object;
+  }
+
   // ---------------------------------------------------------------------------
   // Public connection API
   // ---------------------------------------------------------------------------
@@ -224,10 +247,10 @@ class DefaultClientSession<
       },
       (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('DefaultClientSession.connect(); subscribe failed');
         this._emitter.emit('error', errInfo);
@@ -237,15 +260,24 @@ class DefaultClientSession<
     return this._connectPromise;
   }
 
+  /**
+   * The session's identity, read from the Ably client's `auth.clientId`. Read
+   * lazily (never cached at construction): under token auth the client only
+   * learns its clientId once the connection reaches CONNECTED, which is
+   * guaranteed by the time any write runs — every write awaits `connect()`,
+   * and the channel cannot attach before the connection is CONNECTED. A
+   * connection with no concrete identity (anonymous, or a wildcard `*` token)
+   * resolves to `undefined`, so no run/input client id is stamped.
+   * @returns The client's concrete identity, or `undefined` if it has none.
+   */
+  // Spec: AIT-CT1b
+  private _resolveClientId(): string | undefined {
+    const clientId = this._client.auth.clientId;
+    return clientId && clientId !== '*' ? clientId : undefined;
+  }
+
   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);
   }
 
   // ---------------------------------------------------------------------------
@@ -267,24 +299,21 @@ class DefaultClientSession<
         // CAST: agent always writes a valid RunEndReason; default to 'complete' for robustness
         const reason = (headers[HEADER_RUN_REASON] ?? 'complete') as RunEndReason;
         if (reason === 'error') {
-          const codeRaw = headers[HEADER_ERROR_CODE];
-          const parsedCode = codeRaw === undefined ? Number.NaN : Number(codeRaw);
-          const code = Number.isFinite(parsedCode) ? parsedCode : ErrorCode.SessionSubscriptionError;
-          const message = headers[HEADER_ERROR_MESSAGE] ?? 'agent reported an error';
-          const statusCode = code >= 10000 && code < 60000 ? Math.floor(code / 100) : 500;
-          const errInfo = new Ably.ErrorInfo(message, code, statusCode);
+          const errInfo = buildRunEndError(headers);
           this._logger.error('ClientSession._handleMessage(); agent error received', {
             runId: headers[HEADER_RUN_ID],
             invocationId: headers[HEADER_INVOCATION_ID],
-            code,
+            code: errInfo.code,
           });
           this._emitter.emit('error', errInfo);
         }
       }
 
-      // Reconstruct the tree via the shared decode-fold engine — the same path
-      // the View's history replay uses, so the live loop can't drift from it.
-      const event = applyWireMessage(this._tree, this._decoder, ablyMessage);
+      // Reconstruct the tree via the Tree's single decode-and-apply engine —
+      // the same applier (and decoder instance) the Views' history replay
+      // uses, so the live loop can't drift from it and an attach-boundary
+      // stream isn't double-decoded.
+      const event = this._applier.apply(ablyMessage);
 
       // Live-only: resolve the pending `runId` promise on a fresh run-start or
       // a continuation run-resume. Key by the echoed `input-codec-message-id`
@@ -309,14 +338,13 @@ class DefaultClientSession<
       // 'update' events the apply triggers.
       this._tree.emitAblyMessage(ablyMessage);
     } catch (error) {
-      const cause = error instanceof Ably.ErrorInfo ? error : undefined;
       this._emitter.emit(
         'error',
         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,
-          cause,
+          errorCause(error),
         ),
       );
     }
@@ -338,13 +366,7 @@ class DefaultClientSession<
       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('ClientSession._handleChannelStateChange(); channel continuity lost', {
       current,
@@ -352,12 +374,7 @@ class DefaultClientSession<
       previous: stateChange.previous,
     });
 
-    const err = new Ably.ErrorInfo(
-      `unable to deliver events; channel continuity lost (${current}${current === 'attached' ? ', resumed: false' : ''})`,
-      ErrorCode.ChannelContinuityLost,
-      500,
-      stateChange.reason,
-    );
+    const err = continuityLostError(stateChange, 'deliver events');
 
     // Surface the loss via the session `error` event. Consumers that expose a
     // per-run stream (e.g. the Vercel ChatTransport) error their stream off
@@ -406,6 +423,7 @@ class DefaultClientSession<
       tree: this._tree,
       channel: this._channel,
       codec: this._codec,
+      applier: this._applier,
       sendDelegate: this._internalSend.bind(this),
       logger: this._logger,
       onClose: () => this._views.delete(view),
@@ -506,7 +524,7 @@ class DefaultClientSession<
         role: 'user',
         runId,
         codecMessageId,
-        runClientId: this._clientId,
+        runClientId: this._resolveClientId(),
         ...(parent !== undefined && { parent }),
         ...(forkOf !== undefined && { forkOf }),
         ...(regenerates !== undefined && { regenerates }),
@@ -574,16 +592,15 @@ class DefaultClientSession<
           await this._encoder.publishInput(item.input, {
             extras: { headers: item.headers },
             messageId: item.codecMessageId,
-            ...(this._clientId !== undefined && { clientId: this._clientId }),
           });
         }
       } catch (error) {
-        const cause = error instanceof Ably.ErrorInfo ? error : undefined;
+        const cause = errorCause(error);
         const isPermission = cause?.statusCode === 401 || cause?.statusCode === 403;
         const err = new Ably.ErrorInfo(
           isPermission
             ? `unable to publish events; missing publish capability on the channel`
-            : `unable to publish events; ${error instanceof Error ? error.message : String(error)}`,
+            : `unable to publish events; ${errorMessage(error)}`,
           isPermission ? ErrorCode.InsufficientCapability : ErrorCode.SessionSendFailed,
           isPermission ? 401 : 500,
           cause,
@@ -735,19 +752,7 @@ class DefaultClientSession<
       // Swallow: encoder close is best-effort during teardown
     }
 
-    // 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('ClientSession.close(); channel detach failed', { error });
-      }
-    }
+    await bestEffortDetach(this._channel, this._connectPromise, this._logger, 'ClientSession');
   }
 }
 

package/src/core/transport/decode-fold.ts

@@ -5,87 +5,97 @@
  * the conversation Tree from the same raw Ably wire log. This module is the one
  * place that classifies a wire message (run-lifecycle vs codec-decoded), parses
  * or decodes it, and applies it to the Tree — so the two paths can never drift.
+ *
+ * The engine is exposed as a {@link WireApplier} binding one Tree to one
+ * decoder. A Tree has exactly one applier (the session constructs it and hands
+ * it to every View), so every route a wire message can arrive by — the live
+ * subscription, View history pagination, the agent's hydration walks — feeds
+ * the same decoder. The decoder's version-guarded stream trackers then make
+ * re-delivery across routes (an attach-boundary in-flight stream, a replayed
+ * history page) decode to nothing instead of double-folding. The delivery's
+ * `version.serial` is also threaded into the Tree, whose per-entry
+ * `decodedThrough` high-water-mark drops whole-wire replays that no decoder
+ * state can see (stateless discrete re-decodes).
  */
 
 import type * as Ably from 'ably';
 
 import { HEADER_RUN_ID } from '../../constants.js';
 import { getTransportHeaders } from '../../utils.js';
-import type { Codec, CodecInputEvent, CodecOutputEvent, Decoder } from '../codec/types.js';
+import type { CodecInputEvent, CodecOutputEvent, Decoder } from '../codec/types.js';
 import { isRunLifecycleName, parseRunLifecycle } from './headers.js';
 import type { TreeInternal } from './tree.js';
 import type { RunLifecycleEvent } from './types.js';
 
 /**
- * Apply one inbound wire message to the tree.
- *
- * Run-lifecycle messages are turned into a {@link RunLifecycleEvent} via
- * {@link parseRunLifecycle} and applied with `applyRunLifecycle`; everything
- * else is decoded with `decoder` and applied with `applyMessage`, skipping
- * wire-only carriers that decode to no events and carry no run-id (the eventual
- * reply run is created later by its run-start).
- *
- * Does NOT emit the tree's `ably-message` event — the caller owns that, because
- * the live loop emits per message while history replay emits in a batch once
- * the whole page is applied. Returns the parsed lifecycle event so a live
- * caller can run its own side-effects (resolving a pending run-start,
- * surfacing an agent error); returns `undefined` for a codec-decoded message
- * or a lifecycle message that carried no run-id.
+ * The decode-and-apply engine for one Tree: a single codec decoder bound to a
+ * single Tree, shared by every route that feeds the Tree wire messages.
+ */
+export interface WireApplier {
+  /**
+   * Apply one inbound wire message to the bound tree.
+   *
+   * Run-lifecycle messages are turned into a {@link RunLifecycleEvent} via
+   * {@link parseRunLifecycle} and applied with `applyRunLifecycle`; everything
+   * else is decoded with the bound decoder and applied with `applyMessage`,
+   * skipping wire-only carriers that decode to no events and carry no run-id
+   * (the eventual reply run is created later by its run-start).
+   *
+   * Does NOT emit the tree's `ably-message` event — the caller owns that,
+   * because the live loop emits per message while history replay emits in a
+   * batch once the whole page is applied. Returns the parsed lifecycle event
+   * so a live caller can run its own side-effects (resolving a pending
+   * run-start, surfacing an agent error); returns `undefined` for a
+   * codec-decoded message or a lifecycle message that carried no run-id.
+   * @param rawMsg - The inbound Ably wire message.
+   * @returns The parsed run-lifecycle event, or `undefined`.
+   */
+  apply(rawMsg: Ably.InboundMessage): RunLifecycleEvent | undefined;
+}
+
+/**
+ * Classify, decode, and apply one inbound wire message to the tree. See
+ * {@link WireApplier.apply} for the contract.
  * @param tree - The tree to apply the message to.
  * @param decoder - The codec decoder used for non-lifecycle messages.
  * @param rawMsg - The inbound Ably wire message.
  * @returns The parsed run-lifecycle event, or `undefined`.
  */
-export const applyWireMessage = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection>(
+const applyWireMessage = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection>(
   tree: TreeInternal<TInput, TOutput, TProjection>,
   decoder: Decoder<TInput, TOutput>,
   rawMsg: Ably.InboundMessage,
 ): RunLifecycleEvent | undefined => {
   const headers = getTransportHeaders(rawMsg);
   const serial = rawMsg.serial;
+  // Top-level timestamp — the message's create time on every delivery (an
+  // append's own receive time lives in `version.timestamp`). The retention
+  // clock is sound on this timeline because run-end, a fresh create published
+  // after every wire of its run, bounds the node's last activity.
+  const timestamp = rawMsg.timestamp;
 
   if (isRunLifecycleName(rawMsg.name)) {
-    const event = parseRunLifecycle(rawMsg.name, headers, serial);
+    const event = parseRunLifecycle(rawMsg.name, headers, serial, timestamp);
     if (event) tree.applyRunLifecycle(event);
     return event;
   }
 
   const { inputs, outputs } = decoder.decode(rawMsg);
   if (inputs.length > 0 || outputs.length > 0 || headers[HEADER_RUN_ID]) {
-    tree.applyMessage({ inputs, outputs }, headers, serial);
+    tree.applyMessage({ inputs, outputs }, headers, serial, timestamp, rawMsg.version.serial);
   }
   return undefined;
 };
 
 /**
- * Decode one wire message with `decoder` and fold its events into `projection`,
- * returning the updated projection. Unlike {@link applyWireMessage} this builds
- * a standalone projection rather than applying to a tree — used by the agent's
- * conversation reconstruction. The caller owns the decoder so its streaming
- * state can span the messages of a run, and chooses the reducer routing key.
- * @param codec - The codec whose inherited Reducer `fold` method folds each decoded event into the projection.
- * @param decoder - The caller-owned codec decoder (reused across a run's wires).
- * @param projection - The projection to fold the message's events into.
- * @param rawMsg - The wire message to decode and fold.
- * @param messageId - The reducer routing key (codec-message-id) for this message.
- * @returns The projection after folding all of the message's decoded events.
+ * Bind a Tree and a decoder into the Tree's single {@link WireApplier}.
+ * @param tree - The tree the applier feeds.
+ * @param decoder - The codec decoder shared by every route into the tree.
+ * @returns The applier.
  */
-export const foldMessageInto = <
-  TInput extends CodecInputEvent,
-  TOutput extends CodecOutputEvent,
-  TProjection,
-  TMessage,
->(
-  codec: Codec<TInput, TOutput, TProjection, TMessage>,
+export const createWireApplier = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection>(
+  tree: TreeInternal<TInput, TOutput, TProjection>,
   decoder: Decoder<TInput, TOutput>,
-  projection: TProjection,
-  rawMsg: Ably.InboundMessage,
-  messageId: string,
-): TProjection => {
-  const { inputs, outputs } = decoder.decode(rawMsg);
-  let next = projection;
-  for (const event of [...inputs, ...outputs]) {
-    next = codec.fold(next, event, { serial: rawMsg.serial ?? '', messageId });
-  }
-  return next;
-};
+): WireApplier => ({
+  apply: (rawMsg: Ably.InboundMessage): RunLifecycleEvent | undefined => applyWireMessage(tree, decoder, rawMsg),
+});

package/src/core/transport/headers.ts

@@ -2,16 +2,20 @@
  * Transport header builder.
  *
  * Single source of truth for which transport headers every transport
- * message carries. Used by the agent session (pipe, addEvents) and by
+ * message carries. Used by the agent session (pipe) and by
  * the client session (optimistic message stamping).
  */
 
+import * as Ably from 'ably';
+
 import {
   EVENT_RUN_END,
   EVENT_RUN_RESUME,
   EVENT_RUN_START,
   EVENT_RUN_SUSPEND,
   HEADER_CODEC_MESSAGE_ID,
+  HEADER_ERROR_CODE,
+  HEADER_ERROR_MESSAGE,
   HEADER_EVENT_ID,
   HEADER_FORK_OF,
   HEADER_INPUT_CLIENT_ID,
@@ -24,6 +28,7 @@ import {
   HEADER_RUN_ID,
   HEADER_RUN_REASON,
 } from '../../constants.js';
+import { ErrorCode } from '../../errors.js';
 import type { RunEndReason, RunLifecycleEvent } from './types.js';
 
 /**
@@ -105,6 +110,11 @@ export const buildTransportHeaders = (opts: {
  * @param opts.inputClientId - ClientId of the triggering input event.
  * @param opts.inputCodecMessageId - Codec-message-id of the triggering input event.
  * @param opts.reason - Terminal reason; stamped on run-end only.
+ * @param opts.errorCode - Numeric error code stamped as `error-code` on
+ *   run-end. Set only when the run ended in error and the agent supplied an
+ *   error to surface; gives codec-agnostic consumers a baseline failure detail.
+ * @param opts.errorMessage - Error message stamped as `error-message` on
+ *   run-end. Paired with `errorCode`; set under the same condition.
  * @returns A headers record with the lifecycle headers set.
  */
 export const buildLifecycleHeaders = (opts: {
@@ -117,6 +127,8 @@ export const buildLifecycleHeaders = (opts: {
   inputClientId?: string;
   inputCodecMessageId?: string;
   reason?: RunEndReason;
+  errorCode?: number;
+  errorMessage?: string;
 }): Record<string, string> => {
   const h: Record<string, string> = {
     [HEADER_RUN_ID]: opts.runId,
@@ -129,6 +141,8 @@ export const buildLifecycleHeaders = (opts: {
   if (opts.invocationId !== undefined) h[HEADER_INVOCATION_ID] = opts.invocationId;
   if (opts.inputClientId !== undefined) h[HEADER_INPUT_CLIENT_ID] = opts.inputClientId;
   if (opts.inputCodecMessageId !== undefined) h[HEADER_INPUT_CODEC_MESSAGE_ID] = opts.inputCodecMessageId;
+  if (opts.errorCode !== undefined) h[HEADER_ERROR_CODE] = String(opts.errorCode);
+  if (opts.errorMessage !== undefined) h[HEADER_ERROR_MESSAGE] = opts.errorMessage;
   return h;
 };
 
@@ -151,6 +165,26 @@ type RunLifecycleName =
 export const isRunLifecycleName = (name: string | undefined): name is RunLifecycleName =>
   name === EVENT_RUN_START || name === EVENT_RUN_SUSPEND || name === EVENT_RUN_RESUME || name === EVENT_RUN_END;
 
+/**
+ * Reconstruct the terminal `Ably.ErrorInfo` for a run that ended in error, from
+ * its run-end transport headers. Reads the `error-code` / `error-message`
+ * headers the agent stamps (see {@link buildLifecycleHeaders}); falls back to a
+ * generic code/message when a run ended in error without detail. Single source
+ * of truth for the header→ErrorInfo derivation, shared by the client session's
+ * `on('error')` emit and the Tree's `RunInfo.error`.
+ * @param headers - Transport headers from the inbound run-end message.
+ * @returns The reconstructed terminal error.
+ */
+export const buildRunEndError = (headers: Record<string, string>): Ably.ErrorInfo => {
+  const codeRaw = headers[HEADER_ERROR_CODE];
+  const parsedCode = codeRaw === undefined ? Number.NaN : Number(codeRaw);
+  const code = Number.isFinite(parsedCode) ? parsedCode : ErrorCode.SessionSubscriptionError;
+  const message = headers[HEADER_ERROR_MESSAGE] ?? 'agent reported an error';
+  // 5-digit codes encode their HTTP status in the leading 3 digits; otherwise 500.
+  const statusCode = code >= 10000 && code < 60000 ? Math.floor(code / 100) : 500;
+  return new Ably.ErrorInfo(message, code, statusCode);
+};
+
 /**
  * Parse an inbound run-lifecycle Ably message into a {@link RunLifecycleEvent}.
  *
@@ -162,6 +196,9 @@ export const isRunLifecycleName = (name: string | undefined): name is RunLifecyc
  * @param headers - Transport headers from the inbound Ably message.
  * @param serial - Ably channel serial of the message, or `undefined` for an
  *   optimistic local event. Stamped onto the returned event.
+ * @param timestamp - Ably server timestamp (epoch ms) of the message, or
+ *   `undefined` for an optimistic local event. Stamped onto the returned
+ *   event; drives the Tree's event-log retention clock.
  * @returns The lifecycle event, or `undefined` when `name` is not a
  *   run-lifecycle event name or the message carries no `run-id`.
  */
@@ -169,11 +206,13 @@ export const parseRunLifecycle = (
   name: string,
   headers: Record<string, string>,
   serial: string | undefined,
+  timestamp: number | undefined,
 ): RunLifecycleEvent | undefined => {
   const runId = headers[HEADER_RUN_ID];
   if (!runId) return undefined;
 
   const clientId = headers[HEADER_RUN_CLIENT_ID] ?? '';
+  const stamped = timestamp === undefined ? {} : { timestamp };
 
   if (name === EVENT_RUN_START) {
     const parent = headers[HEADER_PARENT];
@@ -185,6 +224,7 @@ export const parseRunLifecycle = (
       clientId,
       serial,
       invocationId: headers[HEADER_INVOCATION_ID] ?? '',
+      ...stamped,
       ...(parent !== undefined && { parent }),
       ...(forkOf !== undefined && { forkOf }),
       ...(regenerates !== undefined && { regenerates }),
@@ -192,17 +232,30 @@ export const parseRunLifecycle = (
   }
 
   if (name === EVENT_RUN_SUSPEND) {
-    return { type: 'suspend', runId, clientId, serial, invocationId: headers[HEADER_INVOCATION_ID] ?? '' };
+    return { type: 'suspend', runId, clientId, serial, invocationId: headers[HEADER_INVOCATION_ID] ?? '', ...stamped };
   }
 
   if (name === EVENT_RUN_RESUME) {
-    return { type: 'resume', runId, clientId, serial, invocationId: headers[HEADER_INVOCATION_ID] ?? '' };
+    return { type: 'resume', runId, clientId, serial, invocationId: headers[HEADER_INVOCATION_ID] ?? '', ...stamped };
   }
 
   if (name === EVENT_RUN_END) {
     // CAST: agent always writes a valid RunEndReason; default to 'complete' for robustness.
     const reason = (headers[HEADER_RUN_REASON] ?? 'complete') as RunEndReason;
-    return { type: 'end', runId, clientId, serial, invocationId: headers[HEADER_INVOCATION_ID] ?? '', reason };
+    const invocationId = headers[HEADER_INVOCATION_ID] ?? '';
+    if (reason === 'error') {
+      return {
+        type: 'end',
+        runId,
+        clientId,
+        serial,
+        invocationId,
+        reason,
+        ...stamped,
+        error: buildRunEndError(headers),
+      };
+    }
+    return { type: 'end', runId, clientId, serial, invocationId, reason, ...stamped };
   }
 
   return undefined;

package/src/core/transport/index.ts

@@ -8,17 +8,18 @@ export type {
   ClientSession,
   ClientSessionOptions,
   ConversationNode,
-  EventsNode,
   InputNode,
   LoadConversationOptions,
   MessageNode,
   OutputEvent,
   PipeOptions,
   Run,
+  RunEndParams,
   RunEndReason,
   RunInfo,
   RunLifecycleEvent,
   RunNode,
+  RunNodeState,
   RunRuntime,
   RunView,
   SendOptions,

package/src/core/transport/invocation.ts

@@ -11,7 +11,7 @@
  * const invocation = Invocation.fromJSON(data);
  * const run = session.createRun(invocation, { signal: req.signal });
  * await run.start();
- * await run.loadProjection(); // fetch run projection from the channel
+ * await run.loadConversation(); // walk channel history into the session tree
  * const messages = run.messages;
  * ```
  *