docs: add hydrateMessages, chat.history, and actions documentation

Author: ericallam

docs/ai-chat/backend.mdx

@@ -181,6 +181,56 @@ export const myChat = chat.agent({
   `onValidateMessages` fires **before** `onTurnStart` and message accumulation. If you need to validate messages loaded from a database, do the loading in `onChatStart` or `onPreload` and let `onValidateMessages` validate the full incoming set each turn.
 </Note>
 
+#### hydrateMessages
+
+Load the full message history from your backend on every turn, replacing the built-in linear accumulator. When set, the hook's return value becomes the accumulated state — the normal accumulation logic (append for submit, replace for regenerate) is skipped entirely.
+
+Use this when the backend should be the source of truth for message history — abuse prevention, branching conversations (DAGs), or rollback/undo support.
+
+| Field              | Type                                                  | Description                                               |
+| ------------------ | ----------------------------------------------------- | --------------------------------------------------------- |
+| `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 (empty for actions) |
+| `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           |
+| `previousRunId`    | `string \| undefined`                                 | The previous run ID (if continuation)                     |
+
+```ts
+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 ?? [];
+
+    // Append the new user message and persist
+    if (trigger === "submit-message" && incomingMessages.length > 0) {
+      const newMsg = incomingMessages[incomingMessages.length - 1]!;
+      stored.push(newMsg);
+      await db.chat.update({
+        where: { id: chatId },
+        data: { messages: stored },
+      });
+    }
+
+    return stored;
+  },
+  run: async ({ messages, signal }) => {
+    return streamText({ model: openai("gpt-4o"), messages, abortSignal: signal });
+  },
+});
+```
+
+**Lifecycle position:** `onValidateMessages` → **`hydrateMessages`** → `onChatStart` (turn 0) → `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.
+
+<Note>
+  `hydrateMessages` also fires for [action](#actions) turns (`trigger: "action"`) with empty `incomingMessages`. This lets the action handler work with the latest DB state.
+</Note>
+
 #### 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.
@@ -785,6 +835,96 @@ export const myChat = chat.agent({
   example, and how it differs from pending messages.
 </Tip>
 
+### Actions
+
+Custom actions let the frontend send structured commands (undo, rollback, edit) that modify the conversation state before the LLM responds. Actions use the same input stream as messages, so they wake the agent from suspension and trigger a full turn.
+
+Define an `actionSchema` for validation and an `onAction` handler that uses `chat.history` to modify state:
+
+```ts
+import { z } from "zod";
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  actionSchema: z.discriminatedUnion("type", [
+    z.object({ type: z.literal("undo") }),
+    z.object({ type: z.literal("rollback"), targetMessageId: z.string() }),
+    z.object({ type: z.literal("edit"), messageId: z.string(), text: z.string() }),
+  ]),
+
+  onAction: async ({ action }) => {
+    switch (action.type) {
+      case "undo":
+        chat.history.slice(0, -2); // Remove last user + assistant exchange
+        break;
+      case "rollback":
+        chat.history.rollbackTo(action.targetMessageId);
+        break;
+      case "edit":
+        chat.history.replace(action.messageId, {
+          id: action.messageId,
+          role: "user",
+          parts: [{ type: "text", text: action.text }],
+        });
+        break;
+    }
+  },
+
+  run: async ({ messages, signal }) => {
+    return streamText({ model: openai("gpt-4o"), messages, abortSignal: signal });
+  },
+});
+```
+
+**Lifecycle flow:** Wake → parse action against `actionSchema` → `hydrateMessages` (if set) → **`onAction`** → apply `chat.history` mutations → `onTurnStart` → `run()` → `onTurnComplete`
+
+On the frontend, send actions via the transport:
+
+```ts
+// Browser — TriggerChatTransport
+const stream = await transport.sendAction(chatId, { type: "undo" });
+
+// Server — AgentChat
+const stream = await agentChat.sendAction({ type: "rollback", targetMessageId: "msg-3" });
+```
+
+The action payload is validated against `actionSchema` on the backend — invalid actions throw and abort the turn. The `action` parameter in `onAction` is fully typed from the schema.
+
+<Note>
+  Actions always trigger `run()` — the LLM responds to the modified state. For silent state changes that don't need a response (e.g. injecting background context), use [`chat.inject()`](/ai-chat/background-injection) instead.
+</Note>
+
+### chat.history {#chat-history}
+
+Imperative API for modifying the accumulated message history. Works from any hook (`onAction`, `onTurnStart`, `onBeforeTurnComplete`, `onTurnComplete`) or from `run()` and AI SDK tools.
+
+| Method | Description |
+|--------|-------------|
+| `chat.history.all()` | Read the current accumulated UI messages (returns a copy) |
+| `chat.history.set(messages)` | Replace all messages (same as `chat.setMessages()`) |
+| `chat.history.remove(messageId)` | Remove a specific message by ID |
+| `chat.history.rollbackTo(messageId)` | Keep messages up to and including the given ID (undo) |
+| `chat.history.replace(messageId, message)` | Replace a specific message by ID (edit) |
+| `chat.history.slice(start, end?)` | Keep only messages in the given range |
+
+```ts
+// Undo the last exchange in onAction
+onAction: async ({ action }) => {
+  if (action.type === "undo") {
+    chat.history.slice(0, -2);
+  }
+},
+
+// Trim history in onTurnComplete
+onTurnComplete: async ({ uiMessages }) => {
+  if (uiMessages.length > 50) {
+    chat.history.slice(-20);
+  }
+},
+```
+
+Mutations use the same deferred mechanism as `chat.setMessages()` — they are applied at lifecycle checkpoints (after hooks return). Multiple mutations in the same hook compose correctly.
+
 ### prepareMessages
 
 Transform model messages before they're used anywhere — in `run()`, in compaction rebuilds, and in compaction results. Define once, applied everywhere.

docs/ai-chat/changelog.mdx

@@ -4,6 +4,69 @@ sidebarTitle: "Changelog"
 description: "Pre-release updates for AI chat agents."
 ---
 
+<Update label="April 15, 2026" description="0.0.0-chat-prerelease-20260415152704" tags={["SDK"]}>
+
+## `hydrateMessages` — backend-controlled message history
+
+Load message history from your database on every turn instead of trusting the frontend accumulator. The hook replaces the built-in linear accumulation entirely — the backend is the source of truth.
+
+```ts
+chat.agent({
+  id: "my-chat",
+  hydrateMessages: async ({ chatId, trigger, incomingMessages }) => {
+    const stored = await db.getMessages(chatId);
+    if (trigger === "submit-message" && incomingMessages.length > 0) {
+      stored.push(incomingMessages[incomingMessages.length - 1]!);
+      await db.persistMessages(chatId, stored);
+    }
+    return stored;
+  },
+});
+```
+
+Tool approval updates are auto-merged after hydration — no extra handling needed.
+
+See [hydrateMessages](/ai-chat/backend#hydratemessages).
+
+## `chat.history` — imperative message mutations
+
+Modify the accumulated message history from any hook or `run()`:
+
+```ts
+chat.history.rollbackTo(messageId);  // Undo — keep up to this message
+chat.history.remove(messageId);      // Remove one message
+chat.history.replace(id, newMsg);    // Edit a message
+chat.history.slice(0, -2);           // Remove last 2 messages
+chat.history.all();                  // Read current state
+```
+
+See [chat.history](/ai-chat/backend#chat-history).
+
+## Custom actions — `actionSchema` + `onAction`
+
+Send typed actions (undo, rollback, edit) from the frontend via `transport.sendAction()`. Actions wake the agent, fire `onAction`, then trigger a normal `run()` turn.
+
+```ts
+chat.agent({
+  id: "my-chat",
+  actionSchema: z.discriminatedUnion("type", [
+    z.object({ type: z.literal("undo") }),
+    z.object({ type: z.literal("rollback"), targetMessageId: z.string() }),
+  ]),
+  onAction: async ({ action }) => {
+    if (action.type === "undo") chat.history.slice(0, -2);
+    if (action.type === "rollback") chat.history.rollbackTo(action.targetMessageId);
+  },
+});
+```
+
+Frontend: `transport.sendAction(chatId, { type: "undo" })`
+Server: `agentChat.sendAction({ type: "undo" })`
+
+See [Actions](/ai-chat/backend#actions) and [Sending actions](/ai-chat/frontend#sending-actions).
+
+</Update>
+
 <Update label="April 14, 2026" description="0.0.0-chat-prerelease-20260414181032" tags={["SDK"]}>
 
 ## `chat.response` — persistent data parts

docs/ai-chat/client-protocol.mdx

@@ -290,6 +290,34 @@ The agent matches the incoming message by its `id` against the accumulated conve
   The message `id` must match the one the agent assigned during streaming. If you're using `TriggerChatTransport`, IDs are kept in sync automatically. Custom transports should use the `messageId` from the stream's `start` chunk.
 </Note>
 
+## Custom actions
+
+Send a custom action (undo, rollback, edit) to the agent using the same `chat-messages` input stream. Actions use `trigger: "action"` and carry a custom payload in the `action` field:
+
+```bash
+POST /realtime/v1/streams/{runId}/input/chat-messages
+Authorization: Bearer <publicAccessToken>
+Content-Type: application/json
+
+{
+  "data": {
+    "messages": [],
+    "chatId": "conversation-123",
+    "trigger": "action",
+    "action": { "type": "undo" },
+    "metadata": { "userId": "user-456" }
+  }
+}
+```
+
+Actions wake the agent from suspension (same as messages), fire the `onAction` hook, then trigger a normal `run()` turn. The `action` payload is validated against the agent's `actionSchema`.
+
+After sending, subscribe to the output stream to receive the agent's response — the same flow as [Step 2](#step-2-subscribe-to-the-output-stream).
+
+<Note>
+  `messages` is empty for actions. The agent's `onAction` handler modifies the conversation state via `chat.history.*`, and the LLM responds to the updated state. See [Actions](/ai-chat/backend#actions) for backend setup.
+</Note>
+
 ## Pending and steering messages
 
 You can send messages to the agent **while it's still streaming a response**. These are called pending messages — the agent receives them mid-turn and can inject them between tool-call steps.

docs/ai-chat/frontend.mdx

@@ -370,6 +370,42 @@ function Chat({ chatId, transport }) {
   for tool approval updates.
 </Info>
 
+## Sending actions
+
+Send custom actions (undo, rollback, edit) to the agent via `transport.sendAction()`. Actions wake the agent, fire the `onAction` hook, and trigger a normal response — the LLM responds to the modified state.
+
+```tsx
+function ChatControls({ chatId }: { chatId: string }) {
+  const transport = useTriggerChatTransport({ task: "my-chat", accessToken });
+
+  return (
+    <div>
+      <button onClick={() => transport.sendAction(chatId, { type: "undo" })}>
+        Undo last exchange
+      </button>
+      <button onClick={() => transport.sendAction(chatId, { type: "rollback", targetMessageId: "msg-5" })}>
+        Rollback to message
+      </button>
+    </div>
+  );
+}
+```
+
+The action payload is validated against the agent's `actionSchema` on the backend — invalid actions are rejected. See [Actions](/ai-chat/backend#actions) for the backend setup.
+
+<Note>
+  `sendAction` returns a `ReadableStream<UIMessageChunk>` — the agent's response to the modified state. If you're using `useChat`, the response is handled automatically through the transport.
+</Note>
+
+For server-to-server usage, `AgentChat` has the same method:
+
+```ts
+const stream = await agentChat.sendAction({ type: "undo" });
+for await (const chunk of stream) {
+  if (chunk.type === "text-delta") process.stdout.write(chunk.delta);
+}
+```
+
 ## Self-hosting
 
 If you're self-hosting Trigger.dev, pass the `baseURL` option:

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

@@ -113,6 +113,38 @@ chat.agent({
 });
 ```
 
+## Alternative: `hydrateMessages`
+
+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/backend#hydratemessages) instead of relying on the frontend's accumulated state.
+
+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
+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 ?? [];
+
+    if (trigger === "submit-message" && incomingMessages.length > 0) {
+      stored.push(incomingMessages[incomingMessages.length - 1]!);
+      await db.chat.update({ where: { id: chatId }, data: { messages: stored } });
+    }
+
+    return stored;
+  },
+  onTurnComplete: async ({ chatId, uiMessages }) => {
+    // Persist the response
+    await db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } });
+  },
+  run: async ({ messages, signal }) => {
+    return streamText({ model: openai("gpt-4o"), messages, abortSignal: signal });
+  },
+});
+```
+
+This replaces the `onTurnStart` persistence pattern — the hook handles both loading and persisting the new message in one place.
+
 ## Design notes
 
 - **`chatId`** is stable for the life of a thread; **`runId`** changes when the user starts a **new** run (timeout, cancel, explicit new chat). Session rows must always reflect the **current** run.