@ably/ai-transport 0.0.1 → 0.2.0

package/dist/vercel/react/contexts/chat-transport-context.d.ts

@@ -0,0 +1,33 @@
+import { ClientSession } from '../../../core/transport/types.js';
+import { VercelInput, VercelOutput, VercelProjection } from '../../codec/index.js';
+import { ChatTransport } from '../../transport/chat-transport.js';
+import type * as Ably from 'ably';
+import type * as AI from 'ai';
+/**
+ * A single entry in the chat transport registry, holding both the
+ * underlying {@link ClientSession} and the {@link ChatTransport} wrapping it.
+ */
+export interface ChatTransportSlot {
+    /** The underlying client session used to create the chat transport. */
+    readonly session: ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>;
+    /** Construction error from the underlying {@link ClientSession}, or `undefined` on success. */
+    readonly sessionError?: Ably.ErrorInfo | undefined;
+    /** The chat transport adapter for use with Vercel's useChat hook. */
+    readonly chatTransport: ChatTransport;
+}
+/**
+ * The shape of the single {@link ChatTransportContext} value.
+ * Combines the nearest slot with the full registry in one context object.
+ */
+export interface ChatTransportContextValue {
+    /** The slot from the nearest {@link ChatTransportProvider} in the tree. */
+    readonly nearest: ChatTransportSlot | undefined;
+    /** All registered slots, keyed by channelName. */
+    readonly providers: Readonly<Record<string, ChatTransportSlot>>;
+}
+/**
+ * Context that carries both the nearest {@link ChatTransportSlot} and the full registry of
+ * registered slots keyed by channelName. Populated by {@link ChatTransportProvider};
+ * read by {@link useChatTransport}.
+ */
+export declare const ChatTransportContext: import('react').Context<ChatTransportContextValue>;

package/dist/vercel/react/contexts/chat-transport-provider.d.ts

@@ -0,0 +1,96 @@
+import { PropsWithChildren, ReactNode } from 'react';
+import { ClientSessionProviderProps } from '../../../react/index.js';
+import { VercelInput, VercelOutput, VercelProjection } from '../../codec/index.js';
+import { ChatTransportOptions } from '../../transport/index.js';
+/**
+ * ChatTransportProvider: creates a ChatTransport from a ClientSession and makes it
+ * available to descendants via ChatTransportContext.
+ *
+ * Wraps children with ClientSessionProvider (using UIMessageCodec). The
+ * surrounding `<AblyProvider>` supplies the Realtime client; the session
+ * resolves the channel from `channelName` itself. An inner component reads
+ * the ClientSession via useClientSession() and creates the ChatTransport
+ * via useMemo, keyed on the session and transport options.
+ *
+ * The ChatTransport is NOT closed on unmount — the underlying ClientSession
+ * lifecycle is managed by the wrapping ClientSessionProvider. Auto-closing would break
+ * React Strict Mode, and ChatTransport.close() delegates to ClientSession.close()
+ * which ClientSessionProvider already calls.
+ *
+ * Multiple ChatTransportProviders can be nested using distinct channelNames.
+ * Each provider merges its session into the parent registry, so descendants
+ * can access all registered sessions via useChatTransport({ channelName }).
+ */
+import type * as AI from 'ai';
+export declare const ClientSessionProvider: import('react').ComponentType<ClientSessionProviderProps<VercelInput, VercelOutput, VercelProjection, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>>>, useAblyMessages: (props?: {
+    session?: import('../../../react/index.js').ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>> | undefined;
+    skip?: boolean;
+} | undefined) => import('ably').InboundMessage[], useClientSession: (props?: {
+    channelName?: string;
+    skip?: boolean;
+    onError?: (error: import('ably').ErrorInfo) => void;
+}) => import('../../../react/use-client-session.js').ClientSessionHandle<VercelInput, VercelOutput, VercelProjection, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>>, useCreateView: (props?: {
+    session?: import('../../../react/index.js').ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>> | null | undefined;
+    limit?: number;
+    skip?: boolean;
+} | undefined) => import('../../../react/use-view.js').ViewHandle<VercelInput, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>>, useTree: (props?: {
+    session?: import('../../../react/index.js').ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>> | undefined;
+} | undefined) => import('../../../react/use-tree.js').TreeHandle<VercelProjection>, useView: (props?: {
+    session?: import('../../../react/index.js').ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>> | null | undefined;
+    view?: import('../../../index.js').View<VercelInput, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>> | null | undefined;
+    limit?: number;
+    skip?: boolean;
+} | undefined) => import('../../../react/use-view.js').ViewHandle<VercelInput, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>>;
+type CoreClientSessionProviderProps = Omit<ClientSessionProviderProps<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>, 'codec'>;
+/**
+ * Props for {@link ChatTransportProvider}.
+ *
+ * All {@link ClientSessionProviderProps} for Vercel types except `codec` (baked as UIMessageCodec),
+ * plus the transport-owned invocation POST options (`api` / `credentials` / `fetch`) and
+ * `chatOptions` for customizing chat request construction.
+ */
+export interface ChatTransportProviderProps extends CoreClientSessionProviderProps {
+    /** Endpoint the chat transport POSTs the invocation to, to wake the agent. Default `/api/chat`. */
+    api?: string;
+    /** Fetch credentials mode for the invocation POST. */
+    credentials?: RequestCredentials;
+    /** Custom fetch implementation for the invocation POST. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Optional transport options for customizing chat request construction (e.g. the `prepareSendMessagesRequest` hook).
+     * Must be stable across renders — wrap in `useMemo` or define outside the component.
+     * A new object reference triggers ChatTransport recreation.
+     * If this object also sets `api`/`credentials`/`fetch`, the dedicated top-level props of the same name take precedence.
+     */
+    chatOptions?: ChatTransportOptions;
+}
+/**
+ * Provide a {@link ChatTransport} and its underlying {@link ClientSession} to descendant components.
+ *
+ * Wraps children with `ClientSessionProvider` using `channelName` (the Realtime
+ * client is read from the surrounding `<AblyProvider>`), creates a
+ * {@link ClientSession} with UIMessageCodec, wraps it in a {@link ChatTransport},
+ * and registers the full slot in `ChatTransportContext` under `channelName`. Descendants call
+ * {@link useChatTransport} with the same `channelName` to access both.
+ *
+ * `useClientSession` is also available inside this provider's subtree.
+ *
+ * ```tsx
+ * <ChatTransportProvider channelName="ai:demo">
+ *   <Chat />
+ * </ChatTransportProvider>
+ *
+ * // Inside Chat:
+ * const { chatTransport, session } = useChatTransport();
+ * const { session } = useClientSession(); // also available
+ * ```
+ * @param props - Provider configuration including `channelName`, the invocation POST options (`api` / `credentials` / `fetch`), optional `chatOptions`, and all other session options.
+ * @param props.api - Endpoint the chat transport POSTs the invocation to. Default `/api/chat`.
+ * @param props.credentials - Fetch credentials mode for the invocation POST.
+ * @param props.fetch - Custom fetch implementation for the invocation POST.
+ * @param props.chatOptions - Optional hooks for customizing chat request construction. Must be stable (memoized) — a new reference recreates the ChatTransport.
+ * @param props.children - Descendant components that consume the chat transport via hooks.
+ * @returns A React element wrapping children with ClientSessionContext and ChatTransportContext.
+ */
+export declare const ChatTransportProvider: ({ api, credentials, fetch, chatOptions, children, ...sessionProps }: ChatTransportProviderProps & PropsWithChildren) => ReactNode;
+export {};

package/dist/vercel/react/index.d.ts

@@ -1,3 +1,7 @@
 export type { ChatTransport } from '../transport/chat-transport.js';
+export type { ChatTransportProviderProps } from './contexts/chat-transport-provider.js';
+export { ChatTransportProvider, ClientSessionProvider, useAblyMessages, useClientSession, useCreateView, useTree, useView, } from './contexts/chat-transport-provider.js';
+export type { ChatTransportHandle, UseChatTransportOptions } from './use-chat-transport.js';
 export { useChatTransport } from './use-chat-transport.js';
+export type { UseMessageSyncOptions } from './use-message-sync.js';
 export { useMessageSync } from './use-message-sync.js';

package/dist/vercel/react/use-chat-transport.d.ts

@@ -1,29 +1,74 @@
-import { ClientTransport } from '../../core/transport/types.js';
-import { ChatTransport, ChatTransportOptions } from '../transport/chat-transport.js';
-import { VercelClientTransportOptions } from '../transport/index.js';
+import { ClientSession } from '../../core/transport/types.js';
+import { VercelInput, VercelOutput, VercelProjection } from '../codec/index.js';
+import { ChatTransport } from '../transport/index.js';
 /**
- * useChatTransport: wraps a core ClientTransport into the ChatTransport
- * shape that Vercel's useChat expects.
+ * useChatTransport: reads a ChatTransport and its underlying ClientSession from
+ * the nearest ChatTransportProvider.
  *
- * Accepts either an existing ClientTransport or options to create one:
- * - From an existing ClientTransport — wraps it directly
- * - From options — creates a ClientTransport with UIMessageCodec and wraps it
+ * The chat transport is created by ChatTransportProvider, which wraps the subtree
+ * with ClientSessionProvider. The Ably Realtime client is read from the
+ * surrounding `<AblyProvider>`. This hook is a thin context reader — it does
+ * not create or manage any session/transport state.
  *
- * Both forms accept an optional second argument for ChatTransportOptions
- * (e.g. prepareSendMessagesRequest for the persistence pattern).
- *
- * The hook does NOT auto-close the transport on unmount. Channel lifecycle is
- * managed by the Ably provider (useChannel). Auto-closing would break React
- * Strict Mode. Call chatTransport.close() explicitly if needed.
+ * Pass `channelName` to look up a specific provider by name. Omit to use the nearest
+ * provider in the tree. Pass `skip: true` to defer (e.g. when auth is not yet resolved)
+ * — returns stubs whose properties throw with a descriptive error.
  */
+import * as Ably from 'ably';
 import type * as AI from 'ai';
+/** Options for {@link useChatTransport}. */
+export interface UseChatTransportOptions {
+    /** Channel name to look up; omit to use the nearest {@link ChatTransportProvider}. */
+    channelName?: string;
+    /** When `true`, return stubs that throw on any access. */
+    skip?: boolean;
+}
+/**
+ * The value returned by {@link useChatTransport}.
+ * Provides both the underlying {@link ClientSession} and the {@link ChatTransport}
+ * adapter for Vercel's useChat hook.
+ */
+export interface ChatTransportHandle {
+    /**
+     * The underlying client session, also available via {@link useClientSession}.
+     * A throwing stub when `skip` is `true`, when no matching {@link ClientSessionProvider}
+     * was found in the tree, or when session construction failed. Check `sessionError` before use.
+     */
+    session: ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>;
+    /**
+     * The chat transport adapter for use with Vercel's `useChat` hook.
+     *
+     * A throwing stub when `skip` is `true` or when no matching
+     * {@link ChatTransportProvider} was found in the tree. When a provider is found
+     * but the underlying {@link ClientSession} failed to construct, this is the real
+     * transport and `sessionError` is set instead. Check `chatTransportError` and
+     * `sessionError` before use.
+     */
+    chatTransport: ChatTransport;
+    /**
+     * Set when no matching {@link ClientSessionProvider} was found, when session
+     * construction failed, and `skip` is `false`.
+     * `undefined` when the session resolved successfully or when `skip` is `true`.
+     */
+    sessionError?: Ably.ErrorInfo | undefined;
+    /**
+     * Set only when no matching {@link ChatTransportProvider} was found and `skip` is
+     * `false`.
+     * `undefined` when the chat transport resolved successfully (even if session
+     * construction failed — see `sessionError`) or when `skip` is `true`.
+     */
+    chatTransportError?: Ably.ErrorInfo | undefined;
+}
 /**
- * Create and memoize a {@link ChatTransport} for Vercel's useChat hook.
+ * Access a {@link ChatTransport} and {@link ClientSession} from the nearest {@link ChatTransportProvider}.
  *
- * Pass an existing `ClientTransport` to wrap it, or pass
- * `VercelClientTransportOptions` to create one internally with UIMessageCodec.
- * @param transportOrOptions - An existing ClientTransport, or options to create one.
- * @param chatOptions - Optional hooks for customizing request construction.
- * @returns A {@link ChatTransport} compatible with Vercel's useChat hook.
+ * When `channelName` is omitted, the innermost `ChatTransportProvider` in the tree is used.
+ * When `skip` is `true`, returns stubs whose every property and method throws
+ * an {@link Ably.ErrorInfo} — safe to hold in state before conditions are ready.
+ * When no provider is found, returns stubs with `chatTransportError` set instead of throwing.
+ * @param props - Options for selecting the chat transport.
+ * @param props.channelName - The channel name passed to the enclosing `ChatTransportProvider`. Omit to use the nearest.
+ * @param props.skip - When `true`, return stubs that throw on any access instead of reading from context.
+ * @returns The `ChatTransportHandle` containing both the chat transport adapter and the underlying client session.
  */
-export declare const useChatTransport: (transportOrOptions: ClientTransport<AI.UIMessageChunk, AI.UIMessage> | VercelClientTransportOptions, chatOptions?: ChatTransportOptions) => ChatTransport;
+export declare const useChatTransport: ({ channelName, skip }?: UseChatTransportOptions) => ChatTransportHandle;

package/dist/vercel/react/use-message-sync.d.ts

@@ -1,19 +1,38 @@
-import { ClientTransport } from '../../core/transport/types.js';
 /**
- * useMessageSync: wires transport message lifecycle events into useChat's setMessages.
+ * useMessageSync: wire view updates into useChat's setMessages.
  *
- * Subscribes to the transport's 'message' event and replaces messages state
- * with the transport's authoritative message list. Events fire immediately
- * on every store update (including during active streaming), so this hook
- * keeps React state in sync in real time.
+ * During active own-run streams, setMessages is gated to avoid an
+ * ID-mismatch in useChat's write(). When the stream ends, the gate
+ * opens and the view is synced into useChat's overlay.
  *
- * Returns the unsubscribe function in the useEffect cleanup so handlers
- * are removed on unmount or when dependencies change.
+ * The sync is a per-message merge, not a replace: when the overlay has
+ * resolved a client-side tool locally (via addToolResult) but the
+ * tree's echo hasn't landed yet, the overlay's resolution wins.
+ * Without that, the gate-open sync would race the AI SDK's post-stream
+ * sendAutomaticallyWhen check and could clobber the resolution before
+ * the continuation publishes.
  */
 import type * as AI from 'ai';
+/** Options for {@link useMessageSync}. */
+export interface UseMessageSyncOptions {
+    /**
+     * The `setMessages` updater function from `useChat()`. Called with an
+     * updater that returns the next overlay.
+     */
+    setMessages: (updater: (prev: AI.UIMessage[]) => AI.UIMessage[]) => void;
+    /**
+     * Channel name of the {@link ChatTransportProvider} to observe.
+     * Omit to use the nearest provider.
+     */
+    channelName?: string;
+    /** When `true`, skip all subscriptions. */
+    skip?: boolean;
+}
 /**
- * Wire transport message updates into useChat's `setMessages` updater.
- * @param transport - The client transport to observe, or null/undefined if not yet available.
- * @param setMessages - The `setMessages` updater function from useChat.
+ * Subscribe to view updates and sync them into `useChat()`'s overlay.
+ * @param options - Hook options.
+ * @param options.setMessages - The `setMessages` function from `useChat()`.
+ * @param options.channelName - Channel name of the provider to observe; defaults to the nearest.
+ * @param options.skip - When `true`, skip all subscriptions.
  */
-export declare const useMessageSync: (transport: ClientTransport<unknown, AI.UIMessage> | null | undefined, setMessages: (updater: (prev: AI.UIMessage[]) => AI.UIMessage[]) => void) => void;
+export declare const useMessageSync: ({ setMessages, channelName, skip }: UseMessageSyncOptions) => void;

package/dist/vercel/run-end-reason.d.ts

@@ -0,0 +1,29 @@
+import { RunEndReason, StreamResult } from '../core/transport/types.js';
+import type * as AI from 'ai';
+/**
+ * Derive the outcome for a Vercel `streamText` response that was piped through
+ * `Run.pipe`: either a terminal {@link RunEndReason} the caller passes to
+ * `Run.end`, or the sentinel `'suspend'` telling the caller to call
+ * `Run.suspend` instead. Preserves transport-level outcomes (`'cancelled'`,
+ * `'error'`) from the pipe result; when the pipe completed naturally, awaits
+ * Vercel's `finishReason` and returns `'suspend'` for `'tool-calls'` (the LLM
+ * requested tools the SDK did not auto-execute, so the run should suspend
+ * rather than end), or `'complete'` otherwise.
+ *
+ * Tolerates `finishReason` rejection. Vercel AI SDK v6 rejects
+ * `streamText().finishReason` with the abort signal's reason when the stream
+ * is aborted before any step completes, and rejects with
+ * `NoOutputGeneratedError` when the model produced nothing at all. Without
+ * this guard the rejection would bubble out of the route handler's `after()`
+ * block, skip the developer's `Run.end(...)` call, and leave the run with no
+ * `ai-run-end` event on the channel — so observers' UIs stay stuck on
+ * `streaming` indefinitely.
+ *
+ * Saves callers from interpreting Vercel domain semantics inline at the end
+ * of every route handler.
+ * @param pipeResult - The result returned by `Run.pipe`.
+ * @param finishReason - The `finishReason` promise from a `streamText` result.
+ * @returns `'suspend'` when the run should suspend awaiting tool input, or the
+ *   {@link RunEndReason} to pass to `Run.end` otherwise.
+ */
+export declare const vercelRunOutcome: (pipeResult: StreamResult, finishReason: PromiseLike<AI.FinishReason>) => Promise<RunEndReason | "suspend">;

package/dist/vercel/transport/chat-transport.d.ts

@@ -1,19 +1,33 @@
-import { ClientTransport, CloseOptions } from '../../core/transport/types.js';
+import { ClientSession } from '../../core/transport/types.js';
+import { VercelInput, VercelOutput, VercelProjection } from '../codec/index.js';
 /**
- * Vercel chat transport: wraps a core ClientTransport to satisfy the
+ * Vercel chat transport: wraps a core ClientSession to satisfy the
  * ChatTransport interface that useChat expects.
  *
- * This is a thin adapter — the real logic lives in the core transport.
+ * This is a thin adapter — the real logic lives in the core client session.
  * The chat transport maps Vercel's sendMessages/reconnectToStream contract
- * to the core transport's send/cancel methods.
+ * to the core session's send/cancel methods.
  *
  * useChat manages message state before calling sendMessages:
- * - submit-message: appends the new user message, passes the full array
+ * - submit-message (new): appends the new user message, passes the full array
+ * - submit-message (edit): truncates after the edited message, replaces it,
+ *   passes the truncated array with messageId set
  * - regenerate-message: truncates after the target, passes the truncated array
  *
- * The adapter uses `trigger` to determine the history/messages split:
- * - submit-message: last message is new (publish to channel), rest is history
+ * The adapter uses `(trigger, last-message role)` to determine the
+ * history/messages split:
+ * - submit-message + last message is a user message: that last message is new
+ *   (publish to channel), rest is history. A new submit and an edit both take
+ *   this path — an edit just carries a messageId.
+ * - submit-message + last message is an assistant already in the tree
+ *   (continuation): no new messages, entire array is history
  * - regenerate-message: no new messages, entire array is history
+ *
+ * For an edit (submit-message with messageId) and for forking off an
+ * unresolved tool call, the adapter computes fork metadata (forkOf/parent)
+ * from the conversation tree so the server can place the response on the
+ * correct branch. Regeneration fork metadata is NOT computed here —
+ * `View.regenerate` derives forkOf/parent from the tree itself.
  */
 import type * as AI from 'ai';
 /**
@@ -22,33 +36,46 @@ import type * as AI from 'ai';
  */
 export interface SendMessagesRequestContext {
     /** Chat session ID (from useChat's id). */
-    id?: string;
+    chatId?: string;
     /** What triggered the request: user sent a message, or requested regeneration. */
     trigger: 'submit-message' | 'regenerate-message';
     /**
-     * The message ID for regeneration requests. Identifies which assistant
-     * message to regenerate. Undefined for submit-message.
+     * The message ID for edit or regeneration requests. For regeneration,
+     * identifies the assistant message to regenerate. For edits (submit-message
+     * with messageId), identifies the user message being replaced. Undefined
+     * when submitting a new message.
      */
     messageId?: string;
     /** Previous messages in the conversation (context for the LLM). */
     history: AI.UIMessage[];
-    /** The new message(s) being sent (to publish to the channel). Empty for regeneration. */
+    /** The new message(s) being sent (to publish to the channel). Empty for regeneration and for continuations (an auto-submit where the last message is an already-tracked assistant). */
     messages: AI.UIMessage[];
-    /** The msg-id of the message being forked (regenerated or edited). */
+    /** The codec-message-id of the message being forked — the edited user message, or the preceding assistant when forking off an unresolved tool call. Undefined for regeneration (View.regenerate derives it) and fresh sends. */
     forkOf?: string;
-    /** The msg-id of the predecessor in the conversation thread. */
-    parent?: string | null;
+    /** The codec-message-id of the predecessor in the conversation thread. */
+    parent?: string;
 }
+/** Default agent endpoint the transport POSTs invocations to — mirrors Vercel's DefaultChatTransport. */
+export declare const DEFAULT_VERCEL_API = "/api/chat";
 /** Options for customizing the ChatTransport behavior. */
 export interface ChatTransportOptions {
     /**
-     * Customize the POST body before sending. Called by sendMessages()
-     * with the conversation context. Return the body and headers for
-     * the HTTP POST.
-     *
-     * Default: sends all previous messages as `history` in the body.
+     * Endpoint the transport POSTs the invocation pointer to, to wake the
+     * agent. Mirrors useChat's request-driven contract. Default `/api/chat`.
+     */
+    api?: string;
+    /** Fetch credentials mode for the invocation POST (e.g. `'include'`). */
+    credentials?: RequestCredentials;
+    /** Custom fetch implementation for the invocation POST. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Customize the invocation POST before sending. Called by sendMessages()
+     * with the conversation context; the returned `body` is merged into the
+     * POST body (the run's invocation identifiers always take precedence) and
+     * `headers` are added to the request. Use it for auth headers or extra
+     * agent metadata.
      * @param context - The conversation context for the current request.
-     * @returns The body and headers to use for the HTTP POST.
+     * @returns The body and headers to merge into the invocation POST.
      */
     prepareSendMessagesRequest?: (context: SendMessagesRequestContext) => {
         body?: Record<string, unknown>;
@@ -75,7 +102,8 @@ interface ChatRequestOptions {
  *
  * Structurally compatible with the AI SDK's internal `ChatTransport<UIMessage>`
  * interface. Extended with `close()` for releasing the underlying Ably transport
- * resources.
+ * resources and `streaming` / `onStreamingChange` for coordinating with
+ * useMessageSync.
  */
 export interface ChatTransport {
     /** Send messages and return a streaming response of UIMessageChunk events. */
@@ -100,19 +128,32 @@ export interface ChatTransport {
         chatId: string;
     } & ChatRequestOptions) => Promise<ReadableStream<AI.UIMessageChunk> | null>;
     /** Close the underlying transport, releasing all resources. */
-    close(options?: CloseOptions): Promise<void>;
+    close(): Promise<void>;
+    /** Whether an own-run stream is currently being consumed by useChat. */
+    readonly streaming: boolean;
+    /**
+     * Subscribe to streaming state changes. The callback fires when the
+     * ChatTransport transitions between streaming and idle. Used by
+     * useMessageSync to gate setMessages calls during active streams.
+     * @param callback - Called with `true` when a stream starts, `false` when it ends.
+     * @returns Unsubscribe function.
+     */
+    onStreamingChange(callback: (streaming: boolean) => void): () => void;
 }
 /**
- * Create a Vercel ChatTransport from a core ClientTransport.
+ * Create a Vercel ChatTransport from a core ClientSession.
+ *
+ * Exposes a `streaming` flag and `onStreamingChange` callback so that
+ * `useMessageSync` can gate `setMessages` calls during active own-run
+ * streams, preventing the push/replace ID mismatch in useChat's `write()`.
  *
- * Maps Vercel's useChat contract to the core transport's methods:
- * - trigger 'submit-message' → transport.send(lastMessage) with history in body
- * - trigger 'regenerate-message' → transport.send([]) with all messages as history
- * - abortSignal → transport.cancel({ all: true })
- * - reconnectToStream → null (observer mode handles in-progress streams)
- * @param transport - The core client transport to wrap.
+ * Note: concurrent `sendMessage` calls from the same user are a useChat
+ * limitation that cannot be fixed from the transport layer. The
+ * developer must respect useChat's `status` and only call `sendMessage`
+ * when status is `'ready'`.
+ * @param session - The core client session to wrap.
  * @param chatOptions - Optional hooks for customizing request construction.
  * @returns A {@link ChatTransport} compatible with Vercel's useChat hook.
  */
-export declare const createChatTransport: (transport: ClientTransport<AI.UIMessageChunk, AI.UIMessage>, chatOptions?: ChatTransportOptions) => ChatTransport;
+export declare const createChatTransport: (session: ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>, chatOptions?: ChatTransportOptions) => ChatTransport;
 export {};

package/dist/vercel/transport/index.d.ts

@@ -1,4 +1,5 @@
-import { ClientTransport, ClientTransportOptions, ServerTransport, ServerTransportOptions } from '../../core/transport/types.js';
+import { AgentSession, AgentSessionOptions, ClientSession, ClientSessionOptions } from '../../core/transport/types.js';
+import { VercelInput, VercelOutput, VercelProjection } from '../codec/index.js';
 /**
  * Vercel AI SDK transport wrappers that pre-bind the UIMessageCodec.
  *
@@ -6,31 +7,37 @@ import { ClientTransport, ClientTransportOptions, ServerTransport, ServerTranspo
  * 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();
  * ```
  */
 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';
-/** 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'>;
-/** 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'>;
+/** Core client session options with Vercel AI SDK types pre-applied. */
+type CoreClientOpts = ClientSessionOptions<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>;
+/** 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 declare const createClientTransport: (options: VercelClientTransportOptions) => ClientTransport<AI.UIMessageChunk, AI.UIMessage>;
+export declare const createClientSession: (options: VercelClientSessionOptions) => ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>;
 /**
- * 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 declare const createServerTransport: (options: VercelServerTransportOptions) => ServerTransport<AI.UIMessageChunk, AI.UIMessage>;
+export declare const createAgentSession: (options: VercelAgentSessionOptions) => AgentSession<VercelOutput, VercelProjection, AI.UIMessage>;

package/dist/vercel/transport/run-output-stream.d.ts

@@ -0,0 +1,56 @@
+import { ClientSession } from '../../core/transport/types.js';
+import { VercelInput, VercelOutput, VercelProjection } from '../codec/index.js';
+/**
+ * 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';
+type VercelSession = ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>;
+/** 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 declare const createRunOutputStream: (session: VercelSession, runId: Promise<string>, inputCodecMessageId: string) => RunOutputStream;
+export {};

package/dist/version.d.ts

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