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

package/docs/ai-chat/anatomy.mdx

@@ -18,7 +18,7 @@ Everything below maps onto one annotated agent:
 
 ```ts trigger/my-agent.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs } from "ai";
+import { stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 
 export const myAgent = chat.agent({
@@ -36,9 +36,9 @@ export const myAgent = chat.agent({
 
   // The turn loop. Messages arrive accumulated; you stream back.
   // Options, levels, and alternatives — see Backend.
-  run: async ({ messages, tools, signal }) =>
+  run: async ({ messages, tools, signal, streamText }) =>
     streamText({
-      ...chat.toStreamTextOptions({ tools }),
+      tools,
       model: anthropic("claude-sonnet-4-5"),
       messages,
       abortSignal: signal,

package/docs/ai-chat/backend.mdx

@@ -30,14 +30,13 @@ Return the `streamText` result from `run` and it's automatically piped to the fr
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs } from "ai";
+import { stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 
 export const simpleChat = chat.agent({
   id: "simple-chat",
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
-      ...chat.toStreamTextOptions(), // prepareStep, system, telemetry (see note below)
       model: anthropic("claude-sonnet-4-5"),
       system: "You are a helpful assistant.",
       messages,
@@ -48,29 +47,64 @@ export const simpleChat = chat.agent({
 });
 ```
 
-<Warning>
-  **Always spread `chat.toStreamTextOptions()` first** (as above) so your explicit overrides win. It wires up the `prepareStep` callback behind [compaction](/ai-chat/compaction), [steering](/ai-chat/pending-messages), and [background injection](/ai-chat/background-injection), all of which silently no-op without it, and injects the system prompt from `chat.prompt()`, the resolved model (when you pass a `registry`), and telemetry metadata. Examples below keep the spread implicit for brevity, so include it in real code.
-</Warning>
+<Note>
+  The `streamText` destructured from `run`'s argument is the SDK's, not the one
+  imported from `ai`. It carries the agent's managed options, so nothing has to be
+  spread in. [The managed streamText](#the-managed-streamtext) covers what those
+  options are and what happens when yours collide with them.
+</Note>
+
+### The managed streamText
+
+`run()` is handed a `streamText` that already carries everything the spread provides, so the managed state cannot be lost by leaving the spread out:
+
+```ts
+export const simpleChat = chat.agent({
+  id: "simple-chat",
+  run: async ({ messages, signal, streamText }) =>
+    streamText({
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      abortSignal: signal,
+      stopWhen: stepCountIs(15),
+    }),
+});
+```
+
+Note the destructured `streamText`: it shadows the one imported from `ai` inside `run`, so the managed options apply without a spread. Spreading `chat.toStreamTextOptions()` into the imported `streamText` is still supported and equivalent.
+
+It differs from the spread in three ways, all of them about what happens when your options collide with the managed ones:
+
+| Option | Spread | Managed `streamText` |
+| --- | --- | --- |
+| `tools` | Passing `tools` after the spread replaces the skill tools | Merged, so skill tools survive |
+| `prepareStep` | Passing your own after the spread replaces the managed one, silently disabling steering, compaction and injection | Composed, yours runs after the managed one |
+| `system` | Yours replaces the managed prompt and any injected instructions | Throws |
+
+`system` throws rather than merging because there is no shape that combines two system values on every supported AI SDK version: v5 rejects an array of blocks, and a structured block carries the provider options that make [prompt caching](/ai-chat/prompt-caching) work, so concatenating discards the cache entry. Set a static prompt with [`chat.prompt.set()`](#using-prompts) and add per-turn context with [`chat.inject()`](/ai-chat/background-injection).
+
+If the managed prompt names a model, pass a registry on the agent so the runtime can resolve it: `chat.agent({ registry, run })`.
 
 ### Using chat.pipe() for complex flows
 
 For complex agent flows where `streamText` is called deep inside your code, use `chat.pipe()`. It works from **anywhere inside a task** — even nested function calls.
 
 ```ts trigger/agent-chat.ts
-import { chat } from "@trigger.dev/sdk/ai";
-import { streamText } from "ai";
+import { chat, type ChatStreamText } from "@trigger.dev/sdk/ai";
 import { anthropic } from "@ai-sdk/anthropic";
-import type { ModelMessage } from "ai";
+import { stepCountIs, type ModelMessage } from "ai";
 
 export const agentChat = chat.agent({
   id: "agent-chat",
-  run: async ({ messages }) => {
-    // Don't return anything — chat.pipe is called inside
-    await runAgentLoop(messages);
+  run: async ({ messages, streamText }) => {
+    // Don't return anything, chat.pipe is called inside
+    await runAgentLoop(messages, streamText);
   },
 });
 
-async function runAgentLoop(messages: ModelMessage[]) {
+// A loop factored out of `run` takes `streamText` as an argument so it keeps the
+// managed options. `ChatStreamText` types the parameter.
+async function runAgentLoop(messages: ModelMessage[], streamText: ChatStreamText) {
   // ... agent logic, tool calls, etc.
 
   const result = streamText({
@@ -102,7 +136,7 @@ export const myChat = chat.agent({
     // responseMessage.parts includes the data-metadata part
     await db.messages.save(responseMessage);
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     // Also works from run() via chat.response
     chat.response.write({
       type: "data-context",
@@ -177,9 +211,9 @@ const tools = { searchDocs };
 export const myChat = chat.agent({
   id: "my-chat",
   tools,
-  run: async ({ messages, tools, signal }) =>
+  run: async ({ messages, tools, signal, streamText }) =>
     streamText({
-      ...chat.toStreamTextOptions({ tools }),
+      tools,
       model: anthropic("claude-sonnet-4-5"),
       messages,
       abortSignal: signal,
@@ -200,12 +234,12 @@ See [Tools](/ai-chat/tools) for `toModelOutput` across turns, per-turn dynamic t
 
 ### Using prompts
 
-Use [AI Prompts](/ai/prompts) to manage your system prompt as versioned, overridable config. Store the resolved prompt in a lifecycle hook with `chat.prompt.set()`, then spread `chat.toStreamTextOptions()` into `streamText` — it includes the system prompt, model, config, and telemetry automatically.
+Use [AI Prompts](/ai/prompts) to manage your system prompt as versioned, overridable config. Store the resolved prompt in a lifecycle hook with `chat.prompt.set()`. The `streamText` from `run`'s argument picks it up: system prompt, model, config and telemetry.
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
 import { prompts } from "@trigger.dev/sdk";
-import { streamText, createProviderRegistry } from "ai";
+import { createProviderRegistry } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 
@@ -221,15 +255,15 @@ const systemPrompt = prompts.define({
 
 export const myChat = chat.agent({
   id: "my-chat",
+  registry,
   clientDataSchema: z.object({ userId: z.string() }),
   onChatStart: async ({ clientData }) => {
     const user = await db.user.findUnique({ where: { id: clientData.userId } });
     const resolved = await systemPrompt.resolve({ name: user.name });
     chat.prompt.set(resolved);
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
-      ...chat.toStreamTextOptions({ registry }), // system, model, config, telemetry
       messages,
       abortSignal: signal,
       stopWhen: stepCountIs(15),
@@ -238,16 +272,9 @@ export const myChat = chat.agent({
 });
 ```
 
-`chat.toStreamTextOptions()` returns an object with `system`, `model` (resolved via the registry), `temperature`, and `experimental_telemetry` — all from the stored prompt. Properties you set after the spread (like a client-selected model) take precedence.
-
-**Which form to call:**
+The managed `streamText` carries the stored prompt's `system`, `model` (resolved through the agent's `registry`), sampling config, and `experimental_telemetry`. Options you pass at the call site win, apart from `system`, which throws when the prompt already set one.
 
-| Form | Use when |
-|---|---|
-| `chat.toStreamTextOptions()` | Default. Wires up `prepareStep` (compaction, steering, background injection), the stored prompt's `system` / `model` / `config`, and telemetry metadata. |
-| `chat.toStreamTextOptions({ registry })` | You're using [Prompts](/ai/prompts) with a provider-prefixed model string (e.g. `"anthropic:claude-sonnet-4-5"`). The registry resolves the prefix to a real model instance via `createProviderRegistry({ anthropic, openai, ... })`. |
-| `chat.toStreamTextOptions({ tools })` | You want HITL tool approvals — pass the same `tools` object you give to `streamText`. The SDK then knows which tool calls need to pause on `needsApproval: true`. |
-| `chat.toStreamTextOptions({ registry, tools })` | Both of the above. |
+`chat.toStreamTextOptions()` remains available for the same job, and is the only option in a [custom agent](#custom-agents), which has no `run` argument to take a bound `streamText` from. A `chat.headStart` route does get one, and there it also owns `messages`, `stopWhen` and `abortSignal`, since the handover depends on them. Pass `{ registry }` when a prompt names a provider-prefixed model, and `{ tools }` when you want HITL tool approvals, so the SDK knows which calls pause on `needsApproval`.
 
 <Tip>
   See [Prompts](/ai/prompts) for the full guide — defining templates, variable schemas, dashboard
@@ -273,7 +300,7 @@ The `run` function receives three abort signals:
 ```ts
 export const myChat = chat.agent({
   id: "my-chat",
-  run: async ({ messages, signal, stopSignal, cancelSignal }) => {
+  run: async ({ messages, signal, stopSignal, cancelSignal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-5"),
       messages,
@@ -302,7 +329,7 @@ export const myChat = chat.agent({
       data: { messages: uiMessages, lastStoppedAt: stopped ? new Date() : undefined },
     });
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
@@ -312,11 +339,10 @@ You can also check stop status from **anywhere** during a turn using `chat.isSto
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText } from "ai";
 
 export const myChat = chat.agent({
   id: "my-chat",
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-5"),
       messages,
@@ -369,7 +395,7 @@ const sendEmail = tool({
 
 export const myChat = chat.agent({
   id: "my-chat",
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-5"),
       messages,
@@ -405,12 +431,12 @@ Users can send messages while the agent is executing tool calls. With `pendingMe
 ```ts
 export const myChat = chat.agent({
   id: "my-chat",
+  registry,
   pendingMessages: {
     shouldInject: ({ steps }) => steps.length > 0,
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
-      ...chat.toStreamTextOptions({ registry }),
       messages,
       tools: {
         /* ... */
@@ -436,6 +462,7 @@ Inject context from background work into the conversation using `chat.inject()`.
 ```ts
 export const myChat = chat.agent({
   id: "my-chat",
+  registry,
   onTurnComplete: async ({ messages }) => {
     chat.defer(
       (async () => {
@@ -453,8 +480,8 @@ export const myChat = chat.agent({
       })()
     );
   },
-  run: async ({ messages, signal }) => {
-    return streamText({ ...chat.toStreamTextOptions({ registry }), messages, abortSignal: signal });
+  run: async ({ messages, signal, streamText }) => {
+    return streamText({ messages, abortSignal: signal });
   },
 });
 ```
@@ -565,7 +592,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 });
   },
 });
@@ -590,7 +617,7 @@ By default, a chat agent stays idle after each turn waiting for the next user me
 ```ts
 chat.agent({
   id: "one-shot",
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     // Single-response agent — exit after this turn.
     chat.endRun();
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
@@ -606,6 +633,57 @@ Use this when the agent knows its work is done (budget exhausted, goal achieved,
   If you persist `lastEventId` to your own storage for cross-page-load resume, **don't clear it on `chat.endRun()`**. The cursor is sessionId-keyed and stays valid across Run boundaries — clearing it forces the next `sendMessages` to subscribe from `seq_num=0`, where it may hit the prior turn's stale `turn-complete` record and close the stream empty before the new Run's chunks arrive.
 </Warning>
 
+### Ending the conversation
+
+`chat.close()` ends the whole conversation. The session row is marked closed, further appends are refused with HTTP 409, and no continuation run is scheduled. Call it from `run()`, `prepareStep`, or `onBeforeTurnComplete`.
+
+```ts
+chat.agent({
+  id: "budgeted-agent",
+  run: async ({ messages, signal }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
+  // onBeforeTurnComplete carries the same fields as onTurnComplete, including
+  // `usage`, and still runs while the response stream is open.
+  onBeforeTurnComplete: async ({ chatId }) => {
+    if (await overBudget(chatId)) {
+      chat.close({ reason: "Monthly budget reached" });
+    }
+  },
+});
+```
+
+The current turn finishes and streams through normally. Called mid-step, `chat.close()` aborts the in-flight `streamText` the same way the stop signal does, so the partial response is still captured and delivered. The transport then flips to a closed state, carrying `reason` so you can render why the conversation ended.
+
+<Warning>
+  **Decide before the turn ends, not in `onTurnComplete`.** The closed state reaches the browser on the turn's final `turn-complete` record. `onTurnComplete` runs after that record is written and after the response stream has closed, so a close decided there does not reach a reader that is already done with the turn: the user sees a normal answer and learns the conversation ended only when their next message is refused. Use `onBeforeTurnComplete` for the same information one step earlier, and the user sees the closed state as soon as the answer finishes.
+</Warning>
+
+Closing is one-way. A closed session cannot be reopened, and its transcript stays readable. Start a new conversation under a different `chatId` to continue.
+
+On the client, read the closed state off the transport:
+
+```tsx app/components/Chat.tsx
+if (transport.sessionStatus(chatId) === "closed") {
+  return <p>This conversation has ended: {transport.sessionClosedReason(chatId)}</p>;
+}
+```
+
+### Three levels of stopping
+
+`chat.agent` stops at three levels, each with a different "what happens next".
+
+| Level | Primitive | What stops | What happens next |
+| --- | --- | --- | --- |
+| Turn | `stopWhen`, or the [stop signal](/ai-chat/backend#stop-generation) aborting `signal` | The current `streamText` | The turn completes, the agent idles for the next message |
+| Run | `chat.endRun()` | The current worker | The next message on the same `chatId` starts a fresh continuation run |
+| Session | `chat.close()` | The conversation, permanently | Nothing. Appends are refused with 409 and no run is triggered |
+
+Reach for the narrowest level that does the job: a turn budget is a `stopWhen`, a finished one-shot answer is `chat.endRun()`, and an exhausted account or a signed-out user is `chat.close()`.
+
+`chat.close()` is available to [custom agents](/ai-chat/custom-agents#ending-the-conversation) too, where the close is performed when your `run()` returns.
+
+A session can also be closed from outside the run: `sessions.close(chatId)` from your backend, or the Close action in the dashboard. A live run is told either way: the close lands on the session's input channel, so an idle or suspended agent leaves its loop on the next wake instead of waiting out its idle timeout.
+
 ### Runtime configuration
 
 #### chat.setTurnTimeout()
@@ -613,7 +691,7 @@ Use this when the agent knows its work is done (budget exhausted, goal achieved,
 Override how long the run stays suspended waiting for the next message. Call from inside `run()`:
 
 ```ts
-run: async ({ messages, signal }) => {
+run: async ({ messages, signal, streamText }) => {
   chat.setTurnTimeout("2h"); // Wait longer for this conversation
   return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
 },
@@ -624,7 +702,7 @@ run: async ({ messages, signal }) => {
 Override how long the run stays idle (active, using compute) after each turn:
 
 ```ts
-run: async ({ messages, signal }) => {
+run: async ({ messages, signal, streamText }) => {
   chat.setIdleTimeoutInSeconds(60); // Stay idle for 1 minute
   return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
 },
@@ -659,7 +737,7 @@ export const myChat = chat.agent({
       return "Something went wrong. Please try again.";
     },
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
@@ -690,7 +768,7 @@ export const myChat = chat.agent({
     sendReasoning: true, // Forward model reasoning (default: true)
     sendSources: true, // Forward source citations (default: false)
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
@@ -708,7 +786,7 @@ export const myChat = chat.agent({
   uiMessageStreamOptions: {
     generateMessageId: () => uuidv7(),
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
@@ -728,7 +806,7 @@ export const myChat = chat
   })
   .agent({
     id: "my-chat",
-    run: async ({ messages, signal }) => {
+    run: async ({ messages, signal, streamText }) => {
       return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
     },
   });
@@ -746,7 +824,7 @@ export const myChat = chat
 Override per-turn with `chat.setUIMessageStreamOptions()` — per-turn values merge with the static config (per-turn wins on conflicts). The override is cleared automatically after each turn.
 
 ```ts
-run: async ({ messages, clientData, signal }) => {
+run: async ({ messages, clientData, signal, streamText }) => {
   // Enable reasoning only for certain models
   if (clientData.model?.includes("claude")) {
     chat.setUIMessageStreamOptions({ sendReasoning: true });
@@ -772,7 +850,6 @@ If you need full control over task options, use the standard `task()` with `Chat
 ```ts
 import { task } from "@trigger.dev/sdk";
 import { chat, type ChatTaskPayload } from "@trigger.dev/sdk/ai";
-import { streamText } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 
 export const manualChat = task({

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,8 +33,9 @@ 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);
@@ -47,9 +48,8 @@ export const myChat = chat.agent({
       })()
     );
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     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 { streamText, generateObject, createProviderRegistry, stepCountIs } from "ai";
+import { generateObject, createProviderRegistry, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 
@@ -98,6 +98,7 @@ Be concise. Only flag issues worth fixing.`,
 
 export const myChat = chat.agent({
   id: "my-chat",
+  registry,
   onTurnComplete: async ({ messages }) => {
     chat.defer(
       (async () => {
@@ -139,9 +140,8 @@ export const myChat = chat.agent({
       })()
     );
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     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 — `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, because `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 }) => {
+  run: async ({ messages, signal, streamText }) => {
     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,9 +189,57 @@ 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`, `user`, `assistant`) | Typically `user` |
+| **Message role** | Any. `system` becomes an instruction, others join the conversation (see below) | 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()
@@ -200,7 +248,9 @@ export const myChat = chat.agent({
 chat.inject(messages: ModelMessage[]): void
 ```
 
-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.
+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.
 
 **Parameters:**
 
@@ -209,9 +259,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_..."              # 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.