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

package/docs/ai-chat/background-injection.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Background injection"
 description: "Inject context from background work into the agent's conversation — self-review, RAG augmentation, or any async analysis."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 ## Overview
 
 `chat.inject()` queues model messages for injection into the conversation. Messages are picked up at the start of the next turn or at the next `prepareStep` boundary (between tool-call steps).

package/docs/ai-chat/changelog.mdx

@@ -1,9 +1,117 @@
 ---
 title: "Changelog"
 sidebarTitle: "Changelog"
-description: "Pre-release updates for AI chat agents."
+description: "Changelog for the AI Agents SDK."
 ---
 
+<Update label="July 2, 2026" description="4.5.0" tags={["SDK", "Bug fix"]}>
+
+## Point chat sessions at a different project or environment
+
+[`chat.headStart`](/ai-chat/fast-starts#head-start) and [`chat.createStartSessionAction`](/ai-chat/sessions) now take an `apiClient` option (`baseURL` + `accessToken`). The server that creates the session and triggers the run can target a different project or environment than its ambient Trigger config, without setting a global `TRIGGER_SECRET_KEY`. Useful when your `chat.agent` lives in a separate project from the app serving the route, or when one server starts chats across more than one environment. Your LLM provider keys stay in the `run` callback and are unaffected. ([#4018](https://github.com/triggerdotdev/trigger.dev/pull/4018))
+
+```ts
+export const POST = chat.headStart({
+  agentId: "my-agent",
+  apiClient: { baseURL, accessToken },
+  run: async ({ chat }) =>
+    streamText({ ...chat.toStreamTextOptions({ tools }), model: anthropic("claude-sonnet-4-6") }),
+});
+```
+
+```ts
+const startSession = chat.createStartSessionAction("my-chat", {
+  apiClient: { baseURL, accessToken },
+});
+
+await startSession({ chatId, clientData });
+```
+
+## Fix: chat agents on preview branches
+
+Messaging a `chat.agent` (or `AgentChat`) deployed to a preview branch failed with `x-trigger-branch header required for preview env`. The realtime message-append and stream-subscribe calls now send the `x-trigger-branch` header, resolved the same way `sessions.start` resolves it, so preview-branch chat agents work. ([#4018](https://github.com/triggerdotdev/trigger.dev/pull/4018))
+
+## Fix: Head Start handovers with a prepareMessages hook
+
+A [Head Start](/ai-chat/fast-starts#head-start) handover passes the first turn's pending tool call to the agent as a tool-approval round whose trailing tool message must reach the model untouched. A `prepareMessages` hook that rewrites the last message (for example the recommended [prompt-caching](/ai-chat/prompt-caching) breakpoint) could disturb that tail, so the turn failed with `tool_use ids were found without tool_result`. The agent now preserves the approval tail across `prepareMessages`, so prompt caching and Head Start compose cleanly. ([#4018](https://github.com/triggerdotdev/trigger.dev/pull/4018))
+
+</Update>
+
+<Update label="June 17, 2026" description="4.5.0-rc.7" tags={["SDK", "CLI", "Bug fix"]}>
+
+## chat.headStart now works for custom agents and sessions
+
+[Head Start](/ai-chat/fast-starts#head-start) — running the first `streamText` step in your warm server while the agent boots in parallel — now works with the `chat.customAgent` and `chat.createSession` backends, not just the managed `chat.agent`. The warm step-1 response hands over to your loop the same way it does for a managed agent. ([#3963](https://github.com/triggerdotdev/trigger.dev/pull/3963))
+
+In a `chat.customAgent` loop, consume the handover on turn 0:
+
+```ts
+const conversation = new chat.MessageAccumulator();
+const { isFinal, skipped } = await conversation.consumeHandover({ payload });
+if (skipped) return; // warm handler aborted, so exit without a turn
+if (isFinal) {
+  await chat.writeTurnComplete(); // step 1 is the response, no streamText
+} else {
+  const result = streamText({ model, messages: conversation.modelMessages, tools });
+  // Pass originalMessages so the handed-over tool round merges into the
+  // step-1 assistant instead of starting a new message.
+  const response = await chat.pipeAndCapture(result, {
+    originalMessages: conversation.uiMessages,
+  });
+  if (response) await conversation.addResponse(response);
+}
+```
+
+With `chat.createSession`, the iterator surfaces it as `turn.handover`; call `turn.complete()` with no argument on a final handover. The lower-level `chat.waitForHandover()` and `accumulator.applyHandover()` are also exported for hand-rolled loops. See [Handover with custom agents](/ai-chat/fast-starts#handover-with-custom-agents).
+
+## Cache your system prompt with Anthropic prompt caching
+
+`chat.toStreamTextOptions()` can now emit the system prompt as a cacheable message when you opt in, so a large, stable system block is billed at cache-read rates on every turn instead of full price. Without an option, `system` stays a plain string. ([#3952](https://github.com/triggerdotdev/trigger.dev/pull/3952))
+
+```ts
+// at the streamText call site (Anthropic sugar)
+streamText({
+  ...chat.toStreamTextOptions({ cacheControl: { type: "ephemeral" } }),
+  messages,
+});
+
+// provider-agnostic equivalent
+chat.toStreamTextOptions({
+  systemProviderOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
+});
+
+// or where the prompt is defined
+chat.prompt.set(SYSTEM_PROMPT, {
+  providerOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
+});
+```
+
+Pairs with a `prepareMessages` cache breakpoint to cache the conversation prefix across turns too. See the [Prompt caching](/ai-chat/prompt-caching) guide.
+
+## Custom agent loop fixes
+
+Three fixes for custom agent loops (`chat.customAgent`, `chat.createSession`, and hand-rolled `MessageAccumulator` loops): ([#3936](https://github.com/triggerdotdev/trigger.dev/pull/3936))
+
+- **Continuations no longer replay answered messages.** The `.in` resume cursor is now seeded before any listener attaches (the same boot logic `chat.agent` uses), so a chat that continues after a cancel, crash, or upgrade only sees genuinely new messages.
+- **Steering mid-stream keeps the in-flight response.** `chat.pipeAndCapture` now stamps a server-generated message id on the stream, so a `prepareStep` injection keeps the partial text instead of replacing the message.
+- **Task-backed tools work from custom loops.** `ai.toolExecute` now threads the parent's session to the child run, so child tasks can stream progress into the chat with `chat.stream.writer({ target: "root" })` instead of failing with "session handle is not initialized".
+
+See [Custom agents](/ai-chat/custom-agents).
+
+## trigger skills: namespacing, docs bundling, and a cost-savings skill
+
+Follow-ups to the [`trigger skills`](/ai-chat/patterns/skills) command shipped in rc.6:
+
+- The skills installed into your coding assistant are now namespaced with a `trigger-` prefix (e.g. `trigger-authoring-tasks`, `trigger-getting-started`) so they don't collide with unrelated skills in your skills directory. ([#3970](https://github.com/triggerdotdev/trigger.dev/pull/3970))
+- `@trigger.dev/sdk` now bundles the Trigger.dev agent skills and the full Trigger.dev documentation those skills reference. The installed skills read this content from `node_modules`, so the guidance your AI assistant follows is pinned to the SDK version in your project and stays current across upgrades instead of going stale until the next reinstall. ([#3937](https://github.com/triggerdotdev/trigger.dev/pull/3937), [#3970](https://github.com/triggerdotdev/trigger.dev/pull/3970))
+- New `trigger-cost-savings` skill for auditing and reducing compute spend — right-sizing machines, `maxDuration`, batching, and debounce. ([#3970](https://github.com/triggerdotdev/trigger.dev/pull/3970))
+
+```bash
+npx trigger.dev@4.5.0-rc.7 skills
+```
+
+</Update>
+
 <Update label="June 12, 2026" description="4.5.0-rc.6" tags={["SDK", "CLI", "Bug fix"]}>
 
 ## chat.agent reliability fixes

package/docs/ai-chat/chat-local.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "chat.local"
 description: "Typed, run-scoped data accessible from hooks, run(), tools, and subtasks. Survives across turns, auto-cleared between runs, auto-hydrated into subtasks."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 Use `chat.local` to create typed, run-scoped data that persists across turns and is accessible from anywhere — the run function, tools, nested helpers. Each run gets its own isolated copy, and locals are automatically cleared between runs.
 
 Lifecycle hooks and **`run`** also receive **`ctx`** ([`TaskRunContext`](/ai-chat/reference#task-context-ctx)) — the same object as on a standard `task()` — for tags, metadata, and cleanup that needs the full run record.

package/docs/ai-chat/client-protocol.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Client Protocol"
 description: "The wire protocol for building custom chat transports — how clients communicate with chat agents over Sessions and SSE."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 This page documents the protocol that chat clients use to communicate with `chat.agent()` tasks. Use this if you're building a custom transport (e.g., for a Slack bot, CLI tool, or native app) instead of using the built-in `TriggerChatTransport` or `AgentChat`.
 
 <Note>

package/docs/ai-chat/compaction.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Compaction"
 description: "Automatic context compaction to keep long conversations within token limits."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 ## Overview
 
 Long conversations accumulate tokens across turns. Eventually the context window fills up, causing errors or degraded responses. Compaction solves this by automatically summarizing the conversation when token usage exceeds a threshold, then using that summary as the context for future turns.

package/docs/ai-chat/custom-agents.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Custom agents"
 description: "Build chat agents without chat.agent()'s managed lifecycle: register with chat.customAgent(), then drive turns with the createSession iterator or a hand-rolled loop."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 **A custom agent is a task you register with `chat.customAgent()` and drive yourself — either with the managed turn iterator from `chat.createSession()`, or with a fully hand-rolled loop over the raw chat primitives.** You give up `chat.agent()`'s lifecycle hooks and automatic continuation recovery; you gain inline control over every turn, and (at the lowest level) full control over the stream conversion.
 
 See the [comparison table](/ai-chat/backend) before dropping down. The frontend is unchanged either way: all levels speak the same wire protocol, so [`useTriggerChatTransport`](/ai-chat/frontend) points at a custom agent exactly like a `chat.agent()`.
@@ -179,6 +175,38 @@ for await (const turn of session) {
 }
 ```
 
+## Stopping generation
+
+The frontend stops a turn with [`transport.stopGeneration(chatId)`](/ai-chat/frontend#stop-generation), which writes a stop signal to the session's input stream. It aborts the current turn's generation but keeps the run alive, so the next message continues on the same session.
+
+`turn.signal` is a combined stop-and-cancel `AbortSignal`, fresh each turn. Pass it to `streamText` so the stop reaches the model, then let `turn.complete()` finish the turn:
+
+```ts trigger/my-chat.ts
+for await (const turn of session) {
+  const result = streamText({
+    model: anthropic("claude-sonnet-4-5"),
+    messages: turn.messages,
+    abortSignal: turn.signal, // fires on a user stop OR a run cancel
+    stopWhen: stepCountIs(15),
+  });
+
+  await turn.complete(result);
+
+  if (turn.stopped) {
+    // user stopped this turn — the partial response is already accumulated
+  }
+}
+```
+
+On a stop, `turn.complete()` cleans up the aborted parts of the partial response, accumulates it as its own assistant message, and writes turn-complete. The run does not end — the loop continues to the next turn.
+
+Read `turn.stopped` to tell a user stop from a full run cancel:
+
+- **User stop** (`transport.stopGeneration`): `turn.signal` aborts, `turn.stopped` is `true`, the partial response is accumulated, and the run stays alive for the next message.
+- **Run cancel** (cancelled, expired, or `maxDuration` exceeded): `turn.signal` aborts, `turn.stopped` is `false`, and `turn.complete()` returns without accumulating because the run is ending.
+
+A hand-rolled loop wires this itself with `chat.createStopSignal()` and `chat.cleanupAbortedParts()`. Two things `createSession` handles for you are easy to get wrong there — see the [hand-rolled loop checklist](#hand-rolled-loop-checklist).
+
 ## Hand-rolled loop with primitives
 
 For full control, skip `createSession` and compose the primitives directly:

package/docs/ai-chat/error-handling.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Error handling"
 description: "How errors flow through chat.agent — stream errors, hook errors, run failures — and how to recover."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 `chat.agent` errors fall into four layers, each with different recovery semantics. The default behavior is **conversation-preserving**: a thrown error in a hook or `run()` does not kill the chat. The current turn ends with an error chunk, and the agent waits for the user's next message.
 
 ## Error layers at a glance

package/docs/ai-chat/fast-starts.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Fast starts"
 description: "Two ways to cut first-turn TTFC: Preload eagerly triggers the run before the first message; Head Start runs step 1 in your warm server while the agent boots in parallel."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 The first turn of a brand-new conversation pays for the chat.agent run's cold start: dequeue, process boot, `onPreload` / `onChatStart` hooks, and only then the LLM call. Two features address this from different angles.
 
 ## Picking an approach
@@ -112,6 +108,8 @@ Head Start runs step 1's LLM call in your warm server process while the agent ru
 
 `chat.headStart` returns a standard [Web Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) handler — `(req: Request) => Promise<Response>` — so it slots into any runtime that speaks Web Fetch.
 
+Drive it one of two ways: wire the handler into the transport's [`headStart` option](#the-transport-option) so the browser's first message POSTs to it (the setup below), or call [`chat.startHeadStart`](#detached-head-start) from a backend that creates the chat and triggers the run in one request, then resumes on a separate page.
+
 **Verified runtimes:** Node 18+, Bun, Deno, Cloudflare Workers, Vercel (Node and Edge), Netlify (Functions and Edge). The handler uses only `fetch` and Web `ReadableStream` / `TransformStream` (no `node:*` imports), and the S2 streaming dependency picks the right transport for each runtime automatically (HTTP/2 on Node/Deno, HTTP/1.1 on Bun/Workers/browsers).
 
 **Compatible frameworks (native Web Fetch):** Next.js App Router, Hono, SvelteKit, Remix, React Router v7, TanStack Start, Astro, Nitro/Nuxt, Elysia. Mount the handler directly.
@@ -545,6 +543,10 @@ Head Start composes with [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemes
 
 Your hydrate hook shapes **model context**, not the transcript — dropping reasoning-only entries or unresolved tool rows from the returned chain is fine and does not affect what `onTurnComplete` persists or what the UI renders.
 
+#### With `prepareMessages`
+
+When the first turn's handover carries a pending tool call, the runtime reshapes it into a tool-approval round: the partial assistant gets a `tool-approval-request` and the chain ends with a `tool` message holding the matching `tool-approval-response`. The agent's `streamText` reads that trailing row to execute the handed-over call before step 2. `chat.agent` keeps that tail intact across your [`prepareMessages`](/ai-chat/reference#chatagentoptions) hook, so the common [prompt-caching](/ai-chat/prompt-caching) pattern of rolling a cache breakpoint onto the last message is safe on a resume turn (the breakpoint lands on the next user or assistant message instead). If you hand-roll a backend with [`chat.customAgent`](#chatcustomagent) or [`chat.createSession`](#chatcreatesession), preserve that trailing approval row yourself.
+
 ### Handover with custom agents
 
 The route handler is backend-agnostic: `agentId` can point at a `chat.agent`, a [`chat.customAgent`](/ai-chat/custom-agents), or a [`chat.createSession`](/ai-chat/custom-agents#managed-loop-chatcreatesession) loop. With `chat.agent` the handover is consumed for you (the steps above). The two hand-rolled backends consume it explicitly on turn 0.
@@ -655,6 +657,86 @@ Optional. When set, the FIRST message of a brand-new chat (no existing session s
 
 This is **not** a stock `useChat` `endpoint` — it's not the canonical request URL for every turn, just the first-turn shortcut.
 
+### Detached head start
+
+`chat.startHeadStart` runs the same head start as the [`chat.headStart` handler above](#setup); the difference is how step 1 reaches the browser. `chat.headStart` streams step 1 back over the live connection the browser opens when it sends the first message. `chat.startHeadStart` has no open browser connection to stream to, so it drains step 1 into the durable session stream and the browser **resumes** it when the chat page loads.
+
+Use it when there's no open connection at first-turn time, because the first message is captured outside the chat UI and the conversation renders on a separate page. A typical flow: a "new chat" form posts the prompt to your backend, which creates the chat row, starts the run with `chat.startHeadStart`, and returns a `chatId`; the browser then navigates to `/chats/{chatId}` and resumes. You still get the first-turn TTFC win; the browser picks step 1 up on resume instead of live.
+
+**1. Start the head start in your create endpoint.** Call `chat.startHeadStart`, keep `completion` alive past the response (`waitUntil` / Next.js `after`), and return the `chatId`.
+
+```ts app/api/chat/create/route.ts (your backend)
+import { chat } from "@trigger.dev/sdk/chat-server";
+import { streamText } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { after } from "next/server";
+// Schema-only tools; same bundle-isolation rule as chat.headStart.
+import { headStartTools } from "@/lib/chat-tools/schemas";
+
+export async function POST(req: Request) {
+  const { chatId, messages } = await req.json();
+  // Persist your own chat row + the first user message here.
+
+  const { completion } = await chat.startHeadStart({
+    agentId: "my-chat",
+    chatId, // session externalId; reuse it on the destination page
+    messages, // first-turn user history
+    run: async ({ chat: helper }) =>
+      streamText({
+        ...helper.toStreamTextOptions({ tools: headStartTools }),
+        model: anthropic("claude-sonnet-4-6"),
+        system: "You are a helpful assistant.",
+      }),
+  });
+
+  // Keep the function warm until step 1 drains and the handover dispatches.
+  after(completion);
+
+  return Response.json({ chatId });
+}
+```
+
+**2. Resume the chat on the destination page.** Set no `headStart` and no `startSession`: the run is already in flight, so the transport resumes `session.out` and replays step 1 (warm) then step 2+ (agent) under one assistant message.
+
+```tsx app/chats/[chatId]/page.tsx
+import { useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
+import { useChat } from "@ai-sdk/react";
+
+const transport = useTriggerChatTransport({
+  task: "my-chat",
+  accessToken: ({ chatId }) => mintChatAccessToken(chatId),
+});
+
+const { messages } = useChat({ id: chatId, transport, resume: true });
+```
+
+<Warning>
+  `completion` must run to completion, or step 1 never finishes draining and the turn stalls. On serverless, hand it to the platform's run-after-response primitive (`waitUntil`, Next.js `after`). On a long-lived server you can ignore it; it runs in the background.
+</Warning>
+
+<Warning>
+  If you hydrate the transport's session state yourself (the `sessions` option, e.g. so the same page can also resume already-stored chats from your session store), a head-started session is still mid-turn, so mark it `isStreaming: true`. A session hydrated as not streaming is treated as settled: the transport skips reconnecting to `session.out`, so the browser never sees the turn even though the run completed. The minimal example above sidesteps this by not hydrating a session at all (`resume: true` alone reconnects).
+</Warning>
+
+The `run` callback and bundle-isolation rule are the same as `chat.headStart`. Pass `metadata` to attach auth tokens or context to the run; it never reaches the browser. The cost over the transport-routed handler is one extra round trip: the create request, then the resume.
+
+#### The `chat.startHeadStart` API
+
+```ts
+chat.startHeadStart<TTools>({
+  agentId: string,                               // chat.agent / chat.customAgent / chat.createSession id
+  chatId: string,                                // session externalId; reuse on the destination page
+  messages: UIMessage[],                         // first-turn user history
+  run: (args: HeadStartRunArgs<TTools>) => Promise<StreamTextResult<any, any>>,
+  idleTimeoutInSeconds?: number,                 // how long the agent waits for the handover signal. Default: 60
+  triggerConfig?: Partial<SessionTriggerConfig>, // tags, queue, machine, …
+  apiClient?: ApiClientConfiguration,            // when the agent lives in another project/env
+  metadata?: Record<string, unknown>,            // merged into the run payload; never sent to the browser
+}): Promise<{ chatId: string; completion: Promise<void> }>
+```
+
+`completion` resolves once the head start finishes; `await` it or hand it to `waitUntil`. It rejects if the warm step or the dispatch fails.
+
 ### Limitations
 
 - **First turn only.** Step 2+ and turn 2+ run on the trigger side. There's no per-turn "head start every turn" mode — the win comes from amortizing agent boot across the LLM call once.

package/docs/ai-chat/frontend.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Frontend"
 description: "Transport setup, session management, client data, and frontend patterns for AI Chat."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 ## How the transport works
 
 Vanilla `useChat` expects an `api` URL — it POSTs the conversation to your own Next.js route handler, which terminates the stream. `useTriggerChatTransport` replaces that round-trip: instead of an `api` URL, you pass a custom [`ChatTransport`](https://ai-sdk.dev/docs/ai-sdk-ui/transport) that talks directly to the Trigger.dev cloud (or your self-hosted webapp) on behalf of `useChat`.

package/docs/ai-chat/how-it-works.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "How it works"
 description: "End-to-end mechanics of a chat.agent turn: the two durable channels per session, the long-lived task that reads and writes them, and how a chat survives refreshes, deploys, and idle gaps."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 This page explains how `chat.agent` is put together, what each piece does on a single turn, and how a chat survives across turns. It is not an API tour — for that, see [Backend](/ai-chat/backend), [Frontend](/ai-chat/frontend), and the [Reference](/ai-chat/reference). For the byte-level wire format, see [Client Protocol](/ai-chat/client-protocol).
 
 <Note>

package/docs/ai-chat/lifecycle-hooks.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Lifecycle hooks"
 description: "Hook into every stage of a chat agent's run: preload, turn start, turn complete, suspend, resume, and more."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 `chat.agent({ ... })` accepts a set of lifecycle hooks for persisting state, validating input, transforming messages, and reacting to suspension and resumption. They fire at well-defined points in the chat agent's lifetime.
 
 **Once per worker process (every fresh run boot):** `onBoot` → `onPreload` (preloaded runs only).

package/docs/ai-chat/mcp.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "MCP Server"
 description: "Chat with your agents from any AI coding tool using the Trigger.dev MCP server."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 The Trigger.dev MCP server includes tools for having conversations with your chat agents directly from AI coding tools like Claude Code, Cursor, Windsurf, and others. This lets your AI assistant interact with your agents without writing any code.
 
 ## Available tools

package/docs/ai-chat/overview.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Overview"
 description: "Durable multi-turn AI chats — one Trigger.dev task per conversation, surviving refreshes, deploys, and crashes."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 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

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

@@ -4,10 +4,6 @@ sidebarTitle: "Branching conversations"
 description: "Build ChatGPT-style conversation trees with edit, regenerate, undo, and branch switching using hydrateMessages, chat.history, and actions."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 Most chat UIs treat conversations as linear sequences. But real conversations branch — users edit previous messages, regenerate responses, undo exchanges, and explore alternative paths. This pattern shows how to build a branching conversation system using `hydrateMessages`, `chat.history`, and custom actions.
 
 ## Data model

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

@@ -4,10 +4,6 @@ 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."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 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()`:

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

@@ -4,10 +4,6 @@ sidebarTitle: "Database persistence"
 description: "Split conversation state and live session metadata across hooks — preload, turn start, turn complete — without tying the pattern to a specific ORM or schema."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 Durable chat runs can span **hours** and **many turns**. You usually want:
 
 1. **Conversation state** — full **`UIMessage[]`** (or equivalent) keyed by **`chatId`**, so reloads and history views work.

package/docs/ai-chat/patterns/human-in-the-loop.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Human-in-the-loop"
 description: "Pause the agent mid-response to ask the user a clarifying question, then resume with their answer."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 Some turns need to stop and ask the user something before they can finish — picking between options, confirming a destructive action, or clarifying an ambiguous request. The AI SDK calls this **human-in-the-loop** (HITL), and the building block is a tool with no `execute` function.
 
 When the LLM calls a tool that has no `execute`, `streamText` ends with the tool call still pending. The turn completes cleanly, the frontend renders UI to collect the answer, and when the user responds, a new turn resumes with the answer merged into the same assistant message.
@@ -20,7 +16,7 @@ Turn N:
   LLM streams text → calls askUser tool (no execute)
   streamText ends with tool-call in `input-available` state
   onTurnComplete fires (finishReason = "tool-calls")
-  Agent idle
+  Agent suspends (compute freed) — maxDuration does not tick while paused
 
 Frontend:
   Renders question + option buttons from tool input
@@ -36,6 +32,14 @@ Turn N+1:
 
 The AI SDK's `toUIMessageStream` automatically reuses the assistant message ID across the pause (we pass `originalMessages` internally), so `responseMessage` in the post-resume `onTurnComplete` is the **full merged message** — the original text, the completed tool call, and any follow-up content — not just the new parts.
 
+## Duration and cost while paused
+
+A pause doesn't hold compute. After the model calls a no-execute tool, the turn finishes and the run stays warm for `idleTimeoutInSeconds` (default 30s), then **suspends** and frees its compute, the same way [`wait.for`](/wait-for) does. The user's `addToolOutput` wakes it back up.
+
+Because the run is suspended while it waits, the human's thinking time is not billed and does **not** count against [`maxDuration`](/runs/max-duration). `maxDuration` measures active CPU time and excludes suspended waitpoint time, exactly like `wait.for`, so a user can take minutes, hours, or days to answer without the run hitting `maxDuration`. The only time that counts is each turn's actual compute plus the short warm window before each suspend.
+
+You don't need to raise `maxDuration` or end the run to support long human waits. How long a single suspended pause stays open is governed by the run's suspend timeout, not `maxDuration`; if a wait outlives it the run ends, and the next `addToolOutput` boots a fresh continuation that picks up the resolved tool result.
+
 ## Backend: define the tool
 
 A HITL tool has an `inputSchema` describing what the model can ask, but **no `execute` function**. When the LLM calls it, `streamText` returns control to your agent.

package/docs/ai-chat/patterns/large-payloads.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Large payloads"
 description: "Why a single chunk on the chat stream is capped at ~1 MiB, what error you'll see, and how to work around it with ID references."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 The realtime stream that backs `chat.agent` enforces a **per-record cap of ~1 MiB** (`1048576` bytes minus a small envelope reserve). Anything written through the chat output — auto-piped LLM chunks, `chat.response.write`, custom `writer.write` parts — counts as one record per chunk and is rejected if it crosses the cap.
 
 This is a platform-level limit and cannot be raised per project or per stream.

package/docs/ai-chat/patterns/oom-resilience.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "OOM resilience"
 description: "Recover from out-of-memory errors mid-turn by automatically retrying the failed turn on a larger machine — without losing the in-flight user message or re-processing completed turns."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 When a `chat.agent` turn runs out of memory, the worker process dies and everything in it is gone: the in-flight LLM call, the accumulator, any tool execution mid-flight. By default, Trigger.dev surfaces the OOM as a run failure.
 
 Setting `oomMachine` opts the agent into automatic recovery: the failed turn re-runs on a larger machine, picks up the user message that triggered the OOM (without re-processing earlier completed turns), and produces a normal response.

package/docs/ai-chat/patterns/persistence-and-replay.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Persistence and replay"
 description: "How chat.agent rebuilds conversation history at run boot — durable JSON snapshot in object storage plus session.out replay, with a hydrateMessages short-circuit for backend-owned history."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 `chat.agent` runs are processes — they boot, stream a turn, and either suspend (waiting for the next message) or exit. When the next message arrives at a session whose previous run already exited, a **fresh** run boots with no in-memory state. Something has to rebuild the conversation history before that turn can produce a coherent response.
 
 This page walks through the **snapshot + replay** model the runtime uses by default, and the [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) short-circuit that turns the whole thing off when the customer owns history.

package/docs/ai-chat/patterns/recovery-boot.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Recovery boot"
 description: "Recover from cancel-mid-stream, crashes, and OOM kills with full conversational context. The smart default Just Works; the onRecoveryBoot hook is the override path for advanced policies."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 When a `chat.agent` run dies in the middle of streaming a response — the user cancels, the worker OOMs, or an unhandled exception kills the process — the durable streams hold what was in flight. The next run boots as a continuation, reads both stream tails, and reconstructs a chain that preserves the partial response so any follow-up (`keep going`, `actually do X instead`, a new question) has full context.
 
 The behavior is automatic. The `onRecoveryBoot` hook is opt-in for policies that need something different.

package/docs/ai-chat/patterns/skills.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Agent Skills"
 description: "Ship reusable capabilities (folders with SKILL.md + scripts) that a chat agent discovers and invokes on demand."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 Agent skills are reusable capabilities you ship as folders — a `SKILL.md` describing when and how to use them, plus optional scripts, references, and assets. The chat agent sees a short description of each skill in its system prompt, loads the full instructions on demand via a `loadSkill` tool, and invokes the bundled scripts via `bash` — all without you wiring anything up manually.
 
 Built on the [AI SDK cookbook pattern](https://ai-sdk.dev/cookbook/guides/agent-skills). Works with any provider (OpenAI, Anthropic, Gemini, etc.) — not tied to Anthropic's server-side skills.

package/docs/ai-chat/patterns/sub-agents.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Sub-Agents"
 description: "Delegate work to durable sub-agents from within a parent agent's tool calls, with streaming preliminary results."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 Sub-agents let a parent agent delegate work to other agents running as durable Trigger.dev tasks. The sub-agent's response streams back through the parent as preliminary tool results, so the frontend sees the sub-agent working inside the parent's tool call card.
 
 This builds on the AI SDK's [async generator tool pattern](https://ai-sdk.dev/docs/agents/subagents) and Trigger.dev's [AgentChat](/ai-chat/server-chat) for server-side agent interaction.

package/docs/ai-chat/patterns/tool-result-auditing.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Tool result auditing"
 description: "Fire side effects exactly once per resolved tool call — audit logs, billing, notifications — using extractNewToolResults inside hydrateMessages or onTurnComplete."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 When a chat agent uses [tools](/ai-chat/tools) (especially [human-in-the-loop](/ai-chat/patterns/human-in-the-loop) tools that wait on `addToolOutput` from the frontend), you often need to fire side effects exactly once per resolved tool call:
 
 - **Audit logs** — record every tool result for compliance.

package/docs/ai-chat/patterns/trusted-edge-signals.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Trusted edge signals"
 description: "How to safely deliver server-trusted signals (bot scores, JA4, ASN, ReCAPTCHA verdicts) to a chat.agent run via an edge proxy."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 A common need for chat-style endpoints is to drive agent behavior from **server-trusted signals** that the browser cannot be allowed to declare itself — bot management scores, JA4 fingerprints, ASN, ReCAPTCHA verdicts, or any other anti-abuse data only the edge can see. The agent's [`clientData`](/ai-chat/reference#withclientdata) channel is the right delivery mechanism, but `clientData` set in the browser is by definition spoofable. The fix is to move the value population out of the browser and into a trusted edge proxy.
 
 This page documents the pattern using Cloudflare Workers as the proxy. The same shape applies to any edge layer (custom reverse proxy, Vercel Edge Middleware, AWS Lambda@Edge) — the trust comes from the deployment topology, not from Trigger.dev validating the source.

package/docs/ai-chat/patterns/version-upgrades.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Version upgrades"
 description: "Gracefully migrate suspended chat agents to a new deployment using chat.requestUpgrade() and the continuation mechanism."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 Chat agent runs are pinned to the worker version they started on. When you deploy a new version, suspended runs resume on the **old** code. If your deploy includes breaking changes (new tools, changed schemas, updated API contracts), this can cause issues.
 
 `chat.requestUpgrade()` lets the agent opt out of the current run so the transport triggers a new one on the latest version.

package/docs/ai-chat/pending-messages.mdx

@@ -4,10 +4,6 @@ sidebarTitle: "Pending Messages"
 description: "Inject user messages mid-execution to steer agents between tool-call steps."
 ---
 
-import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
-
-<RcBanner />
-
 ## Overview
 
 When an AI agent is executing tool calls, users may want to send a message that **steers the agent mid-execution** — adding context, correcting course, or refining the request without waiting for the response to finish.