@trigger.dev/sdk 0.0.0-prerelease-20260908122921 → 0.0.0-prerelease-20260909071038

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

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

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

@@ -1,12 +1,12 @@
 ---
 title: "Persistence and replay"
 sidebarTitle: "Persistence and replay"
-description: "How chat.agent rebuilds conversation history at run boot — 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/reference.mdx

@@ -44,9 +44,10 @@ Options for `chat.agent()`.
 | `onPreload`                   | `(event: PreloadEvent) => Promise<void> \| void`            | —                              | Fires on preloaded runs before the first message                                                    |
 | `onChatStart`                 | `(event: ChatStartEvent) => Promise<void> \| void`          | —                              | Fires once per chat, on the very first user message. Does NOT fire on continuation runs or OOM-retries — see [onChatStart](/ai-chat/lifecycle-hooks#onchatstart). |
 | `onValidateMessages`          | `(event: ValidateMessagesEvent) => UIMessage[] \| Promise<UIMessage[]>` | —                | Validate/transform UIMessages before model conversion. See [onValidateMessages](/ai-chat/lifecycle-hooks#onvalidatemessages) |
-| `hydrateMessages`             | `(event: HydrateMessagesEvent) => UIMessage[] \| Promise<UIMessage[]>` | —                 | Load message history from backend, replacing the linear accumulator. See [hydrateMessages](/ai-chat/lifecycle-hooks#hydratemessages) |
+| `storage`                     | `TranscriptStorage`                                         | `defaultStorage`               | Where the conversation is persisted and read back. The platform snapshot by default; bring your own to write each change to your database. See [Transcript storage](/ai-chat/transcript-storage) |
+| `hydrateMessages`             | `(event: HydrateMessagesEvent) => UIMessage[] \| Promise<UIMessage[]>` | —                 | **Deprecated.** Load message history from backend, replacing the linear accumulator. Use `loadContext` on a `storage` instead; cannot be combined with `storage`. See [hydrateMessages](/ai-chat/lifecycle-hooks#hydratemessages) |
 | `actionSchema`                | `TaskSchema`                                                | —                              | Schema for validating custom actions sent via `transport.sendAction()`. See [Actions](/ai-chat/actions) |
-| `onAction`                    | `(event: ActionEvent) => Promise<void \| ActionTurn> \| void \| ActionTurn` | —                              | Handle custom actions. Actions are state edits: only `hydrateMessages` + `onAction` fire. Return `chat.turn()` to run a turn on the edited history, or nothing for an edit only. See [Actions](/ai-chat/actions) |
+| `onAction`                    | `(event: ActionEvent) => Promise<void \| ActionTurn> \| void \| ActionTurn` | —                              | Handle custom actions. Actions are state edits: only `hydrateMessages` (or a storage's `loadContext`) + `onAction` fire. Return `chat.turn()` to run a turn on the edited history, or nothing for an edit only. See [Actions](/ai-chat/actions) |
 | `onTurnStart`                 | `(event: TurnStartEvent) => Promise<void> \| void`          | —                              | Fires every turn before `run()`                                                                     |
 | `onBeforeTurnComplete`        | `(event: BeforeTurnCompleteEvent) => Promise<void> \| void` | —                              | Fires after response but before stream closes. Includes `writer`.                                   |
 | `onTurnComplete`              | `(event: TurnCompleteEvent) => Promise<void> \| void`       | —                              | Fires after each turn completes (stream closed)                                                     |
@@ -218,9 +219,38 @@ Passed to the `tools` function form on `chat.agent`, once per turn, to resolve t
 | `continuation` | `boolean`                   | Whether this run is continuing an existing chat   |
 | `clientData`   | Typed by `clientDataSchema` | Custom data from the frontend                     |
 
+## TranscriptStorage
+
+The persistence adapter set through `chat.agent({ storage })`. See [Transcript storage](/ai-chat/transcript-storage). All types below are exported from `@trigger.dev/sdk/ai`.
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `load` | `(scope: TranscriptScope, opts?: TranscriptLoadOptions) => Promise<TranscriptLoadResult>` | The conversation, in order. Called once at a continuation boot and by `chat.createLoadTranscriptAction` for rendering. |
+| `save` | `(ctx: TranscriptStorageContext, changeset: TranscriptChangeset) => Promise<void>` | Apply the changes since the last save. Called after every turn, failed turn and history-changing action. |
+| `loadContext?` | `(scope: TranscriptScope, event: LoadContextEvent) => Promise<UIMessage[]>` | Optional. When present, the storage owns the model's context: called on every turn and action in place of the runtime's transcript. Same event shape as `HydrateMessagesEvent`. |
+
+| Type | Shape |
+| --- | --- |
+| `TranscriptScope<TClientData>` | `{ chatId: string; clientData: TClientData }` |
+| `TranscriptStorageContext<TClientData>` | `TranscriptScope` plus `{ turn: number; trigger: "submit-message" \| "regenerate-message" \| "action"; runId: string; ctx: TaskRunContext }` |
+| `TranscriptChange` | `{ op: "put"; message: UIMessage; final?: boolean }` \| `{ op: "remove"; id: string }` \| `{ op: "truncateAfter"; afterId: string }` \| `{ op: "state"; value: unknown \| null }` |
+| `TranscriptChangeset` | `{ reason: "turn-complete" \| "turn-error" \| "action" \| "compaction" \| "recovery"; changes: TranscriptChange[]; transcript: TranscriptState; cursors?: TranscriptCursors }` |
+| `TranscriptState` | `{ entries: Array<{ id: string; final: boolean; message: UIMessage }>; state: unknown \| null }`: the whole conversation after the changeset's changes, for stores that write one document |
+| `TranscriptCursors` | `{ lastOutEventId?: string; lastInEventId?: string }` |
+| `TranscriptLoadOptions` | `{ limit?: number; before?: string }` |
+| `TranscriptLoadResult` | `{ messages: UIMessage[]; state: unknown \| null; cursors?: TranscriptCursors; nextCursor?: string }` |
+
+| Export | Description |
+| --- | --- |
+| `defaultStorage` | The platform snapshot storage the agent uses when `storage` is not set. Equal to `snapshotTranscriptStorage()`. |
+| `snapshotTranscriptStorage()` | Factory for the platform snapshot storage. |
+| `memoryTranscriptStorage()` | An in-process storage that also records every changeset it receives. The reference implementation. |
+| `reduceTranscriptChanges(state, changes)` | Pure reducer that applies changes to `{ entries, state }`. Useful for building a storage over a document store. |
+| `runTranscriptStorageTests(makeStorage, options?)` | From `@trigger.dev/sdk/ai/test`. The conformance suite for a storage implementation. Pass `{ api: { describe, it, expect } }` when test globals are off, and `clientData` when your storage scopes by it. |
+
 ## HydrateMessagesEvent
 
-Passed to the `hydrateMessages` callback. See [hydrateMessages](/ai-chat/lifecycle-hooks#hydratemessages).
+Passed to the `hydrateMessages` callback. See [hydrateMessages](/ai-chat/lifecycle-hooks#hydratemessages). `hydrateMessages` is deprecated; `LoadContextEvent`, passed to a storage's `loadContext`, has the same shape.
 
 | Field              | Type                                                  | Description                                               |
 | ------------------ | ----------------------------------------------------- | --------------------------------------------------------- |
@@ -369,8 +399,8 @@ Passed to `compactUIMessages` and `compactModelMessages` callbacks.
 | Field           | Type                 | Description                                          |
 | --------------- | -------------------- | ---------------------------------------------------- |
 | `summary`       | `string`             | The generated summary text                           |
-| `uiMessages`    | `UIMessage[]`        | Current UI messages (full conversation)              |
-| `modelMessages` | `ModelMessage[]`     | Current model messages (full conversation)           |
+| `uiMessages`    | `UIMessage[]`        | Current UI messages (the transcript)                 |
+| `modelMessages` | `ModelMessage[]`     | Current model messages (the lane the model is sent; after a compaction this is the summary plus what followed it, not the whole transcript) |
 | `chatId`        | `string`             | Chat session ID                                      |
 | `turn`          | `number`             | Current turn (0-indexed)                             |
 | `clientData`    | `unknown`            | Custom data from the frontend                        |
@@ -514,6 +544,7 @@ All methods available on the `chat` object from `@trigger.dev/sdk/ai`.
 | `chat.messages`                             | Incoming message mailbox; supports non-consuming `.peek()` / `.hasPending()`, single-record `.next()`, `.on()`, and suspend-aware `.waitWithIdleTimeout()` |
 | `chat.local<T>({ id })`                     | Create a per-run typed local (see [`chat.local`](/ai-chat/chat-local))                             |
 | `chat.createStartSessionAction(taskId, options?)` | Returns a server action that creates a chat Session + triggers the first run + returns a session-scoped PAT. Idempotent on `(env, externalId)`.   |
+| `chat.createLoadTranscriptAction(storage, options?)` | Returns a server action that reads a conversation from a transcript storage (`{ chatId, clientData?, limit?, before? }` → `TranscriptLoadResult`). Pair with `useLoadTranscript`. Performs no application authorization: authorize `chatId` for the signed-in user in your own code. See [Transcript storage](/ai-chat/transcript-storage#reading-the-transcript) |
 | `chat.waitForHandover(options)`             | Wait for a [`chat.headStart`](/ai-chat/fast-starts#handover-with-custom-agents) handover signal in a custom loop. Returns the signal or `null`. `chat.MessageAccumulator` wraps this as `consumeHandover()` / `applyHandover()` |
 | `chat.requestUpgrade()`                     | End the current run after this turn so the next message starts on the latest agent version. Server-orchestrated handoff.    |
 | `chat.close({ reason })`                    | End the conversation permanently: close the session row, write a terminal `session-closed` record, and exit without a continuation. Decide it before the turn ends (`onBeforeTurnComplete`, not `onTurnComplete`) so the client sees the closed state on that turn. |
@@ -876,6 +907,26 @@ Second argument to `chat.createStartSessionAction(taskId, options?)`. Controls h
 | `baseURL`        | `string \| (ctx: { endpoint: "sessions" \| "auth"; chatId: string }) => string`      | `apiClientManager.baseURL`    | API base URL. `endpoint` is `"sessions"` for `POST /api/v1/sessions` or `"auth"` for `POST /api/v1/auth/jwt/claims` (only fires when `tokenTTL` is set). |
 | `fetch`          | `(url: string, init: RequestInit, ctx: { endpoint: "sessions" \| "auth"; chatId: string }) => Promise<Response>` | —                             | Per-request fetch override. Use to route session-create through a trusted edge proxy so `basePayload.metadata` is rewritten before reaching `api.trigger.dev`. |
 
+## createLoadTranscriptAction options
+
+Second argument to `chat.createLoadTranscriptAction(storage, options?)`.
+
+| Option      | Type                     | Default                    | Description                                                                 |
+| ----------- | ------------------------ | -------------------------- | --------------------------------------------------------------------------- |
+| `limit`     | `number`                 | —                          | Page size when the caller passes none. Returns the most recent messages and a `nextCursor`. |
+| `apiClient` | `ApiClientConfiguration` | `apiClientManager` config  | Scope the read to a specific API client (secret key, base URL). The default storage reads through it. |
+
+## useLoadTranscript
+
+`useLoadTranscript(chatId, load, options?)` from `@trigger.dev/sdk/chat/react`. Loads a conversation through a `chat.createLoadTranscriptAction` action, for rendering before the chat connects. Re-runs when `chatId` changes.
+
+| Option      | Type                   | Description                                                                                  |
+| ----------- | ---------------------- | -------------------------------------------------------------------------------------------- |
+| `transport` | `TriggerChatTransport` | Seed the transport's resume cursor for this chat from the transcript, once it knows the session. |
+| `limit`     | `number`               | Page size passed to the action.                                                              |
+
+Returns `{ messages, isLoading, error, nextCursor }`. `nextCursor` is the id to pass as `before` to the action for the page before this one.
+
 ## useMultiTabChat
 
 React hook for multi-tab message coordination. Import from `@trigger.dev/sdk/chat/react`.

package/docs/ai-chat/transcript-storage.mdx

@@ -0,0 +1,233 @@
+---
+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`

package/docs/config/extensions/syncEnvVars.mdx

@@ -63,6 +63,12 @@ export default defineConfig({
 
 In this example we're using env vars from [Infisical](https://infisical.com).
 
+<Tip>
+  Infisical also offers a native [Secret Sync](/deploy-environment-variables#infisical-secret-sync)
+  that pushes secrets to Trigger.dev without a build extension or a redeploy. Use `syncEnvVars` when
+  you want to resolve secrets at deploy time in code, or for a service without a native sync.
+</Tip>
+
 ```ts trigger.config.ts
 import { defineConfig } from "@trigger.dev/sdk";
 import { syncEnvVars } from "@trigger.dev/build/extensions/core";

package/docs/deploy-environment-variables.mdx

@@ -184,14 +184,35 @@ For more information about the context object, see the [Context documentation](/
 
 ### Sync env vars from another service
 
-You could use the SDK functions above but it's much easier to use our `syncEnvVars` build extension in your `trigger.config` file.
+There are two ways to pull secrets from another service into Trigger.dev: a native **Secret Sync** (currently [Infisical](https://infisical.com)), or the `syncEnvVars` build extension for any other service.
+
+#### Infisical Secret Sync
+
+If your secrets live in [Infisical](https://infisical.com), sync them natively, without a build extension or a redeploy. You configure the sync in the Infisical dashboard, and it pushes secrets straight to your [Environment Variables page](#in-the-dashboard) in Trigger.dev. When a secret changes in Infisical the sync updates the matching variable, and your tasks pick up the new value on their next run.
+
+Set it up in Infisical in two steps:
+
+1. Add a **Trigger.dev App Connection** using a Trigger.dev Personal Access Token from your account settings. Self-hosted instances are supported.
+2. Create a **Secret Sync**: choose the connection, pick the target organization, project and environment (Production, Staging, Development, or Preview), and set the secret path to sync.
+
+Follow the [Trigger.dev Secret Sync guide](https://infisical.com/docs/integrations/secret-syncs/trigger-dev) in the Infisical docs for the full walkthrough.
+
+<Note>
+  A Secret Sync only overwrites the keys it manages, leaving variables you set manually untouched.
+  Synced variables are marked as [secret](#secret-environment-variables) by default, so they appear
+  redacted on the Environment Variables page.
+</Note>
+
+#### Using the `syncEnvVars` build extension
+
+For any other service, use our `syncEnvVars` build extension in your `trigger.config` file to resolve secrets at deploy time.
 
 <Note>
   To use the `syncEnvVars` build extension, you should first install the `@trigger.dev/build`
   package into your devDependencies.
 </Note>
 
-In this example we're using env vars from [Infisical](https://infisical.com).
+In this example we're using env vars from [Infisical](https://infisical.com), but you can adapt it to any secrets manager.
 
 ```ts trigger.config.ts
 import { defineConfig } from "@trigger.dev/sdk";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "0.0.0-prerelease-20260908122921",
+  "version": "0.0.0-prerelease-20260909071038",
   "description": "trigger.dev Node.JS SDK",
   "license": "MIT",
   "publishConfig": {
@@ -69,7 +69,7 @@
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/semantic-conventions": "1.41.1",
-    "@trigger.dev/core": "0.0.0-prerelease-20260908122921",
+    "@trigger.dev/core": "0.0.0-prerelease-20260909071038",
     "uncrypto": "^0.1.3"
   },
   "devDependencies": {

package/skills/trigger-authoring-chat-agent/SKILL.md

@@ -222,8 +222,9 @@ frontend, narrow `useChat` with `InferChatUIMessage<typeof myChat>` from `@trigg
 `chat.agent` accepts hooks that fire in a fixed per-turn order:
 
 ```text
-onValidateMessages -> hydrateMessages -> onChatStart (chat's first message only)
-  -> onTurnStart -> run() -> onBeforeTurnComplete -> onTurnComplete
+onValidateMessages -> storage.loadContext (or the deprecated hydrateMessages)
+  -> onChatStart (chat's first message only)
+  -> onTurnStart -> run() -> onBeforeTurnComplete -> onTurnComplete -> storage.save
 ```
 
 `onBoot` fires once per worker process (every fresh boot, including continuation runs) and is where

package/skills/trigger-chat-agent-advanced/SKILL.md

@@ -193,11 +193,11 @@ compaction: {
 to also emit a model response, built with the `streamText` from `onAction`'s own argument so it
 carries the agent's prompt and tools like any other turn.
 
-Persistence splits by model. Without `hydrateMessages` the runtime snapshots the conversation after
-an action that changed it, so a rollback or a returned response survives the run ending. With
-`hydrateMessages` your store is the source of truth and the runtime does not write, so mirror every
-mutation yourself: a regenerate is a delete and an insert, and `chat.pipeAndCapture` hands back the
-same assistant message the runtime would have captured.
+Persistence goes through the agent's transcript storage (`storage` on `chat.agent`; the platform
+snapshot by default). After an action that changed the conversation the runtime hands the storage a
+changeset: an undo is one `truncateAfter`, a regenerate is a `truncateAfter` plus the new answer's
+`put`. With the deprecated `hydrateMessages` your store is the source of truth and the runtime does
+not write, so mirror every mutation yourself: a regenerate is a delete and an insert.
 
 ```ts
 export const myChat = chat.agent({