@trigger.dev/sdk 4.8.0 → 4.8.2

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

@@ -1,33 +1,36 @@
 ---
 title: "Sub-Agents"
 sidebarTitle: "Sub-Agents"
-description: "Delegate work to durable sub-agents from within a parent agent's tool calls, with streaming preliminary results."
+description: "Delegate work to durable sub-agents from a parent agent's tool calls, and stream each sub-agent's work to the frontend as it happens."
 ---
 
-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.
+**Sub-agents let a parent agent delegate work to other agents running as durable Trigger.dev tasks, and `chat.forwardSubAgent` streams each sub-agent's reply to the frontend inside the parent's tool call.**
 
-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.
+Every chunk the sub-agent streams is written to the parent chat once, so the cost of streaming a sub-agent grows with the length of its reply. When the sub-agent finishes, its final message becomes the tool's output and persists with the parent's history.
+
+This builds on Trigger.dev's [AgentChat](/ai-chat/server-chat) for server-side agent interaction.
 
 ## How it works
 
-1. The parent LLM calls a tool (e.g., `researchAgent`)
-2. The tool's `execute` is an `async function*` (async generator)
-3. Inside, it creates an `AgentChat` and sends a message to the sub-agent
-4. `yield* stream.messages()` streams each accumulated `UIMessage` snapshot as a preliminary tool result
-5. The frontend renders the sub-agent's response building up inside the parent's tool card
-6. `toModelOutput` compresses the full output into a summary for the parent LLM
+1. The parent LLM calls a tool (for example `research`).
+2. The tool's `execute` creates an `AgentChat` and sends a message to the sub-agent.
+3. `chat.forwardSubAgent(stream, { toolCallId })` writes each sub-agent chunk to the parent chat as a transient `data-subagent` part.
+4. The frontend rebuilds the sub-agent's message from those chunks with `useSubAgentMessages` and renders it inside the parent's tool card.
+5. When the sub-agent finishes, `forwardSubAgent` resolves with its final `UIMessage`, which becomes the tool's output.
+6. `toModelOutput` compresses that output into a summary for the parent LLM.
 
 ```
 Parent LLM
   │
-  ├─ calls researchAgent tool
+  ├─ calls research tool
   │    │
   │    ├─ AgentChat triggers sub-agent run
-  │    ├─ sub-agent streams response (text, tool calls, etc.)
-  │    ├─ yield* sends UIMessage snapshots as preliminary results
-  │    └─ toModelOutput compresses for parent LLM
+  │    ├─ sub-agent streams its reply (text, tool calls, etc.)
+  │    ├─ forwardSubAgent writes each chunk once as a transient data-subagent part
+  │    ├─ the tool returns the sub-agent's final UIMessage
+  │    └─ toModelOutput compresses it for the parent LLM
   │
-  └─ parent LLM reads compressed summary, continues reasoning
+  └─ parent LLM reads the summary and continues
 ```
 
 ## Single-turn sub-agent
@@ -35,7 +38,8 @@ Parent LLM
 The simplest pattern: one tool call, one sub-agent turn, conversation closes.
 
 ```ts
-import { tool, stepCountIs } from "ai";
+import { tool } from "ai";
+import { chat } from "@trigger.dev/sdk/ai";
 import { AgentChat } from "@trigger.dev/sdk/chat";
 import { z } from "zod";
 import type { prReviewAgent } from "./trigger/pr-review";
@@ -46,19 +50,20 @@ const prReviewTool = tool({
     prNumber: z.number().describe("The PR number to review"),
     repo: z.string().describe("The GitHub repo URL"),
   }),
-  execute: async function* ({ prNumber, repo }, { abortSignal }) {
-    const chat = new AgentChat<typeof prReviewAgent>({
+  execute: async ({ prNumber, repo }, { toolCallId, abortSignal }) => {
+    const reviewer = new AgentChat<typeof prReviewAgent>({
       agent: "pr-review",
       id: `review-${prNumber}`,
       clientData: { userId: "parent-agent", githubUrl: repo },
     });
 
-    const stream = await chat.sendMessage(`Review PR #${prNumber}`, { abortSignal });
-
-    // Each yield sends a UIMessage snapshot to the frontend
-    yield* stream.messages();
-
-    await chat.close();
+    try {
+      const stream = await reviewer.sendMessage(`Review PR #${prNumber}`, { abortSignal });
+      // Streams the review to the frontend and resolves with the final message
+      return await chat.forwardSubAgent(stream, { toolCallId });
+    } finally {
+      await reviewer.close();
+    }
   },
   // The parent LLM only sees this compressed summary
   toModelOutput: ({ output: message }) => {
@@ -70,26 +75,42 @@ const prReviewTool = tool({
 });
 ```
 
-Use this tool in a parent agent's `streamText` call:
+`forwardSubAgent` needs the parent chat to write to, so call it from a tool that runs inside a `chat.agent` or `chat.customAgent` run. [Combining with chat.agent()](#combining-with-chat-agent) below shows the agent side.
 
-```ts
-import { streamText } from "ai";
-import { anthropic } from "@ai-sdk/anthropic";
+## Render sub-agents in the frontend
 
-const result = streamText({
-  model: anthropic("claude-sonnet-4-6"),
-  tools: { prReview: prReviewTool },
-  prompt: "Review PR #42 on triggerdotdev/trigger.dev",
-  stopWhen: stepCountIs(15),
-});
+While the sub-agent runs, the parent's tool part has no output yet. `useSubAgentMessages` collects the forwarded chunks and gives you the sub-agent's message so far for each tool call:
+
+```tsx app/components/chat.tsx
+import { useChat } from "@ai-sdk/react";
+import type { TriggerChatTransport } from "@trigger.dev/sdk/chat";
+import { useSubAgentMessages } from "@trigger.dev/sdk/chat/react";
+import { ReviewCard } from "./review-card";
+
+export function Chat({ transport }: { transport: TriggerChatTransport }) {
+  const subAgents = useSubAgentMessages();
+  const { messages } = useChat({ transport, onData: subAgents.onData });
+
+  return messages.map((message) =>
+    message.parts.map((part) => {
+      if (part.type !== "tool-prReview") return null;
+      // Live while the sub-agent runs, the tool output once it finishes
+      const review = subAgents.get(part.toolCallId) ?? part.output;
+      return <ReviewCard key={part.toolCallId} message={review} />;
+    })
+  );
+}
 ```
 
+The hook rebuilds each message at most once per `throttleMs` (100ms by default), so a long reply costs a bounded number of rebuilds. After a reload mid-turn, the transport replays the current turn and the hook rebuilds the sub-agent's message from it; batches it has already seen are skipped. Outside React, `createSubAgentMessages()` from `@trigger.dev/sdk/chat` does the same job.
+
 ## Multi-turn sub-agent (LLM-driven)
 
 The parent LLM drives a persistent conversation with a sub-agent across multiple tool calls. Each call with the same `conversationId` hits the same durable agent run.
 
 ```ts
 import { tool } from "ai";
+import { chat } from "@trigger.dev/sdk/ai";
 import { AgentChat } from "@trigger.dev/sdk/chat";
 import { z } from "zod";
 
@@ -106,7 +127,7 @@ const researchTool = tool({
       .describe("Unique ID for this research thread. Reuse to continue."),
     message: z.string().describe("Your message to the research agent"),
   }),
-  execute: async function* ({ conversationId, message }, { abortSignal }) {
+  execute: async ({ conversationId, message }, { toolCallId, abortSignal }) => {
     let agent = subAgents.get(conversationId);
     if (!agent) {
       agent = new AgentChat({
@@ -117,7 +138,7 @@ const researchTool = tool({
     }
 
     const stream = await agent.sendMessage(message, { abortSignal });
-    yield* stream.messages();
+    return await chat.forwardSubAgent(stream, { toolCallId });
   },
   toModelOutput: ({ output: message }) => {
     const lastText = message?.parts?.findLast(
@@ -209,13 +230,19 @@ For the multi-turn pattern, the parent should clean up sub-agents when it exits
 
 ## What the frontend sees
 
-Each `yield` from `stream.messages()` sends a complete `UIMessage` containing all the sub-agent's parts accumulated so far. The AI SDK delivers these as `tool-output-available` chunks with `preliminary: true`.
+While the sub-agent runs, the parent's tool part stays in `state: "input-available"`, and the parent stream carries transient `data-subagent` parts. Each one holds a batch of the sub-agent's chunks, tagged with the parent's `toolCallId` and a sequence number:
 
-The frontend renders the tool part with:
-- `state: "output-available"` and `preliminary: true` while streaming
-- `state: "output-available"` and `preliminary: false` (or absent) when done
+```ts
+{
+  type: "data-subagent",
+  transient: true,
+  data: { toolCallId: "toolu_01...", seq: 3, chunks: [/* UIMessageChunk[] */] },
+}
+```
+
+Transient parts reach `useChat`'s `onData` and are not added to `message.parts`, so they never persist. When the sub-agent finishes, the tool part moves to `state: "output-available"` with the full `UIMessage` as its output: text, the sub-agent's own tool calls and results, reasoning, and so on. That output is what reloaded history renders.
 
-The tool output contains the full `UIMessage` with nested parts — text, the sub-agent's own tool calls and results, reasoning, etc.
+If the user stops the parent turn while a sub-agent is running, the tool call ends without an output, the same as any stopped tool. The sub-agent's work up to that point was only ever in the transient parts, so neither the parent's history nor the next turn's model context includes it.
 
 ### Controlling what the parent LLM sees
 
@@ -238,30 +265,27 @@ This is important for token efficiency: the sub-agent might use 100K tokens expl
   `toModelOutput` only runs when the SDK has your tools at conversion time. On a multi-turn parent, the SDK re-converts the persisted history at the start of each turn, so you must declare the sub-agent tool on the agent config (`chat.agent({ tools })`) for the compression to survive. Without it, the summary holds on turn 1 but turn 2 onward re-ingests the full sub-agent output. In a `chat.customAgent` loop you own the conversion, so pass the tools to `convertToModelMessages(uiMessages, { tools })` yourself. See [Tools: toModelOutput across turns](/ai-chat/tools#tomodeloutput-across-turns).
 </Warning>
 
-## ChatStream.messages()
+## Snapshots with `stream.messages()`
 
-The `messages()` method on `ChatStream` wraps the AI SDK's `readUIMessageStream`. It reads the raw `UIMessageChunk` stream and yields complete `UIMessage` snapshots — each containing all parts received so far.
+`ChatStream.messages()` wraps the AI SDK's `readUIMessageStream` and yields the whole accumulated `UIMessage` after almost every chunk. Yielding those snapshots from an `async function*` tool (`yield* stream.messages()`) turns each one into a preliminary tool result, which streams the sub-agent too, but every snapshot repeats the whole message so far. The bytes written grow with the square of the reply length:
 
-```ts
-const stream = await chat.sendMessage("Research this topic");
+| Sub-agent reply | `yield* stream.messages()` | `chat.forwardSubAgent` |
+| --- | --- | --- |
+| 500 text deltas, no tools | 1.1 MB | 0.07 MB |
+| 5 tool results of 20 KB, then 2,000 deltas | 218 MB | 0.47 MB |
+| 10 tool results of 50 KB, then 4,000 deltas | 2.1 GB | 1.5 MB |
+
+Every one of those bytes goes to the chat's stream storage and to each browser watching the chat. Use `forwardSubAgent` for sub-agents, and keep `stream.messages()` for reading a short reply in server code:
 
-// Each yield is a complete UIMessage with all accumulated parts
+```ts
+const stream = await agent.sendMessage("Summarize this ticket in one sentence");
 for await (const message of stream.messages()) {
   console.log(message.parts.length, "parts so far");
 }
 ```
 
-For the sub-agent pattern, use `yield*` to delegate all yields to the parent tool's generator:
-
-```ts
-execute: async function* ({ topic }, { abortSignal }) {
-  const stream = await chat.sendMessage(topic, { abortSignal });
-  yield* stream.messages();
-},
-```
-
 <Tip>
-  `stream.messages()` consumes the stream. You can't also call `stream.text()` or iterate over chunks on the same stream. Pick one consumption mode.
+  A `ChatStream` can be consumed once: by `forwardSubAgent`, `stream.messages()`, `stream.text()`, or by iterating its chunks. Pick one.
 </Tip>
 
 ## Combining with chat.agent()
@@ -275,7 +299,7 @@ const tools = { research: researchTool };
 export const myAgent = chat.agent({
   id: "orchestrator",
   tools, // declare here so toModelOutput survives across turns
-  run: async ({ messages, tools, stopSignal }) => {
+  run: async ({ messages, tools, stopSignal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-6"),
       messages,
@@ -345,6 +369,8 @@ const research = tool({
 });
 ```
 
+Keep a part you update this way small. The frontend replaces the part on each write, but the chat stream stores every version, so writing a growing payload under one `id` (a full message history, say) stores every copy. Mark progress updates that don't need to persist with `transient: true`, and use `chat.forwardSubAgent` when the thing you are streaming is a sub-agent's reply.
+
 On the frontend, render the custom data part:
 
 ```tsx

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

@@ -100,7 +100,7 @@ On the agent side, declare which versions the current code supports:
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText } from "ai";
+
 import { anthropic } from "@ai-sdk/anthropic";
 
 // The set of frontend protocol versions this agent code supports.
@@ -121,7 +121,7 @@ export const myChat = chat
         chat.requestUpgrade();
       }
     },
-    run: async ({ messages, signal }) => {
+    run: async ({ messages, signal, streamText }) => {
       return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
     },
   });
@@ -183,7 +183,7 @@ export const myChat = chat
         chat.requestUpgrade();
       }
     },
-    run: async ({ messages, signal }) => {
+    run: async ({ messages, signal, streamText }) => {
       return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
     },
   });

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

@@ -132,6 +132,8 @@ When messages are injected, the SDK automatically writes a `data-pending-message
 - Remove them from the pending overlay
 - Render them inline at the injection point in the assistant response
 
+Background injections appear as a different data part (`data-background-injected`) that `usePendingMessages` ignores. It is not a user message.
+
 A "pending message injected" span also appears in the run trace.
 
 ## Backend: chat.createSession

package/docs/ai-chat/quick-start.mdx

@@ -159,5 +159,5 @@ Run your frontend and `pnpm exec trigger dev`, then send a message. You should s
 - [Frontend](/ai-chat/frontend) — Session management, client data, reconnection
 - [Types](/ai-chat/types) — `chat.withUIMessage`, `InferChatUIMessage`, and related typing
 - [`chat.local`](/ai-chat/chat-local) — Per-run typed state across hooks, run, tools, subtasks
-- [Sub-agents pattern](/ai-chat/patterns/sub-agents) — Subtask-as-tool, `target: "root"` streaming, `ai.toolExecute` helpers
+- [Sub-agents pattern](/ai-chat/patterns/sub-agents): `chat.forwardSubAgent`, subtask-as-tool, `target: "root"` streaming, `ai.toolExecute` helpers
 - [Background injection](/ai-chat/background-injection) — `chat.inject()` and `chat.defer()` for between-turn work

package/docs/ai-chat/reference.mdx

@@ -565,6 +565,7 @@ All methods available on the `chat` object from `@trigger.dev/sdk/ai`.
 | `chat.isStopped()`                          | Check if the current turn was stopped by the user                                                                            |
 | `chat.cleanupAbortedParts(message)`         | Remove incomplete parts from a stopped response message                                                                      |
 | `chat.response.write(chunk)`                | Write a data part that streams to the frontend AND persists in `onTurnComplete`'s `responseMessage`                          |
+| `chat.forwardSubAgent(stream, { toolCallId, flushIntervalMs? })` | Stream a sub-agent's reply through a parent tool call as transient `data-subagent` parts, and resolve with its final `UIMessage`. Call it inside a tool's `execute`. See [Sub-agents](/ai-chat/patterns/sub-agents) |
 | `chat.stream`                               | Raw chat output stream — use `.writer()`, `.pipe()`, `.append()`, `.read()`. Chunks are NOT accumulated into the response.   |
 | `chat.history.all()`                        | Read the current accumulated UI messages (returns a copy). See [chat.history](/ai-chat/backend#chat-history)                  |
 | `chat.history.set(messages)`                | Replace all accumulated messages (same as `chat.setMessages()`)                                                              |
@@ -837,6 +838,27 @@ const transport = useTriggerChatTransport({
 
 No-op when `BroadcastChannel` is unavailable (SSR, Node.js). See [Multi-tab coordination](/ai-chat/frontend#multi-tab-coordination).
 
+## useSubAgentMessages
+
+React hook that rebuilds sub-agents streamed with [`chat.forwardSubAgent`](/ai-chat/patterns/sub-agents) while they run. Import from `@trigger.dev/sdk/chat/react`.
+
+```tsx
+import { useSubAgentMessages } from "@trigger.dev/sdk/chat/react";
+
+const subAgents = useSubAgentMessages();
+const { messages } = useChat({ transport, onData: subAgents.onData });
+
+const message = subAgents.get(part.toolCallId) ?? part.output;
+```
+
+| Option       | Type     | Default | Description                                                              |
+| ------------ | -------- | ------- | ------------------------------------------------------------------------ |
+| `throttleMs` | `number` | `100`   | Minimum time between rebuilds of a sub-agent's message while chunks stream in. |
+
+**Returns:** `{ onData, get }`. Pass `onData` to `useChat`. `get(toolCallId)` returns the sub-agent's `UIMessage` so far, or `undefined` before its first chunk. Batches a resumed stream replays are skipped, so a reload mid-turn does not duplicate content.
+
+`createSubAgentMessages({ throttleMs?, onChange? })` from `@trigger.dev/sdk/chat` is the same store without React: call its `onData` with every data part you receive, read with `get(toolCallId)`, and `dispose()` when you are done.
+
 ### Trigger configuration
 
 Trigger config (machine, queue, tags, maxAttempts, idleTimeoutInSeconds) lives server-side in `chat.createStartSessionAction(taskId, options?)`. The transport doesn't accept these options directly — pass them when wrapping the action:

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

@@ -161,21 +161,25 @@ export async function POST(req: Request) {
 
 ## Sub-agent tool pattern
 
-`AgentChat` can be used inside an AI SDK tool to delegate work to a durable sub-agent. The sub-agent's response streams as preliminary tool results:
+`AgentChat` can be used inside an AI SDK tool to delegate work to a durable sub-agent. `chat.forwardSubAgent` streams the sub-agent's reply to the frontend inside the tool call and resolves with its final message:
 
 ```ts
 import { tool } from "ai";
+import { chat } from "@trigger.dev/sdk/ai";
 import { AgentChat } from "@trigger.dev/sdk/chat";
 import { z } from "zod";
 
 const researchTool = tool({
   description: "Delegate research to a specialist agent.",
   inputSchema: z.object({ topic: z.string() }),
-  execute: async function* ({ topic }, { abortSignal }) {
-    const chat = new AgentChat({ agent: "research-agent" });
-    const stream = await chat.sendMessage(topic, { abortSignal });
-    yield* stream.messages();
-    await chat.close();
+  execute: async ({ topic }, { toolCallId, abortSignal }) => {
+    const researcher = new AgentChat({ agent: "research-agent" });
+    try {
+      const stream = await researcher.sendMessage(topic, { abortSignal });
+      return await chat.forwardSubAgent(stream, { toolCallId });
+    } finally {
+      await researcher.close();
+    }
   },
   toModelOutput: ({ output: message }) => {
     const lastText = message?.parts?.findLast(
@@ -254,6 +258,6 @@ const stream = await chat.reconnect();
 |---|---|---|
 | `text()` | `Promise<string>` | Consume stream, return accumulated text |
 | `result()` | `Promise<ChatStreamResult>` | Consume stream, return `{ text, toolCalls, toolResults }` |
-| `messages()` | `AsyncGenerator<UIMessage>` | Yield accumulated UIMessage snapshots (sub-agent pattern) |
+| `messages()` | `AsyncGenerator<UIMessage>` | Yield the accumulated UIMessage after each chunk. For sub-agents, pass the stream to `chat.forwardSubAgent` instead |
 | `[Symbol.asyncIterator]` | `UIMessageChunk` | Iterate over typed stream chunks |
 | `.stream` | `ReadableStream<UIMessageChunk>` | Raw stream for AI SDK utilities |

package/docs/ai-chat/side-channels.mdx

@@ -38,12 +38,12 @@ Inside a `chat.agent` run, `chat.channel(...)` opens a channel on the current ru
 
 ```ts /trigger/browser-agent.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText } from "ai";
+
 import { screenshots } from "./channels";
 
 export const browserAgent = chat.agent({
   id: "browser-agent",
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     const frames = chat.channel(screenshots);
 
     frames.in.on((control) => setPaused(control.paused)); // control: ViewportControl

package/docs/ai-chat/types.mdx

@@ -56,7 +56,7 @@ Call `withUIMessage` **once**, then chain `.agent({ ... })` instead of `chat.age
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, tool } from "ai";
+import { tool } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 import type { MyChatUIMessage } from "./my-chat-types";
@@ -90,7 +90,7 @@ export const myChat = chat
         data: { status: "preparing" },
       });
     },
-    run: async ({ messages, tools, signal }) => {
+    run: async ({ messages, tools, signal, streamText }) => {
       // `tools` is myTools, typed, handed back on the payload
       return streamText({
         model: anthropic("claude-sonnet-4-5"),
@@ -156,7 +156,7 @@ export const myChat = chat
       // clientData is typed as { userId: string; model?: string }
       await initUser(clientData.userId);
     },
-    run: async ({ messages, clientData, signal }) => {
+    run: async ({ messages, clientData, signal, streamText }) => {
       return streamText({
         model: getModel(clientData.model),
         messages,
@@ -193,7 +193,7 @@ export const myChat = chat
   })
   .agent({
     id: "my-chat",
-    run: async ({ messages, signal }) => {
+    run: async ({ messages, signal, streamText }) => {
       return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
     },
   });
@@ -218,7 +218,7 @@ chat
       // Runs second — task-specific logic
       await createChatRecord(event.chatId);
     },
-    run: async ({ messages, signal }) => {
+    run: async ({ messages, signal, streamText }) => {
       return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
     },
   });

package/docs/config/config-file.mdx

@@ -329,7 +329,7 @@ After each call we restore the few attributes we use to link a span to its run,
 
 If you don't set a `runtime`, your tasks run on the current Node.js LTS. Setting `runtime: "node"` does the same thing — see the Node.js versions section below to pin a specific version instead.
 
-We currently only officially support the `node` runtime, but you can try our experimental `bun` runtime by setting the `runtime` option in your config file:
+We currently only officially support the `node` runtime, but you can try our experimental Bun runtimes by setting the `runtime` option in your config file:
 
 ```ts trigger.config.ts
 import { defineConfig } from "@trigger.dev/sdk";
@@ -341,7 +341,7 @@ export default defineConfig({
 });
 ```
 
-See our [Bun guide](/guides/frameworks/bun) for more information.
+`bun` runs on Bun 1.3 with a Node.js binary alongside it. `bun-1.4` runs on a Bun-only image with no Node.js binary. See our [Bun guide](/guides/frameworks/bun) for the differences.
 
 ### Node.js versions
 

package/docs/database-connections.mdx

@@ -176,13 +176,13 @@ A chat agent runs one long-lived worker per conversation and suspends between me
 
 ```ts /trigger/chat.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText } from "ai";
+
 import { openai } from "@ai-sdk/openai";
 import { prisma } from "@/lib/db";
 
 export const myChat = chat.agent({
   id: "my-chat",
-  run: async ({ messages, clientData, signal }) => {
+  run: async ({ messages, clientData, signal, streamText }) => {
     const user = await prisma.user.findUnique({ where: { id: clientData.userId } });
     // The connection is back in the pool before the model stream starts.
     return streamText({

package/docs/how-to-reduce-your-spend.mdx

@@ -190,6 +190,10 @@ export const waitpointTask = task({
 
 Waiting saves you compute, but it doesn't always free up concurrency — see [Wait](/wait).
 
+## Filter webhooks before they start runs
+
+Give each [webhook](/webhooks/overview) subscriber a [filter](/webhooks/filters) so it only runs for the events it handles. A delivery that no subscriber's filter matches starts no run for any subscriber, so you aren't charged for it. Filters only apply to subscribers: a run [waiting](/webhooks/waiters) for a matching webhook still resumes and uses compute. Receiving webhooks has no separate charge.
+
 ## Use debounce to consolidate multiple triggers
 
 When a task might be triggered multiple times in quick succession, use debounce to consolidate them into a single run. This is useful for document indexing, webhook aggregation, cache invalidation, and real-time sync scenarios.