@ably/ai-transport 0.2.0 → 0.3.0

package/dist/core/transport/tree.d.ts

@@ -1,5 +1,5 @@
 import { Logger } from '../../logger.js';
-import { CodecInputEvent, CodecOutputEvent, Reducer } from '../codec/types.js';
+import { CodecEvent, CodecInputEvent, CodecOutputEvent, Reducer } from '../codec/types.js';
 import { ConversationNode, OutputEvent, RunLifecycleEvent, RunNode, Tree } from './types.js';
 /**
  * Tree — materializes a branching conversation as a forest of nodes. Each turn
@@ -24,6 +24,14 @@ import { ConversationNode, OutputEvent, RunLifecycleEvent, RunNode, Tree } from
  * sharing the same input-node parent (no fork-of).
  */
 import type * as Ably from 'ably';
+/**
+ * How long (in ms, on the Ably message-timestamp timeline) a structurally
+ * complete run's event log is retained after the node's last observed
+ * activity. Bounds cross-publisher live delivery reorder: a wire can be
+ * delivered after a higher-serial wire by at most this window. Conservative
+ * placeholder pending confirmation of the actual cross-region bound.
+ */
+export declare const REORDER_WINDOW_MS = 120000;
 /**
  * The primary key a node is indexed under: a reply run's `runId`, or an input
  * node's `codecMessageId` (the client owns it before the agent mints a runId).
@@ -70,24 +78,34 @@ export interface TreeInternal<TInput extends CodecInputEvent, TOutput extends Co
      * @param events.outputs - Agent-published events (`ai-output` wire).
      * @param headers - Transport headers from the inbound Ably message.
      * @param serial - Ably channel serial; undefined for optimistic inserts.
+     * @param timestamp - Ably server timestamp (epoch ms) of the message —
+     *   top-level `Message.timestamp`, the message's create time on every
+     *   delivery (an append's own receive time lives in `version.timestamp`) —
+     *   or undefined for optimistic inserts. Advances the Tree's event-log
+     *   retention clock and the owning node's last-activity time.
+     * @param version - The delivery's `Message.version.serial`, or undefined
+     *   when the delivery carried none (optimistic inserts, never-mutated
+     *   deliveries from sources that omit it). Guards the node's event log
+     *   against whole-wire replays: a delivery at or below the version already
+     *   decoded into its log entry is dropped.
      */
     applyMessage(events: {
         inputs: TInput[];
         outputs: TOutput[];
-    }, headers: Record<string, string>, serial?: string): void;
+    }, headers: Record<string, string>, serial?: string, timestamp?: number, version?: string): void;
     /**
      * Apply a run-lifecycle event.
      *
      * - `start`: creates the reply run (if missing) or, for an existing run,
-     *   sets RunNode.status to 'active', promotes startSerial, and backfills
+     *   sets RunNode.state to 'active', promotes startSerial, and backfills
      *   structural metadata (parent / forkOf / regenerates / invocationId).
-     * - `suspend`: sets RunNode.status to 'suspended' and records `endSerial`.
+     * - `suspend`: sets RunNode.state to 'suspended' and records `endSerial`.
      *   The run stays live so a resume under the same `runId` picks up where it
      *   left off.
-     * - `resume`: re-activates an existing suspended Run (status back to
+     * - `resume`: re-activates an existing suspended Run (state back to
      *   'active') without touching its structure or serials — a pure re-entry
      *   signal. A no-op if the Run is not yet known.
-     * - `end`: sets RunNode.status to the terminal reason and records
+     * - `end`: sets RunNode.state to the terminal reason and records
      *   `endSerial`.
      *
      * Always emits a 'run' event to subscribers.
@@ -169,7 +187,31 @@ export declare class DefaultTree<TInput extends CodecInputEvent, TOutput extends
      */
     private _siblingCache;
     private _siblingCacheVersion;
-    constructor(codec: Reducer<TInput | TOutput, TProjection>, logger: Logger);
+    /**
+     * Index from `event-id` header to the raw Ably message that carried it.
+     * Populated incrementally as messages arrive via {@link emitAblyMessage};
+     * reads back the raw message for the agent's input-event lookup
+     * ({@link findAblyMessageByEventId}). Bounded by the Tree's lifetime — cleared
+     * when the Tree is replaced on continuity loss / session close.
+     */
+    private readonly _eventIdIndex;
+    /**
+     * Event-log retention logical clock: the max Ably message timestamp (epoch
+     * ms) observed across every apply, 0 until the first timestamped one. Only
+     * ever advances — older-page history application carries smaller timestamps
+     * and leaves it (and therefore the sweep) untouched.
+     */
+    private _clock;
+    /**
+     * Keys of structurally complete run nodes (run-start and run-end both
+     * observed) whose event logs await the retention window, in completion
+     * order. Drained from the front whenever {@link _clock} advances; sweeping
+     * only at clock advances keeps a history page's batch atomic — applying an
+     * older page can never advance the clock, so a node cannot be swept between
+     * its run-start and the rest of its wires in the same page.
+     */
+    private readonly _sweepQueue;
+    constructor(codec: Reducer<CodecEvent<TInput, TOutput>, TProjection>, logger: Logger);
     /**
      * Compare two nodes (Run or input) for sorted list ordering.
      * Serial-bearing nodes sort by their sort serial (`startSerial` for runs,
@@ -224,6 +266,88 @@ export declare class DefaultTree<TInput extends CodecInputEvent, TOutput extends
      * @param messageId - The reducer routing key (codec-message-id), or undefined.
      */
     private _foldInto;
+    /**
+     * Record a serial-bearing wire in the node's event log and fold it. Events
+     * extending the log tail (the common case — in-order live delivery) fold
+     * incrementally onto the existing projection, identical to a bare
+     * {@link _foldInto}. Events that land earlier in the log (an earlier-serial
+     * wire delivered late — cross-publisher reorder, or a history page applying
+     * an older message after a newer one) cannot be folded incrementally without
+     * corrupting serial order, so the node is refolded from the whole log via
+     * {@link _refold}.
+     *
+     * Optimistic (serial-less) applies and empty event batches are not logged;
+     * an optimistic seed folds into the projection but never into the log, and
+     * marks the node `optimistic`. The first serial-bearing wire (the echo of
+     * the optimistic input, which re-delivers the seeded content) refolds the
+     * node from the log alone — rebuilding the projection without the seed
+     * rather than folding the echo on top of it. The codec therefore never sees
+     * the seed and its echo in one projection, and needs no seed-replacement
+     * logic. The seed must be a faithful preview of the echo, since the echo's
+     * content is what survives.
+     *
+     * Whole-wire replays are dropped at the log: each entry records the highest
+     * `Message.version.serial` decoded into it (`decodedThrough`), so a
+     * version-bearing delivery the entry has already incorporated — a second
+     * hydration over a populated Tree, a remounted View's re-fetch, an agent
+     * re-walk — records nothing and folds nothing. A newer version of a
+     * discrete wire (an edited discrete) is likewise dropped; propagating edits
+     * into projections is deliberately out of scope.
+     * @param entry - The internal node whose log and projection are updated.
+     * @param events - The decoded events to fold, in wire order.
+     * @param serial - Ably channel serial; undefined for an optimistic insert.
+     * @param messageId - The reducer routing key (codec-message-id), or undefined.
+     * @param version - The delivery's `Message.version.serial`, or undefined.
+     * @param streamed - Whether the delivery is part of a streamed wire.
+     */
+    private _recordAndFold;
+    /**
+     * Rebuild a node's projection from its event log in canonical serial order:
+     * a fresh {@link Reducer.init} folded through every logged event, each with
+     * its own wire's serial and messageId. Used when a late, earlier-serial wire
+     * makes incremental folding unsound. Reducer purity (a fold is a function of
+     * its inputs alone) is what makes the rebuild faithful; the per-fold
+     * try/catch mirrors {@link _foldInto} so one throwing event can't abort the
+     * rebuild.
+     *
+     * Rebuilds the projection only; the surrounding apply emits its usual
+     * `output` event carrying just the triggering wire's events. Consumers read
+     * the rebuilt state from `node.projection` (the View recomputes its message
+     * list from it), so on the refold path the event's `events` payload is not a
+     * delta of the full projection change.
+     * @param entry - The internal node whose projection is rebuilt in place.
+     */
+    private _refold;
+    /**
+     * Record activity on a node and advance the retention clock. Updates the
+     * node's `lastActivityTs` and the Tree-wide `_clock` to the given timestamp
+     * when it is newer; a clock advance drains the sweep queue. `undefined`
+     * (an optimistic local apply) advances nothing.
+     * @param entry - The node the activity belongs to.
+     * @param timestamp - Ably message timestamp (epoch ms), or undefined.
+     */
+    private _recordActivity;
+    /**
+     * Queue a run node's event log for retention sweeping once the node is
+     * structurally complete: its run-start (serial floor — no older history page
+     * can add to it) and its run-end (no further agent output) have both been
+     * observed. The actual drop happens in {@link _drainSweepQueue} once the
+     * reorder window has also lapsed. No-op for input nodes (never swept — no
+     * floor marker, and their logs are bounded by one user message), for nodes
+     * already queued or swept, and while either marker is missing.
+     * @param entry - The node to consider for sweeping.
+     */
+    private _maybeQueueSweep;
+    /**
+     * Drop the event logs of queued nodes whose retention window has lapsed:
+     * `lastActivityTs + REORDER_WINDOW_MS < _clock`. Drains from the front and
+     * stops at the first node still inside the window — completion order is
+     * time-ordered for live traffic, so this is amortised O(1) per apply, and
+     * stopping early only ever over-retains (memory, never correctness). Called
+     * only when the clock advances, so applying an older history page (smaller
+     * timestamps) can never sweep mid-batch. Deleted nodes are skipped.
+     */
+    private _drainSweepQueue;
     private _addToParentIndex;
     private _removeFromParentIndex;
     /**
@@ -297,7 +421,7 @@ export declare class DefaultTree<TInput extends CodecInputEvent, TOutput extends
     applyMessage(events: {
         inputs: TInput[];
         outputs: TOutput[];
-    }, headers: Record<string, string>, serial?: string): void;
+    }, headers: Record<string, string>, serial?: string, timestamp?: number, version?: string): void;
     /**
      * Apply a run-less user input wire: create (or promote the serial of) the
      * input node keyed by its codec-message-id, fold the input events into its
@@ -306,7 +430,9 @@ export declare class DefaultTree<TInput extends CodecInputEvent, TOutput extends
      * @param codecMessageId - The input node's codec-message-id (its primary key).
      * @param headers - Transport headers from the inbound Ably message.
      * @param serial - Ably channel serial; undefined for an optimistic insert.
-     * @param all - The decoded input events to fold, in wire order.
+     * @param timestamp - Ably server timestamp (epoch ms); undefined for an optimistic insert.
+     * @param version - The delivery's `Message.version.serial`, or undefined.
+     * @param all - The direction-tagged input events to fold, in wire order.
      */
     private _applyInputMessage;
     /**
@@ -322,6 +448,8 @@ export declare class DefaultTree<TInput extends CodecInputEvent, TOutput extends
      * @param events.outputs - Agent-published events (`ai-output` wire).
      * @param headers - Transport headers from the inbound Ably message.
      * @param serial - Ably channel serial; undefined for an optimistic insert.
+     * @param timestamp - Ably server timestamp (epoch ms); undefined for an optimistic insert.
+     * @param version - The delivery's `Message.version.serial`, or undefined.
      */
     private _applyRunMessage;
     /**
@@ -365,10 +493,17 @@ export declare class DefaultTree<TInput extends CodecInputEvent, TOutput extends
      */
     private _applyRunResume;
     /**
-     * Apply a run-end lifecycle event: record the terminal reason as the node's
-     * status and the serial it ended at. Status/endSerial are content, not
-     * structure, so this never mutates `_structuralVersion`; the caller owns the
-     * emits.
+     * Apply a run-end lifecycle event: record the terminal reason (and, for an
+     * error end, the error) as the node's state, plus the serial it ended at.
+     * State/endSerial are content, not structure, so this never mutates
+     * `_structuralVersion`; the caller owns the emits.
+     *
+     * A run-end for an unknown runId is a no-op: nothing else is known about the
+     * run yet, so there is no node to mark. When that happens during history
+     * replay (a page boundary falling just before the run-end, so the run's
+     * other wires arrive in later pages), the run is never marked terminal and
+     * its event log is retained for the Tree's lifetime — over-retention, never
+     * corruption.
      * @param event - The run-end lifecycle event.
      */
     private _applyRunEnd;
@@ -382,6 +517,17 @@ export declare class DefaultTree<TInput extends CodecInputEvent, TOutput extends
      * @returns A newly-allocated internal run node ready for insertion.
      */
     private _createRunFromHeaders;
+    /**
+     * Wrap a freshly-built conversation node in its internal envelope — sort
+     * sequence, event log, and retention/promotion state. The single home for
+     * those per-node fields, so a new field is added in one place rather than at
+     * every node-construction site.
+     * @param node - The conversation node to wrap.
+     * @param runStartSeen - Whether the run's ai-run-start has been observed
+     *   (run nodes only; always false for input nodes).
+     * @returns A newly-allocated internal node ready for insertion.
+     */
+    private _wrapNode;
     /**
      * Allocate a RunNode from already-resolved fields. Shared by the
      * header-driven and lifecycle-driven run creators: both build the identical
@@ -394,6 +540,7 @@ export declare class DefaultTree<TInput extends CodecInputEvent, TOutput extends
      * @param params.clientId - The publishing client's id.
      * @param params.invocationId - The agent invocation id.
      * @param params.startSerial - Ably channel serial; undefined for optimistic inserts.
+     * @param params.runStartSeen - Whether the run's ai-run-start has been observed (true only for lifecycle-created runs).
      * @returns A newly-allocated internal run node ready for insertion.
      */
     private _buildRunNode;
@@ -418,10 +565,13 @@ export declare class DefaultTree<TInput extends CodecInputEvent, TOutput extends
     on(event: 'run', handler: (event: RunLifecycleEvent) => void): () => void;
     on(event: 'output', handler: (event: OutputEvent<TOutput>) => void): () => void;
     /**
-     * Forward a raw Ably message event to tree subscribers.
+     * Forward a raw Ably message event to tree subscribers. Also indexes the
+     * Ably message by `event-id` header (if present) for
+     * {@link findAblyMessageByEventId} lookups.
      * @param msg - The raw Ably message to emit.
      */
     emitAblyMessage(msg: Ably.InboundMessage): void;
+    findAblyMessageByEventId(eventId: string): Ably.InboundMessage | undefined;
 }
 /**
  * Create a Tree that materializes branching conversation history from a flat
@@ -432,4 +582,4 @@ export declare class DefaultTree<TInput extends CodecInputEvent, TOutput extends
  *   directly for internal methods (applyMessage, applyRunLifecycle,
  *   emitAblyMessage). Public consumers see the narrower {@link Tree} interface.
  */
-export declare const createTree: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection>(codec: Reducer<TInput | TOutput, TProjection>, logger: Logger) => DefaultTree<TInput, TOutput, TProjection>;
+export declare const createTree: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection>(codec: Reducer<CodecEvent<TInput, TOutput>, TProjection>, logger: Logger) => DefaultTree<TInput, TOutput, TProjection>;

package/dist/core/transport/types/agent.d.ts

@@ -2,9 +2,10 @@ import { Logger } from '../../../logger.js';
 import { Codec, CodecInputEvent, CodecOutputEvent, WriteOptions } from '../../codec/types.js';
 import { Invocation } from '../invocation.js';
 import { CancelRequest, RunEndReason } from './shared.js';
-import { MessageNode } from './tree.js';
+import { MessageNode, Tree } from './tree.js';
 /** Agent (server-side) session types: options, run runtime, and the Run / AgentSession contracts. */
 import type * as Ably from 'ably';
+import type * as AblyObjects from 'ably/liveobjects';
 /** Options for creating an agent session. */
 export interface AgentSessionOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
     /**
@@ -30,60 +31,43 @@ export interface AgentSessionOptions<TInput extends CodecInputEvent, TOutput ext
     onError?: (error: Ably.ErrorInfo) => void;
     /**
      * 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).
      */
     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;
-}
-/**
- * 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[];
+    channelModes?: readonly Ably.ChannelMode[];
 }
 /**
  * Options for `Run.pipe` — per-operation overrides for the assistant message.
@@ -177,7 +161,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
@@ -205,21 +189,41 @@ export interface RunView<TMessage> {
 /** Options for {@link Run.loadConversation}. */
 export interface LoadConversationOptions {
     /**
-     * Number of wire messages to request per history page.
-     * Default: 200.
+     * 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.
      */
-    pageLimit?: 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';
     /**
-     * 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.
+     * Optional terminal error to surface to clients. Omit to end in error
+     * without detail.
      */
-    maxMessages?: number;
-}
+    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.
  */
 export interface Run<TOutput extends CodecOutputEvent, TProjection, TMessage> {
     /** The run's unique identifier. */
@@ -254,7 +258,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>;
     /**
@@ -263,45 +267,26 @@ export interface Run<TOutput extends CodecOutputEvent, TProjection, TMessage> {
      * Does NOT call end() — the caller must call end() after pipe returns.
      */
     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[]>;
     /**
@@ -315,18 +300,55 @@ export interface Run<TOutput extends CodecOutputEvent, TProjection, TMessage> {
      * suspended.
      */
     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>;
 }
 /** 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.
      */