@ably/ai-transport 0.0.1 → 0.2.0

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

@@ -0,0 +1,122 @@
+/**
+ * Shared tool part transition logic for the Vercel AI SDK codec.
+ *
+ * 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';
+
+import { stripUndefined } from '../../utils.js';
+
+// ---------------------------------------------------------------------------
+// Tool output chunk type guard
+// ---------------------------------------------------------------------------
+
+/** The set of UIMessageChunk types that represent tool output transitions. */
+export type ToolOutputChunk = Extract<
+  AI.UIMessageChunk,
+  { type: 'tool-output-available' | 'tool-output-error' | 'tool-output-denied' | 'tool-approval-request' }
+>;
+
+/**
+ * Whether a UIMessageChunk is a tool output transition event.
+ * @param chunk - The chunk to test.
+ * @returns True if the chunk is a tool output transition type.
+ */
+export const isToolOutputChunk = (chunk: AI.UIMessageChunk): chunk is ToolOutputChunk =>
+  chunk.type === 'tool-output-available' ||
+  chunk.type === 'tool-output-error' ||
+  chunk.type === 'tool-output-denied' ||
+  chunk.type === 'tool-approval-request';
+
+// ---------------------------------------------------------------------------
+// Tool base helper
+// ---------------------------------------------------------------------------
+
+/** Fields shared by all DynamicToolUIPart state variants. */
+interface ToolBaseFields {
+  type: 'dynamic-tool';
+  toolName: string;
+  toolCallId: string;
+  title?: string;
+  providerExecuted?: boolean;
+}
+
+/**
+ * Extract the state-independent base fields for a DynamicToolUIPart.
+ * Works with both chunks (tool-input-start, etc.) and existing parts.
+ * @param source - Any object containing the required tool identity fields.
+ * @param source.toolCallId - The tool call identifier.
+ * @param source.toolName - The tool name.
+ * @param source.title - Optional display title.
+ * @param source.providerExecuted - Whether the provider executed the tool.
+ * @returns Base fields shared across all DynamicToolUIPart state variants.
+ */
+export const toolBase = (source: {
+  toolCallId: string;
+  toolName: string;
+  title?: string;
+  providerExecuted?: boolean;
+}): ToolBaseFields =>
+  stripUndefined({
+    type: 'dynamic-tool' as const,
+    toolCallId: source.toolCallId,
+    toolName: source.toolName,
+    title: source.title,
+    providerExecuted: source.providerExecuted,
+  });
+
+// ---------------------------------------------------------------------------
+// Tool part transition
+// ---------------------------------------------------------------------------
+
+/**
+ * Transition a DynamicToolUIPart to a new state based on a tool output chunk.
+ * Pure function — does not mutate the input part.
+ * @param part - The existing tool part to transition.
+ * @param chunk - The tool output chunk describing the transition.
+ * @returns A new DynamicToolUIPart in the target state.
+ */
+export const transitionToolPart = (part: AI.DynamicToolUIPart, chunk: ToolOutputChunk): AI.DynamicToolUIPart => {
+  const base = toolBase(part);
+
+  switch (chunk.type) {
+    case 'tool-output-available': {
+      return stripUndefined({
+        ...base,
+        state: 'output-available' as const,
+        input: part.input,
+        output: chunk.output,
+        preliminary: chunk.preliminary,
+      });
+    }
+
+    case 'tool-output-error': {
+      return {
+        ...base,
+        state: 'output-error',
+        input: part.input,
+        errorText: chunk.errorText,
+      };
+    }
+
+    case 'tool-output-denied': {
+      return {
+        ...base,
+        state: 'output-denied',
+        input: part.input,
+        approval: { id: '', approved: false },
+      };
+    }
+
+    case 'tool-approval-request': {
+      return {
+        ...base,
+        state: 'approval-requested',
+        input: part.input,
+        approval: { id: chunk.approvalId },
+      };
+    }
+  }
+};

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,7 +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';
+
+// Vercel-shaped helpers
+export { vercelRunOutcome } from './run-end-reason.js';

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

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

package/src/vercel/react/contexts/chat-transport-provider.tsx

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

package/src/vercel/react/index.ts

@@ -1,4 +1,16 @@
-// 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,
+  ClientSessionProvider,
+  useAblyMessages,
+  useClientSession,
+  useCreateView,
+  useTree,
+  useView,
+} from './contexts/chat-transport-provider.js';
+export type { ChatTransportHandle, UseChatTransportOptions } from './use-chat-transport.js';
 export { useChatTransport } from './use-chat-transport.js';
+export type { UseMessageSyncOptions } from './use-message-sync.js';
 export { useMessageSync } from './use-message-sync.js';

package/src/vercel/react/use-chat-transport.ts

@@ -1,60 +1,180 @@
 /**
- * useChatTransport: wraps a core ClientTransport into the ChatTransport
- * shape that Vercel's useChat expects.
+ * useChatTransport: reads a ChatTransport and its underlying ClientSession from
+ * the nearest ChatTransportProvider.
  *
- * Accepts either an existing ClientTransport or options to create one:
- * - From an existing ClientTransport — wraps it directly
- * - From options — creates a ClientTransport with UIMessageCodec and wraps it
+ * The chat transport is created by ChatTransportProvider, which wraps the subtree
+ * with ClientSessionProvider. The Ably Realtime client is read from the
+ * surrounding `<AblyProvider>`. This hook is a thin context reader — it does
+ * not create or manage any session/transport state.
  *
- * Both forms accept an optional second argument for ChatTransportOptions
- * (e.g. prepareSendMessagesRequest for the persistence pattern).
- *
- * The hook does NOT auto-close the transport on unmount. Channel lifecycle is
- * managed by the Ably provider (useChannel). Auto-closing would break React
- * Strict Mode. Call chatTransport.close() explicitly if needed.
+ * Pass `channelName` to look up a specific provider by name. Omit to use the nearest
+ * provider in the tree. Pass `skip: true` to defer (e.g. when auth is not yet resolved)
+ * — returns stubs whose properties throw with a descriptive error.
  */
 
+import * as Ably from 'ably';
 import type * as AI from 'ai';
-import { useRef } from 'react';
+import { useContext } from 'react';
+
+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';
 
-import type { ClientTransport } from '../../core/transport/types.js';
-import type { ChatTransport, ChatTransportOptions } from '../transport/chat-transport.js';
-import { createChatTransport } from '../transport/chat-transport.js';
-import type { VercelClientTransportOptions } from '../transport/index.js';
-import { createClientTransport as createCoreClientTransport } from '../transport/index.js';
+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<VercelInput, AI.UIMessage> {
+    throw new Ably.ErrorInfo('unable to access view; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+  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);
+  },
+  on: () => {
+    throw new Ably.ErrorInfo('unable to subscribe; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+  close: () => {
+    throw new Ably.ErrorInfo('unable to close; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+};
+
+const SKIPPED_CHAT_TRANSPORT: ChatTransport = {
+  sendMessages: (): never => {
+    throw new Ably.ErrorInfo('unable to send messages; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+  reconnectToStream: (): never => {
+    throw new Ably.ErrorInfo('unable to reconnect to stream; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+  close: (): never => {
+    throw new Ably.ErrorInfo('unable to close; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+  get streaming(): never {
+    throw new Ably.ErrorInfo('unable to access streaming; hook is skipped', ErrorCode.InvalidArgument, 400);
+  },
+  onStreamingChange: (): never => {
+    throw new Ably.ErrorInfo(
+      'unable to subscribe to streaming changes; hook is skipped',
+      ErrorCode.InvalidArgument,
+      400,
+    );
+  },
+};
+
+/** Options for {@link useChatTransport}. */
+export interface UseChatTransportOptions {
+  /** Channel name to look up; omit to use the nearest {@link ChatTransportProvider}. */
+  channelName?: string;
+  /** When `true`, return stubs that throw on any access. */
+  skip?: boolean;
+}
 
 /**
- * Type guard: distinguish an existing ClientTransport from options.
- * @param x - Either a transport instance or options object.
- * @returns True if the argument is a ClientTransport instance.
+ * The value returned by {@link useChatTransport}.
+ * Provides both the underlying {@link ClientSession} and the {@link ChatTransport}
+ * adapter for Vercel's useChat hook.
  */
-const isClientTransport = (
-  x: ClientTransport<AI.UIMessageChunk, AI.UIMessage> | VercelClientTransportOptions,
-): x is ClientTransport<AI.UIMessageChunk, AI.UIMessage> => 'send' in x && typeof x.send === 'function';
+export interface ChatTransportHandle {
+  /**
+   * The underlying client session, also available via {@link useClientSession}.
+   * A throwing stub when `skip` is `true`, when no matching {@link ClientSessionProvider}
+   * was found in the tree, or when session construction failed. Check `sessionError` before use.
+   */
+  session: ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>;
+
+  /**
+   * The chat transport adapter for use with Vercel's `useChat` hook.
+   *
+   * A throwing stub when `skip` is `true` or when no matching
+   * {@link ChatTransportProvider} was found in the tree. When a provider is found
+   * but the underlying {@link ClientSession} failed to construct, this is the real
+   * transport and `sessionError` is set instead. Check `chatTransportError` and
+   * `sessionError` before use.
+   */
+  chatTransport: ChatTransport;
+
+  /**
+   * Set when no matching {@link ClientSessionProvider} was found, when session
+   * construction failed, and `skip` is `false`.
+   * `undefined` when the session resolved successfully or when `skip` is `true`.
+   */
+  sessionError?: Ably.ErrorInfo | undefined;
+  /**
+   * Set only when no matching {@link ChatTransportProvider} was found and `skip` is
+   * `false`.
+   * `undefined` when the chat transport resolved successfully (even if session
+   * construction failed — see `sessionError`) or when `skip` is `true`.
+   */
+  chatTransportError?: Ably.ErrorInfo | undefined;
+}
 
 /**
- * Create and memoize a {@link ChatTransport} for Vercel's useChat hook.
+ * Access a {@link ChatTransport} and {@link ClientSession} from the nearest {@link ChatTransportProvider}.
  *
- * Pass an existing `ClientTransport` to wrap it, or pass
- * `VercelClientTransportOptions` to create one internally with UIMessageCodec.
- * @param transportOrOptions - An existing ClientTransport, or options to create one.
- * @param chatOptions - Optional hooks for customizing request construction.
- * @returns A {@link ChatTransport} compatible with Vercel's useChat hook.
+ * When `channelName` is omitted, the innermost `ChatTransportProvider` in the tree is used.
+ * When `skip` is `true`, returns stubs whose every property and method throws
+ * an {@link Ably.ErrorInfo} — safe to hold in state before conditions are ready.
+ * When no provider is found, returns stubs with `chatTransportError` set instead of throwing.
+ * @param props - Options for selecting the chat transport.
+ * @param props.channelName - The channel name passed to the enclosing `ChatTransportProvider`. Omit to use the nearest.
+ * @param props.skip - When `true`, return stubs that throw on any access instead of reading from context.
+ * @returns The `ChatTransportHandle` containing both the chat transport adapter and the underlying client session.
  */
-export const useChatTransport = (
-  transportOrOptions: ClientTransport<AI.UIMessageChunk, AI.UIMessage> | VercelClientTransportOptions,
-  chatOptions?: ChatTransportOptions,
-): ChatTransport => {
-  const chatTransportRef = useRef<ChatTransport | null>(null);
-
-  if (chatTransportRef.current === null) {
-    if (isClientTransport(transportOrOptions)) {
-      chatTransportRef.current = createChatTransport(transportOrOptions, chatOptions);
-    } else {
-      const transport = createCoreClientTransport(transportOrOptions);
-      chatTransportRef.current = createChatTransport(transport, chatOptions);
+export const useChatTransport = ({ channelName, skip }: UseChatTransportOptions = {}): ChatTransportHandle => {
+  const { nearest, providers } = useContext(ChatTransportContext);
+
+  if (skip) {
+    return { session: SKIPPED_CLIENT_SESSION, chatTransport: SKIPPED_CHAT_TRANSPORT };
+  }
+
+  if (channelName !== undefined) {
+    const slot = providers[channelName];
+    if (slot) {
+      return { session: slot.session, chatTransport: slot.chatTransport, sessionError: slot.sessionError };
     }
+    return {
+      session: SKIPPED_CLIENT_SESSION,
+      chatTransport: SKIPPED_CHAT_TRANSPORT,
+      sessionError: new Ably.ErrorInfo(
+        `unable to use client session; no ClientSessionProvider found for channelName "${channelName}"`,
+        ErrorCode.BadRequest,
+        400,
+      ),
+      chatTransportError: new Ably.ErrorInfo(
+        `unable to use chat transport; no ChatTransportProvider found for channelName "${channelName}"`,
+        ErrorCode.BadRequest,
+        400,
+      ),
+    };
+  }
+
+  if (nearest) {
+    return {
+      session: nearest.session,
+      chatTransport: nearest.chatTransport,
+      sessionError: nearest.sessionError,
+    };
   }
 
-  return chatTransportRef.current;
+  return {
+    session: SKIPPED_CLIENT_SESSION,
+    chatTransport: SKIPPED_CHAT_TRANSPORT,
+    sessionError: new Ably.ErrorInfo(
+      'unable to use session; no ClientSessionProvider found in the tree',
+      ErrorCode.BadRequest,
+      400,
+    ),
+    chatTransportError: new Ably.ErrorInfo(
+      'unable to use chat transport; no ChatTransportProvider found in the tree',
+      ErrorCode.BadRequest,
+      400,
+    ),
+  };
 };