@trigger.dev/sdk 4.5.16 → 4.6.0

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,27 +161,80 @@ 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`.** `chat.defer` only promises the work finished before `onTurnComplete`, which is long after the answer started streaming. A page refresh in between reads `[]` from your DB and loses the user's message from the rendered conversation. Use [`chat.deferBeforeOutput()`](#chat-deferbeforeoutput) for that write instead, and reserve `chat.defer` for writes whose timing has no resume implication.
 </Warning>
 
+## `chat.deferBeforeOutput`
+
+`chat.deferBeforeOutput()` is `chat.defer()` for work the next page load has to see. The work starts immediately and the hook does not await it, so it runs alongside the model and costs no time to first token. The difference is that the output stream waits for it: no part of the answer is written to the session until it settles.
+
+That ordering is the point. A reader that can see the answer can also see whatever the work persisted, so a refresh mid-answer never renders a reply to a question that is missing.
+
+```ts
+export const myChat = chat.agent({
+  id: "my-chat",
+  onTurnStart: async ({ chatId, uiMessages }) => {
+    // The next page load has to see this, so the answer waits for it.
+    chat.deferBeforeOutput(
+      db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } })
+    );
+  },
+  run: async ({ messages, signal, streamText }) => {
+    return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
+  },
+});
+```
+
+Use it for the conversation write, a message insert, or anything else the frontend reads back on reload. Keep analytics, audit logs and search-index updates on `chat.defer`.
+
+<Warning>
+**This is not a consistency barrier for the turn.** It orders the write against what the frontend can see, and nothing else. The work is still in flight while the model runs, so a tool, a `prepareStep`, or another service reading the same row during the turn can still see the state as it was before the write.
+
+If the turn's own code reads the write back, `await` it instead:
+
+```ts
+onTurnStart: async ({ chatId, uiMessages }) => {
+  // A tool later in this turn reads this row, so the turn has to wait for it.
+  await db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } });
+},
+```
+
+That costs time to first token, which is the price of the stronger guarantee. `chat.deferBeforeOutput` is for writes whose only reader is the next page load.
+</Warning>
+
+A registered promise that rejects, or that runs longer than the internal timeout, lets the answer through rather than stalling the conversation. It is a best-effort ordering guarantee, not a lock.
+
+| | `chat.defer()` | `chat.deferBeforeOutput()` |
+|---|---|---|
+| **Awaited by the hook** | No | No |
+| **Costs time to first token** | No | No |
+| **Answer waits for it** | No | Yes |
+| **Settled by** | Before `onTurnComplete` | Before the first chunk reaches the session |
+| **Read back by tools in the same turn** | No | No |
+| **Use for** | Analytics, audit logs, index writes | Conversation and message writes the frontend reads back |
+
+<Note>
+  If your agent persists through a [transcript storage](/ai-chat/transcript-storage), the runtime already does this for the incoming message on your behalf. `chat.deferBeforeOutput` is for writes your app owns on top of that.
+</Note>
+
 ## How it differs from pending messages
 
 | | `chat.inject()` | [Pending messages](/ai-chat/pending-messages) |
@@ -189,9 +242,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 +301,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 +312,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>