@trigger.dev/sdk 4.5.0-rc.5 → 4.5.0-rc.7

package/docs/ai-chat/actions.mdx

@@ -0,0 +1,115 @@
+---
+title: "Actions"
+sidebarTitle: "Actions"
+description: "Custom commands sent from the frontend that mutate chat state without consuming a turn — undo, rollback, edit, regenerate."
+---
+
+import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
+
+<RcBanner />
+
+## Overview
+
+Custom actions let the frontend send structured commands (undo, rollback, edit, regenerate) that modify the conversation state. **Actions are not turns**: they fire `hydrateMessages` (if set) and `onAction` only. No turn lifecycle hooks (`onTurnStart` / `prepareMessages` / `onBeforeTurnComplete` / `onTurnComplete`), no `run()`, no turn-counter increment. The trace span is named `chat action`.
+
+Actions wake the agent from suspension the same way a new message does, run their handler against the latest accumulator state, and emit a `trigger:turn-complete` chunk so the frontend's `useChat` knows the action has been applied.
+
+## Defining an action handler
+
+Define an `actionSchema` for validation and an `onAction` handler that uses [`chat.history`](/ai-chat/backend#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;
+    }
+    // returning void → side-effect-only, no model call
+  },
+
+  run: async ({ messages, signal }) => {
+    return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
+  },
+});
+```
+
+**Lifecycle flow:** Wake → parse action against `actionSchema` → `hydrateMessages` (if set) → **`onAction`** → apply `chat.history` mutations → emit `trigger:turn-complete` → wait for next message.
+
+## Returning a model response from an action
+
+`onAction` can return a `StreamTextResult`, `string`, or `UIMessage` to produce a response. The returned stream is auto-piped to the frontend just like a normal turn, but the rest of the turn machinery (`onTurnStart`, `onTurnComplete`, etc.) still does not fire.
+
+```ts
+onAction: async ({ action, messages }) => {
+  if (action.type === "regenerate") {
+    chat.history.slice(0, -1); // drop the last assistant
+    return streamText({
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      stopWhen: stepCountIs(15),
+    });
+  }
+  // other actions return void → side-effect only
+}
+```
+
+This is useful for actions that both mutate state and want a fresh model response (regenerate-from-here, retry-with-different-style). Persistence is your responsibility inside `onAction` itself; you have access to the streamed response object.
+
+## Gating actions on HITL state
+
+If you have a [human-in-the-loop](/ai-chat/patterns/human-in-the-loop) tool waiting on `addToolOutput`, you usually want to refuse competing actions like `regenerate` until the answer arrives. [`chat.history.getPendingToolCalls()`](/ai-chat/backend#chat-history) gives you exactly that signal:
+
+```ts
+onAction: async ({ action, messages, signal }) => {
+  if (action.type === "regenerate") {
+    if (chat.history.getPendingToolCalls().length > 0) return; // gated
+    chat.history.slice(0, -1);
+    return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
+  }
+},
+```
+
+## Sending actions from the frontend
+
+```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 surface as a stream error. The `action` parameter in `onAction` is fully typed from the schema.
+
+<Note>
+  For silent state changes that should never appear as a turn (e.g. injecting background context), use [`chat.inject()`](/ai-chat/background-injection) instead. Actions are explicit user-driven mutations; injections are agent-side context updates.
+</Note>
+
+## See also
+
+- [`chat.history`](/ai-chat/backend#chat-history) — the imperative API actions use to mutate state
+- [Sending actions from the frontend](/ai-chat/frontend#sending-actions) — `transport.sendAction` ergonomics
+- [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) — fires before `onAction` when set
+- [Branching conversations](/ai-chat/patterns/branching-conversations) — pairs action handlers with backend-controlled history
+- [Human-in-the-loop](/ai-chat/patterns/human-in-the-loop) — gating fresh actions while a tool is waiting

package/docs/ai-chat/anatomy.mdx

@@ -0,0 +1,71 @@
+---
+title: "Anatomy of an agent"
+sidebarTitle: "Anatomy"
+description: "The moving parts of a chat agent — the agent task, the session, the frontend transport — and which page covers each."
+---
+
+import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
+
+<RcBanner />
+
+**A chat agent is three parts: a long-lived agent task that runs the turn loop, a durable Session carrying messages in and the response stream out, and a frontend transport that plugs the session into `useChat`.** The pages in this section each own one part of that picture. This page is the map — if you'd rather read mechanics end to end, skip to [How it works](/ai-chat/how-it-works).
+
+```mermaid
+flowchart LR
+  FE["Frontend<br/>useChat + transport"] -- "user messages" --> IN([Session .in])
+  IN --> AGENT["Agent task<br/>turn loop + hooks"]
+  AGENT --> OUT([Session .out])
+  OUT -- "streamed response" --> FE
+```
+
+Everything below maps onto one annotated agent:
+
+```ts trigger/my-agent.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { streamText, stepCountIs } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export const myAgent = chat.agent({
+  id: "my-agent",
+
+  // Tools declared on the config survive history re-conversion
+  // across turns — see Tools.
+  tools: { searchDocs },
+
+  // Hooks fire around each turn: validation, persistence,
+  // post-turn work — see Lifecycle hooks.
+  onTurnComplete: async ({ responseMessage }) => {
+    await db.messages.save(responseMessage);
+  },
+
+  // The turn loop. Messages arrive accumulated; you stream back.
+  // Options, levels, and alternatives — see Backend.
+  run: async ({ messages, tools, signal }) =>
+    streamText({
+      ...chat.toStreamTextOptions({ tools }),
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      abortSignal: signal,
+      stopWhen: stepCountIs(15),
+    }),
+});
+```
+
+The frontend side is one hook — `useTriggerChatTransport` connects `useChat` to the agent's session, no API routes ([Frontend](/ai-chat/frontend)). Underneath, the conversation lives on a [Session](/ai-chat/sessions): a pair of durable streams keyed on your `chatId` that survives refreshes, deploys, and run boundaries.
+
+## Where each part is covered
+
+| Part                                                  | Page                                           |
+| ----------------------------------------------------- | ---------------------------------------------- |
+| `chat.agent()` options, the turn loop, piping         | [Backend](/ai-chat/backend)                    |
+| Hooks around each turn (`onTurnComplete`, hydration)  | [Lifecycle hooks](/ai-chat/lifecycle-hooks)    |
+| Declaring tools, typed payloads, `toModelOutput`      | [Tools](/ai-chat/tools)                        |
+| `useChat` wiring, tokens, starting sessions           | [Frontend](/ai-chat/frontend)                  |
+| Driving a chat from your server instead of a browser  | [Server-side chat](/ai-chat/server-chat)       |
+| The durable substrate under every agent               | [Sessions](/ai-chat/sessions)                  |
+| Per-run typed state inside the loop                   | [chat.local](/ai-chat/chat-local)              |
+| Type-safe payloads, client data, and messages         | [Types](/ai-chat/types)                        |
+| Building without the managed lifecycle                | [Custom agents](/ai-chat/custom-agents)        |
+| End-to-end mechanics: what survives a refresh and why | [How it works](/ai-chat/how-it-works)          |
+
+Beyond this section: [Features](/ai-chat/fast-starts) covers opt-in capabilities (Head Start, compaction, steering, actions), and [Patterns](/ai-chat/patterns/sub-agents) covers production recipes (sub-agents, HITL approvals, persistence, recovery).