@ably/ai-transport 0.2.0 → 0.3.0

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

@@ -1,4 +1,4 @@
-import { Codec, CodecInputEvent, CodecOutputEvent, Decoder } from '../codec/types.js';
+import { CodecInputEvent, CodecOutputEvent, Decoder } from '../codec/types.js';
 import { TreeInternal } from './tree.js';
 import { RunLifecycleEvent } from './types.js';
 /**
@@ -8,40 +8,48 @@ import { RunLifecycleEvent } from './types.js';
  * 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';
 /**
- * Apply one inbound wire message to the tree.
- *
- * Run-lifecycle messages are turned into a {@link RunLifecycleEvent} via
- * {@link parseRunLifecycle} and applied with `applyRunLifecycle`; everything
- * else is decoded with `decoder` and applied with `applyMessage`, skipping
- * wire-only carriers that decode to no events and carry no run-id (the eventual
- * reply run is created later by its run-start).
- *
- * Does NOT emit the tree's `ably-message` event — the caller owns that, because
- * the live loop emits per message while history replay emits in a batch once
- * the whole page is applied. Returns the parsed lifecycle event so a live
- * caller can run its own side-effects (resolving a pending run-start,
- * surfacing an agent error); returns `undefined` for a codec-decoded message
- * or a lifecycle message that carried no run-id.
- * @param tree - The tree to apply the message to.
- * @param decoder - The codec decoder used for non-lifecycle messages.
- * @param rawMsg - The inbound Ably wire message.
- * @returns The parsed run-lifecycle event, or `undefined`.
+ * 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 declare const applyWireMessage: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection>(tree: TreeInternal<TInput, TOutput, TProjection>, decoder: Decoder<TInput, TOutput>, rawMsg: Ably.InboundMessage) => RunLifecycleEvent | undefined;
+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;
+}
 /**
- * Decode one wire message with `decoder` and fold its events into `projection`,
- * returning the updated projection. Unlike {@link applyWireMessage} this builds
- * a standalone projection rather than applying to a tree — used by the agent's
- * conversation reconstruction. The caller owns the decoder so its streaming
- * state can span the messages of a run, and chooses the reducer routing key.
- * @param codec - The codec whose inherited Reducer `fold` method folds each decoded event into the projection.
- * @param decoder - The caller-owned codec decoder (reused across a run's wires).
- * @param projection - The projection to fold the message's events into.
- * @param rawMsg - The wire message to decode and fold.
- * @param messageId - The reducer routing key (codec-message-id) for this message.
- * @returns The projection after folding all of the message's decoded events.
+ * Bind a Tree and a decoder into the Tree's single {@link WireApplier}.
+ * @param tree - The tree the applier feeds.
+ * @param decoder - The codec decoder shared by every route into the tree.
+ * @returns The applier.
  */
-export declare const foldMessageInto: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>(codec: Codec<TInput, TOutput, TProjection, TMessage>, decoder: Decoder<TInput, TOutput>, projection: TProjection, rawMsg: Ably.InboundMessage, messageId: string) => TProjection;
+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,5 +1,13 @@
 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 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.
@@ -63,6 +71,11 @@ export declare const buildTransportHeaders: (opts: {
  * @param opts.inputClientId - ClientId of the triggering input event.
  * @param opts.inputCodecMessageId - Codec-message-id of the triggering input event.
  * @param opts.reason - Terminal reason; stamped on run-end only.
+ * @param opts.errorCode - Numeric error code stamped as `error-code` on
+ *   run-end. Set only when the run ended in error and the agent supplied an
+ *   error to surface; gives codec-agnostic consumers a baseline failure detail.
+ * @param opts.errorMessage - Error message stamped as `error-message` on
+ *   run-end. Paired with `errorCode`; set under the same condition.
  * @returns A headers record with the lifecycle headers set.
  */
 export declare const buildLifecycleHeaders: (opts: {
@@ -75,6 +88,8 @@ export declare const buildLifecycleHeaders: (opts: {
     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;
@@ -88,6 +103,17 @@ type RunLifecycleName = typeof EVENT_RUN_START | typeof EVENT_RUN_SUSPEND | type
  * @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}.
  *
@@ -99,8 +125,11 @@ export declare const isRunLifecycleName: (name: string | undefined) => name is R
  * @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) => RunLifecycleEvent | undefined;
+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,4 +1,4 @@
-export type { ActiveRun, AgentSession, AgentSessionOptions, BranchSelection, CancelRequest, ClientSession, ClientSessionOptions, ConversationNode, EventsNode, InputNode, LoadConversationOptions, MessageNode, OutputEvent, PipeOptions, Run, RunEndReason, RunInfo, RunLifecycleEvent, RunNode, RunRuntime, RunView, SendOptions, StreamResult, Tree, View, } from './types.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';

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

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

package/dist/core/transport/load-history-pages.d.ts

@@ -0,0 +1,71 @@
+import { Logger } from '../../logger.js';
+/**
+ * loadHistoryPages — shared low-level history pagination primitive.
+ *
+ * Consumed by both client (via `load-history.ts`, which layers a complete-
+ * domain-message counter on top) and agent (directly, for input-event lookup
+ * and conversation hydration). Returns raw Ably messages; does NOT decode.
+ *
+ * Behaviour:
+ *  - Attaches the channel (idempotent) then pages via `channel.history()`,
+ *    using `untilAttach: true` for gapless continuity with any live subscription.
+ *  - Exposes the underlying pagination as a cursor with `hasNext()` (cheap,
+ *    no network) and `next()` (one Ably page per call, newest-first within
+ *    the page).
+ *  - Per-page failures are retried with bounded exponential backoff; on
+ *    exhaustion throws `Ably.ErrorInfo` with code `HistoryFetchFailed`.
+ *  - `signal.aborted` is checked between pages; rejects with
+ *    `Ably.ErrorInfo` (InvalidArgument) when aborted.
+ *
+ * Spec: AIT-CT11 / AIT-ST hydration.
+ */
+import * as Ably from 'ably';
+/** Options for {@link loadHistoryPages}. */
+export interface LoadHistoryPagesOptions {
+    /** Wire-message limit per Ably page. */
+    pageLimit: number;
+    /** Set `untilAttach: true` on the underlying history query for gapless continuity with live subscriptions. Default: true. */
+    untilAttach?: boolean;
+    /** AbortSignal checked between pages. Rejects with InvalidArgument when aborted. */
+    signal?: AbortSignal;
+    /** Max retries per `page.next()` / initial `history()` failure. Default: 3. */
+    maxRetries?: number;
+    /** Initial retry backoff in ms (doubled per attempt). Default: 100. */
+    retryBackoffMs?: number;
+    /** Logger for diagnostic output. */
+    logger?: Logger;
+}
+/**
+ * Cursor over the channel's history pages.
+ *
+ * `hasNext()` is cheap (cursor-only, no network); `next()` issues one Ably
+ * page fetch (with retry/backoff) and returns its messages. Once `next()`
+ * returns `undefined` the cursor is exhausted.
+ */
+export interface HistoryPagesCursor {
+    /** True when another Ably page is available (cheap to check; no network). */
+    hasNext(): boolean;
+    /**
+     * Fetch the next Ably page's messages (newest-first within the page).
+     * Returns `undefined` when no more pages are available or the abort
+     * signal has fired.
+     */
+    next(): Promise<readonly Ably.InboundMessage[] | undefined>;
+}
+/**
+ * Page through channel history, returning a cursor over Ably pages.
+ *
+ * Newest-first within each yielded page (matching Ably's native ordering).
+ * Caller drives the cursor — calling `next()` until it returns `undefined`
+ * or stopping early when a domain-specific stop condition is met
+ * (e.g. complete-message counter satisfied, target codec-message-id found,
+ * parent chain walk reaches root).
+ *
+ * The initial Ably history call is awaited eagerly so the returned cursor
+ * already knows whether there are pages available (via `hasNext()`).
+ * @param channel - The Ably channel to read history from.
+ * @param options - Pagination options.
+ * @returns A cursor with `hasNext()` (cheap, cursor-only) and `next()` (fetches one page with retry).
+ * @throws {Ably.ErrorInfo} `HistoryFetchFailed` on exhausted retry of the initial fetch, or `InvalidArgument` on signal abort.
+ */
+export declare const loadHistoryPages: (channel: Ably.RealtimeChannel, options: LoadHistoryPagesOptions) => Promise<HistoryPagesCursor>;

package/dist/core/transport/load-history.d.ts

@@ -2,35 +2,40 @@ import { Logger } from '../../logger.js';
 import { HistoryPage, LoadHistoryOptions } from './types.js';
 /**
  * loadHistory — load conversation history from an Ably channel and return
- * the raw wire messages as a paginated HistoryPage result.
+ * the raw Ably messages as a paginated HistoryPage result.
  *
- * This does NOT decode: it pages back through Ably history until `limit`
- * complete messages are present, then hands the raw Ably messages
- * (oldest-first) to the caller. The View re-decodes them into the Tree
- * itself, so load-history only needs a cheap, header-based completion
- * counter to decide when to stop paging — the decoder never runs here.
+ * This does NOT decode: it pages back through Ably history via the shared
+ * {@link loadHistoryPages} primitive until `limit` complete messages are
+ * present, then hands the raw Ably messages (oldest-first) to the caller.
+ * The View re-decodes them into the Tree itself, so load-history only needs
+ * a cheap, header-based completion counter to decide when to stop paging.
  *
  * The `limit` option controls the number of complete **messages** per page,
- * not the number of Ably wire messages fetched. A message is complete when
+ * not the number of Ably messages fetched. A message is complete when
  * its terminal wire signal — `status: "complete"` / `"cancelled"`, or a
- * `discrete` create — has been seen. Runs that span a
- * page boundary are handled by the counter requiring both a start and a
- * terminal signal before counting a message complete.
+ * `discrete` create — has been seen. Runs that span a page boundary are
+ * handled by the counter requiring both a start and a terminal signal
+ * before counting a message complete.
  *
  * Because Ably history returns newest-first, each page's `rawMessages` are
  * reversed to chronological (oldest-first) so the caller can fold them in
  * order.
+ *
+ * Spec: AIT-CT11, AIT-CT11b.
  */
 import type * as Ably from 'ably';
 /**
- * Load conversation history from a channel and return the raw wire messages.
+ * Load conversation history from a channel and return the raw Ably messages.
  *
- * Attaches the channel if not already attached, then calls
- * `channel.history({ untilAttach: true })` to guarantee no gap between
- * historical and live messages. The attach is idempotent.
+ * Drives the shared {@link loadHistoryPages} primitive with
+ * `untilAttach: true` (gapless continuity with the live subscription) and a
+ * Ably message page limit that overprovisions for the many-Ably-messages-per-domain-message
+ * ratio. Each `HistoryPage` returned covers up to `limit` complete domain
+ * messages; subsequent pages drain over-collected messages from the buffer
+ * before pulling more from the iterator.
  *
- * The `limit` option controls the number of complete messages
- * returned per page, not the number of Ably wire messages fetched.
+ * The `limit` option controls the number of complete messages returned per
+ * page, not the number of Ably messages fetched.
  * @param channel - The Ably channel to load history from.
  * @param options - Pagination options.
  * @param logger - Logger for diagnostic output.

package/dist/core/transport/run-manager.d.ts

@@ -14,7 +14,7 @@ import type * as Ably from 'ably';
  * continuation (re-entering an existing run) sets `continuation` and omits the
  * structural `parent` / `forkOf` / `regenerates` fields.
  */
-export interface StartRunMetadata {
+interface StartRunMetadata {
     /** Structural parent codec-message-id (fresh run-start only). */
     parent?: string;
     /** Forked user-prompt codec-message-id for an edit (fresh run-start only). */
@@ -37,9 +37,9 @@ export interface RunManager {
      * `ai-run-start` for a fresh run, or `ai-run-resume` when `metadata.continuation`
      * is set (a subsequent invocation re-entering an existing run). A resume omits
      * the structural `parent` / `forkOf` / `regenerates` headers — the original
-     * run-start owns the run's structure. Returns the run's AbortSignal.
+     * run-start owns the run's structure.
      */
-    startRun(runId: string, clientId?: string, controller?: AbortController, metadata?: StartRunMetadata): Promise<AbortSignal>;
+    startRun(runId: string, clientId?: string, controller?: AbortController, metadata?: StartRunMetadata): Promise<void>;
     /**
      * Suspend a run. Publishes run-suspend on the channel and drops the run's
      * active-run entry — the agent process terminates on suspend, so there is no
@@ -55,17 +55,14 @@ export interface RunManager {
      * run-reason header) and drops the run's active-run entry. Carries the same
      * per-invocation attribution as {@link suspendRun} (`invocationId`,
      * `inputClientId`, `inputCodecMessageId`), since run-end is the terminal event
-     * of the ending invocation.
+     * of the ending invocation. When `reason` is `'error'` and an `error` is
+     * supplied, its `code` and `message` are additionally stamped as the
+     * `error-code` / `error-message` headers — a codec-agnostic baseline failure
+     * detail for consumers; omitting `error` publishes a bare `reason: 'error'`.
      */
-    endRun(runId: string, reason: RunEndReason, invocationId?: string, inputClientId?: string, inputCodecMessageId?: string): Promise<void>;
-    /** Get the AbortSignal for a run. */
-    getSignal(runId: string): AbortSignal | undefined;
+    endRun(runId: string, reason: RunEndReason, invocationId?: string, inputClientId?: string, inputCodecMessageId?: string, error?: Ably.ErrorInfo): Promise<void>;
     /** Get the clientId that owns a run. */
     getClientId(runId: string): string | undefined;
-    /** Fire the AbortSignal for a run to cancel any in-flight work. */
-    cancel(runId: string): void;
-    /** Get all active run IDs. */
-    getActiveRunIds(): string[];
     /** Cancel all active runs and clear state. */
     close(): void;
 }
@@ -76,3 +73,4 @@ export interface RunManager {
  * @returns A new {@link RunManager} instance.
  */
 export declare const createRunManager: (channel: Ably.RealtimeChannel, logger?: Logger) => RunManager;
+export {};

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

@@ -0,0 +1,55 @@
+import { Logger } from '../../logger.js';
+/**
+ * Shared lifecycle plumbing for the client and agent sessions.
+ *
+ * Both `DefaultClientSession` and `DefaultAgentSession` gate their writes on
+ * `connect()` having run, detach their channel best-effort on close, and react
+ * to channel continuity loss with the same detection rule and error shape.
+ * These helpers own that common machinery so the two sessions cannot drift on
+ * the connection guard, the detach-swallow behaviour, or — most importantly —
+ * the continuity-loss predicate, which encodes channel protocol semantics
+ * (Spec AIT-CT19 / AIT-ST12). Each session keeps its own divergent reaction to
+ * continuity loss (the client emits; the agent aborts runs and swaps its Tree).
+ */
+import * as Ably from 'ably';
+/**
+ * Resolve a session's connect guard: return the in-flight/settled connect
+ * promise, or reject with `InvalidArgument` when `connect()` has not been
+ * called. Callers `await` the result before any write.
+ * @param connectPromise - The session's connect promise, or `undefined` when not yet connected.
+ * @param method - The method name being guarded, for the error message.
+ * @returns The connect promise.
+ * @throws {Ably.ErrorInfo} `InvalidArgument` when `connectPromise` is `undefined`.
+ */
+export declare const requireConnected: (connectPromise: Promise<void> | undefined, method: string) => Promise<void>;
+/**
+ * Detach the session's channel on close, best-effort. `connect()` subscribes
+ * (which implicitly attaches), so a detach is only attempted when `connect()`
+ * ran. A detach failure (e.g. the channel is already FAILED) must not throw out
+ * of `close()`, so it is swallowed and logged at debug.
+ * @param channel - The session's channel.
+ * @param connectPromise - The session's connect promise; detach is skipped when `undefined`.
+ * @param logger - Logger for the swallowed-failure debug line, or `undefined`.
+ * @param component - The owning class name, used as the log message prefix.
+ */
+export declare const bestEffortDetach: (channel: Ably.RealtimeChannel, connectPromise: Promise<void> | undefined, logger: Logger | undefined, component: string) => Promise<void>;
+/**
+ * Whether a channel state change breaks message continuity:
+ * - FAILED, SUSPENDED, DETACHED — no more messages expected (or a gap)
+ * - ATTACHED with `resumed: false` (an UPDATE) — messages were lost
+ *
+ * The initial attach (ATTACHED with no prior attach) is the caller's concern
+ * and is not handled here.
+ * @param stateChange - The channel state change to classify.
+ * @returns True when continuity was lost.
+ */
+export declare const isContinuityLost: (stateChange: Ably.ChannelStateChange) => boolean;
+/**
+ * Build the `ChannelContinuityLost` error for a continuity-breaking state
+ * change, attaching the state change's `reason` as `cause`.
+ * @param stateChange - The continuity-breaking state change.
+ * @param verb - The operation that can no longer proceed, for the
+ *   `unable to <verb>; ...` message (e.g. "deliver events", "continue").
+ * @returns The continuity-loss error.
+ */
+export declare const continuityLostError: (stateChange: Ably.ChannelStateChange, verb: string) => Ably.ErrorInfo;