@trigger.dev/sdk 0.0.0-prerelease-streamfix-20260909094302 → 0.0.0-prerelease-20260909121655

package/docs/ai-chat/compaction.mdx

@@ -19,11 +19,12 @@ Provide `shouldCompact` to decide when to compact and `summarize` to generate th
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, generateText, stepCountIs } from "ai";
+import { generateText, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 
 export const myChat = chat.agent({
   id: "my-chat",
+  registry,
   compaction: {
     shouldCompact: ({ totalTokens }) => (totalTokens ?? 0) > 80_000,
     summarize: async ({ messages }) => {
@@ -34,9 +35,8 @@ export const myChat = chat.agent({
       return result.text;
     },
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
-      ...chat.toStreamTextOptions({ registry }),
       messages,
       abortSignal: signal,
       stopWhen: stepCountIs(15),
@@ -61,6 +61,12 @@ After each turn completes:
 
 On the next turn, the LLM receives the compact summary instead of the full history — dramatically reducing token usage while preserving context.
 
+The compacted context is durable. The runtime writes it to the [transcript storage](/ai-chat/transcript-storage)'s `state` alongside the messages, so a new run that boots to continue the conversation starts from the summary rather than re-reading the whole transcript and summarising it again. An undo or edit that reaches into the summarised part of the conversation clears the stored summary, and compaction runs again from the edited history when the threshold is next crossed.
+
+<Note>
+  This is Trigger.dev's provider-agnostic compaction. To persist a **provider's own** compaction across turns instead (Anthropic context editing or OpenAI stored responses), and to fall back between providers without re-sending history, see [Native compaction & provider fallback](/ai-chat/patterns/native-compaction).
+</Note>
+
 ## Customizing what gets persisted
 
 By default, compaction only affects model messages — UI messages stay intact so users see the full conversation after a page refresh. You can customize this with `compactUIMessages`:
@@ -91,7 +97,7 @@ export const myChat = chat.agent({
       ...uiMessages.slice(-4), // Keep the last 4 messages
     ],
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
@@ -185,7 +191,7 @@ export const myChat = chat.agent({
       data: { chatId, summary, totalTokens, messageCount },
     });
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
@@ -201,7 +207,7 @@ Define a `compact` action that reuses your existing `summarize` function:
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, generateText, generateId, convertToModelMessages } from "ai";
+import { generateText, generateId, convertToModelMessages } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 
@@ -243,7 +249,7 @@ export const myChat = chat.agent({
     ]);
   },
 
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });

package/docs/ai-chat/custom-agents.mdx

@@ -290,6 +290,29 @@ Read `turn.stopped` to tell a user stop from a full run cancel:
 
 A hand-rolled loop wires this itself with `chat.createStopSignal()` and `chat.cleanupAbortedParts()`. Two things `createSession` handles for you are easy to get wrong there — see the [hand-rolled loop checklist](#hand-rolled-loop-checklist).
 
+### Ending the conversation
+
+`chat.close({ reason })` works in a custom agent exactly as it does in [`chat.agent`](/ai-chat/backend#ending-the-conversation): the session row is closed, further sends are refused with HTTP 409, and no continuation run is scheduled. Call it from anywhere in your loop.
+
+```ts trigger/my-chat.ts
+for await (const turn of session) {
+  const result = streamText({ model, messages: turn.messages, abortSignal: turn.signal });
+
+  // Close BEFORE turn.complete(): that call writes the turn boundary the
+  // browser stops reading at, and it carries the closed state out with it.
+  if (await overBudget(turn.chatId)) {
+    chat.close({ reason: "Monthly budget reached" });
+  }
+
+  await turn.complete(result);
+  if (turn.stopped) break;
+}
+```
+
+The close is performed when your `run()` returns, so it lands whether you `break` out of the loop, return early, or keep iterating. A hand-rolled loop with no iterator at all works the same way, as long as you call `chat.close()` before the `chat.writeTurnComplete()` that ends the turn.
+
+Only `chat.agent` and `chat.customAgent` bind the run to its Session, so `chat.close()` throws in a plain `task()`.
+
 ## Hand-rolled loop with primitives
 
 For full control, skip `createSession` and compose the primitives directly:

package/docs/ai-chat/fast-starts.mdx

@@ -239,11 +239,11 @@ This is an **import-chain** problem, not a runtime one. A "we'll strip the execu
 
     export const myChat = chat.agent({
       id: "my-chat",
-      run: async ({ messages, signal }) =>
+      run: async ({ messages, signal, streamText }) =>
         streamText({
-          ...chat.toStreamTextOptions({ tools: chatTools }),
           model: anthropic("claude-sonnet-4-6"),
           messages,
+          tools: chatTools,
           stopWhen: stepCountIs(10),
           abortSignal: signal,
         }),
@@ -251,7 +251,7 @@ This is an **import-chain** problem, not a runtime one. A "we'll strip the execu
     ```
   </Step>
   <Step title="Build the head-start handler">
-    Call `chat.headStart({ agentId, run })`. It returns a standard Web Fetch handler: `(req: Request) => Promise<Response>`. Inside the `run` callback you call `streamText` yourself and spread `chat.toStreamTextOptions({ tools })` to inherit the SDK-owned wiring (messages, schema-only tools, `stopWhen: stepCountIs(1)`, abort signal). Add your own `model` and `system` on top.
+    Call `chat.headStart({ agentId, run })`. It returns a standard Web Fetch handler: `(req: Request) => Promise<Response>`. The `run` callback receives a `streamText` that already carries the SDK-owned wiring: the converted messages, `stopWhen: stepCountIs(1)` and the abort signal. Pass your schema-only tools to it explicitly, and add your own `model` and `system` on top.
 
     ```ts lib/chat-handler.ts
     import { chat } from "@trigger.dev/sdk/chat-server";
@@ -261,18 +261,23 @@ This is an **import-chain** problem, not a runtime one. A "we'll strip the execu
 
     export const chatHandler = chat.headStart({
       agentId: "my-chat",
-      run: async ({ chat: helper }) =>
+      run: async ({ streamText }) =>
         streamText({
-          ...helper.toStreamTextOptions({ tools: headStartTools }),
           model: anthropic("claude-sonnet-4-6"),
           system: "You are a helpful assistant.",
+          tools: headStartTools,
         }),
     });
     ```
 
-    <Warning>
-      Don't set `stopWhen` here. The spread pins it to `stepCountIs(1)`, and overriding it makes the handler run steps the agent is supposed to own — the handover then splices a stream that has already moved past step 1.
-    </Warning>
+    <Note>
+      That `streamText` is the SDK's, not the one from `ai`. It pins `messages`,
+      `prompt`, `stopWhen: stepCountIs(1)` and `abortSignal`, which the handover depends on:
+      running past step 1 would splice a stream the agent is supposed to own. Setting
+      any of the four at the call site is a type error, and a throw if you get past
+      the types, rather than breaking the handover quietly. `chat.toStreamTextOptions()` is still there if you want to build the
+      options yourself.
+    </Note>
 
     <Tip>
       Use the **same model** on both sides (route handler and `chat.agent`) to avoid a tone or style shift between step 1 and step 2+. Your LLM provider keys stay server-side in your warm process — Trigger.dev never holds them in this design.
@@ -625,27 +630,27 @@ chat.headStart<TTools>({
 export const chatHandler = chat.headStart({
   agentId: "my-chat",
   triggerConfig: { tags: ["org:acme"], queue: "chat", machine: "small-2x" },
-  run: async ({ chat: helper }) =>
-    streamText({ ...helper.toStreamTextOptions({ tools: headStartTools }), model, system }),
+  run: async ({ streamText }) => streamText({ model, system, tools: headStartTools }),
 });
 ```
 
 The `run` callback receives:
 
-- `messages: UIMessage[]` — user messages parsed from the request body.
-- `signal: AbortSignal` — fires when the request closes or the SDK times out the handover.
-- `chat: HeadStartChatHelper<TTools>` — exposes `chat.toStreamTextOptions({ tools })` and a `chat.session` escape hatch for power users.
+- `messages: UIMessage[]`: user messages parsed from the request body.
+- `signal: AbortSignal`: fires when the request closes or the SDK times out the handover.
+- `streamText`: the AI SDK's `streamText` with the keys below already applied. Prefer it.
+- `chat: HeadStartChatHelper<TTools>`: exposes `chat.toStreamTextOptions({ tools })` for building the options by hand, plus a `chat.session` escape hatch for power users.
 
-`chat.toStreamTextOptions({ tools })` returns options to spread into `streamText`. The SDK owns these keys — overriding them will break the protocol:
+The SDK owns these keys. Passing one to the callback's `streamText` is a type error, and a throw behind that; re-setting one after a `chat.toStreamTextOptions()` spread breaks the protocol with no error at all:
 
 | Key | What the SDK sets | Why |
 | --- | --- | --- |
 | `messages` | `convertToModelMessages(uiMessages)` | First-turn user history |
-| `tools` | What you pass | Schema-only tools for step 1 |
-| `stopWhen` | `stepCountIs(1)` | Step 1 only — agent picks up step 2+ |
+| `prompt` | Nothing, and rejects yours | `messages` already carries the history |
+| `stopWhen` | `stepCountIs(1)` | Step 1 only, the agent picks up step 2 onward |
 | `abortSignal` | Combined request + idle timeout | Safe cleanup on disconnect |
 
-You bring `model`, `system`, `providerOptions`, `prepareStep`, anything else `streamText` accepts.
+You bring `model`, `system`, `providerOptions`, `prepareStep`, anything else `streamText` accepts. `tools` is yours too: pass your schema-only set to the callback's `streamText` (or to `chat.toStreamTextOptions({ tools })`), since the SDK cannot know it.
 
 #### The transport option
 
@@ -684,11 +689,11 @@ export async function POST(req: Request) {
     agentId: "my-chat",
     chatId, // session externalId; reuse it on the destination page
     messages, // first-turn user history
-    run: async ({ chat: helper }) =>
+    run: async ({ streamText }) =>
       streamText({
-        ...helper.toStreamTextOptions({ tools: headStartTools }),
         model: anthropic("claude-sonnet-4-6"),
         system: "You are a helpful assistant.",
+        tools: headStartTools,
       }),
   });
 
@@ -735,11 +740,13 @@ chat.startHeadStart<TTools>({
   triggerConfig?: Partial<SessionTriggerConfig>, // tags, queue, machine, …
   apiClient?: ApiClientConfiguration,            // when the agent lives in another project/env
   metadata?: Record<string, unknown>,            // merged into the run payload; never sent to the browser
-}): Promise<{ chatId: string; completion: Promise<void> }>
+}): Promise<{ chatId: string; pendingVersion: boolean; completion: Promise<void> }>
 ```
 
 `completion` resolves once the head start finishes; `await` it or hand it to `waitUntil`. It rejects if the warm step or the dispatch fails.
 
+`pendingVersion` is `true` when the agent run is parked waiting for the deployment carrying the session's [external deployment id](/deployment/version-skew-protection#chat-sessions). Step 1 still runs in your process and still reaches the browser, so pass the flag to the destination page if you want it to say a deploy is in progress rather than appear to stall on step 2.
+
 ### Limitations
 
 - **First turn only.** Step 2+ and turn 2+ run on the trigger side. There's no per-turn "head start every turn" mode — the win comes from amortizing agent boot across the LLM call once.

package/docs/ai-chat/frontend.mdx

@@ -137,6 +137,8 @@ On page load, fetch both the messages and the session state from your database,
 
 Because the underlying Session row outlives individual runs, a chat you were in yesterday resumes against the same chat — even if the original run has long since exited. The transport hydrates from the persisted state and uses `lastEventId` to resubscribe; if the client tries to send a new message and no run is alive, the server triggers a fresh continuation run on the same session before the message is appended.
 
+If you do not keep your own copy of the conversation, load it from the agent's [transcript storage](/ai-chat/transcript-storage#reading-the-transcript) instead: `chat.createLoadTranscriptAction(storage)` on the server and `useLoadTranscript(chatId, action, { transport })` in the browser return the messages and seed the transport's resume cursor, for the default storage and your own alike.
+
 ```tsx app/chat/[chatId]/ChatPage.tsx
 "use client";
 
@@ -442,45 +444,48 @@ function Chat({ chatId, transport }) {
 
 ## Sending actions
 
-Send custom actions (undo, rollback, edit) to the agent via `transport.sendAction()`. Actions wake the agent and fire only `hydrateMessages` (if configured) and `onAction` — they're not turns, so `onTurnStart` / `prepareMessages` / `onBeforeTurnComplete` / `onTurnComplete` and `run()` do not fire.
-
-For optimistic UI, mirror the action's effect on the `useChat` state via `setMessages` while the request is in flight:
+Send custom actions (undo, rollback, edit, regenerate) as `useChat` requests, with the action in the request `body`. The transport recognises `body.action` and sends it as an action rather than a message, and because `useChat` made the request it owns the response: an action that returns `chat.turn()` on the server streams its answer into the message list like any turn, with `status`, `error` and `stop` behaving as for a message. An action that returns nothing completes with no message added.
 
 ```tsx
+import { useChat } from "@ai-sdk/react";
+import { useChatActions, useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
+
 function ChatControls({ chatId }: { chatId: string }) {
   const transport = useTriggerChatTransport({
     task: "my-chat",
     accessToken: ({ chatId }) => mintChatAccessToken(chatId),
-    startSession: ({ chatId, clientData }) =>
-      startChatSession({ chatId, clientData }),
+    startSession: ({ chatId, clientData }) => startChatSession({ chatId, clientData }),
   });
-
-  const { setMessages } = useChat({ transport });
+  const { sendMessage, regenerate, setMessages } = useChat({ id: chatId, transport });
+  const { sendAction } = useChatActions({ sendMessage });
 
   return (
     <div>
       <button
         onClick={() => {
-          void transport.sendAction(chatId, { type: "undo" });
+          // Mirror the server-side edit optimistically; the server does not
+          // push history changes back.
           setMessages((prev) => prev.slice(0, -2));
+          void sendAction({ type: "undo" });
         }}
       >
         Undo last exchange
       </button>
-      <button
-        onClick={() => transport.sendAction(chatId, { type: "rollback", targetMessageId: "msg-5" })}
-      >
-        Rollback to message
+      {/* regenerate() removes the trailing answer locally; the server does the same before its turn */}
+      <button onClick={() => regenerate({ body: { action: { type: "regenerate" } } })}>
+        Regenerate
       </button>
     </div>
   );
 }
 ```
 
-The action payload is validated against the agent's `actionSchema` on the backend — invalid actions are rejected. See [Actions](/ai-chat/actions) for the backend setup.
+`useChatActions` is a two-line convenience over `sendMessage(undefined, { body: { action } })`. Any `useChat` request can carry an action the same way, `regenerate({ body })` included.
+
+The action payload is validated against the agent's `actionSchema` on the backend; invalid actions are rejected. See [Actions](/ai-chat/actions) for the backend setup.
 
 <Note>
-  `sendAction` returns a `ReadableStream<UIMessageChunk>`. For side-effect-only actions (where `onAction` returns `void`), the stream completes immediately with `trigger:turn-complete`. For actions where `onAction` returns a `StreamTextResult`, the stream carries the assistant chunks the same way `sendMessages` does — `useChat` consumes them automatically.
+  `transport.sendAction()` still exists for callers outside `useChat` (server to server, or a custom client). It returns the response as a raw `ReadableStream<UIMessageChunk>` that the caller must read; `useChat` does not consume it.
 </Note>
 
 For server-to-server usage, `AgentChat` has the same method:

package/docs/ai-chat/lifecycle-hooks.mdx

@@ -86,7 +86,7 @@ export const myChat = chat.agent({
 
 Fires once on a continuation boot when the dead predecessor was mid-stream — a partial assistant survives on `session.out`. The runtime reconstructs context automatically via a smart default; this hook is the override path for policies that need something different.
 
-The hook does NOT fire when there's no partial — clean continuations after `chat.endRun()` or `chat.requestUpgrade()`, fresh chats, OOM retries on top of a complete snapshot. Those paths dispatch any in-flight user message as a normal turn on the new run without involving the hook. It also does NOT fire when [`hydrateMessages`](#hydratemessages) is registered (the customer owns persistence).
+The hook does NOT fire when there's no partial — clean continuations after `chat.endRun()` or `chat.requestUpgrade()`, fresh chats, OOM retries on top of a complete snapshot. Those paths dispatch any in-flight user message as a normal turn on the new run without involving the hook. It fires regardless of whether [`hydrateMessages`](#hydratemessages) or a [transcript storage](/ai-chat/transcript-storage) is registered: crash recovery is runtime-owned for every agent.
 
 ```ts
 export const myChat = chat.agent({
@@ -260,6 +260,10 @@ export const myChat = chat.agent({
 
 ## hydrateMessages
 
+<Warning>
+  `hydrateMessages` is deprecated. Give the agent a [transcript storage](/ai-chat/transcript-storage) instead: `loadContext` on the storage decides the model's context, and `save` persists every change, so crash recovery and durable compaction cover it. Existing agents keep working with a one-time warning. Setting `hydrateMessages` together with `storage` is an error.
+</Warning>
+
 Load the full message history from your backend on every turn, replacing the built-in linear accumulator. When set, the hook's return value becomes the accumulated state; the normal accumulation logic (append for submit, replace for regenerate) is skipped entirely.
 
 Use this when the backend should be the source of truth for message history: abuse prevention, branching conversations (DAGs), or rollback/undo support.
@@ -315,7 +319,7 @@ After the hook returns, the runtime overlays the wire's tool-state advances (`ou
 </Note>
 
 <Tip>
-  Registering `hydrateMessages` short-circuits the runtime's [snapshot + replay](/ai-chat/patterns/persistence-and-replay) reconstruction at run boot — your hook is the single source of truth for history, so the runtime skips reading or writing the snapshot entirely. No object storage traffic, no replay cost. The trade-off is that you own persistence end-to-end.
+  Registering `hydrateMessages` turns off the runtime's transcript reads and writes: your hook is the source of truth for history, and the runtime does not read or write its [snapshot](/ai-chat/patterns/persistence-and-replay). Crash recovery still runs. When a new run boots, the dead run's unfinished answer and unacknowledged messages are replayed from the session streams, `onRecoveryBoot` fires, and the hook receives the recovered tail in `previousMessages`. Persisting that tail is yours to do; a [transcript storage](/ai-chat/transcript-storage) does it for you.
 </Tip>
 
 <Note>

package/docs/ai-chat/migrating-from-a-route-handler.mdx

@@ -56,7 +56,7 @@ Then make these changes:
 - Create a `chat.agent` task in `trigger/chat.ts`. Move the existing `streamText` call
   into its `run` function UNCHANGED — same model, same `system`, same `temperature`,
   same `stopWhen`, same provider options. Do not rewrite the prompt or swap the model.
-- Spread `...chat.toStreamTextOptions({ tools })` as the FIRST property of that
+- Take `streamText` from the `run` argument, so the managed options apply to that
   `streamText` call, so the explicit options after it still win.
 - `run` receives `ModelMessage[]` already. Delete the `convertToModelMessages` call.
 - Forward the `signal` from `run` as `abortSignal` so Stop works.
@@ -145,10 +145,9 @@ import { tools } from "@/lib/tools";
 export const myChat = chat.agent({
   id: "my-chat",
   tools,
-  run: async ({ messages, tools, signal }) =>
+  run: async ({ messages, tools, signal, streamText }) =>
     streamText({
-      // Spread first, so every option below still wins.
-      ...chat.toStreamTextOptions({ tools }),
+      tools,
       model: anthropic("claude-sonnet-4-5"),
       system: "You are a helpful assistant.",
       messages,
@@ -163,10 +162,10 @@ Four things changed inside the `streamText` call, and `tools` moved onto the age
 - **`messages` arrives as `ModelMessage[]`.** The runtime converts the frontend's `UIMessage[]` for you, so `convertToModelMessages` is gone.
 - **`abortSignal` comes from `signal` on the payload**, not `req.signal`. It fires on stop and on cancel.
 - **Return the `StreamTextResult`.** It's piped to the frontend automatically — no `toUIMessageStreamResponse`. If `streamText` is buried in a helper, call `await chat.pipe(result)` from anywhere in the task instead and let `run` resolve `void`.
-- **`...chat.toStreamTextOptions()` is spread first.** It wires up the `prepareStep` callback behind [compaction](/ai-chat/compaction), [mid-turn steering](/ai-chat/pending-messages), and [background injection](/ai-chat/background-injection), plus the system prompt set via [`chat.prompt()`](/ai-chat/backend#using-prompts) and telemetry.
+- **`streamText` comes from the `run` argument, not from `ai`.** It carries the `prepareStep` behind [compaction](/ai-chat/compaction), [mid-turn steering](/ai-chat/pending-messages) and [background injection](/ai-chat/background-injection), plus the system prompt set via [`chat.prompt()`](/ai-chat/backend#using-prompts) and telemetry.
 
 <Warning>
-  Omitting `...chat.toStreamTextOptions()` throws no error — compaction, steering, and background injection just silently never run. Spread it first so any explicit override you write after it takes precedence.
+  Importing `streamText` from `ai` instead throws no error: compaction, steering and background injection never run. Spreading `chat.toStreamTextOptions()` into the imported one is the equivalent, and is what a custom agent has to do, since it has no `run` argument. A `chat.headStart` route gets a bound `streamText` of its own.
 </Warning>
 
 There's no `maxDuration` equivalent to set. A turn isn't bounded by a function timeout; a run stays alive across turns and suspends when nothing is happening.
@@ -357,9 +356,9 @@ export const myChat = chat.agent({
       }),
     ]);
   },
-  run: async ({ messages, tools, signal }) =>
+  run: async ({ messages, tools, signal, streamText }) =>
     streamText({
-      ...chat.toStreamTextOptions({ tools }),
+      tools,
       model: anthropic("claude-sonnet-4-5"),
       system: "You are a helpful assistant.",
       messages,
@@ -468,18 +467,21 @@ Head Start brings the route handler back for exactly that first turn. It runs st
 
     export const chatHandler = chat.headStart({
       agentId: "my-chat",
-      run: async ({ chat: helper }) =>
+      run: async ({ streamText }) =>
         streamText({
-          ...helper.toStreamTextOptions({ tools: headStartTools }),
           model: anthropic("claude-sonnet-4-5"),
           system: "You are a helpful assistant.",
+          tools: headStartTools,
         }),
     });
     ```
 
-    <Warning>
-      Spread `toStreamTextOptions()` first and add only your own keys after it. It owns `messages`, `tools`, `abortSignal`, and `stopWhen` — and unlike the agent-side spread, re-setting any of those breaks the handover rather than degrading it. `stopWhen` in particular is pinned to `stepCountIs(1)`: the agent, not the handler, runs step 2 onward.
-    </Warning>
+    <Note>
+      That `streamText` owns `messages`, `prompt`, `abortSignal` and `stopWhen`. Passing one is
+      a type error, and a runtime throw if you get past the types. Unlike the agent side, re-setting one breaks the
+      handover rather than degrading it: `stopWhen` is pinned to `stepCountIs(1)`
+      because the agent, not the handler, runs step 2 onward.
+    </Note>
 
     Your provider keys never leave your server — the first-turn model call runs in your process, so that environment needs whatever the model requires.
   </Step>
@@ -558,7 +560,7 @@ The shape is identical outside Next.js. The agent task and the React component d
 
 **The head-start route dies mid-turn on Vercel.** The handler holds the SSE response open until the agent signals turn-complete, so the function timeout has to cover the whole turn, not just step 1. Set `maxDuration` on that route segment.
 
-**Compaction and steering do nothing.** The `...chat.toStreamTextOptions()` spread is missing, or something before it in the object is overwriting `prepareStep`. Spread it as the first property.
+**Compaction and steering do nothing.** `run` is calling the `streamText` imported from `ai` rather than the one in its argument. Destructure `streamText` from the `run` argument, or spread `chat.toStreamTextOptions()` into the imported one.
 
 **`toModelOutput` works on the first turn, then stops.** Tools are declared only on `streamText`. Declare the same set on `chat.agent({ tools })` too, and read it back off the `run` payload.
 

package/docs/ai-chat/patterns/database-persistence.mdx

@@ -9,6 +9,10 @@ Durable chat runs can span **hours** and **many turns**. You usually want:
 1. **Conversation state** — full **`UIMessage[]`** (or equivalent) keyed by **`chatId`**, so reloads and history views work.
 2. **Live session state** — a **scoped access token** for the session and optionally **`lastEventId`** for stream resume.
 
+<Note>
+  You can persist the conversation state through a [transcript storage](/ai-chat/transcript-storage) on the agent rather than the hook mapping below. Give `chat.agent` a `storage` that writes to your database and the runtime hands it every change (a new message, an undo, a regenerate, a compaction) as it happens, with the resume cursors, and reads it back when a run continues. Your own database is then the transcript. The hook mapping below still works, and it is the way to persist the live session state (the access token) and anything the transcript does not cover.
+</Note>
+
 This page describes a **hook mapping** that works with any database. Adapt table and column names to your stack.
 
 ## Conceptual data model
@@ -167,9 +171,9 @@ chat.agent({
 });
 ```
 
-## Alternative: `hydrateMessages`
+## Alternative: `hydrateMessages` (deprecated)
 
-For apps that need the backend to be the single source of truth for message history — abuse prevention, branching conversations, or rollback support — use [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) instead of relying on the frontend's accumulated state.
+For apps that need the backend to be the single source of truth for message history — abuse prevention, branching conversations, or rollback support — the recommended path is a [transcript storage](/ai-chat/transcript-storage#owning-the-models-context) with `loadContext`. The deprecated [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) hook does the same job without the runtime writing to your store.
 
 With hydration, the hook loads messages from your database on every turn. The frontend's messages are ignored (except for the new user message, which arrives in `incomingMessages`):