feat(chat): hand run() a streamText that already has the managed options

Spreading chat.toStreamTextOptions() is the integration point for six things:
the managed prompt and its cache control, the resolved model, the prompt's
sampling config, telemetry, the skill tools, and the prepareStep that delivers
steering, compaction and injected context. Forgetting the spread drops all six
in silence, and spread order decides whether passing your own tools or
prepareStep clobbers the managed ones.

run() now receives a streamText with those options applied, so the managed
state cannot be lost by omission and the merge happens inside rather than at
the call site: tools go into the helper so skills survive, a caller system
becomes the base the prompt and injections append to, and a caller prepareStep
composes after the managed one instead of replacing it.

The signature is borrowed with typeof import("ai").streamText rather than
restated, so it resolves to whichever of ai v5/v6/v7 the user installed. The
runtime value rides the existing ESM/CJS shim that already isolates value
imports from ai.

PROTOTYPE. Typechecks and passes the suite on ai@6.0.116 and ai@7.0.66, but
adds a public registry option, does not settle what happens when caller and
managed system are both structured, and has no test for the composed
prepareStep.

Author: ericallam

.changeset/managed-streamtext-in-run.md

@@ -0,0 +1,20 @@
+---
+"@trigger.dev/sdk": minor
+---
+
+`run()` now receives a `streamText` with your agent's managed options already applied, so they cannot be lost by leaving out the spread:
+
+```ts
+run: async ({ messages, signal, streamText }) =>
+  streamText({ model, messages, abortSignal: signal });
+```
+
+Spreading `chat.toStreamTextOptions()` still works and is equivalent. The difference is what happens when your options collide with the managed ones. Passing `tools` after the spread replaces the skill tools, and passing your own `prepareStep` replaces the managed one, which silently switches off steering, compaction and injected context. The managed `streamText` merges tools and composes `prepareStep` instead, so neither can be turned off by accident.
+
+`system` can be set at the call site, on `chat.agent({ system })`, or through `chat.prompt.set()`, but only in one of them: setting it in two places throws, because no single shape merges two system values across every supported AI SDK version, and dropping one silently is the failure this seam exists to prevent. Injected instructions append to whichever one is in play.
+
+`chat.agent()` also takes `registry`, `cacheControl` and `systemProviderOptions` now, so a managed prompt's model and its cache breakpoint no longer have to be passed at the call site.
+
+`onAction` receives the same `streamText`, so a response produced from an action, a regenerate especially, answers with the agent's own system prompt and tools. Built with the `streamText` imported from `ai` it answered with none, and the reply still looked fine, which is what made the difference easy to miss.
+
+`chat.headStart` and `chat.startHeadStart` hand their `run` the same thing, carrying the four options the handover protocol depends on. There it matters more: re-setting `messages`, `stopWhen` or `abortSignal` after a spread breaks the handover rather than degrading a feature, and nothing caught it. On the managed one those keys are a type error.

docs/ai-chat/actions.mdx

@@ -44,7 +44,7 @@ export const myChat = chat.agent({
     // returning void → side-effect-only, no model call
   },
 
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
@@ -56,13 +56,19 @@ export const myChat = chat.agent({
 
 `onAction` can return a `StreamTextResult`, `string`, or `UIMessage` to produce a response. The returned stream is auto-piped to the frontend just like a normal turn, but the rest of the turn machinery (`onTurnStart`, `onTurnComplete`, etc.) still does not fire.
 
+The `messages` argument is captured before `onAction` runs, so a handler that mutates `chat.history` and then passes `messages` straight through sends the model the state it just changed. Rebuild from `chat.history.all()` after the mutation.
+
+Build the response with the `streamText` from `onAction`'s own argument, the same one `run()` receives. It carries the agent's system prompt, skill tools, resolved model and telemetry, so a regenerated answer is produced under the same configuration as every other turn. The `streamText` imported from `ai` carries none of that, and the reply still looks fine, which is what makes the difference easy to miss.
+
 ```ts
-onAction: async ({ action, messages }) => {
+onAction: async ({ action, streamText }) => {
   if (action.type === "regenerate") {
     chat.history.slice(0, -1); // drop the last assistant
     return streamText({
       model: anthropic("claude-sonnet-4-5"),
-      messages,
+      // Rebuild from the mutated history. The `messages` argument was captured
+      // before the slice, so it still contains the answer being replaced.
+      messages: await convertToModelMessages(chat.history.all()),
       stopWhen: stepCountIs(15),
     });
   }
@@ -81,7 +87,7 @@ An action is not a turn, so `onTurnComplete` never fires, and that is where an a
 **Your own store** (`hydrateMessages` registered): the runtime deliberately does not write, because your store is the source of truth. A history mutation and a returned response both live only in the running worker until you persist them, and a continuation rehydrates from your store, not from what the worker had in memory. `chat.pipeAndCapture` hands you the same assistant message the runtime would have captured:
 
 ```ts
-onAction: async ({ action, messages }) => {
+onAction: async ({ action, messages, streamText }) => {
   if (action.type === "undo") {
     chat.history.slice(0, -2);
     await db.deleteLastExchange(chatId); // the rollback is yours to persist
@@ -91,7 +97,10 @@ onAction: async ({ action, messages }) => {
     chat.history.slice(0, -1);
     await db.deleteLastAssistant(chatId); // drop the answer being replaced
     const { message } = await chat.pipeAndCapture(
-      streamText({ model: anthropic("claude-sonnet-4-5"), messages })
+      streamText({
+        model: anthropic("claude-sonnet-4-5"),
+        messages: await convertToModelMessages(chat.history.all()),
+      })
     );
     if (message) await db.saveMessage(message); // then store the new one
   }
@@ -107,11 +116,15 @@ Returning the stream instead of piping it yourself still works and still reaches
 If you have a [human-in-the-loop](/ai-chat/patterns/human-in-the-loop) tool waiting on `addToolOutput`, you usually want to refuse competing actions like `regenerate` until the answer arrives. [`chat.history.getPendingToolCalls()`](/ai-chat/backend#chat-history) gives you exactly that signal:
 
 ```ts
-onAction: async ({ action, messages, signal }) => {
+onAction: async ({ action, signal, streamText }) => {
   if (action.type === "regenerate") {
     if (chat.history.getPendingToolCalls().length > 0) return; // gated
     chat.history.slice(0, -1);
-    return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
+    return streamText({
+      model: anthropic("claude-sonnet-4-5"),
+      messages: await convertToModelMessages(chat.history.all()),
+      abortSignal: signal,
+    });
   }
 },
 ```

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,