@ably/ai-transport 0.1.0 → 0.2.0

package/src/vercel/codec/tool-transitions.ts

@@ -1,8 +1,8 @@
 /**
  * Shared tool part transition logic for the Vercel AI SDK codec.
  *
- * Extracted from the accumulator so the tool output state transition logic
- * lives in one place, reusable by the accumulator and any other callers.
+ * Keeps the tool output state transition logic in one place, reusable by the
+ * Vercel codec reducer and any other callers.
  */
 
 import type * as AI from 'ai';

package/src/vercel/index.ts

@@ -1,4 +1,5 @@
 // Vercel AI SDK codec
+export type { VercelInput, VercelOutput, VercelProjection } from './codec/index.js';
 export { UIMessageCodec } from './codec/index.js';
 
 // Vercel AI SDK transport wrappers (pre-bound to UIMessageCodec)
@@ -6,24 +7,10 @@ export type {
   ChatTransport,
   ChatTransportOptions,
   SendMessagesRequestContext,
-  VercelClientTransportOptions,
-  VercelServerTransportOptions,
+  VercelAgentSessionOptions,
+  VercelClientSessionOptions,
 } from './transport/index.js';
-export { createChatTransport, createClientTransport, createServerTransport } from './transport/index.js';
+export { createAgentSession, createChatTransport, createClientSession } from './transport/index.js';
 
-// Server-side tool result merge helper
-export { applyToolEventsToHistory } from './tool-events.js';
-
-// Server-side tool approval helpers
-export type {
-  PrepareApprovalTurnOptions,
-  PrepareApprovalTurnResult,
-  StreamResponseWithApprovalRedirectOptions,
-  ToolApprovalDecision,
-} from './tool-approvals.js';
-export {
-  applyToolApprovalsToHistory,
-  extractApprovalDecisionsFromHistory,
-  prepareApprovalTurn,
-  streamResponseWithApprovalRedirect,
-} from './tool-approvals.js';
+// Vercel-shaped helpers
+export { vercelRunOutcome } from './run-end-reason.js';

package/src/vercel/react/contexts/chat-transport-context.ts

@@ -2,18 +2,19 @@ import type * as Ably from 'ably';
 import type * as AI from 'ai';
 import { createContext } from 'react';
 
-import type { ClientTransport } from '../../../core/transport/types.js';
+import type { ClientSession } from '../../../core/transport/types.js';
+import type { VercelInput, VercelOutput, VercelProjection } from '../../codec/index.js';
 import type { ChatTransport } from '../../transport/chat-transport.js';
 
 /**
  * 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/src/vercel/react/contexts/chat-transport-provider.tsx

@@ -1,92 +1,100 @@
 /**
- * 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';
 import { type PropsWithChildren, type ReactNode, useContext, useMemo } from 'react';
 
-import { createTransportHooks, type TransportProviderProps } from '../../../react/index.js';
-import { UIMessageCodec } from '../../codec/index.js';
-import { type ChatTransportOptions, DEFAULT_VERCEL_API } from '../../transport/index.js';
+import { type ClientSessionProviderProps, createSessionHooks } from '../../../react/index.js';
+import { UIMessageCodec, type VercelInput, type VercelOutput, type VercelProjection } from '../../codec/index.js';
+import type { ChatTransportOptions } from '../../transport/index.js';
 import { createChatTransport } from '../../transport/index.js';
 import type { ChatTransportSlot } from './chat-transport-context.js';
 import { ChatTransportContext } from './chat-transport-context.js';
 
-export const {
-  TransportProvider,
-  useAblyMessages,
-  useActiveTurns,
-  useClientTransport,
-  useCreateView,
-  useTree,
-  useView,
-} = createTransportHooks<AI.UIMessageChunk, AI.UIMessage>();
+export const { ClientSessionProvider, useAblyMessages, useClientSession, useCreateView, useTree, useView } =
+  createSessionHooks<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>();
 
-type CoreTransportProviderProps = Omit<TransportProviderProps<AI.UIMessageChunk, AI.UIMessage>, 'codec' | 'api'> &
-  Partial<Pick<TransportProviderProps<AI.UIMessageChunk, AI.UIMessage>, 'api'>>;
+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;
 }
 
 const ChatTransportProviderInner = ({
   channelName,
-  chatOptions,
+  chatTransportOptions,
   children,
 }: {
   channelName: string;
-  chatOptions?: ChatTransportOptions;
+  chatTransportOptions: ChatTransportOptions;
   children: ReactNode;
 }) => {
-  const { transport, transportError } = useClientTransport();
+  const { session, sessionError } = useClientSession();
   const { providers: parentProviders } = useContext(ChatTransportContext);
-  const chatTransport = useMemo(() => createChatTransport(transport, chatOptions), [transport, chatOptions]);
+  const chatTransport = useMemo(
+    () => createChatTransport(session, chatTransportOptions),
+    [session, chatTransportOptions],
+  );
   const contextValue = useMemo(() => {
-    const slot: ChatTransportSlot = { transport, transportError, chatTransport };
+    const slot: ChatTransportSlot = { session, sessionError, chatTransport };
     return {
       nearest: slot,
       providers: { ...parentProviders, [channelName]: slot },
     };
-  }, [channelName, parentProviders, chatTransport, transport, transportError]);
+  }, [channelName, parentProviders, chatTransport, session, sessionError]);
 
   return <ChatTransportContext.Provider value={contextValue}>{children}</ChatTransportContext.Provider>;
 };
 
 /**
- * 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">
@@ -94,29 +102,49 @@ const ChatTransportProviderInner = ({
  * </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 const ChatTransportProvider = ({
+  api,
+  credentials,
+  fetch,
   chatOptions,
   children,
-  ...transportProps
-}: ChatTransportProviderProps & PropsWithChildren): ReactNode => (
-  <TransportProvider
-    {...transportProps}
-    api={transportProps.api ?? DEFAULT_VERCEL_API}
-    codec={UIMessageCodec}
-  >
-    <ChatTransportProviderInner
-      channelName={transportProps.channelName}
-      chatOptions={chatOptions}
+  ...sessionProps
+}: ChatTransportProviderProps & PropsWithChildren): ReactNode => {
+  // Fold the transport-owned POST options into a single ChatTransportOptions.
+  // Memoized so the ChatTransport isn't recreated each render — createChatTransport
+  // is keyed on this object's identity.
+  const chatTransportOptions = useMemo<ChatTransportOptions>(
+    () => ({
+      ...chatOptions,
+      ...(api !== undefined && { api }),
+      ...(credentials !== undefined && { credentials }),
+      ...(fetch !== undefined && { fetch }),
+    }),
+    [api, credentials, fetch, chatOptions],
+  );
+
+  return (
+    <ClientSessionProvider
+      {...sessionProps}
+      codec={UIMessageCodec}
     >
-      {children}
-    </ChatTransportProviderInner>
-  </TransportProvider>
-);
+      <ChatTransportProviderInner
+        channelName={sessionProps.channelName}
+        chatTransportOptions={chatTransportOptions}
+      >
+        {children}
+      </ChatTransportProviderInner>
+    </ClientSessionProvider>
+  );
+};

package/src/vercel/react/index.ts

@@ -1,12 +1,11 @@
-// Vercel-specific React hooks
+// Vercel-specific React entry point: providers, hooks, and their types
 export type { ChatTransport } from '../transport/chat-transport.js';
 export type { ChatTransportProviderProps } from './contexts/chat-transport-provider.js';
 export {
   ChatTransportProvider,
-  TransportProvider,
+  ClientSessionProvider,
   useAblyMessages,
-  useActiveTurns,
-  useClientTransport,
+  useClientSession,
   useCreateView,
   useTree,
   useView,
@@ -15,4 +14,3 @@ export type { ChatTransportHandle, UseChatTransportOptions } from './use-chat-tr
 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/src/vercel/react/use-chat-transport.ts

@@ -1,47 +1,43 @@
 /**
- * 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';
 import { useContext } from 'react';
 
-import type { ClientTransport, Tree, View } from '../../core/transport/types.js';
+import type { ClientSession, Tree, View } from '../../core/transport/types.js';
 import { ErrorCode } from '../../errors.js';
+import type { VercelInput, VercelOutput, VercelProjection } from '../codec/index.js';
 import type { ChatTransport } from '../transport/index.js';
 import { ChatTransportContext } from './contexts/chat-transport-context.js';
 
-const SKIPPED_CLIENT_TRANSPORT: ClientTransport<AI.UIMessageChunk, AI.UIMessage> = {
-  get tree(): Tree<AI.UIMessage> {
+const SKIPPED_CLIENT_SESSION: ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage> = {
+  get tree(): Tree<VercelOutput, VercelProjection> {
     throw new Ably.ErrorInfo('unable to access tree; hook is skipped', ErrorCode.InvalidArgument, 400);
   },
-  get view(): View<AI.UIMessageChunk, AI.UIMessage> {
+  get view(): View<VercelInput, AI.UIMessage> {
     throw new Ably.ErrorInfo('unable to access view; hook is skipped', ErrorCode.InvalidArgument, 400);
   },
-  createView: (): View<AI.UIMessageChunk, AI.UIMessage> => {
+  connect: () => {
+    throw new Ably.ErrorInfo('unable to connect; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+  createView: (): View<VercelInput, AI.UIMessage> => {
     throw new Ably.ErrorInfo('unable to create view; hook is skipped', ErrorCode.InvalidArgument, 400);
   },
   cancel: () => {
     throw new Ably.ErrorInfo('unable to cancel; hook is skipped', ErrorCode.InvalidArgument, 400);
   },
-  stageEvents: () => {
-    throw new Ably.ErrorInfo('unable to stage events; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  stageMessage: () => {
-    throw new Ably.ErrorInfo('unable to stage message; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  waitForTurn: () => {
-    throw new Ably.ErrorInfo('unable to wait for turn; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
   on: () => {
     throw new Ably.ErrorInfo('unable to subscribe; hook is skipped', ErrorCode.InvalidArgument, 400);
   },
@@ -76,76 +72,78 @@ const SKIPPED_CHAT_TRANSPORT: ChatTransport = {
 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 const useChatTransport = ({ channelName, skip }: UseChatTransportOptions = {}): ChatTransportHandle => {
   const { nearest, providers } = useContext(ChatTransportContext);
 
   if (skip) {
-    return { transport: SKIPPED_CLIENT_TRANSPORT, chatTransport: SKIPPED_CHAT_TRANSPORT };
+    return { session: SKIPPED_CLIENT_SESSION, chatTransport: SKIPPED_CHAT_TRANSPORT };
   }
 
   if (channelName !== undefined) {
     const slot = providers[channelName];
     if (slot) {
-      return { transport: slot.transport, chatTransport: slot.chatTransport, transportError: slot.transportError };
+      return { session: slot.session, chatTransport: slot.chatTransport, sessionError: slot.sessionError };
     }
     return {
-      transport: SKIPPED_CLIENT_TRANSPORT,
+      session: SKIPPED_CLIENT_SESSION,
       chatTransport: SKIPPED_CHAT_TRANSPORT,
-      transportError: new Ably.ErrorInfo(
-        `unable to use client transport; no TransportProvider found for channelName "${channelName}"`,
+      sessionError: new Ably.ErrorInfo(
+        `unable to use client session; no ClientSessionProvider found for channelName "${channelName}"`,
         ErrorCode.BadRequest,
         400,
       ),
@@ -159,17 +157,17 @@ export const useChatTransport = ({ channelName, skip }: UseChatTransportOptions
 
   if (nearest) {
     return {
-      transport: nearest.transport,
+      session: nearest.session,
       chatTransport: nearest.chatTransport,
-      transportError: nearest.transportError,
+      sessionError: nearest.sessionError,
     };
   }
 
   return {
-    transport: SKIPPED_CLIENT_TRANSPORT,
+    session: SKIPPED_CLIENT_SESSION,
     chatTransport: SKIPPED_CHAT_TRANSPORT,
-    transportError: new Ably.ErrorInfo(
-      'unable to use transport; no TransportProvider found in the tree',
+    sessionError: new Ably.ErrorInfo(
+      'unable to use session; no ClientSessionProvider found in the tree',
       ErrorCode.BadRequest,
       400,
     ),