@ably/ai-transport 0.1.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

@@ -14,18 +14,24 @@ export enum ErrorCode {
    */
   InvalidArgument = 40003,
 
+  /**
+   * Operation not permitted with the provided capability (Ably 40160).
+   * Used when the Ably channel rejects a publish for a capability reason.
+   */
+  InsufficientCapability = 40160,
+
   // 104000 - 104999 are reserved for AI Transport SDK errors
 
   /**
-   * Encoder recovery failed after flush — one or more updateMessage calls
+   * 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.
@@ -33,19 +39,19 @@ export enum ErrorCode {
   CancelListenerError = 104002,
 
   /**
-   * A publish within a turn failed (lifecycle event, message, or event).
+   * A publish within a run failed (lifecycle event, message, or event).
    */
-  TurnLifecycleError = 104003,
+  RunLifecycleError = 104003,
 
   /**
-   * An operation was attempted on a transport that has already been closed.
+   * An operation was attempted on a session that has already been closed.
    */
-  TransportClosed = 104004,
+  SessionClosed = 104004,
 
   /**
-   * The HTTP POST to the server endpoint failed (network error or non-2xx response).
+   * The HTTP POST to the agent endpoint failed (network error or non-2xx response).
    */
-  TransportSendFailed = 104005,
+  SessionSendFailed = 104005,
 
   /**
    * The Ably channel lost message continuity — the channel entered FAILED,
@@ -66,6 +72,20 @@ export enum ErrorCode {
    * network failure) or an underlying publish failed mid-stream.
    */
   StreamError = 104008,
+
+  /**
+   * 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/event-emitter.ts

@@ -76,8 +76,9 @@ const toAblyLogger = (logger: Logger): unknown => ({
 });
 
 // CAST: Access Ably's internal EventEmitter constructor. Not publicly exported
-// but available to other Ably SDKs. The logger parameter ensures listener
-// exceptions are caught and logged rather than crashing.
+// but available to other Ably SDKs. Ably always catches listener exceptions
+// internally; the logger parameter ensures those caught exceptions are logged
+// rather than silently swallowed.
 const InternalEventEmitter: new <EventsMap>(logger: unknown) => InterfaceEventEmitter<EventsMap> = (
   Ably.Realtime as unknown as { EventEmitter: new <EventsMap>(logger: unknown) => InterfaceEventEmitter<EventsMap> }
 ).EventEmitter;

package/src/index.ts

@@ -1,87 +1,131 @@
 // Core transport
 export type {
-  ActiveTurn,
-  AddMessageOptions,
-  AddMessagesResult,
-  CancelFilter,
+  ActiveRun,
+  AgentSession,
+  AgentSessionOptions,
+  BranchSelection,
   CancelRequest,
-  ClientTransport,
-  ClientTransportOptions,
-  CloseOptions,
-  EventsNode,
+  ClientSession,
+  ClientSessionOptions,
+  ConversationNode,
+  InputNode,
+  InvocationData,
+  LoadConversationOptions,
   MessageNode,
-  NewTurnOptions,
+  OutputEvent,
+  PipeOptions,
+  Run,
+  RunEndParams,
+  RunEndReason,
+  RunInfo,
+  RunLifecycleEvent,
+  RunNode,
+  RunNodeState,
+  RunRuntime,
+  RunView,
   SendOptions,
-  ServerTransport,
-  ServerTransportOptions,
-  StreamResponseOptions,
   StreamResult,
   Tree,
-  Turn,
-  TurnEndReason,
-  TurnLifecycleEvent,
   View,
 } from './core/transport/index.js';
+export { buildTransportHeaders, createAgentSession, createClientSession, Invocation } from './core/transport/index.js';
 
-// Deprecated aliases — intentional re-export of deprecated types for backwards compatibility.
-// eslint-disable-next-line @typescript-eslint/no-deprecated
-export type { EventNode } from './core/transport/index.js';
-// eslint-disable-next-line @typescript-eslint/no-deprecated
-export type { TreeNode } from './core/transport/index.js';
-export { buildTransportHeaders, createClientTransport, createServerTransport } 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,
-  DecoderOutput,
-  DiscreteEncoder,
+  DefineCodecConfig,
+  DefinedCodec,
+  Encoder,
   EncoderCore,
   EncoderCoreOptions,
   EncoderOptions,
+  EscapeHatchCore,
   Extras,
+  FieldFor,
+  HeaderBuilder,
+  HeaderField,
+  InputBuilder,
+  InputDescriptor,
+  InputEventSpec,
+  LifecycleDiscreteContext,
+  LifecyclePolicy,
   LifecycleTracker,
-  MessageAccumulator,
   MessagePayload,
+  OutputBuilder,
+  OutputDecodeContext,
+  OutputDescriptor,
+  OutputEncodeHatchContext,
+  OutputEventSpec,
+  OutputStreamEndContext,
+  OutputStreamSpec,
+  PartBuilder,
+  PartSpec,
   PhaseConfig,
-  StreamDecoder,
-  StreamEncoder,
+  Reducer,
+  ReducerMeta,
+  Regenerate,
   StreamPayload,
   StreamTrackerState,
+  ToolApprovalResponse,
+  ToolResult,
+  ToolResultError,
+  UserMessage,
+  WellKnownInputFactories,
   WriteOptions,
 } from './core/codec/index.js';
-export { createDecoderCore, createEncoderCore, createLifecycleTracker, eventOutput } from './core/codec/index.js';
+export {
+  boolField,
+  createDecoderCore,
+  createEncoderCore,
+  createLifecycleTracker,
+  defineCodec,
+  enumField,
+  jsonField,
+  strField,
+} from './core/codec/index.js';
 
 // Constants
 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,
+  EVENT_RUN_END,
+  EVENT_RUN_START,
+  HEADER_CODEC_MESSAGE_ID,
+  HEADER_ERROR_CODE,
+  HEADER_ERROR_MESSAGE,
   HEADER_FORK_OF,
-  HEADER_MSG_ID,
+  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,
-  HEADER_TURN_CLIENT_ID,
-  HEADER_TURN_ID,
-  HEADER_TURN_REASON,
 } from './constants.js';
 
 // Utilities
-export type { DomainHeaderReader, DomainHeaderWriter, Stripped } from './utils.js';
-export { getHeaders, 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/logger.ts

@@ -143,10 +143,22 @@ export const consoleLogger = (message: string, level: LogLevel, context?: LogCon
  * 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 const makeLogger = (options: LoggerOptions): Logger => {
   const logHandler = options.logHandler ?? consoleLogger;
 
@@ -218,7 +230,8 @@ class DefaultLogger implements Logger {
   }
 
   withContext(context: LogContext): Logger {
-    // Get the original log level by finding the key in logLevelNumberMap that matches this._levelNumber
+    // Get the original log level by finding the key in logLevelNumberMap that matches this._levelNumber.
+    // The Error fallback is defensive and unreachable in practice: _levelNumber always originates from the map.
     const originalLevel =
       [...logLevelNumberMap.entries()].find(([, value]) => value === this._levelNumber)?.[0] ?? LogLevel.Error;
 

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

@@ -0,0 +1,41 @@
+import type * as Ably from 'ably';
+import { createContext } from 'react';
+
+import type { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import type { ClientSession } from '../../core/transport/types.js';
+
+/**
+ * A single entry in the client-session registry, holding the session and any
+ * error that occurred during its construction.
+ *
+ * `session` is `undefined` when construction failed.
+ * `sessionError` is set when `createClientSession` threw during provider render.
+ */
+export interface ClientSessionSlot {
+  /** The constructed session, or `undefined` if construction failed. */
+  session: ClientSession<CodecInputEvent, CodecOutputEvent, unknown, unknown> | undefined;
+  /** Construction error from `createClientSession`, or `undefined` on success. */
+  sessionError?: Ably.ErrorInfo | undefined;
+}
+
+/**
+ * The shape of the {@link ClientSessionContext} value.
+ *
+ * `nearest` is the slot from the innermost enclosing {@link ClientSessionProvider}.
+ * `providers` is the full registry of all enclosing providers, keyed by channelName.
+ */
+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. */
+  providers: Readonly<Record<string, ClientSessionSlot>>;
+}
+
+/**
+ * Unified client-session context.
+ *
+ * Holds the nearest client-session slot and the full registry of all registered
+ * slots keyed by channelName. Populated by {@link ClientSessionProvider};
+ * read by {@link useClientSession} and internal hooks.
+ */
+export const ClientSessionContext = createContext<ClientSessionContextValue>({ nearest: undefined, providers: {} });