@trigger.dev/sdk 4.5.16 → 4.6.1

package/docs/ai-chat/patterns/native-compaction.mdx

@@ -0,0 +1,310 @@
+---
+title: "Native compaction & provider fallback"
+sidebarTitle: "Native compaction"
+description: "Persist provider-native compaction (Anthropic context editing, OpenAI stored responses) across chat.agent turns so history is never re-sent, and fall back between providers without losing the conversation."
+---
+
+Providers compact a conversation within a single request. Anthropic's [context editing](https://docs.anthropic.com/en/docs/build-with-claude/context-editing) clears old tool-use blocks server-side, and OpenAI's [stored responses](https://platform.openai.com/docs/guides/conversation-state) keep the thread server-side so you only send the delta. Neither changes what your agent has accumulated, so on its own the next turn re-sends the whole transcript again and the token saving is lost.
+
+This is the gap this page closes. After each turn, mirror what the provider compacted into the agent's stored history with [`chat.history.set()`](/ai-chat/reference#chat-namespace), so the next turn is derived from the already-reduced conversation. And because a native handle is provider-specific, this page also shows how a provider-agnostic [Trigger.dev compaction](/ai-chat/compaction) summary lets you fall back between providers without re-expanding the context.
+
+<Note>
+  The full runnable example is [`triggerdotdev/resilient-chat-example`](https://github.com/triggerdotdev/resilient-chat-example). See `native-persist.ts` for the Anthropic persistence flow and `resilient-chat.ts` for OpenAI stored responses plus provider fallback.
+</Note>
+
+## Two kinds of compaction
+
+They are not competing; they compose. Native compaction is the per-turn optimization, and Trigger.dev compaction is the durable, portable checkpoint.
+
+| | Native (provider) | Trigger.dev `compaction` |
+| --- | --- | --- |
+| Runs | Inside one provider request | Between steps / turns, in your run |
+| Scope | Provider-specific (Anthropic edits, OpenAI stored thread) | Provider-agnostic |
+| Portable across a provider switch | No, the handle is a cache miss on the other provider | Yes, `summarize` returns a plain string |
+| Persisted by default | No, you mirror it in `onTurnComplete` | Yes, replaces model messages and keeps UI messages |
+
+## Persist Anthropic native context editing
+
+Anthropic's `contextManagement` clears old tool-use/tool-result blocks server-side per request, and reports how many it cleared in `providerMetadata.anthropic.contextManagement.appliedEdits` (`clearedToolUses`, `clearedInputTokens`). It does not touch your accumulated history, so on its own the next turn still re-sends everything.
+
+The fix: read the `appliedEdits` counts as they stream in `onStepFinish`, then after the turn mirror that clearing into stored history with `chat.history.set()`. No custom summarizer is involved, since the provider's native editing drives what gets persisted.
+
+```ts /trigger/native-persist.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { streamText, stepCountIs, tool, type UIMessage } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { z } from "zod";
+
+const fetchRecord = tool({
+  description: "Fetch the full text of a record by its numeric id.",
+  inputSchema: z.object({ id: z.number() }),
+  execute: async ({ id }) => ({ id, text: `RECORD ${id}: ...` }),
+});
+
+// How many tool-uses Anthropic cleared this turn, per chat. Captured in run(),
+// applied in onTurnComplete. An in-memory Map is enough because the run stays
+// alive across turns (idleTimeoutInSeconds).
+const clearedByChat = new Map<string, number>();
+
+const isToolPart = (p: { type?: string }) =>
+  typeof p?.type === "string" && (p.type.startsWith("tool-") || p.type === "dynamic-tool");
+
+// Drop the oldest n tool parts, mirroring what the provider cleared. A tool call
+// and its result live in one part, so pairing stays intact.
+function pruneOldestToolParts(messages: UIMessage[], n: number): UIMessage[] {
+  let toRemove = n;
+  const out: UIMessage[] = [];
+  for (const m of messages) {
+    if (toRemove <= 0 || m.role !== "assistant" || !m.parts) {
+      out.push(m);
+      continue;
+    }
+    const kept = m.parts.filter((p) => {
+      if (toRemove > 0 && isToolPart(p)) {
+        toRemove--;
+        return false;
+      }
+      return true;
+    });
+    if (kept.length > 0) out.push({ ...m, parts: kept });
+  }
+  return out;
+}
+
+export const nativePersist = chat.agent({
+  id: "native-persist",
+  idleTimeoutInSeconds: 120,
+  tools: { fetchRecord },
+  run: async ({ messages, chatId, tools, signal }) => {
+    return streamText({
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      tools,
+      abortSignal: signal,
+      stopWhen: stepCountIs(12),
+      providerOptions: {
+        anthropic: {
+          contextManagement: {
+            edits: [
+              {
+                type: "clear_tool_uses_20250919",
+                trigger: { type: "tool_uses", value: 2 },
+                keep: { type: "tool_uses", value: 1 },
+                clearToolInputs: true,
+              },
+            ],
+          },
+        },
+      },
+      onStepFinish: ({ providerMetadata }) => {
+        const cm = providerMetadata?.anthropic?.contextManagement as
+          | { appliedEdits?: Array<{ type?: string; clearedToolUses?: number }> }
+          | undefined;
+        let stepCleared = 0;
+        for (const e of cm?.appliedEdits ?? []) {
+          if (e.type === "clear_tool_uses_20250919") stepCleared += e.clearedToolUses ?? 0;
+        }
+        if (stepCleared > 0) {
+          clearedByChat.set(chatId, (clearedByChat.get(chatId) ?? 0) + stepCleared);
+        }
+      },
+    });
+  },
+  // After the turn, mirror the server-side clearing into stored history.
+  onTurnComplete: async ({ chatId, uiMessages }) => {
+    const cleared = clearedByChat.get(chatId) ?? 0;
+    if (cleared <= 0) return;
+    chat.history.set(pruneOldestToolParts(uiMessages, cleared));
+    clearedByChat.set(chatId, 0);
+  },
+});
+```
+
+Turn 1 sends the user message and accumulates six tool results. Anthropic clears four of them server-side. `onTurnComplete` prunes those four from stored history, so turn 2 re-sends the smaller conversation (one tool result, not six) instead of the full transcript.
+
+<Note>
+  `onTurnComplete` is where persistence happens. Action turns fire `onAction` only, and a `chat.history.set()` inside `run()` is overwritten by the accumulator at turn end. See [Persistence and replay](/ai-chat/patterns/persistence-and-replay#action-turns-no-snapshot-write).
+</Note>
+
+## Persist OpenAI stored responses
+
+OpenAI's `store: true` keeps the thread server-side and returns a `responseId`. Pass that back as `previousResponseId` on the next turn and send only the messages since the last assistant reply; everything before it lives on OpenAI's side.
+
+```ts /trigger/openai-store.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { streamText, stepCountIs, type ModelMessage } from "ai";
+import { openai } from "@ai-sdk/openai";
+
+// Persist the stored-response handle between turns. Replace with your database.
+const nativeStore = new Map<string, { previousResponseId: string }>();
+
+// When OpenAI already holds the thread, send only what is new since the last
+// assistant reply. Everything before that lives server-side.
+function messagesSinceLastAssistant(messages: ModelMessage[]): ModelMessage[] {
+  let last = -1;
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i]!.role === "assistant") last = i;
+  }
+  return last === -1 ? messages : messages.slice(last + 1);
+}
+
+export const openaiStore = chat.agent({
+  id: "openai-store",
+  idleTimeoutInSeconds: 120,
+  run: async ({ messages, chatId, signal }) => {
+    const native = nativeStore.get(chatId);
+    const outbound = native ? messagesSinceLastAssistant(messages) : messages;
+
+    const result = streamText({
+      model: openai("gpt-4o"),
+      messages: outbound,
+      abortSignal: signal,
+      stopWhen: stepCountIs(5),
+      providerOptions: {
+        openai: native ? { store: true, previousResponseId: native.previousResponseId } : { store: true },
+      },
+    });
+
+    // Capture the response id off the metadata for the next turn.
+    void result.providerMetadata.then((meta) => {
+      const rid = typeof meta?.openai?.responseId === "string" ? meta.openai.responseId : undefined;
+      if (rid) nativeStore.set(chatId, { previousResponseId: rid });
+    });
+
+    return result;
+  },
+});
+```
+
+Turn 1 stores the thread and sends all three messages. Turn 2 sends only the new user message (`1/3`), because OpenAI already has the rest.
+
+## Fall back between providers without losing history
+
+A native handle is a per-provider cache. An OpenAI `previousResponseId` means nothing to Anthropic, and Anthropic's server-side edits don't exist on OpenAI. So when a provider is down and you fall back to another, the native optimization is a cache miss, and a naive fallback re-sends the entire raw transcript to the new provider.
+
+[Trigger.dev's `compaction`](/ai-chat/compaction) is the portable checkpoint that closes this gap. `summarize` returns a plain string and `compactModelMessages` returns neutral `ModelMessage[]`, so the summary survives any provider switch. Tag each native handle with the provider that produced it. On a switch it's a cache miss, and you rebuild from the summary instead of re-expanding the context.
+
+```ts /trigger/resilient-chat.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { streamText, generateText, stepCountIs, generateId, type ModelMessage } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { openai } from "@ai-sdk/openai";
+
+type Provider = "anthropic" | "openai";
+const FALLBACK_ORDER: Provider[] = ["anthropic", "openai"];
+
+// Native handle, tagged with the provider that produced it. Replace with your DB.
+type NativeState = { provider: "openai"; previousResponseId: string };
+const nativeStore = new Map<string, NativeState>();
+
+// Provider-agnostic summary: a plain string, portable across any provider.
+async function summarizeConversation(messages: ModelMessage[]): Promise<string> {
+  const { text } = await generateText({
+    model: openai("gpt-4o-mini"),
+    messages: [
+      ...messages,
+      {
+        role: "user",
+        content:
+          "Summarize this conversation so it can continue with ANY model. " +
+          "Preserve decisions made, facts established, open questions, and the user's intent.",
+      },
+    ],
+  });
+  return text;
+}
+
+export const resilientChat = chat.agent({
+  id: "resilient-chat",
+  idleTimeoutInSeconds: 120,
+
+  compaction: {
+    shouldCompact: ({ totalTokens }) => (totalTokens ?? 0) > 80_000,
+    summarize: ({ messages }) => summarizeConversation(messages),
+    compactModelMessages: ({ modelMessages, summary }) => [
+      { role: "user", content: `Summary of the conversation so far:\n\n${summary}` },
+      ...modelMessages.slice(-2),
+    ],
+    compactUIMessages: ({ uiMessages, summary }) => [
+      {
+        id: generateId(),
+        role: "assistant",
+        parts: [{ type: "text", text: `[Conversation summary]\n\n${summary}` }],
+      },
+      ...uiMessages.slice(-2),
+    ],
+  },
+
+  // A Trigger.dev compaction is the reset point: the provider's server-side thread
+  // no longer matches the compacted baseline, so invalidate the native handle.
+  onCompacted: async ({ chatId }) => {
+    if (chatId) nativeStore.delete(chatId);
+  },
+
+  run: async ({ messages, chatId, signal }) => {
+    let lastError: unknown;
+    for (const providerId of FALLBACK_ORDER) {
+      const native = nativeStore.get(chatId);
+      try {
+        if (providerId === "openai") {
+          // On a switch to OpenAI with no matching handle, `messages` is already the
+          // compacted baseline (summary + recent), so raw history is not re-sent.
+          const useHandle = native?.provider === "openai";
+          const result = streamText({
+            model: openai("gpt-4o"),
+            messages,
+            abortSignal: signal,
+            stopWhen: stepCountIs(5),
+            providerOptions: {
+              openai: useHandle
+                ? { store: true, previousResponseId: native!.previousResponseId }
+                : { store: true },
+            },
+          });
+          void result.providerMetadata.then((meta) => {
+            const rid = typeof meta?.openai?.responseId === "string" ? meta.openai.responseId : undefined;
+            if (rid) nativeStore.set(chatId, { provider: "openai", previousResponseId: rid });
+          });
+          return result;
+        }
+
+        return streamText({
+          model: anthropic("claude-sonnet-4-5"),
+          messages,
+          abortSignal: signal,
+          stopWhen: stepCountIs(5),
+          providerOptions: {
+            anthropic: {
+              contextManagement: {
+                edits: [{ type: "clear_tool_uses_20250919", trigger: { type: "input_tokens", value: 80_000 }, keep: { type: "tool_uses", value: 3 } }],
+              },
+            },
+          },
+        });
+      } catch (error) {
+        lastError = error; // Provider failed, try the next one in the order.
+      }
+    }
+    throw lastError;
+  },
+});
+```
+
+When Anthropic is down, the loop falls through to OpenAI. Because `compaction` has already reduced `messages` to a summary plus the last couple of exchanges, the switch sends the portable baseline, not megabytes of raw transcript.
+
+<Warning>
+  Fallback here retries a turn that hasn't started streaming yet. Once a response is streaming to the client, a mid-stream provider failure can't be swapped transparently. Surface the error and let the frontend regenerate the turn. See [Error handling](/ai-chat/error-handling).
+</Warning>
+
+## Production notes
+
+- **Persist the handles.** The `Map`s above (`nativeStore`, `clearedByChat`) work in the example because the run stays alive across turns, but they don't survive a run boundary. Store native handles and summaries in your database keyed by `chatId`, alongside your [message persistence](/ai-chat/patterns/database-persistence).
+- **No cross-provider translation.** Native compaction from one provider never transfers to another. The Trigger.dev `compaction` summary is the only portable baseline across a switch.
+- **Native compaction is opt-in per turn.** It applies only for the provider whose `providerOptions` you set on that turn's `streamText` call.
+
+## See also
+
+- [Compaction](/ai-chat/compaction): the provider-agnostic `compaction` option, `onCompacted`, and manual `chat.compact()`.
+- [Prompt caching](/ai-chat/prompt-caching): the other per-turn token optimization, and how it interacts with a growing history.
+- [Database persistence](/ai-chat/patterns/database-persistence): where to store native handles and summaries for real.
+- [Lifecycle hooks](/ai-chat/lifecycle-hooks): `onTurnComplete` and `onCompacted` in the broader hook taxonomy.

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 — durable JSON snapshot in object storage plus session.out replay, with a hydrateMessages short-circuit for backend-owned history."
+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."
 ---
 
 `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 **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.
+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.
 
 ## 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, lastOutTimestamp }
+  Run1->>Snapshot: write { messages: [u1, a1], lastOutEventId, lastInEventId }
   Note over Run1: idle suspend (or exit)
 
   User->>Run2: u2 (delta only)
@@ -52,15 +52,21 @@ The accumulator starts empty. The wire delivers `u1`. After the model finishes,
 
 ```json
 {
-  "version": 1,
+  "version": 2,
   "savedAt": 1715180400000,
-  "messages": [u1, a1],
+  "messages": [
+    { "id": "u1", "final": true, "message": u1 },
+    { "id": "a1", "final": true, "message": a1 }
+  ],
+  "state": null,
   "lastOutEventId": "42",
-  "lastOutTimestamp": 1715180399000
+  "lastInEventId": "7"
 }
 ```
 
-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.
+`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.
 
 ### Run 2 — boot
 
@@ -110,21 +116,25 @@ 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 includes a `lastOutTimestamp` field that is exactly that high-water mark.
+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.
 
-When a snapshot exists, the OOM-retry path reads `lastOutTimestamp` directly instead of scanning `session.out`. One fewer stream subscription per retry. Free win.
+When a snapshot exists, the OOM-retry path reads `lastInEventId` 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 — no snapshot write
+## 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](/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.
+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.
 
-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.
+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`.
 
-## The `hydrateMessages` short-circuit
+### The `hydrateMessages` hook
 
-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.
+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.
 
 ```ts
 import { chat, upsertIncomingMessage } from "@trigger.dev/sdk/ai";
@@ -160,24 +170,24 @@ export const myChat = chat.agent({
 
 What you gain:
 
-- **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.
+- **Zero object-store traffic per turn.** No snapshot read, no snapshot write. `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.
-- **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.)
+- **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.
 
-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.
+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.
 
-## When neither is configured
+## When no storage is configured
 
-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.
+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.
 
 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.
-- **`hydrateMessages` + your own database** — stronger control, suits multi-tenant apps with audit needs.
+- **A transcript storage over your own database** — stronger control, suits multi-tenant apps with audit needs.
 
 ## Snapshot key & lifecycle
 
@@ -188,7 +198,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` |
+| Cadence | Overwritten after every successful `onTurnComplete`, and after a history-changing action |
 
 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.
 
@@ -201,7 +211,8 @@ 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
-- [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) — the short-circuit hook
+- [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
 - [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 { streamText, stepCountIs } from "ai";
+import { stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 
 const timeUtilsSkill = skills.define({
@@ -92,12 +92,11 @@ export const agent = chat.agent({
   onChatStart: async () => {
     chat.skills.set([await timeUtilsSkill.local()]);
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-5"),
       messages,
       abortSignal: signal,
-      ...chat.toStreamTextOptions(),
       stopWhen: stepCountIs(15),
     });
   },
@@ -111,7 +110,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. `chat.toStreamTextOptions()` spreads them into `streamText` automatically:
+`chat.skills.set([...])` stores the resolved skills for the current run. The `streamText` from `run`'s argument picks them up automatically:
 
 - The frontmatter `description` lands in the system prompt under "Available skills:".
 - Three tools are added: `loadSkill`, `readFile`, `bash` — scoped per skill.
@@ -169,12 +168,10 @@ return streamText({
   model: anthropic("claude-sonnet-4-5"),
   messages,
   abortSignal: signal,
-  ...chat.toStreamTextOptions({
-    tools: {
-      webFetch,       // your tool
-      deepResearch,   // your tool
-    },
-  }),
+  tools: {
+    webFetch,       // your tool
+    deepResearch,   // your tool
+  },
   stopWhen: stepCountIs(15),
 });
 ```

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

@@ -8,6 +8,17 @@ 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`:
@@ -19,22 +30,44 @@ 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->>RunV1: input stream
+  Transport->>Session: append message
+  Session->>RunV1: input stream
   RunV1->>RunV1: onTurnStart → requestUpgrade()
-  RunV1-->>Transport: trigger:upgrade-required
-  RunV1->>RunV1: exit (run() never called)
-  Transport->>RunV2: trigger new run (continuation, same message)
-  RunV2-->>Transport: response stream
+  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)
   Transport-->>User: response (seamless)
 ```
 
@@ -103,6 +136,13 @@ 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"
@@ -151,6 +191,38 @@ 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:
@@ -166,7 +238,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 unless the Session's trigger configuration sets `lockToVersion`.
+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.
 
 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.
 
@@ -182,6 +254,7 @@ 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