@ably/ai-transport 0.2.0 → 0.3.0

package/dist/core/transport/wire-log.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Per-node event log.
+ *
+ * Each node retains the decoded events it was folded from, grouped by
+ * wire-message serial and ordered ascending by serial. The log captures
+ * canonical serial order regardless of delivery order, so a node's event
+ * sequence can be re-derived in that order even when wires arrive late
+ * (cross-publisher reordering) or out of order (history pages applying older
+ * messages after newer ones).
+ *
+ * Within one serial, deliveries are sequenced by `Message.version.serial`
+ * (lexicographically ordered per mutation — platform guarantee): each entry
+ * records the highest version decoded into it, so a delivery the entry has
+ * already incorporated — a whole-wire replay from a second hydration, a
+ * remount, or an agent re-walk — is recognised and dropped at the transport.
+ *
+ * {@link WireLog} encapsulates the entry list and all of its mutation: the
+ * caller hands it a wire and is told only how to fold (see {@link WireLogFold}).
+ */
+/** How a {@link WireLog.record} call tells the caller to fold the wire's events. */
+export type WireLogFold = 
+/**
+ * The version guard rejected a re-delivery the log already incorporated — a
+ * whole-wire replay, or a newer version of a non-streamed wire (an edited
+ * discrete). Nothing was recorded; fold nothing.
+ */
+'dropped'
+/**
+ * The events extend the log tail (in-order delivery) or landed on a swept
+ * log; fold them onto the node's existing projection.
+ */
+ | 'incremental'
+/**
+ * An earlier-serial wire arrived late, so incremental folding would corrupt
+ * serial order; rebuild the projection from the whole log via {@link replay}.
+ */
+ | 'refold';
+/**
+ * A node's event log: one entry per wire-message serial, kept ascending by
+ * serial, each accumulating that serial's decoded events in arrival order.
+ */
+export declare class WireLog<TEvent> {
+    private readonly _entries;
+    private _swept;
+    /**
+     * Whether the retention sweep has dropped this log's decoded payloads. A
+     * swept log keeps each entry's replay key (serial + `decodedThrough`) so it
+     * still recognises whole-wire replays, but it can no longer be refolded.
+     * @returns True once {@link sweep} has run.
+     */
+    get swept(): boolean;
+    /**
+     * Record a wire message's decoded events and report how to fold them.
+     *
+     * Events for an already-logged serial are guarded by the entry's
+     * `decodedThrough` version before being recorded; a new serial is inserted
+     * at the position that keeps the log ascending by serial (Ably serials order
+     * lexicographically). The version guard fires only for deliveries carrying
+     * an explicit `version.serial`: in-contract mutations always do, while a
+     * version-less delivery records unguarded (and never advances
+     * `decodedThrough`), matching the decoder's convention.
+     *
+     * On a swept log the payload is not retained (only the replay key is), so
+     * the fold is never `refold` — a genuinely-new wire there is outside the
+     * reorder window and folds incrementally in arrival order.
+     * @param serial - The Ably channel serial of the wire message.
+     * @param messageId - The wire's codec-message-id, or undefined.
+     * @param events - The decoded events to record, in arrival order.
+     * @param version - The delivery's `Message.version.serial`, or undefined
+     *   when the delivery carried none (guard disabled for this delivery).
+     * @param streamed - Whether the delivery is part of a streamed wire; a
+     *   guarded newer delivery for a non-streamed wire is an edited discrete and
+     *   is dropped.
+     * @returns How the caller should fold the events.
+     */
+    record(serial: string, messageId: string | undefined, events: TEvent[], version: string | undefined, streamed: boolean): WireLogFold;
+    /**
+     * Replay every recorded event in canonical order — wire messages ascending
+     * by serial, events within a wire in arrival order — each with its wire's
+     * routing metadata, for a refold.
+     * @param visit - Called once per event, in canonical order.
+     */
+    replay(visit: (event: TEvent, serial: string, messageId: string | undefined) => void): void;
+    /**
+     * Drop the decoded payloads (the unbounded cost) but keep each entry's
+     * replay key, so a post-sweep whole-wire replay is still recognised and
+     * dropped rather than re-folded. The log becomes {@link swept}; a refold can
+     * no longer rebuild the dropped events, which `swept` reflects.
+     */
+    sweep(): void;
+    /**
+     * Insert or extend the entry for `serial`, guarding replays by version.
+     * @param serial - The Ably channel serial of the wire message.
+     * @param messageId - The wire's codec-message-id, or undefined.
+     * @param events - The decoded events to store (empty on a swept log).
+     * @param version - The delivery's `Message.version.serial`, or undefined.
+     * @param streamed - Whether the delivery is part of a streamed wire.
+     * @returns The index of the entry the events landed in, or `undefined` when
+     *   the version guard dropped the delivery.
+     */
+    private _recordEntry;
+}

package/dist/errors.d.ts

@@ -59,11 +59,17 @@ export declare enum ErrorCode {
      */
     StreamError = 104008,
     /**
-     * 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.
+     * The agent waited for the input event(s) the invocation points at —
+     * across the bounded history scan and the live subscription — but
+     * `inputEventLookupTimeoutMs` lapsed without seeing them.
      */
-    InputEventNotFound = 104010
+    InputEventNotFound = 104010,
+    /**
+     * Channel history pagination failed after bounded retry — either the initial
+     * `channel.history()` call or a subsequent `page.next()` exhausted its
+     * retry budget. The original failure is preserved as `cause`.
+     */
+    HistoryFetchFailed = 104011
 }
 /**
  * Returns true if the {@link Ably.ErrorInfo} code matches the provided ErrorCode value.

package/dist/index.d.ts

@@ -1,10 +1,11 @@
-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 type { ActiveRun, AgentSession, AgentSessionOptions, BranchSelection, CancelRequest, ClientSession, ClientSessionOptions, ConversationNode, InputNode, InvocationData, LoadConversationOptions, MessageNode, OutputEvent, PipeOptions, Run, RunEndParams, RunEndReason, RunInfo, RunLifecycleEvent, RunNode, RunNodeState, 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 { OBJECT_MODES } from './core/channel-options.js';
+export type { BatchAssembleContext, BatchMessageHeaders, BatchSpec, ChannelWriter, Codec, CodecEvent, CodecInputEvent, CodecMessage, CodecOutputEvent, CodecReducer, DataCodec, DecodedMessage, Decoder, DecoderCore, DecoderCoreHooks, DecoderCoreOptions, DefineCodecConfig, DefinedCodec, Encoder, EncoderCore, EncoderCoreOptions, EncoderOptions, EscapeHatchCore, Extras, FieldFor, HeaderBuilder, HeaderField, InputBuilder, InputDescriptor, InputEventSpec, LifecycleDiscreteContext, LifecyclePolicy, LifecycleTracker, MessagePayload, OutputBuilder, OutputDecodeContext, OutputDescriptor, OutputEncodeHatchContext, OutputEventSpec, OutputStreamEndContext, OutputStreamSpec, PartBuilder, PartSpec, PhaseConfig, Reducer, ReducerMeta, Regenerate, StreamPayload, StreamTrackerState, ToolApprovalResponse, ToolResult, ToolResultError, UserMessage, WellKnownInputFactories, WriteOptions, } from './core/codec/index.js';
+export { boolField, createDecoderCore, createEncoderCore, createLifecycleTracker, defineCodec, enumField, jsonField, strField, } 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 { getCodecHeaders, getTransportHeaders, headerReader, headerWriter, mergeHeaders, stripUndefined, } from './utils.js';
+export type { Stripped } from './utils.js';
+export { getCodecHeaders, getTransportHeaders, 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';