@ably/ai-transport 0.0.1 → 0.2.0

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

@@ -0,0 +1,435 @@
+import { Logger } from '../../logger.js';
+import { CodecInputEvent, CodecOutputEvent, Reducer } from '../codec/types.js';
+import { ConversationNode, OutputEvent, RunLifecycleEvent, RunNode, Tree } from './types.js';
+/**
+ * Tree — materializes a branching conversation as a forest of nodes. Each turn
+ * is two nodes: a user {@link InputNode} keyed by its client-owned
+ * codec-message-id and an agent {@link RunNode} keyed by the agent-minted
+ * run-id, parented to the input node.
+ *
+ * Each node holds a per-node codec {@link TProjection} which the Tree folds
+ * from inbound events. The Tree owns the complete conversation state across
+ * every observed node. The {@link View} walks the parent chain to extract a
+ * flat message list for rendering.
+ *
+ * `applyMessage()` is the entry point for inbound channel messages — it
+ * classifies a run-less user input into an input node (keyed by
+ * codec-message-id) or routes a run-bearing wire to its reply run (keyed by
+ * run-id), folds events into that node's projection, and maintains a secondary
+ * `codecMessageId -> nodeKey` index. `applyRunLifecycle()` handles run-start /
+ * run-suspend / run-resume / run-end events.
+ *
+ * Sibling structure: editing a prompt produces a sibling input node linked by
+ * {@link InputNode.forkOf}; regenerating a reply produces a sibling reply run
+ * sharing the same input-node parent (no fork-of).
+ */
+import type * as Ably from 'ably';
+/**
+ * The primary key a node is indexed under: a reply run's `runId`, or an input
+ * node's `codecMessageId` (the client owns it before the agent mints a runId).
+ * @param node - The node to key.
+ * @returns The node's primary key.
+ */
+export declare const nodeKey: <TProjection>(node: ConversationNode<TProjection>) => string;
+/** Internal tree surface used by View and ClientSession — not part of the public Tree API. */
+export interface TreeInternal<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection> extends Tree<TOutput, TProjection> {
+    /**
+     * Walk the visible node chain (both input nodes and reply runs) along the
+     * selected branches, in chronological order. The View renders from this.
+     * @param selections - Per-group selected member key, keyed by group root.
+     * @returns The visible nodes in chronological order.
+     */
+    visibleNodes(selections?: Map<string, string>): ConversationNode<TProjection>[];
+    /**
+     * Get the "group root" key for a sibling group — the stable key the
+     * selection map is keyed by (the earliest edit version for input nodes, the
+     * original reply for a regenerate group).
+     */
+    getGroupRoot(key: string): string;
+    /**
+     * The reply runs parented at an input node (its codec-message-id), in
+     * iteration order. Empty when none have been observed. Used to resolve a
+     * user prompt to its reply run(s).
+     * @param inputCodecMessageId - The input node's codec-message-id.
+     * @returns The reply runs parented at that input.
+     */
+    getReplyRuns(inputCodecMessageId: string): RunNode<TProjection>[];
+    /**
+     * Apply an inbound channel message to the tree.
+     *
+     * Classifies the message and routes it to the owning node:
+     * 1. Run-less user input (no run-id, a `user`-role message carrying a
+     *    codec-message-id and input events): creates or promotes the input node
+     *    keyed by that codec-message-id, folds the input events.
+     * 2. Run-bearing wire (assistant output, continuation tool-resolution, or a
+     *    fresh agent-minted run): routes to the reply run by run-id (reconciling
+     *    an optimistic insert by codec-message-id), folds events.
+     * @param events - Decoded codec events, split by wire direction. Both are
+     *   folded into the node's projection, inputs first.
+     * @param events.inputs - Client-published events (`ai-input` wire).
+     * @param events.outputs - Agent-published events (`ai-output` wire).
+     * @param headers - Transport headers from the inbound Ably message.
+     * @param serial - Ably channel serial; undefined for optimistic inserts.
+     */
+    applyMessage(events: {
+        inputs: TInput[];
+        outputs: TOutput[];
+    }, headers: Record<string, string>, serial?: string): void;
+    /**
+     * Apply a run-lifecycle event.
+     *
+     * - `start`: creates the reply run (if missing) or, for an existing run,
+     *   sets RunNode.status to 'active', promotes startSerial, and backfills
+     *   structural metadata (parent / forkOf / regenerates / invocationId).
+     * - `suspend`: sets RunNode.status to 'suspended' and records `endSerial`.
+     *   The run stays live so a resume under the same `runId` picks up where it
+     *   left off.
+     * - `resume`: re-activates an existing suspended Run (status back to
+     *   'active') without touching its structure or serials — a pure re-entry
+     *   signal. A no-op if the Run is not yet known.
+     * - `end`: sets RunNode.status to the terminal reason and records
+     *   `endSerial`.
+     *
+     * Always emits a 'run' event to subscribers.
+     * @param event - Lifecycle event payload, including the channel serial.
+     */
+    applyRunLifecycle(event: RunLifecycleEvent): void;
+    /**
+     * Get the node keyed by `key`, or undefined if `key` names no node. The
+     * key is a {@link nodeKey} — a runId (reply run) or an input node's
+     * codec-message-id — so the result is a {@link ConversationNode} union:
+     * narrow on `kind` before reading kind-specific fields. Pairs with
+     * {@link getNodeByCodecMessageId}, which resolves an arbitrary owned
+     * codec-message-id (including an assistant message's) to its node.
+     * @param key - The node key to look up.
+     * @returns The node, or undefined if not found.
+     */
+    getNode(key: string): ConversationNode<TProjection> | undefined;
+    /**
+     * Remove a node from the tree by its key ({@link nodeKey} — a runId or an
+     * input node's codec-message-id). Children become unreachable because their
+     * parent is no longer on the active path.
+     * @param key - The node key to remove.
+     */
+    delete(key: string): void;
+    /** Forward a raw Ably message event to tree subscribers. */
+    emitAblyMessage(msg: Ably.InboundMessage): void;
+}
+export declare class DefaultTree<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection> implements TreeInternal<TInput, TOutput, TProjection> {
+    private readonly _codec;
+    private readonly _logger;
+    private readonly _emitter;
+    /**
+     * All nodes indexed by their primary key ({@link nodeKey}): a reply run's
+     * runId, or an input node's codec-message-id.
+     */
+    private readonly _nodeIndex;
+    /**
+     * Maps every observed `codec-message-id` to its owning node's key
+     * ({@link nodeKey}). For a reply run that is the runId of every message the
+     * run published; for an input node it is the input's own codec-message-id.
+     * Resolves fork-of / parent codec-message-ids to node keys, routes
+     * continuation amend wires to existing nodes, and backs UI lookups that hold
+     * a codec-message-id.
+     */
+    private readonly _codecMessageIdToNodeKey;
+    /**
+     * All nodes sorted by their sort serial ({@link sortSerial}: `startSerial`
+     * for runs, `serial` for input nodes), lexicographically. Nodes with no sort
+     * serial (optimistic) sort after all serial-bearing nodes, ordered among
+     * themselves by insertion sequence.
+     */
+    private readonly _sortedNodes;
+    /**
+     * Parent index: parent node key (the key its children's
+     * `parentCodecMessageId` resolves to) to the set of child node keys. Root
+     * nodes (no parent) are indexed under the key `undefined`. Kind-blind — a
+     * reply run and an input node parent off each other through the same index.
+     */
+    private readonly _parentIndex;
+    /**
+     * Reverse edge: an input node's codec-message-id to the set of reply-run ids
+     * parented at it. Lets the View resolve a user prompt to its (selected) reply
+     * run, and groups regenerate siblings (which all parent at the same input
+     * node).
+     */
+    private readonly _replyRunsByInput;
+    /** Monotonically increasing counter for insertion sequence. */
+    private _seqCounter;
+    /** Incremented on structural changes; unchanged on projection-only updates. */
+    private _structuralVersion;
+    /**
+     * Cached sibling-group lookups keyed by node key. The walk over forkOf
+     * chains and the per-parent fan-out are pure functions of the node
+     * graph, so the cache is keyed against {@link _structuralVersion}:
+     * any topology mutation drops the cache and the next lookup
+     * recomputes. Hits matter most during a single render pass where
+     * the View calls `getSiblingNodes` once per visible node plus extra
+     * per-message branch-anchor probes from React components.
+     */
+    private _siblingCache;
+    private _siblingCacheVersion;
+    constructor(codec: Reducer<TInput | TOutput, TProjection>, logger: Logger);
+    /**
+     * Compare two nodes (Run or input) for sorted list ordering.
+     * Serial-bearing nodes sort by their sort serial (`startSerial` for runs,
+     * `serial` for input nodes), lexicographically.
+     * Nodes with no sort serial sort after all serial-bearing nodes.
+     * Among them, sort by insertion sequence.
+     *
+     * Optimistic (null-serial) nodes intentionally tail-sort so they reorder
+     * into place when the server relay arrives and `applyMessage` promotes
+     * startSerial — see {@link applyMessage}'s `_removeSortedNode` /
+     * `_insertSortedNode` pair on the promotion path.
+     * @param a - First node to compare.
+     * @param b - Second node to compare.
+     * @returns Negative if a sorts before b, positive if after, zero if equal.
+     */
+    private _compareNodes;
+    /**
+     * Insert a node into the sorted list at the correct position via binary search.
+     * @param internal - The node to insert.
+     */
+    private _insertSortedNode;
+    /**
+     * Remove a node from the sorted list.
+     * @param internal - The node to remove.
+     */
+    private _removeSortedNode;
+    /**
+     * Insert a freshly-created node into the primary store, the parent index, and
+     * the sorted list, then bump the structural version. Kind-specific secondary
+     * indexing — the codec-message-id map for input nodes, the reply→input edge
+     * for reply runs — is the caller's responsibility.
+     * @param key - The node's primary key ({@link nodeKey}).
+     * @param entry - The internal node to insert.
+     * @param parentCodecMessageId - The node's structural parent, or undefined for a root.
+     */
+    private _insertNode;
+    /**
+     * Re-sort a node whose sort key just changed and bump the structural version.
+     * The caller mutates the serial field (`serial` for input nodes, `startSerial`
+     * for runs); this keeps the sorted list and version in step. Used on the
+     * optimistic-serial promotion paths when the server relay/echo arrives.
+     * @param entry - The internal node whose serial was just promoted.
+     */
+    private _promoteSerial;
+    /**
+     * Fold a batch of events into a node's projection in place, isolating each
+     * fold in a try/catch so a throwing reducer can't abort the rest of the batch
+     * or the surrounding apply.
+     * @param entry - The internal node whose projection is folded in place.
+     * @param events - The decoded events to fold, in wire order.
+     * @param serial - Ably channel serial; coerced to '' for an optimistic insert.
+     * @param messageId - The reducer routing key (codec-message-id), or undefined.
+     */
+    private _foldInto;
+    private _addToParentIndex;
+    private _removeFromParentIndex;
+    /**
+     * Resolve a node's structural parent to the parent node's key
+     * ({@link nodeKey}), or undefined for a root. The parent is named by a
+     * codec-message-id (`parentCodecMessageId`); this maps it through the
+     * codec-message-id index to the owning node's key (a runId for a reply run,
+     * a codec-message-id for an input node). Returns undefined when the parent
+     * hasn't been observed yet (the node is treated as a root until it arrives).
+     * @param node - The node whose parent to resolve.
+     * @returns The parent node's key, or undefined.
+     */
+    private _parentKeyOf;
+    /**
+     * Walk an input node's `forkOf` chain to the group root — the earliest edit
+     * version sharing the same structural parent. Stops at a missing target, a
+     * non-input target, a parent mismatch, or a cycle.
+     * @param node - The input node to walk from.
+     * @returns The group-root input node (the node itself when it is the root).
+     */
+    private _inputGroupRoot;
+    /**
+     * Get the sibling group that the node keyed by `key` belongs to. Kind-split:
+     *
+     * - **Reply runs** — every reply run sharing the same input-node parent is a
+     *   sibling (the original reply + its regenerators all parent at the same
+     *   input node M_user). No fork-of involved.
+     * - **Input nodes** — edit versions: nodes sharing a parent AND linked by a
+     *   `forkOf` chain to the group root.
+     *
+     * Returned ordered by startSerial (original/oldest first). A group of one is
+     * returned as a single-element array (no branching).
+     * @param key - The node key ({@link nodeKey}) to look up the group for.
+     * @returns The ordered list of sibling nodes.
+     */
+    private _getSiblingGroup;
+    /**
+     * Whether `node` belongs to the sibling group anchored at `original`.
+     * Requires the same kind and the same structural parent; reply runs need
+     * nothing more (same-parent runs are regenerate siblings), input nodes must
+     * additionally be forkOf-linked to the original (edit versions).
+     * @param node - The candidate node.
+     * @param original - The group's anchor node.
+     * @returns True if `node` is a sibling of `original`.
+     */
+    private _isSiblingOf;
+    /**
+     * Get the "group root" key for a sibling group — the stable key the
+     * selection map is keyed by. For an input node (edit versions) that is the
+     * earliest fork-of ancestor; for a reply run (regenerate group) it is the
+     * oldest same-parent run (the original reply).
+     * @param key - Any node key in the sibling group.
+     * @returns The group root's key.
+     */
+    getGroupRoot(key: string): string;
+    /**
+     * Walk the visible node chain along the selected branches, kind-blind. An
+     * input node and a reply run reach each other through the same
+     * parent-membership check, so seed-only user→user chains and the
+     * input→reply→input weave both resolve here. Sibling groups (edit versions /
+     * regenerate runs) collapse to the selected member.
+     * @param selections - Per-group selected member key, keyed by group root.
+     * @returns The visible nodes (both kinds) in chronological order.
+     */
+    visibleNodes(selections?: Map<string, string>): ConversationNode<TProjection>[];
+    getRunNode(runId: string): RunNode<TProjection> | undefined;
+    getNode(key: string): ConversationNode<TProjection> | undefined;
+    getNodeByCodecMessageId(codecMessageId: string): ConversationNode<TProjection> | undefined;
+    getReplyRuns(inputCodecMessageId: string): RunNode<TProjection>[];
+    getSiblingNodes(key: string): ConversationNode<TProjection>[];
+    applyMessage(events: {
+        inputs: TInput[];
+        outputs: TOutput[];
+    }, headers: Record<string, string>, serial?: string): void;
+    /**
+     * Apply a run-less user input wire: create (or promote the serial of) the
+     * input node keyed by its codec-message-id, fold the input events into its
+     * own projection, and emit an `output` event (with empty outputs — input
+     * folds carry none) so the View observes the optimistic insert.
+     * @param codecMessageId - The input node's codec-message-id (its primary key).
+     * @param headers - Transport headers from the inbound Ably message.
+     * @param serial - Ably channel serial; undefined for an optimistic insert.
+     * @param all - The decoded input events to fold, in wire order.
+     */
+    private _applyInputMessage;
+    /**
+     * Apply a reply-run wire (assistant output, continuation tool-resolution, or
+     * a fresh run keyed by the agent-minted run-id): create or reconcile the run
+     * node, fold its events, maintain the codec-message-id and reply→input
+     * indices, and emit the `output` event. Derives the codec-message-id,
+     * triggering-input id, fold list, and outputs from `events`/`headers`,
+     * mirroring `applyMessage`.
+     * @param wireRunId - The run-id from the inbound wire (the node's primary key).
+     * @param events - The decoded inputs and outputs from the wire.
+     * @param events.inputs - Client-published events (`ai-input` wire).
+     * @param events.outputs - Agent-published events (`ai-output` wire).
+     * @param headers - Transport headers from the inbound Ably message.
+     * @param serial - Ably channel serial; undefined for an optimistic insert.
+     */
+    private _applyRunMessage;
+    /**
+     * Record a reply run against its input-node parent (the reverse edge powering
+     * `getReplyRuns` and regenerate sibling grouping). A reply run's
+     * `parentCodecMessageId` is its input node's codec-message-id (the master
+     * invariant), so no resolution is needed.
+     * @param node - The reply run node.
+     * @param runId - The run's id.
+     */
+    private _indexReplyRun;
+    applyRunLifecycle(event: RunLifecycleEvent): void;
+    /**
+     * Apply a run-start lifecycle event's structural effect: create the reply
+     * run if it doesn't exist yet, or backfill an optimistic / wire-created
+     * node's structure and metadata from the canonical run-start. Mutates
+     * `_structuralVersion` when the tree shape changes; the caller owns the
+     * `run`/`update` emits.
+     * @param event - The run-start lifecycle event.
+     */
+    private _applyRunStart;
+    /**
+     * Apply a run-suspend lifecycle event: pause the run without ending it —
+     * mark the node 'suspended' and record the serial it paused at, but keep the
+     * Run live so a resume under the same runId resumes it. Status/endSerial are
+     * content, not structure, so this never mutates `_structuralVersion`; the
+     * caller owns the emits.
+     * @param event - The run-suspend lifecycle event.
+     */
+    private _applyRunSuspend;
+    /**
+     * Apply a run-resume lifecycle event: re-enter an already-started run by
+     * flipping a suspended run back to 'active'. Pure re-entry — it carries no
+     * parent/forkOf and does not promote startSerial (the original run-start owns
+     * the run's structure). Only a suspended run resumes: a no-op when the run
+     * isn't known (e.g. a resume replayed from a newer history page before its
+     * run-start) and a no-op for an already-active or terminal
+     * (complete/cancelled/error) run — a stray resume must never resurrect a run
+     * that has ended. The caller owns the emits.
+     * @param event - The run-resume lifecycle event.
+     */
+    private _applyRunResume;
+    /**
+     * Apply a run-end lifecycle event: record the terminal reason as the node's
+     * status and the serial it ended at. Status/endSerial are content, not
+     * structure, so this never mutates `_structuralVersion`; the caller owns the
+     * emits.
+     * @param event - The run-end lifecycle event.
+     */
+    private _applyRunEnd;
+    delete(key: string): void;
+    /**
+     * Build a fresh RunNode from a wire message's headers. Used when an
+     * inbound message arrives before any run-start event for its runId.
+     * @param runId - The run-id from the inbound wire.
+     * @param headers - Transport headers from the inbound Ably message.
+     * @param serial - Ably channel serial; undefined for optimistic inserts.
+     * @returns A newly-allocated internal run node ready for insertion.
+     */
+    private _createRunFromHeaders;
+    /**
+     * Allocate a RunNode from already-resolved fields. Shared by the
+     * header-driven and lifecycle-driven run creators: both build the identical
+     * RunNode literal and stamp an insert sequence.
+     * @param params - The resolved run fields.
+     * @param params.runId - The run's id (its primary key).
+     * @param params.parentCodecMessageId - Structural parent codec-message-id, or undefined for a root.
+     * @param params.forkOf - The resolved fork target's node key (already mapped through the codec-message-id index), or undefined.
+     * @param params.regeneratesCodecMessageId - The codec-message-id this run regenerates, or undefined.
+     * @param params.clientId - The publishing client's id.
+     * @param params.invocationId - The agent invocation id.
+     * @param params.startSerial - Ably channel serial; undefined for optimistic inserts.
+     * @returns A newly-allocated internal run node ready for insertion.
+     */
+    private _buildRunNode;
+    /**
+     * Build a fresh InputNode from a run-less user input wire's headers.
+     * @param codecMessageId - The input's codec-message-id (its primary key).
+     * @param headers - Transport headers from the inbound Ably message.
+     * @param serial - Ably channel serial; undefined for optimistic inserts.
+     * @returns A newly-allocated internal input node ready for insertion.
+     */
+    private _createInputNodeFromHeaders;
+    /**
+     * Build a fresh RunNode from a run-start lifecycle event. Used when a
+     * run-start event arrives before any message for its runId.
+     * @param event - The run-start lifecycle event from the agent, including
+     *   its channel serial.
+     * @returns A newly-allocated internal run node ready for insertion.
+     */
+    private _createRunFromLifecycle;
+    on(event: 'update', handler: () => void): () => void;
+    on(event: 'ably-message', handler: (msg: Ably.InboundMessage) => void): () => void;
+    on(event: 'run', handler: (event: RunLifecycleEvent) => void): () => void;
+    on(event: 'output', handler: (event: OutputEvent<TOutput>) => void): () => void;
+    /**
+     * Forward a raw Ably message event to tree subscribers.
+     * @param msg - The raw Ably message to emit.
+     */
+    emitAblyMessage(msg: Ably.InboundMessage): void;
+}
+/**
+ * Create a Tree that materializes branching conversation history from a flat
+ * oplog of Ably messages as a two-node-per-turn forest (input node + reply run).
+ * @param codec - Codec used to fold inbound events into per-Run projections.
+ * @param logger - Logger for diagnostic output.
+ * @returns A new {@link DefaultTree} instance. The session uses DefaultTree
+ *   directly for internal methods (applyMessage, applyRunLifecycle,
+ *   emitAblyMessage). Public consumers see the narrower {@link Tree} interface.
+ */
+export declare const createTree: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection>(codec: Reducer<TInput | TOutput, TProjection>, logger: Logger) => DefaultTree<TInput, TOutput, TProjection>;