@ably/ai-transport 0.2.0 → 0.3.0

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

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

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

@@ -18,6 +18,12 @@ interface RunLifecycleBase {
      * Empty string if the wire didn't carry an invocation-id.
      */
     invocationId: string;
+    /**
+     * Ably server timestamp (epoch ms) of the lifecycle message; absent for an
+     * optimistic local event. Advances the Tree's event-log retention clock and
+     * the target run's last-activity time.
+     */
+    timestamp?: number;
 }
 /**
  * A structured event describing a run starting, suspending, resuming, or
@@ -72,12 +78,20 @@ export type RunLifecycleEvent = (RunLifecycleBase & {
      * optimistic local event. The Tree reads it to set the Run's endSerial.
      */
     serial: string | undefined;
+} & ({
+    /** Why the run ended — any terminal reason other than `'error'`. */
+    reason: Exclude<RunEndReason, 'error'>;
+} | {
+    /** The run ended in error. */
+    reason: 'error';
     /**
-     * Why the run ended — the terminal reason the Tree records as the
-     * RunNode's status: `complete`, `cancelled`, or `error`.
+     * Terminal error detail, reconstructed from the run-end's
+     * `error-code` / `error-message` headers (or a generic fallback
+     * when the run ended in error without detail). The Tree records it
+     * on the RunNode and exposes it via `RunInfo.error`.
      */
-    reason: RunEndReason;
-});
+    error: Ably.ErrorInfo;
+}));
 /** A node in the conversation tree, representing a single domain message. */
 export interface MessageNode<TMessage> {
     /** Discriminator — identifies this as a message node. */
@@ -99,6 +113,24 @@ export interface MessageNode<TMessage> {
      */
     serial: string | undefined;
 }
+/**
+ * A Run's lifecycle state, modelled as one discriminated value so the terminal
+ * `error` is carried exactly when `status` is `'error'`. A RunNode is mutated
+ * in place, so status and its dependent error move together — transitions
+ * reassign `node.state` wholesale rather than setting fields individually.
+ */
+export type RunNodeState = {
+    /** `'active'` (streaming), `'suspended'` (paused), or a non-error terminal reason. */
+    status: 'active' | 'suspended' | Exclude<RunEndReason, 'error'>;
+} | {
+    /** Terminal error status. */
+    status: 'error';
+    /**
+     * The run-end's stamped error (or a generic fallback). Exposed to
+     * consumers via `RunInfo.error`.
+     */
+    error: Ably.ErrorInfo;
+};
 /**
  * A node in the conversation tree, representing a single Run.
  *
@@ -155,13 +187,12 @@ export interface RunNode<TProjection> {
      */
     clientId: string;
     /**
-     * Run lifecycle status.
-     * - `'active'` — run-start observed, no terminal event yet.
-     * - `'suspended'` — run-suspend observed; the run is paused awaiting input
-     *   and stays live (a continuation re-activates it). Not terminal.
-     * - {@link RunEndReason} — terminal state reflecting the run-end reason.
+     * Run lifecycle state — see {@link RunNodeState}. `'active'` until a terminal
+     * event; `'suspended'` while paused (a continuation re-activates it);
+     * otherwise the run-end reason, carrying `error` when that reason is
+     * `'error'`.
      */
-    status: 'active' | 'suspended' | RunEndReason;
+    state: RunNodeState;
     /** Per-Run codec projection. Folded by the Tree from every event published under this run-id. */
     projection: TProjection;
     /**
@@ -292,6 +323,17 @@ export interface Tree<TOutput extends CodecOutputEvent, TProjection> {
      * @returns The ordered sibling nodes.
      */
     getSiblingNodes(key: string): ConversationNode<TProjection>[];
+    /**
+     * Look up the raw Ably message that carried the given `event-id` header,
+     * if the Tree has observed it. Populated incrementally as messages arrive
+     * through the Tree's `ably-message` channel; not bounded except by the
+     * Tree's lifetime. Used by the agent's input-event lookup to find a
+     * triggering input message by id without scanning a separate buffer.
+     * @param eventId - The `event-id` header value to look up.
+     * @returns The matching raw Ably message, or undefined when the Tree has
+     *   not observed an event with that id.
+     */
+    findAblyMessageByEventId(eventId: string): Ably.InboundMessage | undefined;
     /**
      * Subscribe to tree structural changes (Run insert, delete, sort-reorder,
      * startSerial promotion, run-start metadata backfill). Does NOT fire on

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

@@ -18,16 +18,8 @@ export interface LoadHistoryOptions {
     /** Max messages per page. Default: 100. */
     limit?: number;
 }
-/**
- * Projection-free, View-facing snapshot of a Run.
- *
- * Exposes the Run facts a UI consumer needs (`runId`, owner `clientId`,
- * lifecycle `status`, `invocationId`) without leaking the codec's
- * opaque per-Run projection or the Tree's structural fields. Callers
- * that need the full Run record (parent / fork relationships, serials,
- * projection) reach `session.tree.getRunNode(runId)` directly.
- */
-export interface RunInfo {
+/** Fields common to every {@link RunInfo} arm. */
+interface RunInfoBase {
     /** The Run's unique identifier. */
     runId: string;
     /**
@@ -35,14 +27,6 @@ export interface RunInfo {
      * when the wire didn't carry an owner client id.
      */
     clientId: string;
-    /**
-     * Run lifecycle status. `'active'` while the Run is streaming;
-     * `'suspended'` while it is paused awaiting input (still live, a
-     * continuation re-activates it); otherwise the {@link RunEndReason} the Run
-     * terminated with. Literal lifecycle vocabulary — UIs that want `'streaming'`
-     * rendering language translate at the component boundary.
-     */
-    status: 'active' | 'suspended' | RunEndReason;
     /**
      * The agent-minted `invocationId` observed for this Run, adopted from the
      * wire `ai-run-start`. Stable across the Run's lifecycle once observed.
@@ -52,6 +36,45 @@ export interface RunInfo {
      */
     invocationId: string;
 }
+/**
+ * Projection-free, View-facing snapshot of a Run.
+ *
+ * Exposes the Run facts a UI consumer needs (`runId`, owner `clientId`,
+ * lifecycle `status`, `invocationId`, and — only when it failed — the terminal
+ * `error`) without leaking the codec's opaque per-Run projection or the Tree's
+ * structural fields. Callers that need the full Run record (parent / fork
+ * relationships, serials, projection) reach `session.tree.getRunNode(runId)`
+ * directly.
+ *
+ * Discriminated on `status`: a Run with `status: 'error'` carries the terminal
+ * `error`; every other status has no `error`. So `info.error` is defined
+ * exactly when `info.status === 'error'`.
+ */
+export type RunInfo = (RunInfoBase & {
+    /**
+     * Run lifecycle status. `'active'` while the Run is streaming;
+     * `'suspended'` while it is paused awaiting input (still live, a
+     * continuation re-activates it); otherwise the non-error terminal
+     * {@link RunEndReason} (`'complete'` or `'cancelled'`). Literal lifecycle
+     * vocabulary — UIs that want `'streaming'` rendering language translate
+     * at the component boundary. The `'error'` terminal status lives on the
+     * other arm of this union, where it is paired with the terminal `error`.
+     */
+    status: 'active' | 'suspended' | Exclude<RunEndReason, 'error'>;
+    /** Never present for a non-error status. */
+    error?: never;
+}) | (RunInfoBase & {
+    /** Terminal error status — the Run ended with {@link RunEndReason} `'error'`, carrying the terminal `error` below. */
+    status: 'error';
+    /**
+     * The terminal error. Carries the agent-stamped `error-code` /
+     * `error-message` detail (or a generic fallback when the run ended in
+     * error without detail), so a UI can show *why* a run failed alongside
+     * its `'error'` status. Mirrors the `Ably.ErrorInfo` delivered via
+     * `ClientSession.on('error')`.
+     */
+    error: Ably.ErrorInfo;
+});
 /**
  * Bundle returned by {@link View.branchSelection} describing the
  * sibling group anchored at a given codec-message-id.
@@ -121,19 +144,22 @@ export interface View<TInput extends CodecInputEvent, TMessage> {
      * the Tree.
      */
     runs(): RunInfo[];
-    /** Whether there are older Runs that can be loaded or revealed. */
+    /** Whether there are older messages that can be loaded or revealed. */
     hasOlder(): boolean;
     /**
-     * Reveal older Runs. Loads from channel history if the tree doesn't have
-     * enough, then advances the pagination window by up to `limit` Runs.
-     * Emits 'update' when the visible list changes.
+     * Reveal exactly `limit` older codecMessages — fewer only when channel history
+     * is exhausted. Loads from channel history when the tree doesn't already hold
+     * `limit` hidden messages, then advances the pagination window. Emits 'update'
+     * when the visible list changes.
      *
-     * The pagination unit is the **Run**, not the message. A single Run
-     * typically contributes more than one message to the flat list returned
-     * by {@link View.getMessages} (e.g. a user prompt + assistant reply
-     * pair). Revealing `limit` Runs may add 1..N messages each to the
-     * visible window.
-     * @param limit - Maximum number of older Runs to reveal. Defaults to 100.
+     * The pagination unit is the **codecMessage**. A node (a user prompt, or a
+     * reply Run) contributes 1..N messages to the flat list returned by
+     * {@link View.getMessages}; the window counts those messages, so a node
+     * straddling the boundary is **partially revealed** — only its newest messages
+     * enter the window — and the page lands exactly on `limit` rather than on a
+     * node boundary. Such a partially-revealed run still appears in
+     * {@link View.runs} and is event-scoped.
+     * @param limit - Number of older codecMessages to reveal. Defaults to 10.
      */
     loadOlder(limit?: number): Promise<void>;
     /**
@@ -220,3 +246,4 @@ export interface View<TInput extends CodecInputEvent, TMessage> {
     /** Tear down the view — unsubscribe from tree events and clear internal state. */
     close(): void;
 }
+export {};

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

@@ -1,5 +1,6 @@
 import { Logger } from '../../logger.js';
 import { Codec, CodecInputEvent, CodecMessage, CodecOutputEvent } from '../codec/types.js';
+import { WireApplier } from './decode-fold.js';
 import { TreeInternal } from './tree.js';
 import { ActiveRun, BranchSelection, RunInfo, RunLifecycleEvent, SendOptions, View } from './types.js';
 /**
@@ -39,13 +40,19 @@ import * as Ably from 'ably';
  */
 export type SendDelegate<TInput extends CodecInputEvent> = (input: TInput[], options: SendOptions | undefined, parentCodecMessageId: string | undefined) => Promise<ActiveRun>;
 /** Options for creating a View. */
-export interface ViewOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+interface ViewOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
     /** The tree to project. */
     tree: TreeInternal<TInput, TOutput, TProjection>;
     /** The Ably channel to load history from. */
     channel: Ably.RealtimeChannel;
-    /** The codec used to project messages, mint regenerate inputs, and decode history. */
+    /** The codec used to project messages and mint regenerate inputs. */
     codec: Codec<TInput, TOutput, TProjection, TMessage>;
+    /**
+     * The Tree's single decode-and-apply engine, owned by the session and
+     * shared with the live decode loop. History replay feeds pages through it
+     * so the one decoder instance sees every route into the Tree.
+     */
+    applier: WireApplier;
     /** Delegate for executing sends through the session. */
     sendDelegate: SendDelegate<TInput>;
     /** Logger for diagnostic output. */
@@ -57,6 +64,7 @@ export declare class DefaultView<TInput extends CodecInputEvent, TOutput extends
     private readonly _tree;
     private readonly _channel;
     private readonly _codec;
+    private readonly _applier;
     private readonly _sendDelegate;
     private readonly _logger;
     private readonly _emitter;
@@ -76,6 +84,16 @@ export declare class DefaultView<TInput extends CodecInputEvent, TOutput extends
      * landed).
      */
     private readonly _regenSelections;
+    /**
+     * Non-head regenerate selections, keyed by the regenerate target's
+     * codec-message-id. Separate from {@link _regenSelections} because a non-head
+     * regenerator parents inside the owner run rather than as a same-parent
+     * sibling, so it lives outside the Tree's `visibleNodes` selection space and
+     * is resolved at extraction (see `_extractMessages`). Value is the selected
+     * member's nodeKey (the owner run id, or a regenerator run id); absent groups
+     * default to the newest regenerator.
+     */
+    private readonly _nonHeadRegenSelections;
     /** Spec: AIT-CT11c — runIds loaded from history but not yet revealed to the UI. */
     private readonly _withheldRunIds;
     /** Snapshot of visible node keys — used to detect structural changes and for selection pinning. */
@@ -99,6 +117,16 @@ export declare class DefaultView<TInput extends CodecInputEvent, TOutput extends
     private _lastHistoryPage;
     /** Buffer of withheld nodes (input + reply), drained newest-first by successive loadOlder() calls. */
     private readonly _withheldBuffer;
+    /**
+     * Message-level trim on top of the run-level pagination window. Runs are
+     * revealed whole (via `_withheldRunIds`/`_withheldBuffer`), so a `loadOlder`
+     * may surface more messages than asked; this is the count of OLDEST messages
+     * of the visible node chain to hide from `getMessages()` so a page lands on
+     * exactly `limit` messages. The boundary run still appears in `runs()` (it's
+     * a revealed node); only its oldest messages are trimmed from the flat list.
+     * Live messages append at the newest end and are never trimmed.
+     */
+    private _hiddenMessageCount;
     /** Unsubscribe functions for tree event subscriptions. */
     private readonly _unsubs;
     /**
@@ -152,36 +180,91 @@ export declare class DefaultView<TInput extends CodecInputEvent, TOutput extends
      */
     private _runByCodecMessageId;
     /**
-     * Extract the flat TMessage[] from a visible node chain.
-     *
-     * In the two-node model the Tree's `visibleNodes` has already selected one
-     * member per sibling group (the chosen edit version, the chosen regenerate
-     * run), so a regenerate is just a sibling reply run that appears in place of
-     * the original. Each visible node contributes its own messages in projection
-     * order; the flat list is their concatenation.
-     *
-     * Deferred caveat: a mid-reply regenerate that replaces a non-head message
-     * inside a multi-message reply run is not expressible as a sibling run in
-     * this model and is not handled here (see the `regenerate-of-multi-message`
-     * golden test).
-     * @param nodes - The visible nodes (inputs + reply runs) in chronological order.
-     * @returns The flat message list, each message paired with its codec-message-id.
+     * The regenerator runs that replaced a non-head message of a reply run. They
+     * file under the target's predecessor (not the owner run's input node), so the
+     * Tree's `visibleNodes` cannot collapse them into the owner's slot; this
+     * surfaces them for the View to resolve and render. Head-message (index 0)
+     * regenerates are excluded - those are whole-reply sibling runs the Tree
+     * already groups.
+     * @param targetCodecMessageId - The regenerate target's (non-head) message id.
+     * @param predecessorCodecMessageId - The codec-message-id immediately before it in the owner run.
+     * @returns The regenerator runs in startSerial order (oldest first).
+     */
+    private _nonHeadRegenerators;
+    /**
+     * Resolve the selected member of a non-head regenerate group anchored at
+     * `targetCodecMessageId`. Members are the owner run `O` (memberNodeKey =
+     * `ownerRunId`, the regenerate target in place) followed by each regenerator
+     * run. Honours an explicit {@link _nonHeadRegenSelections} entry, else
+     * defaults to the latest member (newest regenerator), mirroring the
+     * whole-reply regenerate default.
+     * @param targetCodecMessageId - The regenerate target's message id (the group anchor).
+     * @param ownerRunId - The runId of the run that owns the regenerate target.
+     * @param regenerators - The regenerator runs (oldest first) from `_nonHeadRegenerators`.
+     * @returns The selected member's node key (`ownerRunId` or a regenerator runId).
+     */
+    private _selectedNonHeadMember;
+    /**
+     * Flatten visible nodes to messages, collapsing a non-head regenerate into the
+     * slot it replaces: while emitting a reply run, at each non-head message that
+     * has a selected regenerator, drop that message and the run's tail and emit the
+     * selected regenerator instead (recursive for regen-of-regen). Whole-reply
+     * regenerates need nothing here - visibleNodes already picks the sibling.
+     * @param nodes - Visible nodes (inputs + reply runs), chronological.
+     * @returns The flat message list, each paired with its codec-message-id.
      */
     private _extractMessages;
+    /**
+     * Emit one visible node's messages into `out`, applying non-head regenerate
+     * substitution for a reply run (see `_extractMessages`). Input nodes and runs
+     * with no non-head regenerators emit their projection verbatim.
+     * @param node - The node to emit.
+     * @param out - The accumulating flat message list (mutated in place).
+     * @param consumedRunIds - Set of regenerator runIds already emitted via substitution (mutated in place).
+     */
+    private _emitNodeMessages;
     hasOlder(): boolean;
     /**
-     * Reveal up to `limit` older Runs in this view.
+     * Reveal `limit` more older codecMessages in this view — fewer only when
+     * channel history is exhausted.
      *
-     * The pagination unit is the **Run**, not the message. A single Run
-     * typically materialises into multiple messages (e.g. user + assistant
-     * pair) so revealing `limit` Runs may add several messages to the flat
-     * list returned by {@link getMessages}. Channel pages don't align to
-     * Run boundaries, so {@link _loadUntilVisible} keeps fetching channel
-     * pages until at least `limit` Runs are buffered (or the channel is
-     * exhausted).
-     * @param limit - Maximum number of older Runs to reveal. Defaults to 100.
+     * Internally runs are revealed WHOLE (run-granular withholding), counting
+     * codecMessages to decide how many runs to bring in, then the flat list
+     * returned by {@link getMessages} is trimmed to exactly `limit` more
+     * messages. So a run straddling the boundary still appears in {@link runs}
+     * (it's a revealed node) while only its newest messages show in
+     * `getMessages`. Live messages append at the newest end and are never
+     * trimmed.
+     * @param limit - Number of older codecMessages to reveal. Defaults to 10.
      */
     loadOlder(limit?: number): Promise<void>;
+    /**
+     * Fetch older channel history covering at least `target` more codecMessages,
+     * buffering the older nodes and revealing whole runs. The withheld buffer is
+     * assumed already drained by the caller. Loads the first page when no history
+     * has been fetched yet, otherwise advances to the next older page; the
+     * page-walk inside {@link _revealFromPage} loops until `target` messages are
+     * covered or history runs out. No-op (leaving `_hasMoreHistory` false) once
+     * channel history is exhausted.
+     * @param target - Minimum additional codecMessages this fetch aims to cover.
+     */
+    private _fetchOlder;
+    /**
+     * Find the index in `nodes` (chronological, oldest-first) at which the newest
+     * whole runs covering at least `target` codecMessages begin. Walks newest-first
+     * summing each node's `codec.getMessages(projection)` count; once the running
+     * total reaches `target`, the current node (and everything newer) is the
+     * revealed batch — so whole runs are revealed and the batch may overshoot
+     * `target` (the caller trims). Returns `0` when the nodes hold fewer than
+     * `target` messages — reveal everything.
+     *
+     * Shared by the buffer-drain and history-fetch reveal paths so they agree on
+     * "covering `target` messages".
+     * @param nodes - Candidate nodes, oldest-first.
+     * @param target - Minimum codecMessages the revealed batch must cover.
+     * @returns The split index; `nodes[splitIdx..]` is the revealed batch.
+     */
+    private _messageTailSplitIndex;
     runOf(codecMessageId: string): RunInfo | undefined;
     /**
      * Resolve the reply run currently selected for an input node, honouring the
@@ -203,27 +286,45 @@ export declare class DefaultView<TInput extends CodecInputEvent, TOutput extends
      */
     private _resolveSelectedIndex;
     /**
-     * Resolve the branch point anchored at `codecMessageId`, if any.
-     *
-     * Returns the resolved group `kind` along with the sibling list so the
-     * caller can update the correct selection map without re-entering the
-     * runId-based `select()` dispatch (which biases to fork-of first and
-     * would mis-route a regen-anchor codec-message-id when the owning Run is in
-     * BOTH groups — e.g. R1 owns both a user prompt that got edited and
-     * an assistant that got regenerated).
-     *
-     * Two anchor cases:
-     * - **fork-of** — `codecMessageId` is the first message of a Run in a fork-of
-     *   sibling group (edit-style branch point anchored at the user prompt).
-     * - **regen** — `codecMessageId` is the regen-anchor itself (in the owner Run)
-     *   or content of a regenerator Run (regen-style branch point anchored
-     *   at the assistant slot).
+     * Resolve the branch point anchored at `codecMessageId`, if any, returning the
+     * group `kind` + members + groupRoot so the caller routes to the correct
+     * selection map directly (not via a runId dispatch that would mis-route when
+     * the owning Run is in both a fork-of and a regen group).
      * @param codecMessageId - The codec-message-id to look up.
-     * @returns The kind + sibling list + group key (runId for fork-of,
-     *   anchor codec-message-id for regen), or undefined when `codecMessageId` is not an
-     *   anchor in either group type.
+     * @returns The resolved branch point, or undefined when `codecMessageId`
+     *   anchors no group.
      */
     private _resolveMessageBranchPoint;
+    /**
+     * Resolve a non-head regenerate branch point from a reply-run message, if any.
+     * `codecMessageId` is either (a) a non-head message `M` of its owner run with
+     * regenerators, or (b) a regenerator run's head; both resolve to the same group
+     * anchored at `M` (key matching {@link _nonHeadRegenSelections}).
+     * @param node - The reply run owning `codecMessageId`.
+     * @param ownMessages - That run's projected messages (already extracted).
+     * @param codecMessageId - The slot's codec-message-id (an `M`, or a regenerator head).
+     * @returns The non-head branch point, or undefined when `codecMessageId` anchors none.
+     */
+    private _resolveNonHeadBranchPoint;
+    /**
+     * Build the {@link MessageBranchPoint} for a non-head regenerate group, or
+     * undefined when the anchor has no regenerators. The owner member's
+     * representative is the anchor message (the regenerate target); each
+     * regenerator's is its head message.
+     * @param anchorCodecMessageId - The regenerate target's (non-head) message id.
+     * @param ownerRunId - The runId owning the regenerate target.
+     * @param predecessorCodecMessageId - The codec-message-id immediately before the anchor in the owner run.
+     * @returns The non-head branch point, or undefined when there are no regenerators.
+     */
+    private _buildNonHeadGroup;
+    /**
+     * Project nodes to {@link BranchMember}s for fork-of / whole-reply regen
+     * groups, where each member's branch-arrow representative is its own head
+     * message and its memberNodeKey is its node key.
+     * @param nodes - The sibling nodes.
+     * @returns One member per node that has a head message.
+     */
+    private _nodeHeadMembers;
     send(input: TInput | TInput[], options?: SendOptions): Promise<ActiveRun>;
     /**
      * Auto-select / pin branch selections after a forking send.
@@ -269,28 +370,33 @@ export declare class DefaultView<TInput extends CodecInputEvent, TOutput extends
     close(): void;
     private _loadFirstPage;
     /**
-     * Walk channel history from `page` until at least `limit` new Runs are
-     * observed (or the channel is exhausted), then reveal the newest batch and
-     * withhold the rest. Snapshots the already-visible nodes up front so only
-     * newly-observed Runs count toward `limit`. No-op if the view closed during
-     * the page walk.
+     * Walk channel history from `page` until the newly-observed nodes hold at
+     * least `target` codecMessages (or the channel is exhausted), then reveal the
+     * newest whole runs covering `target` and withhold the rest. Snapshots the
+     * already-visible nodes up front so only newly-observed nodes count toward
+     * `target`. No-op if the view closed during the page walk.
      * @param page - The decoded history page to start from.
-     * @param limit - Max Runs to reveal in this batch.
+     * @param target - Minimum codecMessages to reveal in this batch.
      */
     private _revealFromPage;
     /**
-     * Reveal the newest `limit` Runs from `newVisible` and withhold the rest
-     * so subsequent `loadOlder` calls can drain them. Called by
-     * {@link _revealFromPage} to enforce the Run-unit pagination contract.
-     * @param newVisible - Newly observed Runs from the history fetch.
-     * @param limit - Max Runs to reveal in this batch.
+     * Reveal the newest whole runs covering `target` codecMessages from
+     * `newVisible` and withhold the rest so subsequent `loadOlder` calls can
+     * drain them. Reveal granularity is the whole run; the caller trims the flat
+     * message list (via `_hiddenMessageCount`) to make the visible message count
+     * exact. Called by {@link _revealFromPage}.
+     * @param newVisible - Newly observed nodes (inputs + reply runs) from the history fetch, chronological.
+     * @param target - Minimum codecMessages the revealed batch must cover.
      */
     private _splitReveal;
     /**
-     * Replay a history page's raw messages into the Tree. Dispatches by Ably
-     * message name to run-lifecycle vs. regular wire messages, mirroring the
-     * live `client-session._handleMessage` decode loop. Uses a fresh decoder
-     * since the session's live decoder maintains its own stream-tracker state.
+     * Replay a history page's raw messages into the Tree through the Tree's
+     * single decode-and-apply engine — the same applier (and decoder instance)
+     * the client's live loop uses, so history replay can't drift from it. The
+     * shared decoder's version-guarded trackers make the overlap between the
+     * two routes safe: an in-flight stream that spans the attach boundary is
+     * continued rather than re-started, and content the live route already
+     * incorporated decodes to nothing.
      * @param page - The history page returned by `loadHistory`.
      */
     private _processHistoryPage;
@@ -335,6 +441,17 @@ export declare class DefaultView<TInput extends CodecInputEvent, TOutput extends
      * newest as the selected member.
      */
     private _resolvePendingRegenSelections;
+    /**
+     * Roll `pending` and `auto` non-head regenerate selections forward to the
+     * newest regenerator of their anchor message. Mirrors
+     * {@link _resolvePendingRegenSelections} for the non-head group, which lives in
+     * a separate selection map (anchored by the regenerate target rather than a
+     * sibling-group root): a `user` selection pins and is left untouched; a
+     * `pending`/`auto` slot adopts the newest regenerator once one lands. The
+     * anchor's predecessor — the key the regenerators file under — is recovered
+     * from the owning run's projection.
+     */
+    private _resolvePendingNonHeadRegenSelections;
     private _onTreeAblyMessage;
     private _onTreeRun;
     /**
@@ -352,3 +469,4 @@ export declare class DefaultView<TInput extends CodecInputEvent, TOutput extends
  * @returns A new {@link DefaultView} instance.
  */
 export declare const createView: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>(options: ViewOptions<TInput, TOutput, TProjection, TMessage>) => DefaultView<TInput, TOutput, TProjection, TMessage>;
+export {};