ai 7.0.134 → 7.0.136

package/docs/07-reference/01-ai-sdk-core/24-mcp-events.mdx

@@ -99,9 +99,11 @@ for the definition fields. Pagination is explicit; this method does not fetch al
 ## Managed Subscriptions
 
 Configure `experimental_events: { adapter }` to delegate subscription lifecycle
-operations to a backend. The adapter implements `Experimental_MCPEventsAdapter`
-from `@ai-sdk/mcp`; it is bound to the authorized account and destination by your
-application or integration package.
+operations to a backend. The `adapter` configuration requires an
+`Experimental_MCPEventAdapter` from `@ai-sdk/mcp`. Its
+`createAdapter({ transport })` method returns `Experimental_MCPEventOperations` bound
+to the authorized account, endpoint and destination by your application or
+integration package.
 
 ```ts
 import { createMCPClient } from '@ai-sdk/mcp';
@@ -143,7 +145,123 @@ try {
 Use the same authorized account for discovery and subscription management.
 Never derive account identity, destination or authorization from model arguments.
 
-### Adapter Contract
+### Using an Adapter Helper
+
+A backend SDK or application helper can return `Experimental_MCPEventAdapter`
+directly. Pass the helper's result as `adapter`; you do not need another object
+wrapper or an inline `createAdapter` callback:
+
+```ts
+import { createMCPClient } from '@ai-sdk/mcp';
+import { createBackendEventsAdapter } from './my-events-adapter';
+
+const client = await createMCPClient({
+  transport: { type: 'http', url: 'https://service.example/mcp' },
+  experimental_events: {
+    adapter: createBackendEventsAdapter({
+      accountId: authenticatedUser.id,
+      destination: { path: '/hooks' },
+    }),
+  },
+});
+```
+
+The helper holds the authorized account and delivery configuration. AI SDK supplies
+the transport type and URL to its `createAdapter` method internally, so the application
+configures that URL only once. When a backend SDK exports this helper, import it
+from that SDK instead of an application module. Use the same authorized account
+for the MCP transport and the backend's subscription operations.
+
+### Implementing an Adapter Helper
+
+Backend integration authors implement `createAdapter` inside their helper:
+
+```ts filename="my-events-adapter.ts"
+import type { Experimental_MCPEventAdapter } from '@ai-sdk/mcp';
+import { createBackendEventOperations } from './my-events-backend';
+
+type BackendEventsConfig = {
+  accountId: string;
+  destination: { path: string };
+  mcpUrl?: string;
+};
+
+export function createBackendEventsAdapter(
+  config: BackendEventsConfig,
+): Experimental_MCPEventAdapter {
+  return {
+    createAdapter({ transport }) {
+      return createBackendEventOperations({
+        ...config,
+        mcpUrl:
+          config.mcpUrl ??
+          (transport.type === 'custom' ? undefined : transport.url),
+      });
+    },
+  };
+}
+```
+
+These helpers and `BackendEventsConfig` are illustrative application or backend
+SDK code, not AI SDK exports. `createBackendEventOperations` returns
+`Experimental_MCPEventOperations` bound to the authorized account, endpoint
+and destination. The helper above lets an explicit `mcpUrl` override the transport
+URL for backend operations; it does not change the MCP client's transport or
+catalog discovery. The backend still authorizes the selected endpoint.
+
+The AI SDK adapter contract is:
+
+```ts
+interface MCPEventAdapter {
+  createAdapter(context: {
+    transport: { type: 'http' | 'sse'; url: string } | { type: 'custom' };
+  }): MCPEventOperations;
+}
+```
+
+The interface is exported as `Experimental_MCPEventAdapter`. The client
+calls `createAdapter` once, before starting the transport, and uses the returned
+operations for managed subscriptions. The return value must be an object with
+callable `subscribe`, `getSubscription`, `listSubscriptions`, and `unsubscribe`
+methods. Nullish values, missing or non-callable methods, and Promise/thenable
+results reject `createMCPClient` with `MCPClientError` before the transport starts.
+Errors thrown by `createAdapter` also reject initialization without starting the
+transport. Bound operations are no longer accepted directly in
+`experimental_events.adapter`. To migrate existing subscription operations, wrap them explicitly:
+
+```ts
+experimental_events: {
+  adapter: {
+    createAdapter: () => existingOperations,
+  },
+}
+```
+
+Only reuse bound operations when their account, endpoint and destination are correct
+for every client using them. The former subscription operations interface is now
+exported as `Experimental_MCPEventOperations`; `Experimental_MCPEventAdapter`
+names the configured integration with `createAdapter`.
+
+For HTTP and SSE transport configurations, the context contains a fresh
+`transport: { type, url }` object. `url` is the configured string, including its
+path and query, not a resolved redirect target. Custom `MCPTransport` instances
+receive `transport: { type: 'custom' }`, with no `url` property; arbitrary
+properties on the instance are not inspected.
+
+This is a description of the transport, not the full configuration or live
+instance. Headers, auth providers, fetch functions, session callbacks and
+`start`/`send`/`close` methods are not passed to the adapter. The `transport`
+grouping leaves room for other client context without mixing it with transport
+metadata. No negotiated protocol version is supplied before initialization.
+
+Return separately bound operations for each client instead of mutating shared
+endpoint state. Adapters may prefer their own explicit endpoint override or
+resolve a configured endpoint when `transport.type` is `'custom'`. That policy belongs to
+the adapter; it does not change the client's transport or catalog discovery.
+The managed backend must still authorize an endpoint before sending credentials
+there. Receiving the transport URL does not grant that authorization.
+
+### Managed Operations Contract
 
 ```ts
 import type { JSONObject } from '@ai-sdk/provider';
@@ -184,7 +302,7 @@ These types are exported as `Experimental_ManagedSubscription` and
 a positive `ttlMs`, an ISO deadline in `expiresAt`, or `expiresAt: null` to
 monitor until stopped. The backend validates these values and enforces its limits.
 
-`Experimental_MCPEventsAdapter` has four operations:
+`Experimental_MCPEventOperations` has four operations:
 
 | Operation           | Input                                             | Result                             |
 | ------------------- | ------------------------------------------------- | ---------------------------------- |

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.136",
   "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.110",
+    "@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;
 };
 
 /**