@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/ai-chat/migrating-from-hydrate-messages.mdx

@@ -0,0 +1,299 @@
+---
+title: "Migrate from hydrateMessages to transcript storage"
+sidebarTitle: "Migrating from hydrateMessages"
+description: "Move a chat.agent that persists its own history through hydrateMessages onto a TranscriptStorage: map your tables, implement load and save, decide whether you need loadContext, and delete the recovery and compaction code you no longer own."
+---
+
+Learn how to replace a `hydrateMessages` hook with a `storage` on the same tables, so the runtime writes the conversation for you and your app stops re-deriving what the runtime already knows.
+
+`hydrateMessages` keeps working with a one-time deprecation warning, so you can migrate one agent at a time. Setting both `hydrateMessages` and `storage` on one agent is a startup error, which makes the switch a swap rather than an overlap.
+
+## What changes hands
+
+With `hydrateMessages`, your hook was the source of truth and the runtime wrote nothing, so your app re-derived from its own rows everything the runtime already knew. A [transcript storage](/ai-chat/transcript-storage) inverts that: the runtime owns the transcript and calls your storage at the durable boundaries.
+
+| Concern | With `hydrateMessages` | With `storage` |
+| --- | --- | --- |
+| Reading history | Your hook, on every turn and action | `load`, once when a run boots |
+| Writing the user's message and the answer | Your `onTurnStart` / `onTurnComplete` code | `save` receives them as `put` changes |
+| A message sent mid-answer (steering) | You wrote it, and placed it before the answer | Arrives in the same changeset, in order |
+| Undo, edit, regenerate | Row writes paired with each `chat.history` call | Arrive as `truncateAfter` and `put` changes |
+| Partial answer after a crash | Your partial rows and a recovery flag | A `put` with `final: false`; you report it back in `nonFinalIds` |
+| Tool call the dead run never answered | Your repair pass | Cleaned up by the runtime before the save |
+| Compaction summary | Your summary column and watermark, invalidated on every rollback path | An opaque `state` blob you store and return; the runtime discards it when a rollback crosses it |
+| Resume cursors | Your `lastEventId` write, in the same transaction as the answer | `cursors` on the changeset; write them in the same transaction |
+| Deciding what the model sees | The array your hook returned | The transcript, or `loadContext` if your database decides |
+
+## Before you start
+
+- Your message table needs three things per row: the message id, the `UIMessage` itself, and a column to order by. If you stored messages as `ModelMessage`s, convert your existing rows first; a storage holds `UIMessage`s only.
+- Add somewhere to keep an opaque JSON blob per chat (the runtime's `state`) and two opaque string cursors per chat.
+- If you have a `final`, `status` or `partial` flag already, keep it. If not, add one; it is how a cut-short answer stays marked across a continuation.
+
+<Steps>
+  <Step title="Implement load">
+    `load` returns the conversation in order, the `state` blob, the cursors, and the ids of any rows you stored as partial. Scope the read by `clientData` where your backend enforces tenancy.
+
+    ```ts lib/transcript-storage.ts
+    import type { TranscriptStorage } from "@trigger.dev/sdk/ai";
+    import { db } from "@/lib/db";
+
+    type Scope = { userId: string };
+
+    export const transcriptStorage: TranscriptStorage<Scope> = {
+      async load({ chatId, clientData }, opts) {
+        const chat = await db.chat.findUnique({
+          where: { id: chatId },
+          include: { session: true },
+        });
+        if (chat && chat.userId !== clientData.userId) {
+          throw new Error("This conversation could not be loaded.");
+        }
+        if (!chat) return { messages: [], state: null };
+
+        const cursors = {
+          lastOutEventId: chat.session?.lastEventId ?? undefined,
+          lastInEventId: chat.session?.lastInEventId ?? undefined,
+        };
+
+        let before: number | undefined;
+        if (opts?.before) {
+          const anchor = await db.message.findUnique({
+            where: { chatId_id: { chatId, id: opts.before } },
+          });
+          if (!anchor) return { messages: [], state: chat.transcriptState, cursors };
+          before = anchor.position;
+        }
+        const where = { chatId, ...(before !== undefined ? { position: { lt: before } } : {}) };
+
+        let rows;
+        let nextCursor: string | undefined;
+        if (opts?.limit) {
+          const page = await db.message.findMany({
+            where,
+            orderBy: { position: "desc" },
+            take: opts.limit + 1,
+          });
+          rows = page.slice(0, opts.limit).reverse();
+          if (page.length > opts.limit) nextCursor = rows[0]?.id;
+        } else {
+          rows = await db.message.findMany({ where, orderBy: { position: "asc" } });
+        }
+
+        return {
+          messages: rows.map((row) => row.message),
+          state: chat.transcriptState,
+          cursors,
+          nextCursor,
+          nonFinalIds: rows.filter((row) => row.status === "partial").map((row) => row.id),
+        };
+      },
+
+      async save(ctx, changeset) {
+        // next step
+      },
+    };
+    ```
+
+    The runtime calls `load` with no options and wants the whole conversation. Your frontend's [history read](/ai-chat/transcript-storage#reading-the-transcript) passes `limit` (and later `before`), so the example fetches one extra row to tell whether earlier messages exist and returns the oldest included id as `nextCursor`.
+  </Step>
+
+  <Step title="Implement save">
+    Apply the changeset's `changes` to your rows and write the `cursors`, in one transaction. The cursor tells a reconnecting client what it has already seen; a cursor that lands ahead of the rows it accounts for makes that client skip chunks stored nowhere.
+
+    ```ts lib/transcript-storage.ts
+    async save({ chatId, clientData }, changeset) {
+      await db.$transaction(async (tx) => {
+        const chat = await tx.chat.findUnique({ where: { id: chatId } });
+        if (chat && chat.userId !== clientData.userId) {
+          throw new Error("This conversation could not be saved.");
+        }
+        if (!chat) await tx.chat.create({ data: { id: chatId, userId: clientData.userId } });
+
+        let next = (await lastPosition(tx, chatId)) + 1;
+
+        for (const change of changeset.changes) {
+          switch (change.op) {
+            case "put": {
+              const status = change.final === false ? "partial" : "complete";
+              const existing = await tx.message.findUnique({
+                where: { chatId_id: { chatId, id: change.message.id } },
+              });
+              if (existing) {
+                await tx.message.update({
+                  where: { chatId_id: { chatId, id: change.message.id } },
+                  data: { message: change.message, status },
+                });
+              } else {
+                await tx.message.create({
+                  data: { chatId, id: change.message.id, position: next++, message: change.message, status },
+                });
+              }
+              break;
+            }
+            case "remove":
+              await tx.message.deleteMany({ where: { chatId, id: change.id } });
+              break;
+            case "truncateAfter": {
+              const anchor = await tx.message.findUnique({
+                where: { chatId_id: { chatId, id: change.afterId } },
+              });
+              if (anchor) {
+                await tx.message.deleteMany({ where: { chatId, position: { gt: anchor.position } } });
+                next = anchor.position + 1;
+              }
+              break;
+            }
+            case "state":
+              await tx.chat.update({ where: { id: chatId }, data: { transcriptState: change.value } });
+              break;
+          }
+        }
+
+        if (changeset.cursors) {
+          await tx.chatSession.upsert({
+            where: { chatId },
+            create: { chatId, ...cursorColumns(changeset.cursors) },
+            update: cursorColumns(changeset.cursors),
+          });
+        }
+      });
+    }
+    ```
+
+    Three rules keep the rows in the runtime's order:
+
+    - Assign a position only when a row is first inserted, in the order the `put`s arrive. Within one changeset that is conversation order, so a steer sent mid-answer lands before the answer it shaped.
+    - Leave the position alone on a `put` for a known id. A tool approval, a settled partial and a compaction all replace a message in place.
+    - Do not order by a write timestamp. A replaced message would jump to the end, and a steer written after the answer would sort after it.
+
+    If you keep the whole conversation as one document instead of rows, ignore `changes` and write `changeset.transcript` as-is. Pick one of the two and stay with it.
+  </Step>
+
+  <Step title="Decide whether you need loadContext">
+    Most `hydrateMessages` hooks did two jobs: they persisted the incoming message and they returned the history. `save` and `load` cover both, so most agents need nothing more.
+
+    Add `loadContext` only when your database decides what the model sees each turn: a branching conversation where only the active branch is context, or a trust boundary where the browser's history is not to be believed. The runtime calls it on every turn and action with the incoming messages and the transcript it had, and uses what you return as the conversation. `save` keeps receiving every change and crash recovery keeps running.
+
+    ```ts lib/transcript-storage.ts
+    loadContext: async ({ chatId, clientData }, { incomingMessages }) => {
+      const branch = await db.activeBranch(chatId, clientData.userId);
+      return [...branch, ...incomingMessages];
+    },
+    ```
+
+    Do not port the body of your `hydrateMessages` hook into `loadContext` wholesale. The writes in it belong in `save`, and the recovery and compaction logic in it is gone.
+  </Step>
+
+  <Step title="Swap the option">
+    Set `storage`, remove `hydrateMessages`, and let the agent boot. It throws on start if both are still present.
+
+    ```ts trigger/chat.ts
+    export const myChat = chat.agent({
+      id: "my-chat",
+      storage: transcriptStorage,
+      clientDataSchema: z.object({ userId: z.string() }),
+      run: async ({ messages, signal, streamText }) =>
+        streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
+    });
+    ```
+  </Step>
+
+  <Step title="Delete what the runtime now owns">
+    Work through your hooks and remove every write that duplicates a change the storage receives:
+
+    - Message writes in `onTurnStart` and `onTurnComplete`, including the steering messages you filed from `newUIMessages` or `pendingMessages.onReceived`.
+    - The `lastEventId` write in `onTurnComplete`. The cursor now arrives on the changeset.
+    - Row writes paired with `chat.history` calls in `onAction`. An undo is a `truncateAfter`, an edit is a `put` and a `truncateAfter`. To answer after an edit, return `chat.turn()`; returning a model response from `onAction` is no longer supported.
+    - Per-step partial writes in `onStepFinish`, and any run-state or "still streaming" flag. A crash is recovered from the durable session stream, and a partial that survives reaches `save` with `final: false`.
+    - Dangling tool-call repair. The runtime cleans a partial before it saves it.
+    - Your compaction summary column, its watermark, and the invalidation you ran on every rollback path. The summary travels in `state`, and the runtime discards it when a rollback crosses the point it covers.
+    - Any filter that dropped an empty assistant message. A turn that fails before the model writes anything is not handed to `save`.
+
+    Keep `onTurnStart` for the session token if your frontend hydrates from your own table, and keep `onTurnComplete` for side work such as naming the conversation.
+  </Step>
+
+  <Step title="Update the history read on your frontend">
+    Your page most likely reads history from your tables directly. That keeps working. To use the same read the runtime uses, and to seed the live subscription's cursor so a reload does not replay what it just loaded, wrap the storage in a server action and load it with the hook:
+
+    <CodeGroup>
+    ```ts app/actions.ts
+    "use server";
+    import { chat } from "@trigger.dev/sdk/ai";
+    import { transcriptStorage } from "@/lib/transcript-storage";
+
+    const load = chat.createLoadTranscriptAction(transcriptStorage);
+
+    export async function loadTranscript(params: { chatId: string; limit?: number; before?: string }) {
+      const userId = await getUserId();
+      await assertOwnsChat(userId, params.chatId);
+      return load({ ...params, clientData: { userId } });
+    }
+    ```
+
+    ```tsx app/c/[chatId]/ChatPage.tsx
+    "use client";
+    import { useLoadTranscript, useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
+    import { loadTranscript } from "@/app/actions";
+
+    export function ChatPage({ chatId }: { chatId: string }) {
+      const transport = useTriggerChatTransport({ task: "my-chat", accessToken, startSession });
+      const { messages, isLoading, nextCursor } = useLoadTranscript(chatId, loadTranscript, {
+        transport,
+        limit: 50,
+      });
+      if (isLoading) return <Spinner />;
+      return <Chat chatId={chatId} initialMessages={messages} transport={transport} olderPage={nextCursor} />;
+    }
+    ```
+    </CodeGroup>
+
+    <Warning>
+      The action receives `chatId` from the browser. Authorize it there, before calling the storage. The storage's own `clientData` check is a backstop, not the boundary.
+    </Warning>
+  </Step>
+
+  <Step title="Run the conformance suite">
+    Point `runTranscriptStorageTests` at your storage. It checks appends and in-place replacement, idempotent `remove` and `truncateAfter`, `state` round-trips, cursors, replaying the same changeset twice, paging, and chat isolation, against whatever database you give it.
+
+    ```ts lib/transcript-storage.test.ts
+    import { runTranscriptStorageTests } from "@trigger.dev/sdk/ai/test";
+    import { describe, expect, it } from "vitest";
+    import { transcriptStorage } from "./transcript-storage";
+
+    runTranscriptStorageTests(() => transcriptStorage, {
+      api: { describe, it, expect },
+      clientData: { userId: "user_test" },
+    });
+    ```
+
+    `memoryTranscriptStorage()` is the reference implementation. Use it in your agent tests to see exactly which changes the runtime hands a storage for a given turn.
+  </Step>
+</Steps>
+
+## Behaviour that changes
+
+A few things your users and your tests will notice after the swap:
+
+- **Actions are edits.** `onAction` mutates `chat.history` and returns nothing, or returns `chat.turn()` to have a full turn answer the edited history. The regenerated answer is saved and remembered like any other. See [Actions](/ai-chat/actions#answering-after-an-action).
+- **`onRecoveryBoot` is informational.** It fires when a run boots after a crash and finds a half-written answer on the session stream. The runtime already reconciled the transcript; use the hook to tell the user, not to write rows.
+- **A failed turn keeps its partial, marked.** An answer cut short reaches `save` with `final: false`; report those ids back from `load` in `nonFinalIds`.
+- **Compaction survives a reboot without your help.** The summary travels in `state`.
+- **Your rows do not have to be byte-identical.** Store messages in whatever shape your database prefers. The runtime does not depend on an exact JSON round-trip.
+
+## Checklist
+
+- [ ] `load` returns messages in conversation order, plus `state`, `cursors` and `nonFinalIds`
+- [ ] `save` applies all four change kinds and writes the cursors in the same transaction
+- [ ] Positions are assigned on first insert only, never by timestamp
+- [ ] `hydrateMessages` removed; `storage` set; the agent boots
+- [ ] Message, cursor, partial, repair and compaction writes deleted from hooks
+- [ ] `onAction` returns `chat.turn()` where it used to stream an answer
+- [ ] `runTranscriptStorageTests` passes against the real database
+
+## See also
+
+- [Transcript storage](/ai-chat/transcript-storage): the full contract and what `save` receives
+- [Actions](/ai-chat/actions): what undo, edit and regenerate become in the changeset
+- [Lifecycle hooks](/ai-chat/lifecycle-hooks#hydratemessages): the deprecated hook's reference entry
+- [Database persistence](/ai-chat/patterns/database-persistence): the hook-based pattern this replaces

package/docs/ai-chat/overview.mdx

@@ -0,0 +1,86 @@
+---
+title: "AI Agents"
+sidebarTitle: "Overview"
+description: "Durable multi-turn AI chats — one Trigger.dev task per conversation, surviving refreshes, deploys, and crashes."
+---
+
+An AI chat isn't a request — it's a session. `chat.agent` runs every conversation as a single long-lived Trigger.dev task: you write the loop, it wakes up when a message arrives, freezes when none do, and the same in-memory state and on-disk workspace survive across page refreshes, deploys, idle gaps, and crashes. The substrate handles the parts most teams stitch together by hand — turn lifecycle, mid-stream resume, recovery from cancel/crash/OOM, HITL approvals, deploy upgrades — so your code is the loop you'd write anyway: messages in, `streamText` out.
+
+## A minimal example
+
+A `chat.agent` task takes `messages`, calls `streamText`, and returns the result. The frontend wires the [Vercel AI SDK's `useChat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) to a `TriggerChatTransport`. No API routes.
+
+```ts trigger/chat.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { streamText, stepCountIs } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  run: async ({ messages, signal }) =>
+    streamText({
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      abortSignal: signal,
+      stopWhen: stepCountIs(15),
+    }),
+});
+```
+
+```tsx app/components/Chat.tsx
+import { useChat } from "@ai-sdk/react";
+import { useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
+
+export function Chat() {
+  const transport = useTriggerChatTransport<typeof myChat>({
+    task: "my-chat",
+    accessToken: ({ chatId }) => mintChatAccessToken(chatId),
+    startSession: ({ chatId, clientData }) =>
+      startChatSession({ chatId, clientData }),
+  });
+  const { messages, sendMessage } = useChat({ transport });
+  // ... render UI
+}
+```
+
+See [Quick Start](/ai-chat/quick-start) for the matching server actions and a runnable project.
+
+## Why use AI Agents on Trigger.dev
+
+- **Resume across refreshes, deploys, and crashes.** A chat in progress keeps streaming through a redeploy, pinned to the version it started on. Move it onto new code when you choose with a [version upgrade](/ai-chat/patterns/version-upgrades). Mid-stream refreshes pick up where they left off.
+- **Native AI SDK support.** Text, tool calls, reasoning, and custom `data-*` parts all flow through `useChat` over a custom `ChatTransport`. No custom protocol to maintain.
+- **Multi-turn for free.** Each turn is a step inside the same durable task; conversation history accumulates server-side, so clients only ship the new message.
+- **Fast cold starts.** Opt-in [Head Start](/ai-chat/fast-starts#head-start) runs the first `streamText` step in your warm Next.js / Hono / SvelteKit server while the agent boots in parallel — cuts time-to-first-chunk roughly in half.
+- **Production primitives ship in the box.** Stop generation, steering, edits, branching, sub-agents, HITL tool approvals, version upgrades, recovery from cancel/crash/OOM — all first-class.
+- **Observable.** Every turn is a span in the Trigger.dev dashboard. Sessions are queryable via `sessions.list` for inbox-style UIs.
+
+## How it fits together
+
+Three primitives, related but distinct:
+
+- **Chat agents** — the SDK surface you define with [`chat.agent()`](/ai-chat/backend#chat-agent). Owns the turn loop, lifecycle hooks, and the response stream.
+- **Sessions** — the durable, bi-directional channel keyed on `chatId` that holds the conversation across run boundaries. A chat agent runs *on top of* a [Session](/ai-chat/sessions).
+- **Sub-agents** — Delegate work from one agent to another via [`AgentChat`](/ai-chat/patterns/sub-agents). The sub-agent runs as its own durable agent on its own session; its response streams back through the parent as preliminary tool results, so the frontend sees the sub-agent working inside the parent's tool card.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Quick Start" icon="rocket" href="/ai-chat/quick-start">
+    Get a working chat in three steps — agent, token, frontend.
+  </Card>
+  <Card title="How it works" icon="diagram-project" href="/ai-chat/how-it-works">
+    Sessions, the turn loop, durable streams, and what survives a refresh.
+  </Card>
+  <Card title="Backend" icon="server" href="/ai-chat/backend">
+    `chat.agent` options, lifecycle hooks, and the raw-task primitives.
+  </Card>
+  <Card title="Tools" icon="wrench" href="/ai-chat/tools">
+    Declare tools so `toModelOutput` survives across turns, typed in `run()`.
+  </Card>
+  <Card title="Patterns" icon="puzzle-piece" href="/ai-chat/patterns/sub-agents">
+    HITL approvals, branching, sub-agents, OOM/crash recovery.
+  </Card>
+  <Card title="Database connections" icon="database" href="/database-connections">
+    Size and release connection pools so agents don't exhaust your database.
+  </Card>
+</CardGroup>

package/docs/ai-chat/patterns/branching-conversations.mdx

@@ -0,0 +1,145 @@
+---
+title: "Branching conversations"
+sidebarTitle: "Branching conversations"
+description: "Persist an active conversation branch and use transcript storage and actions to switch the agent's context."
+---
+
+Keep an explicit active branch for each chat. Use your storage adapter's `loadContext` to give the model that branch, and use actions to fork or switch it.
+
+A fork copies the conversation up to a selected message. Later messages belong to that branch only. For example, one branch can keep Oslo as a destination while another changes it to Tokyo.
+
+## Store the active branch
+
+Your database needs a chat record with an `activeBranchId`, plus messages for each branch. You can store each branch as a snapshot or use parent pointers to share message prefixes. Persist the selected branch explicitly; choosing the newest leaf loses the selection when someone switches to an older branch.
+
+Keep the transcript's `final` flags, opaque runtime state, and stream cursors. A partial assistant response must stay partial after a reload. See [transcript storage](/ai-chat/transcript-storage) for the adapter contract and pagination helpers.
+
+The examples below use application helpers from `@/lib/branches`. Implement them against your database with these guarantees:
+
+| Helper | Behavior |
+| --- | --- |
+| `readActiveMessages(chatId)` | Return the selected branch in message order. |
+| `forkBranch(chatId, messageId)` | Copy the active prefix through the selected message, create a branch, and select it in one transaction. Reject messages outside this chat. |
+| `selectBranch(chatId, branchId)` | Select an existing branch belonging to this chat. |
+| `branchStorage.load` | Return the active transcript, runtime state, final flags, and resume cursors. |
+| `branchStorage.save` | Save the supplied transcript to the active branch and retain the supplied runtime state and cursors. |
+
+Make repeated saves idempotent by message ID. Serialize branch changes with transcript writes so a turn can't save its response into a different branch.
+
+## Load the selected context
+
+A storage adapter with `loadContext` owns the model's context on every turn and action. Include incoming user messages in the selected branch. Handle regeneration explicitly by removing trailing assistant messages before returning the context.
+
+```ts lib/branch-storage.ts
+import type { UIMessage } from "ai";
+import type {
+  LoadContextEvent,
+  TranscriptScope,
+  TranscriptStorage,
+} from "@trigger.dev/sdk/ai";
+import { branchStorage, readActiveMessages } from "@/lib/branches";
+
+export const storage: TranscriptStorage = {
+  ...branchStorage,
+  async loadContext<T extends UIMessage>(
+    { chatId }: TranscriptScope,
+    event: LoadContextEvent<unknown, T>
+  ): Promise<T[]> {
+    const messages = [...(await readActiveMessages(chatId))] as T[];
+
+    if (event.trigger === "regenerate-message") {
+      while (messages.length && messages.at(-1)!.role !== "user") {
+        messages.pop();
+      }
+    }
+
+    for (const incoming of event.incomingMessages) {
+      if (incoming.role === "user" && !messages.some((m) => m.id === incoming.id)) {
+        messages.push(incoming);
+      }
+    }
+
+    return messages;
+  },
+};
+```
+
+This pattern supports plain user messages. For tools that wait for browser results or approval, retain the canonical assistant message in your returned context. The SDK merges incoming tool-result state into that message by ID.
+
+`loadContext` also receives `previousMessages`, including any tail recovered from the session stream. If your database missed a save, reconcile that tail with the active branch before returning context. Recovery needs to preserve branch ownership; appending every recovered message to whichever branch is selected can mix conversations.
+
+## Fork and switch through actions
+
+Perform branch changes in `onAction` and update `chat.history` to match the selected branch. Returning without `chat.turn()` completes the action without asking the model for a response. The runtime still calls `storage.save` with reason `action`.
+
+```ts trigger/chat.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { z } from "zod";
+import { storage } from "@/lib/branch-storage";
+import { forkBranch, selectBranch, readActiveMessages } from "@/lib/branches";
+
+export const myChat = chat.agent({
+  id: "branching-chat",
+  storage,
+  actionSchema: z.discriminatedUnion("type", [
+    z.object({ type: z.literal("fork"), messageId: z.string() }),
+    z.object({ type: z.literal("switch"), branchId: z.string() }),
+  ]),
+  onAction: async ({ chatId, action }) => {
+    if (action.type === "fork") {
+      await forkBranch(chatId, action.messageId);
+    } else {
+      await selectBranch(chatId, action.branchId);
+    }
+
+    chat.history.set(await readActiveMessages(chatId));
+  },
+  run: async ({ messages, signal, streamText }) => {
+    return streamText({
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      abortSignal: signal,
+    });
+  },
+});
+```
+
+Wait for a response to finish before forking or switching. Start with forks at completed assistant messages. Forking inside an unresolved tool exchange needs a policy for pending tool calls and already-performed side effects.
+
+## Update the frontend after the action
+
+Use `useChatActions` with `useChat`'s `sendMessage`. It consumes the action's response stream and keeps request state in the chat hook. After the action completes, reload the selected transcript so the visible messages match the next model call.
+
+```tsx app/chat/BranchPicker.tsx
+import { useChat } from "@ai-sdk/react";
+import { useChatActions } from "@trigger.dev/sdk/chat/react";
+import { loadTranscript } from "@/app/actions";
+
+// Inside your chat component, with its existing chatId and transport:
+const { sendMessage, setMessages, status } = useChat({ id: chatId, transport });
+const { sendAction } = useChatActions({ sendMessage });
+const busy = status === "submitted" || status === "streaming";
+
+async function switchBranch(branchId: string) {
+  await sendAction({ type: "switch", branchId });
+  const transcript = await loadTranscript({ chatId });
+  setMessages(transcript.messages);
+}
+
+<button disabled={busy} onClick={() => switchBranch(branch.id)}>
+  {branch.label}
+</button>
+```
+
+Authenticate `loadTranscript` and check ownership before reading the chat. Validate branch IDs on the server even when the frontend only offers branches from that chat. If you use `transport.sendAction` directly, consume its returned stream before sending another message.
+
+## Check branch isolation
+
+1. Tell the agent the destination is Oslo and wait for the response.
+2. Fork at that response, then change the destination to Tokyo.
+3. Switch to the original branch and ask for the destination. It should answer Oslo.
+4. Switch to the fork and ask again. It should answer Tokyo.
+5. Reload the page and repeat the checks. The selected branch and its messages should survive the reload.
+
+Also test regeneration, repeated storage saves, and continuation in a fresh run. An in-memory branch choice can pass the first four steps and still disappear when the worker restarts.

package/docs/ai-chat/patterns/code-sandbox.mdx

@@ -0,0 +1,122 @@
+---
+title: "Code execution sandbox"
+sidebarTitle: "Code sandbox"
+description: "Warm an isolated sandbox on each chat turn, run an AI SDK executeCode tool, and tear down right before the run suspends — using chat.agent hooks and chat.local."
+---
+
+Use a **hosted code sandbox** (for example [E2B](https://e2b.dev)) when the model should run short scripts to analyze tool output (PostHog queries, CSV-like data, math) without executing arbitrary code on the Trigger worker host.
+
+This page describes a **durable chat** pattern that fits `chat.agent()`:
+
+- **Warm** the sandbox at the start of each turn (**non-blocking**).
+- **Reuse** it for every `executeCode` tool call during that turn (and across turns in the same run if you keep the handle).
+- **Dispose** it **right before the run suspends** waiting for the next user message — using the **`onChatSuspend`** hook, not `onTurnComplete`.
+
+
+## Why not tear down in `onTurnComplete`?
+
+After a turn finishes, the chat runtime still goes through an **idle** window and only then suspends. During that window the run is still executing — useful for `chat.defer()` work — and the run hasn't suspended yet.
+
+The boundary you want for “turn done, about to sleep” is **`onChatSuspend`**, which fires right before the run transitions from idle to suspended. It provides the `phase` (`”preload”` or `”turn”`) and full chat context. See [onChatSuspend / onChatResume](/ai-chat/lifecycle-hooks#onchatsuspend--onchatresume).
+
+```mermaid
+sequenceDiagram
+  participant TurnStart as onTurnStart
+  participant Run as run / streamText
+  participant TurnDone as onTurnComplete
+  participant Idle as Idle window
+  participant Suspend as onChatSuspend
+  participant Sleep as suspended
+
+  TurnStart->>Run: warm sandbox (async)
+  Run->>TurnDone: persist / inject / etc.
+  TurnDone->>Idle: still running
+  Idle->>Suspend: dispose sandbox
+  Suspend->>Sleep: waiting for next message
+```
+
+## Recommended provider: E2B
+
+- **API key** auth — works from any Trigger.dev worker; no Vercel-only OIDC.
+- **Code Interpreter** SDK (`@e2b/code-interpreter`): long-lived sandbox, `runCode()`, `kill()`.
+
+Alternatives (Modal, Daytona, raw Docker) are fine but more DIY. Vercel’s sandbox + AI SDK helpers are a better fit when execution stays **on Vercel**, not on the Trigger worker.
+
+## Implementation sketch
+
+### 1. Run-scoped sandbox map
+
+Keep a `Map<runId, Promise<Sandbox>>` (or similar) in a **task-only module** so your Next.js app never imports it.
+
+### 2. `onTurnStart` — warm without blocking
+
+```ts
+onTurnStart: async ({ runId, ctx, ...rest }) => {
+  warmCodeSandbox(runId); // fire-and-forget Sandbox.create()
+  // ...persist messages, writer, etc.
+},
+```
+
+### 3. `chat.local` — run id for tools
+
+Tool `execute` functions do not receive hook payloads. Use [`chat.local()`](/ai-chat/chat-local) to store the current run id for the sandbox key, **initialized from `onTurnStart`** (same `runId` as the map):
+
+```ts
+// In the same task module as your tools
+import { chat } from "@trigger.dev/sdk/ai";
+
+export const codeSandboxRun = chat.local<{ runId: string }>({ id: "codeSandboxRun" });
+
+export function warmCodeSandbox(runId: string) {
+  codeSandboxRun.init({ runId });
+  // ...start Sandbox.create(), store promise in Map by runId
+}
+```
+
+The **`executeCode`** tool reads `codeSandboxRun.runId` and awaits the sandbox promise before `runCode`.
+
+### 4. `onChatSuspend` / `onComplete` — teardown
+
+Use **`onChatSuspend`** to dispose the sandbox right before the run suspends, and **`onComplete`** as a safety net when the run ends entirely.
+
+```ts
+export const aiChat = chat.agent({
+  id: "ai-chat",
+  // ...
+  onChatSuspend: async ({ phase, ctx }) => {
+    await disposeCodeSandboxForRun(ctx.run.id);
+  },
+  onComplete: async ({ ctx }) => {
+    await disposeCodeSandboxForRun(ctx.run.id);
+  },
+});
+```
+
+Unlike `onWait` (which fires for all wait types), `onChatSuspend` only fires at chat suspension points — no need to filter on `wait.type`. The `phase` discriminator tells you if this is a preload or post-turn suspension.
+
+Optional **`onChatResume`**: log or reset flags; a fresh sandbox can be warmed again on the next **`onTurnStart`**.
+
+### 5. AI SDK tool
+
+Wrap the provider in a normal AI SDK `tool({ inputSchema, execute })` (same pattern as `webFetch`). Keep tool definitions in **task code**, not in the Next.js server bundle.
+
+### 6. Environment
+
+Set **`E2B_API_KEY`** (or your provider’s secret) on the **Trigger environment** for the worker — not in public client env.
+
+## Typing `ctx`
+
+Every `chat.agent` lifecycle event and the `run` payload include **`ctx`**: the same **[`TaskRunContext`](/ai-chat/reference#task-context-ctx)** shape as `task({ run: (payload, { ctx }) => ... })`.
+
+```ts
+import type { TaskRunContext } from "@trigger.dev/sdk";
+```
+
+The alias **`Context`** is also exported from `@trigger.dev/sdk` and is the same type.
+
+## See also
+
+- [Database persistence for chat](/ai-chat/patterns/database-persistence) — conversation + session rows, hooks, token renewal
+- [Lifecycle hooks](/ai-chat/lifecycle-hooks)
+- [API Reference — `ctx` on events](/ai-chat/reference#task-context-ctx)
+- [Per-run data with `chat.local`](/ai-chat/chat-local)