@ably/ai-transport 0.2.0 → 0.3.0

package/src/core/transport/wire-log.ts

@@ -0,0 +1,189 @@
+/**
+ * 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}).
+ */
+
+/** One wire message in a node's event log: a serial and its decoded events. */
+interface WireLogEntry<TEvent> {
+  /** Ably channel serial of the wire message. */
+  serial: string;
+  /**
+   * The wire's codec-message-id — the reducer routing key the events were
+   * folded alongside; undefined when the wire carried none.
+   */
+  messageId: string | undefined;
+  /**
+   * The decoded events from this wire message's deliveries, in arrival order.
+   * Same-serial deliveries (the create plus each append/update) extend the
+   * entry, so the list accumulates across deliveries.
+   */
+  events: TEvent[];
+  /**
+   * The highest `Message.version.serial` decoded into this entry. Versions
+   * are lexicographically comparable within one serial, so a delivery at or
+   * below this value is already incorporated and must not fold again. In
+   * practice every delivery carries a version (a never-mutated message's
+   * version serial equals its serial); the message serial is used as the floor
+   * only as a defensive fallback for the type-optional absent case.
+   */
+  decodedThrough: string;
+}
+
+/** 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 class WireLog<TEvent> {
+  private readonly _entries: WireLogEntry<TEvent>[] = [];
+  private _swept = false;
+
+  /**
+   * 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 {
+    return this._swept;
+  }
+
+  /**
+   * 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 {
+    // A swept log retains replay keys but not payloads: record an empty event
+    // list so the key advances while nothing is stored. The caller folds the
+    // events it already holds.
+    const index = this._recordEntry(serial, messageId, this._swept ? [] : events, version, streamed);
+    if (index === undefined) return 'dropped';
+    if (this._swept) return 'incremental';
+    return index === this._entries.length - 1 ? 'incremental' : 'refold';
+  }
+
+  /**
+   * 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 {
+    for (const entry of this._entries) {
+      for (const event of entry.events) visit(event, entry.serial, entry.messageId);
+    }
+  }
+
+  /**
+   * 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 {
+    this._swept = true;
+    for (const entry of this._entries) entry.events.length = 0;
+  }
+
+  /**
+   * 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(
+    serial: string,
+    messageId: string | undefined,
+    events: TEvent[],
+    version: string | undefined,
+    streamed: boolean,
+  ): number | undefined {
+    // Scan from the tail: live delivery appends at (or extends) the end, so the
+    // match is almost always within the last entry or two.
+    for (let i = this._entries.length - 1; i >= 0; i--) {
+      const entry = this._entries[i];
+      if (!entry) break; // unreachable
+      if (entry.serial === serial) {
+        // Version guard: drop a re-delivery the entry already incorporated — a
+        // replay (version at or below the high-water-mark) or an edit to a
+        // discrete (a newer version of a non-streamed wire, not propagated).
+        if (version !== undefined && (version <= entry.decodedThrough || !streamed)) {
+          return undefined;
+        }
+        entry.events.push(...events);
+        if (version !== undefined) entry.decodedThrough = version;
+        return i;
+      }
+      if (entry.serial < serial) {
+        this._entries.splice(i + 1, 0, { serial, messageId, events: [...events], decodedThrough: version ?? serial });
+        return i + 1;
+      }
+    }
+    // Lower than every logged serial (or the log is empty): insert at the head.
+    this._entries.unshift({ serial, messageId, events: [...events], decodedThrough: version ?? serial });
+    return 0;
+  }
+}

package/src/errors.ts

@@ -74,11 +74,18 @@ export 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,
+
+  /**
+   * 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,
 }
 
 /**

package/src/index.ts

@@ -8,7 +8,6 @@ export type {
   ClientSession,
   ClientSessionOptions,
   ConversationNode,
-  EventsNode,
   InputNode,
   InvocationData,
   LoadConversationOptions,
@@ -16,10 +15,12 @@ export type {
   OutputEvent,
   PipeOptions,
   Run,
+  RunEndParams,
   RunEndReason,
   RunInfo,
   RunLifecycleEvent,
   RunNode,
+  RunNodeState,
   RunRuntime,
   RunView,
   SendOptions,
@@ -29,25 +30,54 @@ export type {
 } from './core/transport/index.js';
 export { buildTransportHeaders, createAgentSession, createClientSession, Invocation } from './core/transport/index.js';
 
+// Channel modes
+export { OBJECT_MODES } from './core/channel-options.js';
+
 // Core codec
 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,
@@ -58,9 +88,19 @@ export type {
   ToolResult,
   ToolResultError,
   UserMessage,
+  WellKnownInputFactories,
   WriteOptions,
 } from './core/codec/index.js';
-export { createDecoderCore, createEncoderCore, createLifecycleTracker } from './core/codec/index.js';
+export {
+  boolField,
+  createDecoderCore,
+  createEncoderCore,
+  createLifecycleTracker,
+  defineCodec,
+  enumField,
+  jsonField,
+  strField,
+} from './core/codec/index.js';
 
 // Constants
 export {
@@ -84,15 +124,8 @@ export {
 } from './constants.js';
 
 // Utilities
-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';
 
 // Event emitter
 export { EventEmitter } from './event-emitter.js';

package/src/react/contexts/client-session-context.ts

@@ -24,7 +24,7 @@ export interface ClientSessionSlot {
  * `nearest` is the slot from the innermost enclosing {@link ClientSessionProvider}.
  * `providers` is the full registry of all enclosing providers, keyed by channelName.
  */
-export interface ClientSessionContextValue {
+interface ClientSessionContextValue {
   /** The innermost {@link ClientSessionProvider}'s slot. `undefined` when no provider is present. */
   nearest: ClientSessionSlot | undefined;
   /** All registered session slots from enclosing providers, keyed by channelName. */

package/src/react/contexts/client-session-provider.tsx

@@ -22,12 +22,20 @@
  * Multiple ClientSessionProviders can be nested using distinct channelNames.
  * Each provider merges its slot into the parent record so descendants
  * can access all registered sessions via useClientSession(channelName).
+ *
+ * The provider also wraps its children in ably-js's `<ChannelProvider>` for the
+ * session's channel, so descendants can use ably-js channel hooks
+ * (`usePresence`, `useChannel`, etc.) against it without adding their own. It
+ * seeds the ChannelProvider's `options` with this SDK's channel agent so the
+ * hooks' agent is appended rather than overwriting it (ably-js >= 2.22).
  */
 
 import * as Ably from 'ably';
-import { useAbly } from 'ably/react';
+import { ChannelProvider, useAbly } from 'ably/react';
 import { type PropsWithChildren, type ReactNode, useContext, useEffect, useMemo, useRef } from 'react';
 
+import { channelAgent } from '../../core/agent.js';
+import { resolveChannelModes } from '../../core/channel-options.js';
 import type { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
 import { createClientSession } from '../../core/transport/client-session.js';
 import type { ClientSession, ClientSessionOptions } from '../../core/transport/types.js';
@@ -86,6 +94,9 @@ export interface ClientSessionProviderProps<
  * const { session: main } = useClientSession({ channelName: 'ai:main' });
  * const { session: aux }  = useClientSession({ channelName: 'ai:aux' });
  * ```
+ * `channelModes` must stay constant for the provider's lifetime: the session is
+ * only recreated when `channelName` changes, and removing the modes after mount
+ * silently reverts the channel's mode set without a reattach.
  * @param props - Provider configuration including `channelName`, `codec`, and all other {@link ClientSessionOptions} except `client`.
  * @param props.children - Descendant components that consume the session via {@link useClientSession}.
  * @returns A React element wrapping children with ClientSessionContext.
@@ -101,6 +112,22 @@ export const ClientSessionProvider = <
 }: ClientSessionProviderProps<TInput, TOutput, TProjection, TMessage>): ReactNode => {
   const client = useAbly();
   const { channelName } = sessionOptions;
+
+  // Seed the ChannelProvider with this SDK's channel agent so ably-js's React
+  // hooks append their agent (`channelOptionsForReactHooks`) rather than
+  // overwriting it. Memoised on the codec, which determines the agent string.
+  //
+  // Spec: AIT-CT23 — resolve the channel modes through the same helper the
+  // session uses so the provider and the session request an identical,
+  // identically-ordered mode set. ably-js compares modes order- and
+  // duplicate-sensitively, so matching arrays mean the provider's setOptions
+  // never triggers a reattach and never silently reverts the session's modes.
+  const channelOptions = useMemo<Ably.ChannelOptions>(() => {
+    const options: Ably.ChannelOptions = { params: { agent: channelAgent(sessionOptions.codec) } };
+    const modes = resolveChannelModes(sessionOptions.channelModes);
+    if (modes) options.modes = modes;
+    return options;
+  }, [sessionOptions.codec, sessionOptions.channelModes]);
   const sessionRef = useRef<ClientSession<TInput, TOutput, TProjection, TMessage> | undefined>(undefined);
   const sessionChannelRef = useRef<string>(channelName);
   const sessionsToDisposeRef = useRef<ClientSession<CodecInputEvent, CodecOutputEvent, unknown, unknown>[]>([]);
@@ -182,5 +209,14 @@ export const ClientSessionProvider = <
     };
   }, []);
 
-  return <ClientSessionContext.Provider value={contextValue}>{children}</ClientSessionContext.Provider>;
+  return (
+    <ClientSessionContext.Provider value={contextValue}>
+      <ChannelProvider
+        channelName={channelName}
+        options={channelOptions}
+      >
+        {children}
+      </ChannelProvider>
+    </ClientSessionContext.Provider>
+  );
 };

package/src/react/index.ts

@@ -1,14 +1,15 @@
+export { OBJECT_MODES } from '../core/channel-options.js';
 export type { CodecMessage } from '../core/codec/types.js';
 export type {
   ActiveRun,
   BranchSelection,
   ClientSession,
   ConversationNode,
-  EventsNode,
   InputNode,
   MessageNode,
   RunInfo,
   RunNode,
+  RunNodeState,
   SendOptions,
 } from '../core/transport/types.js';
 export type { ClientSessionSlot } from './contexts/client-session-context.js';

package/src/react/internal/skipped-session.ts

@@ -0,0 +1,62 @@
+/**
+ * The stub {@link ClientSession} returned by the context-reader hooks when they
+ * are skipped, when no provider is found, or when session construction failed.
+ * Every member throws so a held-but-unusable session fails loudly rather than
+ * silently no-ops. Generic so each consumer gets a session typed to its own
+ * codec parameters without a cast — the throwing bodies satisfy any instantiation.
+ */
+
+import * as Ably from 'ably';
+import type * as AblyObjects from 'ably/liveobjects';
+
+import type { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import type { ClientSession, Tree, View } from '../../core/transport/types.js';
+import { ErrorCode } from '../../errors.js';
+
+/**
+ * Build the `hook is skipped` error for a stub member.
+ * @param operation - The attempted operation, phrased for the `unable to <operation>; hook is skipped` message.
+ * @returns The skipped-hook error.
+ */
+const skipped = (operation: string): Ably.ErrorInfo =>
+  new Ably.ErrorInfo(`unable to ${operation}; hook is skipped`, ErrorCode.InvalidArgument, 400);
+
+/**
+ * Create a throwing stub {@link ClientSession}. Held safely in state before a
+ * provider resolves; any access throws {@link Ably.ErrorInfo}.
+ * @returns A stub session whose every member throws.
+ */
+export const makeSkippedClientSession = <
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+>(): ClientSession<TInput, TOutput, TProjection, TMessage> => ({
+  get tree(): Tree<TOutput, TProjection> {
+    throw skipped('access tree');
+  },
+  get view(): View<TInput, TMessage> {
+    throw skipped('access view');
+  },
+  get presence(): Ably.RealtimePresence {
+    throw skipped('access presence');
+  },
+  get object(): AblyObjects.RealtimeObject {
+    throw skipped('access object');
+  },
+  connect: () => {
+    throw skipped('connect');
+  },
+  createView: (): View<TInput, TMessage> => {
+    throw skipped('create view');
+  },
+  cancel: () => {
+    throw skipped('cancel');
+  },
+  on: () => {
+    throw skipped('subscribe');
+  },
+  close: () => {
+    throw skipped('close');
+  },
+});

package/src/react/use-client-session.ts

@@ -23,33 +23,10 @@ import * as Ably from 'ably';
 import { useContext, useEffect, useRef } from 'react';
 
 import type { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
-import type { ClientSession, Tree, View } from '../core/transport/types.js';
+import type { ClientSession } from '../core/transport/types.js';
 import { ErrorCode } from '../errors.js';
 import { ClientSessionContext } from './contexts/client-session-context.js';
-
-const SKIPPED_SESSION: ClientSession<CodecInputEvent, CodecOutputEvent, unknown, unknown> = {
-  get tree(): Tree<CodecOutputEvent, unknown> {
-    throw new Ably.ErrorInfo('unable to access tree; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  get view(): View<CodecInputEvent, unknown> {
-    throw new Ably.ErrorInfo('unable to access view; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  connect: () => {
-    throw new Ably.ErrorInfo('unable to connect; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  createView: (): View<CodecInputEvent, unknown> => {
-    throw new Ably.ErrorInfo('unable to create view; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  cancel: () => {
-    throw new Ably.ErrorInfo('unable to cancel; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  on: () => {
-    throw new Ably.ErrorInfo('unable to subscribe; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  close: () => {
-    throw new Ably.ErrorInfo('unable to close; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-};
+import { makeSkippedClientSession } from './internal/skipped-session.js';
 
 /**
  * Return value of {@link useClientSession}.
@@ -146,7 +123,7 @@ export const useClientSession = <
 
   if (skip) {
     return {
-      session: SKIPPED_SESSION as unknown as ClientSession<TInput, TOutput, TProjection, TMessage>,
+      session: makeSkippedClientSession<TInput, TOutput, TProjection, TMessage>(),
     };
   }
 
@@ -162,12 +139,12 @@ export const useClientSession = <
       }
       // Provider exists but construction failed.
       return {
-        session: SKIPPED_SESSION as unknown as ClientSession<TInput, TOutput, TProjection, TMessage>,
+        session: makeSkippedClientSession<TInput, TOutput, TProjection, TMessage>(),
         sessionError: slot.sessionError,
       };
     }
     return {
-      session: SKIPPED_SESSION as unknown as ClientSession<TInput, TOutput, TProjection, TMessage>,
+      session: makeSkippedClientSession<TInput, TOutput, TProjection, TMessage>(),
       sessionError: new Ably.ErrorInfo(
         `unable to use session; no ClientSessionProvider found for channelName "${channelName}"`,
         ErrorCode.BadRequest,
@@ -185,13 +162,13 @@ export const useClientSession = <
     }
     // Nearest provider exists but construction failed.
     return {
-      session: SKIPPED_SESSION as unknown as ClientSession<TInput, TOutput, TProjection, TMessage>,
+      session: makeSkippedClientSession<TInput, TOutput, TProjection, TMessage>(),
       sessionError: nearestSlot.sessionError,
     };
   }
 
   return {
-    session: SKIPPED_SESSION as unknown as ClientSession<TInput, TOutput, TProjection, TMessage>,
+    session: makeSkippedClientSession<TInput, TOutput, TProjection, TMessage>(),
     sessionError: new Ably.ErrorInfo(
       'unable to use session; no ClientSessionProvider found in the tree',
       ErrorCode.BadRequest,

package/src/react/use-view.ts

@@ -26,7 +26,7 @@ export interface UseViewOptions<
 > extends BaseSessionOption<TInput, TOutput, TProjection, TMessage> {
   /** A specific {@link View} to subscribe to directly. Takes priority over `session`. */
   view?: View<TInput, TMessage> | null;
-  /** Maximum number of older Runs to reveal per page (the pagination unit is the Run, not the message). When provided, auto-loads the first page on mount. */
+  /** Number of older codecMessages to reveal per page (exactly `limit`, fewer only at the end of history). When provided, auto-loads the first page on mount. */
   limit?: number;
   /** When `true`, skip all subscriptions and return an empty handle immediately. */
   skip?: boolean;
@@ -46,7 +46,7 @@ export interface ViewHandle<TInput extends CodecInputEvent, TMessage> {
    * identity the domain `message` may carry. See {@link View.getMessages}.
    */
   messages: CodecMessage<TMessage>[];
-  /** Whether there are older Runs that can be revealed via `loadOlder`. */
+  /** Whether there are older messages that can be revealed via `loadOlder`. */
   hasOlder: boolean;
   /** Whether a page load is currently in progress. */
   loading: boolean;
@@ -128,7 +128,7 @@ const EMPTY_BRANCH_SELECTION: BranchSelection<never> = {
  * @param props - Options for selecting the view source and configuring auto-load.
  * @param props.session - Client session whose default view to subscribe to; defaults to the nearest provider.
  * @param props.view - A specific {@link View} to subscribe to directly. Takes priority over `session`.
- * @param props.limit - Max older Runs to reveal per page; when provided, auto-loads the first page on mount.
+ * @param props.limit - Number of older codecMessages to reveal per page (exactly `limit`, fewer only at end of history); when provided, auto-loads the first page on mount.
  * @param props.skip - When `true`, skip all subscriptions and return an empty handle.
  * @returns A {@link ViewHandle} with messages, pagination state, navigation, write operations, and loadOlder.
  */