@ably/ai-transport 0.1.0 → 0.2.0

package/dist/core/transport/types/agent.d.ts

@@ -0,0 +1,353 @@
+import { Logger } from '../../../logger.js';
+import { Codec, CodecInputEvent, CodecOutputEvent, WriteOptions } from '../../codec/types.js';
+import { Invocation } from '../invocation.js';
+import { CancelRequest, RunEndReason } from './shared.js';
+import { MessageNode } from './tree.js';
+/** Agent (server-side) session types: options, run runtime, and the Run / AgentSession contracts. */
+import type * as Ably from 'ably';
+/** Options for creating an agent session. */
+export interface AgentSessionOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /**
+     * The Ably Realtime client. The caller owns its lifecycle —
+     * `session.close()` does not close the client.
+     */
+    client: Ably.Realtime;
+    /**
+     * The name of the channel to publish to. The session owns this channel —
+     * do not also resolve it elsewhere with conflicting channel options.
+     */
+    channelName: string;
+    /** The codec to use for encoding events and messages. */
+    codec: Codec<TInput, TOutput, TProjection, TMessage>;
+    /** Logger instance for diagnostic output. */
+    logger?: Logger;
+    /**
+     * Called with non-fatal session-level errors not scoped to any run.
+     * Examples: cancel listener subscription failure, channel attach errors,
+     * channel continuity loss (FAILED/SUSPENDED/DETACHED or re-attach with
+     * `resumed: false`).
+     */
+    onError?: (error: Ably.ErrorInfo) => void;
+    /**
+     * How long `Run.start()` will wait for the input event(s) tagged with
+     * the run's `invocationId` to arrive on the channel (rewind + live wait)
+     * before rejecting with `InputEventNotFound`. The rejection bubbles up to the
+     * developer's HTTP handler, which should surface it as a non-2xx response
+     * so the client's pending send fails.
+     * Default: 30000 (30 seconds).
+     */
+    inputEventLookupTimeoutMs?: number;
+    /**
+     * Maximum number of distinct invocation-ids whose input events
+     * may be buffered while waiting for `Run.start()` to register a lookup
+     * listener. Channel rewind on attach can replay input events before any
+     * run has been created for them; this buffer holds those events so
+     * that subsequent `start()` calls can drain them on registration.
+     *
+     * Each entry corresponds to one invocation-id regardless of how many
+     * events that invocation buffered. When the limit is exceeded the
+     * oldest invocation entry (and all its buffered events) is FIFO-evicted
+     * — the client whose input was dropped will fail their lookup with
+     * `InputEventNotFound`. The eviction is logged at warn level so operators
+     * can correlate capacity pressure with `InputEventNotFound` errors.
+     *
+     * Default: 200.
+     */
+    inputEventBufferLimit?: number;
+    /**
+     * The channel rewind applied when the agent attaches. Replays the whole
+     * channel subscription on attach (not just input events) so the lookup
+     * can catch input events published before the session attached. Passed
+     * through verbatim to Ably's `params.rewind` channel parameter — accepts
+     * duration strings (`"2m"`, `"30s"`) or a count of messages as a string
+     * (e.g. `"50"`). Malformed values surface as a channel attach error from
+     * Ably; the SDK does not pre-validate.
+     *
+     * A longer window improves the chances of catching an input event for an
+     * agent that takes a while to come up after the client published, but
+     * also increases the buffer pressure on `inputEventBufferLimit` because
+     * more events may be replayed on attach.
+     *
+     * Default: `"2m"`.
+     */
+    rewindWindow?: string;
+}
+/**
+ * A batch of events targeting an existing message.
+ * Each node specifies the target message and the events to apply to it.
+ * Used for cross-run updates such as tool result delivery.
+ */
+export interface EventsNode<TOutput extends CodecOutputEvent> {
+    /** Discriminator — identifies this as an events node. */
+    kind: 'event';
+    /** The `codec-message-id` of the existing message to update. */
+    codecMessageId: string;
+    /** Outputs to apply to the target message. */
+    events: TOutput[];
+}
+/**
+ * Options for `Run.pipe` — per-operation overrides for the assistant message.
+ * @template TOutput - The codec output type carried by the stream; used by the `resolveWriteOptions` hook.
+ */
+export interface PipeOptions<TOutput extends CodecOutputEvent> {
+    /** The codec-message-id of the immediately preceding message in this branch. */
+    parent?: string;
+    /** The codec-message-id of the message this response replaces (for regeneration). */
+    forkOf?: string;
+    /**
+     * Optional per-output hook invoked before each output is encoded. The
+     * returned {@link WriteOptions} (if any) override the stream's default
+     * headers and `codecMessageId` for that one encode call only; return `undefined`
+     * to use the stream defaults.
+     *
+     * Used to carry a subset of outputs within the stream to a different
+     * message (e.g. `tool-output-available` chunks that belong on a prior
+     * assistant message, stamped with `amend`). Must not be used
+     * for outputs that participate in the encoder's stream-append pipeline
+     * — streaming state (stream tracker, append ordering) is anchored to
+     * the stream's default identity and is not affected by per-output
+     * overrides.
+     * @param output - The output about to be encoded.
+     * @returns Per-write overrides for this output, or undefined.
+     */
+    resolveWriteOptions?: (output: TOutput) => WriteOptions | undefined;
+}
+/** The result of streaming a response through the encoder. */
+export interface StreamResult {
+    /** Why the stream ended. */
+    reason: RunEndReason;
+    /**
+     * The error that caused the stream to fail, present when `reason` is
+     * `'error'`. This is the original error (e.g. from the LLM provider)
+     * preserved so the caller can inspect provider-specific fields. The
+     * run's `onError` callback also fires with a wrapped `Ably.ErrorInfo`
+     * (code `StreamError`) for standardized observability.
+     */
+    error?: Error;
+}
+/** Per-run runtime hooks, signal, and overrides supplied at `createRun()` time. */
+export interface RunRuntime<TOutput extends CodecOutputEvent> {
+    /**
+     * Override the invocation id for this run. When omitted, the agent mints a
+     * fresh `crypto.randomUUID()` — the normal path (one per HTTP request).
+     * Supply a non-empty fixed value for deterministic ids in tests or
+     * in-process drivers; the empty string is not a valid override (it is the
+     * "unset" sentinel and does not fall through to minting).
+     */
+    invocationId?: string;
+    /**
+     * Override the run id for a FRESH run. When omitted, the agent mints a fresh
+     * `crypto.randomUUID()` — the normal path. A continuation IGNORES this: its
+     * run id is read from the triggering input event's wire headers, since a
+     * continuation re-enters a run that already exists. Supply a non-empty fixed
+     * value for deterministic ids in tests or in-process drivers; the empty
+     * string is not a valid override (it is the "unset" sentinel and does not
+     * fall through to minting).
+     */
+    runId?: string;
+    /**
+     * An external AbortSignal (typically the HTTP request's `req.signal`) that,
+     * when fired, cancels this run. This allows platform-level cancellation —
+     * request cancellation, serverless function timeout — to stop LLM generation
+     * and stream piping gracefully.
+     */
+    signal?: AbortSignal;
+    /**
+     * Called before each Ably message is published in this run.
+     * Mutate the Ably message in place to add custom headers under extras.ai.
+     */
+    onMessage?: (message: Ably.Message) => void;
+    /**
+     * Called when the run's stream is cancelled (by client cancel or server).
+     * Receives a write function to publish final outputs before the cancellation finalises.
+     */
+    onCancelled?: (write: (output: TOutput) => Promise<void>) => void | Promise<void>;
+    /**
+     * Called when a cancel message arrives matching this run.
+     * Return true to allow cancellation (fires `abortSignal`, stream cancels).
+     * Return false to reject (cancel ignored, stream continues).
+     * If not provided, all cancels are accepted.
+     */
+    onCancel?: (request: CancelRequest) => Promise<boolean>;
+    /**
+     * Called with non-fatal run-scoped errors that have no other delivery
+     * path. Fires in two scenarios:
+     * - Stream failures in `pipe` — the underlying error is also returned on
+     *   `StreamResult.error`, but this callback delivers it wrapped as an
+     *   `Ably.ErrorInfo` (code `StreamError`) for standardized observability.
+     * - Failures in the `onCancel` handler.
+     *
+     * Publish failures in `start`, `addEvents`, and `end`
+     * are not delivered here — those methods reject their returned promise
+     * with an `Ably.ErrorInfo`, and the caller should handle it at the await
+     * site. Run errors never render the session unusable, but the run may
+     * be in an inconsistent state; the caller should typically `end` it
+     * with reason `'error'`.
+     *
+     * Channel-wide events (e.g. continuity loss) are delivered via the
+     * session-level `onError` on {@link AgentSessionOptions}, not here.
+     */
+    onError?: (error: Ably.ErrorInfo) => void;
+}
+/**
+ * Read-only view exposed on a {@link Run} of the conversation messages
+ * this run was created with.
+ *
+ * TODO(AIT-771): when the agent rebuilds full conversation history from
+ * the channel, this should expose `RunNode[]`-shaped data to match the
+ * client side. Today it carries the flat input messages handed to the
+ * invocation.
+ */
+export interface RunView<TMessage> {
+    /** Invocation input messages handed to this run; no branch awareness today. */
+    readonly messages: MessageNode<TMessage>[];
+}
+/** Options for {@link Run.loadConversation}. */
+export interface LoadConversationOptions {
+    /**
+     * Number of wire messages to request per history page.
+     * Default: 200.
+     */
+    pageLimit?: number;
+    /**
+     * Maximum total wire messages to collect across all pages before
+     * stopping pagination. A safety bound so a long-lived channel
+     * doesn't exhaust memory.
+     * Default: 2000.
+     */
+    maxMessages?: number;
+}
+/**
+ * A server-side run with explicit lifecycle methods. Generic over the codec's
+ * output, projection, and message types.
+ */
+export interface Run<TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /** The run's unique identifier. */
+    readonly runId: string;
+    /**
+     * The invocation's unique identifier, minted by the agent when the run is
+     * created (one per HTTP request that invokes the agent). Readable
+     * synchronously — the application returns it on the HTTP response so the
+     * caller can observe it. The agent stamps it on every event it publishes
+     * for this invocation (run lifecycle + outputs).
+     */
+    readonly invocationId: string;
+    /** AbortSignal scoped to this run. Fires when a cancel event arrives for this runId. */
+    readonly abortSignal: AbortSignal;
+    /** Read-only view of the conversation messages associated with this run. */
+    readonly view: RunView<TMessage>;
+    /**
+     * The conversation messages this run should feed to the model.
+     *
+     * - Before {@link start} resolves: empty (no view contribution yet).
+     * - After {@link start}: the user-prompt messages looked up on the
+     *   channel for this invocation.
+     * - After {@link loadConversation}: the full multi-turn conversation —
+     *   all ancestor run messages followed by the current run's messages,
+     *   oldest turn first. This is the value to pass to the LLM when the
+     *   agent handles a reply in an ongoing conversation.
+     *
+     * Each access returns a fresh array — safe to mutate without affecting
+     * internal Run state.
+     */
+    readonly messages: TMessage[];
+    /**
+     * Publish the run's opening lifecycle event to the channel (run-start, or
+     * run-resume for a continuation). Must be called before any other run method
+     * (pipe, addEvents, suspend, end).
+     */
+    start(): Promise<void>;
+    /**
+     * Pipe a ReadableStream through the encoder to the channel.
+     * Returns when the stream completes, is cancelled, or errors.
+     * Does NOT call end() — the caller must call end() after pipe returns.
+     */
+    pipe(stream: ReadableStream<TOutput>, options?: PipeOptions<TOutput>): Promise<StreamResult>;
+    /**
+     * Publish events targeting existing messages in the tree. Each node
+     * specifies a target message (by `codecMessageId`) and the events to apply.
+     * Events are encoded and published with the target's `codec-message-id`,
+     * so receiving clients apply them to the existing node rather than
+     * creating a new one.
+     *
+     * Used for cross-run updates such as tool result delivery after
+     * approval or client-side tool execution.
+     */
+    addEvents(nodes: EventsNode<TOutput>[]): Promise<void>;
+    /**
+     * Fetch every channel message bound to this run and fold them through
+     * the codec into a single projection. Used by the agent to reconstruct
+     * the run's full state — including client-published tool-output amends
+     * the agent didn't observe live — when resuming a suspended run.
+     *
+     * Uses `channel.history()` (no `untilAttach`) so messages published
+     * after the channel was originally attached are still included. Each
+     * call paginates until either there are no more pages or an internal
+     * safety bound is reached.
+     * @returns The TProjection produced by folding every event for this run
+     *   in serial order. The caller extracts what they need via
+     *   {@link Codec.getMessages}.
+     */
+    loadProjection(): Promise<TProjection>;
+    /**
+     * Reconstruct the full multi-turn conversation by walking the ancestor
+     * run chain and concatenating each run's messages, oldest turn first.
+     *
+     * Performs a single `channel.history()` scan and builds projections for
+     * all ancestor runs plus the current run. After this call:
+     * - {@link Run.messages} returns the complete conversation (all ancestor
+     *   turns followed by the current run's messages), making it ready to
+     *   pass directly to the LLM.
+     * - The current run's projection is cached so {@link Run.pipe} works
+     *   correctly without a separate {@link Run.loadProjection} call.
+     * @param options - Optional tuning for history pagination.
+     * @returns The same message list now accessible via {@link Run.messages}.
+     */
+    loadConversation(options?: LoadConversationOptions): Promise<TMessage[]>;
+    /**
+     * Publish a run-suspend event to the channel and clean up, pausing the run
+     * without ending it. Call this instead of {@link Run.end} when the run is
+     * waiting on participant input (e.g. a client-side tool execution or a
+     * server-side tool approval): the run stays live and a later invocation can
+     * resume it under the same `runId`. Like {@link Run.end}, it is terminal for
+     * this Run instance — the resuming invocation builds a fresh Run. Must be
+     * called after {@link Run.start}; a no-op if the run has already ended or
+     * suspended.
+     */
+    suspend(): Promise<void>;
+    /** Publish run-end event to the channel and clean up. Terminal. */
+    end(reason: RunEndReason): Promise<void>;
+}
+/** Server-side session that manages run lifecycles over an Ably channel. */
+export interface AgentSession<TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /**
+     * Subscribe (unfiltered) to the shared channel and (implicitly) attach. The
+     * subscribe is deliberately unfiltered so channel-rewind-replayed input
+     * events also reach the dispatcher, which routes by name (cancel vs. input
+     * event). Idempotent — subsequent calls return the same promise. All run
+     * methods (`start`, `addEvents`, `pipe`, `loadProjection`,
+     * `loadConversation`, `suspend`, `end`) throw `InvalidArgument` until
+     * `connect()` has been *called*; once it has, they await the in-flight
+     * connect promise rather than throwing.
+     */
+    connect(): Promise<void>;
+    /**
+     * Create a new run from an invocation. Synchronous — no channel activity
+     * until start() is called. The run is registered for cancel routing
+     * immediately so that early cancels fire the AbortSignal.
+     * @param invocation - The {@link Invocation} carrying run identity and
+     *   conversation messages.
+     * @param runtime - Optional runtime hooks and external AbortSignal
+     *   (e.g. the HTTP request's `req.signal`).
+     */
+    createRun(invocation: Invocation, runtime?: RunRuntime<TOutput>): Run<TOutput, TProjection, TMessage>;
+    /**
+     * Unsubscribe from cancel messages, cancel all active runs, detach the
+     * channel this session attached, and clean up.
+     *
+     * Resolves once the detach completes. The detach is best-effort:
+     * a failure (e.g. the channel is already FAILED) is swallowed
+     * and does not reject. Idempotent.
+     */
+    close(): Promise<void>;
+}

package/dist/core/transport/types/client.d.ts

@@ -0,0 +1,168 @@
+import { Logger } from '../../../logger.js';
+import { Codec, CodecInputEvent, CodecOutputEvent } from '../../codec/types.js';
+import { Invocation } from '../invocation.js';
+import { Tree } from './tree.js';
+import { View } from './view.js';
+/** Client session types: options, send options, the ActiveRun handle, and the ClientSession contract. */
+import type * as Ably from 'ably';
+/** Options for creating a client session. */
+export interface ClientSessionOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /**
+     * The Ably Realtime client. The caller owns its lifecycle —
+     * `session.close()` does not close the client.
+     */
+    client: Ably.Realtime;
+    /**
+     * The name of the channel to subscribe to and publish cancel signals on.
+     * The session owns this channel — do not also resolve it elsewhere with
+     * conflicting channel options.
+     */
+    channelName: string;
+    /** The codec to use for encoding/decoding. */
+    codec: Codec<TInput, TOutput, TProjection, TMessage>;
+    /**
+     * The client's identity, used as the Ably publisher `clientId` on
+     * everything this session publishes. Surfaces on the wire as the
+     * run/input client id so other clients can attribute messages.
+     */
+    clientId?: string;
+    /** Initial messages to seed the conversation tree with. Forms a linear chain. */
+    messages?: TMessage[];
+    /** Logger instance for diagnostic output. */
+    logger?: Logger;
+}
+/** Per-send options for branching metadata and run identity. */
+export interface SendOptions {
+    /**
+     * The codec-message-id of the message this send replaces (fork).
+     * Set for regeneration (forkOf an assistant message) or
+     * edit (forkOf a user message).
+     */
+    forkOf?: string;
+    /**
+     * The codec-message-id of the message that precedes this one in the
+     * conversation thread. If omitted, auto-computed from the last
+     * message in the view.
+     */
+    parent?: string;
+    /**
+     * Reuse an existing `runId` (e.g. resume a suspended run). When set,
+     * the send is treated as a continuation: the run's existing observer
+     * state (router stream, tree run-tracking) is reused; no fresh
+     * `crypto.randomUUID()` is minted. Each continuation POST is woken by the
+     * agent, which mints a distinct `invocationId` per HTTP request.
+     */
+    runId?: string;
+    /**
+     * Currently non-functional: the send path always mints each input's
+     * `inputEventId` with `crypto.randomUUID()` (no override is read), so a
+     * value supplied here has no effect.
+     */
+    inputEventId?: string;
+}
+/**
+ * A handle to an active client-side run, returned by `send()`,
+ * `regenerate()`, and `edit()`.
+ *
+ * The core does not expose a per-run output stream — streaming is a
+ * consumer-layer concern (e.g. the Vercel ChatTransport builds a stream from
+ * the Tree's `output` events). The handle carries only run identity and
+ * control, so it is not parameterized by the codec output type.
+ */
+export interface ActiveRun {
+    /**
+     * The synchronous routing handle for this send: the triggering input's
+     * codec-message-id, which the client owns the moment it publishes and the
+     * agent echoes back as `input-codec-message-id`. Stream routing and cancel
+     * key on this — it is known immediately, unlike {@link runId}, which the
+     * agent mints.
+     */
+    inputCodecMessageId: string;
+    /**
+     * The run's unique identifier, resolved when the agent's `ai-run-start` for
+     * this send is observed on the channel. The agent mints the run-id, so it is
+     * not known synchronously: `await run.runId`
+     * to learn it (this also tells you the agent has picked up the run). There is
+     * no built-in deadline — race it against your own timeout if you need one.
+     * Rejects only if the session is closed before run-start arrives. A
+     * continuation does not resolve any sooner: its run-id promise resolves when
+     * the agent's run-resume (`event.type === 'resume'`) for this send is observed
+     * on the channel, not synchronously from the run-id the caller passed in.
+     */
+    runId: Promise<string>;
+    /**
+     * The input event's unique identifier. Stamped on the primary input event
+     * published to the channel and forwarded in the HTTP POST body so the
+     * agent can locate the exact triggering event.
+     */
+    inputEventId: string;
+    /**
+     * Cancel this specific run. Publishes a cancel signal synchronously — keyed
+     * by the triggering input's codec-message-id ({@link inputCodecMessageId}),
+     * which the client owns the moment it publishes, so a cancel issued before
+     * the agent mints the run-id is still honoured (the agent buffers it and
+     * fires it once its input-event lookup resolves the input to the run). A
+     * continuation also carries its known run-id. Resolves once the cancel is
+     * published; it does not wait for {@link runId}.
+     */
+    cancel(): Promise<void>;
+    /**
+     * The codec-message-id of every input in this send, in input order. Includes
+     * wire-only inputs (regenerate, tool resolutions), which are NOT folded into
+     * the local projection — so an entry here does not by itself mean an
+     * optimistic insert occurred.
+     */
+    optimisticCodecMessageIds: string[];
+    /**
+     * Build the {@link Invocation} pointer for this run — only `inputEventId` and
+     * the session's channel name as `sessionName`. The body carries no run-id: a
+     * fresh run's run-id is minted by the agent, and a continuation's run-id is
+     * read off the triggering input event's wire headers, so run identity always
+     * lives on the channel rather than the invocation body. The
+     * application POSTs `run.toInvocation().toJSON()` to its agent endpoint to
+     * wake the agent; the agent rebuilds it via {@link Invocation.fromJSON} and
+     * mints the `invocationId` (and a fresh `runId`) itself. The conversation
+     * itself is read from the channel, so the pointer carries only identifiers.
+     */
+    toInvocation(): Invocation;
+}
+/** Client-side session that manages conversation state over an Ably channel. */
+export interface ClientSession<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /** The complete conversation tree — all known Run nodes, events for any change. */
+    readonly tree: Tree<TOutput, TProjection>;
+    /** The default paginated, branch-aware view for rendering — events scoped to visible messages. */
+    readonly view: View<TInput, TMessage>;
+    /**
+     * Subscribe to the channel and (implicitly) attach. Idempotent —
+     * subsequent calls return the same promise. The View's write operations
+     * (`send()`, `regenerate()`, `edit()`) and this session's `cancel()` throw
+     * `InvalidArgument` until `connect()` resolves.
+     */
+    connect(): Promise<void>;
+    /**
+     * Create an additional view over the same conversation tree.
+     * Each view has independent branch selections and pagination state.
+     * The caller is responsible for calling `close()` on the returned view
+     * when it is no longer needed, or it will be closed when the session closes.
+     */
+    createView(): View<TInput, TMessage>;
+    /** Cancel the specified run by publishing an `ai-cancel` signal on the channel. The core does not own a per-run stream; closing any consumer-built stream is the responsibility of the layer that built it (e.g. the Vercel ChatTransport). */
+    cancel(runId: string): Promise<void>;
+    /**
+     * Subscribe to non-fatal session errors. These indicate something went
+     * wrong but the session is still operational. Returns an unsubscribe function.
+     * Once the session is CLOSED this is a no-op: the handler is not registered and
+     * the returned function does nothing.
+     */
+    on(event: 'error', handler: (error: Ably.ErrorInfo) => void): () => void;
+    /**
+     * Tear down the session: unsubscribe from the channel, close active views,
+     * clear all handlers, and detach the channel this session attached.
+     *
+     * Detaching stops the session from receiving further channel messages;
+     * the server keeps streaming until its runs end on their own. To stop
+     * in-progress runs, call {@link cancel} for each before `close()`. The
+     * detach is best-effort: a failure is swallowed and does not reject.
+     */
+    close(): Promise<void>;
+}

package/dist/core/transport/types/shared.d.ts

@@ -0,0 +1,24 @@
+/** Types shared across the client, agent, tree, and view layers. */
+import type * as Ably from 'ably';
+/**
+ * Why a run ended.
+ *
+ * A run-end is terminal — a run that merely pauses awaiting input publishes
+ * `ai-run-suspend` instead (see {@link Run.suspend}).
+ *
+ * - `complete` — the run finished naturally.
+ * - `cancelled` — the run was cancelled by a client.
+ * - `error` — the run errored.
+ */
+export type RunEndReason = 'complete' | 'cancelled' | 'error';
+/**
+ * Passed to a run's `onCancel` hook for authorization decisions.
+ * The hook inspects the incoming cancel message and decides whether to
+ * allow the targeted run to be cancelled.
+ */
+export interface CancelRequest {
+    /** The raw Ably message that carried the cancel signal. */
+    message: Ably.InboundMessage;
+    /** The runId being cancelled. */
+    runId: string;
+}