@trigger.dev/sdk 4.8.1 → 4.8.2

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/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/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.

package/docs/limits.mdx

@@ -178,6 +178,47 @@ All of an environment's endpoints also share a per-environment limit, counted in
 | Pro          | 3,000 every 10 sec     |
 | Enterprise   | Set per organization   |
 
+## Webhook waiters
+
+A [waiter](/webhooks/waiters) is a run paused until a matching webhook arrives. The per-endpoint limit is also the most waiting runs one delivery can resume.
+
+| Pricing tier | Live waiters per environment | Live waiters per endpoint |
+| :----------- | :--------------------------- | :------------------------ |
+| Free         | 500                          | 100                       |
+| Hobby        | 2,000                        | 1,000                     |
+| Pro          | 25,000                       | 10,000                    |
+| Enterprise   | Set per organization         | Set per organization      |
+
+A waiter can wait for up to 90 days.
+
+## Webhook processing concurrency
+
+This limit controls how many webhook deliveries and waiter resumes are processed at once per environment. Additional deliveries wait their turn. It is not a limit on the runs those deliveries start, which use your normal [concurrency limits](#concurrency-limits).
+
+| Pricing tier | Limit                    |
+| :----------- | :----------------------- |
+| Free         | 5 concurrent deliveries  |
+| Hobby        | 10 concurrent deliveries |
+| Pro          | 50 concurrent deliveries |
+| Enterprise   | Set per organization     |
+
+## Webhook delivery retention
+
+How long [deliveries](/webhooks/deliveries) stay visible in the dashboard and the API.
+
+| Pricing tier | Limit                        |
+| :----------- | :--------------------------- |
+| Free         | 3 days                       |
+| Hobby        | 7 days                       |
+| Pro          | 30 days                      |
+| Enterprise   | 90, 180 or 365 days          |
+
+By default, deliveries are stored for at least 30 days, so upgrading your plan shows older deliveries that are still stored. An organization can ask us to store deliveries only for its retention period instead. Deliveries past that period are then deleted and can't be shown again after an upgrade.
+
+## Webhook subscribers
+
+An endpoint can have up to 25 subscribers (tasks, agent sessions and channels) on every plan.
+
 ## Log retention
 
 | Pricing tier | Limit   |

package/docs/observability/query.mdx

@@ -57,6 +57,35 @@ ORDER BY minute
 LIMIT 1000
 ```
 
+#### Platform limit metrics
+
+The `metrics` table also records how close your environment is to platform limits. These are the metrics behind [Limits alerts](/troubleshooting-alerts#limits-alerts):
+
+| Metric                          | What it shows                                    |
+| ------------------------------- | ------------------------------------------------ |
+| `queue.size.queued`             | Runs currently queued in the environment         |
+| `queue.size.limit`              | The environment's maximum queued runs            |
+| `webhook.processing.in_flight`  | Webhooks being processed now                     |
+| `webhook.processing.limit`      | The webhook processing concurrency limit         |
+| `webhook.ingress.denied`        | Incoming webhooks rejected by a rate limit       |
+| `webhook.ingress.remaining_min` | The lowest remaining rate limit allowance seen   |
+| `webhook.ingress.limit.tokens`  | The rate limit's allowance per window            |
+| `webhook.waiters.live`          | Runs currently waiting for a webhook             |
+| `webhook.waiters.limit.env`     | The environment's maximum webhook waiters        |
+| `webhook.waiters.refused`       | New webhook waiters that were refused            |
+
+```sql
+SELECT
+  timeBucket(),
+  maxIf(metric_value, metric_name = 'queue.size.queued') AS queued,
+  maxIf(metric_value, metric_name = 'queue.size.limit') AS queue_limit
+FROM metrics
+WHERE metric_name LIKE 'queue.size.%'
+GROUP BY timeBucket
+ORDER BY timeBucket
+LIMIT 1000
+```
+
 ### `prettyFormat()`
 
 Use `prettyFormat()` to format metric values for display:

package/docs/self-hosting/docker.mdx

@@ -389,6 +389,68 @@ EVENT_REPOSITORY_DEFAULT_STORE=clickhouse_v2
 
 This only affects new runs; existing runs continue to read from wherever their events were originally stored.
 
+### Move from the legacy clickhouse store
+
+The legacy `clickhouse` store (the `task_events_v1` table) is retired. If you set `EVENT_REPOSITORY_DEFAULT_STORE=clickhouse`, your webapp now writes and reads `clickhouse_v2` instead and logs a warning at startup. Events recorded in `task_events_v1` stay there but no longer show in the dashboard until you copy them over.
+
+<Steps titleSize="h4">
+  <Step title="Switch to clickhouse_v2">
+    Switch the store in your `.env` and restart the webapp:
+
+    ```bash .env
+    EVENT_REPOSITORY_DEFAULT_STORE=clickhouse_v2
+    ```
+  </Step>
+  <Step title="List the days to copy">
+    List the days that hold legacy events. The bundled ClickHouse container already sets `CLICKHOUSE_USER` and `CLICKHOUSE_PASSWORD`, and `clickhouse-client` reads them, so no credentials are needed:
+
+    ```bash
+    docker compose exec clickhouse clickhouse-client -q \
+      "SELECT toDate(start_time) AS day, count() FROM trigger_dev.task_events_v1 GROUP BY day ORDER BY day"
+    ```
+  </Step>
+  <Step title="Save the copy query">
+    Save the copy query as `copy-task-events-v1.sql`. It copies one day and skips events already in `task_events_v2`, so it's safe to run again if it's interrupted:
+
+    ```sql copy-task-events-v1.sql
+    INSERT INTO trigger_dev.task_events_v2
+      (environment_id, organization_id, project_id, task_identifier, run_id, start_time,
+       trace_id, span_id, parent_span_id, message, kind, status, attributes_text,
+       metadata, duration, expires_at, inserted_at)
+    SELECT
+      environment_id, organization_id, project_id, task_identifier, run_id, start_time,
+      trace_id, span_id, parent_span_id, message, kind, status, attributes_text,
+      metadata, duration, expires_at, toDateTime64(start_time, 3)
+    FROM trigger_dev.task_events_v1
+    WHERE toDate(start_time) = {day:Date}
+      AND (trace_id, span_id, start_time, kind, status) NOT IN (
+        SELECT trace_id, span_id, start_time, kind, status
+        FROM trigger_dev.task_events_v2
+        WHERE inserted_at >= {day:Date} AND inserted_at < {day:Date} + INTERVAL 8 DAY
+          AND toDate(start_time) = {day:Date}
+      );
+    ```
+  </Step>
+  <Step title="Copy each day">
+    Run it once per day from step 2, oldest first:
+
+    ```bash
+    docker compose exec -T clickhouse clickhouse-client --param_day=2026-08-01 \
+      --multiquery < copy-task-events-v1.sql
+    ```
+  </Step>
+  <Step title="Check a copied run">
+    Open a run from one of the copied days and check its trace and logs show.
+  </Step>
+</Steps>
+
+Copying one day at a time keeps memory use bounded on large tables. A future release removes `task_events_v1`, so copy anything you want to keep before then.
+
+<Note>
+  `EVENT_REPOSITORY_V1_REROUTE_ENABLED=0` keeps the legacy store while you migrate. It's
+  temporary and will be removed in a future release.
+</Note>
+
 ## Realtime streams
 
 Realtime streams power AI-agent token streaming and run streams. They default to **v2**, backed by the bundled `s2` service — [s2-lite](https://s2.dev), the open-source, self-hostable S2 server. It stores stream data in a persistent volume and is preconfigured in the webapp compose file, so no setup is required.

package/docs/self-hosting/env/supervisor.mdx

@@ -33,6 +33,9 @@ mode: "wide"
 | `TRIGGER_DEQUEUE_INTERVAL_MS`               | No       | 250         | Dequeue interval (ms).                                      |
 | `TRIGGER_DEQUEUE_IDLE_INTERVAL_MS`          | No       | 1000 (1s)   | Dequeue idle interval (ms).                                 |
 | `TRIGGER_DEQUEUE_MAX_CONSUMER_COUNT`        | No       | 1           | Max dequeue consumer count.                                 |
+| `RELEASE_UNSTARTED_RUNS_ENABLED`            | No       | false       | Set to true to requeue a run straight away when its container or pod can't be created, rather than after the pending execution timeout. Limited by `RUN_RELEASES_PER_MINUTE`. |
+| `RELEASE_FAILED_POD_RUNS_ENABLED`           | No       | false       | Set to true to requeue a run straight away when its pod fails before the run starts, rather than after the pending execution timeout. Independent of `RELEASE_UNSTARTED_RUNS_ENABLED`; the two share `RUN_RELEASES_PER_MINUTE`. Needs `FAILED_POD_HANDLER_ENABLED`. |
+| `RUN_RELEASES_PER_MINUTE`                   | No       | 5           | Different runs released within a minute, by either release flag, past which every release waits for the timeout again until a slot frees, a run already released included. 0 withholds every release; blank means the default. |
 | **Docker settings**                         |          |             |                                                             |
 | `DOCKER_API_VERSION`                        | No       | v1.41       | Docker API version. You should probably not touch this.     |
 | `DOCKER_STRIP_IMAGE_DIGEST`                 | No       | true        | Strip image digest in Docker. Turning off can cause issues. |

package/docs/self-hosting/env/webapp.mdx

@@ -88,6 +88,11 @@ mode: "wide"
 | `API_RATE_LIMIT_METRICS_MAX_ENTRIES`             | No       | 10000                 | Cap on distinct (environment, bucket) entries held between flushes.                                                |
 | `API_RATE_LIMIT_METRICS_WAIT_FOR_ASYNC_INSERT`   | No       | 0                     | Wait for ClickHouse to write each async insert of API rate limit metrics, surfacing write failures.                |
 | `API_RATE_LIMIT_METRICS_INSERT_BUSY_TIMEOUT_MS`  | No       | 10000                 | How long ClickHouse buffers API rate limit metric inserts before writing a part.                                   |
+| `WEBHOOK_METRICS_FLUSH_INTERVAL_MS`              | No       | 10000                 | How often aggregated webhook limit metrics are flushed to ClickHouse.                                              |
+| `WEBHOOK_METRICS_MAX_ENTRIES`                    | No       | 10000                 | Cap on distinct (environment, bucket) entries held between flushes.                                                |
+| `WEBHOOK_METRICS_MAX_ENDPOINTS`                  | No       | 500                   | Cap on endpoints with their own webhook metric rows per environment and bucket; environment totals still count all. |
+| `QUEUE_SIZE_METRICS_INTERVAL_SEC`                | No       | 30                    | Queue size sampling interval in seconds; must divide 60.                                                           |
+| `QUEUE_SIZE_METRICS_MAX_ENVS`                    | No       | 2000                  | Most environments sampled per interval.                                                                            |
 | `DEPLOYMENT_RATE_LIMIT_REFILL_INTERVAL`          | No       | 10s                   | Deployment endpoints rate limit refill interval.                                                                   |
 | `DEPLOYMENT_RATE_LIMIT_MAX`                      | No       | 1500                  | Deployment endpoints rate limit max.                                                                               |
 | `DEPLOYMENT_RATE_LIMIT_REFILL_RATE`              | No       | 500                   | Deployment endpoints rate limit refill rate.                                                                       |
@@ -123,6 +128,14 @@ mode: "wide"
 | `ARTIFACTS_OBJECT_STORE_ACCESS_KEY_ID`           | No       | —                     | Optional artifacts store access key.                                                                               |
 | `ARTIFACTS_OBJECT_STORE_SECRET_ACCESS_KEY`       | No       | —                     | Optional artifacts store secret key.                                                                               |
 | `ARTIFACTS_OBJECT_STORE_REGION`                  | No       | —                     | Optional artifacts store region.                                                                                   |
+| `DEPLOYMENT_INDEX_OBJECT_STORE_BASE_URL`         | No       | —                     | Optional separate store for deployment index snapshots. If not set, uses main object store.                        |
+| `DEPLOYMENT_INDEX_OBJECT_STORE_BUCKET`           | No       | —                     | Deployment index store bucket. Required together with the base URL.                                                |
+| `DEPLOYMENT_INDEX_OBJECT_STORE_ACCESS_KEY_ID`    | No       | —                     | Deployment index store access key.                                                                                 |
+| `DEPLOYMENT_INDEX_OBJECT_STORE_SECRET_ACCESS_KEY` | No       | —                     | Deployment index store secret key.                                                                                 |
+| `DEPLOYMENT_INDEX_OBJECT_STORE_REGION`           | No       | —                     | Deployment index store region.                                                                                     |
+| `DEPLOYMENT_INDEX_OBJECT_STORE_SERVICE`          | No       | s3                    | Deployment index store service.                                                                                    |
+| `DEPLOYMENT_INDEX_UPLOAD_MAX_ATTEMPTS`           | No       | 4                     | Attempts to store a deployment's index before the deploy fails.                                                    |
+| `DEPLOYMENT_INDEX_CAPTURE_ENABLED`               | No       | false                 | Set to true to store each deployment's full index in object storage when it deploys. |
 | **Alerts**                                       |          |                       |                                                                                                                    |
 | `ORG_SLACK_INTEGRATION_CLIENT_ID`                | No       | —                     | Slack client ID. Required for Slack alerts.                                                                        |
 | `ORG_SLACK_INTEGRATION_CLIENT_SECRET`            | No       | —                     | Slack client secret. Required for Slack alerts.                                                                    |
@@ -160,6 +173,7 @@ mode: "wide"
 | `SERVER_OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`  | No       | 8192                  | OTel span attribute value length limit.                                                                            |
 | **Task events**                                  |          |                       |                                                                                                                    |
 | `EVENT_REPOSITORY_DEFAULT_STORE`                 | No       | postgres              | Where to store task events. Set to `clickhouse_v2` to store in ClickHouse (recommended for production).            |
+| `EVENT_REPOSITORY_V1_REROUTE_ENABLED`            | No       | 1                     | Routes the retired `clickhouse` store to `clickhouse_v2`, for new events and for reads. Set `EVENT_REPOSITORY_DEFAULT_STORE=clickhouse_v2` and [copy older events](/self-hosting/docker#move-from-the-legacy-clickhouse-store) to keep them. `0` keeps the legacy store temporarily and will be removed. |
 | `EVENT_REPOSITORY_POSTGRES_WRITES_DISABLED`      | No       | 0                     | Skip all PostgreSQL task-event writes (set to `1`). Only enable when `EVENT_REPOSITORY_DEFAULT_STORE` is `clickhouse_v2`, otherwise task events are lost. |
 | **Realtime**                                     |          |                       |                                                                                                                    |
 | `REALTIME_BACKEND_NATIVE_ENABLED`                | No       | 0                     | Set to `1` to enable native realtime run subscriptions and change notifications. When `0`, subscriptions use Electric. The Helm chart sets this to `1`. |

package/docs/self-hosting/kubernetes.mdx

@@ -679,6 +679,8 @@ webapp:
 
 This only affects new runs; existing runs continue to read from wherever their events were originally stored.
 
+If you set `EVENT_REPOSITORY_DEFAULT_STORE` to the legacy `clickhouse` store, switch it to `clickhouse_v2`. To keep events recorded before the switch, follow [Move from the legacy clickhouse store](/self-hosting/docker#move-from-the-legacy-clickhouse-store) and run the queries with `kubectl exec` against your ClickHouse pod.
+
 ### Realtime streams
 
 Realtime streams power AI-agent token streaming and run streams. They default to **v2**, backed by the bundled `s2` deployment — [s2-lite](https://s2.dev), the open-source, self-hostable S2 server. The chart deploys it with a persistent volume, so no extra services are required.

package/docs/troubleshooting-alerts.mdx

@@ -3,6 +3,8 @@ title: "Alerts"
 description: "Get alerted when runs or deployments fail, or when deployments succeed."
 ---
 
+import { PrivateBeta } from "/snippets/feature-status.jsx";
+
 We support receiving alerts for the following events:
 - Run fails
 - Deployment fails
@@ -44,6 +46,43 @@ Click on the triple dot menu on the right side of the table row and select "Disa
 </Steps>
 
 
+## Limits alerts
+
+<PrivateBeta flag="alertsEnabled" />
+
+A **Limits** alert watches limits that can interrupt or degrade runtime flow. Pick one limit for a single alert, or several (or "Watch all limits") for one combined alert.
+
+| Group    | What you can watch                                                                                                                                                       |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Platform | API rate limit running out, Environment concurrency filling up, Queue size nearing its limit                                                                              |
+| Webhooks | Webhook processing saturating, Webhook ingress getting rate-limited, Webhook endpoint getting rate-limited, Webhook waiters running out                                  |
+
+### Signals
+
+Each limit has up to two signals. Choose one or both:
+
+- **Limit reached**: the limit is already affecting traffic, for example requests are being rejected.
+- **Approaching the limit**: usage has reached a share of the limit. The default is 80%, and you can change it.
+
+Queue size only has the approaching signal.
+
+### Any or all
+
+When you watch more than one limit, choose when the alert raises:
+
+- **Any**: raise when at least one selected limit is true.
+- **All**: raise only when every selected limit is true at the same time.
+
+### Queue metrics
+
+Environment concurrency and queue size need queue metrics for your environment. If they aren't available, they aren't offered when you create the alert.
+
+### No data
+
+A limit shows "No data" until its metrics exist, for example before your environment has made any API requests or received any webhooks. You can query these metrics yourself, see [Platform limit metrics](/observability/query#platform-limit-metrics).
+
+You can also create these alerts with the [API](/management/alerts/create).
+
 ## Error group alerts
 
 Error group alerts are **issue-based**, not run-based. They are created from the **Errors** page in the dashboard (the "Configure alerts…" button), not from the New alert modal on the Alerts page. Once created they show up in the Alerts table alongside your other alerts, labelled "Error group".

package/docs/webhooks/deliveries.mdx

@@ -70,6 +70,10 @@ The [MCP server](/mcp-introduction) has `list_webhook_deliveries` (filter by end
 | [`GET /api/v1/webhooks/deliveries/{deliveryId}`](/management/webhooks/retrieve-delivery) | Reads a delivery, with a `targets` entry per subscriber and one for waiting runs. |
 | [`POST /api/v1/webhooks/deliveries/{deliveryId}/replay`](/management/webhooks/replay-delivery) | Replays it, as above. The key needs permission to trigger every task the replay starts, and to write sessions if it reaches an agent's subscriber. |
 
+## Retention
+
+Deliveries stay visible for 3 days on Free, 7 days on Hobby, 30 days on Pro, and 90, 180 or 365 days on Enterprise. See [Limits](/limits#webhook-delivery-retention).
+
 ## Deduplication
 
 Trigger.dev uses the endpoint and idempotency key to deduplicate incoming events. Delivery records and task runs have separate deduplication windows:

package/docs/webhooks/overview.mdx

@@ -83,6 +83,14 @@ The CLI finds your endpoints and subscribers during `trigger dev` and deployment
 
 A request must pass verification before anything else happens. Provider handshakes are answered directly and create no delivery. A verified request is checked for duplicates, recorded, and then routed: each subscriber's filter is checked, matching subscribers run, and waiting runs whose match fits the event are resumed. The delivery records a result per subscriber.
 
+## Pricing and limits
+
+Webhooks have no separate charge on Trigger.dev Cloud. Receiving, verifying, filtering and recording deliveries is included in every plan. The runs a delivery starts or resumes are billed like any other run: a per-run invocation cost plus compute time. See [pricing](https://trigger.dev/pricing).
+
+A delivery that no subscriber's filter matches starts no run for any subscriber, so it costs nothing. A run already waiting for that webhook still resumes. A run [waiting](/webhooks/waiters) for a webhook is suspended, so it uses no compute until the webhook arrives.
+
+Each plan sets limits on the ingest rate, waiting runs, processing concurrency and how long deliveries are kept. See [Limits](/limits#webhook-ingest-rate-limits).
+
 ## Connect it
 
 Every endpoint can produce a setup prompt for an AI coding agent. It holds the URL, the events your subscribers filter on, and the steps for registering the endpoint and its signing secret with the provider. Copy it from the endpoints list or the endpoint's page, or read it with the MCP server's `get_webhook_endpoint_details` tool. See [Connect a provider](/webhooks/connect).

package/docs/webhooks/sources.mdx

@@ -106,6 +106,8 @@ Supabase database webhooks aren't signed, so `supabase()` checks a shared secret
 
 Slack also ships as a chat channel in `@trigger.dev/slack`.
 
+For a complete project built on `resend()`, see the [Resend email agent example](https://github.com/triggerdotdev/examples/tree/main/resend-slack-email-agent). It drafts replies to a Resend inbox and waits for your approval in Slack before sending them.
+
 ### Hookdeck
 
 `hookdeck()` verifies requests that a [Hookdeck](https://hookdeck.com) connection forwards to the endpoint. Hookdeck forwards the original provider's body unchanged, so pass that provider's event type:
@@ -242,7 +244,7 @@ Custom sources support these schemes:
 | `hmac` | Computes an HMAC over the raw body or a signing template and compares it with a request header. |
 | `shared-secret` | Compares a static token supplied in a header, bearer token, basic authentication, or request body. |
 | `url-secret` | Compares a token in a URL query parameter. Hosted endpoints don't support path placement. |
-| `asymmetric` | Verifies an Ed25519, ECDSA, or RSA signature using the provider's public key. |
+| `asymmetric` | Verifies an Ed25519, ECDSA (P-256 with SHA-256, P-384 with SHA-384), or RSA-SHA256 signature using the provider's public key. Set `prehash: "sha256"` when the provider signs a SHA-256 digest of the signing string instead of the string itself. |
 
 <Warning>
   Query parameters can appear in access logs, proxies, and traces. Prefer a header-based scheme when

package/docs/webhooks/waiters.mdx

@@ -178,13 +178,13 @@ if (!result.cancelled) {
 
 | Limit | Default |
 | --- | --- |
-| Live waiters per endpoint | 10,000. This is also the most one delivery can resume. |
-| Live waiters per environment | 1,000,000 on self-hosted installs. |
+| Live waiters per endpoint | Depends on your plan on Trigger.dev Cloud, 10,000 on self-hosted installs. This is also the most one delivery can resume. |
+| Live waiters per environment | Depends on your plan on Trigger.dev Cloud, 1,000,000 on self-hosted installs. |
 | Distinct sets of `match` paths per endpoint | 25 |
 | Paths per `match` | 5 |
 | Tags per waiter | 10 |
 | Timeout | 24 hours by default, 90 days at most |
 
-On Trigger.dev Cloud the per-endpoint and per-environment limits depend on your plan. Self-hosted installs can change them with `WEBHOOK_WAITER_MAX_PER_ENDPOINT`, `WEBHOOK_WAITER_MAX_PER_ENVIRONMENT` and `WEBHOOK_WAITER_MAX_SHAPES`.
+On Trigger.dev Cloud the per-endpoint and per-environment limits depend on your plan: see [Limits](/limits#webhook-waiters). Self-hosted installs can change them with `WEBHOOK_WAITER_MAX_PER_ENDPOINT`, `WEBHOOK_WAITER_MAX_PER_ENVIRONMENT` and `WEBHOOK_WAITER_MAX_SHAPES`.
 
 A delivery that resumes waiters shows one **Waiting runs** row on its [delivery page](/webhooks/deliveries#where-a-delivery-went) with how many matched, resumed and failed. A delivery that arrives while runs are waiting but matches none of them, and no subscriber takes, is `UNMATCHED`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "4.8.1",
+  "version": "4.8.2",
   "description": "trigger.dev Node.JS SDK",
   "license": "MIT",
   "publishConfig": {
@@ -69,7 +69,7 @@
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/semantic-conventions": "1.41.1",
-    "@trigger.dev/core": "4.8.1",
+    "@trigger.dev/core": "4.8.2",
     "uncrypto": "^0.1.3"
   },
   "devDependencies": {

package/skills/trigger-chat-agent-advanced/SKILL.md

@@ -95,22 +95,27 @@ mutate with `sessions.update`, end with `sessions.close` (terminal, idempotent).
 
 ### 2. Durable sub-agent as a streaming tool
 
-`AgentChat` inside an AI SDK `tool()` delegates to a durable sub-agent; its response streams as
-preliminary tool results. Give the tool a `toModelOutput` so the model sees a compact summary.
+`AgentChat` inside an AI SDK `tool()` delegates to a durable sub-agent; `chat.forwardSubAgent`
+streams its reply to the frontend and returns the final message as the tool output. Give the tool a
+`toModelOutput` so the model sees a compact summary.
 
 ```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(); // UIMessage snapshots become preliminary tool results
-    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 }); // chunks out once, final UIMessage back
+    } finally {
+      await researcher.close();
+    }
   },
   toModelOutput: ({ output: message }) => {
     const lastText = message?.parts?.findLast((p: { type: string }) => p.type === "text") as
@@ -121,6 +126,11 @@ const researchTool = tool({
 });
 ```
 
+On the frontend, `useSubAgentMessages()` from `@trigger.dev/sdk/chat/react` rebuilds each sub-agent
+while it runs: pass its `onData` to `useChat` and render `subAgents.get(part.toolCallId) ?? part.output`.
+Do not `yield* stream.messages()` from a tool: every snapshot repeats the whole message, so the bytes
+written grow with the square of the reply length.
+
 For a subtask exposed via `execute: ai.toolExecute(task)`, stream progress to the agent's run with
 `chat.stream.writer({ target: "root" })`. `target` accepts `"self" | "parent" | "root" | <runId>`.
 Inside the subtask, read context with `ai.toolCallId()` and `ai.chatContextOrThrow<typeof myChat>()`

package/skills/trigger-cost-savings/SKILL.md

@@ -105,6 +105,7 @@ Larger machines cost proportionally more per second of compute:
 ## Key principles
 
 - **Waits > 5 seconds are free** — checkpointed, no compute charge.
+- **Webhook filters skip runs** — a webhook delivery starts no run when no subscriber's filter matches, so it costs no compute (a run already waiting for that webhook still resumes). Receiving webhooks has no separate charge.
 - **Start small, scale up** — the default `small-1x` is right for most tasks.
 - **I/O-bound tasks don't need big machines** — API calls and DB queries wait on the network.
 - **Debounce saves the most on high-frequency tasks** — it consolidates bursts into single runs.