docs(ai-chat): document the head-start persistence and handover contract

Adds a persistence section to the fast starts page covering the stable
assistant messageId across the handover, onTurnComplete as the canonical
persistence point, reasoning parts surviving into durable history, and
how Head Start composes with hydrateMessages. Switches the hydrate hook
examples to upsert their conversation row, since head-start first turns
run without a preload to create it.

Author: ericallam

docs/ai-chat/fast-starts.mdx

@@ -524,8 +524,27 @@ The handler keeps the SSE response open until the agent run signals turn-complet
 | Tool execution runs in | Trigger.dev agent run | Trigger.dev agent run |
 | Step 2+ LLM call runs in | Trigger.dev agent run | Trigger.dev agent run |
 | `onChatStart` / `onTurnStart` fire | After handover signal arrives | Normally |
+| `hydrateMessages` fires (if registered) | After handover, with the first-turn history as `incomingMessages` | Normally |
 | `onTurnComplete` fires | After turn finishes (handover) or skipped (handover-skip) | Normally |
 
+### Persistence and the handover contract
+
+A head-start turn persists exactly like a normal turn — the handover machinery is invisible to your hooks. The guarantees:
+
+- **One stable assistant `messageId` across the whole turn.** The route handler generates the id, the handover signal carries it to the agent, and the agent's step 2+ stream reuses it — so the browser merges step 1 and step 2+ into a single assistant message, and you can merge-by-id when persisting.
+- **`onTurnComplete` is the canonical persistence point**, same as any turn. It carries the full assistant message under that one id: step-1 text, reasoning, and tool calls plus step-2+ tool results and text. The [database persistence](/ai-chat/patterns/database-persistence) patterns apply unchanged.
+- **Reasoning parts survive the handover.** When step 1 runs on an extended-thinking model, the reasoning streamed by your route handler lands in the durable session history (and `onTurnComplete`) under the same `messageId`, with provider metadata intact — Anthropic thinking signatures survive a replay back to the model. Step-2 reasoning appends to the same message rather than replacing it.
+
+#### With `hydrateMessages`
+
+Head Start composes with [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages). On the first turn, the hook receives the route handler's first-turn history as `incomingMessages` — the canonical upsert-and-return pattern persists the user message exactly as it would on a direct-trigger turn. The runtime splices the warm handler's partial assistant onto your hydrated chain after the hook returns, deduplicated by the assistant `messageId`, so your hook never needs to include the in-flight partial.
+
+<Warning>
+  **Hydrate hooks must upsert their conversation row, not update it.** Head-start turns skip preload entirely, so row-creating hooks (`onPreload`, or an `onChatStart` create) have not run when `hydrateMessages` first fires. A bare `UPDATE` against a missing row throws and errors the turn.
+</Warning>
+
+Your hydrate hook shapes **model context**, not the transcript — dropping reasoning-only entries or unresolved tool rows from the returned chain is fine and does not affect what `onTurnComplete` persists or what the UI renders.
+
 ### The `chat.headStart` API
 
 ```ts

docs/ai-chat/lifecycle-hooks.mdx

@@ -273,7 +273,7 @@ Use this when the backend should be the source of truth for message history: abu
 | `chatId`           | `string`                                              | Chat session ID                                           |
 | `turn`             | `number`                                              | Turn number (0-indexed)                                   |
 | `trigger`          | `"submit-message" \| "regenerate-message" \| "action"` | The trigger type for this turn                           |
-| `incomingMessages` | `UIMessage[]`                                         | Validated wire messages from the frontend — 0-or-1-length (empty for actions, regenerates, and continuations; one element for normal `submit-message` and tool-approval responses) |
+| `incomingMessages` | `UIMessage[]`                                         | Validated wire messages from the frontend — 0-or-1-length (empty for actions, regenerates, and continuations; one element for normal `submit-message` and tool-approval responses). On a [Head Start](/ai-chat/fast-starts#with-hydratemessages) first turn, carries the route handler's first-turn history |
 | `previousMessages` | `UIMessage[]`                                         | Accumulated UI messages before this turn (`[]` on turn 0) |
 | `clientData`       | Typed by `clientDataSchema`                           | Custom data from the frontend                             |
 | `continuation`     | `boolean`                                             | Whether this run is continuing an existing chat           |
@@ -289,9 +289,12 @@ export const myChat = chat.agent({
     const stored = record?.messages ?? [];
 
     if (upsertIncomingMessage(stored, { trigger, incomingMessages })) {
-      await db.chat.update({
+      // Upsert, not update: on a head-start first turn no preload ran,
+      // so the row may not exist yet when this hook fires.
+      await db.chat.upsert({
         where: { id: chatId },
-        data: { messages: stored },
+        create: { id: chatId, messages: stored },
+        update: { messages: stored },
       });
     }
 

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

@@ -191,7 +191,13 @@ export const myChat = chat.agent({
     // 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 } });
+      // Upsert, not update: on a head-start first turn no preload ran,
+      // so the row may not exist yet when this hook fires.
+      await db.chat.upsert({
+        where: { id: chatId },
+        create: { id: chatId, messages: stored },
+        update: { messages: stored },
+      });
     }
 
     return stored;
@@ -217,6 +223,8 @@ export const myChat = chat.agent({
 
 This replaces the `onTurnStart` persistence pattern — the hook handles both loading and persisting the new message in one place.
 
+Hydration composes with [Head Start](/ai-chat/fast-starts#with-hydratemessages): on a head-start first turn the route handler's history arrives as `incomingMessages`, and the write path must be an upsert because no preload ran to create the row.
+
 ## Design notes
 
 - **`chatId`** is stable for the life of a thread and is the only identifier the transport persists. Runs come and go (idle continuation, upgrade, cancel/restart) but the chat keeps its identity.