ai 7.0.134 → 7.0.135

package/docs/07-reference/02-ai-sdk-ui/51-websocket-chat-transport.mdx

@@ -0,0 +1,393 @@
+---
+title: WebSocketChatTransport
+description: API Reference for the WebSocketChatTransport class.
+---
+
+# `WebSocketChatTransport`
+
+A [`ChatTransport`](/docs/ai-sdk-ui/transport) implementation that sends chat
+requests and receives `UIMessageChunk` streams over one persistent WebSocket
+connection.
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+import { WebSocketChatTransport } from 'ai';
+import { useMemo } from 'react';
+
+export default function Chat() {
+  const transport = useMemo(
+    () => new WebSocketChatTransport({ url: '/api/chat' }),
+    [],
+  );
+
+  const { messages, sendMessage, stop } = useChat({ transport });
+
+  // ... render the chat
+}
+```
+
+## Import
+
+<Snippet text={`import { WebSocketChatTransport } from "ai"`} prompt={false} />
+
+## Constructor
+
+<PropertiesTable
+  content={[
+    {
+      name: 'url',
+      type: 'string',
+      isRequired: true,
+      description:
+        'The WebSocket endpoint. Relative URLs are resolved against the browser location. HTTP and HTTPS URLs are converted to WS and WSS.',
+    },
+    {
+      name: 'protocols',
+      type: 'string | string[]',
+      isOptional: true,
+      description: 'WebSocket subprotocols sent during the handshake.',
+    },
+    {
+      name: 'params',
+      type: 'Resolvable<Record<string, string>>',
+      isOptional: true,
+      description:
+        'Query parameters resolved and appended whenever a new connection is opened.',
+    },
+    {
+      name: 'headers',
+      type: 'Resolvable<Record<string, string> | Headers>',
+      isOptional: true,
+      description:
+        'Headers included inside each application-level send or resume frame. These are not WebSocket handshake headers.',
+    },
+    {
+      name: 'body',
+      type: 'Resolvable<object>',
+      isOptional: true,
+      description:
+        'Additional application data merged with per-request body data and included in send and resume frames.',
+    },
+    {
+      name: 'webSocket',
+      type: 'WebSocketConstructor',
+      isOptional: true,
+      description:
+        'A custom WebSocket constructor. Use this for Node.js WebSocket implementations or tests. Defaults to globalThis.WebSocket.',
+    },
+    {
+      name: 'prepareSendMessagesRequest',
+      type: 'PrepareWebSocketChatTransportSendMessagesRequest',
+      isOptional: true,
+      description:
+        'Transforms the messages, headers, or body before a send frame is transmitted.',
+    },
+    {
+      name: 'prepareReconnectToStreamRequest',
+      type: 'PrepareWebSocketChatTransportReconnectToStreamRequest',
+      isOptional: true,
+      description:
+        'Transforms the headers or body before a resume frame is transmitted.',
+    },
+  ]}
+/>
+
+`headers` supplied to `sendMessage`, `regenerate`, or an automatic tool
+follow-up override transport-level headers with the same lower-cased name.
+Per-request `body` properties override transport-level body properties.
+Preparation callbacks receive the merged values; values they return replace
+the corresponding merged value.
+
+## Methods
+
+### `sendMessages()`
+
+Opens the socket when necessary, sends a `send` frame, and returns the
+correlated `ReadableStream<UIMessageChunk>`. Multiple requests can share the
+same connection and are routed by `requestId`.
+
+### `reconnectToStream()`
+
+Sends a `resume` frame. The promise resolves as follows:
+
+- `start`, the first `chunk`, or `end` resolves to a readable stream.
+- `no-active` resolves to `null`.
+- `error`, cancellation, or a connection failure rejects the promise if no
+  stream has been returned yet.
+
+Servers should send `start` as soon as they confirm that a resumable stream is
+active, then replay the retained response from sequence zero. The transport
+omits `lastSequence` because Chat starts a fresh message parser when resuming:
+text, reasoning, and tool deltas need their preceding chunks. Retain and replay
+the original UI `start` chunk with a stable `messageId` so Chat replaces the
+partial assistant message instead of appending another one. The transport
+rejects gaps and ignores duplicate sequence numbers within each response
+stream, including the replay.
+
+### `close()`
+
+Closes the current socket and errors active streams. A later send or resume
+request opens a new connection.
+
+The code that creates a transport owns its lifecycle. React and Vue `useChat`
+do not close caller-supplied transports during replacement or cleanup, because
+one transport can be shared by multiple chats. Call `close()` after its final
+consumer is gone.
+
+If a directly managed `Chat` instance exclusively owns the transport, call
+`dispose()`:
+
+```ts
+await chat.dispose();
+```
+
+For a shared transport, stop or discard individual chats without disposing
+their shared transport, then call `transport.close()` after all consumers are
+finished.
+
+## Wire Protocol
+
+Each frame is a JSON object with a `type` and a correlated `requestId`.
+
+### Client-to-server frames
+
+| Type     | Purpose                                                                                                                                                 |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `send`   | Starts a new or regenerated turn and includes `id`, `messages`, `trigger`, `messageId`, request `headers`, `body`, and `metadata`.                      |
+| `resume` | Requests the retained response for a chat `id`, with request `headers`, `body`, and `metadata`. `lastSequence` is omitted to request a complete replay. |
+| `abort`  | Cancels the operation identified by `requestId`.                                                                                                        |
+
+Use `WebSocketChatTransportRequest<UI_MESSAGE>`,
+`WebSocketChatTransportSendRequest`, `WebSocketChatTransportResumeRequest`,
+and `WebSocketChatTransportAbortRequest` to type these frames.
+
+### Server-to-client frames
+
+| Type        | Purpose                                                                       |
+| ----------- | ----------------------------------------------------------------------------- |
+| `start`     | Confirms that a resume request has an active stream.                          |
+| `chunk`     | Carries a monotonic `sequence` and one valid `UIMessageChunk` in `chunk`.     |
+| `end`       | Closes the correlated response stream.                                        |
+| `error`     | Errors the correlated stream with the optional `errorText`.                   |
+| `no-active` | Resolves a resume request to `null`; for a send request it closes the stream. |
+
+Use `WebSocketChatTransportResponse` to type server frames.
+
+Responses for unknown or completed request IDs are ignored. Malformed frames,
+unknown response types, and invalid UI message chunks are treated as protocol
+errors: the connection is closed and all active streams are errored.
+
+Validate every untrusted client frame before using its fields:
+
+```ts
+const validated = await safeValidateWebSocketChatTransportRequest({
+  value: parsed.value,
+});
+
+if (!validated.success) {
+  socket.close(1008, 'Invalid frame');
+  return;
+}
+
+const frame = validated.data;
+```
+
+## Server Example
+
+The server owns authentication, authorization, message validation, model
+execution, resumable stream storage, and cancellation. The following Node.js
+outline forwards a `streamText` UI message stream:
+
+```ts
+import { WebSocket, WebSocketServer } from 'ws';
+import {
+  convertToModelMessages,
+  safeValidateWebSocketChatTransportRequest,
+  streamText,
+  toUIMessageStream,
+  validateUIMessages,
+  type UIMessage,
+  type UIMessageChunk,
+  type WebSocketChatTransportResponse,
+} from 'ai';
+import { generateId, safeParseJSON } from '@ai-sdk/provider-utils';
+__PROVIDER_IMPORT__;
+
+const server = new WebSocketServer({ port: 8080 });
+
+type RetainedStream = {
+  abortController: AbortController;
+  chunks: Array<{ sequence: number; chunk: UIMessageChunk }>;
+  subscribers: Map<WebSocket, string>;
+  ended: boolean;
+};
+
+// Scope retained streams to an authenticated user. Use durable storage when
+// reconnects can land in another process.
+const streamsByUser = new Map<string, Map<string, RetainedStream>>();
+
+server.on('connection', (socket, request) => {
+  const userId = authenticateAndValidateOrigin(request);
+  const streams =
+    streamsByUser.get(userId) ?? new Map<string, RetainedStream>();
+  streamsByUser.set(userId, streams);
+
+  socket.on('message', async data => {
+    const parsed = await safeParseJSON({ text: data.toString() });
+    if (!parsed.success) {
+      socket.close(1008, 'Invalid frame');
+      return;
+    }
+
+    const validated =
+      await safeValidateWebSocketChatTransportRequest<UIMessage>({
+        value: parsed.value,
+      });
+    if (!validated.success) {
+      socket.close(1008, 'Invalid frame');
+      return;
+    }
+    const frame = validated.data;
+
+    const send = (response: WebSocketChatTransportResponse) => {
+      socket.send(JSON.stringify(response));
+    };
+
+    if (frame.type === 'abort') {
+      for (const stream of streams.values()) {
+        if (stream.subscribers.get(socket) === frame.requestId) {
+          stream.subscribers.delete(socket);
+          stream.abortController.abort();
+        }
+      }
+      return;
+    }
+
+    if (frame.type === 'resume') {
+      const stream = streams.get(frame.id);
+      if (stream == null) {
+        send({ type: 'no-active', requestId: frame.requestId });
+        return;
+      }
+
+      send({ type: 'start', requestId: frame.requestId });
+      if (!stream.ended) {
+        stream.subscribers.set(socket, frame.requestId);
+      }
+      for (const stored of stream.chunks) {
+        if (stored.sequence > (frame.lastSequence ?? -1)) {
+          send({
+            type: 'chunk',
+            requestId: frame.requestId,
+            ...stored,
+          });
+        }
+      }
+      if (stream.ended) {
+        send({ type: 'end', requestId: frame.requestId });
+      }
+      return;
+    }
+
+    if (streams.get(frame.id)?.ended === false) {
+      send({
+        type: 'error',
+        requestId: frame.requestId,
+        errorText: 'A response is already active for this chat.',
+      });
+      return;
+    }
+
+    const abortController = new AbortController();
+    const stream: RetainedStream = {
+      abortController,
+      chunks: [],
+      subscribers: new Map([[socket, frame.requestId]]),
+      ended: false,
+    };
+    streams.set(frame.id, stream);
+
+    try {
+      const messages = await validateUIMessages({
+        messages: frame.messages,
+      });
+      const result = streamText({
+        model: __MODEL__,
+        messages: await convertToModelMessages(messages),
+        abortSignal: abortController.signal,
+      });
+
+      for await (const chunk of toUIMessageStream({
+        stream: result.stream,
+        originalMessages: messages,
+        generateMessageId: generateId,
+      })) {
+        const stored = { sequence: stream.chunks.length, chunk };
+        stream.chunks.push(stored);
+        for (const [subscriber, requestId] of stream.subscribers) {
+          subscriber.send(
+            JSON.stringify({ type: 'chunk', requestId, ...stored }),
+          );
+        }
+      }
+      stream.ended = true;
+      for (const [subscriber, requestId] of stream.subscribers) {
+        subscriber.send(JSON.stringify({ type: 'end', requestId }));
+      }
+    } catch (error) {
+      // Failed responses cannot resume. Remove the retained entry so a retry
+      // can start a new response and resume requests receive no-active.
+      streams.delete(frame.id);
+      // Log the internal error server-side, but do not expose it to the client.
+      console.error(error);
+      for (const [subscriber, requestId] of stream.subscribers) {
+        subscriber.send(
+          JSON.stringify({
+            type: 'error',
+            requestId,
+            errorText: 'Chat request failed.',
+          }),
+        );
+      }
+    } finally {
+      stream.subscribers.clear();
+    }
+  });
+
+  socket.on('close', () => {
+    for (const stream of streams.values()) {
+      stream.subscribers.delete(socket);
+    }
+  });
+});
+```
+
+This outline keeps completed chunks in memory to make the replay behavior
+clear. Production servers should expire completed streams and store resumable
+state durably when reconnects can reach another process. If response setup or
+streaming throws, the outline removes that response from retained state before
+reporting the error. A later resume returns `no-active`, and a new send can retry
+the chat.
+
+## Authentication and Deployment
+
+- Use WSS in production.
+- Browser WebSockets cannot set arbitrary handshake headers. Prefer secure
+  cookies, short-lived query tokens, or subprotocols.
+- Validate the handshake origin, authorize chat IDs, validate every frame and
+  UI message, limit frame sizes, and rate-limit connections.
+- Do not depend on process memory for reconnection when your deployment can
+  restart or move the connection to another process.
+- The transport does not automatically replay interrupted `send` requests,
+  because replay can duplicate model output or tool side effects.
+
+`WebSocketChatTransport` is separate from the experimental Realtime APIs.
+Realtime transports implement provider realtime sessions; this transport
+carries the provider-independent AI SDK UI message protocol used by `useChat`.
+
+## Client-side Tool Follow-ups
+
+When `sendAutomaticallyWhen` triggers after client-side tool output is added,
+the next turn reuses the same WebSocket. This avoids another HTTP connection,
+but the current `ChatTransport` contract remains turn-based: the tool output is
+not injected into a model generation that is still active.

package/docs/07-reference/02-ai-sdk-ui/index.mdx

@@ -70,6 +70,12 @@ AI SDK UI contains the following hooks:
         'Transform a stream of UIMessageChunk objects into an AsyncIterableStream of UIMessage objects.',
       href: '/docs/reference/ai-sdk-ui/read-ui-message-stream',
     },
+    {
+      title: 'WebSocketChatTransport',
+      description:
+        'Send correlated chat requests and UI message streams over a persistent WebSocket connection.',
+      href: '/docs/reference/ai-sdk-ui/websocket-chat-transport',
+    },
     {
       title: 'experimental_MCPAppRenderer',
       description: 'Render interactive MCP App tool UIs in React.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.134",
+  "version": "7.0.135",
   "type": "module",
   "description": "AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.",
   "license": "Apache-2.0",
@@ -42,20 +42,20 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.108",
-    "@ai-sdk/provider": "4.0.25",
-    "@ai-sdk/provider-utils": "5.0.57"
+    "@ai-sdk/gateway": "4.0.109",
+    "@ai-sdk/provider": "4.0.26",
+    "@ai-sdk/provider-utils": "5.0.58"
   },
   "devDependencies": {
-    "@ai-sdk/amazon-bedrock": "5.0.112",
-    "@ai-sdk/deepseek": "3.0.62",
-    "@ai-sdk/google": "4.0.92",
-    "@ai-sdk/groq": "4.0.58",
-    "@ai-sdk/huggingface": "2.0.66",
-    "@ai-sdk/moonshotai": "3.0.66",
-    "@ai-sdk/openai": "4.0.90",
+    "@ai-sdk/amazon-bedrock": "5.0.113",
+    "@ai-sdk/deepseek": "3.0.63",
+    "@ai-sdk/google": "4.0.93",
+    "@ai-sdk/groq": "4.0.59",
+    "@ai-sdk/huggingface": "2.0.67",
+    "@ai-sdk/moonshotai": "3.0.67",
+    "@ai-sdk/openai": "4.0.91",
     "@ai-sdk/test-server": "2.0.4",
-    "@ai-sdk/xai": "5.0.19",
+    "@ai-sdk/xai": "5.0.20",
     "@edge-runtime/vm": "^5.0.0",
     "@smithy/eventstream-codec": "^4.3.3",
     "@smithy/util-utf8": "^4.3.3",

package/src/agent/default-stop-condition.ts

@@ -0,0 +1,33 @@
+import { logWarnings } from '../logger/log-warnings';
+import type { StopCondition } from '../generate-text/stop-condition';
+
+/**
+ * Stop conditions are only evaluated when the tool loop can otherwise continue,
+ * so logging here avoids warning when a call finishes naturally at the limit.
+ */
+export function createDefaultStopCondition(
+  stepCount: number,
+): StopCondition<any, any> {
+  return ({ steps }) => {
+    if (steps.length !== stepCount) {
+      return false;
+    }
+
+    const { provider, modelId } = steps[steps.length - 1].model;
+    logWarnings({
+      provider,
+      model: modelId,
+      warnings: [
+        {
+          type: 'other',
+          message:
+            `The tool loop stopped because it reached the default stopWhen condition, isStepCount(${stepCount}). ` +
+            'To allow more steps, set stopWhen to isStepCount(...) with a higher limit or provide a custom stop condition. ' +
+            'Learn more: https://ai-sdk.dev/docs/agents/loop-control',
+        },
+      ],
+    });
+
+    return true;
+  };
+}

package/src/agent/tool-loop-agent.ts

@@ -13,7 +13,6 @@ import type {
 } from '../generate-text/generate-text-events';
 import type { GenerateTextResult } from '../generate-text/generate-text-result';
 import type { Output } from '../generate-text/output';
-import { isStepCount } from '../generate-text/stop-condition';
 import { streamText } from '../generate-text/stream-text';
 import type { StreamTextResult } from '../generate-text/stream-text-result';
 import type { Prompt } from '../prompt';
@@ -24,6 +23,7 @@ import type {
   AgentStreamParameters,
 } from './agent';
 import type { ToolLoopAgentSettings } from './tool-loop-agent-settings';
+import { createDefaultStopCondition } from './default-stop-condition';
 
 /**
  * A tool loop agent is an agent that runs tools in a loop. In each step,
@@ -129,7 +129,7 @@ export class ToolLoopAgent<
 
     const baseCallArgs = {
       ...settingsWithoutCallbacks,
-      stopWhen: this.settings.stopWhen ?? isStepCount(20),
+      stopWhen: this.settings.stopWhen ?? createDefaultStopCondition(20),
       ...options,
     };
 

package/src/embed/embed-events.ts

@@ -27,6 +27,9 @@ export type EmbedStartEvent<RUNTIME_CONTEXT extends Context = Context> = {
   /** The value(s) being embedded. A string for embed, an array for embedMany. */
   readonly value: string | Array<string>;
 
+  /** Requested output dimensions, when specified. */
+  readonly dimensions?: number;
+
   /** Maximum number of retries for failed requests. */
   readonly maxRetries: number;
 
@@ -104,6 +107,9 @@ export type EmbeddingModelCallStartEvent = {
 
   /** The values being embedded in this particular model call. */
   readonly values: Array<string>;
+
+  /** Requested output dimensions, when specified. */
+  readonly dimensions?: number;
 };
 
 /**

package/src/embed/embed-many.ts

@@ -20,6 +20,7 @@ import { notify } from '../util/notify';
 import { prepareRetries } from '../util/prepare-retries';
 import { splitArray } from '../util/split-array';
 import type { EmbedEndEvent, EmbedStartEvent } from './embed-events';
+import { validateEmbeddingDimensions } from './validate-embedding-dimensions';
 import type { EmbedManyResult } from './embed-many-result';
 import { VERSION } from '../version';
 
@@ -39,6 +40,8 @@ const originalGenerateCallId = createIdGenerator({
  * @param model - The embedding model to use.
  * @param values - The values that should be embedded.
  *
+ * @param dimensions - Requested output dimensions. Must be a positive integer. Requires provider support.
+ *
  * @param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
  * @param abortSignal - An optional abort signal that can be used to cancel the call.
  * @param headers - Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
@@ -59,6 +62,7 @@ const originalGenerateCallId = createIdGenerator({
 export async function embedMany<RUNTIME_CONTEXT extends Context = Context>({
   model: modelArg,
   values,
+  dimensions,
   maxParallelCalls = Infinity,
   maxRetries: maxRetriesArg,
   abortSignal,
@@ -83,6 +87,13 @@ export async function embedMany<RUNTIME_CONTEXT extends Context = Context>({
    */
   values: Array<string>;
 
+  /**
+   * The requested number of dimensions for the output embeddings.
+   * Must be a positive integer. Support and allowed values depend on the model
+   * and provider implementation.
+   */
+  dimensions?: number;
+
   /**
    * Maximum number of retries per embedding model call. Set to 0 to disable retries.
    *
@@ -168,6 +179,8 @@ export async function embedMany<RUNTIME_CONTEXT extends Context = Context>({
     generateCallId?: () => string;
   };
 }): Promise<EmbedManyResult> {
+  validateEmbeddingDimensions(dimensions);
+
   const model = resolveEmbeddingModel(modelArg);
 
   const { maxRetries, retry } = prepareRetries({
@@ -200,6 +213,7 @@ export async function embedMany<RUNTIME_CONTEXT extends Context = Context>({
     provider: model.provider,
     modelId: model.modelId,
     value: values,
+    dimensions,
     maxRetries,
     headers: headersWithUserAgent,
     providerOptions,
@@ -243,12 +257,14 @@ export async function embedMany<RUNTIME_CONTEXT extends Context = Context>({
                   provider: model.provider,
                   modelId: model.modelId,
                   values,
+                  dimensions,
                 },
                 callbacks: [telemetryDispatcher.onEmbedStart],
               });
 
               const modelResponse = await model.doEmbed({
                 values,
+                dimensions,
                 abortSignal,
                 headers: headersWithUserAgent,
                 providerOptions,
@@ -371,12 +387,14 @@ export async function embedMany<RUNTIME_CONTEXT extends Context = Context>({
                     provider: model.provider,
                     modelId: model.modelId,
                     values: chunk,
+                    dimensions,
                   },
                   callbacks: [telemetryDispatcher.onEmbedStart],
                 });
 
                 const modelResponse = await model.doEmbed({
                   values: chunk,
+                  dimensions,
                   abortSignal,
                   headers: headersWithUserAgent,
                   providerOptions: chunkProviderOptions,

package/src/embed/embed.ts

@@ -15,6 +15,7 @@ import { notify } from '../util/notify';
 import { prepareRetries } from '../util/prepare-retries';
 import { VERSION } from '../version';
 import type { EmbedEndEvent, EmbedStartEvent } from './embed-events';
+import { validateEmbeddingDimensions } from './validate-embedding-dimensions';
 import type { EmbedResult } from './embed-result';
 
 const originalGenerateCallId = createIdGenerator({
@@ -28,6 +29,8 @@ const originalGenerateCallId = createIdGenerator({
  * @param model - The embedding model to use.
  * @param value - The value that should be embedded.
  *
+ * @param dimensions - Requested output dimensions. Must be a positive integer. Requires provider support.
+ *
  * @param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
  * @param abortSignal - An optional abort signal that can be used to cancel the call.
  * @param headers - Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
@@ -44,6 +47,7 @@ const originalGenerateCallId = createIdGenerator({
 export async function embed<RUNTIME_CONTEXT extends Context = Context>({
   model: modelArg,
   value,
+  dimensions,
   providerOptions,
   maxRetries: maxRetriesArg,
   abortSignal,
@@ -67,6 +71,13 @@ export async function embed<RUNTIME_CONTEXT extends Context = Context>({
    */
   value: string;
 
+  /**
+   * The requested number of dimensions for the output embeddings.
+   * Must be a positive integer. Support and allowed values depend on the model
+   * and provider implementation.
+   */
+  dimensions?: number;
+
   /**
    * Maximum number of retries per embedding model call. Set to 0 to disable retries.
    *
@@ -144,6 +155,8 @@ export async function embed<RUNTIME_CONTEXT extends Context = Context>({
     generateCallId?: () => string;
   };
 }): Promise<EmbedResult> {
+  validateEmbeddingDimensions(dimensions);
+
   const model = resolveEmbeddingModel(modelArg);
 
   const { maxRetries, retry } = prepareRetries({
@@ -176,6 +189,7 @@ export async function embed<RUNTIME_CONTEXT extends Context = Context>({
     provider: model.provider,
     modelId: model.modelId,
     value,
+    dimensions,
     maxRetries,
     headers: headersWithUserAgent,
     providerOptions,
@@ -203,12 +217,14 @@ export async function embed<RUNTIME_CONTEXT extends Context = Context>({
                 provider: model.provider,
                 modelId: model.modelId,
                 values: [value],
+                dimensions,
               },
               callbacks: [telemetryDispatcher.onEmbedStart],
             });
 
             const modelResponse = await model.doEmbed({
               values: [value],
+              dimensions,
               abortSignal,
               headers: headersWithUserAgent,
               providerOptions,