docs(ai-chat): use upsertIncomingMessage helper in hydrateMessages examples

Author: ericallam

docs/ai-chat/changelog.mdx

@@ -16,7 +16,26 @@ The per-turn merge now overlays only the tool-part state advances (`output-avail
 
 ### `hydrateMessages` upsert-by-id
 
-If your `hydrateMessages` hook persists the incoming message, **upsert by id** — don't unconditionally push. HITL continuations ship the existing assistant's id with a slim payload; a blind `stored.push(newMsg)` duplicates the row in the chain you return, the merge updates the first match, and the slim duplicate hits `toModelMessages` with no `input`. The examples in [lifecycle hooks](/ai-chat/lifecycle-hooks#hydratemessages), [Database persistence](/ai-chat/patterns/database-persistence#alternative-hydratemessages), and [Persistence and replay](/ai-chat/patterns/persistence-and-replay) have all been updated.
+If your `hydrateMessages` hook persists the incoming message, **upsert by id** — don't unconditionally push. HITL continuations ship the existing assistant's id with a slim payload; a blind `stored.push(newMsg)` duplicates the row in the chain you return, the merge updates the first match, and the slim duplicate hits `toModelMessages` with no `input`.
+
+A new `upsertIncomingMessage` helper is exported from `@trigger.dev/sdk/ai` to handle this for the common case:
+
+```ts
+import { chat, upsertIncomingMessage } from "@trigger.dev/sdk/ai";
+
+chat.agent({
+  hydrateMessages: async ({ chatId, trigger, incomingMessages }) => {
+    const record = await db.chat.findUnique({ where: { id: chatId } });
+    const stored = record?.messages ?? [];
+    if (upsertIncomingMessage(stored, { trigger, incomingMessages })) {
+      await db.chat.update({ where: { id: chatId }, data: { messages: stored } });
+    }
+    return stored;
+  },
+});
+```
+
+The helper pushes fresh user messages, no-ops on HITL continuations (so the runtime can overlay the new tool-state advance), and skips on non-`submit-message` triggers. Returns `true` if it mutated `stored`. The examples in [lifecycle hooks](/ai-chat/lifecycle-hooks#hydratemessages), [Database persistence](/ai-chat/patterns/database-persistence#alternative-hydratemessages), and [Persistence and replay](/ai-chat/patterns/persistence-and-replay) have all been updated. Custom hydrate logic (branching, rollback, etc.) can still write the upsert by hand — the helper is a convenience for the common shape.
 
 ### `onValidateMessages` slim wire caveat
 

docs/ai-chat/lifecycle-hooks.mdx

@@ -280,30 +280,19 @@ Use this when the backend should be the source of truth for message history: abu
 | `previousRunId`    | `string \| undefined`                                 | The previous run ID (if continuation)                     |
 
 ```ts
+import { chat, upsertIncomingMessage } from "@trigger.dev/sdk/ai";
+
 export const myChat = chat.agent({
   id: "my-chat",
   hydrateMessages: async ({ chatId, trigger, incomingMessages }) => {
     const record = await db.chat.findUnique({ where: { id: chatId } });
     const stored = record?.messages ?? [];
 
-    // Upsert the incoming message by id. On HITL continuations
-    // (`addToolOutput` / `addToolApproveResponse`) the incoming wire
-    // shares the id of an existing assistant in `stored` — `push`ing
-    // unconditionally would duplicate the row. The runtime merges the
-    // resolution onto the existing entry; new ids (typically a fresh
-    // user message) get appended.
-    if (trigger === "submit-message" && incomingMessages.length > 0) {
-      const newMsg = incomingMessages[incomingMessages.length - 1]!;
-      const existingIdx = newMsg.id
-        ? stored.findIndex((m) => m.id === newMsg.id)
-        : -1;
-      if (existingIdx === -1) {
-        stored.push(newMsg);
-        await db.chat.update({
-          where: { id: chatId },
-          data: { messages: stored },
-        });
-      }
+    if (upsertIncomingMessage(stored, { trigger, incomingMessages })) {
+      await db.chat.update({
+        where: { id: chatId },
+        data: { messages: stored },
+      });
     }
 
     return stored;
@@ -314,6 +303,10 @@ export const myChat = chat.agent({
 });
 ```
 
+`upsertIncomingMessage` (exported from `@trigger.dev/sdk/ai`) handles the three cases that matter — fresh user messages get pushed, HITL continuations (`addToolOutput` / `addToolApproveResponse`) no-op because the incoming wire shares the existing assistant's id and the runtime overlays the new tool-state advance onto that entry, and non-`submit-message` triggers (`regenerate-message` / `action`) skip persistence. It returns `true` when it mutated `stored`, so the caller knows whether to persist.
+
+If you need branching, rollback, or other custom hydrate logic, you can still write the upsert by hand — `upsertIncomingMessage` is a convenience for the common case, not the only supported shape.
+
 **Lifecycle position:** `onValidateMessages` → **`hydrateMessages`** → `onChatStart` (chat's first message only) → `onTurnStart` → `run()`
 
 After the hook returns, the runtime overlays the wire's tool-state advances (`output-available` / `output-error` / `approval-responded` / `output-denied`) onto matching hydrated entries by id. Everything else on the hydrated entry — text, reasoning, tool `input`, providerMetadata — stays put. This makes [tool approvals](/ai-chat/frontend#tool-approvals) and HITL `addToolOutput` continuations work transparently: ship a slim resolution on the wire, the agent merges the new state onto your DB-backed copy.

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

@@ -178,26 +178,20 @@ For apps that need the backend to be the single source of truth for message hist
 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`):
 
 ```ts
+import { chat, upsertIncomingMessage } from "@trigger.dev/sdk/ai";
+
 export const myChat = chat.agent({
   id: "my-chat",
   hydrateMessages: async ({ chatId, trigger, incomingMessages }) => {
     const record = await db.chat.findUnique({ where: { id: chatId } });
     const stored = record?.messages ?? [];
 
-    // Upsert by id. HITL continuations (addToolOutput /
-    // addToolApproveResponse) ship the existing assistant's id with a
-    // slim payload — push-without-check duplicates the row, the
-    // runtime merges only the first match, and the duplicate slim copy
-    // hits `toModelMessages` with no `input`.
-    if (trigger === "submit-message" && incomingMessages.length > 0) {
-      const newMsg = incomingMessages[incomingMessages.length - 1]!;
-      const existingIdx = newMsg.id
-        ? stored.findIndex((m) => m.id === newMsg.id)
-        : -1;
-      if (existingIdx === -1) {
-        stored.push(newMsg);
-        await db.chat.update({ where: { id: chatId }, data: { messages: stored } });
-      }
+    // `upsertIncomingMessage` pushes a fresh user message and no-ops
+    // on HITL continuations (the runtime overlays the new tool-state
+    // advance onto the existing entry). See lifecycle hooks for the
+    // full pattern: /ai-chat/lifecycle-hooks#hydratemessages
+    if (upsertIncomingMessage(stored, { trigger, incomingMessages })) {
+      await db.chat.update({ where: { id: chatId }, data: { messages: stored } });
     }
 
     return stored;

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

@@ -131,26 +131,18 @@ If `onAction` mutates `chat.history.*` and then the run crashes before the next
 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.
 
 ```ts
-import { chat } from "@trigger.dev/sdk/ai";
+import { chat, upsertIncomingMessage } from "@trigger.dev/sdk/ai";
 import { db } from "@/lib/db";
 
 export const myChat = chat.agent({
   id: "my-chat",
   hydrateMessages: async ({ chatId, trigger, incomingMessages }) => {
     const stored = (await db.chat.findUnique({ where: { id: chatId } }))?.messages ?? [];
 
-    // Upsert by id — HITL continuations ship the existing assistant's
-    // id with a slim payload; the runtime overlays the new state.
-    // See lifecycle-hooks for the full pattern + rationale.
-    if (trigger === "submit-message" && incomingMessages.length > 0) {
-      const newMsg = incomingMessages[0]!;
-      const existingIdx = newMsg.id
-        ? stored.findIndex((m) => m.id === newMsg.id)
-        : -1;
-      if (existingIdx === -1) {
-        stored.push(newMsg);
-        await db.chat.update({ where: { id: chatId }, data: { messages: stored } });
-      }
+    // See lifecycle-hooks for the full upsert pattern + rationale:
+    // /ai-chat/lifecycle-hooks#hydratemessages
+    if (upsertIncomingMessage(stored, { trigger, incomingMessages })) {
+      await db.chat.update({ where: { id: chatId }, data: { messages: stored } });
     }
 
     return stored;