@ably/ai-transport 0.1.0 → 0.3.0

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-session.d.ts

@@ -0,0 +1,10 @@
+import { CodecInputEvent, CodecOutputEvent } from '../codec/types.js';
+import { AgentSession, AgentSessionOptions } from './types.js';
+/**
+ * Create an agent (server-side) session bound to the given Realtime client
+ * and channel name. The caller owns the client's lifecycle; the session
+ * owns its channel.
+ * @param options - Session configuration.
+ * @returns A new {@link AgentSession} instance.
+ */
+export declare const createAgentSession: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>(options: AgentSessionOptions<TInput, TOutput, TProjection, TMessage>) => AgentSession<TOutput, TProjection, TMessage>;

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>;

package/dist/core/transport/client-session.d.ts

@@ -0,0 +1,13 @@
+import { CodecInputEvent, CodecOutputEvent } from '../codec/types.js';
+import { ClientSession, ClientSessionOptions } from './types.js';
+/**
+ * Create a client-side session that manages conversation state over an Ably channel.
+ *
+ * The caller owns the client's lifecycle; the session owns its channel.
+ * The session is created in a not-yet-connected state — callers must
+ * `await session.connect()` before `send`, `regenerate`, `edit`, `update`,
+ * or `cancel`.
+ * @param options - Configuration for the client session.
+ * @returns A new {@link ClientSession} instance.
+ */
+export declare const createClientSession: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>(options: ClientSessionOptions<TInput, TOutput, TProjection, TMessage>) => ClientSession<TInput, TOutput, TProjection, TMessage>;

package/dist/core/transport/decode-fold.d.ts

@@ -0,0 +1,55 @@
+import { CodecInputEvent, CodecOutputEvent, Decoder } from '../codec/types.js';
+import { TreeInternal } from './tree.js';
+import { RunLifecycleEvent } from './types.js';
+/**
+ * Shared wire decode-and-apply engine.
+ *
+ * The client's live decode loop and the View's history replay both reconstruct
+ * the conversation Tree from the same raw Ably wire log. This module is the one
+ * place that classifies a wire message (run-lifecycle vs codec-decoded), parses
+ * or decodes it, and applies it to the Tree — so the two paths can never drift.
+ *
+ * The engine is exposed as a {@link WireApplier} binding one Tree to one
+ * decoder. A Tree has exactly one applier (the session constructs it and hands
+ * it to every View), so every route a wire message can arrive by — the live
+ * subscription, View history pagination, the agent's hydration walks — feeds
+ * the same decoder. The decoder's version-guarded stream trackers then make
+ * re-delivery across routes (an attach-boundary in-flight stream, a replayed
+ * history page) decode to nothing instead of double-folding. The delivery's
+ * `version.serial` is also threaded into the Tree, whose per-entry
+ * `decodedThrough` high-water-mark drops whole-wire replays that no decoder
+ * state can see (stateless discrete re-decodes).
+ */
+import type * as Ably from 'ably';
+/**
+ * The decode-and-apply engine for one Tree: a single codec decoder bound to a
+ * single Tree, shared by every route that feeds the Tree wire messages.
+ */
+export interface WireApplier {
+    /**
+     * Apply one inbound wire message to the bound tree.
+     *
+     * Run-lifecycle messages are turned into a {@link RunLifecycleEvent} via
+     * {@link parseRunLifecycle} and applied with `applyRunLifecycle`; everything
+     * else is decoded with the bound decoder and applied with `applyMessage`,
+     * skipping wire-only carriers that decode to no events and carry no run-id
+     * (the eventual reply run is created later by its run-start).
+     *
+     * Does NOT emit the tree's `ably-message` event — the caller owns that,
+     * because the live loop emits per message while history replay emits in a
+     * batch once the whole page is applied. Returns the parsed lifecycle event
+     * so a live caller can run its own side-effects (resolving a pending
+     * run-start, surfacing an agent error); returns `undefined` for a
+     * codec-decoded message or a lifecycle message that carried no run-id.
+     * @param rawMsg - The inbound Ably wire message.
+     * @returns The parsed run-lifecycle event, or `undefined`.
+     */
+    apply(rawMsg: Ably.InboundMessage): RunLifecycleEvent | undefined;
+}
+/**
+ * Bind a Tree and a decoder into the Tree's single {@link WireApplier}.
+ * @param tree - The tree the applier feeds.
+ * @param decoder - The codec decoder shared by every route into the tree.
+ * @returns The applier.
+ */
+export declare const createWireApplier: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection>(tree: TreeInternal<TInput, TOutput, TProjection>, decoder: Decoder<TInput, TOutput>) => WireApplier;

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

@@ -1,28 +1,135 @@
+import { EVENT_RUN_END, EVENT_RUN_RESUME, EVENT_RUN_START, EVENT_RUN_SUSPEND } from '../../constants.js';
+import { RunEndReason, RunLifecycleEvent } from './types.js';
 /**
  * Transport header builder.
  *
- * Single source of truth for which `x-ably-*` headers every transport
- * message carries. Used by the server transport (addMessages, streamResponse)
- * and will be used by the client transport (optimistic message stamping).
+ * Single source of truth for which transport headers every transport
+ * message carries. Used by the agent session (pipe) and by
+ * the client session (optimistic message stamping).
  */
+import * as Ably from 'ably';
 /**
  * Build the standard transport header set for a message.
  * @param opts - The header values to include.
  * @param opts.role - Message role (e.g. "user", "assistant").
- * @param opts.turnId - Turn correlation ID.
- * @param opts.msgId - Message identity.
- * @param opts.turnClientId - ClientId of the turn initiator.
- * @param opts.parent - Preceding message's msg-id (for branching).
- * @param opts.forkOf - Forked message's msg-id (for edit/regen).
- * @param opts.amend - The msg-id of the existing message this message targets (cross-turn events).
- * @returns A headers record with the `x-ably-*` transport headers set.
+ * @param opts.runId - Run correlation ID, or `undefined` for a fresh client
+ *   input (the agent mints run-ids, so it is not known synchronously). Omitted
+ *   from the headers when undefined; a continuation still carries the known run-id.
+ * @param opts.codecMessageId - Message identity — the wire `codec-message-id` for this message.
+ * @param opts.runClientId - ClientId of the run initiator.
+ * @param opts.parent - Preceding message's codec-message-id (for branching).
+ * @param opts.forkOf - Forked user-prompt's codec-message-id (for edits — creates a Run-level fork sibling).
+ * @param opts.regenerates - Assistant codec-message-id this run regenerates. Stamps
+ *   `msg-regenerate`. Distinct from `forkOf`: regenerate is a
+ *   continuation of the prior run (no Run-level fork), with the message
+ *   replacement resolved at projection extraction time.
+ * @param opts.invocationId - Agent-minted invocation id. Stamped by the agent on every event it publishes for the invocation (run lifecycle + outputs) so the client can observe it; not set by the client on the input.
+ * @param opts.inputClientId - ClientId of the input event (the `ai-input`) that
+ *   drove the current invocation. The agent reads it from the publisher's
+ *   Ably-level `clientId` on the matched input event and re-stamps it on its
+ *   own publishes (run lifecycle + outputs). Differs from `runClientId` on
+ *   continuation invocations driven by an input from a non-owner.
+ * @param opts.inputEventId - Per-event identifier. Set on each client-published user-prompt message; the invocation body's `inputEventIds` lists the ids the agent should look up.
+ * @param opts.inputCodecMessageId - The codec-message-id of the input event that
+ *   triggered the current invocation (the one whose `event-id` matched the
+ *   invocation's `inputEventId`). The agent re-stamps it on every event it
+ *   publishes for the invocation (run lifecycle + outputs), mirroring
+ *   `inputClientId`, so the client can correlate any of those events back to
+ *   the originating input by the id it owned at send time.
+ * @returns A headers record with the transport headers set.
  */
 export declare const buildTransportHeaders: (opts: {
     role: string;
-    turnId: string;
-    msgId: string;
-    turnClientId?: string;
+    runId?: string;
+    codecMessageId: string;
+    runClientId?: string;
     parent?: string;
     forkOf?: string;
-    amend?: string;
+    regenerates?: string;
+    invocationId?: string;
+    inputClientId?: string;
+    inputCodecMessageId?: string;
+    inputEventId?: string;
 }) => Record<string, string>;
+/**
+ * Build the transport header set for a run-lifecycle event (run-start,
+ * run-resume, run-suspend, run-end). Single source of truth for lifecycle
+ * header stamping, mirroring {@link buildTransportHeaders} for the
+ * message-carrier path. Every field except `runId`/`runClientId` is optional
+ * and omitted when not provided.
+ *
+ * A resume suppresses the structural `parent` / `forkOf` / `regenerates`
+ * headers — the caller passes them only for a fresh run-start. `reason` is
+ * stamped only on run-end.
+ * @param opts - The lifecycle header values to include.
+ * @param opts.runId - The run's id.
+ * @param opts.runClientId - ClientId of the run initiator (empty string when unknown).
+ * @param opts.parent - Structural parent codec-message-id (fresh run-start only).
+ * @param opts.forkOf - Forked user-prompt codec-message-id (fresh run-start only).
+ * @param opts.regenerates - Regenerated assistant codec-message-id (fresh run-start only).
+ * @param opts.invocationId - Agent-minted invocation id; carried on every lifecycle event.
+ * @param opts.inputClientId - ClientId of the triggering input event.
+ * @param opts.inputCodecMessageId - Codec-message-id of the triggering input event.
+ * @param opts.reason - Terminal reason; stamped on run-end only.
+ * @param opts.errorCode - Numeric error code stamped as `error-code` on
+ *   run-end. Set only when the run ended in error and the agent supplied an
+ *   error to surface; gives codec-agnostic consumers a baseline failure detail.
+ * @param opts.errorMessage - Error message stamped as `error-message` on
+ *   run-end. Paired with `errorCode`; set under the same condition.
+ * @returns A headers record with the lifecycle headers set.
+ */
+export declare const buildLifecycleHeaders: (opts: {
+    runId: string;
+    runClientId: string;
+    parent?: string;
+    forkOf?: string;
+    regenerates?: string;
+    invocationId?: string;
+    inputClientId?: string;
+    inputCodecMessageId?: string;
+    reason?: RunEndReason;
+    errorCode?: number;
+    errorMessage?: string;
+}) => Record<string, string>;
+/** The four run-lifecycle Ably message names. */
+type RunLifecycleName = typeof EVENT_RUN_START | typeof EVENT_RUN_SUSPEND | typeof EVENT_RUN_RESUME | typeof EVENT_RUN_END;
+/**
+ * Whether an Ably message `name` is one of the run-lifecycle event names
+ * (run-start / run-suspend / run-resume / run-end). Single source of truth for
+ * the classification both decode loops and the agent's history scan use to
+ * route lifecycle wires away from the codec decoder. Narrows `name` to a
+ * lifecycle name so callers can pass it straight to {@link parseRunLifecycle}.
+ * @param name - The inbound Ably message `name`, or undefined.
+ * @returns True when `name` is a run-lifecycle event name.
+ */
+export declare const isRunLifecycleName: (name: string | undefined) => name is RunLifecycleName;
+/**
+ * Reconstruct the terminal `Ably.ErrorInfo` for a run that ended in error, from
+ * its run-end transport headers. Reads the `error-code` / `error-message`
+ * headers the agent stamps (see {@link buildLifecycleHeaders}); falls back to a
+ * generic code/message when a run ended in error without detail. Single source
+ * of truth for the header→ErrorInfo derivation, shared by the client session's
+ * `on('error')` emit and the Tree's `RunInfo.error`.
+ * @param headers - Transport headers from the inbound run-end message.
+ * @returns The reconstructed terminal error.
+ */
+export declare const buildRunEndError: (headers: Record<string, string>) => Ably.ErrorInfo;
+/**
+ * Parse an inbound run-lifecycle Ably message into a {@link RunLifecycleEvent}.
+ *
+ * Single source of truth for turning the wire run-lifecycle message `name`,
+ * transport headers, and channel serial into the structured lifecycle event
+ * the Tree consumes. Used by the client decode loop (live) and the View's
+ * history replay so both build the event identically.
+ * @param name - The inbound Ably message `name`.
+ * @param headers - Transport headers from the inbound Ably message.
+ * @param serial - Ably channel serial of the message, or `undefined` for an
+ *   optimistic local event. Stamped onto the returned event.
+ * @param timestamp - Ably server timestamp (epoch ms) of the message, or
+ *   `undefined` for an optimistic local event. Stamped onto the returned
+ *   event; drives the Tree's event-log retention clock.
+ * @returns The lifecycle event, or `undefined` when `name` is not a
+ *   run-lifecycle event name or the message carries no `run-id`.
+ */
+export declare const parseRunLifecycle: (name: string, headers: Record<string, string>, serial: string | undefined, timestamp: number | undefined) => RunLifecycleEvent | undefined;
+export {};

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

@@ -1,7 +1,6 @@
-export type { ActiveTurn, AddMessageOptions, AddMessagesResult, CancelFilter, CancelRequest, ClientTransport, ClientTransportOptions, CloseOptions, EventsNode, MessageNode, NewTurnOptions, SendOptions, ServerTransport, ServerTransportOptions, StreamResponseOptions, StreamResult, Tree, Turn, TurnEndReason, TurnLifecycleEvent, View, } from './types.js';
-export type { EventNode } from './types.js';
-export type { TreeNode } from './types.js';
-export type { TreeInternal } from './tree.js';
-export { createServerTransport } from './server-transport.js';
-export { createClientTransport } from './client-transport.js';
+export type { ActiveRun, AgentSession, AgentSessionOptions, BranchSelection, CancelRequest, ClientSession, ClientSessionOptions, ConversationNode, InputNode, LoadConversationOptions, MessageNode, OutputEvent, PipeOptions, Run, RunEndParams, RunEndReason, RunInfo, RunLifecycleEvent, RunNode, RunNodeState, RunRuntime, RunView, SendOptions, StreamResult, Tree, View, } from './types.js';
+export type { InvocationData } from './invocation.js';
+export { Invocation } from './invocation.js';
+export { createAgentSession } from './agent-session.js';
+export { createClientSession } from './client-session.js';
 export { buildTransportHeaders } from './headers.js';

package/dist/core/transport/internal/bounded-map.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Helpers for FIFO-bounded `Map`s — Maps used as capacity-limited buffers that
+ * must evict their oldest entry when full.
+ */
+/**
+ * Make room for a new key in a FIFO-bounded map: if `map` is at (or over)
+ * `limit` and does not already contain `key`, evict the oldest entry (insertion
+ * order) and return its key so the caller can log the eviction. Returns
+ * `undefined` when nothing was evicted (the key already exists, the map is
+ * below the limit, or it is empty).
+ *
+ * The caller performs the actual set/append afterwards — this only frees a
+ * slot — so it works for maps whose values are replaced and for maps whose
+ * values are appended-to lists.
+ * @param map - The bounded map to evict from.
+ * @param key - The key about to be added; an existing key never evicts.
+ * @param limit - The maximum number of entries the map may hold.
+ * @returns The evicted key, or `undefined` if nothing was evicted.
+ */
+export declare const evictOldestIfFull: <K, V>(map: Map<K, V>, key: K, limit: number) => K | undefined;