ai 6.0.176 → 6.0.177

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # ai
 
+## 6.0.177
+
+### Patch Changes
+
+- Updated dependencies [5c73af8]
+  - @ai-sdk/gateway@3.0.112
+
 ## 6.0.176
 
 ### Patch Changes

package/dist/index.js

@@ -1254,7 +1254,7 @@ function detectMediaType({
 var import_provider_utils3 = require("@ai-sdk/provider-utils");
 
 // src/version.ts
-var VERSION = true ? "6.0.176" : "0.0.0-test";
+var VERSION = true ? "6.0.177" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({

package/dist/index.mjs

@@ -1144,7 +1144,7 @@ import {
 } from "@ai-sdk/provider-utils";
 
 // src/version.ts
-var VERSION = true ? "6.0.176" : "0.0.0-test";
+var VERSION = true ? "6.0.177" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({

package/dist/internal/index.js

@@ -152,7 +152,7 @@ function detectMediaType({
 var import_provider_utils2 = require("@ai-sdk/provider-utils");
 
 // src/version.ts
-var VERSION = true ? "6.0.176" : "0.0.0-test";
+var VERSION = true ? "6.0.177" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({

package/dist/internal/index.mjs

@@ -131,7 +131,7 @@ import {
 } from "@ai-sdk/provider-utils";
 
 // src/version.ts
-var VERSION = true ? "6.0.176" : "0.0.0-test";
+var VERSION = true ? "6.0.177" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({

package/docs/04-ai-sdk-ui/03-chatbot-resume-streams.mdx

@@ -8,10 +8,12 @@ description: Learn how to resume chatbot streams after client disconnects.
 `useChat` supports resuming ongoing streams after page reloads. Use this feature to build applications with long-running generations.
 
 <Note type="warning">
-  Stream resumption is not compatible with abort functionality. Closing a tab or
-  refreshing the page triggers an abort signal that will break the resumption
-  mechanism. Do not use `resume: true` if you need abort functionality in your
-  application. See
+  In a resumable stream setup, client-side aborts are treated as disconnects.
+  Closing a tab, refreshing the page, or calling `stop()` only closes the
+  current HTTP connection and should not cancel the underlying generation. To
+  let users stop generation, add a dedicated stop endpoint that persists the
+  partial response, cancels the active work, and clears the active stream. See
+  [Stop an Active Resumable Stream](#stop-an-active-resumable-stream) and
   [troubleshooting](/docs/troubleshooting/abort-breaks-resumable-streams) for
   more details.
 </Note>
@@ -250,9 +252,148 @@ This lets you:
 - Add query parameters or custom paths
 - Integrate with different backend architectures
 
+## Stop an Active Resumable Stream
+
+`useChat` includes a `stop()` function that aborts the current client request. In a resumable stream setup, that abort is a disconnect signal, not a request to stop generation.
+
+Stream resumption lets a client reconnect to an active stream after the original connection closes. To make that possible, the server keeps the stream running even when no client is actively consuming it. If the user refreshes the page, closes the tab, loses their connection, or navigates away, the client can reconnect later with `resumeStream()`.
+
+Because of this, a client-side abort (e.g. closing the page or refreshing) only closes the current HTTP connection. It is not a request to cancel the underlying work. If your stop button only calls `stop()`, the model request, background job, workflow, or stream writer can continue running, and the client can reconnect to the same active stream.
+
+To support an explicit stop button, create a dedicated stop endpoint. The endpoint should accept the current assistant message from the client, persist that partial response, cancel the work that is producing the stream, and clear the active stream record for the chat.
+
+Stream resumption also needs your application to store a reference from the chat to the stream that can be resumed. This guide calls that reference `activeStreamId`. The resume endpoint uses it to find the stream to reconnect to. The stop endpoint uses the same value to find the work to cancel, and to avoid clearing a newer stream that may have started while the stop request was in flight.
+
+### Client-side: send the current assistant message
+
+The chat setup is the same as the resumable stream setup above. To add stop behavior, send the latest partial assistant message to your stop endpoint before stopping the local chat stream.
+
+When the client knows the active stream ID, include it in the request. This lets the server ignore stale stop requests that arrive after a newer stream has already started.
+
+```tsx filename="app/chat/[chatId]/chat.tsx"
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { type UIMessage } from 'ai';
+
+export function Chat({
+  chatData,
+  resume = false,
+}: {
+  chatData: {
+    id: string;
+    messages: UIMessage[];
+    activeStreamId?: string | null;
+  };
+  resume?: boolean;
+}) {
+  const chat = useChat({
+    id: chatData.id,
+    messages: chatData.messages,
+    resume,
+  });
+
+  const stop = () => {
+    const lastMessage = chat.messages[chat.messages.length - 1];
+    const assistantMessage =
+      lastMessage?.role === 'assistant' ? lastMessage : undefined;
+
+    void fetch(`/api/chat/${chatData.id}/stop`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(
+        assistantMessage || chatData.activeStreamId
+          ? {
+              assistantMessage,
+              activeStreamId: chatData.activeStreamId,
+            }
+          : {},
+      ),
+    });
+
+    void chat.stop();
+  };
+
+  return <button onClick={stop}>Stop</button>;
+}
+```
+
+The stop request tells your server to cancel the active work. `chat.stop()` stops the local client from reading more chunks.
+
+### Server-side: stop the active work and clear the stream
+
+The stop endpoint should:
+
+1. Load the chat and read its `activeStreamId`
+2. Persist the assistant snapshot if one was sent
+3. Cancel the work that is producing the stream
+4. Clear `activeStreamId` only if it still points to the same stream
+
+```ts filename="app/api/chat/[id]/stop/route.ts"
+import { readChat, saveChat } from '@util/chat-store';
+import { type UIMessage } from 'ai';
+
+type StopRequest = {
+  activeStreamId?: string | null;
+  assistantMessage?: UIMessage;
+};
+
+export async function POST(
+  req: Request,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const { id } = await params;
+  const chat = await readChat(id);
+
+  if (chat.activeStreamId == null) {
+    return Response.json({ success: true });
+  }
+
+  const activeStreamId = chat.activeStreamId;
+  const body = (await req.json().catch(() => ({}))) as StopRequest;
+
+  if (
+    body.activeStreamId != null &&
+    body.activeStreamId !== activeStreamId
+  ) {
+    return Response.json({ success: true });
+  }
+
+  if (body.assistantMessage) {
+    await saveAssistantSnapshot({
+      chatId: id,
+      message: body.assistantMessage,
+    });
+  }
+
+  await markStreamAsStopped(activeStreamId);
+  await cancelActiveWork(activeStreamId);
+
+  const latestChat = await readChat(id);
+  if (latestChat.activeStreamId === activeStreamId) {
+    await saveChat({ id, activeStreamId: null });
+  }
+
+  return Response.json({ success: true });
+}
+```
+
+`markStreamAsStopped` and `cancelActiveWork` depend on your backend. In a Redis-backed resumable stream setup, you might close the stored stream and abort the model request that is writing to it. In a workflow setup, you might cancel the workflow run that owns the stream. In a job queue setup, you might cancel the job or write a cancellation flag that the job checks.
+
+The `activeStreamId` can identify replay state, producer state, or both. If those are separate in your system, store enough information with the chat to cancel the producer that writes to the stream.
+
+Persist the assistant snapshot as an insert or merge. Avoid overwriting a newer server-written message with an older client snapshot.
+
+### Keep navigation separate from stop
+
+Do not call the stop endpoint from route cleanup code. Route cleanup is a disconnect, not an explicit stop. The active stream should remain resumable when the user refreshes the page or navigates away.
+
+Only call the stop endpoint for an explicit user action, such as pressing a stop button.
+
+After a user stops a stream, avoid automatic reconnect attempts for that chat until the user sends another message or explicitly retries. Otherwise the client can reconnect before cancellation has finished.
+
 ## Important considerations
 
-- **Incompatibility with abort**: Stream resumption is not compatible with abort functionality. Closing a tab or refreshing the page triggers an abort signal that will break the resumption mechanism. Do not use `resume: true` if you need abort functionality in your application
 - **Stream expiration**: Streams in Redis expire after a set time (configurable in the `resumable-stream` package)
 - **Multiple clients**: Multiple clients can connect to the same stream simultaneously
 - **Error handling**: When no active stream exists, the GET handler returns a 204 (No Content) status code

package/docs/09-troubleshooting/15-abort-breaks-resumable-streams.mdx

@@ -1,46 +1,60 @@
 ---
-title: Abort breaks resumable streams
-description: Troubleshooting stream resumption failures when using abort functionality
+title: Abort and resumable streams
+description: Troubleshooting abort and stop behavior with resumable streams
 ---
 
-# Abort breaks resumable streams
+# Abort and resumable streams
 
 ## Issue
 
-When using `useChat` with `resume: true` for stream resumption, the abort functionality breaks. Closing a tab, refreshing the page, or calling the `stop()` function will trigger an abort signal that interferes with the resumption mechanism, preventing streams from being properly resumed.
+When using `useChat` with `resume: true` for stream resumption, client-side aborts are treated as disconnects. Closing a tab, refreshing the page, navigating away, or calling `stop()` closes the current HTTP connection, but it should not cancel the underlying generation.
+
+If your application passes the request abort signal through to the model call, disconnects can cancel the work that stream resumption expects to keep running. If your stop button only calls `stop()`, the server-side generation can continue and the client may reconnect to the same active stream.
 
 ```tsx
-// This configuration will cause conflicts
 const { messages, stop } = useChat({
   id: chatId,
   resume: true, // Stream resumption enabled
 });
 
-// Closing the tab will trigger abort and stop resumption
+// stop() only aborts the current client request.
+// It is not a server-side cancellation request.
 ```
 
 ## Background
 
-When a page is closed or refreshed, the browser automatically sends an abort signal, which breaks the resumption flow.
+Stream resumption lets the client reconnect to an active stream after the original connection closes. To support that, the server needs to keep the stream producer running even when no client is currently connected.
+
+This means route cleanup, page unloads, and network disconnects should be handled as resumable disconnects. Explicit user cancellation needs a separate server-side signal that cancels the active producer and clears the stored active stream reference.
 
-## Current limitations
+## Solution
 
-We're aware of this incompatibility and are exploring solutions. **In the meantime, please choose either stream resumption or abort functionality based on your application's requirements**, but not both.
+Use `resume: true` for reconnecting after disconnects, and add a dedicated stop endpoint for explicit user cancellation.
 
-### Option 1: Use stream resumption without abort
+The stop endpoint should:
 
-If you need to support long-running generations that persist across page reloads:
+1. Load the chat and read its active stream ID
+2. Persist the latest partial assistant message if the client sends one
+3. Cancel the work that is producing the stream
+4. Clear the active stream reference only if it still points to the same stream
+
+On the client, call your stop endpoint before stopping the local chat stream:
 
 ```tsx
-const { messages, sendMessage } = useChat({
+const chat = useChat({
   id: chatId,
   resume: true,
 });
+
+async function stopStream() {
+  await fetch(`/api/chat/${chatId}/stop`, { method: 'POST' });
+  chat.stop();
+}
 ```
 
-### Option 2: Use abort without stream resumption
+Keep navigation separate from stop behavior. Do not call the stop endpoint from route cleanup code, page unload handlers, or component unmount cleanup. Those events are disconnects that should remain resumable.
 
-If you need to allow users to stop streams manually:
+If you do not need stream resumption and only want client-side cancellation, disable `resume` and use `stop()` directly:
 
 ```tsx
 const { messages, sendMessage, stop } = useChat({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "6.0.176",
+  "version": "6.0.177",
   "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",
   "sideEffects": false,
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
-    "@ai-sdk/gateway": "3.0.111",
+    "@ai-sdk/gateway": "3.0.112",
     "@ai-sdk/provider": "3.0.10",
     "@ai-sdk/provider-utils": "4.0.27"
   },