@ably/ai-transport 0.0.1 → 0.2.0

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

@@ -0,0 +1,354 @@
+import { Logger } from '../../logger.js';
+import { Codec, CodecInputEvent, CodecMessage, CodecOutputEvent } from '../codec/types.js';
+import { TreeInternal } from './tree.js';
+import { ActiveRun, BranchSelection, RunInfo, RunLifecycleEvent, SendOptions, View } from './types.js';
+/**
+ * DefaultView — a paginated, branch-aware projection over the Tree.
+ *
+ * Wraps a Tree (RunNode-keyed) and manages a pagination window that controls
+ * which Runs are visible to the UI. New live Runs appear immediately; older
+ * Runs are revealed progressively via `loadOlder()`.
+ *
+ * `getMessages()` reads the Tree's visible node chain (input nodes + reply
+ * runs, with sibling selection applied) and concatenates each node's
+ * `codec.getMessages(node.projection)` to produce the flat
+ * `CodecMessage<TMessage>[]` the UI renders.
+ *
+ * Each View owns its own branch selection state and pagination window,
+ * allowing multiple independent Views over the same Tree.
+ *
+ * Events are scoped to the visible window — 'update' only fires when the
+ * visible output changes, 'ably-message' only for messages corresponding to
+ * visible Runs, and 'run' only for runs with visible content.
+ */
+import * as Ably from 'ably';
+/**
+ * Internal delegate function provided by the session for executing sends.
+ * The View pre-computes the visible branch's flat message list and the
+ * codec-message-id of its tail (for auto-parent routing) before calling
+ * the delegate, so the delegate has no back-reference to the View.
+ *
+ * Each TInput carries its own routing metadata (`parent` / `target` /
+ * `codecMessageId`) via the {@link CodecInputEvent} base; the delegate
+ * reads those fields directly without runtime classification.
+ *
+ * `parentCodecMessageId` is the codec-message-id of the last message in
+ * the visible branch (extracted from the tail Run's projection per codec
+ * convention), or `undefined` for an empty conversation. The session
+ * uses it as the auto-parent for fresh user messages.
+ */
+export type SendDelegate<TInput extends CodecInputEvent> = (input: TInput[], options: SendOptions | undefined, parentCodecMessageId: string | undefined) => Promise<ActiveRun>;
+/** Options for creating a View. */
+export interface ViewOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /** The tree to project. */
+    tree: TreeInternal<TInput, TOutput, TProjection>;
+    /** The Ably channel to load history from. */
+    channel: Ably.RealtimeChannel;
+    /** The codec used to project messages, mint regenerate inputs, and decode history. */
+    codec: Codec<TInput, TOutput, TProjection, TMessage>;
+    /** Delegate for executing sends through the session. */
+    sendDelegate: SendDelegate<TInput>;
+    /** Logger for diagnostic output. */
+    logger: Logger;
+    /** Called when the view is closed, allowing the owner to clean up references. */
+    onClose?: () => void;
+}
+export declare class DefaultView<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> implements View<TInput, TMessage> {
+    private readonly _tree;
+    private readonly _channel;
+    private readonly _codec;
+    private readonly _sendDelegate;
+    private readonly _logger;
+    private readonly _emitter;
+    private readonly _onClose?;
+    /**
+     * View-local branch selections: group-root runId → selection intent.
+     * Fork points not present here default to the latest sibling.
+     */
+    private readonly _branchSelections;
+    /**
+     * View-local regenerate-group selections: anchor codec-message-id (the assistant
+     * codec-message-id being regenerated) → selection intent. Distinct from
+     * {@link _branchSelections} because a regenerate group is a set of
+     * same-parent reply runs — message-level alternatives at a single
+     * conversation slot, not edit forks of the prompt. Groups not present here default to the latest
+     * member (the most recent regenerator, or the original if no regen has
+     * landed).
+     */
+    private readonly _regenSelections;
+    /** Spec: AIT-CT11c — runIds loaded from history but not yet revealed to the UI. */
+    private readonly _withheldRunIds;
+    /** Snapshot of visible node keys — used to detect structural changes and for selection pinning. */
+    private _lastVisibleNodeKeys;
+    /**
+     * Snapshot of visible projection references — used to detect in-place
+     * projection updates (streaming). One entry per visible Run.
+     */
+    private _lastVisibleProjections;
+    /**
+     * Snapshot of the visible flat message chain with codec-message-ids —
+     * exposed verbatim via `getMessages()` and the internal correlation
+     * source for parent/branch routing.
+     */
+    private _lastVisibleMessagePairs;
+    /** Cached visible node-key Set — for O(1) lookup in event scoping. */
+    private _lastVisibleNodeKeySet;
+    /** Whether there are more history pages to fetch from the channel. */
+    private _hasMoreHistory;
+    /** Internal state for continuing history pagination. */
+    private _lastHistoryPage;
+    /** Buffer of withheld nodes (input + reply), drained newest-first by successive loadOlder() calls. */
+    private readonly _withheldBuffer;
+    /** Unsubscribe functions for tree event subscriptions. */
+    private readonly _unsubs;
+    /**
+     * Cached result of the last flat-nodes computation. Drives the visible
+     * message snapshot exposed via `getMessages()`; refreshed by
+     * `_computeFlatNodes()` on structural changes, selection changes,
+     * and history reveal.
+     */
+    private _cachedNodes;
+    private _loadingOlder;
+    private _processingHistory;
+    private _closed;
+    constructor(options: ViewOptions<TInput, TOutput, TProjection, TMessage>);
+    /**
+     * Handle decoded outputs folded into a Run (streaming delta). If the run
+     * is on the visible chain, recompute the flat message list and emit
+     * `update`.
+     * @param event - The output event from the Tree.
+     */
+    private _onTreeOutput;
+    getMessages(): CodecMessage<TMessage>[];
+    runs(): RunInfo[];
+    /**
+     * Compute the fresh visible node chain. The Tree's `visibleNodes` already
+     * applies kind-blind reachability and sibling selection (edit versions /
+     * regenerate runs collapse to the selected member), so the View only layers
+     * its pagination window on top: drop nodes whose key is currently withheld.
+     * @returns A fresh array of visible nodes (inputs + reply runs).
+     */
+    private _computeFlatNodes;
+    /**
+     * Recompute the visible node chain, refresh the cache + snapshot, and emit
+     * `update` unconditionally. Use after a mutation that always changes the
+     * visible output (e.g. an explicit selection or a withheld-batch reveal).
+     */
+    private _recomputeAndEmit;
+    /**
+     * Recompute the visible node chain and, only if it differs from the current
+     * snapshot, refresh the cache + snapshot and emit `update`. Use after a
+     * mutation that may or may not move the visible window (e.g. a structural
+     * tree update, or a deferred regenerate promotion that may already match).
+     */
+    private _recomputeAndEmitIfChanged;
+    /**
+     * Resolve the reply Run that owns a codec-message-id, narrowing the Tree's
+     * node union to a {@link RunNode}. A user-input codec-message-id resolves to
+     * an input node and yields `undefined` here — callers that must handle input
+     * nodes use {@link _tree.getNodeByCodecMessageId} directly.
+     * @param codecMessageId - The codec-message-id to resolve.
+     * @returns The owning RunNode, or undefined if absent or not a reply Run.
+     */
+    private _runByCodecMessageId;
+    /**
+     * Extract the flat TMessage[] from a visible node chain.
+     *
+     * In the two-node model the Tree's `visibleNodes` has already selected one
+     * member per sibling group (the chosen edit version, the chosen regenerate
+     * run), so a regenerate is just a sibling reply run that appears in place of
+     * the original. Each visible node contributes its own messages in projection
+     * order; the flat list is their concatenation.
+     *
+     * Deferred caveat: a mid-reply regenerate that replaces a non-head message
+     * inside a multi-message reply run is not expressible as a sibling run in
+     * this model and is not handled here (see the `regenerate-of-multi-message`
+     * golden test).
+     * @param nodes - The visible nodes (inputs + reply runs) in chronological order.
+     * @returns The flat message list, each message paired with its codec-message-id.
+     */
+    private _extractMessages;
+    hasOlder(): boolean;
+    /**
+     * Reveal up to `limit` older Runs in this view.
+     *
+     * The pagination unit is the **Run**, not the message. A single Run
+     * typically materialises into multiple messages (e.g. user + assistant
+     * pair) so revealing `limit` Runs may add several messages to the flat
+     * list returned by {@link getMessages}. Channel pages don't align to
+     * Run boundaries, so {@link _loadUntilVisible} keeps fetching channel
+     * pages until at least `limit` Runs are buffered (or the channel is
+     * exhausted).
+     * @param limit - Maximum number of older Runs to reveal. Defaults to 100.
+     */
+    loadOlder(limit?: number): Promise<void>;
+    runOf(codecMessageId: string): RunInfo | undefined;
+    /**
+     * Resolve the reply run currently selected for an input node, honouring the
+     * View's regenerate selection. Falls back to the latest reply run when no
+     * selection has been recorded; undefined when no reply run has started.
+     * @param inputCodecMessageId - The input node's codec-message-id.
+     * @returns The selected reply RunNode, or undefined.
+     */
+    private _selectedReplyRun;
+    run(runId: string): RunInfo | undefined;
+    branchSelection(codecMessageId: string): BranchSelection<TMessage>;
+    selectSibling(codecMessageId: string, index: number): void;
+    /**
+     * Resolve the currently selected sibling's index inside a branch group.
+     * Pending selections fall back to the latest sibling. The caller clamps
+     * the returned index against any post-extraction filtering.
+     * @param branch - Resolved branch-point descriptor from `_resolveMessageBranchPoint`.
+     * @returns The selected sibling's index within `branch.siblings`.
+     */
+    private _resolveSelectedIndex;
+    /**
+     * Resolve the branch point anchored at `codecMessageId`, if any.
+     *
+     * Returns the resolved group `kind` along with the sibling list so the
+     * caller can update the correct selection map without re-entering the
+     * runId-based `select()` dispatch (which biases to fork-of first and
+     * would mis-route a regen-anchor codec-message-id when the owning Run is in
+     * BOTH groups — e.g. R1 owns both a user prompt that got edited and
+     * an assistant that got regenerated).
+     *
+     * Two anchor cases:
+     * - **fork-of** — `codecMessageId` is the first message of a Run in a fork-of
+     *   sibling group (edit-style branch point anchored at the user prompt).
+     * - **regen** — `codecMessageId` is the regen-anchor itself (in the owner Run)
+     *   or content of a regenerator Run (regen-style branch point anchored
+     *   at the assistant slot).
+     * @param codecMessageId - The codec-message-id to look up.
+     * @returns The kind + sibling list + group key (runId for fork-of,
+     *   anchor codec-message-id for regen), or undefined when `codecMessageId` is not an
+     *   anchor in either group type.
+     */
+    private _resolveMessageBranchPoint;
+    send(input: TInput | TInput[], options?: SendOptions): Promise<ActiveRun>;
+    /**
+     * Auto-select / pin branch selections after a forking send.
+     * @param result - The ActiveRun returned by the delegate.
+     * @param options - The SendOptions passed by the caller.
+     */
+    private _applyForkAutoSelect;
+    /**
+     * Auto-select / pin the regenerate group anchored at `anchorCodecMessageId` so
+     * the new Run's content appears as soon as the agent's run-start lands.
+     *
+     * `View.regenerate()` calls this with the assistant codec-message-id being
+     * regenerated. The Run doesn't exist yet on the channel (the regenerate
+     * wire is wire-only); the selection is recorded as `pending` and
+     * promoted to `auto` by `_pinRegenSelections` once the corresponding
+     * Run is created in the tree.
+     * @param result - The ActiveRun returned by the delegate (run-id is the new regenerator's).
+     * @param anchorCodecMessageId - The codec-message-id of the assistant being regenerated.
+     */
+    private _applyRegenerateAutoSelect;
+    regenerate(messageId: string, options?: SendOptions): Promise<ActiveRun>;
+    edit(messageId: string, inputs: TInput | TInput[], options?: SendOptions): Promise<ActiveRun>;
+    /**
+     * Find the codec-message-id of the message immediately preceding `targetMsgId` in
+     * the visible conversation.
+     *
+     * Consults the View's visible message chain first so message-level
+     * replacements (regenerate) are respected: regenerating an
+     * already-regenerated assistant lands the predecessor on the user
+     * prompt the regen is responding to, NOT on the hidden original
+     * assistant that occupies the same conversation slot. Falls back to a
+     * projection-walk for the rare case where `targetMsgId` isn't on the
+     * visible chain (e.g. caller is operating on a Run that's selection-
+     * hidden by the current branch).
+     * @param targetNode - The node (input node or reply run) that owns `targetMsgId`.
+     * @param targetMsgId - The codec-message-id to find the parent of.
+     * @returns The parent codec-message-id, or undefined if no predecessor exists.
+     */
+    private _findParentMsgId;
+    on(event: 'update', handler: () => void): () => void;
+    on(event: 'ably-message', handler: (msg: Ably.InboundMessage) => void): () => void;
+    on(event: 'run', handler: (event: RunLifecycleEvent) => void): () => void;
+    close(): void;
+    private _loadFirstPage;
+    /**
+     * Walk channel history from `page` until at least `limit` new Runs are
+     * observed (or the channel is exhausted), then reveal the newest batch and
+     * withhold the rest. Snapshots the already-visible nodes up front so only
+     * newly-observed Runs count toward `limit`. No-op if the view closed during
+     * the page walk.
+     * @param page - The decoded history page to start from.
+     * @param limit - Max Runs to reveal in this batch.
+     */
+    private _revealFromPage;
+    /**
+     * Reveal the newest `limit` Runs from `newVisible` and withhold the rest
+     * so subsequent `loadOlder` calls can drain them. Called by
+     * {@link _revealFromPage} to enforce the Run-unit pagination contract.
+     * @param newVisible - Newly observed Runs from the history fetch.
+     * @param limit - Max Runs to reveal in this batch.
+     */
+    private _splitReveal;
+    /**
+     * Replay a history page's raw messages into the Tree. Dispatches by Ably
+     * message name to run-lifecycle vs. regular wire messages, mirroring the
+     * live `client-session._handleMessage` decode loop. Uses a fresh decoder
+     * since the session's live decoder maintains its own stream-tracker state.
+     * @param page - The history page returned by `loadHistory`.
+     */
+    private _processHistoryPage;
+    private _loadUntilVisible;
+    private _releaseWithheld;
+    private _updateVisibleSnapshot;
+    private _onTreeUpdate;
+    /**
+     * Build the unified selection map the Tree's `visibleNodes` consumes:
+     * `groupRootKey -> selectedKey`, covering both edit forks (input-node groups,
+     * keyed by the input group root) and regenerate groups (reply-run groups,
+     * keyed by the original reply's group root). Pending entries (no chosen
+     * member yet) are omitted so the Tree falls back to the latest sibling.
+     * @returns The merged group-root → selected-key map.
+     */
+    private _resolveSelections;
+    /**
+     * The Tree's visible node chain under this view's current selections — the
+     * reachable, sibling-resolved nodes before the View's pagination window is
+     * applied.
+     * @returns The selection-resolved visible node chain.
+     */
+    private _treeVisibleNodes;
+    /**
+     * For each previously-visible Run that now has siblings but no explicit
+     * selection, pin the selection to that Run's runId. This preserves the
+     * current branch when new forks appear from other views or external
+     * sources.
+     *
+     * Exception: if the fork was initiated by this view (tracked as a
+     * `pending` BranchSelection), select the newest sibling (the awaited Run)
+     * instead of pinning the old one.
+     */
+    private _pinBranchSelections;
+    /**
+     * Roll `pending` and `auto` regenerate selections forward to the newest
+     * group member. A regenerate slot defaults to the latest member, so each
+     * new regenerator (this view's awaited run, or an external one) auto-rolls
+     * the slot forward — UNLESS the user explicitly selected an earlier member
+     * (`user`), which pins and is left untouched. The agent mints the run-id, so
+     * we can't match the awaited run by id — once the group grows we adopt the
+     * newest as the selected member.
+     */
+    private _resolvePendingRegenSelections;
+    private _onTreeAblyMessage;
+    private _onTreeRun;
+    /**
+     * Predict whether a run-start's messages will be visible on this view's
+     * branch using the parent/forkOf metadata from the event.
+     * @param event - The run-start lifecycle event.
+     * @returns True if the run is expected to be visible on this view's branch.
+     */
+    private _isRunStartVisible;
+    private _visibleChanged;
+}
+/**
+ * Create a View that projects a paginated window over a Tree.
+ * @param options - The tree, channel, codec, and logger to use.
+ * @returns A new {@link DefaultView} instance.
+ */
+export declare const createView: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>(options: ViewOptions<TInput, TOutput, TProjection, TMessage>) => DefaultView<TInput, TOutput, TProjection, TMessage>;

package/dist/errors.d.ts

@@ -12,30 +12,58 @@ export declare enum ErrorCode {
      */
     InvalidArgument = 40003,
     /**
-     * Encoder recovery failed after flush — one or more updateMessage calls
+     * Operation not permitted with the provided capability (Ably 40160).
+     * Used when the Ably channel rejects a publish for a capability reason.
+     */
+    InsufficientCapability = 40160,
+    /**
+     * Encoder recovery failed during flush — one or more updateMessage calls
      * could not recover a failed append pipeline.
      */
     EncoderRecoveryFailed = 104000,
     /**
-     * A transport-level channel subscription callback threw unexpectedly.
+     * A session-level channel subscription callback threw unexpectedly.
      */
-    TransportSubscriptionError = 104001,
+    SessionSubscriptionError = 104001,
     /**
      * Cancel listener or onCancel hook threw while processing a cancel message.
      */
     CancelListenerError = 104002,
     /**
-     * A turn lifecycle event (turn-start or turn-end) failed to publish.
+     * A publish within a run failed (lifecycle event, message, or event).
+     */
+    RunLifecycleError = 104003,
+    /**
+     * An operation was attempted on a session that has already been closed.
+     */
+    SessionClosed = 104004,
+    /**
+     * The HTTP POST to the agent endpoint failed (network error or non-2xx response).
+     */
+    SessionSendFailed = 104005,
+    /**
+     * The Ably channel lost message continuity — the channel entered FAILED,
+     * SUSPENDED, or DETACHED, or re-attached with `resumed: false`. Active
+     * streams can no longer be guaranteed to receive all events.
+     */
+    ChannelContinuityLost = 104006,
+    /**
+     * An operation was attempted but the channel is not in a usable state
+     * (not ATTACHED or ATTACHING).
      */
-    TurnLifecycleError = 104003,
+    ChannelNotReady = 104007,
     /**
-     * An operation was attempted on a transport that has already been closed.
+     * An error occurred while piping a response stream to the channel — either
+     * the source event stream threw (e.g. LLM provider rate limit, model error,
+     * network failure) or an underlying publish failed mid-stream.
      */
-    TransportClosed = 104004,
+    StreamError = 104008,
     /**
-     * The HTTP POST to the server endpoint failed (network error or non-2xx response).
+     * The agent attached to the channel and waited for the input event(s) the
+     * invocation points at (rewind + live wait) but `inputEventLookupTimeoutMs`
+     * lapsed without seeing them.
      */
-    TransportSendFailed = 104005
+    InputEventNotFound = 104010
 }
 /**
  * Returns true if the {@link Ably.ErrorInfo} code matches the provided ErrorCode value.

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-export type { ActiveTurn, AddMessageOptions, AddMessagesResult, CancelFilter, CancelRequest, ClientTransport, ClientTransportOptions, CloseOptions, ConversationNode, ConversationTree, LoadHistoryOptions, MessageWithHeaders, NewTurnOptions, PaginatedMessages, SendOptions, ServerTransport, ServerTransportOptions, StreamResponseOptions, StreamResult, Turn, TurnEndReason, TurnLifecycleEvent, } from './core/transport/index.js';
-export { buildTransportHeaders, createClientTransport, createServerTransport } from './core/transport/index.js';
-export type { ChannelWriter, Codec, DecoderCore, DecoderCoreHooks, DecoderCoreOptions, DecoderOutput, DiscreteEncoder, EncoderCore, EncoderCoreOptions, EncoderOptions, Extras, LifecycleTracker, MessageAccumulator, MessagePayload, PhaseConfig, StreamDecoder, StreamEncoder, StreamPayload, StreamTrackerState, WriteOptions, } from './core/codec/index.js';
-export { createDecoderCore, createEncoderCore, createLifecycleTracker, eventOutput } from './core/codec/index.js';
-export { DOMAIN_HEADER_PREFIX, EVENT_ABORT, EVENT_CANCEL, EVENT_ERROR, EVENT_TURN_END, EVENT_TURN_START, HEADER_CANCEL_ALL, HEADER_CANCEL_CLIENT_ID, HEADER_CANCEL_OWN, HEADER_CANCEL_TURN_ID, HEADER_FORK_OF, HEADER_MSG_ID, HEADER_PARENT, HEADER_ROLE, HEADER_STATUS, HEADER_STREAM, HEADER_STREAM_ID, HEADER_TURN_CLIENT_ID, HEADER_TURN_ID, HEADER_TURN_REASON, } from './constants.js';
+export type { ActiveRun, AgentSession, AgentSessionOptions, BranchSelection, CancelRequest, ClientSession, ClientSessionOptions, ConversationNode, EventsNode, InputNode, InvocationData, LoadConversationOptions, MessageNode, OutputEvent, PipeOptions, Run, RunEndReason, RunInfo, RunLifecycleEvent, RunNode, RunRuntime, RunView, SendOptions, StreamResult, Tree, View, } from './core/transport/index.js';
+export { buildTransportHeaders, createAgentSession, createClientSession, Invocation } from './core/transport/index.js';
+export type { ChannelWriter, Codec, CodecInputEvent, CodecMessage, CodecOutputEvent, DecodedMessage, Decoder, DecoderCore, DecoderCoreHooks, DecoderCoreOptions, Encoder, EncoderCore, EncoderCoreOptions, EncoderOptions, Extras, LifecycleTracker, MessagePayload, PhaseConfig, Reducer, ReducerMeta, Regenerate, StreamPayload, StreamTrackerState, ToolApprovalResponse, ToolResult, ToolResultError, UserMessage, WriteOptions, } from './core/codec/index.js';
+export { createDecoderCore, createEncoderCore, createLifecycleTracker } from './core/codec/index.js';
+export { EVENT_CANCEL, EVENT_RUN_END, EVENT_RUN_START, HEADER_CODEC_MESSAGE_ID, HEADER_ERROR_CODE, HEADER_ERROR_MESSAGE, HEADER_FORK_OF, HEADER_INPUT_CLIENT_ID, HEADER_MSG_REGENERATE, HEADER_PARENT, HEADER_ROLE, HEADER_RUN_CLIENT_ID, HEADER_RUN_ID, HEADER_RUN_REASON, HEADER_STATUS, HEADER_STREAM, HEADER_STREAM_ID, } from './constants.js';
 export type { DomainHeaderReader, DomainHeaderWriter, Stripped } from './utils.js';
-export { getHeaders, headerReader, headerWriter, mergeHeaders, stripUndefined } from './utils.js';
+export { getCodecHeaders, getTransportHeaders, headerReader, headerWriter, mergeHeaders, stripUndefined, } from './utils.js';
 export { EventEmitter } from './event-emitter.js';
 export { ErrorCode, errorInfoIs } from './errors.js';
 export type { LogContext, Logger, LoggerOptions, LogHandler } from './logger.js';

package/dist/logger.d.ts

@@ -97,7 +97,19 @@ export declare const consoleLogger: (message: string, level: LogLevel, context?:
  * Options for creating a logger.
  */
 export interface LoggerOptions {
+    /**
+     * The handler that receives formatted log messages. Defaults to {@link consoleLogger} when omitted.
+     */
     logHandler?: LogHandler;
+    /**
+     * The minimum level to emit; messages below this level are suppressed. Must be a valid {@link LogLevel}, otherwise logger creation throws.
+     */
     logLevel: LogLevel;
 }
+/**
+ * Creates a {@link Logger} from the given options.
+ * @param options The handler and minimum level for the logger.
+ * @returns A logger that filters by level and delegates to the handler.
+ * @throws {@link Ably.ErrorInfo} with {@link ErrorCode.InvalidArgument} if `options.logLevel` is not a recognised {@link LogLevel}.
+ */
 export declare const makeLogger: (options: LoggerOptions) => Logger;