@ably/ai-transport 0.1.0 → 0.3.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;
 }
@@ -18,7 +19,7 @@ export interface ChatTransportSlot {
  * The shape of the single {@link ChatTransportContext} value.
  * Combines the nearest slot with the full registry in one context object.
  */
-export interface ChatTransportContextValue {
+interface ChatTransportContextValue {
     /** The slot from the nearest {@link ChatTransportProvider} in the tree. */
     readonly nearest: ChatTransportSlot | undefined;
     /** All registered slots, keyed by channelName. */
@@ -30,3 +31,4 @@ export interface ChatTransportContextValue {
  * read by {@link useChatTransport}.
  */
 export declare const ChatTransportContext: import('react').Context<ChatTransportContextValue>;
+export {};

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,84 @@
+import { RunEndReason, StreamResult } from '../core/transport/types.js';
+import * as Ably from 'ably';
+import type * as AI from 'ai';
+/**
+ * The outcome of a Vercel `streamText` response piped through `Run.pipe`.
+ * Discriminated on `reason`: `'suspend'` means the run should pause; the
+ * non-`'suspend'` arms describe how it terminated, and an `'error'` outcome
+ * always carries `error`.
+ *
+ * This is a *description of what the Vercel run resulted in*, not a command to
+ * the SDK. The common case maps cleanly onto one transport action — `'suspend'`
+ * → `Run.suspend()`, everything else → `Run.end()` — and to make that case a
+ * one-liner the non-`'suspend'` arms are deliberately assignable to
+ * {@link RunEndParams}, so after a `suspend` guard the whole object passes
+ * straight to `Run.end(outcome)`. That assignability is a convenience for this
+ * adapter, not a constraint on what an outcome can mean: responding to an
+ * outcome may also involve work outside this SDK (persisting a result,
+ * notifying a human, triggering a downstream workflow), and the developer is
+ * free to do that around the terminal call.
+ *
+ * The type is Vercel-specific by design. Outcomes are the layer where agent
+ * SDKs diverge most — both in what they report (the `'suspend'` arm exists only
+ * because Vercel surfaces unexecuted tool calls as a non-terminal finish) and
+ * in what a developer must do in response. A different SDK's outcome type would
+ * have different arms; hence each adapter names its own rather than sharing a
+ * single core `RunOutcome`. The vocabulary it bottoms out in
+ * ({@link RunEndParams}, `Run.suspend`/`Run.end`) is the shared, codec-agnostic
+ * part that does live in core.
+ */
+export type VercelRunOutcome = {
+    /**
+     * The LLM requested tools the SDK did not auto-execute, so the run
+     * pauses rather than ending — call `Run.suspend()`.
+     */
+    reason: 'suspend';
+    /** Never present for a suspend outcome. */
+    error?: never;
+} | {
+    /** A non-error terminal reason; pass the outcome to `Run.end()`. */
+    reason: Exclude<RunEndReason, 'error'>;
+    /** Never present for a non-error outcome. */
+    error?: never;
+} | {
+    /** The run ended in error; pass the outcome to `Run.end()`. */
+    reason: Extract<RunEndReason, 'error'>;
+    /**
+     * The terminal error: the underlying stream / `finishReason` failure
+     * wrapped as an `Ably.ErrorInfo` (code `StreamError`).
+     */
+    error: Ably.ErrorInfo;
+};
+/**
+ * Derive the {@link VercelRunOutcome} for a Vercel `streamText` response that
+ * was piped through `Run.pipe`. 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.
+ *
+ * Surfaces the failure for both error shapes so the caller can forward it to
+ * `Run.end(reason, error)`: a stream that threw (`pipeResult.error`) and a
+ * `finishReason` that rejected with a non-abort error (e.g.
+ * `NoOutputGeneratedError`, network blow-ups). The error is wrapped as an
+ * `Ably.ErrorInfo` (code `StreamError`). A stream that already produced a
+ * codec-level error chunk is unaffected — stamping run-end is the
+ * codec-agnostic baseline that any consumer can read.
+ *
+ * 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 The {@link VercelRunOutcome}: the terminal `reason` (or `'suspend'`)
+ *   and, when `reason` is `'error'`, the wrapped `error` to pass to `Run.end`.
+ */
+export declare const vercelRunOutcome: (pipeResult: StreamResult, finishReason: PromiseLike<AI.FinishReason>) => Promise<VercelRunOutcome>;

package/dist/vercel/tool-part.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared tool-part type guard for the Vercel layer.
+ *
+ * The codec normalises every tool part to the `dynamic-tool` shape, but the AI
+ * SDK emits `tool-${name}` parts for statically-declared tools. Both shapes
+ * carry `toolCallId` and `state`. The guard accepts either representation so
+ * the transport's unresolved-tool detection and the React overlay merge can
+ * match tool parts uniformly — and so the cross-representation rule lives in
+ * one place rather than being re-spelled per call site.
+ */
+import type * as AI from 'ai';
+/** A UIMessage tool part in either the `dynamic-tool` or `tool-${name}` representation. */
+export type ToolPart = AI.DynamicToolUIPart | AI.ToolUIPart;
+/**
+ * Whether a UIMessage part is a tool part of either representation. The
+ * `toolCallId`/`state` shape check is defensive against a future AI SDK release
+ * introducing a non-tool variant under the `tool-` prefix (none exists today).
+ * @param part - The UIMessage part to inspect.
+ * @returns True when the part is a tool part.
+ */
+export declare const isToolPart: (part: AI.UIMessage["parts"][number]) => part is ToolPart;

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,32 @@ 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;
 }
 /** 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 +126,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 +139,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 {};