@ably/ai-transport 0.0.1 → 0.1.0

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

@@ -0,0 +1,32 @@
+import { ClientTransport } from '../../../core/transport/types.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.
+ */
+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 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,84 @@
+import { PropsWithChildren, ReactNode } from 'react';
+import { TransportProviderProps } from '../../../react/index.js';
+import { ChatTransportOptions } from '../../transport/index.js';
+/**
+ * ChatTransportProvider: creates a ChatTransport from a ClientTransport 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).
+ *
+ * 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.
+ *
+ * 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 }).
+ */
+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;
+    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?: {
+    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;
+    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;
+    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'>>;
+/**
+ * Props for {@link ChatTransportProvider}.
+ *
+ * All {@link TransportProviderProps} for Vercel types except `codec` (baked as UIMessageCodec),
+ * plus `chatOptions` for customizing chat request construction.
+ */
+export interface ChatTransportProviderProps extends CoreTransportProviderProps {
+    /**
+     * Optional hooks for customizing chat request construction (e.g. prepareSendMessagesRequest).
+     * Must be stable across renders — wrap in `useMemo` or define outside the component.
+     * A new object reference triggers ChatTransport recreation.
+     */
+    chatOptions?: ChatTransportOptions;
+}
+/**
+ * Provide a {@link ChatTransport} and its underlying {@link ClientTransport} 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},
+ * and registers the full slot in `ChatTransportContext` under `channelName`. Descendants call
+ * {@link useChatTransport} with the same `channelName` to access both transports.
+ *
+ * `useClientTransport` is also available inside this provider's subtree.
+ *
+ * ```tsx
+ * <ChatTransportProvider channelName="ai:demo">
+ *   <Chat />
+ * </ChatTransportProvider>
+ *
+ * // Inside Chat:
+ * const { chatTransport, transport } = useChatTransport();
+ * const { transport } = useClientTransport(); // also available
+ * ```
+ * @param props - Provider configuration including `channelName`, optional `chatOptions`, and all other transport options.
+ * @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.
+ */
+export declare const ChatTransportProvider: ({ chatOptions, children, ...transportProps }: ChatTransportProviderProps & PropsWithChildren) => ReactNode;
+export {};

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

@@ -1,3 +1,8 @@
 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 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,29 +1,70 @@
 import { ClientTransport } from '../../core/transport/types.js';
-import { ChatTransport, ChatTransportOptions } from '../transport/chat-transport.js';
-import { VercelClientTransportOptions } from '../transport/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 ClientTransport 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 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.
  *
- * 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 stub transports 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 stub transports that throw on any access. */
+    skip?: boolean;
+}
+/**
+ * The value returned by {@link useChatTransport}.
+ * Provides both the underlying {@link ClientTransport} 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.
+     */
+    transport: ClientTransport<AI.UIMessageChunk, 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.
+     */
+    chatTransport: ChatTransport;
+    /**
+     * Set when no matching {@link TransportProvider} was found, when transport
+     * construction failed, and `skip` is `false`.
+     * `undefined` when the transport resolved successfully or when `skip` is `true`.
+     */
+    transportError?: 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`.
+     */
+    chatTransportError?: Ably.ErrorInfo | undefined;
+}
 /**
- * Create and memoize a {@link ChatTransport} for Vercel's useChat hook.
+ * Access a {@link ChatTransport} and {@link ClientTransport} 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 stub transports 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.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.
  */
-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,51 @@
-import { ClientTransport } from '../../core/transport/types.js';
 /**
  * useMessageSync: wires transport message lifecycle events 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.
+ * Subscribes to the transport view's 'update' event and replaces messages state
+ * with the view's authoritative message list.
+ *
+ * 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.
  */
 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.
+     */
+    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.
+     */
+    channelName?: string;
+    /**
+     * When `true`, skip all subscriptions and do nothing.
+     * Use when the hook's dependencies are not yet resolved (e.g. auth pending).
+     */
+    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.
+ * 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.
+ * @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.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/react/use-staged-add-tool-approval-response.d.ts

@@ -0,0 +1,30 @@
+import { ChatAddToolApproveResponseFunction } from 'ai';
+import { ClientTransport } from '../../core/transport/types.js';
+/**
+ * useStagedAddToolApprovalResponse — wrap useChat's `addToolApprovalResponse`
+ * so the approval response is also applied to the transport tree
+ * synchronously at click time.
+ *
+ * Patching the tree at click time eliminates the useChat↔tree divergence
+ * the ChatTransport would otherwise have to reconcile via a history
+ * overlay, and closes the observer-turn race that could wipe the
+ * approval state between `addToolApprovalResponse` and
+ * `sendAutomaticallyWhen`'s evaluation.
+ *
+ * Use this in place of useChat's raw `addToolApprovalResponse` wherever
+ * you wire Approve / Deny buttons.
+ */
+import type * as AI from 'ai';
+/**
+ * Returns a function with the same signature as useChat's
+ * `addToolApprovalResponse`, but additionally applies the approval
+ * response to the transport tree via `stageMessage` before delegating.
+ *
+ * If the tool call identified by `opts.id` isn't found in the tree,
+ * the tree update is skipped and the raw function is still called —
+ * matches useChat's tolerant behavior for stale approval ids.
+ * @param transport - The client transport whose tree to patch.
+ * @param addToolApprovalResponse - The raw function from `useChat()`.
+ * @returns A drop-in replacement that patches the tree then delegates.
+ */
+export declare const useStagedAddToolApprovalResponse: (transport: ClientTransport<AI.UIMessageChunk, AI.UIMessage>, addToolApprovalResponse: ChatAddToolApproveResponseFunction) => ChatAddToolApproveResponseFunction;

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

@@ -0,0 +1,124 @@
+import { MessageNode, StreamResponseOptions, StreamResult, Turn } from '../core/transport/types.js';
+/**
+ * Server-side helpers for processing a tool-approval turn.
+ *
+ * When a Vercel AI SDK tool is marked `needsApproval`, `streamText` pauses
+ * after emitting a `dynamic-tool` part in state `approval-requested`. To
+ * resume, the server must:
+ *
+ *   1. Patch the UIMessage history so the pending tool part reflects the
+ *      user's decision (`approval-responded` or `output-denied`).
+ *   2. Strip the client-appended "Approved: …" user message, because
+ *      `streamText`'s multi-step loop only auto-executes pending tool
+ *      calls when the conversation ends on a tool/assistant message.
+ *   3. Disable `needsApproval` on just-approved tools so the multi-step
+ *      loop doesn't immediately pause again on the same tool.
+ *   4. Redirect the resulting `tool-output-available` / `tool-output-error`
+ *      chunks back to the ORIGINAL assistant message (the one that held
+ *      the `approval-requested` part) via `x-ably-amend`, instead of
+ *      letting them land on the new assistant message this turn produces.
+ *
+ * `prepareApprovalTurn` covers steps 1–3; `streamResponseWithApprovalRedirect`
+ * covers step 4.
+ */
+import type * as AI from 'ai';
+/**
+ * A user's decision on a pending tool approval. The client ships an array of
+ * these to the server in the POST body; the server feeds them to
+ * `prepareApprovalTurn` (to patch history) and
+ * `streamResponseWithApprovalRedirect` (to route tool outputs back to the
+ * original assistant message).
+ *
+ * Intentionally does not carry `toolName` or `input` — those are redundant
+ * with what's already on the UIMessage history part.
+ */
+export interface ToolApprovalDecision {
+    /**
+     * The `toolCallId` of the pending `dynamic-tool` part being approved/denied.
+     * Must match a part already in the history; decisions that don't match any
+     * part are ignored by {@link applyToolApprovalsToHistory}.
+     */
+    toolCallId: string;
+    /** Whether the user approved or denied the tool call. */
+    approved: boolean;
+    /**
+     * The `x-ably-msg-id` of the assistant message whose `dynamic-tool` part
+     * is being responded to. When approved and the tool executes successfully,
+     * the output is published cross-turn targeting this message.
+     */
+    targetMsgId: string;
+    /** Optional reason accompanying the response. */
+    reason?: string;
+}
+/**
+ * Patch `dynamic-tool` parts in the history to reflect a batch of approval
+ * decisions. Pure — returns a new array; input is not mutated.
+ *
+ * Approved decisions transition the matching part to `approval-responded`,
+ * which `convertToModelMessages` will expand into a `tool-approval-response`
+ * model message for `streamText`'s multi-step loop. Denied decisions
+ * transition to `output-denied`.
+ *
+ * Messages and parts whose `toolCallId` is not referenced by any decision
+ * are passed through by reference.
+ * @param messages - The UIMessage history (user + assistant messages).
+ * @param decisions - Approval decisions keyed by `toolCallId`.
+ * @returns A new array with matching tool parts transitioned.
+ */
+export declare const applyToolApprovalsToHistory: (messages: AI.UIMessage[], decisions: ToolApprovalDecision[]) => AI.UIMessage[];
+/** Options for {@link prepareApprovalTurn}. */
+export interface PrepareApprovalTurnOptions<T extends Record<string, object>> {
+    /** The full UIMessage history (user + assistant messages for this conversation). */
+    messages: AI.UIMessage[];
+    /** The user's approval decisions for this request, if any. */
+    decisions: ToolApprovalDecision[] | undefined;
+    /**
+     * The tool dictionary that will be passed to `streamText`. Typed with a
+     * structural `object` value constraint so it accepts `Record<string, Tool>`
+     * regardless of which copy of the `ai` peer dep typed it.
+     */
+    tools: T;
+}
+/** Result of {@link prepareApprovalTurn}. */
+export interface PrepareApprovalTurnResult<T extends Record<string, object>> {
+    /** Model-format messages ready to pass to `streamText({ messages })`. */
+    modelMessages: AI.ModelMessage[];
+    /** Tools with `needsApproval` disabled for any tool that was just approved. */
+    tools: T;
+}
+/**
+ * One-shot transform to ready a history + tool dict for a `streamText` call
+ * on an approval turn. Returns the patched model-message array and the
+ * effective tools dict.
+ *
+ * When `decisions` is absent or empty, this is a thin wrapper around
+ * `convertToModelMessages(messages)` that returns the original tools — so
+ * callers can use it uniformly regardless of whether the request carries
+ * approvals.
+ * @param options - See {@link PrepareApprovalTurnOptions}.
+ * @returns See {@link PrepareApprovalTurnResult}.
+ */
+export declare const prepareApprovalTurn: <T extends Record<string, object>>(options: PrepareApprovalTurnOptions<T>) => Promise<PrepareApprovalTurnResult<T>>;
+/** Options for {@link streamResponseWithApprovalRedirect}. */
+export interface StreamResponseWithApprovalRedirectOptions extends StreamResponseOptions<AI.UIMessageChunk> {
+    /**
+     * The approval decisions this turn is resolving. Only approved decisions
+     * redirect tool outputs — denied decisions have already been reflected
+     * in the history and produce no tool output to capture.
+     */
+    decisions: ToolApprovalDecision[] | undefined;
+}
+export declare const streamResponseWithApprovalRedirect: (turn: Turn<AI.UIMessageChunk, AI.UIMessage>, stream: ReadableStream<AI.UIMessageChunk>, options: StreamResponseWithApprovalRedirectOptions) => Promise<StreamResult>;
+/**
+ * Walk the conversation history and synthesize a {@link ToolApprovalDecision}
+ * for each `dynamic-tool` part in `approval-responded` (approved) or
+ * `output-denied` (denied) state.
+ *
+ * Use in server routes where the client flips the tool part state directly
+ * (via useChat's `addToolApprovalResponse` and our
+ * `useStagedAddToolApprovalResponse`) and ships it through the history
+ * overlay instead of a separate `toolApprovals` body field.
+ * @param history - The conversation history nodes from the POST body.
+ * @returns Approval decisions derived from the history, in walk order.
+ */
+export declare const extractApprovalDecisionsFromHistory: (history: readonly MessageNode<AI.UIMessage>[]) => ToolApprovalDecision[];

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

@@ -0,0 +1,26 @@
+import { EventsNode, MessageNode } from '../core/transport/types.js';
+/**
+ * Server-side helper for folding client-shipped events into an in-memory
+ * history array before handing it to `convertToModelMessages` / `streamText`.
+ *
+ * When a client-executed tool resolves, the client stages the resulting
+ * `tool-output-available` / `tool-output-error` chunk via
+ * `transport.stageEvents(msgId, [...])`. The next send flushes it into the
+ * POST body's `events` field. The server republishes the event on the
+ * channel via `turn.addEvents`, and must also merge it into the in-memory
+ * history so the LLM sees the tool result this turn.
+ */
+import type * as AI from 'ai';
+/**
+ * Fold a batch of client-shipped events into an in-memory history array.
+ *
+ * Mirrors the optimistic tree update in
+ * `DefaultClientTransport._internalSend` (src/core/transport/client-transport.ts)
+ * so the server can rebuild the same message state before handing it to
+ * `convertToModelMessages` / `streamText`.
+ * @param events - The events shipped by the client.
+ * @param nodes - The history messages from the POST body.
+ * @returns A new array with tool-result events applied to the matching
+ *   messages. Non-targeted messages are passed through unchanged.
+ */
+export declare const applyToolEventsToHistory: (events: EventsNode<AI.UIMessageChunk>[], nodes: MessageNode<AI.UIMessage>[]) => MessageNode<AI.UIMessage>[];

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

@@ -8,12 +8,18 @@ import { ClientTransport, CloseOptions } from '../../core/transport/types.js';
  * to the core transport'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
  * - 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.
  */
 import type * as AI from 'ai';
 /**
@@ -22,12 +28,14 @@ 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). */
@@ -37,7 +45,7 @@ export interface SendMessagesRequestContext {
     /** The msg-id of the message being forked (regenerated or edited). */
     forkOf?: string;
     /** The msg-id of the predecessor in the conversation thread. */
-    parent?: string | null;
+    parent?: string;
 }
 /** Options for customizing the ChatTransport behavior. */
 export interface ChatTransportOptions {
@@ -75,7 +83,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. */
@@ -101,15 +110,28 @@ export interface ChatTransport {
     } & 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. */
+    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.
  *
- * 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)
+ * Exposes a `streaming` flag and `onStreamingChange` callback so that
+ * `useMessageSync` can gate `setMessages` calls during active own-turn
+ * 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 chatOptions - Optional hooks for customizing request construction.
  * @returns A {@link ChatTransport} compatible with Vercel's useChat hook.

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

@@ -14,10 +14,13 @@ import { ClientTransport, ClientTransportOptions, ServerTransport, ServerTranspo
 export type { ChatTransport, ChatTransportOptions, SendMessagesRequestContext } from './chat-transport.js';
 export { createChatTransport } 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'>;
+/** 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";
 /**
  * Create a client-side transport pre-configured with the Vercel AI SDK codec.
  *