fix(chat): publish the agent options for hydrateMessages agents, and align the Head Start docs

chat.toStreamTextOptions() read the agent-level system, registry, cacheControl
and systemProviderOptions from a key set only inside the snapshot boot block,
which a hydrateMessages agent skips, so the spread form dropped them there.
The key is set on every boot now, with a test for the hydrateMessages case.

Docs: the actions gating example returns chat.turn() instead of a streamText
call onAction no longer receives; the extracted-loop examples import
ChatStreamText, stepCountIs and ModelMessage; the Head Start pages and the
chat-server docstrings list prompt among the owned options and describe
tools as caller-supplied.

Author: ericallam

docs/ai-chat/actions.mdx

@@ -107,15 +107,11 @@ onTurnComplete: async ({ chatId, newUIMessages }) => {
 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, signal, streamText }) => {
+onAction: async ({ action }) => {
   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: await convertToModelMessages(chat.history.all()),
-      abortSignal: signal,
-    });
+    return chat.turn();
   }
 },
 ```

docs/ai-chat/backend.mdx

@@ -90,9 +90,9 @@ If the managed prompt names a model, pass a registry on the agent so the runtime
 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 { 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",

docs/ai-chat/fast-starts.mdx

@@ -272,9 +272,9 @@ This is an **import-chain** problem, not a runtime one. A "we'll strip the execu
 
     <Note>
       That `streamText` is the SDK's, not the one from `ai`. It pins `messages`,
-      `stopWhen: stepCountIs(1)` and `abortSignal`, which the handover depends on:
+      `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 three at the call site is a type error, and a throw if you get past
+      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>
@@ -646,11 +646,11 @@ The SDK owns these keys. Passing one to the callback's `streamText` is a type er
 | Key | What the SDK sets | Why |
 | --- | --- | --- |
 | `messages` | `convertToModelMessages(uiMessages)` | First-turn user history |
-| `tools` | What you pass | Schema-only tools for step 1 |
+| `prompt` | Nothing, and rejects yours | `messages` already carries the history |
 | `stopWhen` | `stepCountIs(1)` | Step 1 only, the agent picks up step 2 onward |
 | `abortSignal` | Combined request + idle timeout | Safe cleanup on disconnect |
 
-You bring `model`, `system`, `providerOptions`, `prepareStep`, anything else `streamText` accepts. Note that `tools` is the one owned key you do pass, since the SDK cannot know your schema-only set.
+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.
 
 #### The transport option
 

docs/ai-chat/migrating-from-a-route-handler.mdx

@@ -478,7 +478,7 @@ Head Start brings the route handler back for exactly that first turn. It runs st
     ```
 
     <Note>
-      That `streamText` owns `messages`, `abortSignal` and `stopWhen`. Passing one is
+      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.

packages/trigger-sdk/skills/trigger-authoring-chat-agent/SKILL.md

@@ -120,6 +120,10 @@ inside nested helpers, call `await chat.pipe(result)` from anywhere in the task
 `run` resolve `void`.
 
 ```ts
+import { chat, type ChatStreamText } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import type { ModelMessage } from "ai";
+
 export const agentChat = chat.agent({
   id: "agent-chat",
   run: async ({ messages, streamText }) => {
@@ -262,7 +266,7 @@ There is no API route in this model. The transport replaces the route round-trip
   model, and telemetry. The imported one carries none of it, with no error.
   `...chat.toStreamTextOptions()` does the same job by hand, and is what a custom agent has to use,
   since it has no `run` argument. A `chat.headStart` route gets a bound `streamText` too, and there it
-  also owns `messages`, `stopWhen` and `abortSignal`. Spreading it and then re-setting
+  also owns `messages`, `prompt`, `stopWhen` and `abortSignal`. Spreading it and then re-setting
   `tools` or `prepareStep` replaces the managed ones; the run argument's `streamText` merges `tools`
   and composes `prepareStep` instead.
 

packages/trigger-sdk/skills/trigger-chat-agent-advanced/SKILL.md

@@ -231,8 +231,8 @@ import { headStartTools } from "@/lib/chat-tools/schemas";
 
 export const chatHandler = chat.headStart({
   agentId: "my-chat",
-  // `streamText` from the run argument owns `messages`, `stopWhen` and
-  // `abortSignal`: the handover needs `stopWhen: stepCountIs(1)` so the agent,
+  // `streamText` from the run argument owns `messages`, `prompt`, `stopWhen`
+  // and `abortSignal`: the handover needs `stopWhen: stepCountIs(1)` so the agent,
   // not this handler, runs step 2 onward. Passing any of them is a type error.
   run: async ({ streamText }) =>
     streamText({

packages/trigger-sdk/src/v3/ai.ts

@@ -7499,18 +7499,18 @@ function chatAgent<
           }
         }
 
-        locals.set(chatAgentManagedConfigKey, {
-          registry: promptRegistry,
-          system: agentSystem,
-          cacheControl: agentCacheControl,
-          systemProviderOptions: agentSystemProviderOptions,
-        });
-
         // Make the seeded UI accumulator visible to `chat.history.*`
         // before any hook (`onChatStart`, `onTurnStart`, etc.) fires.
         locals.set(chatCurrentUIMessagesKey, accumulatedUIMessages);
       }
 
+      locals.set(chatAgentManagedConfigKey, {
+        registry: promptRegistry,
+        system: agentSystem,
+        cacheControl: agentCacheControl,
+        systemProviderOptions: agentSystemProviderOptions,
+      });
+
       // Token usage tracking across turns
       let previousTurnUsage: LanguageModelUsage | undefined;
       let cumulativeUsage: LanguageModelUsage = emptyUsage();

packages/trigger-sdk/src/v3/chat-server.ts

@@ -172,16 +172,16 @@ export type HeadStartRunArgs<TTools extends Record<string, Tool>> = {
   /** Helper exposing `toStreamTextOptions(...)` and a session escape hatch. */
   chat: HeadStartChatHelper<TTools>;
   /**
-   * `streamText` with the four options the handover protocol depends on already
-   * applied: the converted `messages`, your `tools`, `stopWhen: stepCountIs(1)`
-   * and the combined `abortSignal`.
+   * `streamText` with the options the handover protocol depends on already
+   * applied: the converted `messages`, `stopWhen: stepCountIs(1)` and the
+   * combined `abortSignal`, plus the `tools` you pass to it.
    *
    * Prefer it over importing `streamText` from `ai`. Spreading
    * `chat.toStreamTextOptions()` into the imported one is equivalent, but
-   * setting `messages`, `stopWhen` or `abortSignal` after the spread breaks the
-   * handover, and nothing catches that. Passing any of them here throws
-   * instead, and note that the four it owns are a type error, not just a
-   * runtime one.
+   * setting `messages`, `prompt`, `stopWhen` or `abortSignal` after the spread
+   * breaks the handover, and nothing catches that. Passing any of those four
+   * here is a type error, and a throw if you get past the types. `tools` is
+   * yours to supply.
    */
   streamText: HeadStartStreamTextFn;
 };
@@ -203,7 +203,7 @@ export type HeadStartChatHelper<TTools extends Record<string, Tool>> = {
    * this helper just hands back the options the SDK needs to own.
    *
    * The customer COULD override any of these by re-setting them after
-   * the spread, but doing so for `stopWhen` / `messages` /
+   * the spread, but doing so for `stopWhen` / `messages` / `prompt` /
    * `abortSignal` will break the handover protocol. The intent is
    * that customers spread first, then add only their own keys.
    */

packages/trigger-sdk/test/spread-form-agent-options.test.ts

@@ -47,4 +47,30 @@ describe("chat.toStreamTextOptions with agent-level options", () => {
       await harness.close();
     }
   });
+
+  it("carries chat.agent({ system }) in the spread form for a hydrateMessages agent", async () => {
+    const prompts: string[] = [];
+    const model = new MockLanguageModelV3({
+      doStream: async ({ prompt }) => {
+        prompts.push(JSON.stringify(prompt));
+        return {
+          stream: simulateReadableStream({ chunks: textChunks("ok"), initialDelayInMs: 5 }),
+        };
+      },
+    });
+    const agent = chat.agent({
+      id: "spread-form-agent-system-hydrate",
+      system: "AGENT-SYSTEM-VIA-SPREAD-HYDRATE",
+      hydrateMessages: async ({ incomingMessages }) => incomingMessages,
+      run: async ({ messages, signal }) =>
+        streamText({ model, messages, abortSignal: signal, ...chat.toStreamTextOptions() }),
+    });
+    const harness = mockChatAgent(agent, { chatId: "spread-form-agent-system-hydrate" });
+    try {
+      await harness.sendMessage({ id: "u1", role: "user", parts: [{ type: "text", text: "hi" }] });
+      expect(prompts.at(-1)!).toContain("AGENT-SYSTEM-VIA-SPREAD-HYDRATE");
+    } finally {
+      await harness.close();
+    }
+  });
 });