@ably/ai-transport 0.1.0 → 0.2.0

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

@@ -1,16 +1,17 @@
-import { ClientTransport } from '../../../core/transport/types.js';
+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 ClientTransport} and the {@link ChatTransport} wrapping it.
+ * underlying {@link ClientSession} and the {@link ChatTransport} wrapping it.
  */
 export interface ChatTransportSlot {
-    /** The underlying client transport used to create the chat transport. */
-    readonly transport: ClientTransport<AI.UIMessageChunk, AI.UIMessage>;
-    /** Construction error from the underlying {@link ClientTransport}, or `undefined` on success. */
-    readonly transportError: Ably.ErrorInfo | undefined;
+    /** 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;
 }

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

@@ -1,70 +1,79 @@
 import { PropsWithChildren, ReactNode } from 'react';
-import { TransportProviderProps } from '../../../react/index.js';
+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 ClientTransport and makes it
+ * ChatTransportProvider: creates a ChatTransport from a ClientSession and makes it
  * available to descendants via ChatTransportContext.
  *
- * Wraps children with TransportProvider (using UIMessageCodec) so the Ably channel
- * lifecycle is managed in one place. An inner component reads the ClientTransport
- * from NearestTransportContext and creates the ChatTransport once on first render
- * (via useRef).
+ * 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 ClientTransport
- * lifecycle is managed by the wrapping TransportProvider. Auto-closing would break
- * React Strict Mode, and ChatTransport.close() delegates to ClientTransport.close()
- * which TransportProvider already calls.
+ * 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 transport into the parent registry, so descendants
- * can access all registered transports via useChatTransport({ channelName }).
+ * 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 TransportProvider: import('react').ComponentType<TransportProviderProps<AI.UIMessageChunk, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>>>, useAblyMessages: (props?: {
-    transport?: import('../../../index.js').ClientTransport<AI.UIMessageChunk, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>> | undefined;
+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[], useActiveTurns: (props?: {
-    transport?: import('../../../index.js').ClientTransport<AI.UIMessageChunk, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>> | null | undefined;
-} | undefined) => Map<string, Set<string>>, useClientTransport: (props?: {
+} | undefined) => import('ably').InboundMessage[], useClientSession: (props?: {
     channelName?: string;
     skip?: boolean;
     onError?: (error: import('ably').ErrorInfo) => void;
-}) => import('../../../react/use-client-transport.js').ClientTransportHandle<AI.UIMessageChunk, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>>, useCreateView: (props?: {
-    transport?: import('../../../index.js').ClientTransport<AI.UIMessageChunk, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>> | null | undefined;
+}) => 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<AI.UIMessageChunk, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>>, useTree: (props?: {
-    transport?: import('../../../index.js').ClientTransport<AI.UIMessageChunk, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>> | undefined;
-} | undefined) => import('../../../react/use-tree.js').TreeHandle<AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>>, useView: (props?: {
-    transport?: import('../../../index.js').ClientTransport<AI.UIMessageChunk, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>> | null | undefined;
-    view?: import('../../../index.js').View<AI.UIMessageChunk, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>> | null | undefined;
+} | 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<AI.UIMessageChunk, AI.UIMessage<unknown, AI.UIDataTypes, AI.UITools>>;
-type CoreTransportProviderProps = Omit<TransportProviderProps<AI.UIMessageChunk, AI.UIMessage>, 'codec' | 'api'> & Partial<Pick<TransportProviderProps<AI.UIMessageChunk, AI.UIMessage>, 'api'>>;
+} | 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 TransportProviderProps} for Vercel types except `codec` (baked as UIMessageCodec),
- * plus `chatOptions` for customizing chat request construction.
+ * 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 CoreTransportProviderProps {
+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 hooks for customizing chat request construction (e.g. prepareSendMessagesRequest).
+     * 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 ClientTransport} to descendant components.
+ * Provide a {@link ChatTransport} and its underlying {@link ClientSession} to descendant components.
  *
- * Wraps children with Ably's `ChannelProvider` (via `TransportProvider`) using `channelName`,
- * creates a {@link ClientTransport} with UIMessageCodec, wraps it in a {@link ChatTransport},
+ * 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 transports.
+ * {@link useChatTransport} with the same `channelName` to access both.
  *
- * `useClientTransport` is also available inside this provider's subtree.
+ * `useClientSession` is also available inside this provider's subtree.
  *
  * ```tsx
  * <ChatTransportProvider channelName="ai:demo">
@@ -72,13 +81,16 @@ export interface ChatTransportProviderProps extends CoreTransportProviderProps {
  * </ChatTransportProvider>
  *
  * // Inside Chat:
- * const { chatTransport, transport } = useChatTransport();
- * const { transport } = useClientTransport(); // also available
+ * const { chatTransport, session } = useChatTransport();
+ * const { session } = useClientSession(); // also available
  * ```
- * @param props - Provider configuration including `channelName`, optional `chatOptions`, and all other transport options.
+ * @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 transport via hooks.
- * @returns A React element wrapping children with ChannelProvider, TransportContext, and ChatTransportContext.
+ * @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: ({ chatOptions, children, ...transportProps }: ChatTransportProviderProps & PropsWithChildren) => ReactNode;
+export declare const ChatTransportProvider: ({ api, credentials, fetch, chatOptions, children, ...sessionProps }: ChatTransportProviderProps & PropsWithChildren) => ReactNode;
 export {};

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

@@ -1,8 +1,7 @@
 export type { ChatTransport } from '../transport/chat-transport.js';
 export type { ChatTransportProviderProps } from './contexts/chat-transport-provider.js';
-export { ChatTransportProvider, TransportProvider, useAblyMessages, useActiveTurns, useClientTransport, useCreateView, useTree, useView, } 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';
-export { useStagedAddToolApprovalResponse } from './use-staged-add-tool-approval-response.js';

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

@@ -1,16 +1,18 @@
-import { ClientTransport } from '../../core/transport/types.js';
+import { ClientSession } from '../../core/transport/types.js';
+import { VercelInput, VercelOutput, VercelProjection } from '../codec/index.js';
 import { ChatTransport } from '../transport/index.js';
 /**
- * useChatTransport: reads a ChatTransport and its underlying ClientTransport from
+ * useChatTransport: reads a ChatTransport and its underlying ClientSession from
  * the nearest ChatTransportProvider.
  *
- * The transport is created by ChatTransportProvider, which also wraps the subtree
- * with TransportProvider and Ably's ChannelProvider. This hook is a thin context
- * reader — it does not create or manage any transport state.
+ * 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.
  *
  * 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 stub transports whose properties throw with a descriptive error.
+ * — returns stubs whose properties throw with a descriptive error.
  */
 import * as Ably from 'ably';
 import type * as AI from 'ai';
@@ -18,53 +20,55 @@ import type * as AI from 'ai';
 export interface UseChatTransportOptions {
     /** Channel name to look up; omit to use the nearest {@link ChatTransportProvider}. */
     channelName?: string;
-    /** When `true`, return stub transports that throw on any access. */
+    /** When `true`, return stubs that throw on any access. */
     skip?: boolean;
 }
 /**
  * The value returned by {@link useChatTransport}.
- * Provides both the underlying {@link ClientTransport} and the {@link ChatTransport}
+ * Provides both the underlying {@link ClientSession} and the {@link ChatTransport}
  * adapter for Vercel's useChat hook.
  */
 export interface ChatTransportHandle {
     /**
-     * The underlying client transport, also available via {@link useClientTransport}.
-     * A throwing stub when `skip` is `true`, when no matching {@link TransportProvider}
-     * was found in the tree, or when transport construction failed. Check `transportError` before use.
+     * 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.
      */
-    transport: ClientTransport<AI.UIMessageChunk, AI.UIMessage>;
+    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`, when no matching
-     * {@link ChatTransportProvider} was found in the tree, or when the underlying
-     * {@link ClientTransport} construction failed. Check both `chatTransportError`
-     * and `transportError` before use.
+     * 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 TransportProvider} was found, when transport
+     * Set when no matching {@link ClientSessionProvider} was found, when session
      * construction failed, and `skip` is `false`.
-     * `undefined` when the transport resolved successfully or when `skip` is `true`.
+     * `undefined` when the session resolved successfully or when `skip` is `true`.
      */
-    transportError?: Ably.ErrorInfo | undefined;
+    sessionError?: Ably.ErrorInfo | undefined;
     /**
-     * Set when no matching {@link ChatTransportProvider} was found or when transport
-     * construction failed, and `skip` is `false`.
-     * `undefined` when the transport resolved successfully or when `skip` is `true`.
+     * 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;
 }
 /**
- * Access a {@link ChatTransport} and {@link ClientTransport} from the nearest {@link ChatTransportProvider}.
+ * Access a {@link ChatTransport} and {@link ClientSession} from the nearest {@link ChatTransportProvider}.
  *
  * When `channelName` is omitted, the innermost `ChatTransportProvider` in the tree is used.
- * When `skip` is `true`, returns stub transports whose every property and method throws
+ * 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 transport.
+ * @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 transport.
+ * @returns The `ChatTransportHandle` containing both the chat transport adapter and the underlying client session.
  */
 export declare const useChatTransport: ({ channelName, skip }?: UseChatTransportOptions) => ChatTransportHandle;

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

@@ -1,51 +1,38 @@
 /**
- * useMessageSync: wires transport message lifecycle events into useChat's setMessages.
+ * useMessageSync: wire view updates into useChat's setMessages.
  *
- * Subscribes to the transport view's 'update' event and replaces messages state
- * with the view's authoritative message list.
+ * 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.
  *
- * When a ChatTransport is provided (resolved from the nearest ChatTransportProvider),
- * setMessages calls are gated during active own-turn streams. This prevents the
- * push/replace ID mismatch in useChat's write() function. When the stream finishes,
- * the gate opens and an immediate sync fires to pick up any observer messages that
- * arrived during the stream.
- *
- * All dependencies are resolved from the nearest ChatTransportProvider via
- * useChatTransport(). Pass channelName to select a specific provider; omit to use
- * the nearest. Pass skip: true to pause all subscriptions.
- *
- * 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()`. Required.
-     * Called with a function that replaces the previous message list with the
-     * transport's current authoritative message list.
+     * 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 in the tree.
+     * Omit to use the nearest provider.
      */
     channelName?: string;
-    /**
-     * When `true`, skip all subscriptions and do nothing.
-     * Use when the hook's dependencies are not yet resolved (e.g. auth pending).
-     */
+    /** When `true`, skip all subscriptions. */
     skip?: boolean;
 }
 /**
- * Wire transport message updates into `useChat()`'s `setMessages` updater.
- *
- * Resolves both the transport view and the streaming gate from the nearest
- * `ChatTransportProvider`. Pass `channelName` to target a specific provider.
- * Pass `skip: true` to pause all subscriptions.
+ * Subscribe to view updates and sync them into `useChat()`'s overlay.
  * @param options - Hook options.
- * @param options.setMessages - The `setMessages` function from `useChat()`. Required.
- * @param options.channelName - Channel name of the provider to observe; defaults to nearest.
+ * @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: ({ 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,11 +1,12 @@
-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 (new): appends the new user message, passes the full array
@@ -13,13 +14,20 @@ import { ClientTransport, CloseOptions } from '../../core/transport/types.js';
  *   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
  *
- * When messageId is set (edit or regeneration), the adapter computes fork
- * metadata (forkOf/parent) from the conversation tree so the server can
- * place the response on the correct branch.
+ * 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';
 /**
@@ -40,23 +48,34 @@ export interface SendMessagesRequestContext {
     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. */
+    /** 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>;
@@ -109,8 +128,8 @@ export interface ChatTransport {
         chatId: string;
     } & ChatRequestOptions) => Promise<ReadableStream<AI.UIMessageChunk> | null>;
     /** Close the underlying transport, releasing all resources. */
-    close(options?: CloseOptions): Promise<void>;
-    /** Whether an own-turn stream is currently being consumed by useChat. */
+    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
@@ -122,19 +141,19 @@ export interface ChatTransport {
     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-turn
+ * `useMessageSync` can gate `setMessages` calls during active own-run
  * streams, preventing the push/replace ID mismatch in useChat's `write()`.
  *
  * 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 transport - The core client transport to wrap.
+ * @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,34 +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';
-/** Core client transport options with Vercel AI SDK types pre-applied. */
-type CoreClientOpts = ClientTransportOptions<AI.UIMessageChunk, AI.UIMessage>;
-/** Options for creating a Vercel client transport. Same as core options but without the codec field, and with `api` optional (defaults to `"/api/chat"`). */
-export type VercelClientTransportOptions = Omit<CoreClientOpts, 'codec' | 'api'> & Partial<Pick<CoreClientOpts, 'api'>>;
-/** 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'>;
-export declare const DEFAULT_VERCEL_API = "/api/chat";
+/** 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>;