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

package/docs/ai-chat/background-injection.mdx

@@ -1,14 +1,14 @@
 ---
 title: "Background injection"
 sidebarTitle: "Background injection"
-description: "Inject context from background work into the agent's conversation: self-review, RAG augmentation, or any async analysis."
+description: "Inject context from background work into the agent's conversation — self-review, RAG augmentation, or any async analysis."
 ---
 
 ## Overview
 
 `chat.inject()` queues model messages for injection into the conversation. Messages are picked up at the start of the next turn or at the next `prepareStep` boundary (between tool-call steps).
 
-This is the backend counterpart to [pending messages](/ai-chat/pending-messages). Pending messages come from the user via the frontend, while `chat.inject()` comes from your task code.
+This is the backend counterpart to [pending messages](/ai-chat/pending-messages) — pending messages come from the user via the frontend, while `chat.inject()` comes from your task code.
 
 ## Basic usage
 
@@ -33,9 +33,8 @@ The most powerful pattern combines `chat.defer()` (background work) with `chat.i
 ```ts
 export const myChat = chat.agent({
   id: "my-chat",
-  registry,
   onTurnComplete: async ({ messages }) => {
-    // Kick off background analysis, doesn't block the turn
+    // Kick off background analysis — doesn't block the turn
     chat.defer(
       (async () => {
         const analysis = await analyzeConversation(messages);
@@ -48,8 +47,9 @@ export const myChat = chat.agent({
       })()
     );
   },
-  run: async ({ messages, signal, streamText }) => {
+  run: async ({ messages, signal }) => {
     return streamText({
+      ...chat.toStreamTextOptions({ registry }),
       messages,
       abortSignal: signal,
       stopWhen: stepCountIs(15),
@@ -77,7 +77,7 @@ A cheap model reviews the agent's response after each turn and injects coaching
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
 import { prompts } from "@trigger.dev/sdk";
-import { generateObject, createProviderRegistry, stepCountIs } from "ai";
+import { streamText, generateObject, createProviderRegistry, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 
@@ -98,7 +98,6 @@ Be concise. Only flag issues worth fixing.`,
 
 export const myChat = chat.agent({
   id: "my-chat",
-  registry,
   onTurnComplete: async ({ messages }) => {
     chat.defer(
       (async () => {
@@ -140,8 +139,9 @@ export const myChat = chat.agent({
       })()
     );
   },
-  run: async ({ messages, signal, streamText }) => {
+  run: async ({ messages, signal }) => {
     return streamText({
+      ...chat.toStreamTextOptions({ registry }),
       messages,
       abortSignal: signal,
       stopWhen: stepCountIs(15),
@@ -150,7 +150,7 @@ export const myChat = chat.agent({
 });
 ```
 
-The self-review runs on `claude-haiku-4-5` (fast, cheap) in the background. If the user sends another message before it completes, the coaching is still injected, because `chat.inject()` persists across the idle wait.
+The self-review runs on `claude-haiku-4-5` (fast, cheap) in the background. If the user sends another message before it completes, the coaching is still injected — `chat.inject()` persists across the idle wait.
 
 ## Other use cases
 
@@ -161,25 +161,25 @@ The self-review runs on `claude-haiku-4-5` (fast, cheap) in the background. If t
 
 ## `chat.defer` standalone
 
-`chat.defer()` is also useful on its own, without `chat.inject()`. Any work whose timing has no resume implication (analytics, audit logs, search-index writes, cache warming) can run in parallel with streaming instead of in the critical path. All deferred promises are awaited (with a 5s timeout) before `onTurnComplete` fires.
+`chat.defer()` is also useful on its own, without `chat.inject()`. Any work whose timing has no resume implication — analytics, audit logs, search-index writes, cache warming — can run in parallel with streaming instead of in the critical path. All deferred promises are awaited (with a 5s timeout) before `onTurnComplete` fires.
 
 ```ts
 export const myChat = chat.agent({
   id: "my-chat",
   onTurnStart: async ({ chatId, runId }) => {
-    // Analytics: fire-and-forget, irrelevant to resume.
+    // Analytics — fire-and-forget, irrelevant to resume.
     chat.defer(analytics.track("turn_started", { chatId, runId }));
   },
-  run: async ({ messages, signal, streamText }) => {
+  run: async ({ messages, signal }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
 ```
 
-`chat.defer()` can be called from anywhere during a turn: hooks, `run()`, or nested helpers. All deferred promises are collected and awaited together before `onTurnComplete`.
+`chat.defer()` can be called from anywhere during a turn — hooks, `run()`, or nested helpers. All deferred promises are collected and awaited together before `onTurnComplete`.
 
 <Warning>
-**Don't use `chat.defer()` for the message-history write in `onTurnStart`.** That write must land *before* the model starts streaming, otherwise a mid-stream page refresh will read `[]` from your DB and lose the user's message from the rendered conversation. See [Database persistence: `onTurnStart`](/ai-chat/patterns/database-persistence#onturnstart). Reserve `chat.defer` for writes whose timing has no resume implication.
+**Don't use `chat.defer()` for the message-history write in `onTurnStart`.** That write must land *before* the model starts streaming, otherwise a mid-stream page refresh will read `[]` from your DB and lose the user's message from the rendered conversation. See [Database persistence — `onTurnStart`](/ai-chat/patterns/database-persistence#onturnstart). Reserve `chat.defer` for writes whose timing has no resume implication.
 </Warning>
 
 ## How it differs from pending messages
@@ -189,57 +189,9 @@ export const myChat = chat.agent({
 | **Source** | Backend task code | Frontend user input |
 | **Triggered by** | Your code (e.g. `onTurnComplete` + `chat.defer()`) | User sending a message during streaming |
 | **Injection point** | Start of next turn, or next `prepareStep` boundary | Next `prepareStep` boundary only |
-| **Message role** | Any. `system` becomes an instruction, others join the conversation (see below) | Typically `user` |
+| **Message role** | Any (`system`, `user`, `assistant`) | Typically `user` |
 | **Frontend visibility** | Not visible unless you write custom `data-*` chunks | Visible via `usePendingMessages` hook |
 
-## Two lanes: trusted and untrusted
-
-The role you inject with decides more than position. It decides whether the model
-treats the content as trustworthy.
-
-**`role: "system"` goes to the instructions lane.** The block is appended to the
-system instructions for subsequent inference calls, so it carries the same standing
-as your system prompt. This is the lane for context the agent should believe:
-entitlements, plan changes, operational notices.
-
-It has to work this way. On AI SDK 7 a system message inside `messages` is rejected
-for every provider. `standardizePrompt` throws before any provider is called, and
-its own advice is to use the instructions option, so the injected block goes there
-rather than into the transcript.
-
-<Warning>
-  The instructions lane is delivered by `chat.toStreamTextOptions()`, because that
-  is the only place the SDK can set `streamText`'s instructions for you. If your
-  `run()` calls `streamText({ model, messages, abortSignal })` without spreading
-  `chat.toStreamTextOptions()`, a `role: "system"` injection never reaches the
-  model. The conversational lane has no such requirement: it arrives through
-  `messages` either way.
-</Warning>
-
-- An injection applies to the next turn only. A block injected in `onTurnComplete`
-  shapes the following turn and is cleared after it, so it is not repeated on every
-  turn from then on. Within that turn it is consumed once rather than once per read,
-  so a `run()` that builds options more than once sees the same instructions in
-  every build.
-- The injected text is merged into a single instruction rather than added as a
-  second block, because AI SDK 5 rejects an array of system blocks while accepting
-  one structured block. Merging changes the cached prefix, so a cached system prompt
-  gets no cache hit for as long as an injection is live. If you rely on prompt
-  caching, inject sparingly and prefer facts that go stale, so the injection clears.
-
-**Any other role joins the conversation, and is untrusted by construction.** A
-message injected as `user` is indistinguishable from something the user typed, and a
-well-aligned model treats it accordingly, and may say so and re-derive the answer
-from tools instead of taking it at face value:
-
-> "that text arrived embedded in your message, not from a tool I called, so I
-> verified it myself rather than trusting it"
-
-That is correct behaviour, not a bug. So inject **checkable facts** in the
-conversational lane and put **directives** in the instructions lane. A conclusion
-injected as a user message is the worst of both: the model neither trusts it nor
-ignores it, and may contradict it in front of the user.
-
 ## API reference
 
 ### chat.inject()
@@ -248,9 +200,7 @@ ignores it, and may contradict it in front of the user.
 chat.inject(messages: ModelMessage[]): void
 ```
 
-Queue model messages for injection at the next opportunity. Messages persist across the idle wait between turns, and are not reset when a new turn starts.
-
-Lifetime: a conversational message (`role: "user"` or `"assistant"`) becomes part of the model's context from the next turn onward, for the rest of the conversation. It is written to the [transcript storage](/ai-chat/transcript-storage)'s `state`, anchored to the message it followed, so it survives a continuation run and comes back in the same place. It does not appear in the UI transcript. A history edit that rebuilds the context drops it. This holds however the message reached the model: drained before `run()` or at a step boundary inside a multi-step turn. A message that is still queued when the run ends (injected from the last `onTurnComplete` before an exit, for example) is carried in the storage's `state` too and is queued again when the next run boots, so it reaches the next turn. A `role: "system"` message is appended to the instructions for the next turn only and is consumed once. Injecting the same notice every turn adds a copy every turn; dedupe on your side.
+Queue model messages for injection at the next opportunity. Messages persist across the idle wait between turns — they are not reset when a new turn starts.
 
 **Parameters:**
 
@@ -259,9 +209,9 @@ Lifetime: a conversational message (`role: "user"` or `"assistant"`) becomes par
 | `messages` | `ModelMessage[]` | Model messages to inject (from the `ai` package) |
 
 Messages are drained (consumed) when:
-1. A new turn starts, before `run()` executes
-2. A `prepareStep` boundary is reached, between tool-call steps during streaming
+1. A new turn starts — before `run()` executes
+2. A `prepareStep` boundary is reached — between tool-call steps during streaming
 
 <Note>
-  `chat.inject()` writes to an in-memory queue in the current process. It works from any code running in the same task: lifecycle hooks, deferred work, tool execute functions, etc. It does not work from subtasks or other runs.
+  `chat.inject()` writes to an in-memory queue in the current process. It works from any code running in the same task — lifecycle hooks, deferred work, tool execute functions, etc. It does not work from subtasks or other runs.
 </Note>

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_sk_..."              # secret API key for the env
+SECRET_KEY="tr_dev_..."              # secret API key for the env
 TASK_ID="ai-chat"                    # your chat.agent task id
 CHAT_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
 
@@ -210,7 +210,6 @@ 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). |
 
@@ -267,7 +266,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`, or `chat.close()` from inside the agent): 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`): 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>
@@ -694,7 +693,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", "code": "session_closed", "closedReason": "<reason or null>" }`. Key on `code`, not the message. Terminal: do not retry, and stop reconnecting to `.out`. |
+| `409` | The session is closed — `{ "ok": false, "error": "Cannot append to a closed session" }`. |
 | `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). |
 
@@ -833,7 +832,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 `chat.turn()`, a turn runs on the edited history and its chunks follow on `.out` like any turn's.
+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.
 
 Raw `chat.customAgent()` tasks receive `action` as `unknown` and must validate it in their own loop.
 

package/docs/ai-chat/compaction.mdx

@@ -19,12 +19,11 @@ Provide `shouldCompact` to decide when to compact and `summarize` to generate th
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { generateText, stepCountIs } from "ai";
+import { streamText, 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 }) => {
@@ -35,8 +34,9 @@ export const myChat = chat.agent({
       return result.text;
     },
   },
-  run: async ({ messages, signal, streamText }) => {
+  run: async ({ messages, signal }) => {
     return streamText({
+      ...chat.toStreamTextOptions({ registry }),
       messages,
       abortSignal: signal,
       stopWhen: stepCountIs(15),
@@ -61,12 +61,6 @@ 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`:
@@ -97,7 +91,7 @@ export const myChat = chat.agent({
       ...uiMessages.slice(-4), // Keep the last 4 messages
     ],
   },
-  run: async ({ messages, signal, streamText }) => {
+  run: async ({ messages, signal }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
@@ -191,7 +185,7 @@ export const myChat = chat.agent({
       data: { chatId, summary, totalTokens, messageCount },
     });
   },
-  run: async ({ messages, signal, streamText }) => {
+  run: async ({ messages, signal }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
@@ -207,7 +201,7 @@ Define a `compact` action that reuses your existing `summarize` function:
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { generateText, generateId, convertToModelMessages } from "ai";
+import { streamText, generateText, generateId, convertToModelMessages } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 
@@ -249,7 +243,7 @@ export const myChat = chat.agent({
     ]);
   },
 
-  run: async ({ messages, signal, streamText }) => {
+  run: async ({ messages, signal }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });

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

@@ -290,29 +290,6 @@ 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, streamText }) =>
+      run: async ({ messages, signal }) =>
         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>`. 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.
+    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.
 
     ```ts lib/chat-handler.ts
     import { chat } from "@trigger.dev/sdk/chat-server";
@@ -261,23 +261,18 @@ 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 ({ streamText }) =>
+      run: async ({ chat: helper }) =>
         streamText({
+          ...helper.toStreamTextOptions({ tools: headStartTools }),
           model: anthropic("claude-sonnet-4-6"),
           system: "You are a helpful assistant.",
-          tools: headStartTools,
         }),
     });
     ```
 
-    <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>
+    <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>
 
     <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.
@@ -630,27 +625,27 @@ chat.headStart<TTools>({
 export const chatHandler = chat.headStart({
   agentId: "my-chat",
   triggerConfig: { tags: ["org:acme"], queue: "chat", machine: "small-2x" },
-  run: async ({ streamText }) => streamText({ model, system, tools: headStartTools }),
+  run: async ({ chat: helper }) =>
+    streamText({ ...helper.toStreamTextOptions({ tools: headStartTools }), model, system }),
 });
 ```
 
 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.
-- `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.
+- `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.
 
-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:
+`chat.toStreamTextOptions({ tools })` returns options to spread into `streamText`. The SDK owns these keys — overriding them will break the protocol:
 
 | Key | What the SDK sets | Why |
 | --- | --- | --- |
 | `messages` | `convertToModelMessages(uiMessages)` | First-turn user history |
-| `prompt` | Nothing, and rejects yours | `messages` already carries the history |
-| `stopWhen` | `stepCountIs(1)` | Step 1 only, the agent picks up step 2 onward |
+| `tools` | What you pass | Schema-only tools for step 1 |
+| `stopWhen` | `stepCountIs(1)` | Step 1 only — agent picks up step 2+ |
 | `abortSignal` | Combined request + idle timeout | Safe cleanup on disconnect |
 
-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.
+You bring `model`, `system`, `providerOptions`, `prepareStep`, anything else `streamText` accepts.
 
 #### The transport option
 
@@ -689,11 +684,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 ({ streamText }) =>
+    run: async ({ chat: helper }) =>
       streamText({
+        ...helper.toStreamTextOptions({ tools: headStartTools }),
         model: anthropic("claude-sonnet-4-6"),
         system: "You are a helpful assistant.",
-        tools: headStartTools,
       }),
   });
 
@@ -740,13 +735,11 @@ 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; pendingVersion: boolean; completion: Promise<void> }>
+}): Promise<{ chatId: string; 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,8 +137,6 @@ 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";
 
@@ -444,48 +442,45 @@ function Chat({ chatId, transport }) {
 
 ## Sending actions
 
-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.
+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.
 
-```tsx
-import { useChat } from "@ai-sdk/react";
-import { useChatActions, useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
+For optimistic UI, mirror the action's effect on the `useChat` state via `setMessages` while the request is in flight:
 
+```tsx
 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 { sendMessage, regenerate, setMessages } = useChat({ id: chatId, transport });
-  const { sendAction } = useChatActions({ sendMessage });
+
+  const { setMessages } = useChat({ transport });
 
   return (
     <div>
       <button
         onClick={() => {
-          // Mirror the server-side edit optimistically; the server does not
-          // push history changes back.
+          void transport.sendAction(chatId, { type: "undo" });
           setMessages((prev) => prev.slice(0, -2));
-          void sendAction({ type: "undo" });
         }}
       >
         Undo last exchange
       </button>
-      {/* regenerate() removes the trailing answer locally; the server does the same before its turn */}
-      <button onClick={() => regenerate({ body: { action: { type: "regenerate" } } })}>
-        Regenerate
+      <button
+        onClick={() => transport.sendAction(chatId, { type: "rollback", targetMessageId: "msg-5" })}
+      >
+        Rollback to message
       </button>
     </div>
   );
 }
 ```
 
-`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.
+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>
-  `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.
+  `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.
 </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 fires regardless of whether [`hydrateMessages`](#hydratemessages) or a [transcript storage](/ai-chat/transcript-storage) is registered: crash recovery is runtime-owned for every agent.
+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).
 
 ```ts
 export const myChat = chat.agent({
@@ -260,10 +260,6 @@ 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.
@@ -319,7 +315,7 @@ After the hook returns, the runtime overlays the wire's tool-state advances (`ou
 </Note>
 
 <Tip>
-  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.
+  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.
 </Tip>
 
 <Note>