@trigger.dev/sdk 0.0.0-prerelease-20260909121655 → 0.0.0-prerelease-20260911153544

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/commonjs/v3/ai.d.ts +36 -0
  2. package/dist/commonjs/v3/ai.js +260 -55
  3. package/dist/commonjs/v3/ai.js.map +1 -1
  4. package/dist/commonjs/v3/auth.d.ts +10 -4
  5. package/dist/commonjs/v3/auth.js.map +1 -1
  6. package/dist/commonjs/v3/chatSnapshotIo.js +6 -7
  7. package/dist/commonjs/v3/chatSnapshotIo.js.map +1 -1
  8. package/dist/commonjs/v3/retry.d.ts +4 -0
  9. package/dist/commonjs/v3/retry.js +22 -13
  10. package/dist/commonjs/v3/retry.js.map +1 -1
  11. package/dist/commonjs/v3/test/transcript-storage-tests.js.map +1 -1
  12. package/dist/commonjs/v3/transcriptStorage.d.ts +43 -6
  13. package/dist/commonjs/v3/transcriptStorage.js +87 -8
  14. package/dist/commonjs/v3/transcriptStorage.js.map +1 -1
  15. package/dist/commonjs/version.js +1 -1
  16. package/dist/esm/v3/ai.d.ts +36 -0
  17. package/dist/esm/v3/ai.js +260 -55
  18. package/dist/esm/v3/ai.js.map +1 -1
  19. package/dist/esm/v3/auth.d.ts +10 -4
  20. package/dist/esm/v3/auth.js.map +1 -1
  21. package/dist/esm/v3/chatSnapshotIo.js +7 -8
  22. package/dist/esm/v3/chatSnapshotIo.js.map +1 -1
  23. package/dist/esm/v3/retry.d.ts +4 -0
  24. package/dist/esm/v3/retry.js +14 -8
  25. package/dist/esm/v3/retry.js.map +1 -1
  26. package/dist/esm/v3/test/transcript-storage-tests.js.map +1 -1
  27. package/dist/esm/v3/transcriptStorage.d.ts +43 -6
  28. package/dist/esm/v3/transcriptStorage.js +85 -8
  29. package/dist/esm/v3/transcriptStorage.js.map +1 -1
  30. package/dist/esm/version.js +1 -1
  31. package/docs/ai-chat/background-injection.mdx +54 -1
  32. package/docs/ai-chat/how-it-works.mdx +1 -1
  33. package/docs/ai-chat/migrating-from-hydrate-messages.mdx +299 -0
  34. package/docs/ai-chat/patterns/database-persistence.mdx +18 -7
  35. package/docs/ai-chat/reference.mdx +2 -1
  36. package/docs/ai-chat/side-channels.mdx +1 -1
  37. package/docs/ai-chat/transcript-storage.mdx +21 -7
  38. package/docs/self-hosting/security.mdx +12 -0
  39. package/package.json +2 -2
  40. package/skills/trigger-chat-agent-advanced/SKILL.md +31 -15
@@ -179,9 +179,62 @@ export const myChat = chat.agent({
179
179
  `chat.defer()` can be called from anywhere during a turn: hooks, `run()`, or nested helpers. All deferred promises are collected and awaited together before `onTurnComplete`.
180
180
 
181
181
  <Warning>
182
- **Don't use `chat.defer()` for the message-history write in `onTurnStart`.** That write must land *before* the model starts streaming, otherwise a mid-stream page refresh will read `[]` from your DB and lose the user's message from the rendered conversation. See [Database persistence: `onTurnStart`](/ai-chat/patterns/database-persistence#onturnstart). Reserve `chat.defer` for writes whose timing has no resume implication.
182
+ **Don't use `chat.defer()` for the message-history write in `onTurnStart`.** `chat.defer` only promises the work finished before `onTurnComplete`, which is long after the answer started streaming. A page refresh in between reads `[]` from your DB and loses the user's message from the rendered conversation. Use [`chat.deferBeforeOutput()`](#chat-deferbeforeoutput) for that write instead, and reserve `chat.defer` for writes whose timing has no resume implication.
183
183
  </Warning>
184
184
 
185
+ ## `chat.deferBeforeOutput`
186
+
187
+ `chat.deferBeforeOutput()` is `chat.defer()` for work the next page load has to see. The work starts immediately and the hook does not await it, so it runs alongside the model and costs no time to first token. The difference is that the output stream waits for it: no part of the answer is written to the session until it settles.
188
+
189
+ That ordering is the point. A reader that can see the answer can also see whatever the work persisted, so a refresh mid-answer never renders a reply to a question that is missing.
190
+
191
+ ```ts
192
+ export const myChat = chat.agent({
193
+ id: "my-chat",
194
+ onTurnStart: async ({ chatId, uiMessages }) => {
195
+ // The next page load has to see this, so the answer waits for it.
196
+ chat.deferBeforeOutput(
197
+ db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } })
198
+ );
199
+ },
200
+ run: async ({ messages, signal, streamText }) => {
201
+ return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
202
+ },
203
+ });
204
+ ```
205
+
206
+ Use it for the conversation write, a message insert, or anything else the frontend reads back on reload. Keep analytics, audit logs and search-index updates on `chat.defer`.
207
+
208
+ <Warning>
209
+ **This is not a consistency barrier for the turn.** It orders the write against what the frontend can see, and nothing else. The work is still in flight while the model runs, so a tool, a `prepareStep`, or another service reading the same row during the turn can still see the state as it was before the write.
210
+
211
+ If the turn's own code reads the write back, `await` it instead:
212
+
213
+ ```ts
214
+ onTurnStart: async ({ chatId, uiMessages }) => {
215
+ // A tool later in this turn reads this row, so the turn has to wait for it.
216
+ await db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } });
217
+ },
218
+ ```
219
+
220
+ That costs time to first token, which is the price of the stronger guarantee. `chat.deferBeforeOutput` is for writes whose only reader is the next page load.
221
+ </Warning>
222
+
223
+ A registered promise that rejects, or that runs longer than the internal timeout, lets the answer through rather than stalling the conversation. It is a best-effort ordering guarantee, not a lock.
224
+
225
+ | | `chat.defer()` | `chat.deferBeforeOutput()` |
226
+ |---|---|---|
227
+ | **Awaited by the hook** | No | No |
228
+ | **Costs time to first token** | No | No |
229
+ | **Answer waits for it** | No | Yes |
230
+ | **Settled by** | Before `onTurnComplete` | Before the first chunk reaches the session |
231
+ | **Read back by tools in the same turn** | No | No |
232
+ | **Use for** | Analytics, audit logs, index writes | Conversation and message writes the frontend reads back |
233
+
234
+ <Note>
235
+ If your agent persists through a [transcript storage](/ai-chat/transcript-storage), the runtime already does this for the incoming message on your behalf. `chat.deferBeforeOutput` is for writes your app owns on top of that.
236
+ </Note>
237
+
185
238
  ## How it differs from pending messages
186
239
 
187
240
  | | `chat.inject()` | [Pending messages](/ai-chat/pending-messages) |
@@ -90,7 +90,7 @@ Here is a typical cold turn — user opens the page, types "What's the weather?"
90
90
  Immediately after writing the new turn-complete marker, the agent issues an S2 trim command targeting the *previous* turn-complete's sequence number. This bounds the stream's storage to roughly one turn of chunks plus the latest control record.
91
91
  </Step>
92
92
  <Step title="Task: fires onTurnComplete, writes snapshot to S3">
93
- `onTurnComplete` runs (your hook for persistence). Then the agent writes `ChatSnapshotV1` — `{ version: 1, messages, lastOutEventId, lastOutTimestamp }` — to S3 at `sessions/:chatId/snapshot.json`. This write is awaited, not fire-and-forget, so the next run is guaranteed to find it.
93
+ `onTurnComplete` runs (your hook for persistence). Then the agent writes the transcript to S3 at `sessions/:chatId/snapshot.json`: a header line carrying the stream cursors and the runtime's own state, one line per message, and an index of the messages at the end so a page of history can be read without downloading the whole conversation. Once [compaction](/ai-chat/compaction) has run, only the most recent messages are kept, so the file stops growing with the conversation. If you need the full history, keep your own [transcript storage](/ai-chat/transcript-storage). This write is awaited, not fire-and-forget, so the next run is guaranteed to find it.
94
94
  </Step>
95
95
  <Step title="Task: goes idle, then suspends">
96
96
  The agent re-enters the waitpoint on `.in`. After `idleTimeoutInSeconds` of nothing arriving, `onChatSuspend` fires and the engine snapshots the run. Compute is freed.
@@ -0,0 +1,299 @@
1
+ ---
2
+ title: "Migrate from hydrateMessages to transcript storage"
3
+ sidebarTitle: "Migrating from hydrateMessages"
4
+ description: "Move a chat.agent that persists its own history through hydrateMessages onto a TranscriptStorage: map your tables, implement load and save, decide whether you need loadContext, and delete the recovery and compaction code you no longer own."
5
+ ---
6
+
7
+ Learn how to replace a `hydrateMessages` hook with a `storage` on the same tables, so the runtime writes the conversation for you and your app stops re-deriving what the runtime already knows.
8
+
9
+ `hydrateMessages` keeps working with a one-time deprecation warning, so you can migrate one agent at a time. Setting both `hydrateMessages` and `storage` on one agent is a startup error, which makes the switch a swap rather than an overlap.
10
+
11
+ ## What changes hands
12
+
13
+ With `hydrateMessages`, your hook was the source of truth and the runtime wrote nothing, so your app re-derived from its own rows everything the runtime already knew. A [transcript storage](/ai-chat/transcript-storage) inverts that: the runtime owns the transcript and calls your storage at the durable boundaries.
14
+
15
+ | Concern | With `hydrateMessages` | With `storage` |
16
+ | --- | --- | --- |
17
+ | Reading history | Your hook, on every turn and action | `load`, once when a run boots |
18
+ | Writing the user's message and the answer | Your `onTurnStart` / `onTurnComplete` code | `save` receives them as `put` changes |
19
+ | A message sent mid-answer (steering) | You wrote it, and placed it before the answer | Arrives in the same changeset, in order |
20
+ | Undo, edit, regenerate | Row writes paired with each `chat.history` call | Arrive as `truncateAfter` and `put` changes |
21
+ | Partial answer after a crash | Your partial rows and a recovery flag | A `put` with `final: false`; you report it back in `nonFinalIds` |
22
+ | Tool call the dead run never answered | Your repair pass | Cleaned up by the runtime before the save |
23
+ | Compaction summary | Your summary column and watermark, invalidated on every rollback path | An opaque `state` blob you store and return; the runtime discards it when a rollback crosses it |
24
+ | Resume cursors | Your `lastEventId` write, in the same transaction as the answer | `cursors` on the changeset; write them in the same transaction |
25
+ | Deciding what the model sees | The array your hook returned | The transcript, or `loadContext` if your database decides |
26
+
27
+ ## Before you start
28
+
29
+ - Your message table needs three things per row: the message id, the `UIMessage` itself, and a column to order by. If you stored messages as `ModelMessage`s, convert your existing rows first; a storage holds `UIMessage`s only.
30
+ - Add somewhere to keep an opaque JSON blob per chat (the runtime's `state`) and two opaque string cursors per chat.
31
+ - If you have a `final`, `status` or `partial` flag already, keep it. If not, add one; it is how a cut-short answer stays marked across a continuation.
32
+
33
+ <Steps>
34
+ <Step title="Implement load">
35
+ `load` returns the conversation in order, the `state` blob, the cursors, and the ids of any rows you stored as partial. Scope the read by `clientData` where your backend enforces tenancy.
36
+
37
+ ```ts lib/transcript-storage.ts
38
+ import type { TranscriptStorage } from "@trigger.dev/sdk/ai";
39
+ import { db } from "@/lib/db";
40
+
41
+ type Scope = { userId: string };
42
+
43
+ export const transcriptStorage: TranscriptStorage<Scope> = {
44
+ async load({ chatId, clientData }, opts) {
45
+ const chat = await db.chat.findUnique({
46
+ where: { id: chatId },
47
+ include: { session: true },
48
+ });
49
+ if (chat && chat.userId !== clientData.userId) {
50
+ throw new Error("This conversation could not be loaded.");
51
+ }
52
+ if (!chat) return { messages: [], state: null };
53
+
54
+ const cursors = {
55
+ lastOutEventId: chat.session?.lastEventId ?? undefined,
56
+ lastInEventId: chat.session?.lastInEventId ?? undefined,
57
+ };
58
+
59
+ let before: number | undefined;
60
+ if (opts?.before) {
61
+ const anchor = await db.message.findUnique({
62
+ where: { chatId_id: { chatId, id: opts.before } },
63
+ });
64
+ if (!anchor) return { messages: [], state: chat.transcriptState, cursors };
65
+ before = anchor.position;
66
+ }
67
+ const where = { chatId, ...(before !== undefined ? { position: { lt: before } } : {}) };
68
+
69
+ let rows;
70
+ let nextCursor: string | undefined;
71
+ if (opts?.limit) {
72
+ const page = await db.message.findMany({
73
+ where,
74
+ orderBy: { position: "desc" },
75
+ take: opts.limit + 1,
76
+ });
77
+ rows = page.slice(0, opts.limit).reverse();
78
+ if (page.length > opts.limit) nextCursor = rows[0]?.id;
79
+ } else {
80
+ rows = await db.message.findMany({ where, orderBy: { position: "asc" } });
81
+ }
82
+
83
+ return {
84
+ messages: rows.map((row) => row.message),
85
+ state: chat.transcriptState,
86
+ cursors,
87
+ nextCursor,
88
+ nonFinalIds: rows.filter((row) => row.status === "partial").map((row) => row.id),
89
+ };
90
+ },
91
+
92
+ async save(ctx, changeset) {
93
+ // next step
94
+ },
95
+ };
96
+ ```
97
+
98
+ The runtime calls `load` with no options and wants the whole conversation. Your frontend's [history read](/ai-chat/transcript-storage#reading-the-transcript) passes `limit` (and later `before`), so the example fetches one extra row to tell whether earlier messages exist and returns the oldest included id as `nextCursor`.
99
+ </Step>
100
+
101
+ <Step title="Implement save">
102
+ Apply the changeset's `changes` to your rows and write the `cursors`, in one transaction. The cursor tells a reconnecting client what it has already seen; a cursor that lands ahead of the rows it accounts for makes that client skip chunks stored nowhere.
103
+
104
+ ```ts lib/transcript-storage.ts
105
+ async save({ chatId, clientData }, changeset) {
106
+ await db.$transaction(async (tx) => {
107
+ const chat = await tx.chat.findUnique({ where: { id: chatId } });
108
+ if (chat && chat.userId !== clientData.userId) {
109
+ throw new Error("This conversation could not be saved.");
110
+ }
111
+ if (!chat) await tx.chat.create({ data: { id: chatId, userId: clientData.userId } });
112
+
113
+ let next = (await lastPosition(tx, chatId)) + 1;
114
+
115
+ for (const change of changeset.changes) {
116
+ switch (change.op) {
117
+ case "put": {
118
+ const status = change.final === false ? "partial" : "complete";
119
+ const existing = await tx.message.findUnique({
120
+ where: { chatId_id: { chatId, id: change.message.id } },
121
+ });
122
+ if (existing) {
123
+ await tx.message.update({
124
+ where: { chatId_id: { chatId, id: change.message.id } },
125
+ data: { message: change.message, status },
126
+ });
127
+ } else {
128
+ await tx.message.create({
129
+ data: { chatId, id: change.message.id, position: next++, message: change.message, status },
130
+ });
131
+ }
132
+ break;
133
+ }
134
+ case "remove":
135
+ await tx.message.deleteMany({ where: { chatId, id: change.id } });
136
+ break;
137
+ case "truncateAfter": {
138
+ const anchor = await tx.message.findUnique({
139
+ where: { chatId_id: { chatId, id: change.afterId } },
140
+ });
141
+ if (anchor) {
142
+ await tx.message.deleteMany({ where: { chatId, position: { gt: anchor.position } } });
143
+ next = anchor.position + 1;
144
+ }
145
+ break;
146
+ }
147
+ case "state":
148
+ await tx.chat.update({ where: { id: chatId }, data: { transcriptState: change.value } });
149
+ break;
150
+ }
151
+ }
152
+
153
+ if (changeset.cursors) {
154
+ await tx.chatSession.upsert({
155
+ where: { chatId },
156
+ create: { chatId, ...cursorColumns(changeset.cursors) },
157
+ update: cursorColumns(changeset.cursors),
158
+ });
159
+ }
160
+ });
161
+ }
162
+ ```
163
+
164
+ Three rules keep the rows in the runtime's order:
165
+
166
+ - Assign a position only when a row is first inserted, in the order the `put`s arrive. Within one changeset that is conversation order, so a steer sent mid-answer lands before the answer it shaped.
167
+ - Leave the position alone on a `put` for a known id. A tool approval, a settled partial and a compaction all replace a message in place.
168
+ - Do not order by a write timestamp. A replaced message would jump to the end, and a steer written after the answer would sort after it.
169
+
170
+ If you keep the whole conversation as one document instead of rows, ignore `changes` and write `changeset.transcript` as-is. Pick one of the two and stay with it.
171
+ </Step>
172
+
173
+ <Step title="Decide whether you need loadContext">
174
+ Most `hydrateMessages` hooks did two jobs: they persisted the incoming message and they returned the history. `save` and `load` cover both, so most agents need nothing more.
175
+
176
+ Add `loadContext` only when your database decides what the model sees each turn: a branching conversation where only the active branch is context, or a trust boundary where the browser's history is not to be believed. The runtime calls it on every turn and action with the incoming messages and the transcript it had, and uses what you return as the conversation. `save` keeps receiving every change and crash recovery keeps running.
177
+
178
+ ```ts lib/transcript-storage.ts
179
+ loadContext: async ({ chatId, clientData }, { incomingMessages }) => {
180
+ const branch = await db.activeBranch(chatId, clientData.userId);
181
+ return [...branch, ...incomingMessages];
182
+ },
183
+ ```
184
+
185
+ Do not port the body of your `hydrateMessages` hook into `loadContext` wholesale. The writes in it belong in `save`, and the recovery and compaction logic in it is gone.
186
+ </Step>
187
+
188
+ <Step title="Swap the option">
189
+ Set `storage`, remove `hydrateMessages`, and let the agent boot. It throws on start if both are still present.
190
+
191
+ ```ts trigger/chat.ts
192
+ export const myChat = chat.agent({
193
+ id: "my-chat",
194
+ storage: transcriptStorage,
195
+ clientDataSchema: z.object({ userId: z.string() }),
196
+ run: async ({ messages, signal, streamText }) =>
197
+ streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
198
+ });
199
+ ```
200
+ </Step>
201
+
202
+ <Step title="Delete what the runtime now owns">
203
+ Work through your hooks and remove every write that duplicates a change the storage receives:
204
+
205
+ - Message writes in `onTurnStart` and `onTurnComplete`, including the steering messages you filed from `newUIMessages` or `pendingMessages.onReceived`.
206
+ - The `lastEventId` write in `onTurnComplete`. The cursor now arrives on the changeset.
207
+ - Row writes paired with `chat.history` calls in `onAction`. An undo is a `truncateAfter`, an edit is a `put` and a `truncateAfter`. To answer after an edit, return `chat.turn()`; returning a model response from `onAction` is no longer supported.
208
+ - Per-step partial writes in `onStepFinish`, and any run-state or "still streaming" flag. A crash is recovered from the durable session stream, and a partial that survives reaches `save` with `final: false`.
209
+ - Dangling tool-call repair. The runtime cleans a partial before it saves it.
210
+ - Your compaction summary column, its watermark, and the invalidation you ran on every rollback path. The summary travels in `state`, and the runtime discards it when a rollback crosses the point it covers.
211
+ - Any filter that dropped an empty assistant message. A turn that fails before the model writes anything is not handed to `save`.
212
+
213
+ Keep `onTurnStart` for the session token if your frontend hydrates from your own table, and keep `onTurnComplete` for side work such as naming the conversation.
214
+ </Step>
215
+
216
+ <Step title="Update the history read on your frontend">
217
+ Your page most likely reads history from your tables directly. That keeps working. To use the same read the runtime uses, and to seed the live subscription's cursor so a reload does not replay what it just loaded, wrap the storage in a server action and load it with the hook:
218
+
219
+ <CodeGroup>
220
+ ```ts app/actions.ts
221
+ "use server";
222
+ import { chat } from "@trigger.dev/sdk/ai";
223
+ import { transcriptStorage } from "@/lib/transcript-storage";
224
+
225
+ const load = chat.createLoadTranscriptAction(transcriptStorage);
226
+
227
+ export async function loadTranscript(params: { chatId: string; limit?: number; before?: string }) {
228
+ const userId = await getUserId();
229
+ await assertOwnsChat(userId, params.chatId);
230
+ return load({ ...params, clientData: { userId } });
231
+ }
232
+ ```
233
+
234
+ ```tsx app/c/[chatId]/ChatPage.tsx
235
+ "use client";
236
+ import { useLoadTranscript, useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
237
+ import { loadTranscript } from "@/app/actions";
238
+
239
+ export function ChatPage({ chatId }: { chatId: string }) {
240
+ const transport = useTriggerChatTransport({ task: "my-chat", accessToken, startSession });
241
+ const { messages, isLoading, nextCursor } = useLoadTranscript(chatId, loadTranscript, {
242
+ transport,
243
+ limit: 50,
244
+ });
245
+ if (isLoading) return <Spinner />;
246
+ return <Chat chatId={chatId} initialMessages={messages} transport={transport} olderPage={nextCursor} />;
247
+ }
248
+ ```
249
+ </CodeGroup>
250
+
251
+ <Warning>
252
+ The action receives `chatId` from the browser. Authorize it there, before calling the storage. The storage's own `clientData` check is a backstop, not the boundary.
253
+ </Warning>
254
+ </Step>
255
+
256
+ <Step title="Run the conformance suite">
257
+ Point `runTranscriptStorageTests` at your storage. It checks appends and in-place replacement, idempotent `remove` and `truncateAfter`, `state` round-trips, cursors, replaying the same changeset twice, paging, and chat isolation, against whatever database you give it.
258
+
259
+ ```ts lib/transcript-storage.test.ts
260
+ import { runTranscriptStorageTests } from "@trigger.dev/sdk/ai/test";
261
+ import { describe, expect, it } from "vitest";
262
+ import { transcriptStorage } from "./transcript-storage";
263
+
264
+ runTranscriptStorageTests(() => transcriptStorage, {
265
+ api: { describe, it, expect },
266
+ clientData: { userId: "user_test" },
267
+ });
268
+ ```
269
+
270
+ `memoryTranscriptStorage()` is the reference implementation. Use it in your agent tests to see exactly which changes the runtime hands a storage for a given turn.
271
+ </Step>
272
+ </Steps>
273
+
274
+ ## Behaviour that changes
275
+
276
+ A few things your users and your tests will notice after the swap:
277
+
278
+ - **Actions are edits.** `onAction` mutates `chat.history` and returns nothing, or returns `chat.turn()` to have a full turn answer the edited history. The regenerated answer is saved and remembered like any other. See [Actions](/ai-chat/actions#answering-after-an-action).
279
+ - **`onRecoveryBoot` is informational.** It fires when a run boots after a crash and finds a half-written answer on the session stream. The runtime already reconciled the transcript; use the hook to tell the user, not to write rows.
280
+ - **A failed turn keeps its partial, marked.** An answer cut short reaches `save` with `final: false`; report those ids back from `load` in `nonFinalIds`.
281
+ - **Compaction survives a reboot without your help.** The summary travels in `state`.
282
+ - **Your rows do not have to be byte-identical.** Store messages in whatever shape your database prefers. The runtime does not depend on an exact JSON round-trip.
283
+
284
+ ## Checklist
285
+
286
+ - [ ] `load` returns messages in conversation order, plus `state`, `cursors` and `nonFinalIds`
287
+ - [ ] `save` applies all four change kinds and writes the cursors in the same transaction
288
+ - [ ] Positions are assigned on first insert only, never by timestamp
289
+ - [ ] `hydrateMessages` removed; `storage` set; the agent boots
290
+ - [ ] Message, cursor, partial, repair and compaction writes deleted from hooks
291
+ - [ ] `onAction` returns `chat.turn()` where it used to stream an answer
292
+ - [ ] `runTranscriptStorageTests` passes against the real database
293
+
294
+ ## See also
295
+
296
+ - [Transcript storage](/ai-chat/transcript-storage): the full contract and what `save` receives
297
+ - [Actions](/ai-chat/actions): what undo, edit and regenerate become in the changeset
298
+ - [Lifecycle hooks](/ai-chat/lifecycle-hooks#hydratemessages): the deprecated hook's reference entry
299
+ - [Database persistence](/ai-chat/patterns/database-persistence): the hook-based pattern this replaces
@@ -56,24 +56,34 @@ If you skip preload, do the equivalent in **`onChatStart`** when **`preloaded`**
56
56
 
57
57
  ### `onTurnStart`
58
58
 
59
- - **`await`** persist **`uiMessages`** (full accumulated history including the new user turn) **before** the hook returns — `chat.agent` does not begin streaming until `onTurnStart` resolves, so this is what bounds "user message is durable before the stream".
59
+ - Persist **`uiMessages`** (full accumulated history including the new user turn). Two ways, and which one you want depends on who reads the write:
60
+ - **Nothing in the turn reads it back** (the usual case: the row exists for the next page load). Use [**`chat.deferBeforeOutput()`**](/ai-chat/background-injection#chat-deferbeforeoutput). The write runs alongside the model, so it adds nothing to time to first token, and no part of the answer reaches the frontend until it lands. That bounds "user message is durable before anything can render the answer".
61
+ - **A tool, a `prepareStep`, or another service reads it back during the turn.** **`await`** it. `chat.deferBeforeOutput` orders the write against the frontend, not against the model, so the turn's own code can still see pre-write state. Awaiting costs time to first token and is the only thing that bounds "durable before the model starts".
60
62
 
61
63
  <Warning>
62
- **Don't use [`chat.defer()`](/ai-chat/background-injection#chat-defer-standalone) for the message write here.** `chat.defer` is fire-and-forget — the hook resolves before the write lands and the stream starts immediately. If the user refreshes mid-stream, the next page load reads `[]` from your DB, the resumed SSE stream pushes the assistant into an empty array, and the user's message disappears from the rendered conversation forever.
64
+ **Don't use [`chat.defer()`](/ai-chat/background-injection#chat-defer-standalone) for the message write here.** `chat.defer` is fire-and-forget: the hook resolves, the stream starts immediately, and the write is only guaranteed before `onTurnComplete`. If the user refreshes in between, the next page load reads `[]` from your DB, the resumed SSE stream pushes the assistant into an empty array, and the user's message disappears from the rendered conversation.
63
65
 
64
66
  ```ts
65
- // ❌ Bad — non-blocking write, mid-stream refresh drops the user message.
67
+ // ❌ Bad: the answer can stream before the write lands.
66
68
  onTurnStart: async ({ chatId, uiMessages }) => {
67
69
  chat.defer(db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } }));
68
70
  },
69
71
 
70
- // ✅ Good — awaited, durable before the model starts.
72
+ // ✅ Good: runs alongside the model, and the answer waits for it.
73
+ onTurnStart: async ({ chatId, uiMessages }) => {
74
+ chat.deferBeforeOutput(
75
+ db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } })
76
+ );
77
+ },
78
+
79
+ // ✅ Required when a tool or prepareStep in this turn reads the row back.
80
+ // Slower: awaiting blocks the model call itself.
71
81
  onTurnStart: async ({ chatId, uiMessages }) => {
72
82
  await db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } });
73
83
  },
74
84
  ```
75
85
 
76
- `chat.defer` is for writes whose timing doesn't matter for resume — analytics, audit logs, search-index updates, etc. Anything the next page load reads needs to land before the stream begins.
86
+ `chat.defer` is for writes whose timing doesn't matter for resume: analytics, audit logs, search-index updates. Anything the next page load reads belongs on `chat.deferBeforeOutput`.
77
87
  </Warning>
78
88
 
79
89
  ### `onTurnComplete`
@@ -152,8 +162,9 @@ chat.agent({
152
162
  },
153
163
 
154
164
  onTurnStart: async ({ chatId, uiMessages }) => {
155
- // Awaited, not chat.defer — see the warning in `onTurnStart` above.
156
- await saveConversationMessages(chatId, uiMessages);
165
+ // Held before output, not chat.defer. See the warning in `onTurnStart` above.
166
+ // Nothing in this turn reads the row back; await it if yours does.
167
+ chat.deferBeforeOutput(saveConversationMessages(chatId, uiMessages));
157
168
  },
158
169
 
159
170
  onTurnComplete: async ({ chatId, uiMessages, chatAccessToken, lastEventId }) => {
@@ -987,9 +987,10 @@ Tokens minted for `TriggerChatTransport` and `AgentChat` are session-scoped —
987
987
  | Scope | Grants |
988
988
  | --- | --- |
989
989
  | `read:sessions:<chatId>` | Subscribe to `.out`, HEAD probe the stream, retrieve the session row |
990
+ | `read:sessions:<chatId>:out` | Subscribe to `.out` and HEAD probe the stream only. Use this when the browser needs nothing but the response stream. |
990
991
  | `write:sessions:<chatId>` | Append to `.in`, close the session, end-and-continue, update metadata |
991
992
 
992
- Tokens are produced by `auth.createPublicToken({ scopes: { read: { sessions: chatId }, write: { sessions: chatId } } })` (used by the customer's `accessToken` server action) or returned automatically from `chat.createStartSessionAction` / `POST /api/v1/sessions`. Either form authorizes both URL forms (`/sessions/{chatId}/...` and `/sessions/session_*/...`) on every read and write route.
993
+ Reading `.in` requires a secret key, so no browser token can replay what clients sent. Tokens are produced by `auth.createPublicToken({ scopes: { read: { sessions: chatId }, write: { sessions: chatId } } })` (used by the customer's `accessToken` server action) or returned automatically from `chat.createStartSessionAction` / `POST /api/v1/sessions`. Either form authorizes both URL forms (`/sessions/{chatId}/...` and `/sessions/session_*/...`) on every read and write route.
993
994
 
994
995
  ## Related
995
996
 
@@ -138,7 +138,7 @@ A side channel's streams are bounded by the same retention as the rest of your r
138
138
 
139
139
  ## Auth
140
140
 
141
- A side channel is covered by the session's public access token: a token scoped to `read:sessions:{id}` / `write:sessions:{id}` grants every channel of that session. Mint a narrower token scoped to a single channel with `read:sessions:{id}:channels:{name}`. Writing a channel's `.out` requires secret-key auth (only the agent run), so a browser cannot forge frames; `.in` is writable with the session token. See [Realtime auth](/realtime/auth).
141
+ A side channel is covered by the session's public access token: a token scoped to `read:sessions:{id}` / `write:sessions:{id}` grants every channel of that session. Mint a narrower token scoped to a single channel with `read:sessions:{id}:channels:{name}`, or to one direction of it with `read:sessions:{id}:channels:{name}:out`. Writing a channel's `.out` requires secret-key auth (only the agent run), so a browser cannot forge frames; `.in` is writable with the session token. See [Realtime auth](/realtime/auth).
142
142
 
143
143
  ### Scope tokens to the channel, not the whole session
144
144
 
@@ -92,7 +92,7 @@ type TranscriptStorage<TClientData = unknown> = {
92
92
  ctx: TaskRunContext;
93
93
  },
94
94
  changeset: {
95
- reason: "turn-complete" | "turn-error" | "action" | "compaction" | "recovery";
95
+ reason: "turn-start" | "turn-complete" | "turn-error" | "action" | "compaction" | "recovery";
96
96
  changes: TranscriptChange[];
97
97
  transcript: { entries: Array<{ id: string; final: boolean; message: UIMessage }>; state: unknown | null };
98
98
  cursors?: { lastOutEventId?: string; lastInEventId?: string };
@@ -131,11 +131,16 @@ A changeset carries the same save two ways, and a storage uses whichever suits i
131
131
 
132
132
  `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.
133
133
 
134
- 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.
134
+ The changes are the intent, spelled out. A normal turn is two `put`s, the user's message and the assistant's answer, split across the turn's two saves. 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.
135
+
136
+ Every turn saves twice. The `turn-start` save carries the message being answered, before the model runs. The `turn-complete` save carries the answer. Both `put` the same user message id, and a `put` upserts, so a storage that applies changes in order needs no special handling for the repeat.
137
+
138
+ The `turn-start` save is what makes a reload during an answer show the question that is being answered. It leaves `cursors` on the previous turn's position, because the answer's own cursor does not exist yet, so a reload mid-answer still resumes from the last completed turn rather than skipping chunks it never received.
135
139
 
136
140
  A few properties worth knowing:
137
141
 
138
- - 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.
142
+ - The `turn-start` save runs alongside the model rather than before it, so it costs no time to first token. Nothing from the turn reaches the browser until it settles, which is what makes the question durable before the answer can render. A save that fails or runs long lets the answer through rather than stalling the conversation.
143
+ - The `turn-complete` save happens after the turn's answer has reached the browser, so it never delays the response. The runtime awaits each `save` before the run suspends.
139
144
  - 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.
140
145
  - A `load` that throws boots the run from the durable stream's recent tail rather than failing.
141
146
 
@@ -169,10 +174,16 @@ export function ChatPage({ chatId }: { chatId: string }) {
169
174
  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.
170
175
  </Warning>
171
176
 
172
- `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.
177
+ `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. A paged read returns the transcript only: `state` is always `null`, because the model lane is not part of what a page renders, and the platform reads just the bytes holding that page rather than the whole conversation. The runtime reads the state separately when it restores context at boot. 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.
173
178
 
174
179
  Swap `defaultStorage` for your own storage and nothing else about the read changes.
175
180
 
181
+ <Warning>
182
+ The saved format changed in this release, and an older SDK cannot read it. Rolling a deployment back to a version from before this release means its runs will not find a readable transcript for conversations already saved by the newer one, and will continue from the live stream tail instead, so earlier history is lost for those conversations. Roll forward rather than back, or keep your own transcript storage.
183
+ </Warning>
184
+
185
+ The default storage is deliberately basic about long conversations. Once compaction has run, it keeps roughly the last hundred messages and drops the rest, so what it rewrites on each save stops growing. A conversation that never compacts is kept whole. If your app renders history further back than that, give the agent your own storage and keep the messages yourself.
186
+
176
187
  ## Owning the model's context
177
188
 
178
189
  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.
@@ -207,6 +218,7 @@ A few things to get right:
207
218
 
208
219
  - 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.
209
220
  - `put` for a known id replaces the message in place; position and ordering don't change.
221
+ - Order is the message's position in the transcript. A document store gets it from `transcript.entries`. A row store needs an order column set once, when a `put` first inserts an id, following the order the `put`s arrive in, and left unchanged when a later `put` replaces that id in place. Don't sort by a write timestamp: a replaced message has to keep its place, and a steering message sent mid-turn sorts before the answer it shaped even though its row is written later.
210
222
  - `truncateAfter` and `remove` are idempotent. Applying a changeset twice gives the same result as applying it once.
211
223
  - `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.
212
224
  - Scope reads and writes by `clientData` where your backend enforces tenancy.
@@ -219,11 +231,13 @@ A few things to get right:
219
231
 
220
232
  ## Migrating from hydrateMessages
221
233
 
222
- `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:
234
+ `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. The move, in short:
223
235
 
224
- 1. Implement `TranscriptStorage` over your existing tables. Your `hydrateMessages` body becomes `loadContext`; the writes you did in hooks become `save`.
236
+ 1. Implement `TranscriptStorage` over your existing tables. The writes you did in hooks become `save`; the read your hook did becomes `load`. Add `loadContext` only if your database decides what the model sees each turn.
225
237
  2. Set `storage` on the agent and remove `hydrateMessages`. Setting both is an error.
226
- 3. Run `runTranscriptStorageTests` against your implementation.
238
+ 3. Delete the recovery, compaction and cursor code the runtime now owns, and run `runTranscriptStorageTests` against your implementation.
239
+
240
+ The [migration guide](/ai-chat/migrating-from-hydrate-messages) walks through each step with code, and lists what to delete from each hook.
227
241
 
228
242
  ## See also
229
243
 
@@ -15,6 +15,18 @@ We take the security of Trigger.dev seriously, for both Cloud and self-hosted de
15
15
  Do not report security vulnerabilities through public GitHub issues, pull requests, or Discord. Use one of the private channels below.
16
16
  </Warning>
17
17
 
18
+ ## What is in scope
19
+
20
+ A self-hosted deployment is a single trust domain: as above, it is built for code and users you trust. Role separation inside an organization is therefore not a security boundary there. Role-based access control comes from a plugin that is not part of the open-source distribution, and without it the permission layer falls back to a permissive ability for session users and personal access tokens. That is deliberate.
21
+
22
+ **Out of scope for self-hosted:** a member of an organization performing a privileged action inside that same organization, such as renaming or deleting the organization or managing other members. Control who you invite, or use Cloud, if you need that separation.
23
+
24
+ **In scope from any deployment:** reaching data or actions belonging to an organization the caller is not a member of, or bypassing authentication. Organization is a hard boundary on Trigger.dev Cloud, and Cloud runs this same code, so report these even though your own install is single-tenant.
25
+
26
+ Tell us which deployment you tested against. The same report can be out of scope for self-hosting and in scope for Cloud.
27
+
28
+ The [security policy](https://github.com/triggerdotdev/trigger.dev/blob/main/SECURITY.md) is canonical.
29
+
18
30
  ## Reporting a vulnerability
19
31
 
20
32
  <Steps>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trigger.dev/sdk",
3
- "version": "0.0.0-prerelease-20260909121655",
3
+ "version": "0.0.0-prerelease-20260911153544",
4
4
  "description": "trigger.dev Node.JS SDK",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
@@ -69,7 +69,7 @@
69
69
  "dependencies": {
70
70
  "@opentelemetry/api": "1.9.1",
71
71
  "@opentelemetry/semantic-conventions": "1.41.1",
72
- "@trigger.dev/core": "0.0.0-prerelease-20260909121655",
72
+ "@trigger.dev/core": "0.0.0-prerelease-20260911153544",
73
73
  "uncrypto": "^0.1.3"
74
74
  },
75
75
  "devDependencies": {