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

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

@@ -56,7 +56,7 @@ Then make these changes:
 - Create a `chat.agent` task in `trigger/chat.ts`. Move the existing `streamText` call
   into its `run` function UNCHANGED — same model, same `system`, same `temperature`,
   same `stopWhen`, same provider options. Do not rewrite the prompt or swap the model.
-- Take `streamText` from the `run` argument, so the managed options apply to that
+- Spread `...chat.toStreamTextOptions({ tools })` as the FIRST property of that
   `streamText` call, so the explicit options after it still win.
 - `run` receives `ModelMessage[]` already. Delete the `convertToModelMessages` call.
 - Forward the `signal` from `run` as `abortSignal` so Stop works.
@@ -145,9 +145,10 @@ import { tools } from "@/lib/tools";
 export const myChat = chat.agent({
   id: "my-chat",
   tools,
-  run: async ({ messages, tools, signal, streamText }) =>
+  run: async ({ messages, tools, signal }) =>
     streamText({
-      tools,
+      // Spread first, so every option below still wins.
+      ...chat.toStreamTextOptions({ tools }),
       model: anthropic("claude-sonnet-4-5"),
       system: "You are a helpful assistant.",
       messages,
@@ -162,10 +163,10 @@ Four things changed inside the `streamText` call, and `tools` moved onto the age
 - **`messages` arrives as `ModelMessage[]`.** The runtime converts the frontend's `UIMessage[]` for you, so `convertToModelMessages` is gone.
 - **`abortSignal` comes from `signal` on the payload**, not `req.signal`. It fires on stop and on cancel.
 - **Return the `StreamTextResult`.** It's piped to the frontend automatically — no `toUIMessageStreamResponse`. If `streamText` is buried in a helper, call `await chat.pipe(result)` from anywhere in the task instead and let `run` resolve `void`.
-- **`streamText` comes from the `run` argument, not from `ai`.** It carries the `prepareStep` behind [compaction](/ai-chat/compaction), [mid-turn steering](/ai-chat/pending-messages) and [background injection](/ai-chat/background-injection), plus the system prompt set via [`chat.prompt()`](/ai-chat/backend#using-prompts) and telemetry.
+- **`...chat.toStreamTextOptions()` is spread first.** It wires up the `prepareStep` callback behind [compaction](/ai-chat/compaction), [mid-turn steering](/ai-chat/pending-messages), and [background injection](/ai-chat/background-injection), plus the system prompt set via [`chat.prompt()`](/ai-chat/backend#using-prompts) and telemetry.
 
 <Warning>
-  Importing `streamText` from `ai` instead throws no error: compaction, steering and background injection never run. Spreading `chat.toStreamTextOptions()` into the imported one is the equivalent, and is what a custom agent has to do, since it has no `run` argument. A `chat.headStart` route gets a bound `streamText` of its own.
+  Omitting `...chat.toStreamTextOptions()` throws no error — compaction, steering, and background injection just silently never run. Spread it first so any explicit override you write after it takes precedence.
 </Warning>
 
 There's no `maxDuration` equivalent to set. A turn isn't bounded by a function timeout; a run stays alive across turns and suspends when nothing is happening.
@@ -356,9 +357,9 @@ export const myChat = chat.agent({
       }),
     ]);
   },
-  run: async ({ messages, tools, signal, streamText }) =>
+  run: async ({ messages, tools, signal }) =>
     streamText({
-      tools,
+      ...chat.toStreamTextOptions({ tools }),
       model: anthropic("claude-sonnet-4-5"),
       system: "You are a helpful assistant.",
       messages,
@@ -467,21 +468,18 @@ Head Start brings the route handler back for exactly that first turn. It runs st
 
     export const chatHandler = chat.headStart({
       agentId: "my-chat",
-      run: async ({ streamText }) =>
+      run: async ({ chat: helper }) =>
         streamText({
+          ...helper.toStreamTextOptions({ tools: headStartTools }),
           model: anthropic("claude-sonnet-4-5"),
           system: "You are a helpful assistant.",
-          tools: headStartTools,
         }),
     });
     ```
 
-    <Note>
-      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.
-    </Note>
+    <Warning>
+      Spread `toStreamTextOptions()` first and add only your own keys after it. It owns `messages`, `tools`, `abortSignal`, and `stopWhen` — and unlike the agent-side spread, re-setting any of those breaks the handover rather than degrading it. `stopWhen` in particular is pinned to `stepCountIs(1)`: the agent, not the handler, runs step 2 onward.
+    </Warning>
 
     Your provider keys never leave your server — the first-turn model call runs in your process, so that environment needs whatever the model requires.
   </Step>
@@ -560,7 +558,7 @@ The shape is identical outside Next.js. The agent task and the React component d
 
 **The head-start route dies mid-turn on Vercel.** The handler holds the SSE response open until the agent signals turn-complete, so the function timeout has to cover the whole turn, not just step 1. Set `maxDuration` on that route segment.
 
-**Compaction and steering do nothing.** `run` is calling the `streamText` imported from `ai` rather than the one in its argument. Destructure `streamText` from the `run` argument, or spread `chat.toStreamTextOptions()` into the imported one.
+**Compaction and steering do nothing.** The `...chat.toStreamTextOptions()` spread is missing, or something before it in the object is overwriting `prepareStep`. Spread it as the first property.
 
 **`toModelOutput` works on the first turn, then stops.** Tools are declared only on `streamText`. Declare the same set on `chat.agent({ tools })` too, and read it back off the `run` payload.
 

package/docs/ai-chat/patterns/database-persistence.mdx

@@ -9,10 +9,6 @@ Durable chat runs can span **hours** and **many turns**. You usually want:
 1. **Conversation state** — full **`UIMessage[]`** (or equivalent) keyed by **`chatId`**, so reloads and history views work.
 2. **Live session state** — a **scoped access token** for the session and optionally **`lastEventId`** for stream resume.
 
-<Note>
-  You can persist the conversation state through a [transcript storage](/ai-chat/transcript-storage) on the agent rather than the hook mapping below. Give `chat.agent` a `storage` that writes to your database and the runtime hands it every change (a new message, an undo, a regenerate, a compaction) as it happens, with the resume cursors, and reads it back when a run continues. Your own database is then the transcript. The hook mapping below still works, and it is the way to persist the live session state (the access token) and anything the transcript does not cover.
-</Note>
-
 This page describes a **hook mapping** that works with any database. Adapt table and column names to your stack.
 
 ## Conceptual data model
@@ -171,9 +167,9 @@ chat.agent({
 });
 ```
 
-## Alternative: `hydrateMessages` (deprecated)
+## Alternative: `hydrateMessages`
 
-For apps that need the backend to be the single source of truth for message history — abuse prevention, branching conversations, or rollback support — the recommended path is a [transcript storage](/ai-chat/transcript-storage#owning-the-models-context) with `loadContext`. The deprecated [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) hook does the same job without the runtime writing to your store.
+For apps that need the backend to be the single source of truth for message history — abuse prevention, branching conversations, or rollback support — use [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) instead of relying on the frontend's accumulated state.
 
 With hydration, the hook loads messages from your database on every turn. The frontend's messages are ignored (except for the new user message, which arrives in `incomingMessages`):
 

package/docs/ai-chat/patterns/persistence-and-replay.mdx

@@ -1,12 +1,12 @@
 ---
 title: "Persistence and replay"
 sidebarTitle: "Persistence and replay"
-description: "How chat.agent rebuilds conversation history at run boot — the transcript storage's persisted conversation plus session.out replay, and what changes when your app owns the model's context."
+description: "How chat.agent rebuilds conversation history at run boot — durable JSON snapshot in object storage plus session.out replay, with a hydrateMessages short-circuit for backend-owned history."
 ---
 
 `chat.agent` runs are processes — they boot, stream a turn, and either suspend (waiting for the next message) or exit. When the next message arrives at a session whose previous run already exited, a **fresh** run boots with no in-memory state. Something has to rebuild the conversation history before that turn can produce a coherent response.
 
-This page walks through the **storage + replay** model. The persisted conversation comes from the agent's [transcript storage](/ai-chat/transcript-storage); the default storage is the snapshot in object storage described below, and a storage you bring is read the same way. Replay of the session streams covers what happened after the last save, and it runs for every agent, including one that owns the model's context.
+This page walks through the **snapshot + replay** model the runtime uses by default, and the [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) short-circuit that turns the whole thing off when the customer owns history.
 
 ## Why a snapshot at all
 
@@ -32,7 +32,7 @@ sequenceDiagram
   User->>Run1: u1
   Run1->>SessionOut: assistant chunks for a1
   Run1->>Run1: onTurnComplete
-  Run1->>Snapshot: write { messages: [u1, a1], lastOutEventId, lastInEventId }
+  Run1->>Snapshot: write { messages: [u1, a1], lastOutEventId, lastOutTimestamp }
   Note over Run1: idle suspend (or exit)
 
   User->>Run2: u2 (delta only)
@@ -52,21 +52,15 @@ The accumulator starts empty. The wire delivers `u1`. After the model finishes,
 
 ```json
 {
-  "version": 2,
+  "version": 1,
   "savedAt": 1715180400000,
-  "messages": [
-    { "id": "u1", "final": true, "message": u1 },
-    { "id": "a1", "final": true, "message": a1 }
-  ],
-  "state": null,
+  "messages": [u1, a1],
   "lastOutEventId": "42",
-  "lastInEventId": "7"
+  "lastOutTimestamp": 1715180399000
 }
 ```
 
-`state` holds what the runtime cannot rebuild from the messages, such as a [compaction](/ai-chat/compaction) summary; `final` is false for a partial answer captured from a failed turn. Snapshots written by older SDK versions have `version: 1` and are read as if every message were final with no state.
-
-The key is `packets/{projectRef}/{envSlug}/sessions/{sessionId}/snapshot.json` — overwritten every turn, never appended. With your own storage, the equivalent is whatever `save` writes: the runtime hands it the two new messages as `put` changes and the same cursors, and a row-per-message store writes two rows instead of the whole conversation. The write is **awaited**, not fire-and-forget — if the run idle-suspends immediately after, in-flight promises don't reliably complete and the snapshot would be lost.
+The key is `packets/{projectRef}/{envSlug}/sessions/{sessionId}/snapshot.json` — overwritten every turn, never appended. The write is **awaited**, not fire-and-forget — if the run idle-suspends immediately after, in-flight promises don't reliably complete and the snapshot would be lost.
 
 ### Run 2 — boot
 
@@ -116,25 +110,21 @@ Replay carries the conversation across the crash boundary with zero customer cod
 
 ## OOM-retry interaction
 
-The runtime already had an OOM-retry path that scans `session.out` for the latest `trigger:turn-complete` timestamp to use as a cutoff for `session.in` (so the retry doesn't re-process completed turns — see [OOM resilience](/ai-chat/patterns/oom-resilience)). The snapshot's `lastInEventId` field is exactly that committed `.in` cursor.
+The runtime already had an OOM-retry path that scans `session.out` for the latest `trigger:turn-complete` timestamp to use as a cutoff for `session.in` (so the retry doesn't re-process completed turns — see [OOM resilience](/ai-chat/patterns/oom-resilience)). The snapshot includes a `lastOutTimestamp` field that is exactly that high-water mark.
 
-When a snapshot exists, the OOM-retry path reads `lastInEventId` directly instead of scanning `session.out`. One fewer stream subscription per retry. Free win.
+When a snapshot exists, the OOM-retry path reads `lastOutTimestamp` directly instead of scanning `session.out`. One fewer stream subscription per retry. Free win.
 
 If no snapshot exists (first turn, or `hydrateMessages` registered), the path falls back to the scan.
 
-## Action turns
-
-[Actions](/ai-chat/actions) (`trigger: "action"`) don't fire `onTurnComplete` — they fire `onAction` only. An action that changed the conversation is saved on its own, with `reason: "action"` and the same resume cursors as the last turn, so an undo survives the run ending. See [Actions and persistence](/ai-chat/actions#actions-and-persistence).
-
-## When your app owns the model's context
+## Action turns — no snapshot write
 
-A storage with [`loadContext`](/ai-chat/transcript-storage#owning-the-models-context), or the deprecated [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) hook, decides what the model sees on every turn instead of the runtime's accumulated transcript. That changes the boot sequence in one place: with `hydrateMessages` the storage read is skipped, because the hook is the source of truth. Everything else still runs. The `session.out` and `session.in` tails are replayed, a partial answer and unacknowledged messages are recovered, and `onRecoveryBoot` fires. The hook then receives the recovered tail in `previousMessages`, so it can persist an answer a crashed run had already started.
+[Action turns](/ai-chat/actions) (`trigger: "action"`) don't fire `onTurnComplete` — they fire `onAction` only. The snapshot write site is gated on `onTurnComplete`, so action turns don't snapshot.
 
-With `loadContext` on a storage, the storage is still read and written: `load` restores the cursors and the runtime's `state` (a compaction summary survives), `save` still receives every change, and only the model's context comes from `loadContext`.
+If `onAction` mutates `chat.history.*` and then the run crashes before the next regular turn, the mutation is lost. The user re-fires the action. This matches `chat.history` semantics in general — mutations are persisted at turn boundaries, not action boundaries.
 
-### The `hydrateMessages` hook
+## The `hydrateMessages` short-circuit
 
-When the customer registers a [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) hook, the runtime trusts the hook to be the source of truth for history. The snapshot is neither read nor written. The hook fires per turn, returns the canonical chain from the customer's database, and the accumulator is set to whatever the hook returned.
+When the customer registers a [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) hook, the runtime trusts the hook to be the source of truth for history. Snapshot read and replay are **skipped entirely** at boot. The hook fires per turn, returns the canonical chain from the customer's database, and the accumulator is set to whatever the hook returned.
 
 ```ts
 import { chat, upsertIncomingMessage } from "@trigger.dev/sdk/ai";
@@ -170,24 +160,24 @@ export const myChat = chat.agent({
 
 What you gain:
 
-- **Zero object-store traffic per turn.** No snapshot read, no snapshot write. `OBJECT_STORE_*` env vars don't have to be set.
+- **Zero object-store traffic per turn.** No snapshot read, no snapshot write, no replay subscription. `OBJECT_STORE_*` env vars don't have to be set.
 - **Branching, undo, edit, abuse prevention** — patterns that need a backend-side single source of truth work naturally because the customer mediates every read.
 
 What you give up:
 
-- **You own persistence end-to-end.** A bug in `hydrateMessages` that returns the wrong chain corrupts the conversation visible to the model, and a compaction summary has nowhere durable to live.
-- **OOM-retry needs a `session.out` scan again** because there's no snapshot to short-circuit it.
+- **You own persistence end-to-end.** A bug in `hydrateMessages` that returns the wrong chain corrupts the conversation visible to the model.
+- **OOM-retry needs a `session.out` scan again** because there's no snapshot to short-circuit it. (Same as the pre-snapshot baseline — not a regression, just a missed optimization.)
 
-A [transcript storage](/ai-chat/transcript-storage) with `loadContext` gives you the same ownership of the model's context while the runtime keeps writing every change and its own state to your store. It is the recommended path; `hydrateMessages` is deprecated.
+The runtime's snapshot+replay is the safer default. `hydrateMessages` is the right choice when you already have authoritative storage for messages and want one consistent persistence path.
 
-## When no storage is configured
+## When neither is configured
 
-If no object store is configured and the agent has no `storage` of its own, conversations don't survive run boundaries. A continuation boots empty. The runtime logs a warning at agent registration time so you see this at deploy time, not at user-traffic time.
+If `hydrateMessages` is not registered **and** no object store is configured, conversations don't survive run boundaries. A continuation boots empty. The runtime logs a warning at agent registration time so you see this at deploy time, not at user-traffic time.
 
 For local development this is sometimes fine — you're not testing continuations. For production it isn't. Configure one of:
 
 - **Object store** (`OBJECT_STORE_*` env vars on your webapp) — easiest, default behavior.
-- **A transcript storage over your own database** — stronger control, suits multi-tenant apps with audit needs.
+- **`hydrateMessages` + your own database** — stronger control, suits multi-tenant apps with audit needs.
 
 ## Snapshot key & lifecycle
 
@@ -198,7 +188,7 @@ For local development this is sometimes fine — you're not testing continuation
 | Key suffix | `sessions/{sessionId}/snapshot.json` |
 | Final key | `packets/{projectRef}/{envSlug}/sessions/{sessionId}/snapshot.json` |
 | Size | Tens of KB typical, capped only by object-store limits |
-| Cadence | Overwritten after every successful `onTurnComplete`, and after a history-changing action |
+| Cadence | Overwritten after every successful `onTurnComplete` |
 
 Snapshots accumulate per-session forever unless you set a lifecycle policy on the bucket. A 90-day expiry on `packets/*/sessions/*/snapshot.json` is a reasonable default if your chats don't typically resume after that window. Closed sessions are not auto-cleaned today.
 
@@ -211,8 +201,7 @@ For local development against `pnpm run docker`, the bundled MinIO container is
 ## See also
 
 - [Client Protocol](/ai-chat/client-protocol#how-history-is-rebuilt) — the wire-level view of the same model
-- [Transcript storage](/ai-chat/transcript-storage) — the adapter the runtime persists through, and how to bring your own
-- [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) — the deprecated context hook
+- [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) — the short-circuit hook
 - [OOM resilience](/ai-chat/patterns/oom-resilience) — how `session.in` cutoffs interact with snapshots
 - [Database persistence](/ai-chat/patterns/database-persistence) — the canonical persistence pattern using `onTurnComplete`
 - [v4.5 upgrade guide](/ai-chat/upgrade-guide#v45-wire-format-change) — when this model landed and what changed

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`.