@trigger.dev/sdk 0.0.0-prerelease-20260908122921 → 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,7 +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.
+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:**
 
@@ -257,9 +209,9 @@ Queue model messages for injection at the next opportunity. Messages persist acr
 | `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,10 +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.
 
-<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`:
@@ -95,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 });
   },
 });
@@ -189,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 });
   },
 });
@@ -205,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";
 
@@ -247,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

@@ -442,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/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.
-- Take `streamText` from the `run` argument, so the managed options apply to that
+- Spread `...chat.toStreamTextOptions({ tools })` as the FIRST property of 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,9 +145,10 @@ import { tools } from "@/lib/tools";
 export const myChat = chat.agent({
   id: "my-chat",
   tools,
-  run: async ({ messages, tools, signal, streamText }) =>
+  run: async ({ messages, tools, signal }) =>
     streamText({
-      tools,
+      // Spread first, so every option below still wins.
+      ...chat.toStreamTextOptions({ tools }),
       model: anthropic("claude-sonnet-4-5"),
       system: "You are a helpful assistant.",
       messages,
@@ -162,10 +163,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`.
-- **`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.
+- **`...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.
 
 <Warning>
-  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.
+  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.
 </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.
@@ -356,9 +357,9 @@ export const myChat = chat.agent({
       }),
     ]);
   },
-  run: async ({ messages, tools, signal, streamText }) =>
+  run: async ({ messages, tools, signal }) =>
     streamText({
-      tools,
+      ...chat.toStreamTextOptions({ tools }),
       model: anthropic("claude-sonnet-4-5"),
       system: "You are a helpful assistant.",
       messages,
@@ -467,21 +468,18 @@ 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 ({ streamText }) =>
+      run: async ({ chat: helper }) =>
         streamText({
+          ...helper.toStreamTextOptions({ tools: headStartTools }),
           model: anthropic("claude-sonnet-4-5"),
           system: "You are a helpful assistant.",
-          tools: headStartTools,
         }),
     });
     ```
 
-    <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>
+    <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>
 
     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>
@@ -560,7 +558,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.** `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.
+**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.
 
 **`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.