@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

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/oom-resilience.mdx

@@ -0,0 +1,116 @@
+---
+title: "OOM resilience"
+sidebarTitle: "OOM resilience"
+description: "Recover from out-of-memory errors mid-turn by automatically retrying the failed turn on a larger machine — without losing the in-flight user message or re-processing completed turns."
+---
+
+When a `chat.agent` turn runs out of memory, the worker process dies and everything in it is gone: the in-flight LLM call, the accumulator, any tool execution mid-flight. By default, Trigger.dev surfaces the OOM as a run failure.
+
+Setting `oomMachine` opts the agent into automatic recovery: the failed turn re-runs on a larger machine, picks up the user message that triggered the OOM (without re-processing earlier completed turns), and produces a normal response.
+
+## Setup
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  machine: "small-1x",         // default machine
+  oomMachine: "medium-2x",     // fallback on OOM
+  run: async ({ messages, signal }) =>
+    streamText({ model, messages, abortSignal: signal }),
+});
+```
+
+That's the entire opt-in. With `oomMachine` set, the agent gets:
+
+- **`retry.maxAttempts: 2`** internally — one retry for OOM only; non-OOM errors don't retry.
+- **`retry.outOfMemory.machine: oomMachine`** — the fresh attempt boots on the larger machine.
+- **`session.in` cursor recovery** — the new attempt skips records belonging to turns that already completed on the prior attempt and only re-runs the OOM'd turn.
+
+`chat.agent` does not expose generic `retry` options. OOM recovery is the only retry path because retrying an LLM-driven loop on non-OOM errors tends to be expensive and side-effecting. Drop down to a [raw `task()` with chat primitives](/ai-chat/custom-agents) if you need richer retry semantics.
+
+## How recovery works
+
+The recovery doesn't need any customer-side persistence to avoid duplicate processing. It uses two pieces of durable state Trigger already maintains for every chat:
+
+- **`session.out`** — the durable response stream. Every successful turn writes a `trigger:turn-complete` chunk here.
+- **`session.in`** — the durable input stream. Every user message after the first turn lands here as a record with a server-assigned timestamp.
+
+On retry boot, the SDK:
+
+1. Scans `session.out` for the latest `trigger:turn-complete` chunk and reads its timestamp. Call this `T_last_complete`.
+2. Sets a per-stream filter on `session.in` so any record with `timestamp <= T_last_complete` is dropped before it reaches the turn loop.
+3. Begins normal processing. The first record that passes the filter is the message that triggered the OOM (or any newer message that arrived during the retry window).
+
+Result: turns 1..N-1 are not re-processed, turn N runs on the larger machine, and the conversation continues.
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Run as chat.agent run
+  participant SessionIn as session.in
+  participant SessionOut as session.out
+
+  User->>SessionIn: u2 (turn 2)
+  Run->>SessionIn: read u2
+  Run->>SessionOut: turn-complete (T1)
+  User->>SessionIn: u3 (turn 3)
+  Run->>SessionIn: read u3
+  Run->>SessionOut: turn-complete (T2)
+  User->>SessionIn: u4 (turn 4)
+  Run->>SessionIn: read u4
+  Note over Run: OOM mid-turn
+  Run->>Run: ⚠️ killed
+  Note over Run: Attempt 2 boots on oomMachine
+  Run->>SessionOut: scan → T_last_complete = T2
+  Run->>SessionIn: read with filter (ts > T2)
+  SessionIn-->>Run: u2 (filtered, ts < T2)
+  SessionIn-->>Run: u3 (filtered, ts < T2)
+  SessionIn-->>Run: u4 (passes — the OOM'd turn)
+  Run->>SessionOut: turn 4 complete
+```
+
+The scan on `session.out` is streaming and bounded in memory: each chunk is inspected and discarded one at a time, so a long-running chat doesn't bloat the retry-boot worker. Bandwidth scales linearly with `session.out` size, but only on the OOM-retry path — a rare event.
+
+## With `hydrateMessages`
+
+If your agent uses [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) to load the durable conversation history per turn, the OOM'd turn re-runs against the full prior accumulator: the model sees `[u1, a1, u2, a2, ..., u_N]` and responds in context. This is the recommended pattern for production chats.
+
+## Without `hydrateMessages`
+
+Recovery boot reconstructs context automatically. The boot reads both the durable `session.out` snapshot (settled turns) and the `session.out` tail past the snapshot cursor (the partial assistant chunks the OOM'd turn streamed before dying). When the new attempt processes the OOM'd user message, the model sees the full prior conversation **plus** the partial assistant that was cut off — so a "keep going" follow-up continues naturally, and any other follow-up has the same context the original turn had.
+
+`hydrateMessages` is still the right choice if you want a single source of truth in your own database (branching conversations, message-level access control, etc.). It's no longer required for OOM continuity.
+
+For full control over recovery — drop the partial, synthesize tool results for an interrupted tool call, emit a recovery banner to the UI — register [`onRecoveryBoot`](/ai-chat/patterns/recovery-boot).
+
+## Tool execute idempotency
+
+If an OOM hits mid-tool-execution, the new attempt re-runs the entire turn — including the tool call. Make tool `execute` functions idempotent or checkpoint their progress externally. Trigger doesn't roll back side effects automatically.
+
+```ts
+import { tool } from "ai";
+
+export const sendEmail = tool({
+  description: "Send an email",
+  inputSchema: z.object({ to: z.string(), idempotencyKey: z.string() }),
+  execute: async ({ to, idempotencyKey }) => {
+    // Stripe-style: dedupe at the side-effect layer with a customer-supplied key.
+    return await mailer.send({ to, idempotencyKey });
+  },
+});
+```
+
+## Limitations
+
+- **One OOM retry per run.** `chat.agent` sets `maxAttempts: 2`. If attempt 2 also OOMs, the run fails. Use a sufficiently large `oomMachine` to avoid this.
+- **Single fallback tier.** Only one `oomMachine`. There's no "tiered retry" (small → medium → large). If you need that, drop down to a [raw `task()` with chat primitives](/ai-chat/custom-agents) and configure `retry` directly.
+- **Non-OOM errors don't retry.** Schema errors, model-call rejections, tool throws, etc. fail the run as before. Out-of-memory is the only retry trigger.
+- **Tools mid-execution are not checkpointed.** A partially-run tool re-runs from scratch on the new attempt. Make them idempotent.
+
+## See also
+
+- [Recovery boot](/ai-chat/patterns/recovery-boot) — the underlying hook + smart default that gives OOM recovery its full-context behavior
+- [Lifecycle hooks](/ai-chat/lifecycle-hooks) — `onChatResume` fires on every retry attempt with `phase: "preload"` or `"turn"`
+- [Database persistence](/ai-chat/patterns/database-persistence) — the `hydrateMessages` pattern for branching, ACL, and DB-as-source-of-truth scenarios

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

@@ -0,0 +1,218 @@
+---
+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."
+---
+
+`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.
+
+## Why a snapshot at all
+
+The wire is delta-only: each `.in/append` carries at most one new `UIMessage` (see [Client Protocol](/ai-chat/client-protocol#chattaskwirepayload)). A long conversation might be 50 turns deep with megabytes of tool results — the wire never carries that. So when run #2 boots to handle turn 51, the wire alone tells it almost nothing about turns 1–50.
+
+Two existing pieces of durable state already capture everything that happened:
+
+- **`session.in`** — every user message and tool-approval response ever sent.
+- **`session.out`** — every assistant token, tool call, and tool result the agent emitted, ordered.
+
+Replaying `session.out` from the beginning is correct but expensive — bandwidth scales with chat length, and parsing N megabytes of streamed chunks at every boot adds latency. So the runtime writes a **snapshot** after every turn and reads it on the next boot. Replay only covers the gap between the snapshot's cursor and now.
+
+## The model end-to-end
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Run1 as Run 1 (turn 1)
+  participant Snapshot as Object storage
+  participant SessionOut as session.out
+  participant Run2 as Run 2 (turn 2+)
+
+  User->>Run1: u1
+  Run1->>SessionOut: assistant chunks for a1
+  Run1->>Run1: onTurnComplete
+  Run1->>Snapshot: write { messages: [u1, a1], lastOutEventId, lastInEventId }
+  Note over Run1: idle suspend (or exit)
+
+  User->>Run2: u2 (delta only)
+  Run2->>Snapshot: read snapshot
+  Run2->>SessionOut: subscribe(lastEventId, wait=0)
+  SessionOut-->>Run2: (empty — nothing since snapshot)
+  Note over Run2: accumulator = [u1, a1]
+  Run2->>Run2: append u2 from wire
+  Run2->>SessionOut: assistant chunks for a2
+  Run2->>Run2: onTurnComplete
+  Run2->>Snapshot: write { messages: [u1, a1, u2, a2], ... }
+```
+
+### Run 1 — first turn
+
+The accumulator starts empty. The wire delivers `u1`. After the model finishes, `onTurnComplete` fires, then the runtime serializes the full accumulator and writes:
+
+```json
+{
+  "version": 2,
+  "savedAt": 1715180400000,
+  "messages": [
+    { "id": "u1", "final": true, "message": u1 },
+    { "id": "a1", "final": true, "message": a1 }
+  ],
+  "state": null,
+  "lastOutEventId": "42",
+  "lastInEventId": "7"
+}
+```
+
+`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
+
+A new run boots when the user sends `u2`. Run 1 has long since exited. Run 2 has no in-memory state. The boot sequence:
+
+<Steps>
+  <Step title="Read the snapshot">
+    GET the JSON blob. On 404 (no snapshot yet — first-ever turn) or read error or version mismatch, treat as empty and continue. Snapshot misses are non-fatal — replay alone may still be sufficient.
+  </Step>
+  <Step title="Replay session.out tail">
+    Subscribe to `session.out` with `wait=0` starting from `snapshot.lastOutEventId`. Drain whatever's there and close. Returns:
+    - **Settled messages** — closed assistant turns past the snapshot cursor (the chunks of a turn that completed after the snapshot was written but before the run exited cleanly).
+    - **A partial assistant** — the trailing message if its stream never received a `finish` chunk. The dead run was mid-response when it died. `cleanupAbortedParts` has already stripped streaming-in-progress fragments.
+
+    In the steady state this returns empty. In recovery, it returns whatever the dead run was in the middle of.
+  </Step>
+  <Step title="Replay session.in tail">
+    GET `session.in` records past the last `turn-complete`'s `session-in-event-id` cursor. Returns the user messages the dead run hadn't acknowledged — typically the message that triggered the cancelled / crashed turn, plus anything the customer typed after.
+  </Step>
+  <Step title="Reconstruct the chain (smart default)">
+    Snapshot messages merge with the settled replay (replay wins on `id` collision). Then:
+
+    - If there's a partial assistant **and** at least one in-flight user message, splice `[firstInFlightUser, partialAssistant]` onto the end of the chain. The model sees the prior turn's incomplete attempt and can continue, abandon, or pivot based on the next user message.
+    - Remaining in-flight users dispatch as fresh turns after the recovered first one.
+    - If there's no partial OR no in-flight users, the chain is just the settled chain and any in-flight users dispatch normally.
+
+    Customers can override this entirely via [`onRecoveryBoot`](/ai-chat/patterns/recovery-boot).
+  </Step>
+  <Step title="Append the new wire message">
+    Append `u2` from the wire payload, exactly as on turn 1.
+  </Step>
+</Steps>
+
+The model now sees `[u1, a1, u2]` and produces `a2`. After `onTurnComplete`, the runtime overwrites the snapshot with `[u1, a1, u2, a2]` and the cycle repeats.
+
+### Crash mid-turn — replay carries the load
+
+Suppose Run 1's turn 1 streams partial assistant chunks to `session.out` and then crashes (OOM, exception, server-side cancel) before `onTurnComplete` fires. No snapshot was written. The next run boots and:
+
+1. Snapshot read returns 404 → empty.
+2. `session.out` tail replay picks up the partial assistant chunks emitted before the crash. `cleanupAbortedParts` strips streaming-in-progress fragments but keeps the cleaned trailing message as the `partialAssistant`.
+3. `session.in` tail replay finds the user message the dead run was answering (no `turn-complete` was written, so the cursor never advanced past it).
+4. Smart default splices `[firstInFlightUser, partialAssistant]` onto the chain. Any later user messages (including the customer's follow-up) dispatch as fresh turns.
+5. The model sees full prior context and responds in kind — continuing a cut-off essay on "keep going", answering a fresh question on "actually, what's 7+8?", abandoning the prior work on "scrap that, do X instead".
+
+Replay carries the conversation across the crash boundary with zero customer code. For policies different from "preserve context" — drop the partial entirely, synthesize tool results for an interrupted tool call, write a recovery banner to the UI — register [`onRecoveryBoot`](/ai-chat/patterns/recovery-boot).
+
+## 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.
+
+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
+
+[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
+
+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.
+
+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` 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. 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";
+import { db } from "@/lib/db";
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  hydrateMessages: async ({ chatId, trigger, incomingMessages }) => {
+    const stored = (await db.chat.findUnique({ where: { id: chatId } }))?.messages ?? [];
+
+    // See lifecycle-hooks for the full upsert pattern + rationale:
+    // /ai-chat/lifecycle-hooks#hydratemessages
+    if (upsertIncomingMessage(stored, { trigger, incomingMessages })) {
+      // Upsert, not update: head-start first turns run without a preload
+      // to create the row.
+      await db.chat.upsert({
+        where: { id: chatId },
+        create: { id: chatId, messages: stored },
+        update: { messages: stored },
+      });
+    }
+
+    return stored;
+  },
+  onTurnComplete: async ({ chatId, uiMessages }) => {
+    await db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } });
+  },
+  run: async ({ messages, signal }) => {
+    return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
+  },
+});
+```
+
+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.
+- **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.
+
+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 no storage 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.
+
+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.
+
+## Snapshot key & lifecycle
+
+| Field | Value |
+|---|---|
+| Bucket | Whatever `OBJECT_STORE_BASE_URL` points to |
+| Key prefix | `packets/{projectRef}/{envSlug}/` (server-prefixed) |
+| 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 |
+
+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.
+
+### MinIO and S3-compatible stores
+
+Snapshot read/write reuses the same object-store layer as Trigger.dev's existing large-payload routes. Anything that already works for large payloads — AWS S3, MinIO (self-host or local development), Cloudflare R2, Tigris, Backblaze B2 — works for snapshots too. `OBJECT_STORE_DEFAULT_PROTOCOL` controls the routing (`s3`, `minio`, etc.) and the SDK picks the right driver automatically. No snapshot-specific config.
+
+For local development against `pnpm run docker`, the bundled MinIO container is enough — set `OBJECT_STORE_DEFAULT_PROTOCOL=minio` and the standard MinIO env vars on the webapp, and continuations work end-to-end against a local stack.
+
+## 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
+- [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