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

package/docs/ai-chat/patterns/skills.mdx

@@ -79,7 +79,7 @@ The **body** is loaded on demand via the `loadSkill` tool when the agent decides
 ```ts trigger/chat.ts
 import { chat } from "@trigger.dev/sdk/ai";
 import { skills } from "@trigger.dev/sdk";
-import { stepCountIs } from "ai";
+import { streamText, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 
 const timeUtilsSkill = skills.define({
@@ -92,11 +92,12 @@ export const agent = chat.agent({
   onChatStart: async () => {
     chat.skills.set([await timeUtilsSkill.local()]);
   },
-  run: async ({ messages, signal, streamText }) => {
+  run: async ({ messages, signal }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-5"),
       messages,
       abortSignal: signal,
+      ...chat.toStreamTextOptions(),
       stopWhen: stepCountIs(15),
     });
   },
@@ -110,7 +111,7 @@ export const agent = chat.agent({
 
 `skill.local()` reads the bundled `SKILL.md` from disk and returns a `ResolvedSkill` with the parsed frontmatter + body + on-disk path.
 
-`chat.skills.set([...])` stores the resolved skills for the current run. The `streamText` from `run`'s argument picks them up automatically:
+`chat.skills.set([...])` stores the resolved skills for the current run. `chat.toStreamTextOptions()` spreads them into `streamText` automatically:
 
 - The frontmatter `description` lands in the system prompt under "Available skills:".
 - Three tools are added: `loadSkill`, `readFile`, `bash` — scoped per skill.
@@ -168,10 +169,12 @@ return streamText({
   model: anthropic("claude-sonnet-4-5"),
   messages,
   abortSignal: signal,
-  tools: {
-    webFetch,       // your tool
-    deepResearch,   // your tool
-  },
+  ...chat.toStreamTextOptions({
+    tools: {
+      webFetch,       // your tool
+      deepResearch,   // your tool
+    },
+  }),
   stopWhen: stepCountIs(15),
 });
 ```

package/docs/ai-chat/patterns/version-upgrades.mdx

@@ -8,17 +8,6 @@ Chat agent runs are pinned to the worker version they started on. When you deplo
 
 `chat.requestUpgrade()` is the managed upgrade signal for `chat.agent()` and the `chat.createSession()` iterator. Fully hand-rolled custom agents use `chat.endAndContinue()` between turns to immediately hand the Session to a new run.
 
-<Note>
-  If your sessions are pinned by [version skew
-  protection](/deployment/version-skew-protection#chat-sessions), you do not need this page to move a
-  conversation onto a new deployment. A pinned session follows its pin on its own: when the stored
-  `externalDeploymentId` stops naming the deployment a run is on, the agent hands over at the next
-  turn boundary. Set [`versionSkew: "hold"`](#staying-put) to turn that off for one agent.
-
-  Read on for the cases that are still yours to decide — leaving a pin for a version nobody named,
-  a session that was never pinned, and hand-rolled custom agents.
-</Note>
-
 ## How it works
 
 When `chat.requestUpgrade()` is called in `onTurnStart` or `onValidateMessages`:
@@ -30,44 +19,22 @@ When `chat.requestUpgrade()` is called in `onTurnStart` or `onValidateMessages`:
 
 The new run lives on the **same Session** as the old one. `chatId` is the durable identity; only the underlying `currentRunId` rotates. The audit log records the new run with `reason: "upgrade"`.
 
-### What "the latest deployment" means
-
-The handoff clears the session's [external deployment id](/deployment/version-skew-protection#chat-sessions) so the new run can land on the current version — re-applying the pin the agent just rejected would make the upgrade impossible. The cleared pin is persisted on the session, so the next continuation doesn't fall back to it either.
-
-To move to a specific deployment rather than to whatever is current, name it:
-
-```ts
-chat.requestUpgrade({ externalDeploymentId: clientData.commitSha });
-```
-
-That is usually what you want when the client told you which build it is on: it upgrades to the version the client expects instead of merely to the newest one.
-
-<Warning>
-  `lockToVersion` is a different thing and is **never** cleared. A session started with an explicit
-  `lockToVersion` re-applies it on every run including upgrade handoffs, so `chat.requestUpgrade()`
-  cannot escape it — the new run lands on the same version the old one did. Use the external
-  deployment id if you want a pin an agent can opt out of.
-</Warning>
-
 When called from inside `run()` or `chat.defer()`, the current turn completes normally first and the run exits afterward. The next message triggers the continuation on the same session.
 
 ```mermaid
 sequenceDiagram
   participant User
   participant Transport
-  participant Session as session.in
   participant RunV1 as Run (v1)
   participant RunV2 as Run (v2)
 
   User->>Transport: send message
-  Transport->>Session: append message
-  Session->>RunV1: input stream
+  Transport->>RunV1: input stream
   RunV1->>RunV1: onTurnStart → requestUpgrade()
-  RunV1->>RunV2: end-and-continue triggers the successor
-  RunV1-->>Transport: trigger:upgrade-required (filtered, no re-send)
-  RunV1->>RunV1: exit (run() never called, message left unacknowledged)
-  Session->>RunV2: same message, replayed on boot
-  RunV2-->>Transport: response stream (same session.out)
+  RunV1-->>Transport: trigger:upgrade-required
+  RunV1->>RunV1: exit (run() never called)
+  Transport->>RunV2: trigger new run (continuation, same message)
+  RunV2-->>Transport: response stream
   Transport-->>User: response (seamless)
 ```
 
@@ -136,13 +103,6 @@ This pattern is useful when:
 
 ## Auto-detect from build ID (Next.js / Vercel)
 
-<Warning>
-  You probably don't need this any more. If your sessions are pinned, following the pin is the
-  built-in behaviour and it needs no `clientData` and no `chat.local`. Reach for the recipe below
-  only when you want to upgrade on a signal the pin doesn't carry — a frontend build id that moves
-  independently of the deployment your app names.
-</Warning>
-
 For automatic upgrade on every deploy, pass your platform's build ID via `clientData` instead of a manual version. The agent stores the ID from the first message and upgrades when it changes:
 
 ```tsx title="app/components/Chat.tsx"
@@ -191,38 +151,6 @@ export const myChat = chat
 
 This upgrades on **every** deploy, not just breaking changes. Good for fast-moving projects where you always want the latest code.
 
-## Staying put
-
-A pinned session follows its pin by default. To keep one agent where it is — a long tool chain you
-don't want interrupted, or a conversation you'd rather move on your own terms — set `versionSkew`:
-
-```ts
-export const myChat = chat.agent({
-  id: "my-chat",
-  versionSkew: "hold",
-  run: async ({ messages, signal }) => { ... },
-});
-```
-
-`"hold"` only stops the automatic handoff. `chat.requestUpgrade()` still works, so you can keep the
-decision and still get the seamless swap.
-
-Two cases never hand over automatically, whatever `versionSkew` says:
-
-- **A session with no pin.** There is nothing to compare against, and an unpinned session already
-  lands on the current version every time it starts a run.
-- **A session using `lockToVersion`.** That pin outranks the external deployment id and
-  `chat.requestUpgrade()` cannot escape it, so handing over would land on the same version and
-  repeat.
-
-<Note>
-  Following the pin costs one session read per turn on pinned chats, and the handoff happens at a
-  turn boundary — never mid-turn. If the pin names a deployment that hasn't landed yet, the successor
-  parks: your messages stay durable, and the transport emits `run-pending-version` with
-  `source: "upgrade"` so you can say so in the UI. See [parked
-  chats](/deployment/version-skew-protection#chat-sessions).
-</Note>
-
 ## Custom agents
 
 Use `chat.requestUpgrade()` with `chat.agent()`. With `chat.createSession()`, call `chat.requestUpgrade()`, then advance the iterator once more so it can exit normally. For an immediate handoff, close the iterator before calling `chat.endAndContinue()`. In a fully hand-rolled `chat.customAgent()` task, detach input listeners, persist the completed turn, write its boundary, then call `chat.endAndContinue()` and return immediately:
@@ -238,7 +166,7 @@ await chat.endAndContinue();
 return;
 ```
 
-The continuation uses the same durable Session and receives `.in` records that the old run has not consumed. It starts on the latest deployed task version only if the Session is unpinned — a Session carrying `lockToVersion` or an `externalDeploymentId` re-applies that pin, so the continuation lands where the Session says rather than on the newest build.
+The continuation uses the same durable Session and receives `.in` records that the old run has not consumed. It starts on the latest deployed task version unless the Session's trigger configuration sets `lockToVersion`.
 
 If input has been dispatched to the old run but should be processed by the continuation, detach the old listeners and skip the final `chat.writeTurnComplete()`. A turn-complete boundary acknowledges the latest input dispatched to the old run, so writing one after that dispatch would cause the continuation to resume past the input.
 
@@ -254,7 +182,6 @@ Both are graceful exits. [`onRecoveryBoot`](/ai-chat/patterns/recovery-boot) doe
 
 ## See also
 
-- [Version skew protection](/deployment/version-skew-protection#chat-sessions) — pin a session to the deployment matching the app build that started it
 - [Lifecycle hooks](/ai-chat/lifecycle-hooks) — where `onTurnStart` and `onChatResume` fit in the turn cycle
 - [Recovery boot](/ai-chat/patterns/recovery-boot) — the sibling hook for mid-stream interruptions (does NOT fire on `requestUpgrade`)
 - [Database persistence](/ai-chat/patterns/database-persistence) — how continuations interact with session state

package/docs/ai-chat/pending-messages.mdx

@@ -30,18 +30,18 @@ Add `pendingMessages` to your `chat.agent` configuration:
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { stepCountIs } from "ai";
+import { streamText, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 
 export const myChat = chat.agent({
   id: "my-chat",
-  registry,
   pendingMessages: {
     // Only inject when there are completed steps (tool calls happened)
     shouldInject: ({ steps }) => steps.length > 0,
   },
-  run: async ({ messages, signal, streamText }) => {
+  run: async ({ messages, signal }) => {
     return streamText({
+      ...chat.toStreamTextOptions({ registry }),
       messages,
       tools: { /* ... */ },
       abortSignal: signal,

package/docs/ai-chat/prompt-caching.mdx

@@ -16,7 +16,7 @@ A request renders as `tools` → `system` → `messages`. There are three prefix
 
 | Region | How to cache it | Stability |
 | --- | --- | --- |
-| System prompt (+ tools) | `cacheControl` / `systemProviderOptions` on `chat.agent()`, or `providerOptions` on `chat.prompt.set()` | Set once, never changes — the highest-value target |
+| System prompt (+ tools) | `cacheControl` / `systemProviderOptions` on `chat.toStreamTextOptions()`, or `providerOptions` on `chat.prompt.set()` | Set once, never changes — the highest-value target |
 | Conversation history | `prepareMessages` adds a breakpoint to the last message | Grows append-only across turns |
 | Tool definitions | Stable as long as your tool set doesn't change between turns | Render at position 0 — changing them invalidates everything |
 
@@ -32,22 +32,23 @@ The system prompt (your `chat.prompt` text plus any skills preamble) is usually
 
 Three ways to opt in, depending on where you'd rather express it.
 
-**`cacheControl` on the agent** — the Anthropic-flavored one-liner:
+**`cacheControl` at the `streamText` call site** — the Anthropic-flavored one-liner:
 
 ```ts /trigger/chat.ts
 import { chat } from "@trigger.dev/sdk/ai";
+import { streamText } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 
 export const myChat = chat.agent({
   id: "my-chat",
-  cacheControl: { type: "ephemeral" },
   onChatStart: async () => {
     chat.prompt.set(SYSTEM_PROMPT); // a large, stable instruction block
   },
-  run: async ({ messages, signal, streamText }) => {
+  run: async ({ messages, signal }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-6"),
       // Caches the system block with a 5-minute breakpoint.
+      ...chat.toStreamTextOptions({ cacheControl: { type: "ephemeral" } }),
       messages,
       abortSignal: signal,
     });
@@ -58,19 +59,17 @@ export const myChat = chat.agent({
 **`systemProviderOptions`** is the provider-agnostic form — pass the raw `providerOptions` so it composes with any provider:
 
 ```ts /trigger/chat.ts
-export const myChat = chat.agent({
-  id: "my-chat",
-  systemProviderOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
-  run: async ({ messages, signal, streamText }) =>
-    streamText({
-      model: anthropic("claude-sonnet-4-6"),
-      messages,
-      abortSignal: signal,
-    }),
+return streamText({
+  model: anthropic("claude-sonnet-4-6"),
+  ...chat.toStreamTextOptions({
+    systemProviderOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
+  }),
+  messages,
+  abortSignal: signal,
 });
 ```
 
-**`providerOptions` on `chat.prompt.set()`** co-locates the intent with where the prompt is defined. It carries through to the managed `streamText` with no call-site change:
+**`providerOptions` on `chat.prompt.set()`** co-locates the intent with where the prompt is defined. It carries through to `toStreamTextOptions()` with no call-site change:
 
 ```ts /trigger/chat.ts
 onChatStart: async () => {
@@ -78,16 +77,17 @@ onChatStart: async () => {
     providerOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
   });
 },
-run: async ({ messages, signal, streamText }) => {
+run: async ({ messages, signal }) => {
   return streamText({
     model: anthropic("claude-sonnet-4-6"),
+    ...chat.toStreamTextOptions(), // already cached
     messages,
     abortSignal: signal,
   });
 },
 ```
 
-If more than one is set, the most specific wins: `systemProviderOptions` overrides `cacheControl`, and both override `chat.prompt.set`'s `providerOptions`. There's no deep merge — the most specific option replaces the rest.
+If more than one is set, the call-site option wins: `systemProviderOptions` overrides `cacheControl`, and both override `chat.prompt.set`'s `providerOptions`. There's no deep merge — the most specific option replaces the rest.
 
 <Note>
   Use the 1-hour cache for prefixes that sit idle longer than 5 minutes between turns: `cacheControl: { type: "ephemeral", ttl: "1h" }`. Writes cost more (2× vs 1.25×), so it pays off only when reads span the longer window.
@@ -100,7 +100,6 @@ Place a breakpoint on the last message and the entire conversation prefix up to
 ```ts /trigger/chat.ts
 export const myChat = chat.agent({
   id: "my-chat",
-  cacheControl: { type: "ephemeral" },
   prepareMessages: async ({ messages }) => {
     if (messages.length === 0) return messages;
     const last = messages[messages.length - 1];
@@ -115,9 +114,10 @@ export const myChat = chat.agent({
       },
     ];
   },
-  run: async ({ messages, signal, streamText }) => {
+  run: async ({ messages, signal }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-6"),
+      ...chat.toStreamTextOptions({ cacheControl: { type: "ephemeral" } }),
       messages,
       abortSignal: signal,
     });
@@ -149,10 +149,11 @@ Caching is provider-specific, and most providers don't use per-block breakpoints
 
 ```ts /trigger/chat.ts
 // Amazon Bedrock
-export const myChat = chat.agent({
-  id: "my-chat",
-  systemProviderOptions: { bedrock: { cachePoint: { type: "default" } } },
-  run: async ({ messages, streamText }) => streamText({ messages }),
+return streamText({
+  ...chat.toStreamTextOptions({
+    systemProviderOptions: { bedrock: { cachePoint: { type: "default" } } },
+  }),
+  messages,
 });
 ```
 
@@ -165,13 +166,14 @@ Usage reporting is normalized. Each provider reports cache tokens under its own
 The turn's usage carries cache token counts. `chat.agent` accumulates them across turns and hands them to `run` as `previousTurnUsage` (last turn) and `totalUsage` (whole chat), both `LanguageModelUsage`:
 
 ```ts /trigger/chat.ts
-run: async ({ messages, signal, previousTurnUsage, streamText }) => {
+run: async ({ messages, signal, previousTurnUsage }) => {
   // After turn 1, cacheReadTokens should be > 0 on a stable prefix.
   console.log("cache read", previousTurnUsage?.inputTokenDetails?.cacheReadTokens);
   console.log("cache write", previousTurnUsage?.inputTokenDetails?.cacheWriteTokens);
 
   return streamText({
     model: anthropic("claude-sonnet-4-6"),
+    ...chat.toStreamTextOptions({ cacheControl: { type: "ephemeral" } }),
     messages,
     abortSignal: signal,
   });

package/docs/ai-chat/quick-start.mdx

@@ -16,16 +16,19 @@ The chat surface works with Vercel AI SDK **v5, v6, or v7**; install whichever m
 
     ```ts trigger/chat.ts
     import { chat } from "@trigger.dev/sdk/ai";
-    import { stepCountIs } from "ai";
+    import { streamText, stepCountIs } from "ai";
     import { anthropic } from "@ai-sdk/anthropic";
 
     export const myChat = chat.agent({
       id: "my-chat",
-      // `streamText` here is the SDK's, not the one from `ai`: it carries
-      // compaction, steering, background injection, the system prompt and
-      // telemetry, so none of them have to be wired up by hand.
-      run: async ({ messages, signal, streamText }) => {
+      run: async ({ messages, signal }) => {
         return streamText({
+          // Spread chat.toStreamTextOptions() FIRST — it wires up
+          // prepareStep (compaction, steering, background injection),
+          // the system prompt set via chat.prompt(), and telemetry.
+          // Skipping this is the single most common cause of subtle
+          // bugs (silent broken compaction, missing steering, etc.).
+          ...chat.toStreamTextOptions(),
           model: anthropic("claude-sonnet-4-5"),
           messages,
           abortSignal: signal,
@@ -35,12 +38,9 @@ The chat surface works with Vercel AI SDK **v5, v6, or v7**; install whichever m
     });
     ```
 
-    <Note>
-      Take `streamText` from `run`'s argument rather than importing it from `ai`. The
-      imported one drives no `prepareStep`, so compaction, mid-turn steering and
-      background injection never run, and nothing reports it. Spreading
-      `chat.toStreamTextOptions()` into the imported one does the same job by hand.
-    </Note>
+    <Warning>
+      **Always spread `chat.toStreamTextOptions()` into your `streamText` call.** It wires up the `prepareStep` callback that drives compaction, mid-turn steering, and background injection — features that silently no-op if the spread is missing. Spread it **first** so any explicit overrides (e.g. a custom `prepareStep`) win.
+    </Warning>
 
     <Tip>
       For a **custom** [`UIMessage`](https://sdk.vercel.ai/docs/reference/ai-sdk-core/ui-message) subtype (typed `data-*` parts, tool map, etc.), define the agent with [`chat.withUIMessage<...>().agent({...})`](/ai-chat/types) instead of `chat.agent`.

package/docs/ai-chat/reference.mdx

@@ -46,16 +46,12 @@ Options for `chat.agent()`.
 | `onValidateMessages`          | `(event: ValidateMessagesEvent) => UIMessage[] \| Promise<UIMessage[]>` | —                | Validate/transform UIMessages before model conversion. See [onValidateMessages](/ai-chat/lifecycle-hooks#onvalidatemessages) |
 | `hydrateMessages`             | `(event: HydrateMessagesEvent) => UIMessage[] \| Promise<UIMessage[]>` | —                 | Load message history from backend, replacing the linear accumulator. See [hydrateMessages](/ai-chat/lifecycle-hooks#hydratemessages) |
 | `actionSchema`                | `TaskSchema`                                                | —                              | Schema for validating custom actions sent via `transport.sendAction()`. See [Actions](/ai-chat/actions) |
-| `onAction`                    | `(event: ActionEvent) => Promise<void \| ActionTurn> \| void \| ActionTurn` | —                              | Handle custom actions. Actions are state edits: only `hydrateMessages` + `onAction` fire. Return `chat.turn()` to run a turn on the edited history, or nothing for an edit only. See [Actions](/ai-chat/actions) |
+| `onAction`                    | `(event: ActionEvent) => Promise<unknown> \| unknown`       | —                              | Handle custom actions. Actions are not turns — only `hydrateMessages` + `onAction` fire. Return a `StreamTextResult` (or `string` / `UIMessage`) for a model response; return `void` for side-effect-only. See [Actions](/ai-chat/actions) |
 | `onTurnStart`                 | `(event: TurnStartEvent) => Promise<void> \| void`          | —                              | Fires every turn before `run()`                                                                     |
 | `onBeforeTurnComplete`        | `(event: BeforeTurnCompleteEvent) => Promise<void> \| void` | —                              | Fires after response but before stream closes. Includes `writer`.                                   |
 | `onTurnComplete`              | `(event: TurnCompleteEvent) => Promise<void> \| void`       | —                              | Fires after each turn completes (stream closed)                                                     |
 | `onCompacted`                 | `(event: CompactedEvent) => Promise<void> \| void`          | —                              | Fires when compaction occurs. Includes `writer`. See [Compaction](/ai-chat/compaction)              |
 | `compaction`                  | `ChatAgentCompactionOptions`                                | —                              | Automatic context compaction. See [Compaction](/ai-chat/compaction)                                 |
-| `registry`                    | `{ languageModel(id: string): unknown }`                    | —                              | A provider registry, so the managed `streamText` can resolve a model set through `chat.prompt.set()` |
-| `system`                      | `string \| SystemModelMessage`                              | —                              | The agent's system prompt. Injected instructions append to it. Set it here, at the `streamText` call site, or through `chat.prompt.set()`, but only in one of them |
-| `cacheControl`                | `SystemCacheControl`                                        | —                              | Mark the system prompt for provider-side caching. See [Prompt caching](/ai-chat/prompt-caching) |
-| `systemProviderOptions`       | `ProviderMetadata`                                          | —                              | Raw provider options for the system block. Takes precedence over `cacheControl` |
 | `pendingMessages`             | `PendingMessagesOptions`                                    | —                              | Mid-execution message injection. See [Pending Messages](/ai-chat/pending-messages)                  |
 | `prepareMessages`             | `(event: PrepareMessagesEvent) => ModelMessage[]`           | —                              | Transform model messages before use (cache breaks, context injection, etc.)                         |
 | `tools`                       | `ToolSet \| ((event: ResolveToolsEvent) => ToolSet \| Promise<ToolSet>)` | —                 | Tools for this agent. Threads each tool's `toModelOutput` through cross-turn history re-conversion, and hands the resolved set back on the run payload. Static set or per-turn function. See [Tools](/ai-chat/tools). |
@@ -102,10 +98,9 @@ The payload passed to the `run` function.
 | `ctx`          | `TaskRunContext`                           | Full task run context — same as `task` `run`’s `{ ctx }`             |
 | `messages`     | `ModelMessage[]`                           | Model-ready messages — pass directly to `streamText`                 |
 | `tools`        | `ToolSet`                                  | Resolved tools declared on the agent config (empty object when none). Pass straight to `streamText`. See [Tools](/ai-chat/tools). |
-| `streamText`   | `typeof streamText`                        | The AI SDK's `streamText` with this agent's managed options already applied: the prompt, skill tools, telemetry, and the `prepareStep` that delivers steering, compaction and injected context. Prefer it over importing `streamText` from `ai`. See [The managed streamText](/ai-chat/backend#the-managed-streamtext). |
 | `chatId`       | `string`                                   | Your conversation ID (the session's `externalId`)                    |
 | `sessionId`    | `string`                                   | Friendly ID of the backing Session (`session_*`). Use with `sessions.open()` for advanced cases. Always set — every chat.agent run is bound to a Session. |
-| `trigger`      | `"submit-message" \| "regenerate-message" \| "action-turn"` | What triggered the request; `"action-turn"` is a turn requested by `chat.turn()` |
+| `trigger`      | `"submit-message" \| "regenerate-message"` | What triggered the request                                           |
 | `messageId`    | `string \| undefined`                      | Message ID (for regenerate)                                          |
 | `clientData`   | Typed by `clientDataSchema`                | Custom data from the frontend (typed when schema is provided)        |
 | `continuation` | `boolean`                                  | Whether this run is continuing an existing chat (previous run ended) |
@@ -495,9 +490,9 @@ Options for [`chat.headStart()`](/ai-chat/fast-starts#head-start), the warm-serv
 | `agentId`              | `string`                                                | required    | The `chat.agent` / `chat.customAgent` id to hand off to                                              |
 | `run`                  | `(args: HeadStartRunArgs) => Promise<StreamTextResult>` | required    | First-turn callback. Call `streamText` and spread `chat.toStreamTextOptions({ tools })`              |
 | `idleTimeoutInSeconds` | `number`                                                | `60`        | How long the agent waits for the handover signal                                                     |
-| `triggerConfig`        | `Partial<SessionTriggerConfig>`                         | `undefined` | Run options (tags, queue, machine, maxAttempts, maxDuration, region, lockToVersion, externalDeploymentId) for the auto-triggered handover-prepare run. The `chat:{chatId}` tag is prepended automatically and counts toward the 10-tag limit |
+| `triggerConfig`        | `Partial<SessionTriggerConfig>`                         | `undefined` | Run options (tags, queue, machine, maxAttempts, maxDuration, region, lockToVersion) for the auto-triggered handover-prepare run. The `chat:{chatId}` tag is prepended automatically and counts toward the 10-tag limit |
 
-`chat.headStart(options)` returns the handler `(req: Request) => Promise<Response>`. The `run` callback receives `HeadStartRunArgs`: `{ messages: UIMessage[], signal: AbortSignal, chat: HeadStartChatHelper }`, where the helper exposes `chat.toStreamTextOptions({ tools })` and a `chat.session` escape hatch (whose `pendingVersion` says whether the agent run is parked waiting for its deployment). See [Head Start](/ai-chat/fast-starts#head-start) for the full guide.
+`chat.headStart(options)` returns the handler `(req: Request) => Promise<Response>`. The `run` callback receives `HeadStartRunArgs`: `{ messages: UIMessage[], signal: AbortSignal, chat: HeadStartChatHelper }`, where the helper exposes `chat.toStreamTextOptions({ tools })` and a `chat.session` escape hatch. See [Head Start](/ai-chat/fast-starts#head-start) for the full guide.
 
 ## chat namespace
 
@@ -516,7 +511,6 @@ All methods available on the `chat` object from `@trigger.dev/sdk/ai`.
 | `chat.createStartSessionAction(taskId, options?)` | Returns a server action that creates a chat Session + triggers the first run + returns a session-scoped PAT. Idempotent on `(env, externalId)`.   |
 | `chat.waitForHandover(options)`             | Wait for a [`chat.headStart`](/ai-chat/fast-starts#handover-with-custom-agents) handover signal in a custom loop. Returns the signal or `null`. `chat.MessageAccumulator` wraps this as `consumeHandover()` / `applyHandover()` |
 | `chat.requestUpgrade()`                     | End the current run after this turn so the next message starts on the latest agent version. Server-orchestrated handoff.    |
-| `chat.close({ reason })`                    | End the conversation permanently: close the session row, write a terminal `session-closed` record, and exit without a continuation. Decide it before the turn ends (`onBeforeTurnComplete`, not `onTurnComplete`) so the client sees the closed state on that turn. |
 | `chat.endAndContinue()`                     | In a hand-rolled custom agent, hand off the Session to a fresh continuation run. Call between turns after detaching input listeners, then return immediately. The promise rejects if the handoff fails. |
 | `chat.setTurnTimeout(duration)`             | Override turn timeout at runtime (e.g. `"2h"`)                                                                               |
 | `chat.setTurnTimeoutInSeconds(seconds)`     | Override turn timeout at runtime (in seconds)                                                                                |
@@ -665,7 +659,6 @@ The `onEvent` callback receives a `ChatTransportEvent` (exported from `@trigger.
 | --- | --- | --- |
 | `message-sent` | `messageId?`, `source`, `durationMs`, `partId?`, `bodyBytes?` | A send was durably acknowledged — a 2xx from the session input stream append (or the `headStart` POST), after any internal token-refresh retries. This means the message is durably written to the stream the agent consumes from, not merely "request accepted". `partId` is the append's idempotency key, also stored on the server-side record. |
 | `message-send-failed` | `messageId?`, `source`, `error`, `status?`, `durationMs`, `partId?`, `bodyBytes?` | A send definitively failed after internal retries. Fires in addition to `useChat`'s `onError`. |
-| `run-pending-version` | `source` | The chat's run is parked waiting for the deployment carrying its external deployment id ([version skew protection](/deployment/version-skew-protection#chat-sessions)). Everything already sent is durable and answered once the deployment lands. `source` is `"start"` (learned while starting the session), `"send"` (from a message append, re-emitted on every send while parked) `"head-start"` (from the `headStart` POST, where step 1 still streams from your server and only step 2 waits) or `"upgrade"` (an automatic version handover whose successor is parked on a deployment that has not landed). |
 | `stream-connected` | `resumed`, `lastEventId?`, `messageId?` | The SSE subscription to the session's output stream started delivering. `resumed: true` when reconnecting from a stored cursor (page reload) rather than following a fresh send. `lastEventId` is the cursor it connected from. |
 | `first-chunk` | `chunkType?`, `lastEventId?`, `messageId?`, `sinceSendMs?` | The first response chunk of a turn arrived. `sinceSendMs` is the delta from the last turn-producing send — time to first token without any bookkeeping. |
 | `turn-completed` | `lastEventId?`, `sessionInEventId?`, `messageId?`, `sinceSendMs?` | The agent's turn-complete control record arrived — the "finished answering" signal. `sinceSendMs` is the full turn latency; `sessionInEventId` is the cursor the agent can safely resume its input stream from. Treat it as a lower bound: it is held back behind any message still waiting to be handled, so it can be below the sequence of the record this turn answered. Do not use it to decide whether a turn boundary belongs to your own send. |
@@ -801,7 +794,7 @@ See [Stop generation](/ai-chat/frontend#stop-generation) for full details.
 
 ### transport.sendAction()
 
-Send a custom action to the agent, outside `useChat`. Actions wake the agent from suspension and fire `onAction`. An action that returns `chat.turn()` is followed by a turn; its answer arrives on the returned stream, which the caller must read. From a `useChat` app, send actions as requests instead (`sendMessage(undefined, { body: { action } })` or the `useChatActions` hook) so `useChat` renders the answer.
+Send a custom action to the agent. Actions wake the agent from suspension and fire `onAction`. They are not turns — `run()` and turn lifecycle hooks do not fire. If `onAction` returns a `StreamTextResult`, the response is auto-piped to the frontend.
 
 ```ts
 transport.sendAction(chatId: string, action: unknown): Promise<ReadableStream<UIMessageChunk>>

package/docs/ai-chat/sessions.mdx

@@ -111,7 +111,7 @@ const { id, runId, publicAccessToken, isCached } = await sessions.start({
 | `type` | `string` | Free-form discriminator. `chat.agent` uses `"chat.agent"`. |
 | `externalId` | `string?` | Your stable identity. Cannot start with `session_` (reserved). |
 | `taskIdentifier` | `string` | Task this session triggers runs against. |
-| `triggerConfig` | `SessionTriggerConfig` | Trigger options applied to every run: `tags` (up to 10, same as [run tags](/tags); the chat helpers such as `chat.createStartSessionAction` and `AgentChat` add a `chat:{chatId}` tag themselves, which uses one slot. Direct `sessions.start` callers get all 10 and must add any chat tag themselves), `queue`, `machine`, `maxAttempts`, `maxDuration`, `region`, `idleTimeoutInSeconds`, `basePayload`, and the version pins `lockToVersion` / [`externalDeploymentId`](/deployment/version-skew-protection#chat-sessions). |
+| `triggerConfig` | `SessionTriggerConfig` | Trigger options applied to every run: `tags` (up to 10, same as [run tags](/tags); the chat helpers such as `chat.createStartSessionAction` and `AgentChat` add a `chat:{chatId}` tag themselves, which uses one slot. Direct `sessions.start` callers get all 10 and must add any chat tag themselves), `queue`, `machine`, `maxAttempts`, `idleTimeoutInSeconds`, `basePayload`. |
 | `tags` | `string[]?` | Up to 10 tags on the Session row (separate from `triggerConfig.tags`). |
 | `metadata` | `Record<string, unknown>?` | Arbitrary JSON. |
 | `expiresAt` | `Date?` | Hard retention deadline. |
@@ -146,11 +146,6 @@ Mark a Session as closed. Terminal and idempotent. The optional `reason` is stor
 await sessions.close(chatId, { reason: "user signed out" });
 ```
 
-Closing tells a live run too: the close lands on the session's input channel, so an idle or suspended agent exits its loop on the next wake rather than waiting out its idle timeout. After it lands, appends to `.in` are refused with HTTP 409 and `code: "session_closed"`.
-
-To close from inside the agent instead, call [`chat.close()`](/ai-chat/backend#ending-the-conversation). It writes a terminal record to the response stream so the browser learns the reason, then closes the row.
-
-
 ### `sessions.list(options?, requestOptions?)`
 
 Cursor-paginated list of Sessions in the current environment. Returns a `CursorPagePromise` you can iterate with `for await`.

package/docs/ai-chat/testing.mdx

@@ -203,7 +203,7 @@ Equivalent to the frontend's `useChat().regenerate()` — replays a turn with th
 
 ### sendAction
 
-Routes a payload through `actionSchema` + `onAction`. An action is a state edit: only `hydrateMessages` and `onAction` fire, unless `onAction` returns `chat.turn()`, in which case a turn runs on the edited history and the returned `turn.rawChunks` carries that turn's answer.
+Routes a payload through `actionSchema` + `onAction`. Actions are not turns: only `hydrateMessages` and `onAction` fire on the agent side — no turn lifecycle hooks, no `run()`. The returned `turn.rawChunks` contains whatever `onAction` produced (a streamed model response if it returned a `StreamTextResult`, otherwise just `trigger:turn-complete`):
 
 ```ts
 const turn = await harness.sendAction({ type: "undo" });
@@ -634,7 +634,6 @@ The harness's initial wire payload depends on `mode`:
 | `sendHandover({ partialAssistantMessage, isFinal?, messageId? })` | Dispatch a `handover` signal — only meaningful when started with `mode: "handover-prepare"`. The agent picks up partial assistant messages and continues the turn. |
 | `sendHandoverSkip()`                  | Dispatch a `handover-skip` signal — only meaningful when started with `mode: "handover-prepare"`. The agent exits cleanly without firing turn hooks. |
 | `sendAction(action)`                  | Route a custom action through `actionSchema` + `onAction`.                                             |
-| `sendPendingMessage(message)`         | Append a user message mid-turn without waiting for a turn to complete, so it reaches the running turn as a steering message. Resolves once the record has landed on `session.in`. |
 | `sendStop(message?)`                  | Fire a stop signal. Does not wait for the turn — the run's `signal.aborted` becomes `true`.            |
 | `seedSnapshot(snapshot)`              | Pre-seed the snapshot read for the next boot. Effective on the next run boot only.                     |
 | `seedSessionOutTail(chunks?)`         | Pre-seed `session.out` chunks for the next boot's replay. Reduces to settled assistant turns.          |

package/docs/ai-chat/tools.mdx

@@ -8,7 +8,7 @@ description: "Declare tools on chat.agent so toModelOutput survives across turns
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { stepCountIs, tool } from "ai";
+import { streamText, stepCountIs, tool } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 
@@ -23,9 +23,9 @@ const tools = {
 export const myChat = chat.agent({
   id: "my-chat",
   tools, // ← declare here
-  run: async ({ messages, tools, signal, streamText }) =>
+  run: async ({ messages, tools, signal }) =>
     streamText({
-      tools,
+      ...chat.toStreamTextOptions({ tools }), // ← the same set, handed back on the payload
       model: anthropic("claude-sonnet-4-5"),
       messages,
       abortSignal: signal,
@@ -46,15 +46,10 @@ There are three places a tool set shows up. Declare once, reuse:
 | Surface | What it's for |
 | --- | --- |
 | `chat.agent({ tools })` | Re-applies `toModelOutput` on prior-turn history; hands the set back typed on the `run()` payload. |
-| `streamText({ tools })` on the `run` argument's `streamText` | What the model actually calls. Detects which calls need [HITL approval](/ai-chat/patterns/human-in-the-loop) (`needsApproval`) and merges the auto-injected [skill](/ai-chat/patterns/skills) tools on top. Naming `tools` replaces the config set for that call, so you can narrow it; omitting `tools` falls back to the config set. |
-| `chat.toStreamTextOptions({ tools })` | The same job by hand, for a [custom agent](#manual-turn-loops-chatcustomagent), which has no `run` argument. |
+| `chat.toStreamTextOptions({ tools })` | Detects which tool calls need [HITL approval](/ai-chat/patterns/human-in-the-loop) (`needsApproval`) and merges any auto-injected [skill](/ai-chat/patterns/skills) tools. |
+| `streamText({ tools })` | What the model actually calls. `chat.toStreamTextOptions({ tools })` already sets this, so spread it instead of passing `tools` twice. |
 
-The canonical pattern: declare `tools` on the config, read them back from the `run()` payload, and pass that set to the `streamText` the payload also carries.
-
-```ts
-run: async ({ messages, tools, signal, streamText }) =>
-  streamText({ model, messages, tools, abortSignal: signal }),
-```
+The canonical pattern: declare `tools` on the config, read them back from the `run()` payload, and pass that to `chat.toStreamTextOptions({ tools })`. One declaration flows everywhere.
 
 <Tip>
   Conversion only reads each tool's `inputSchema` and `toModelOutput`, never `execute`. If you keep heavy `execute` dependencies out of a module (for bundle reasons), you can declare a lightweight schema-only tool map on the config and add the executes where you call `streamText`.
@@ -85,9 +80,9 @@ const tools = {
 export const chartChat = chat.agent({
   id: "chart-chat",
   tools, // ← without this, the image is "remembered" on turn 1 and gone from turn 2
-  run: async ({ messages, tools, signal, streamText }) =>
+  run: async ({ messages, tools, signal }) =>
     streamText({
-      tools,
+      ...chat.toStreamTextOptions({ tools }),
       model: anthropic("claude-sonnet-4-5"),
       messages,
       abortSignal: signal,
@@ -109,9 +104,9 @@ export const myChat = chat
       searchDocs,
       ...(clientData?.plan === "pro" ? { deepResearch } : {}),
     }),
-    run: async ({ messages, tools, signal, streamText }) =>
+    run: async ({ messages, tools, signal }) =>
       streamText({
-        tools,
+        ...chat.toStreamTextOptions({ tools }),
         model: anthropic("claude-sonnet-4-5"),
         messages,
         abortSignal: signal,
@@ -136,10 +131,10 @@ The resolved set is what lands on the `run()` payload's `tools`.
 The `run()` payload's `tools` is typed to whatever you declared, so you can pass it straight through without re-importing the map:
 
 ```ts
-run: async ({ messages, tools, signal, streamText }) => {
+run: async ({ messages, tools, signal }) => {
   // `tools` is typed as your tool set, not a broad `ToolSet`
   return streamText({
-    tools,
+    ...chat.toStreamTextOptions({ tools }),
     model: anthropic("claude-sonnet-4-5"),
     messages,
     abortSignal: signal,
@@ -165,7 +160,7 @@ This is shorthand for `UIMessage<unknown, UIDataTypes, InferUITools<typeof tools
 
 ## Skills
 
-[Agent skills](/ai-chat/patterns/skills) are auto-injected as tools (`loadSkill`, `readFile`, `bash`) by the managed `streamText`, or by `chat.toStreamTextOptions()` if you build the options yourself. They're separate from your config `tools`: declare your own tools on the config (so their `toModelOutput` survives across turns), and the merge happens at call time. Skill tools don't define `toModelOutput`, so they don't need to be on the config.
+[Agent skills](/ai-chat/patterns/skills) are auto-injected as tools (`loadSkill`, `readFile`, `bash`) by `chat.toStreamTextOptions()`. They're separate from your config `tools`: declare your own tools on the config (so their `toModelOutput` survives across turns), and let `toStreamTextOptions` merge the skill tools on top at call time. Skill tools don't define `toModelOutput`, so they don't need to be on the config.
 
 ## Manual turn loops (`chat.customAgent`)
 

package/docs/ai-chat/upgrade-guide.mdx

@@ -298,8 +298,8 @@ and direct API consumers.
   fire at the same lifecycle points.
 - `onAction` is still defined the same way, but its semantics changed
   in the [May 6 prerelease](/ai-chat/changelog) — actions are no longer
-  turns. To answer after an action's edit, return `chat.turn()`; returning
-  a `StreamTextResult` is no longer supported.
+  turns, and `onAction` returning a `StreamTextResult` produces a model
+  response.
 - `chat.customAgent({...})` and the `chat.createSession(payload, ...)`
   helper for building a session loop manually inside a custom agent.
 - `chat.defer` (deferred work) and `chat.history` (imperative history