@ably/ai-transport 0.1.0 → 0.3.0

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

@@ -0,0 +1,74 @@
+/**
+ * Invocation — value object wrapping the JSON body that a client sends to
+ * an agent's HTTP endpoint to start a run.
+ *
+ * The data shape is the wire contract; the {@link Invocation} class is a
+ * runtime view of that data with the same fields. {@link Invocation.fromJSON}
+ * is the entry point used by agent handlers:
+ *
+ * ```ts
+ * const data = (await req.json()) as InvocationData;
+ * const invocation = Invocation.fromJSON(data);
+ * const run = session.createRun(invocation, { signal: req.signal });
+ * await run.start();
+ * await run.loadConversation(); // walk channel history into the session tree
+ * const messages = run.messages;
+ * ```
+ *
+ * The body carries only what the agent needs out-of-band before the channel
+ * is observable: the session/channel name and the `inputEventId` that triggered
+ * the invocation. The agent mints the `invocationId` itself (one per HTTP
+ * request) and returns it on the HTTP response, so it is not a body field. Run
+ * identity also lives on the channel: the agent mints the `runId` for a fresh
+ * run and reads the existing `runId` off the triggering input event for a
+ * continuation — so the body carries no run-id either. Per-message metadata —
+ * `clientId`, `parent`, `forkOf`, continuation status — likewise lives on the
+ * channel and is resolved by the agent from the triggering input event, not
+ * from the body. The `inputClientId` the agent re-stamps on its own publishes
+ * comes from the publisher's Ably `clientId` on the matched input event, not
+ * from a body field.
+ */
+/**
+ * Wire shape of a single invocation — the JSON body sent from the client
+ * transport's HTTP POST to the agent endpoint.
+ */
+export interface InvocationData {
+    /**
+     * Identifier for the specific input event on the channel that triggered
+     * this invocation. The agent locates the event via the `event-id`
+     * header. Its wire headers carry the run-id for a continuation (absent for
+     * a fresh run), so run identity is resolved from the channel, not the body.
+     */
+    inputEventId: string;
+    /** Logical name of the session (chat) — used as the Ably channel name. */
+    sessionName: string;
+}
+/**
+ * Runtime view of an {@link InvocationData}. Constructed via
+ * {@link Invocation.fromJSON}. Read-only; carries no behaviour beyond
+ * exposing its fields.
+ */
+export declare class Invocation {
+    /**
+     * Identifier for the specific input event on the channel that triggered
+     * this invocation. Run identity is resolved from that event's wire headers
+     * (or minted), not from the body.
+     */
+    readonly inputEventId: string;
+    /** Logical name of the session (chat). Used as the Ably channel name. */
+    readonly sessionName: string;
+    private constructor();
+    /**
+     * Build an Invocation from its JSON wire shape.
+     * @param data - Parsed JSON body matching {@link InvocationData}.
+     * @returns A new Invocation exposing the same fields.
+     */
+    static fromJSON(data: InvocationData): Invocation;
+    /**
+     * Serialise this invocation to its JSON wire shape — the body a client
+     * POSTs to the agent's endpoint to wake a run. Round-trips through
+     * {@link Invocation.fromJSON}.
+     * @returns The {@link InvocationData} carrying this invocation's identity.
+     */
+    toJSON(): InvocationData;
+}

package/dist/core/transport/load-history-pages.d.ts

@@ -0,0 +1,71 @@
+import { Logger } from '../../logger.js';
+/**
+ * loadHistoryPages — shared low-level history pagination primitive.
+ *
+ * Consumed by both client (via `load-history.ts`, which layers a complete-
+ * domain-message counter on top) and agent (directly, for input-event lookup
+ * and conversation hydration). Returns raw Ably messages; does NOT decode.
+ *
+ * Behaviour:
+ *  - Attaches the channel (idempotent) then pages via `channel.history()`,
+ *    using `untilAttach: true` for gapless continuity with any live subscription.
+ *  - Exposes the underlying pagination as a cursor with `hasNext()` (cheap,
+ *    no network) and `next()` (one Ably page per call, newest-first within
+ *    the page).
+ *  - Per-page failures are retried with bounded exponential backoff; on
+ *    exhaustion throws `Ably.ErrorInfo` with code `HistoryFetchFailed`.
+ *  - `signal.aborted` is checked between pages; rejects with
+ *    `Ably.ErrorInfo` (InvalidArgument) when aborted.
+ *
+ * Spec: AIT-CT11 / AIT-ST hydration.
+ */
+import * as Ably from 'ably';
+/** Options for {@link loadHistoryPages}. */
+export interface LoadHistoryPagesOptions {
+    /** Wire-message limit per Ably page. */
+    pageLimit: number;
+    /** Set `untilAttach: true` on the underlying history query for gapless continuity with live subscriptions. Default: true. */
+    untilAttach?: boolean;
+    /** AbortSignal checked between pages. Rejects with InvalidArgument when aborted. */
+    signal?: AbortSignal;
+    /** Max retries per `page.next()` / initial `history()` failure. Default: 3. */
+    maxRetries?: number;
+    /** Initial retry backoff in ms (doubled per attempt). Default: 100. */
+    retryBackoffMs?: number;
+    /** Logger for diagnostic output. */
+    logger?: Logger;
+}
+/**
+ * Cursor over the channel's history pages.
+ *
+ * `hasNext()` is cheap (cursor-only, no network); `next()` issues one Ably
+ * page fetch (with retry/backoff) and returns its messages. Once `next()`
+ * returns `undefined` the cursor is exhausted.
+ */
+export interface HistoryPagesCursor {
+    /** True when another Ably page is available (cheap to check; no network). */
+    hasNext(): boolean;
+    /**
+     * Fetch the next Ably page's messages (newest-first within the page).
+     * Returns `undefined` when no more pages are available or the abort
+     * signal has fired.
+     */
+    next(): Promise<readonly Ably.InboundMessage[] | undefined>;
+}
+/**
+ * Page through channel history, returning a cursor over Ably pages.
+ *
+ * Newest-first within each yielded page (matching Ably's native ordering).
+ * Caller drives the cursor — calling `next()` until it returns `undefined`
+ * or stopping early when a domain-specific stop condition is met
+ * (e.g. complete-message counter satisfied, target codec-message-id found,
+ * parent chain walk reaches root).
+ *
+ * The initial Ably history call is awaited eagerly so the returned cursor
+ * already knows whether there are pages available (via `hasNext()`).
+ * @param channel - The Ably channel to read history from.
+ * @param options - Pagination options.
+ * @returns A cursor with `hasNext()` (cheap, cursor-only) and `next()` (fetches one page with retry).
+ * @throws {Ably.ErrorInfo} `HistoryFetchFailed` on exhausted retry of the initial fetch, or `InvalidArgument` on signal abort.
+ */
+export declare const loadHistoryPages: (channel: Ably.RealtimeChannel, options: LoadHistoryPagesOptions) => Promise<HistoryPagesCursor>;

package/dist/core/transport/load-history.d.ts

@@ -0,0 +1,44 @@
+import { Logger } from '../../logger.js';
+import { HistoryPage, LoadHistoryOptions } from './types.js';
+/**
+ * loadHistory — load conversation history from an Ably channel and return
+ * the raw Ably messages as a paginated HistoryPage result.
+ *
+ * This does NOT decode: it pages back through Ably history via the shared
+ * {@link loadHistoryPages} primitive until `limit` complete messages are
+ * present, then hands the raw Ably messages (oldest-first) to the caller.
+ * The View re-decodes them into the Tree itself, so load-history only needs
+ * a cheap, header-based completion counter to decide when to stop paging.
+ *
+ * The `limit` option controls the number of complete **messages** per page,
+ * not the number of Ably messages fetched. A message is complete when
+ * its terminal wire signal — `status: "complete"` / `"cancelled"`, or a
+ * `discrete` create — has been seen. Runs that span a page boundary are
+ * handled by the counter requiring both a start and a terminal signal
+ * before counting a message complete.
+ *
+ * Because Ably history returns newest-first, each page's `rawMessages` are
+ * reversed to chronological (oldest-first) so the caller can fold them in
+ * order.
+ *
+ * Spec: AIT-CT11, AIT-CT11b.
+ */
+import type * as Ably from 'ably';
+/**
+ * Load conversation history from a channel and return the raw Ably messages.
+ *
+ * Drives the shared {@link loadHistoryPages} primitive with
+ * `untilAttach: true` (gapless continuity with the live subscription) and a
+ * Ably message page limit that overprovisions for the many-Ably-messages-per-domain-message
+ * ratio. Each `HistoryPage` returned covers up to `limit` complete domain
+ * messages; subsequent pages drain over-collected messages from the buffer
+ * before pulling more from the iterator.
+ *
+ * The `limit` option controls the number of complete messages returned per
+ * page, not the number of Ably messages fetched.
+ * @param channel - The Ably channel to load history from.
+ * @param options - Pagination options.
+ * @param logger - Logger for diagnostic output.
+ * @returns The first page of raw history messages.
+ */
+export declare const loadHistory: (channel: Ably.RealtimeChannel, options: LoadHistoryOptions | undefined, logger: Logger) => Promise<HistoryPage>;

package/dist/core/transport/pipe-stream.d.ts

@@ -1,17 +1,17 @@
 import { Logger } from '../../logger.js';
-import { StreamEncoder, WriteOptions } from '../codec/types.js';
+import { CodecInputEvent, CodecOutputEvent, Encoder, WriteOptions } from '../codec/types.js';
 import { StreamResult } from './types.js';
 /**
- * Pipe an event stream through an encoder to the channel.
+ * Pipe an output stream through an encoder to the channel.
  *
  * Returns when the stream completes, is cancelled (via signal), or errors.
  * The `reason` field of the result indicates which case occurred.
- * @param stream - The event stream to read from.
- * @param encoder - The streaming encoder to write events through.
- * @param signal - Abort signal to monitor for cancellation.
- * @param onAbort - Optional callback invoked when the stream is cancelled, before the stream ends.
- * @param resolveWriteOptions - Optional per-event hook returning {@link WriteOptions} overrides to pass to `encoder.appendEvent`.
+ * @param stream - The output stream to read from.
+ * @param encoder - The encoder to publish outputs through.
+ * @param signal - AbortSignal to monitor for cancellation.
+ * @param onCancelled - Optional callback invoked when the stream is cancelled, before the stream ends.
+ * @param resolveWriteOptions - Optional per-output hook returning {@link WriteOptions} overrides to pass to `encoder.publishOutput`.
  * @param logger - Optional logger for diagnostic output.
- * @returns The reason the pipe ended.
+ * @returns A {@link StreamResult}: `reason` is why the pipe ended, and `error` holds the caught error when `reason` is `'error'`.
  */
-export declare const pipeStream: <TEvent, TMessage>(stream: ReadableStream<TEvent>, encoder: StreamEncoder<TEvent, TMessage>, signal: AbortSignal | undefined, onAbort?: (write: (event: TEvent) => Promise<void>) => void | Promise<void>, resolveWriteOptions?: (event: TEvent) => WriteOptions | undefined, logger?: Logger) => Promise<StreamResult>;
+export declare const pipeStream: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent>(stream: ReadableStream<TOutput>, encoder: Encoder<TInput, TOutput>, signal: AbortSignal | undefined, onCancelled?: (write: (output: TOutput) => Promise<void>) => void | Promise<void>, resolveWriteOptions?: (output: TOutput) => WriteOptions | undefined, logger?: Logger) => Promise<StreamResult>;

package/dist/core/transport/run-manager.d.ts

@@ -0,0 +1,76 @@
+import { Logger } from '../../logger.js';
+import { RunEndReason } from './types.js';
+/**
+ * Server-side run state management and lifecycle event publishing.
+ *
+ * Owns the authoritative run lifecycle. Tracks active runs with their
+ * AbortControllers and clientIds. Publishes run-start, run-resume, run-suspend, and
+ * run-end events on the Ably channel so all clients can react to run
+ * state changes.
+ */
+import type * as Ably from 'ably';
+/**
+ * Per-invocation metadata carried on a run's opening lifecycle event. A
+ * continuation (re-entering an existing run) sets `continuation` and omits the
+ * structural `parent` / `forkOf` / `regenerates` fields.
+ */
+interface StartRunMetadata {
+    /** Structural parent codec-message-id (fresh run-start only). */
+    parent?: string;
+    /** Forked user-prompt codec-message-id for an edit (fresh run-start only). */
+    forkOf?: string;
+    /** Regenerated assistant codec-message-id (fresh run-start only). */
+    regenerates?: string;
+    /** Agent-minted invocation id, carried on the lifecycle event. */
+    invocationId?: string;
+    /** ClientId of the triggering input event. */
+    inputClientId?: string;
+    /** Codec-message-id of the triggering input event. */
+    inputCodecMessageId?: string;
+    /** When true, publish `ai-run-resume` (re-entry) instead of `ai-run-start`. */
+    continuation?: boolean;
+}
+/** Manages active runs and publishes run lifecycle events on the channel. */
+export interface RunManager {
+    /**
+     * Register a run and publish its opening lifecycle event. Publishes
+     * `ai-run-start` for a fresh run, or `ai-run-resume` when `metadata.continuation`
+     * is set (a subsequent invocation re-entering an existing run). A resume omits
+     * the structural `parent` / `forkOf` / `regenerates` headers — the original
+     * run-start owns the run's structure.
+     */
+    startRun(runId: string, clientId?: string, controller?: AbortController, metadata?: StartRunMetadata): Promise<void>;
+    /**
+     * Suspend a run. Publishes run-suspend on the channel and drops the run's
+     * active-run entry — the agent process terminates on suspend, so there is no
+     * live AbortController to retain. A cancel arriving during suspension is a
+     * no-op; the resuming invocation re-registers the run via {@link startRun}.
+     * Carries the same per-invocation attribution as {@link endRun}
+     * (`inputClientId`, `inputCodecMessageId`), since a suspend is the terminal
+     * event of the suspending invocation just as run-end is of an ending one.
+     */
+    suspendRun(runId: string, invocationId?: string, inputClientId?: string, inputCodecMessageId?: string): Promise<void>;
+    /**
+     * End a run. Publishes run-end on the channel (stamping `reason` as the
+     * run-reason header) and drops the run's active-run entry. Carries the same
+     * per-invocation attribution as {@link suspendRun} (`invocationId`,
+     * `inputClientId`, `inputCodecMessageId`), since run-end is the terminal event
+     * of the ending invocation. When `reason` is `'error'` and an `error` is
+     * supplied, its `code` and `message` are additionally stamped as the
+     * `error-code` / `error-message` headers — a codec-agnostic baseline failure
+     * detail for consumers; omitting `error` publishes a bare `reason: 'error'`.
+     */
+    endRun(runId: string, reason: RunEndReason, invocationId?: string, inputClientId?: string, inputCodecMessageId?: string, error?: Ably.ErrorInfo): Promise<void>;
+    /** Get the clientId that owns a run. */
+    getClientId(runId: string): string | undefined;
+    /** Cancel all active runs and clear state. */
+    close(): void;
+}
+/**
+ * Create a run manager bound to the given channel.
+ * @param channel - The Ably channel to publish lifecycle events on.
+ * @param logger - Optional logger for diagnostic output.
+ * @returns A new {@link RunManager} instance.
+ */
+export declare const createRunManager: (channel: Ably.RealtimeChannel, logger?: Logger) => RunManager;
+export {};

package/dist/core/transport/session-support.d.ts

@@ -0,0 +1,55 @@
+import { Logger } from '../../logger.js';
+/**
+ * Shared lifecycle plumbing for the client and agent sessions.
+ *
+ * Both `DefaultClientSession` and `DefaultAgentSession` gate their writes on
+ * `connect()` having run, detach their channel best-effort on close, and react
+ * to channel continuity loss with the same detection rule and error shape.
+ * These helpers own that common machinery so the two sessions cannot drift on
+ * the connection guard, the detach-swallow behaviour, or — most importantly —
+ * the continuity-loss predicate, which encodes channel protocol semantics
+ * (Spec AIT-CT19 / AIT-ST12). Each session keeps its own divergent reaction to
+ * continuity loss (the client emits; the agent aborts runs and swaps its Tree).
+ */
+import * as Ably from 'ably';
+/**
+ * Resolve a session's connect guard: return the in-flight/settled connect
+ * promise, or reject with `InvalidArgument` when `connect()` has not been
+ * called. Callers `await` the result before any write.
+ * @param connectPromise - The session's connect promise, or `undefined` when not yet connected.
+ * @param method - The method name being guarded, for the error message.
+ * @returns The connect promise.
+ * @throws {Ably.ErrorInfo} `InvalidArgument` when `connectPromise` is `undefined`.
+ */
+export declare const requireConnected: (connectPromise: Promise<void> | undefined, method: string) => Promise<void>;
+/**
+ * Detach the session's channel on close, best-effort. `connect()` subscribes
+ * (which implicitly attaches), so a detach is only attempted when `connect()`
+ * ran. A detach failure (e.g. the channel is already FAILED) must not throw out
+ * of `close()`, so it is swallowed and logged at debug.
+ * @param channel - The session's channel.
+ * @param connectPromise - The session's connect promise; detach is skipped when `undefined`.
+ * @param logger - Logger for the swallowed-failure debug line, or `undefined`.
+ * @param component - The owning class name, used as the log message prefix.
+ */
+export declare const bestEffortDetach: (channel: Ably.RealtimeChannel, connectPromise: Promise<void> | undefined, logger: Logger | undefined, component: string) => Promise<void>;
+/**
+ * Whether a channel state change breaks message continuity:
+ * - FAILED, SUSPENDED, DETACHED — no more messages expected (or a gap)
+ * - ATTACHED with `resumed: false` (an UPDATE) — messages were lost
+ *
+ * The initial attach (ATTACHED with no prior attach) is the caller's concern
+ * and is not handled here.
+ * @param stateChange - The channel state change to classify.
+ * @returns True when continuity was lost.
+ */
+export declare const isContinuityLost: (stateChange: Ably.ChannelStateChange) => boolean;
+/**
+ * Build the `ChannelContinuityLost` error for a continuity-breaking state
+ * change, attaching the state change's `reason` as `cause`.
+ * @param stateChange - The continuity-breaking state change.
+ * @param verb - The operation that can no longer proceed, for the
+ *   `unable to <verb>; ...` message (e.g. "deliver events", "continue").
+ * @returns The continuity-loss error.
+ */
+export declare const continuityLostError: (stateChange: Ably.ChannelStateChange, verb: string) => Ably.ErrorInfo;