@ably/ai-transport 0.2.0 → 0.3.0

package/dist/core/codec/types.d.ts

@@ -29,8 +29,6 @@ export interface Extras {
 }
 /** Per-write overrides for encoder operations. */
 export interface WriteOptions {
-    /** Override the default clientId for this write. */
-    clientId?: string;
     /** Override the default extras for this write. */
     extras?: Extras;
     /** Message identity for projection routing. Stamped as `codec-message-id`. */
@@ -39,7 +37,7 @@ export interface WriteOptions {
 /**
  * A codec-agnostic description of a discrete Ably message. Used on both sides:
  * - **Encode:** the domain encoder describes what to publish; the encoder core
- *   handles header merging, clientId resolution, and the actual publish.
+ *   handles header merging and the actual publish.
  * - **Decode:** the decoder core extracts these fields from an
  *   `Ably.InboundMessage` before calling domain hooks, keeping hooks free of
  *   Ably SDK types.
@@ -48,7 +46,7 @@ export interface WriteOptions {
  * (strings, objects, etc.) — Ably handles serialization natively.
  */
 export interface MessagePayload {
-    /** Ably message name (e.g. "text", "tool-input", "user-message"). */
+    /** Ably message name — the wire direction (`ai-output` / `ai-input`). */
     name: string;
     /** Message data. Ably handles serialization — strings, objects, and arrays are all valid. */
     data: unknown;
@@ -69,7 +67,7 @@ export interface MessagePayload {
  * concatenated for recovery and prefix-matching on the decoder.
  */
 export interface StreamPayload {
-    /** Ably message name (e.g. "text", "reasoning", "tool-input"). */
+    /** Ably message name — `ai-output` (only outputs stream); not the codec `kind` / stream family. */
     name: string;
     /** Initial or closing data for the stream. Must be a string for append/accumulate semantics. */
     data: string;
@@ -86,7 +84,7 @@ export interface StreamPayload {
  * Accumulates text across appends and tracks lifecycle (open/closed).
  */
 export interface StreamTrackerState {
-    /** Ably message name (e.g. "text", "reasoning", "tool-input"). */
+    /** Ably message name — `ai-output` (only outputs stream); not the codec `kind` / stream family. */
     name: string;
     /** Stream identifier (e.g. chunk.id for text, toolCallId for tool-input). */
     streamId: string;
@@ -102,6 +100,16 @@ export interface StreamTrackerState {
      * Initially set from the first publish, but may be replaced on update.
      */
     transportHeaders: Record<string, string>;
+    /**
+     * Highest `Message.version.serial` incorporated into this tracker.
+     * Versions are lexicographically comparable within one message serial, so
+     * a delivery carrying a version at or below this value is already
+     * incorporated and decodes to nothing. Stamped at first contact (a
+     * never-mutated message's version serial equals the message serial, which
+     * is also the fallback when the version carries no serial) and advanced by
+     * each version-bearing delivery.
+     */
+    version: string;
     /** Whether this stream has been closed (complete or cancelled). */
     closed: boolean;
 }
@@ -111,9 +119,12 @@ export interface StreamTrackerState {
  */
 export interface ReducerMeta {
     /**
-     * Ably channel serial of the message that produced this event. The reducer
-     * uses this for idempotency / dedup: events at or below the projection's
-     * high-water-mark serial must be skipped (no-op return).
+     * Ably channel serial of the wire message that produced this event, or `''`
+     * for a not-yet-sequenced optimistic (local) fold. Ordering context only:
+     * the transport invokes `fold` in canonical serial order and exactly once
+     * per event, so the reducer must not treat a same-or-lower serial as a
+     * replay to skip — ordering and dedup are the transport's job, not the
+     * reducer's.
      */
     serial: string;
     /**
@@ -129,9 +140,14 @@ export interface ReducerMeta {
  * result every time — `fold` is a pure function and the reducer holds no
  * instance state.
  *
- * Idempotency: re-folding an event whose serial has already been incorporated
- * must be a no-op. The reducer is free to store a high-water-mark inside the
- * projection.
+ * Ordering, deduplication, and replay are the transport's responsibility, not
+ * the reducer's. The transport invokes `fold` exactly once per event, in
+ * canonical order — wire messages ascending by serial, events within a wire in
+ * decode order — refolding a node from a fresh `init` when a late wire would
+ * otherwise land out of order. The reducer therefore folds unconditionally: it
+ * must not keep a serial high-water-mark or skip "already-seen" events.
+ * Last-writer-wins for events competing over the same state falls out of fold
+ * order, since the highest-serial event folds last.
  *
  * Mutation: `fold` is allowed to mutate the projection passed in and return
  * it. The caller treats the projection as single-owner and never retains a
@@ -141,26 +157,48 @@ export interface Reducer<TEvent, TProjection> {
     /**
      * Build an empty initial projection. Called once per conversation node — a
      * Run node or a run-less input node — before any of that node's events are
-     * folded.
+     * folded, and again on every refold of that node.
      */
     init(): TProjection;
     /**
      * Fold one TEvent into the projection and return the updated projection.
-     * The reducer may mutate `state` in place.
+     * Invoked exactly once per event, in canonical order; the reducer may mutate
+     * `state` in place.
      */
     fold(state: TProjection, event: TEvent, meta: ReducerMeta): TProjection;
 }
+/**
+ * A decoded event tagged with the wire direction it arrived on. The reducer
+ * folds this union (not a bare `TInput | TOutput`) so it can dispatch on
+ * `direction` rather than inspecting the event's shape. Direction is derived
+ * once, from the Ably message name, at decode time (see `toCodecEvents`) — the
+ * authoritative signal, since a single message is either `ai-input` or
+ * `ai-output` but never both.
+ * @template TInput - The codec's input union.
+ * @template TOutput - The codec's output union.
+ */
+export type CodecEvent<TInput, TOutput> = {
+    /** The event arrived on the `ai-input` wire. */
+    readonly direction: 'input';
+    /** The decoded input event. */
+    readonly event: TInput;
+} | {
+    /** The event arrived on the `ai-output` wire. */
+    readonly direction: 'output';
+    /** The decoded output event. */
+    readonly event: TOutput;
+};
 /** Options passed to a codec's `createEncoder` factory. */
 export interface EncoderOptions {
-    /** Default clientId for all writes. */
-    clientId?: string;
     /** Default extras (e.g. headers) merged into every Ably message. */
     extras?: Extras;
     /** Hook called before each Ably message is published. Mutate the message in place to add transport-level headers under `extras.ai`. */
     onMessage?: (message: Ably.Message) => void;
     /**
-     * Default `codec-message-id` for messages where the event payload doesn't
-     * supply one. Overridden by `WriteOptions.messageId` per-publish.
+     * Fallback domain message id surfaced to output escape hatches as
+     * `ctx.messageId` (e.g. the Vercel `start` hatch injects it when a chunk
+     * carries no `messageId` of its own). Unrelated to the wire
+     * codec-message-id transport header, which `WriteOptions.messageId` stamps.
      */
     messageId?: string;
 }
@@ -174,24 +212,24 @@ export interface EncoderOptions {
 export interface Encoder<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent> {
     /**
      * Encode and publish a single client input on the `ai-input` wire.
-     * Throws synchronously if the codec cannot encode the given input
+     * Rejects if the codec cannot encode the given input
      * variant.
      */
     publishInput(input: TInput, options?: WriteOptions): Promise<void>;
     /**
      * Encode and publish a single agent output on the `ai-output` wire.
-     * Throws synchronously if the codec cannot encode the given output
+     * Rejects if the codec cannot encode the given output
      * variant.
      */
     publishOutput(output: TOutput, options?: WriteOptions): Promise<void>;
     /**
-     * Cancel any in-progress streams and emit a codec-specific cancel signal.
-     * Idempotent across repeated calls — a second `cancel` is a no-op. Must not
-     * be called after `close`; doing so throws because the encoder is already
-     * closed.
-     * @param reason - Optional reason string for the cancellation (e.g. 'cancelled').
+     * Close all in-progress streamed messages as cancelled (status:cancelled) and
+     * flush pending appends. Pure transport mechanics — emits no codec output.
+     * Idempotent: streams already cancelled are not re-appended. Must not be
+     * called after `close`; doing so throws because the encoder is already closed.
+     * Run termination is signalled separately by the transport `ai-run-end` event.
      */
-    cancel(reason?: string): Promise<void>;
+    cancelStreams(): Promise<void>;
     /** Flush pending appends and release encoder resources. */
     close(): Promise<void>;
 }
@@ -212,6 +250,12 @@ export interface DecodedMessage<TInput extends CodecInputEvent, TOutput extends
  * compaction, partial-history page boundary, rewind miss) synthesizes any
  * missing start events before deltas reach the SDK — the reducer always
  * sees a clean `(start, delta*, end)` sequence.
+ *
+ * Trackers are version-guarded: a delivery whose `Message.version.serial`
+ * is at or below the version already incorporated decodes to nothing. One
+ * decoder instance can therefore be shared by the live subscription and
+ * history hydration — whichever route delivers a message's content first
+ * wins, and the other route's covered deliveries are no-ops.
  */
 export interface Decoder<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent> {
     /** Decode one Ably inbound message into the input/output halves. */
@@ -246,10 +290,11 @@ export interface CodecInputEvent {
      * Pointer to another codec-message this input references. The semantic
      * depends on `kind` — for `regenerate`, the assistant codec-message to
      * regenerate; codec-specific `kind`s may give it other meanings. The
-     * input event itself does not create a fork — it requests one. The fork
+     * input event itself does not create a fork — it requests one: the
+     * transport reads `target` off the input (e.g. the client session maps a
+     * regenerate's target into its transport headers) and the fork
      * relationship is established on the agent's response (and on
-     * `ai-run-start`), which the codec encoder maps `target` to via the
-     * wire's `fork-of` header.
+     * `ai-run-start`).
      */
     target?: string;
     /**
@@ -300,7 +345,7 @@ export interface Regenerate extends CodecInputEvent {
  * The core is domain-independent: it knows only that this input amends the
  * assistant at `codecMessageId` and carries a codec-defined `payload`. The
  * shape of `payload` (e.g. the tool-call id and output value) is supplied
- * by the codec via `TPayload` — see the Vercel layer's payload type.
+ * by the codec via `TPayload` (e.g. a tool-call id and output value).
  *
  * Codecs opt in to client-side tool resolution by including this variant
  * in their `TInput` union. Codecs whose domain model doesn't natively
@@ -322,7 +367,7 @@ export interface ToolResult<TPayload> extends CodecInputEvent {
  * Well-known input variant: client-published tool result (failure). The
  * tool ran and failed. Mutates the assistant codec-message addressed by
  * `codecMessageId`. The failure detail (e.g. tool-call id and error text)
- * is the codec's domain `payload` — see the Vercel layer's payload type.
+ * is the codec's domain `payload`.
  * @template TPayload - The codec's domain payload for a tool-result failure.
  */
 export interface ToolResultError<TPayload> extends CodecInputEvent {
@@ -339,7 +384,7 @@ export interface ToolResultError<TPayload> extends CodecInputEvent {
  * codec-message addressed by `codecMessageId` — flipping the targeted
  * tool call from pending-approval to approved or denied. The decision
  * detail (e.g. tool-call id, approved flag, reason) is the codec's domain
- * `payload` — see the Vercel layer's payload type.
+ * `payload`.
  *
  * Codecs may layer approval semantics on top of domain models that don't
  * natively support gating tool execution behind an approval — the codec
@@ -374,6 +419,15 @@ export type ToolResultErrorPayloadOf<TInput> = TInput extends ToolResultError<in
  * @template TInput - The codec's input union.
  */
 export type ToolApprovalResponsePayloadOf<TInput> = TInput extends ToolApprovalResponse<infer P> ? P : never;
+/**
+ * Extract the domain message type (`TMessage`) carried by a codec's
+ * {@link UserMessage} member from its `TInput` union, or `never` if the codec
+ * has no user-message variant. Lets the core well-known input factories type
+ * `createUserMessage` from `TInput` alone, without a separate message type
+ * parameter.
+ * @template TInput - The codec's input union.
+ */
+export type UserMessageOf<TInput> = TInput extends UserMessage<infer M> ? M : never;
 /**
  * Structural base every codec output variant must satisfy. The output
  * counterpart of {@link CodecInputEvent}: pins a `type` discriminator so
@@ -382,9 +436,8 @@ export type ToolApprovalResponsePayloadOf<TInput> = TInput extends ToolApprovalR
  * fields on outputs without a breaking generic-arity change.
  *
  * The `type` discriminator is required on every variant so the codec's
- * reducer can switch on it. `AI.UIMessageChunk` already satisfies this
- * constraint structurally — its `type` literal is assignable to
- * `string` — so the Vercel codec needs no implementation changes.
+ * reducer can switch on it — any domain union whose members carry a `type`
+ * string literal satisfies it structurally.
  *
  * No routing fields today: outputs carry no per-event `codecMessageId` /
  * `parent` / `forkOf` overrides. Those move onto this base when a concrete
@@ -428,7 +481,13 @@ export interface CodecMessage<TMessage> {
  * - `TMessage` — the per-message shape consumed by the Tree. Returned from
  *   {@link Codec.getMessages}.
  */
-export interface Codec<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> extends Reducer<TInput | TOutput, TProjection> {
+export interface Codec<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> extends Reducer<CodecEvent<TInput, TOutput>, TProjection> {
+    /**
+     * Optional Ably-Agent identifier. When present, the agent-registration path
+     * registers it on the channel (so traffic is attributed to this codec); when
+     * absent, the codec opts out of registration. Read directly by `registerAgent`.
+     */
+    readonly adapterTag?: string;
     /** Create a stateful encoder bound to the given channel. */
     createEncoder(channel: ChannelWriter, options?: EncoderOptions): Encoder<TInput, TOutput>;
     /** Create a stateful decoder for converting Ably inbound messages into typed inputs and outputs. */

package/dist/core/codec/well-known-inputs.d.ts

@@ -0,0 +1,52 @@
+import { CodecInputEvent, Regenerate, ToolApprovalResponse, ToolApprovalResponsePayloadOf, ToolResult, ToolResultError, ToolResultErrorPayloadOf, ToolResultPayloadOf, UserMessage, UserMessageOf } from './types.js';
+/**
+ * The well-known input factory functions, payload-typed for a codec's `TInput`
+ * union. A codec spreads these into its definition rather than re-implementing
+ * the variant-wrapping boilerplate. Each factory returns the specific variant
+ * it builds — a member of the codec's `TInput` union.
+ * @template TInput - The codec's input union.
+ */
+export interface WellKnownInputFactories<TInput extends CodecInputEvent> {
+    /**
+     * Wrap a domain message as the codec's {@link UserMessage} variant.
+     * @param message - The message in the codec's domain representation.
+     * @returns The user-message input.
+     */
+    createUserMessage(message: UserMessageOf<TInput>): UserMessage<UserMessageOf<TInput>>;
+    /**
+     * Build a {@link Regenerate} input.
+     * @param target - The codec-message-id of the assistant message to regenerate.
+     * @param parent - The codec-message-id of the parent user message the new assistant threads under.
+     * @returns The regenerate input.
+     */
+    createRegenerate(target: string, parent: string): Regenerate;
+    /**
+     * Build a {@link ToolResult} input addressing an assistant codec-message.
+     * @param codecMessageId - The assistant codec-message carrying the tool call.
+     * @param payload - The codec's domain payload describing the tool result.
+     * @returns The tool-result input.
+     */
+    createToolResult(codecMessageId: string, payload: ToolResultPayloadOf<TInput>): ToolResult<ToolResultPayloadOf<TInput>>;
+    /**
+     * Build a {@link ToolResultError} input addressing an assistant codec-message.
+     * @param codecMessageId - The assistant codec-message carrying the tool call.
+     * @param payload - The codec's domain payload describing the failure.
+     * @returns The tool-result-error input.
+     */
+    createToolResultError(codecMessageId: string, payload: ToolResultErrorPayloadOf<TInput>): ToolResultError<ToolResultErrorPayloadOf<TInput>>;
+    /**
+     * Build a {@link ToolApprovalResponse} input addressing an assistant codec-message.
+     * @param codecMessageId - The assistant codec-message carrying the tool call.
+     * @param payload - The codec's domain payload describing the approval decision.
+     * @returns The tool-approval-response input.
+     */
+    createToolApprovalResponse(codecMessageId: string, payload: ToolApprovalResponsePayloadOf<TInput>): ToolApprovalResponse<ToolApprovalResponsePayloadOf<TInput>>;
+}
+/**
+ * Build the {@link WellKnownInputFactories} for a codec's `TInput` union. The
+ * returned factories wrap domain values into the well-known input variants and
+ * are typically spread into a codec definition.
+ * @template TInput - The codec's input union.
+ * @returns The well-known input factory functions, payload-typed to `TInput`.
+ */
+export declare const wellKnownInputs: <TInput extends CodecInputEvent>() => WellKnownInputFactories<TInput>;

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

@@ -0,0 +1,296 @@
+import { Logger } from '../../logger.js';
+import { Codec, CodecInputEvent, CodecOutputEvent } from '../codec/types.js';
+import { WireApplier } from './decode-fold.js';
+import { TreeInternal } from './tree.js';
+import { ConversationNode, Tree } from './types.js';
+/**
+ * AgentView — internal, server-side message-loading + input-event lookup for
+ * AgentSession.
+ *
+ * Encapsulates everything the agent needs to read conversation state off the
+ * channel: locating the triggering input event before `run-start`
+ * ({@link AgentView.findInputEvent}), and reconstructing the ancestor chain for
+ * an LLM prompt ({@link AgentView.loadConversation} / {@link AgentView.messages}).
+ *
+ * It does NOT own the materialisation Tree — AgentSession owns the Tree and the
+ * applier (and swaps them on channel continuity loss) and injects them here as
+ * `readonly` fields, the same way ClientSession wires `DefaultView`. Because
+ * AgentSession swaps the Tree, it RECREATES the AgentView on continuity loss
+ * (a fresh instance bound to the fresh Tree/applier) rather than mutating it —
+ * so this class never needs a tree accessor or a reset hook.
+ *
+ * This is deliberately internal: it is not exported from any entry point and
+ * does NOT implement the public `View` interface (that is the client-side
+ * `DefaultView`, unrelated to this class).
+ *
+ * Both `findInputEvent` and `loadConversation` drive ONE history-walk mechanism
+ * — the single-flight chain in {@link AgentView._driveHistoryChain} — so a
+ * `start()` input scan and a concurrent `loadConversation` share folded pages
+ * instead of each scanning the channel.
+ */
+import * as Ably from 'ably';
+/**
+ * Result of {@link AgentView.findInputEvent}. The lookup races the session's
+ * Tree (`findAblyMessageByEventId` pre-scan + `'ably-message'` event for live
+ * arrivals) against a bounded history scan; resolves with the matched messages
+ * sorted by Ably `serial` ascending.
+ *
+ * Run.start reads `firstHeaders` / `firstClientId` from the smallest-serial
+ * matched message to derive per-run metadata (run-id, parent, forkOf,
+ * continuation flag, publisher clientId). The Tree has already folded each
+ * message by the time the lookup resolves, so callers do NOT need to decode the
+ * raw matched messages themselves.
+ */
+export interface InputEventLookupResult {
+    /** Raw Ably messages matched by the lookup, sorted by serial ascending. */
+    rawMessages: Ably.InboundMessage[];
+    /** Transport headers of the smallest-serial matched message (run metadata). */
+    firstHeaders?: Record<string, string>;
+    /** Publisher's Ably channel-level `clientId` from the smallest-serial message. */
+    firstClientId?: string;
+}
+/**
+ * Walk parent pointers from an anchor codec-message-id back through the
+ * Tree to the conversation root, returning nodes in root-first order. When
+ * `maxRuns` is set, the walk stops before the RunNode that would exceed the
+ * bound, so the bounding run's own input node(s) are still included (input
+ * nodes never count toward the bound). The chain therefore starts with the
+ * input that triggered its oldest run, never with an assistant reply.
+ *
+ * Returns an empty array when the anchor isn't in the Tree.
+ * @param tree - The materialisation tree to walk.
+ * @param anchor - The codec-message-id to start from (typically the current run's input).
+ * @param maxRuns - Optional bound on the number of ancestor reply RunNodes in the chain.
+ * @param currentRunId - The current run's id. Its own RunNode (reachable when
+ * the anchor's wire carried the run-id) is conversation tail, not ancestor
+ * context, so it never counts toward `maxRuns`.
+ * @returns Nodes from root to anchor in chronological order.
+ */
+export declare const walkAncestorChain: <TOutput extends CodecOutputEvent, TProjection>(tree: Tree<TOutput, TProjection>, anchor: string | undefined, maxRuns?: number, currentRunId?: string) => readonly ConversationNode<TProjection>[];
+/**
+ * Constructor dependencies for {@link AgentView}, injected by AgentSession.
+ *
+ * AgentView holds `tree` + `applier` directly (like `DefaultView`). AgentSession
+ * owns them and, because it SWAPS the Tree on continuity loss, recreates the
+ * AgentView with the fresh Tree/applier rather than mutating them in place.
+ */
+export interface AgentViewOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /** The session's materialisation Tree (read for walks; folded into by history). */
+    tree: TreeInternal<TInput, TOutput, TProjection>;
+    /** The Ably channel to read history from. */
+    channel: Ably.RealtimeChannel;
+    /** Codec used to project per-node messages. */
+    codec: Codec<TInput, TOutput, TProjection, TMessage>;
+    /** The Tree's decode-and-apply engine; history pages fold through it. */
+    applier: WireApplier;
+    /** Logger for diagnostic output. */
+    logger?: Logger;
+    /**
+     * Age bound for the input-event scan: the scan gives up paging once it
+     * crosses `Date.now() - inputEventLookbackMs`. Applied only to
+     * `findInputEvent`, never to the ancestor-hydration walk.
+     */
+    inputEventLookbackMs: number;
+}
+/**
+ * Internal server-side view: input-event lookup + conversation loading over the
+ * session Tree. See the file header for the ownership boundary.
+ */
+export declare class AgentView<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    private readonly _tree;
+    private readonly _channel;
+    private readonly _codec;
+    private readonly _applier;
+    private readonly _logger?;
+    private readonly _inputEventLookbackMs;
+    /**
+     * Tail of the single-flight history-hydration chain. Each walk links behind
+     * the current tail and becomes the new tail, so concurrent calls serialise
+     * and share each other's folded pages instead of each scanning the channel.
+     * A link never rejects (it records its error locally), so a follower awaiting
+     * the tail is isolated from a prior link's failure.
+     */
+    private _hydrationMutex;
+    /**
+     * Shared history-walk cursor for this AgentView's attach epoch — ONE backward
+     * `untilAttach` pagination that both `findInputEvent` and `loadConversation`
+     * advance. `findInputEvent` pages it until the trigger is found (or its
+     * lookback give-up point) and pauses; `loadConversation` resumes from that
+     * position instead of re-paging from newest, so the channel is walked once.
+     * Created lazily on first use (no per-caller signal, so it outlives any one
+     * caller; no lookback, so it can reach attach). The single-flight chain
+     * (`_hydrationMutex`) serialises access so it is never paged concurrently. A
+     * continuity-loss swap recreates the whole AgentView, so there is no in-place
+     * reset.
+     */
+    private _cursor;
+    /**
+     * True once the shared cursor reached attach (channel exhausted). Because the
+     * cursor carries no lookback, its exhaustion is always genuine (never a
+     * lookback boundary), so either caller may record it; a lookback-bounded
+     * `findInputEvent` scan stops via an early `break` that leaves the cursor
+     * non-exhausted, so it never sets this.
+     */
+    private _historyExhausted;
+    constructor(options: AgentViewOptions<TInput, TOutput, TProjection, TMessage>);
+    /**
+     * Fold a single wire message into the Tree: decode-and-apply via the applier,
+     * then notify Tree subscribers and populate the event-id index. Mirrors
+     * AgentSession's live `_foldWire`; history pages fold through this.
+     * @param wire - The inbound Ably message to fold.
+     */
+    private _foldWire;
+    /**
+     * Find every message whose `event-id` matches one of `expectedEventIds`,
+     * racing three sources:
+     *
+     *  1. A pre-scan of the Tree via `findAblyMessageByEventId` for messages already
+     *     folded into it from prior live arrivals.
+     *  2. A live listener on the Tree's `ably-message` event for new arrivals
+     *     during the call.
+     *  3. The shared history walk (lookback-bounded) — pages fold into the Tree
+     *     and surface through the same `ably-message` event.
+     *
+     * Resolves when every expected event-id has been matched. Per-id race
+     * resolution — whichever source surfaces a matched message first wins
+     * (dedup by serial). On timeout: cancels the in-flight history scan and
+     * rejects with `InputEventNotFound`, wrapping any history-scan failure as
+     * `cause` so a broken history fetch isn't masked behind the timeout. On
+     * signal abort: rejects with `InvalidArgument`.
+     *
+     * `firstHeaders` and `firstClientId` are read from the matched message with
+     * the smallest serial (`compareBySerial`), giving stable run-level
+     * metadata regardless of arrival ordering across sources.
+     * @param opts - Lookup parameters.
+     * @param opts.invocationId - The invocation id this lookup is for (logging / error messages).
+     * @param opts.runId - The run id this lookup is for (logging / error messages).
+     * @param opts.expectedEventIds - The set of `event-id`s the lookup must observe before resolving.
+     * @param opts.timeoutMs - Maximum total wait across live + history sources.
+     * @param opts.signal - AbortSignal that aborts the lookup if the run is cancelled.
+     * @returns Raw matched Ably messages sorted by serial ascending, plus the
+     *   smallest-serial message's headers and clientId for downstream metadata.
+     */
+    findInputEvent(opts: {
+        invocationId: string;
+        runId: string;
+        expectedEventIds: readonly string[];
+        timeoutMs: number;
+        signal: AbortSignal;
+    }): Promise<InputEventLookupResult>;
+    /**
+     * Reconstruct the conversation by walking the parent chain from the run's
+     * input node back to the conversation root, reading already-folded
+     * projections off the Tree's nodes.
+     *
+     * Hydrates the Tree as needed via the shared history walk
+     * ({@link AgentView._hydrateAncestors}), then concatenates
+     * `codec.getMessages(node.projection)` per node (root first) and appends the
+     * current run's projection at the tail.
+     * @param runId - The current run's id (for the tail run's projection lookup).
+     * @param assistantParentFallback - The current run's input node codec-message-id.
+     * @param signal - AbortSignal; rejects with InvalidArgument when aborted.
+     * @param maxRuns - Optional bound on the parent walk; counts reply RunNodes.
+     * @param runIdAdopted - True when the run-id came from outside (runtime
+     *   override or continuation), so its node may exist in channel history;
+     *   false for agent-minted ids, whose run-start only ever arrives via the
+     *   live echo.
+     * @param regenerateTarget - The codec-message-id being regenerated, or
+     *   undefined; the run that owns it is flattened only up to that message so
+     *   the reconstructed history stops before the assistant message being
+     *   replaced (which the model would otherwise reject).
+     * @returns The branch's messages (root-first) and the current run's projection.
+     */
+    loadConversation(runId: string, assistantParentFallback: string | undefined, signal: AbortSignal, maxRuns: number | undefined, runIdAdopted: boolean, regenerateTarget?: string): Promise<{
+        messages: TMessage[];
+        projection: TProjection;
+    }>;
+    /**
+     * Walk the parent chain from `anchor` over the current Tree and concatenate
+     * each node's projected messages (root-first), then append the current run's
+     * own messages when its RunNode isn't already on the chain. Shared by
+     * {@link AgentView.loadConversation} and {@link AgentView.messages}. Pure read
+     * over whatever is currently folded — no fetching.
+     * @param runId - The current run's id (for the tail run's projection lookup).
+     * @param anchor - The current run's input node codec-message-id.
+     * @param maxRuns - Optional bound on the ancestor walk (counts reply runs).
+     * @param regenerateTarget - The codec-message-id being regenerated; when set,
+     *   the walk stops before that message (a regenerate of a non-head message
+     *   anchors at the target's predecessor, so flattening its run whole would
+     *   re-emit the target and end the history on the message being replaced).
+     * @returns The conversation messages (root-first) and the current run's
+     *   projection (the codec's empty init when the run has no node yet).
+     */
+    private _collectConversation;
+    /**
+     * Synchronous live read of the conversation messages for `Run.messages`:
+     * walk the parent chain from `anchor` (no `maxRuns` bound), concatenate each
+     * ancestor's projection, then append the current run's messages if its node
+     * isn't already on the chain. No I/O — reflects whatever is currently folded.
+     * @param runId - The current run's id (for the tail run's projection lookup).
+     * @param anchor - The current run's input node codec-message-id (assistantParentFallback).
+     * @param regenerateTarget - The codec-message-id being regenerated; when set,
+     *   the walk stops before it (see {@link AgentView._collectConversation}).
+     * @returns The conversation messages, root-first.
+     */
+    messages(runId: string, anchor: string | undefined, regenerateTarget?: string): TMessage[];
+    /**
+     * Single-flight chain entry shared by `findInputEvent` and `loadConversation`.
+     * Serialises behind any in-flight walk so the shared cursor is advanced by one
+     * caller at a time (never paged concurrently), then runs one
+     * {@link AgentView._walkSharedHistory}. A link never rejects (it records its
+     * error locally), so a follower awaiting the chain tail is isolated from a
+     * prior link's failure; this method rethrows the wrapped error from its own
+     * frame after awaiting.
+     *
+     * Returns `exhausted` but never records `_historyExhausted`; the caller records
+     * it (both callers may, since the shared cursor's exhaustion is always genuine
+     * — see {@link AgentView._historyExhausted}).
+     * @param shouldStop - Polled before each page; true pauses this walk.
+     * @param signal - Per-call abort signal (checked between pages).
+     * @param lookbackMs - Optional give-up bound for the input scan (early break).
+     * @param operationLabel - Verb for the wrapped error message.
+     * @returns `{ exhausted }` — true only when the shared cursor reached attach.
+     */
+    private _driveHistoryChain;
+    /**
+     * Advance the SHARED history cursor (lazily opening it once per attach epoch)
+     * and fold each page into the session Tree via the injected `fold`, stopping
+     * when `shouldStop()` returns true, the channel is exhausted, the signal
+     * aborts, a continuity-loss Tree swap abandons the walk, or — when `lookbackMs`
+     * is given — the walk pages past the lookback window. The cursor is NOT closed
+     * on stop: it stays paused at its current position so a later caller resumes
+     * from there rather than re-paging from newest. Throws (caller-wrapped) on a
+     * fetch failure after `loadHistoryPages`' per-page retries.
+     * @param shouldStop - Polled before each page; true pauses the walk.
+     * @param signal - Per-call abort signal (checked between pages; the shared cursor carries none).
+     * @param lookbackMs - Optional give-up bound: stop paging once a page's oldest
+     *   message predates `Date.now() - lookbackMs`. An early `break`, NOT a cursor
+     *   bound, so the cursor stays resumable and exhaustion is never reported here.
+     * @returns True only when the cursor genuinely reached attach — NOT when
+     *   paused by the predicate / lookback, a Tree swap, or signal abort.
+     */
+    private _walkSharedHistory;
+    /**
+     * Populate the Tree with enough ancestor coverage to walk from `anchor` to
+     * root (or `maxRuns` reply runs back) by driving the shared history walk.
+     * Records `_historyExhausted` only when a FULL (no-lookback) walk genuinely
+     * exhausts the channel.
+     * @param runId - The current run's id (when adopted, its node must be present in the Tree before the walk is complete).
+     * @param anchor - The input codec-message-id to walk from. Undefined means no walk is needed (current run only).
+     * @param signal - AbortSignal.
+     * @param maxRuns - Optional bound on the ancestor walk.
+     * @param runIdAdopted - Whether the run-id came from outside (override or continuation) and so may name a run present in channel history.
+     * @throws {Ably.ErrorInfo} `InvalidArgument` when `signal` aborts;
+     *   `HistoryFetchFailed` — or the underlying Ably code when the failure
+     *   carried one — (original as `cause`) when this caller's own history
+     *   fetch fails after retries.
+     */
+    private _hydrateAncestors;
+}
+/**
+ * Create an {@link AgentView}. Factory entry point mirroring `createTree`;
+ * AgentSession never calls `new AgentView` directly.
+ * @param options - Injected dependencies.
+ * @returns A new AgentView.
+ */
+export declare const createAgentView: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>(options: AgentViewOptions<TInput, TOutput, TProjection, TMessage>) => AgentView<TInput, TOutput, TProjection, TMessage>;