@trigger.dev/sdk 4.5.16 → 4.6.0

package/docs/ai-chat/client-protocol.mdx

@@ -54,7 +54,7 @@ A single-shell walk-through of the whole protocol — copy, fill in `BASE_URL` /
 
 ```bash
 BASE_URL="https://api.trigger.dev"   # or your local webapp
-SECRET_KEY="tr_dev_..."              # secret API key for the env
+SECRET_KEY="tr_dev_sk_..."              # secret API key for the env
 TASK_ID="ai-chat"                    # your chat.agent task id
 CHAT_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
 
@@ -210,6 +210,7 @@ Pick `"preload"` when the UI has rendered but the user hasn't typed (warms the a
 | `triggerConfig.maxAttempts` | `number` | Per-run retry cap (1–10). |
 | `triggerConfig.maxDuration` | `number` | Per-run wall-clock cap, seconds. |
 | `triggerConfig.lockToVersion` | `string` | Pin every run to a specific worker version. |
+| `triggerConfig.externalDeploymentId` | `string \| null` | Pin every run to the deployment carrying this [external deployment id](/deployment/version-skew-protection#chat-sessions). Discovered from the environment when omitted; `null` opts the chat out. |
 | `triggerConfig.region` | `string` | Region preference. |
 | `triggerConfig.idleTimeoutInSeconds` | `number` | Surfaced to the agent through the wire payload (1–3600). |
 
@@ -266,7 +267,7 @@ x-trigger-jwt-claims: {"sub":"...","scopes":["read:runs:run_abc123","write:input
 Re-calling `POST /api/v1/sessions` with the same `(taskIdentifier, externalId)` pair is **idempotent for the lifetime of the session**:
 
 - If the session is still alive: returns the existing row with `isCached: true`, `runId` unchanged, and a **fresh** 60-minute `publicAccessToken`. No duplicate run is triggered. (Idle/exited runs are different — see [Continuations](#continuations).)
-- If the session has been closed (`POST /api/v1/sessions/{id}/close`): returns **HTTP 409**. Closed is one-way; reuse a different `externalId` to start a new conversation.
+- If the session has been closed (`POST /api/v1/sessions/{id}/close`, or `chat.close()` from inside the agent): returns **HTTP 409**. Closed is one-way; reuse a different `externalId` to start a new conversation.
 - Any tags / metadata / expiresAt / triggerConfig fields you send on the cached path are written through to the row, so you can update e.g. `triggerConfig.basePayload.metadata` mid-conversation. The new fields apply to **future** runs (continuations); the currently-live run keeps its original config.
 
 <Warning>
@@ -693,7 +694,7 @@ The body is a JSON-serialized [`ChatInputChunk`](#chatinputchunk), a tagged unio
 | --- | --- |
 | `401` | Missing or invalid `Authorization` header. |
 | `403` | Token doesn't carry `write:sessions:{externalId}`. |
-| `409` | The session is closed — `{ "ok": false, "error": "Cannot append to a closed session" }`. |
+| `409` | The session is closed: `{ "ok": false, "error": "Cannot append to a closed session", "code": "session_closed", "closedReason": "<reason or null>" }`. Key on `code`, not the message. Terminal: do not retry, and stop reconnecting to `.out`. |
 | `413` | Body exceeds 1 MiB **or** the wrapped record would exceed S2's ~1 MiB per-record metered ceiling. A normal `kind: "message"` payload is a few KB; if you hit this you're shipping more than one message per record or pushing a single tool output that's itself oversized. Carries CORS headers so browser fetches can read the status. |
 | `500` | Transient backend failure on the durable stream. Safe to retry — appends are idempotent on `(externalId, X-Part-Id)` if you set the optional `X-Part-Id` request header (the built-in clients set it from a UUID). |
 
@@ -832,7 +833,7 @@ Custom actions (undo, rollback, edit) ride on the same `.in` channel using `kind
 }
 ```
 
-For managed `chat.agent()` tasks, actions wake the agent from suspension (same as messages) and fire the `onAction` hook — they are not turns, so `run()` and turn lifecycle hooks do not fire. If `onAction` returns a `StreamTextResult`, the response is auto-piped to the frontend (but still no `run()` or `onTurnComplete`). The `action` payload is validated against the agent's `actionSchema`. If the agent didn't register an `actionSchema` (or your `action` payload doesn't match it), validation fails the same way `metadata` does — `.in/append` returns `200 OK`, but the run trace shows `chat turn N [ERROR]` and the wire emits a `turn-complete` control record with no other chunks. See [Actions](/ai-chat/actions) for the agent-side schema setup.
+For managed `chat.agent()` tasks, actions wake the agent from suspension (same as messages) and fire the `onAction` hook — they are not turns, so `run()` and turn lifecycle hooks do not fire. If `onAction` returns `chat.turn()`, a turn runs on the edited history and its chunks follow on `.out` like any turn's.
 
 Raw `chat.customAgent()` tasks receive `action` as `unknown` and must validate it in their own loop.
 

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/how-it-works.mdx

@@ -90,7 +90,7 @@ Here is a typical cold turn — user opens the page, types "What's the weather?"
     Immediately after writing the new turn-complete marker, the agent issues an S2 trim command targeting the *previous* turn-complete's sequence number. This bounds the stream's storage to roughly one turn of chunks plus the latest control record.
   </Step>
   <Step title="Task: fires onTurnComplete, writes snapshot to S3">
-    `onTurnComplete` runs (your hook for persistence). Then the agent writes `ChatSnapshotV1` — `{ version: 1, messages, lastOutEventId, lastOutTimestamp }` — to S3 at `sessions/:chatId/snapshot.json`. This write is awaited, not fire-and-forget, so the next run is guaranteed to find it.
+    `onTurnComplete` runs (your hook for persistence). Then the agent writes the transcript to S3 at `sessions/:chatId/snapshot.json`: a header line carrying the stream cursors and the runtime's own state, one line per message, and an index of the messages at the end so a page of history can be read without downloading the whole conversation. Once [compaction](/ai-chat/compaction) has run, only the most recent messages are kept, so the file stops growing with the conversation. If you need the full history, keep your own [transcript storage](/ai-chat/transcript-storage). This write is awaited, not fire-and-forget, so the next run is guaranteed to find it.
   </Step>
   <Step title="Task: goes idle, then suspends">
     The agent re-enters the waitpoint on `.in`. After `idleTimeoutInSeconds` of nothing arriving, `onChatSuspend` fires and the engine snapshots the run. Compute is freed.

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.