docs(ai-chat): onChatStart once-per-chat contract + continuation run handling

onChatStart now fires only on the chat's very first user message — not
on every run boot. Continuation runs (post-endRun, post-waitpoint-timeout,
chat.requestUpgrade) and OOM-retry attempts skip the hook, so chat-start
setup work is guaranteed to run exactly once per chat. Per-turn work that
should fire on continuations belongs in onTurnStart.

Also documents the server-side continuation-overrides behavior (sticky
`message` / `messages` / `trigger` are stripped from basePayload on
continuation runs) and the mock harness's new `continuation` /
`mode: "continuation"` options for offline testing.

- lifecycle-hooks: rewrite onChatStart section, mark continuation /
  previousRunId deprecated on ChatStartEvent, clarify onTurnStart still
  fires on continuation turns
- client-protocol: basePayload no longer replays first-turn-only fields
  on continuations; client doesn't need to send continuation /
  previousRunId — server detects automatically
- upgrade-guide: drop the messages.length === 0 → continuation: false
  migration; new guidance is to drop the continuation gate entirely
- testing: full mockChatAgent options table + Boot modes table + new
  'Testing continuation runs' pattern with example
- changelog: replace onChatStart.messages bullet with the once-per-chat
  contract + continuation-wait branch entry on the pending prerelease
- database-persistence pattern: drop the continuation branch from the
  onChatStart walkthrough
- backend, reference: one-line updates to match

Author: ericallam

docs/ai-chat/backend.mdx

@@ -93,7 +93,7 @@ async function runAgentLoop(messages: ModelMessage[]) {
 
 - [Lifecycle hooks](/ai-chat/lifecycle-hooks) — `onPreload`, `onChatStart`, `onValidateMessages`, `hydrateMessages`, `onTurnStart`, `onBeforeTurnComplete`, `onTurnComplete`, `onChatSuspend` / `onChatResume`, `exitAfterPreloadIdle`, plus how `ctx` plumbs through every callback.
 
-**Per-turn order:** `onValidateMessages` → `hydrateMessages` → `onChatStart` (turn 0 only) → `onTurnStart` → `run()` → `onBeforeTurnComplete` → `onTurnComplete`.
+**Per-turn order:** `onValidateMessages` → `hydrateMessages` → `onChatStart` (chat's first message only) → `onTurnStart` → `run()` → `onBeforeTurnComplete` → `onTurnComplete`.
 
 ### Using prompts
 

docs/ai-chat/changelog.mdx

@@ -26,7 +26,8 @@ The wire is now **delta-only**: each `.in/append` carries at most one new `UIMes
 - **Run boot**: when `hydrateMessages` is not registered, the runtime reads `packets/{projectRef}/{envSlug}/sessions/{sessionId}/snapshot.json` from object storage and replays any `session.out` chunks landed since the snapshot's cursor. Snapshot writes happen after every `onTurnComplete`, awaited so they survive an idle suspend.
 - **`hydrateMessages` short-circuit**: registering the hook skips snapshot read/write and replay entirely. Customer is the source of truth for history, same as today.
 - **`hydrateMessages.incomingMessages`**: now consistently 0-or-1-length across every trigger type. Previously `regenerate-message` and continuations occasionally shipped full history; they now ship none.
-- **`onChatStart.messages`**: on a continuation, reflects the **full prior conversation** loaded from snapshot+replay (was empty-or-tiny on a fresh run before).
+- **`onChatStart` is now once-per-chat**: fires only on the chat's very first user message; does NOT fire on continuation runs (post-`endRun`, post-waitpoint-timeout, post-`chat.requestUpgrade`) or on OOM-retry attempts. The `continuation` and `previousRunId` fields on `ChatStartEvent` are now `@deprecated` (always `false` / `undefined` when the hook fires). Drop any `if (continuation) return;` gates from `onChatStart` — they're now unreachable. For per-turn setup that runs on continuations too, move to `onTurnStart`.
+- **Continuation boot payload**: the server now strips `message` / `messages` / `trigger` from the cached `basePayload` on continuation runs, and the SDK enters a new continuation-wait branch that waits silently on `session.in` for the next user message. Fixes a phantom-turn bug where stale boot-payload fields were replayed on every resume.
 - **OOM-retry boot**: uses the snapshot's `lastOutTimestamp` as the `session.in` cutoff, saving one stream subscription per retry.
 - **Built-in transports**: `TriggerChatTransport`, `AgentChat`, mid-stream pending-message handling, and `chat.headStart` route handler all updated to the slim shape. Existing customer code calling `transport.sendMessage(...)` / `agentChat.sendMessage(...)` is unaffected — the change is below those surfaces.
 

docs/ai-chat/client-protocol.mdx

@@ -189,7 +189,7 @@ Pick `"preload"` when the UI has rendered but the user hasn't typed (warms the a
 | --- | --- | --- |
 | `type` | `string` | Discriminator. Use `"chat.agent"`. |
 | `taskIdentifier` | `string` | The `id` you passed to `chat.agent({ id: ... })` — e.g. `"ai-chat"`. |
-| `triggerConfig.basePayload` | `object` | The wire payload sent to **every run** triggered by this session — both the first run (created by this call) and any continuation runs. Same shape as [`ChatTaskWirePayload`](#chattaskwirepayload) in Step 3 (the type used by `.in/append`). See [What goes in `basePayload`](#what-goes-in-basepayload) below. |
+| `triggerConfig.basePayload` | `object` | The wire payload sent to the **first run** created by this call. Same shape as [`ChatTaskWirePayload`](#chattaskwirepayload) in Step 3. Durable fields (`chatId`, `metadata`, `idleTimeoutInSeconds`, `sessionId`) flow through to continuation runs too; first-turn-only fields (`message`, `trigger`) are stripped on continuations — those are session-create concerns and don't replay. See [What goes in `basePayload`](#what-goes-in-basepayload) below. |
 
 ### Optional fields
 
@@ -515,7 +515,7 @@ Signals that the agent cannot handle this message on its current version and a n
 
 When you receive this chunk:
 1. Close the stream reader.
-2. Re-send the user's message on `.in/append` with `continuation: true` and `previousRunId` in the payload (see [Continuations](#continuations)). The append handler triggers a fresh run on the same session — `sessionId` and `publicAccessToken` are reused, only `runId` changes.
+2. Re-send the user's message on `.in/append` as a normal `submit-message` (no extra fields needed — see [Continuations](#continuations)). The append handler triggers a fresh run on the same session — `sessionId` and `publicAccessToken` are reused, only `runId` changes.
 3. Resubscribe to `/realtime/v1/sessions/{sessionId}/out`.
 
 The user's message is not lost — the agent processes it on the new version. The built-in clients handle this transparently.
@@ -642,7 +642,18 @@ type ChatTaskWirePayload<TMessage extends UIMessage = UIMessage, TMetadata = unk
    */
   metadata?: TMetadata;
   action?: unknown;
+  /**
+   * Informational — the server sets this automatically on continuation
+   * runs (when the prior run is dead). Clients don't need to send it.
+   * Read by the agent's boot gate to skip `onChatStart` and trigger
+   * snapshot read + replay.
+   */
   continuation?: boolean;
+  /**
+   * Informational — paired with `continuation: true`, set by the server
+   * from the prior run's friendly ID. Surfaced to the agent in
+   * `ctx.previousRunId`. Clients don't need to send it.
+   */
   previousRunId?: string;
   idleTimeoutInSeconds?: number;
   sessionId?: string;
@@ -843,7 +854,7 @@ See [Pending Messages](/ai-chat/pending-messages) for how to configure the agent
 
 A run can end for several reasons: idle timeout, max turns reached, `chat.requestUpgrade()`, crash, or cancellation. When this happens, the session row stays alive — only the run is gone. The next message you append to `.in` automatically triggers a fresh run on the same session.
 
-The wire shape is identical to a normal `submit-message`, plus a `continuation: true` flag so the agent's `onChatStart` hook can distinguish from a brand-new conversation:
+**Clients send the wire shape exactly as a normal `submit-message`** — the server detects the absent run and handles the continuation itself:
 
 ```json
 {
@@ -856,15 +867,21 @@ The wire shape is identical to a normal `submit-message`, plus a `continuation:
     },
     "chatId": "conversation-123",
     "trigger": "submit-message",
-    "metadata": { "userId": "user-456" },
-    "continuation": true,
-    "previousRunId": "run_abc123"
+    "metadata": { "userId": "user-456" }
   }
 }
 ```
 
 POST to the same `/realtime/v1/sessions/{sessionId}/in/append` URL with the same `publicAccessToken` you've been using — both stay valid across runs. The server detects the absent run, triggers a new one on the session's `triggerConfig`, and the agent boots, reads the snapshot from the prior run's last turn, replays any tail, and continues. Only `runId` (which you can read from later `trigger:turn-complete` chunks if you need it) changes.
 
+<Note>
+  **You don't need to track `runId` or set `continuation: true` / `previousRunId` yourself.** The server detects continuation when the prior run is in a terminal state and sets those fields on the new run's boot payload automatically. The `continuation` and `previousRunId` fields on `ChatTaskWirePayload` are informational — used internally by the agent's boot path, never required from the client.
+</Note>
+
+<Note>
+  **`onChatStart` does NOT fire on continuation runs.** The hook is once-per-chat — it fires only on the chat's very first user message. Customers who want per-turn setup that also runs on continuation turns should use `onTurnStart` instead.
+</Note>
+
 <Tip>
   This is how [version upgrades](/ai-chat/patterns/version-upgrades) work transparently — the agent calls `chat.requestUpgrade()`, the run exits, and the client's next message triggers a continuation on the new version. Same session, new run, same snapshot.
 </Tip>

docs/ai-chat/lifecycle-hooks.mdx

@@ -6,7 +6,7 @@ description: "Hook into every stage of a chat agent's run: preload, turn start,
 
 `chat.agent({ ... })` accepts a set of lifecycle hooks for persisting state, validating input, transforming messages, and reacting to suspension and resumption. They fire in a fixed order around each turn.
 
-**Per-turn order:** `onValidateMessages` → `hydrateMessages` → `onChatStart` (turn 0 only) → `onTurnStart` → `run()` → `onBeforeTurnComplete` → `onTurnComplete`.
+**Per-turn order:** `onValidateMessages` → `hydrateMessages` → `onChatStart` (chat's first message only) → `onTurnStart` → `run()` → `onBeforeTurnComplete` → `onTurnComplete`.
 
 **Suspend / resume:** `onChatSuspend` fires when the run transitions from idle to suspended (waiting on the next message); `onChatResume` fires on wake.
 
@@ -63,20 +63,26 @@ Every lifecycle callback receives a `writer`, a lazy stream writer that lets you
 
 ## onChatStart
 
-Fires once on the first turn (turn 0) before `run()` executes. Use it to create a chat record in your database.
+Fires **exactly once per chat**, on the very first user message of the chat's lifetime, before `run()` executes. Use it for one-time chat setup — create the Chat DB row, initialize per-chat in-memory state, mint resources tied to the chat's lifetime.
 
-The `continuation` field tells you whether this is a brand new chat or a continuation of an existing one (where the previous run timed out or was cancelled). The `preloaded` field tells you whether `onPreload` already ran.
+`onChatStart` does **not** fire on:
+
+- **Continuation runs** — a new run picking up an existing session after the prior run ended (`chat.endRun`, waitpoint timeout, `chat.requestUpgrade`). The chat already started.
+- **OOM-retry attempts** — same chat, same conversation, just on a larger machine.
+
+If you need per-turn setup that runs on every turn including continuations, use [`onTurnStart`](#onturnstart) instead.
+
+The `preloaded` field tells you whether [`onPreload`](#onpreload) already ran for this chat — useful for skipping setup work that's already done.
 
 <Note>
-  On a continuation (`continuation: true`), the `messages` field reflects the **full prior conversation** — the runtime rebuilds it from a durable snapshot plus a `session.out` replay before `onChatStart` runs. On a brand-new chat or a preloaded run that hasn't received its first turn yet, `messages` is empty. See [Persistence and replay](/ai-chat/patterns/persistence-and-replay) for the underlying mechanism.
+  Because `onChatStart` fires only on the chat's first ever message, `messages` is either empty (when no message exists yet — e.g. a preloaded run that hasn't received its first turn) or contains just the first user message. There's no prior history to load here.
 </Note>
 
 ```ts
 export const myChat = chat.agent({
   id: "my-chat",
-  onChatStart: async ({ chatId, clientData, continuation, preloaded }) => {
+  onChatStart: async ({ chatId, clientData, preloaded }) => {
     if (preloaded) return; // Already set up in onPreload
-    if (continuation) return; // Chat record already exists
 
     const { userId } = clientData as { userId: string };
     await db.chat.create({
@@ -170,7 +176,7 @@ export const myChat = chat.agent({
 });
 ```
 
-**Lifecycle position:** `onValidateMessages` → **`hydrateMessages`** → `onChatStart` (turn 0) → `onTurnStart` → `run()`
+**Lifecycle position:** `onValidateMessages` → **`hydrateMessages`** → `onChatStart` (chat's first message only) → `onTurnStart` → `run()`
 
 After the hook returns, any incoming wire message whose ID matches a hydrated message is auto-merged. This makes [tool approvals](/ai-chat/frontend#tool-approvals) work transparently with hydration.
 
@@ -188,7 +194,7 @@ After the hook returns, any incoming wire message whose ID matches a hydrated me
 
 ## onTurnStart
 
-Fires at the start of every turn, after message accumulation and `onChatStart` (turn 0), but **before** `run()` executes. Use it to persist messages before streaming begins so a mid-stream page refresh still shows the user's message.
+Fires at the start of **every turn** — including the first turn of a continuation run, where `onChatStart` doesn't fire. Runs after message accumulation and (when applicable) `onChatStart`, but **before** `run()` executes. Use it to persist messages before streaming begins so a mid-stream page refresh still shows the user's message.
 
 | Field             | Type                                          | Description                                     |
 | ----------------- | --------------------------------------------- | ----------------------------------------------- |

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

@@ -40,11 +40,13 @@ When the user triggers [preload](/ai-chat/fast-starts#preload), the run starts *
 
 If you skip preload, do the equivalent in **`onChatStart`** when **`preloaded`** is false.
 
-### `onChatStart` (turn 0, non-preloaded path)
+### `onChatStart` (chat's first message, non-preloaded path)
 
+- Fires **once per chat**, on the very first user message. Does NOT fire on continuation runs (post-`endRun`, post-waitpoint-timeout, post-`chat.requestUpgrade`) or on OOM-retry attempts.
 - If **`preloaded`** is true, return early — **`onPreload`** already ran.
 - Otherwise mirror preload: user/context, conversation create, session upsert.
-- If **`continuation`** is true, the conversation row usually **already exists** (previous run ended or timed out); only update **session** fields so the **new** PAT and `lastEventId` are stored.
+- No need to gate the conversation create on `continuation` — it's always a brand-new chat at this point.
+- For continuation runs that need to refresh per-run state (new PAT, new `lastEventId`), do it in **`onTurnStart`** / **`onTurnComplete`** — both fire on every turn including the first turn of a continuation run.
 
 ### `onTurnStart`
 
@@ -135,12 +137,11 @@ chat.agent({
     await upsertSession({ chatId, publicAccessToken: chatAccessToken });
   },
 
-  onChatStart: async ({ chatId, chatAccessToken, clientData, continuation, preloaded }) => {
+  onChatStart: async ({ chatId, chatAccessToken, clientData, preloaded }) => {
     if (preloaded) return;
+    // Fires once per chat — no continuation gate needed.
     await ensureUser(clientData.userId);
-    if (!continuation) {
-      await upsertConversation({ id: chatId, userId: clientData.userId /* ... */ });
-    }
+    await upsertConversation({ id: chatId, userId: clientData.userId /* ... */ });
     await upsertSession({ chatId, publicAccessToken: chatAccessToken });
   },
 

docs/ai-chat/reference.mdx

@@ -14,7 +14,7 @@ Options for `chat.agent()`.
 | `run`                         | `(payload: ChatTaskRunPayload) => Promise<unknown>`         | required                       | Handler for each turn                                                                               |
 | `clientDataSchema`            | `TaskSchema`                                                | —                              | Schema for validating and typing `clientData`                                                       |
 | `onPreload`                   | `(event: PreloadEvent) => Promise<void> \| void`            | —                              | Fires on preloaded runs before the first message                                                    |
-| `onChatStart`                 | `(event: ChatStartEvent) => Promise<void> \| void`          | —                              | Fires on turn 0 before `run()`                                                                      |
+| `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) |
 | `actionSchema`                | `TaskSchema`                                                | —                              | Schema for validating custom actions sent via `transport.sendAction()`. See [Actions](/ai-chat/actions) |