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

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

@@ -1,310 +0,0 @@
----
-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/transcript-storage.mdx

@@ -1,233 +0,0 @@
----
-title: "Transcript storage"
-sidebarTitle: "Transcript storage"
-description: "Where a chat.agent conversation is kept: the UIMessages the runtime saves, the platform default, reading history back, and bringing your own database through the TranscriptStorage adapter."
----
-
-## Why a conversation needs a home
-
-A `chat.agent` conversation outlives a single run. One run answers many turns and survives the idle gaps between them, but a run does end eventually (a version upgrade, its turn limit, a crash), and the next message then boots a fresh run with nothing in memory (see [How it works](/ai-chat/how-it-works)). For that new run to answer in context, the conversation so far has to be read back from somewhere durable. The same store is what a page reload and the dashboard read to show history.
-
-That somewhere is a **transcript storage**. You get one by default with no setup: the platform keeps the conversation as a snapshot in object storage, the same blob the Sessions view in the dashboard renders. Bring your own when you want the conversation in your own database instead.
-
-## What gets saved
-
-The transcript is a list of **`UIMessage`s**, keyed by `chatId`. A `UIMessage` is the rich, renderable message the frontend works with: an `id`, a `role`, and an array of `parts` (text, reasoning, tool calls and their results, and any custom `data-*` parts). It is the same shape your React app holds and the same shape the dashboard renders, so what you store is exactly what a user sees.
-
-<Note>
-`UIMessage`s are not what the model reads. Each turn the runtime derives a `ModelMessage[]` from the transcript, the flattened `{ role, content }` form an LLM takes, and hands it to your `run()` as `messages`. The transcript storage never deals in `ModelMessage`s. It holds the UI messages; the model's view is derived from them.
-</Note>
-
-Keeping the UI shape is deliberate. It is lossless (a tool call and its result survive as parts), it is what renders, and the model's view can be rebuilt from it. Two things cannot be rebuilt from the messages alone, so the runtime hands them to the storage as well:
-
-- **`state`**: an opaque record for what the model saw that the transcript does not capture, a [compaction](/ai-chat/compaction) summary and [injected context](/ai-chat/background-injection). Store it as-is and give it back on load.
-- **cursors**: the stream positions the next run resumes from. Persist them opaquely; a storage never reads them.
-
-So a save is: the messages, a `state` blob, and two cursors. Nothing else.
-
-## The default storage
-
-Do nothing and you get the platform snapshot: the whole conversation written to object storage after each change, read back when a run continues. It is the blob the dashboard's Sessions view renders, and it needs no configuration.
-
-```ts
-import { chat } from "@trigger.dev/sdk/ai";
-import { anthropic } from "@ai-sdk/anthropic";
-
-export const myChat = chat.agent({
-  id: "my-chat",
-  run: async ({ messages, signal, streamText }) =>
-    streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
-});
-```
-
-The default rewrites the whole conversation on every turn. That is fine for most chats and costs one write. When it stops being fine, or when you want the conversation in a database you already run, you bring your own.
-
-## Bring your own storage
-
-Set `storage` on the agent to persist the conversation yourself:
-
-```ts
-import { chat } from "@trigger.dev/sdk/ai";
-import { anthropic } from "@ai-sdk/anthropic";
-import { myTranscriptStorage } from "./transcript-storage";
-
-export const myChat = chat.agent({
-  id: "my-chat",
-  storage: myTranscriptStorage,
-  run: async ({ messages, signal, streamText }) =>
-    streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
-});
-```
-
-Reasons to:
-
-- **Your database is the source of truth.** History lives next to the rest of your data, queryable, backed up, and deletable on your terms.
-- **Cheaper writes on long chats.** A row-per-message store writes only what changed on a turn instead of rewriting the whole conversation.
-- **Render history in one query** from your own tables, the same `load` the runtime uses.
-- **Own the model's context** for branching, trust boundaries, or rollback (see [Owning the model's context](#owning-the-models-context)).
-
-The runtime drives the storage. You never decide when to write, what a regenerate means for your rows, or how a crash mid-answer is recovered. Those decisions are the same for every backend, so they live in the runtime; your job is to store what it hands you and give it back.
-
-## The interface
-
-```ts
-type TranscriptStorage<TClientData = unknown> = {
-  load(
-    scope: { chatId: string; clientData: TClientData },
-    opts?: { limit?: number; before?: string }
-  ): Promise<{
-    messages: UIMessage[];
-    state: unknown | null;
-    cursors?: { lastOutEventId?: string; lastInEventId?: string };
-    nextCursor?: string;
-  }>;
-
-  save(
-    ctx: {
-      chatId: string;
-      clientData: TClientData;
-      turn: number;
-      trigger: "submit-message" | "regenerate-message" | "action";
-      runId: string;
-      ctx: TaskRunContext;
-    },
-    changeset: {
-      reason: "turn-complete" | "turn-error" | "action" | "compaction" | "recovery";
-      changes: TranscriptChange[];
-      transcript: { entries: Array<{ id: string; final: boolean; message: UIMessage }>; state: unknown | null };
-      cursors?: { lastOutEventId?: string; lastInEventId?: string };
-    }
-  ): Promise<void>;
-
-  loadContext?(
-    scope: { chatId: string; clientData: TClientData },
-    event: LoadContextEvent
-  ): Promise<UIMessage[]>;
-};
-
-type TranscriptChange =
-  | { op: "put"; message: UIMessage; final?: boolean }
-  | { op: "remove"; id: string }
-  | { op: "truncateAfter"; afterId: string }
-  | { op: "state"; value: unknown | null };
-```
-
-`load` returns the conversation. `save` records a change to it. `loadContext` is optional and covered [below](#owning-the-models-context). All the types are exported from `@trigger.dev/sdk/ai`.
-
-`scope` is the tenant of a read: the `chatId` and the `clientData` your app passed. `ctx` on a save is the same plus the run it happened in. `clientData` is how the runtime hands you the tenant; use it to scope or authorize where your backend needs to.
-
-## What the runtime hands `save`
-
-A changeset carries the same save two ways, and a storage uses whichever suits its shape.
-
-`changes` is the ordered list of what changed since the last save. A row-per-message store applies them, as one transaction where the backend supports one:
-
-| Change | Meaning |
-| --- | --- |
-| `put` | Upsert by `message.id`. An unknown id appends at the end; a known id is replaced in place. `final` is `false` for a partial answer captured from a turn that failed or was stopped, and `true` otherwise. |
-| `remove` | Delete by id. A no-op for an unknown id. |
-| `truncateAfter` | Drop every message ordered after `afterId`. This is what an undo or a regenerate becomes. A no-op for an unknown id. |
-| `state` | Replace the runtime's opaque record; `null` clears it. |
-
-`transcript` is the whole conversation as it stands after those changes, `entries` plus `state`. A store that keeps the conversation as one document (object storage, a key-value store, a JSON column) writes it as-is and keeps no state of its own between saves. The default storage is exactly that: it serialises `transcript` and rewrites the blob.
-
-The changes are the intent, spelled out. A normal turn is two `put`s, the user's message and the assistant's answer. A steering message the user sent mid-turn is another `put` in the same changeset. An undo through `chat.history.slice(0, -2)` is one `truncateAfter`. A regenerate is a `truncateAfter` and a `put`. A tool approval that updates the assistant message in place is one `put` for that id. Messages are addressed by id; how you order rows is your concern.
-
-A few properties worth knowing:
-
-- Saves happen after the turn's answer has reached the browser, so they never delay the response. The runtime awaits each `save` before the run suspends.
-- A `save` that throws is logged and the turn continues. The changes fold into the next changeset, and every change is idempotent, so a retried changeset converges on the same result.
-- A `load` that throws boots the run from the durable stream's recent tail rather than failing.
-
-## Reading the transcript
-
-`load` is the one read for every backend, the default included. Call it on your server, scoped to the signed-in user through `clientData`, and pass the result to the browser:
-
-```ts app/actions.ts
-"use server";
-import { chat, defaultStorage } from "@trigger.dev/sdk/ai";
-
-export const loadTranscript = chat.createLoadTranscriptAction(defaultStorage, { limit: 50 });
-```
-
-```tsx app/chat/[chatId]/ChatPage.tsx
-"use client";
-import { useLoadTranscript, useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
-import { loadTranscript } from "@/app/actions";
-
-export function ChatPage({ chatId }: { chatId: string }) {
-  const transport = useTriggerChatTransport({ task: "my-chat", accessToken, startSession });
-  const { messages, isLoading, nextCursor } = useLoadTranscript(chatId, loadTranscript, {
-    transport,
-  });
-  if (isLoading) return <Spinner />;
-  return <ChatView chatId={chatId} initialMessages={messages} transport={transport} />;
-}
-```
-
-<Warning>
-The action receives `chatId` from the browser, so authorize it before returning: check that the signed-in user owns this chat. `defaultStorage` loads purely by `chatId` and does no tenant check of its own, so an exported action with no authorization lets any authenticated user read any chat's transcript. A custom storage can enforce tenancy inside `load` using `clientData`, but the server action is still the place to reject a `chatId` the caller may not read.
-</Warning>
-
-`limit` returns the most recent messages and a `nextCursor`; pass it as `before` for the page before that one. With the default storage, a paged read is served by the platform, so a long conversation is not downloaded in full to render its last fifty messages. When you pass `transport` and it already knows the session, the hook seeds its resume cursor from the transcript, so the live subscription opens just past the persisted history instead of replaying it.
-
-Swap `defaultStorage` for your own storage and nothing else about the read changes.
-
-## Owning the model's context
-
-By default the model's context each turn is the transcript the runtime accumulated, converted to `ModelMessage`s. A storage that declares `loadContext` takes that over: the runtime calls it on every turn and action, with the messages the frontend sent and the transcript the runtime had, and uses the `UIMessage`s it returns as the conversation (converting them to `ModelMessage`s the same way). Reach for it when your database decides what the model sees, for branching conversations, a trust boundary where the browser's history is not to be believed, or a curated context window.
-
-```ts
-const storage: TranscriptStorage<{ userId: string }> = {
-  load: (scope, opts) => rows.load(scope, opts),
-  save: (ctx, changeset) => rows.save(ctx, changeset),
-  loadContext: async ({ chatId, clientData }, { incomingMessages }) => {
-    const branch = await rows.activeBranch(chatId, clientData.userId);
-    return [...branch, ...incomingMessages];
-  },
-};
-```
-
-`save` keeps receiving every change, and crash recovery keeps running. This is the replacement for the deprecated [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) hook; setting both `hydrateMessages` and `storage` on an agent is a startup error.
-
-## Writing your own storage
-
-The contract is small and the conformance suite checks it. Point the suite at a factory for your storage and run it under vitest or jest:
-
-```ts transcript-storage.test.ts
-import { runTranscriptStorageTests } from "@trigger.dev/sdk/ai/test";
-import { postgresTranscriptStorage } from "./transcript-storage";
-
-runTranscriptStorageTests(() => postgresTranscriptStorage(process.env.TEST_DATABASE_URL!));
-```
-
-The suite covers appends and in-place replacement, idempotent `remove` and `truncateAfter`, `state` round-trips, cursors, replaying the same changeset twice, paging, and chat isolation. `memoryTranscriptStorage()` is the reference implementation, and it is handy in your own tests to see exactly what the runtime hands a storage.
-
-A few things to get right:
-
-- Pick one view and stay with it. Apply `changes` if you store rows, write `transcript` if you store a document; don't mix them within one save.
-- `put` for a known id replaces the message in place; position and ordering don't change.
-- `truncateAfter` and `remove` are idempotent. Applying a changeset twice gives the same result as applying it once.
-- `load` with no options returns the whole conversation in order. With `limit`, return the most recent messages and a `nextCursor` (the id of the oldest returned message) when earlier messages exist.
-- Scope reads and writes by `clientData` where your backend enforces tenancy.
-
-## Guarantees and limits
-
-- Crash recovery of a half-written answer is runtime-owned in every configuration. It comes from the durable session stream, which no application database can reconstruct. A storage holds settled turns; the runtime overlays the recovered tail and hands it to `save` like any other change.
-- Bringing your own database does not remove platform custody. Session streams still hold message content for their retention window.
-- The default storage rewrites the whole conversation each turn. A row-per-message storage writes only what changed. That is the reason to plug in your own.
-
-## Migrating from hydrateMessages
-
-`hydrateMessages` keeps working with a one-time deprecation warning. Crash recovery runs for it, but the runtime does not write to your store on its behalf. To move:
-
-1. Implement `TranscriptStorage` over your existing tables. Your `hydrateMessages` body becomes `loadContext`; the writes you did in hooks become `save`.
-2. Set `storage` on the agent and remove `hydrateMessages`. Setting both is an error.
-3. Run `runTranscriptStorageTests` against your implementation.
-
-## See also
-
-- [Persistence and replay](/ai-chat/patterns/persistence-and-replay): how the runtime rebuilds a conversation when a new run boots
-- [Database persistence](/ai-chat/patterns/database-persistence): the hook-based pattern and how it relates
-- [Actions](/ai-chat/actions#actions-and-persistence): what an undo or regenerate becomes in the changeset
-- [Compaction](/ai-chat/compaction): the summary the runtime keeps in `state`