docs(ai-chat): document actions-not-turns semantics

Update the customer-facing docs for TRI-9118:

- changelog.mdx: new Update entry with the breaking-change writeup
  and a before/after migration snippet
- backend.mdx (already shipped): action lifecycle no longer mentions
  run() / turn hooks; documents void vs StreamTextResult returns
- frontend.mdx: rewrite sendAction section with optimistic setMessages
  example for void actions
- testing.mdx: update harness.sendAction reference to reflect the
  new lifecycle
- reference.mdx: widen onAction return type in the hooks table
- upgrade-guide.mdx: drop the misleading 'onAction unchanged' claim
  from the Sessions migration's 'what didn't change' list

Author: ericallam

docs/ai-chat/changelog.mdx

@@ -4,6 +4,48 @@ sidebarTitle: "Changelog"
 description: "Pre-release updates for AI chat agents."
 ---
 
+<Update label="May 6, 2026" tags={["SDK", "Breaking"]}>
+
+## `chat.agent` actions are no longer turns
+
+Submitting an action via `transport.sendAction()` previously fell through to the regular turn machinery, calling `onTurnStart`, `run()`, `onTurnComplete`, etc. — meaning every action fired an LLM call by default. The workaround was a `chat.store`-based `skipModelCall` flag in `run()`.
+
+Actions now fire `hydrateMessages` and `onAction` only. No `onTurnStart` / `prepareMessages` / `onBeforeTurnComplete` / `onTurnComplete`, no `run()` invocation, no turn-counter increment. The trace span is named `chat action` instead of `chat turn N`.
+
+`onAction`'s return type widens: returning `void` is side-effect-only (default); returning a `StreamTextResult`, `string`, or `UIMessage` produces a model response that's auto-piped back to the frontend.
+
+### Migration
+
+If you had `run()` branching on `payload.trigger === "action"` for a model response, return your `streamText(...)` from `onAction` instead. If you persisted in `onTurnComplete`, do that work inside `onAction`. For state-only actions, just remove the skip-the-model workaround.
+
+```ts
+// before
+onAction: async ({ action }) => {
+  if (action.type === "regenerate") {
+    chat.store.set({ skipModelCall: false });
+    chat.history.slice(0, -1);
+  }
+},
+run: async ({ messages, signal }) => {
+  if (chat.store.get()?.skipModelCall) return;
+  return streamText({ model, messages, abortSignal: signal });
+},
+
+// after
+onAction: async ({ action, messages, signal }) => {
+  if (action.type === "regenerate") {
+    chat.history.slice(0, -1);
+    return streamText({ model, messages, abortSignal: signal });
+  }
+},
+run: async ({ messages, signal }) =>
+  streamText({ model, messages, abortSignal: signal }),
+```
+
+Actions arriving when no `onAction` handler is configured now `console.warn` once and are ignored — previously they silently fell through to `run()` with an empty wire payload.
+
+</Update>
+
 <Update label="May 5, 2026" description="0.0.0-chat-prerelease-20260505140031" tags={["SDK"]}>
 
 ## Fix: duplicate turn after `chat.agent` idle-suspends

docs/ai-chat/frontend.mdx

@@ -428,7 +428,9 @@ function Chat({ chatId, transport }) {
 
 ## 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.
+Send custom actions (undo, rollback, edit) to the agent via `transport.sendAction()`. Actions wake the agent and fire only `hydrateMessages` (if configured) and `onAction` — they're not turns, so `onTurnStart` / `prepareMessages` / `onBeforeTurnComplete` / `onTurnComplete` and `run()` do not fire.
+
+For optimistic UI, mirror the action's effect on the `useChat` state via `setMessages` while the request is in flight:
 
 ```tsx
 function ChatControls({ chatId }: { chatId: string }) {
@@ -439,12 +441,21 @@ function ChatControls({ chatId }: { chatId: string }) {
       startChatSession({ chatId, taskId, clientData }),
   });
 
+  const { setMessages } = useChat({ transport });
+
   return (
     <div>
-      <button onClick={() => transport.sendAction(chatId, { type: "undo" })}>
+      <button
+        onClick={() => {
+          void transport.sendAction(chatId, { type: "undo" });
+          setMessages((prev) => prev.slice(0, -2));
+        }}
+      >
         Undo last exchange
       </button>
-      <button onClick={() => transport.sendAction(chatId, { type: "rollback", targetMessageId: "msg-5" })}>
+      <button
+        onClick={() => transport.sendAction(chatId, { type: "rollback", targetMessageId: "msg-5" })}
+      >
         Rollback to message
       </button>
     </div>
@@ -455,7 +466,7 @@ function ChatControls({ chatId }: { chatId: string }) {
 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.
+  `sendAction` returns a `ReadableStream<UIMessageChunk>`. For side-effect-only actions (where `onAction` returns `void`), the stream completes immediately with `trigger:turn-complete`. For actions where `onAction` returns a `StreamTextResult`, the stream carries the assistant chunks the same way `sendMessages` does — `useChat` consumes them automatically.
 </Note>
 
 For server-to-server usage, `AgentChat` has the same method:

docs/ai-chat/reference.mdx

@@ -18,7 +18,7 @@ Options for `chat.agent()`.
 | `onValidateMessages`          | `(event: ValidateMessagesEvent) => UIMessage[] \| Promise<UIMessage[]>` | —                | Validate/transform UIMessages before model conversion. See [onValidateMessages](/ai-chat/backend#onvalidatemessages) |
 | `hydrateMessages`             | `(event: HydrateMessagesEvent) => UIMessage[] \| Promise<UIMessage[]>` | —                 | Load message history from backend, replacing the linear accumulator. See [hydrateMessages](/ai-chat/backend#hydratemessages) |
 | `actionSchema`                | `TaskSchema`                                                | —                              | Schema for validating custom actions sent via `transport.sendAction()`. See [Actions](/ai-chat/backend#actions) |
-| `onAction`                    | `(event: ActionEvent) => Promise<void> \| void`             | —                              | Handle custom actions. Fires after hydration, before `onTurnStart`. See [Actions](/ai-chat/backend#actions) |
+| `onAction`                    | `(event: ActionEvent) => Promise<unknown> \| unknown`       | —                              | Handle custom actions. Actions are not turns — only `hydrateMessages` + `onAction` fire. Return a `StreamTextResult` (or `string` / `UIMessage`) for a model response; return `void` for side-effect-only. See [Actions](/ai-chat/backend#actions) |
 | `onTurnStart`                 | `(event: TurnStartEvent) => Promise<void> \| void`          | —                              | Fires every turn before `run()`                                                                     |
 | `onBeforeTurnComplete`        | `(event: BeforeTurnCompleteEvent) => Promise<void> \| void` | —                              | Fires after response but before stream closes. Includes `writer`.                                   |
 | `onTurnComplete`              | `(event: TurnCompleteEvent) => Promise<void> \| void`       | —                              | Fires after each turn completes (stream closed)                                                     |

docs/ai-chat/testing.mdx

@@ -201,7 +201,7 @@ Equivalent to the frontend's `useChat().regenerate()` — replays a turn with th
 
 ### sendAction
 
-Routes a payload through `actionSchema` + `onAction`:
+Routes a payload through `actionSchema` + `onAction`. Actions are not turns: only `hydrateMessages` and `onAction` fire on the agent side — no turn lifecycle hooks, no `run()`. The returned `turn.rawChunks` contains whatever `onAction` produced (a streamed model response if it returned a `StreamTextResult`, otherwise just `trigger:turn-complete`):
 
 ```ts
 const turn = await harness.sendAction({ type: "undo" });

docs/ai-chat/upgrade-guide.mdx

@@ -301,8 +301,12 @@ and direct API consumers.
 - `chat.agent({...})` definition — `id`, `idleTimeoutInSeconds`,
   `clientDataSchema`, `actionSchema`, `hydrateMessages`, `onPreload`,
   `onChatStart`, `onValidateMessages`, `onTurnStart`, `onTurnComplete`,
-  `onChatSuspend`, `onAction`, `run`. All callbacks have the same
-  signature and fire at the same lifecycle points.
+  `onChatSuspend`, `run`. All callbacks have the same signature and
+  fire at the same lifecycle points.
+- `onAction` is still defined the same way, but its semantics changed
+  in the [May 6 prerelease](/ai-chat/changelog) — actions are no longer
+  turns, and `onAction` returning a `StreamTextResult` produces a model
+  response.
 - `chat.customAgent({...})` and the `chat.createSession(payload, ...)`
   helper for building a session loop manually inside a custom agent.
 - `chat.store` (snapshot store), `chat.defer` (deferred work), and