@ably/ai-transport 0.0.1 → 0.2.0

package/src/vercel/transport/index.ts

@@ -5,52 +5,64 @@
  * explicitly when using the Vercel AI SDK integration.
  *
  * ```ts
- * import { createClientTransport } from '@ably/ai-transport/vercel';
+ * import { createClientSession } from '@ably/ai-transport/vercel';
  *
- * const transport = createClientTransport({ channel });
+ * const session = createClientSession({ client, channelName: 'ai:demo' });
+ * await session.connect();
  * ```
  */
 
 // Chat transport adapter
 export type { ChatTransport, ChatTransportOptions, SendMessagesRequestContext } from './chat-transport.js';
-export { createChatTransport } from './chat-transport.js';
+export { createChatTransport, DEFAULT_VERCEL_API } from './chat-transport.js';
 
 import type * as AI from 'ai';
 
-import { createClientTransport as createCoreClientTransport } from '../../core/transport/client-transport.js';
-import { createServerTransport as createCoreServerTransport } from '../../core/transport/server-transport.js';
+import { createAgentSession as createCoreAgentSession } from '../../core/transport/agent-session.js';
+import { createClientSession as createCoreClientSession } from '../../core/transport/client-session.js';
 import type {
-  ClientTransport,
-  ClientTransportOptions,
-  ServerTransport,
-  ServerTransportOptions,
+  AgentSession,
+  AgentSessionOptions,
+  ClientSession,
+  ClientSessionOptions,
 } from '../../core/transport/types.js';
-import { UIMessageCodec } from '../codec/index.js';
+import { UIMessageCodec, type VercelInput, type VercelOutput, type VercelProjection } from '../codec/index.js';
 
-/** Options for creating a Vercel client transport. Same as core options but without the codec field. */
-export type VercelClientTransportOptions = Omit<ClientTransportOptions<AI.UIMessageChunk, AI.UIMessage>, 'codec'>;
+/** Core client session options with Vercel AI SDK types pre-applied. */
+type CoreClientOpts = ClientSessionOptions<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>;
 
-/** Options for creating a Vercel server transport. Same as core options but without the codec field. */
-export type VercelServerTransportOptions = Omit<ServerTransportOptions<AI.UIMessageChunk, AI.UIMessage>, 'codec'>;
+/** Options for creating a Vercel client session. Same as core options but without the codec field. */
+export type VercelClientSessionOptions = Omit<CoreClientOpts, 'codec'>;
+
+/** Options for creating a Vercel agent session. Same as core options but without the codec field. */
+export type VercelAgentSessionOptions = Omit<
+  AgentSessionOptions<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>,
+  'codec'
+>;
 
 /**
- * Create a client-side transport pre-configured with the Vercel AI SDK codec.
+ * Create a client-side session pre-configured with the Vercel AI SDK codec.
  *
- * Equivalent to calling the core `createClientTransport` with `codec: UIMessageCodec`.
- * @param options - Configuration for the client transport (codec is provided automatically).
- * @returns A new {@link ClientTransport} for Vercel AI SDK UIMessage/UIMessageChunk types.
+ * Equivalent to calling the core `createClientSession` with `codec: UIMessageCodec`.
+ * The core session is a pure Ably-channel transport — it never sends HTTP.
+ * To wake a serverless agent over HTTP, POST `run.toInvocation().toJSON()`
+ * yourself, or use `createChatTransport` (which does it for useChat parity).
+ * @param options - Configuration for the client session (codec is provided automatically).
+ * @returns A new {@link ClientSession} for Vercel AI SDK UIMessage/UIMessageChunk types.
  */
-export const createClientTransport = (
-  options: VercelClientTransportOptions,
-): ClientTransport<AI.UIMessageChunk, AI.UIMessage> => createCoreClientTransport({ ...options, codec: UIMessageCodec });
+export const createClientSession = (
+  options: VercelClientSessionOptions,
+): ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage> =>
+  createCoreClientSession({ ...options, codec: UIMessageCodec });
 
 /**
- * Create a server-side transport pre-configured with the Vercel AI SDK codec.
+ * Create an agent (server-side) session pre-configured with the Vercel AI SDK codec.
  *
- * Equivalent to calling the core `createServerTransport` with `codec: UIMessageCodec`.
- * @param options - Configuration for the server transport (codec is provided automatically).
- * @returns A new {@link ServerTransport} for Vercel AI SDK UIMessage/UIMessageChunk types.
+ * Equivalent to calling the core `createAgentSession` with `codec: UIMessageCodec`.
+ * @param options - Configuration for the agent session (codec is provided automatically).
+ * @returns A new {@link AgentSession} for Vercel AI SDK UIMessage/UIMessageChunk types.
  */
-export const createServerTransport = (
-  options: VercelServerTransportOptions,
-): ServerTransport<AI.UIMessageChunk, AI.UIMessage> => createCoreServerTransport({ ...options, codec: UIMessageCodec });
+export const createAgentSession = (
+  options: VercelAgentSessionOptions,
+): AgentSession<VercelOutput, VercelProjection, AI.UIMessage> =>
+  createCoreAgentSession({ ...options, codec: UIMessageCodec });

package/src/vercel/transport/run-output-stream.ts

@@ -0,0 +1,170 @@
+/**
+ * Vercel-owned per-run output stream.
+ *
+ * Builds the `ReadableStream<UIMessageChunk>` that `useChat` consumes by
+ * subscribing to the session Tree's `output` and `run` events for a single
+ * run. Streaming is a useChat-integration concern, so it lives in the Vercel
+ * layer rather than the generic core: the core Tree is the fan-out point, and
+ * this projects its events into the shape `useChat` expects.
+ *
+ * Close semantics — the stream the consumer reads ends when:
+ * - a **terminal chunk** (`finish` / `error` / `abort`) is folded for the run.
+ *   This is the signal `useChat`'s `sendAutomaticallyWhen` waits for, and it
+ *   fires even when the run merely *suspends* for a tool call (a tool-calls
+ *   `finish` ends the consumer stream while the core run stays alive in the
+ *   Tree for the continuation); or
+ * - the run reaches `run-end`, which is always terminal (safety net for a run
+ *   that ends without emitting a terminal chunk). A `run-suspend` keeps the
+ *   core run alive and does not close the consumer stream.
+ *
+ * It errors when the session emits a non-fatal `error` (e.g. channel
+ * continuity loss, or an agent-reported mid-run error), so the consumer's
+ * reader rejects rather than hanging.
+ */
+
+import * as Ably from 'ably';
+import type * as AI from 'ai';
+
+import type { ClientSession } from '../../core/transport/types.js';
+import { ErrorCode } from '../../errors.js';
+import type { VercelInput, VercelOutput, VercelProjection } from '../codec/index.js';
+
+type VercelSession = ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>;
+
+/**
+ * Whether a Vercel output chunk ends the consumer-facing stream. The terminal
+ * variants are `finish` (end of an LLM turn, including tool-calls), `error`,
+ * and `abort`.
+ * @param output - The decoded output chunk.
+ * @returns True when the chunk should close the consumer stream.
+ */
+const isTerminalChunk = (output: VercelOutput): boolean =>
+  output.type === 'finish' || output.type === 'error' || output.type === 'abort';
+
+/** A consumer-facing run output stream plus the handles to settle it externally. */
+export interface RunOutputStream {
+  /** The stream of decoded outputs for the run, as `useChat` consumes it. */
+  stream: ReadableStream<VercelOutput>;
+  /** Close the stream now (e.g. on local cancel). Idempotent. */
+  close: () => void;
+  /** Error the stream now (e.g. on a failed agent-invocation POST). Idempotent. */
+  error: (reason: Ably.ErrorInfo) => void;
+}
+
+/**
+ * Create a consumer-facing output stream for a send, sourced from the session
+ * Tree's events. See the module docs for close/error semantics. The returned
+ * `close`/`error` let the caller settle the stream for conditions the Tree
+ * doesn't surface (local cancel, POST failure).
+ *
+ * Outputs route PURELY by the triggering input's codec-message-id — the key the
+ * client owns from send time, before the agent mints the runId. The agent's
+ * minted runId is supplied as a promise so the run-end safety-net can still
+ * close the stream once it resolves.
+ * @param session - The Vercel client session whose Tree to observe.
+ * @param runId - The agent-minted runId, resolved when run-start is observed.
+ *   Used only by the run-end safety-net; routing keys on `inputCodecMessageId`.
+ * @param inputCodecMessageId - The triggering input's codec-message-id. An
+ *   output routes to this stream when it carries this id.
+ * @returns The stream and its external settle handles.
+ */
+export const createRunOutputStream = (
+  session: VercelSession,
+  runId: Promise<string>,
+  inputCodecMessageId: string,
+): RunOutputStream => {
+  const holder: { controller?: ReadableStreamDefaultController<VercelOutput> } = {};
+  // ReadableStream's start() runs synchronously, so the controller is captured
+  // before the constructor returns.
+  const unsubscribe: (() => void)[] = [];
+  const stream = new ReadableStream<VercelOutput>({
+    start: (controller) => {
+      holder.controller = controller;
+    },
+    cancel: () => {
+      teardown();
+    },
+  });
+  const { controller } = holder;
+  if (!controller) {
+    throw new Ably.ErrorInfo(
+      'unable to create run stream; ReadableStream start() was not called synchronously',
+      ErrorCode.SessionSubscriptionError,
+      500,
+    );
+  }
+
+  // The agent mints the runId; learn it (for the run-end safety-net) when the
+  // promise resolves. Fire-and-forget: the stream opens on the input key, so a
+  // never-resolving runId only forgoes the safety-net, not normal close.
+  let resolvedRunId: string | undefined;
+  // Best-effort: failure only disables the run-end safety-net; normal close is
+  // the terminal chunk. `void` discards the promise (no await needed here).
+  void runId.then(
+    (id) => {
+      resolvedRunId = id;
+    },
+    () => {
+      /* session closed before run-start; safety-net stays disarmed */
+    },
+  );
+
+  let settled = false;
+  const teardown = (): void => {
+    for (const unsub of unsubscribe) unsub();
+    unsubscribe.length = 0;
+  };
+  // Settle the stream at most once: run the controller action (close/error),
+  // swallow the throw if the consumer already cancelled, then tear down.
+  const settle = (action: () => void): void => {
+    if (settled) return;
+    settled = true;
+    try {
+      action();
+    } catch {
+      /* consumer already cancelled the stream */
+    }
+    teardown();
+  };
+  const close = (): void => {
+    settle(() => {
+      controller.close();
+    });
+  };
+  const error = (reason: Ably.ErrorInfo): void => {
+    settle(() => {
+      controller.error(reason);
+    });
+  };
+
+  unsubscribe.push(
+    session.tree.on('output', (event) => {
+      if (event.inputCodecMessageId !== inputCodecMessageId) return;
+      for (const output of event.events) {
+        try {
+          controller.enqueue(output);
+        } catch {
+          close();
+          return;
+        }
+        if (isTerminalChunk(output)) {
+          close();
+          return;
+        }
+      }
+    }),
+    session.tree.on('run', (event) => {
+      // run-end is always terminal; a run-suspend (event.type === 'suspend')
+      // keeps the core run alive and must not close the consumer stream. Match
+      // against the resolved runId once the agent has minted it.
+      if (event.type === 'end' && resolvedRunId !== undefined && event.runId === resolvedRunId) {
+        close();
+      }
+    }),
+    session.on('error', (reason) => {
+      error(reason);
+    }),
+  );
+
+  return { stream, close, error };
+};

package/src/version.ts

@@ -0,0 +1,2 @@
+/** SDK version. Kept in sync with `package.json` by the `/release` workflow. */
+export const VERSION = '0.2.0';

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

@@ -1,10 +0,0 @@
-import { ClientTransport, ClientTransportOptions } from './types.js';
-/**
- * Create a client-side transport that manages conversation state over an Ably channel.
- *
- * Subscribes to the channel immediately (before attach per RTL7g). The caller should
- * ensure the channel is attached or will be attached shortly after creation.
- * @param options - Configuration for the client transport.
- * @returns A new {@link ClientTransport} instance.
- */
-export declare const createClientTransport: <TEvent, TMessage>(options: ClientTransportOptions<TEvent, TMessage>) => ClientTransport<TEvent, TMessage>;

package/dist/core/transport/conversation-tree.d.ts

@@ -1,9 +0,0 @@
-import { Logger } from '../../logger.js';
-import { ConversationTree } from './types.js';
-/**
- * Create a ConversationTree that materializes branching history from a flat oplog.
- * @param getKey - Codec function that returns a stable key for a domain message.
- * @param logger - Logger for diagnostic output.
- * @returns A new {@link ConversationTree} instance.
- */
-export declare const createConversationTree: <TMessage>(getKey: (message: TMessage) => string, logger: Logger) => ConversationTree<TMessage>;

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

@@ -1,41 +0,0 @@
-import { Logger } from '../../logger.js';
-import { Codec } from '../codec/types.js';
-import { LoadHistoryOptions, PaginatedMessages } from './types.js';
-/**
- * decodeHistory — load conversation history from an Ably channel and
- * return decoded messages as a PaginatedMessages result.
- *
- * Uses a fresh decoder (not shared with the live subscription) to avoid
- * state conflicts. Per-turn accumulators handle interleaved turns correctly.
- *
- * The `limit` option controls the number of **messages** returned,
- * not the number of Ably wire messages fetched. The implementation pages
- * back through Ably history until `limit` complete messages have
- * been assembled. Partial turns (incomplete at the page boundary) are
- * buffered internally and completed when `next()` fetches more pages.
- *
- * Only completed messages appear in `items`. A message is complete when
- * its terminal event (finish/abort/error) has been received.
- *
- * Because Ably history returns newest-first while the decoder requires
- * chronological order, all collected Ably messages are re-decoded from
- * oldest to newest after each page fetch. This handles turns that span
- * page boundaries correctly.
- */
-import type * as Ably from 'ably';
-/**
- * Load conversation history from a channel and return decoded messages.
- *
- * Attaches the channel if not already attached, then calls
- * `channel.history({ untilAttach: true })` to guarantee no gap between
- * historical and live messages. The attach is idempotent.
- *
- * The `limit` option controls the number of complete messages
- * returned per page, not the number of Ably wire messages fetched.
- * @param channel - The Ably channel to load history from.
- * @param codec - The codec for decoding wire messages into domain messages.
- * @param options - Pagination options.
- * @param logger - Logger for diagnostic output.
- * @returns The first page of decoded history messages.
- */
-export declare const decodeHistory: <TEvent, TMessage>(channel: Ably.RealtimeChannel, codec: Codec<TEvent, TMessage>, options: LoadHistoryOptions | undefined, logger: Logger) => Promise<PaginatedMessages<TMessage>>;

package/dist/core/transport/server-transport.d.ts

@@ -1,7 +0,0 @@
-import { ServerTransport, ServerTransportOptions } from './types.js';
-/**
- * Create a server transport bound to the given channel and codec.
- * @param options - Transport configuration.
- * @returns A new {@link ServerTransport} instance.
- */
-export declare const createServerTransport: <TEvent, TMessage>(options: ServerTransportOptions<TEvent, TMessage>) => ServerTransport<TEvent, TMessage>;

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

@@ -1,19 +0,0 @@
-import { Logger } from '../../logger.js';
-/** Routes decoded events to the correct turn's ReadableStream. */
-export interface StreamRouter<TEvent> {
-    /** Register a new stream for a turnId. Returns the ReadableStream the consumer reads from. */
-    createStream(turnId: string): ReadableStream<TEvent>;
-    /** Close the stream for a turnId. Returns true if a stream was closed. */
-    closeStream(turnId: string): boolean;
-    /** Enqueue an event to the correct stream. Returns true if routed successfully. */
-    route(turnId: string, event: TEvent): boolean;
-    /** Whether a specific turnId has an active stream. */
-    has(turnId: string): boolean;
-}
-/**
- * Create a StreamRouter that routes decoded events to per-turn ReadableStreams.
- * @param isTerminal - Predicate that returns true for events that close the stream.
- * @param logger - Logger for diagnostic output.
- * @returns A new {@link StreamRouter} instance.
- */
-export declare const createStreamRouter: <TEvent>(isTerminal: (event: TEvent) => boolean, logger: Logger) => StreamRouter<TEvent>;

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

@@ -1,34 +0,0 @@
-import { Logger } from '../../logger.js';
-import { TurnEndReason } from './types.js';
-/**
- * Server-side turn state management and lifecycle event publishing.
- *
- * Owns the authoritative turn lifecycle. Tracks active turns with their
- * AbortControllers and clientIds. Publishes turn-start and turn-end events
- * on the Ably channel so all clients can react to turn state changes.
- */
-import type * as Ably from 'ably';
-/** Manages active turns and publishes turn lifecycle events on the channel. */
-export interface TurnManager {
-    /** Register a new turn. Publishes turn-start on the channel. Returns AbortSignal. */
-    startTurn(turnId: string, clientId?: string, controller?: AbortController): Promise<AbortSignal>;
-    /** End a turn. Publishes turn-end on the channel. Cleans up internal state. */
-    endTurn(turnId: string, reason: TurnEndReason): Promise<void>;
-    /** Get the AbortSignal for a turn. */
-    getSignal(turnId: string): AbortSignal | undefined;
-    /** Get the clientId that owns a turn. */
-    getClientId(turnId: string): string | undefined;
-    /** Abort the signal for a turn. */
-    abort(turnId: string): void;
-    /** Get all active turn IDs. */
-    getActiveTurnIds(): string[];
-    /** Abort all active turns and clear state. */
-    close(): void;
-}
-/**
- * Create a turn 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 TurnManager} instance.
- */
-export declare const createTurnManager: (channel: Ably.RealtimeChannel, logger?: Logger) => TurnManager;

package/dist/react/use-active-turns.d.ts

@@ -1,8 +0,0 @@
-import { ClientTransport } from '../core/transport/types.js';
-/**
- * Returns a reactive Map of all active turns on the channel, keyed by clientId.
- * Updates when turns start or end.
- * @param transport - The client transport to observe, or null/undefined if not yet available.
- * @returns A Map where keys are clientIds and values are Sets of active turnIds.
- */
-export declare const useActiveTurns: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage> | null | undefined) => Map<string, Set<string>>;

package/dist/react/use-client-transport.d.ts

@@ -1,7 +0,0 @@
-import { ClientTransport, ClientTransportOptions } from '../core/transport/types.js';
-/**
- * Create and memoize a {@link ClientTransport} across renders.
- * @param options - Configuration for the client transport.
- * @returns The memoized transport instance.
- */
-export declare const useClientTransport: <TEvent, TMessage>(options: ClientTransportOptions<TEvent, TMessage>) => ClientTransport<TEvent, TMessage>;

package/dist/react/use-conversation-tree.d.ts

@@ -1,20 +0,0 @@
-import { ClientTransport } from '../core/transport/types.js';
-/** Handle for navigating the branching conversation tree. */
-export interface ConversationTreeHandle<TMessage> {
-    /** Linear message list for the currently selected branch. */
-    messages: TMessage[];
-    /** Get all sibling messages at a fork point. */
-    getSiblings: (msgId: string) => TMessage[];
-    /** Whether a message has siblings (should show navigation arrows). */
-    hasSiblings: (msgId: string) => boolean;
-    /** Index of the currently selected sibling. */
-    getSelectedIndex: (msgId: string) => number;
-    /** Navigate to a sibling. Triggers re-render with updated messages. */
-    selectSibling: (msgId: string, index: number) => void;
-}
-/**
- * Subscribe to transport message updates and provide branch navigation primitives.
- * @param transport - The client transport whose conversation tree to navigate.
- * @returns A {@link ConversationTreeHandle} with the current messages and navigation methods.
- */
-export declare const useConversationTree: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>) => ConversationTreeHandle<TMessage>;

package/dist/react/use-edit.d.ts

@@ -1,7 +0,0 @@
-import { ActiveTurn, ClientTransport, SendOptions } from '../core/transport/types.js';
-/**
- * Return a stable `edit` callback bound to the given transport.
- * @param transport - The client transport to edit through.
- * @returns A function that edits a user message and returns an {@link ActiveTurn} handle.
- */
-export declare const useEdit: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>) => ((messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>);

package/dist/react/use-history.d.ts

@@ -1,19 +0,0 @@
-import { ClientTransport, LoadHistoryOptions } from '../core/transport/types.js';
-/** Handle for paginated history loading. */
-export interface HistoryHandle {
-    /** Are there older pages available? False until `load()` has been called. */
-    hasNext: boolean;
-    /** Is a page being fetched? */
-    loading: boolean;
-    /** Load the first page (or re-load with different options). Inserts into the conversation tree. */
-    load: (options?: LoadHistoryOptions) => Promise<void>;
-    /** Fetch the next (older) page. No-op if loading or no more pages. Inserts into the conversation tree. */
-    next: () => Promise<void>;
-}
-/**
- * Paginated history handle for a client transport.
- * @param transport - The client transport to load history from, or null/undefined if not yet available.
- * @param options - When provided, auto-loads the first page on mount. Omit or pass null for manual loading.
- * @returns A {@link HistoryHandle} for loading and paginating through history.
- */
-export declare const useHistory: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage> | null | undefined, options?: LoadHistoryOptions | null) => HistoryHandle;

package/dist/react/use-messages.d.ts

@@ -1,7 +0,0 @@
-import { ClientTransport } from '../core/transport/types.js';
-/**
- * Subscribe to transport message updates and return the current message list.
- * @param transport - The client transport to observe.
- * @returns The current list of decoded messages.
- */
-export declare const useMessages: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>) => TMessage[];

package/dist/react/use-regenerate.d.ts

@@ -1,7 +0,0 @@
-import { ActiveTurn, ClientTransport, SendOptions } from '../core/transport/types.js';
-/**
- * Return a stable `regenerate` callback bound to the given transport.
- * @param transport - The client transport to regenerate through.
- * @returns A function that regenerates an assistant message and returns an {@link ActiveTurn} handle.
- */
-export declare const useRegenerate: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>) => ((messageId: string, options?: SendOptions) => Promise<ActiveTurn<TEvent>>);

package/dist/react/use-send.d.ts

@@ -1,7 +0,0 @@
-import { ActiveTurn, ClientTransport, SendOptions } from '../core/transport/types.js';
-/**
- * Return a stable `send` callback bound to the given transport.
- * @param transport - The client transport to send through.
- * @returns A function that sends messages and returns an {@link ActiveTurn} handle.
- */
-export declare const useSend: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>) => ((messages: TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>);

package/dist/vercel/codec/accumulator.d.ts

@@ -1,21 +0,0 @@
-import { MessageAccumulator } from '../../core/codec/types.js';
-/**
- * Vercel AI SDK Message Accumulator
- *
- * Builds and maintains a UIMessage[] list from decoder outputs.
- * Implements MessageAccumulator<UIMessageChunk, UIMessage>.
- *
- * The accumulator consumes DecoderOutput[] from the decoder and groups
- * streaming events into UIMessage objects using lifecycle boundaries
- * (start/finish). Complete messages (from writeMessages) are inserted
- * directly.
- *
- * Multiple messages can be in-progress concurrently — each is identified
- * by the `messageId` field on DecoderOutput (read from x-ably-msg-id).
- */
-import type * as AI from 'ai';
-/**
- * Create a Vercel AI SDK accumulator that builds UIMessage[] from decoder outputs.
- * @returns A {@link MessageAccumulator} for UIMessageChunk/UIMessage.
- */
-export declare const createAccumulator: () => MessageAccumulator<AI.UIMessageChunk, AI.UIMessage>;