@ably/ai-transport 0.0.1 → 0.1.0

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

@@ -0,0 +1,166 @@
+import { Logger } from '../../logger.js';
+import { Codec } from '../codec/types.js';
+import { TreeInternal } from './tree.js';
+import { ActiveTurn, EventsNode, MessageNode, SendOptions, TurnLifecycleEvent, View } from './types.js';
+/**
+ * DefaultView — a paginated, branch-aware projection over the Tree.
+ *
+ * Wraps a Tree and manages a pagination window that controls which nodes
+ * are visible to the UI. New live messages appear immediately; older messages
+ * are revealed progressively via `loadOlder()`.
+ *
+ * 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 nodes, and 'turn' only for turns with visible messages.
+ */
+import * as Ably from 'ably';
+/**
+ * Internal delegate function provided by the transport for executing sends.
+ * The View pre-computes the visible branch history and passes it directly,
+ * so the delegate has no back-reference to the View.
+ * When `eventNodes` is provided, the transport includes them in the POST body
+ * for the server to publish as cross-turn events.
+ */
+export type SendDelegate<TEvent, TMessage> = (input: TMessage | TMessage[], options: SendOptions | undefined, history: MessageNode<TMessage>[], eventNodes?: EventsNode<TEvent>[]) => Promise<ActiveTurn<TEvent>>;
+/** Options for creating a View. */
+export interface ViewOptions<TEvent, TMessage> {
+    /** The tree to project. */
+    tree: TreeInternal<TMessage>;
+    /** The Ably channel to load history from. */
+    channel: Ably.RealtimeChannel;
+    /** The codec for decoding history messages. */
+    codec: Codec<TEvent, TMessage>;
+    /** Delegate for executing sends through the transport. */
+    sendDelegate: SendDelegate<TEvent, TMessage>;
+    /** 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<TEvent, TMessage> implements View<TEvent, 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 msgId → selection intent.
+     * Fork points not present here default to the latest sibling.
+     * Replaces the previous numeric-index _selections and _pendingForkSelections
+     * with a single tagged-union map that carries the selected msgId (not index)
+     * and the reason for the selection.
+     */
+    private readonly _branchSelections;
+    /** Spec: AIT-CT11c — msg-ids loaded from history but not yet revealed to the UI. */
+    private readonly _withheldMsgIds;
+    /** Snapshot of visible msgIds — used to detect structural changes and for selection pinning. */
+    private _lastVisibleIds;
+    /** Snapshot of visible message references — used to detect in-place content updates (streaming). */
+    private _lastVisibleMessages;
+    /** Cached set of turn IDs present on the visible branch — avoids recomputing flattenNodes() on turn events. */
+    private _lastVisibleTurnIds;
+    /** 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, drained newest-first by successive loadOlder() calls. */
+    private readonly _withheldBuffer;
+    /** Unsubscribe functions for tree event subscriptions. */
+    private readonly _unsubs;
+    /**
+     * Cached result of the last flattenNodes computation. Public `flattenNodes()`
+     * returns this in O(1); internal callers use `_computeFlatNodes()` when a
+     * fresh tree walk is needed (structural changes, selection changes, history reveal).
+     */
+    private _cachedNodes;
+    /** Last seen tree structural version - used to distinguish content-only from structural updates. */
+    private _lastStructuralVersion;
+    private _loadingOlder;
+    private _processingHistory;
+    private _closed;
+    constructor(options: ViewOptions<TEvent, TMessage>);
+    getMessages(): TMessage[];
+    flattenNodes(): MessageNode<TMessage>[];
+    /**
+     * Walk the tree and compute a fresh visible node list, applying branch
+     * selections and withheld-message filtering. Use this instead of the
+     * public `flattenNodes()` when the cache may be stale (structural
+     * changes, selection changes, history reveal).
+     * @returns A fresh array of visible nodes.
+     */
+    private _computeFlatNodes;
+    hasOlder(): boolean;
+    loadOlder(limit?: number): Promise<void>;
+    select(msgId: string, index: number): void;
+    getSelectedIndex(msgId: string): number;
+    getSiblings(msgId: string): TMessage[];
+    hasSiblings(msgId: string): boolean;
+    getNode(msgId: string): MessageNode<TMessage> | undefined;
+    send(input: TMessage | TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>>;
+    regenerate(messageId: string, options?: SendOptions): Promise<ActiveTurn<TEvent>>;
+    edit(messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>>;
+    update(msgId: string, events: TEvent[], options?: SendOptions): Promise<ActiveTurn<TEvent>>;
+    private _getHistoryBefore;
+    getActiveTurnIds(): Map<string, Set<string>>;
+    on(event: 'update', handler: () => void): () => void;
+    on(event: 'ably-message', handler: (msg: Ably.InboundMessage) => void): () => void;
+    on(event: 'turn', handler: (event: TurnLifecycleEvent) => void): () => void;
+    /**
+     * Tear down the view — unsubscribe from tree events.
+     */
+    close(): void;
+    private _loadFirstPage;
+    private _loadAndReveal;
+    private _processHistoryPage;
+    private _loadUntilVisible;
+    private _releaseWithheld;
+    private _updateVisibleSnapshot;
+    private _onTreeUpdate;
+    /**
+     * Build a resolved selections map from `_branchSelections` for passing
+     * to `tree.flattenNodes()`. Pending entries (no sibling yet) are omitted,
+     * causing the tree to use the default (latest sibling).
+     * @returns Resolved map of groupRoot → selectedMsgId.
+     */
+    private _resolveSelections;
+    /**
+     * For each previously-visible message that now has siblings but no
+     * explicit selection, pin the selection to that message's msgId.
+     * 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 instead of
+     * pinning the old one. This handles regenerate, where no optimistic
+     * insert was possible at send time.
+     */
+    private _pinBranchSelections;
+    /**
+     * Resolve pending selections that are no longer on the visible branch.
+     * `_pinBranchSelections` only checks visible nodes, so if the user navigated
+     * away before the server response arrived, the pending entry would linger.
+     * This pass checks all pending entries against the tree directly.
+     */
+    private _resolvePendingSelections;
+    private _onTreeAblyMessage;
+    private _onTreeTurn;
+    /**
+     * Predict whether a turn-start's messages will be visible on this view's branch
+     * using the parent/forkOf metadata from the event.
+     * @param event - The turn-start lifecycle event with optional branch metadata.
+     * @returns True if the turn's messages are expected to be visible on this view's branch.
+     */
+    private _isTurnStartVisible;
+    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: <TEvent, TMessage>(options: ViewOptions<TEvent, TMessage>) => DefaultView<TEvent, TMessage>;

package/dist/errors.d.ts

@@ -25,7 +25,7 @@ export declare enum ErrorCode {
      */
     CancelListenerError = 104002,
     /**
-     * A turn lifecycle event (turn-start or turn-end) failed to publish.
+     * A publish within a turn failed (lifecycle event, message, or event).
      */
     TurnLifecycleError = 104003,
     /**
@@ -35,7 +35,24 @@ export declare enum ErrorCode {
     /**
      * The HTTP POST to the server endpoint failed (network error or non-2xx response).
      */
-    TransportSendFailed = 104005
+    TransportSendFailed = 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).
+     */
+    ChannelNotReady = 104007,
+    /**
+     * 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.
+     */
+    StreamError = 104008
 }
 /**
  * Returns true if the {@link Ably.ErrorInfo} code matches the provided ErrorCode value.

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-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 type { ActiveTurn, AddMessageOptions, AddMessagesResult, CancelFilter, CancelRequest, ClientTransport, ClientTransportOptions, CloseOptions, EventsNode, MessageNode, NewTurnOptions, SendOptions, ServerTransport, ServerTransportOptions, StreamResponseOptions, StreamResult, Tree, Turn, TurnEndReason, TurnLifecycleEvent, View, } from './core/transport/index.js';
+export type { EventNode } from './core/transport/index.js';
+export type { TreeNode } 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';