@trigger.dev/sdk 4.8.0-webhooks.20261015065339 → 4.8.0-webhooks.20261020092920

package/docs/ai-chat/backend.mdx

@@ -4,6 +4,8 @@ sidebarTitle: "Backend"
 description: "Three approaches to building your chat backend — chat.agent(), session iterator, or raw task primitives."
 ---
 
+import WebhooksBetaNote from "/snippets/webhooks-beta-note.mdx";
+
 There are three abstraction levels for a chat backend. All three speak the same wire protocol, so the [frontend transport](/ai-chat/frontend) works unchanged whichever you pick.
 
 | Capability                            | `chat.agent()` | `chat.createSession()`                                        | Raw primitives |
@@ -499,6 +501,8 @@ See [Actions](/ai-chat/actions).
 
 ### Webhook events and channels
 
+<WebhooksBetaNote />
+
 Two `chat.agent()` options wire an agent to verified inbound webhooks. `events` claims [`chat.event(...)`](/webhooks/session-routing) descriptors: each verified delivery is routed to this agent's session and arrives at `onAction` as an action (not a turn), so [session routing](/webhooks/session-routing) decides which conversation it lands on. `channels` claims channel connectors that turn an external chat surface into a frontend for the agent: an inbound message runs as a turn through `run()` and the reply is posted back. `slack()` ships in `@trigger.dev/slack`, and `chat.channels.custom(...)` builds a connector for any endpoint without a preset.
 
 ```ts
@@ -513,6 +517,8 @@ export const orderEvents = chat.event({
   id: "order-events",
   endpoint: stripe,
   key: "{event.data.object.customer}",
+  // invoices always carry a customer; events without one would have no session to go to
+  filter: "event.type startsWith 'invoice.'",
   type: "order.event",
 });
 

package/docs/ai-chat/patterns/redacting-telemetry.mdx

@@ -0,0 +1,117 @@
+---
+title: "Redact chat content from traces"
+sidebarTitle: "Redact chat content"
+description: "Stop a chat agent recording user messages and clientData on its spans, turn off AI SDK prompt and response recording, or redact span content with a span processor before it leaves the worker."
+---
+
+A chat agent's run trace records conversation content by default: the user's message and the `clientData` your frontend sends. When AI SDK telemetry is on, it also records the prompts and responses of each model call. This page covers the three controls that change that, and what they don't cover.
+
+## What the run trace records
+
+| Span | Content | Control |
+| --- | --- | --- |
+| `chat turn N` | The last user message (`chat.user_message`) and its first 80 characters as the span preview | `telemetry.recordUserMessage` |
+| `chat turn N` | The raw `clientData` (`chat.client_data`) | `telemetry.recordClientData` |
+| `pending message injected` | Messages sent mid-turn (`pending.messages`) | `telemetry.recordUserMessage` |
+| AI SDK model call spans, when AI SDK telemetry is on | Prompt messages, response text, tool calls | `experimental_telemetry` on the model call |
+| Any span | Everything above, plus your own attributes and span events | A span processor |
+
+## Stop recording chat content
+
+Set `telemetry` on the agent to stop the chat runtime recording the user's message and `clientData` on its spans. Both default to `true`.
+
+```ts /trigger/support-agent.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export const supportAgent = chat.agent({
+  id: "support-agent",
+  telemetry: { recordUserMessage: false, recordClientData: false },
+  run: async ({ messages, signal, streamText }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
+});
+```
+
+The spans still appear in the trace with their timings and token usage. The turn spans have no preview text.
+
+## Stop the AI SDK recording prompts and responses
+
+AI SDK model call spans appear when AI SDK telemetry is on: [`chat.prompt.set()`](/ai-chat/backend#using-prompts) turns it on for you, or you pass `experimental_telemetry` yourself. Those spans include prompts and responses unless you turn that off with `recordInputs` and `recordOutputs`:
+
+```ts /trigger/support-agent.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export const supportAgent = chat.agent({
+  id: "support-agent",
+  telemetry: { recordUserMessage: false, recordClientData: false },
+  run: async ({ messages, signal, streamText }) =>
+    streamText({
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      abortSignal: signal,
+      // Replaces any telemetry config from chat.prompt.set(), so keep isEnabled on
+      experimental_telemetry: { isEnabled: true, recordInputs: false, recordOutputs: false },
+    }),
+});
+```
+
+If you use `chat.prompt.set()`, your `experimental_telemetry` replaces the one it adds, including the metadata that links each generation to its prompt version. To keep that link, redact with a span processor instead.
+
+## Redact instead of dropping
+
+To keep the content but strip sensitive values from it, add a span processor in `trigger.config.ts`. It runs on every span before export, so one processor covers the chat runtime's spans, the AI SDK spans and your own.
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+import type { AttributeValue, Attributes } from "@opentelemetry/api";
+import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+
+const EMAIL = /[\w.+-]+@[\w-]+\.[\w.]+/g;
+
+function redact(value: AttributeValue | undefined): AttributeValue | undefined {
+  if (typeof value === "string") return value.replace(EMAIL, "[email]");
+  // Some attributes are string arrays, like the messages sent mid-turn
+  if (Array.isArray(value)) {
+    return value.map((item) =>
+      typeof item === "string" ? item.replace(EMAIL, "[email]") : item
+    ) as AttributeValue;
+  }
+  return value;
+}
+
+function scrub(attributes: Attributes) {
+  for (const key of Object.keys(attributes)) attributes[key] = redact(attributes[key]);
+}
+
+const redactEmails: SpanProcessor = {
+  onStart: () => {},
+  onEnding: (span) => {
+    scrub(span.attributes);
+    for (const event of span.events) scrub(event.attributes ?? {});
+  },
+  onEnd: () => {},
+  forceFlush: async () => {},
+  shutdown: async () => {},
+};
+
+export default defineConfig({
+  project: "<project ref>",
+  telemetry: { spanProcessors: [redactEmails] },
+});
+```
+
+Scrubbing every string value, rather than matching attribute names, also catches the turn preview text. See [Span processors](/config/config-file#span-processors) for when each hook runs and which attributes are kept.
+
+## What spans don't cover
+
+These controls change the run trace only. Conversation content also reaches the platform in two other places:
+
+- **Session streams.** Each message your frontend sends is written to the session's `session.in` stream, and the agent's output to `session.out`. They hold message content for their retention window, and the session view in the dashboard reads from them. See [transcript storage limits](/ai-chat/transcript-storage#guarantees-and-limits).
+- **The run payload.** A chat agent run's payload includes `clientData` as `metadata`, and every `session.in` record carries it too. Send an id in `clientData` and look up the rest in `onPreload` or `run` instead of sending the values themselves.
+
+To keep a value off the platform entirely, redact or tokenize it in your frontend or backend before it's sent. The model then sees the redacted value too, unless your tools resolve the tokens.
+
+## Verify it
+
+Send a message containing a marker value (an email address, for example), then open the run in the dashboard. Select the `chat turn 1` span and check its properties: the marker is gone, or shows as `[email]` with the span processor above. The span list shows the same redacted preview.

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

@@ -12,7 +12,7 @@ By default (without `pendingMessages`), a message sent while the agent is respon
 
 The `pendingMessages` option enables steering instead, injecting user messages between tool-call steps via the AI SDK's `prepareStep`. Messages that arrive during streaming are queued and injected at the next step boundary. A message that is not injected becomes the next turn instead, whether that is because `shouldInject` returned `false` or because there were no more step boundaries (single-step response or final text generation). The backend handles that, so no client-side re-send is involved.
 
-Messages from a [channel](/webhooks/channels) such as [Slack](/webhooks/slack) are offered the same way, with `metadata.source` set to `"channel"` so `shouldInject` can tell them apart. A channel's stop control and approval clicks are never offered. The connector acknowledges a channel message as soon as it arrives (Slack reacts with 👀, Linear posts a thought), before `shouldInject` decides, so the acknowledgement is the same whether the message is folded in or answered next.
+Messages from a [channel](/webhooks/channels) such as [Slack](/webhooks/slack) are offered the same way, with `metadata.source` set to `"channel"` so `shouldInject` can tell them apart. A channel's stop control and approval clicks are never offered. The connector acknowledges a channel message as soon as it arrives (Slack reacts with 👀, Linear posts a thought), before `shouldInject` decides, so the acknowledgement is the same whether the message is folded in or answered next. Channels are part of the [webhooks private beta](https://trigger.dev/webhooks-beta).
 
 Use the `streamText` passed to your agent's `run` callback. It wires up pending-message injection automatically. If you import `streamText` directly from `ai`, spread `chat.toStreamTextOptions()` into its options to connect injection.
 

package/docs/ai-chat/reference.mdx

@@ -48,8 +48,8 @@ Options for `chat.agent()`.
 | `hydrateMessages`             | `(event: HydrateMessagesEvent) => UIMessage[] \| Promise<UIMessage[]>` | —                 | **Deprecated.** Load message history from backend, replacing the linear accumulator. Use `loadContext` on a `storage` instead; cannot be combined with `storage`. See [hydrateMessages](/ai-chat/lifecycle-hooks#hydratemessages) |
 | `actionSchema`                | `TaskSchema`                                                | —                              | Schema for validating custom actions sent via `transport.sendAction()`. See [Actions](/ai-chat/actions) |
 | `onAction`                    | `(event: ActionEvent) => Promise<void \| ActionTurn> \| void \| ActionTurn` | —                              | Handle custom actions. Actions are state edits: only `hydrateMessages` (or a storage's `loadContext`) + `onAction` fire. Return `chat.turn()` to run a turn on the edited history (`chat.turn(message)` to answer a new user message), or nothing for an edit only. See [Actions](/ai-chat/actions) |
-| `events`                      | `ChatEvent[]`                                               | —                              | Webhook event descriptors (from `chat.event()`) whose verified deliveries are routed to this agent as actions and handled in `onAction`. See [session routing](/webhooks/session-routing). |
-| `channels`                    | `ChannelConnector[]`                                        | —                              | Channel connectors (for example `slack()`) that turn an external chat surface into a frontend for the agent: inbound messages run as turns and the reply posts back. See [channels](/webhooks/channels). |
+| `events`                      | `ChatEvent[]`                                               | —                              | Webhook event descriptors (from `chat.event()`) whose verified deliveries are routed to this agent as actions and handled in `onAction`. See [session routing](/webhooks/session-routing). Part of the [webhooks private beta](https://trigger.dev/webhooks-beta). |
+| `channels`                    | `ChannelConnector[]`                                        | —                              | Channel connectors (for example `slack()`) that turn an external chat surface into a frontend for the agent: inbound messages run as turns and the reply posts back. See [channels](/webhooks/channels). Part of the [webhooks private beta](https://trigger.dev/webhooks-beta). |
 | `onTurnStart`                 | `(event: TurnStartEvent) => Promise<void> \| void`          | —                              | Fires every turn before `run()`                                                                     |
 | `onBeforeTurnComplete`        | `(event: BeforeTurnCompleteEvent) => Promise<void> \| void` | —                              | Fires after response but before stream closes. Includes `writer`.                                   |
 | `onTurnComplete`              | `(event: TurnCompleteEvent) => Promise<void> \| void`       | —                              | Fires after each turn completes (stream closed)                                                     |
@@ -73,6 +73,7 @@ Options for `chat.agent()`.
 | `onChatResume`                | `(event: ChatResumeEvent) => Promise<void> \| void`         | —                              | Fires right after the run resumes from suspension                                                   |
 | `exitAfterPreloadIdle`        | `boolean`                                                   | `false`                        | Exit run after preload idle timeout instead of suspending. See [exitAfterPreloadIdle](/ai-chat/lifecycle-hooks#exitafterpreloadidle) |
 | `oomMachine`                  | `MachinePresetName`                                         | —                              | Fallback machine when an attempt fails with OOM. Setting it enables a single OOM retry on the larger machine. See [OOM resilience](/ai-chat/patterns/oom-resilience) |
+| `telemetry`                   | `{ recordUserMessage?: boolean; recordClientData?: boolean }` | both `true`                    | What the chat runtime records on its spans. `recordUserMessage: false` drops the user message and turn preview (`chat.user_message`, `pending.messages`); `recordClientData: false` drops `chat.client_data`. See [Redact chat content from traces](/ai-chat/patterns/redacting-telemetry) |
 
 Plus most standard [TaskOptions](/tasks/overview) — `queue`, `machine`, `maxDuration`, **`onWait`**, **`onResume`**, **`onComplete`**, and other lifecycle hooks. Generic `retry` is **not** exposed on `chat.agent`; use `oomMachine` for OOM recovery, or drop down to a raw [`task()`](/ai-chat/custom-agents) if you need richer retry semantics. Standard hooks use the same parameter shapes as on a normal `task()` (including `ctx`).
 
@@ -541,8 +542,8 @@ All methods available on the `chat` object from `@trigger.dev/sdk/ai`.
 | Method                                      | Description                                                                                                                  |
 | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | `chat.agent(options)`                       | Create a chat agent                                                                                                          |
-| `chat.event(options)`                       | Declare an inbound webhook event descriptor an agent claims via `chat.agent({ events })`. See [session routing](/webhooks/session-routing). |
-| `chat.channels.custom(options)`             | Create a generic chat-frontend channel over any verified webhook source (you supply the egress). The `slack()` preset ships in `@trigger.dev/slack`. See [channels](/webhooks/channels). |
+| `chat.event(options)`                       | Declare an inbound webhook event descriptor an agent claims via `chat.agent({ events })`. See [session routing](/webhooks/session-routing). Part of the [webhooks private beta](https://trigger.dev/webhooks-beta). |
+| `chat.channels.custom(options)`             | Create a generic chat-frontend channel over any verified webhook source (you supply the egress). The `slack()` preset ships in `@trigger.dev/slack`. See [channels](/webhooks/channels). Part of the [webhooks private beta](https://trigger.dev/webhooks-beta). |
 | `chat.createSession(payload, options)`      | Create an async iterator for chat turns                                                                                      |
 | `chat.pipe(source, options?)`               | Pipe a stream to the frontend (from anywhere inside a task)                                                                  |
 | `chat.pipeAndCapture(source, options?)`     | Pipe and capture the response; returns `{ message, status, error }`                                                         |
@@ -589,6 +590,8 @@ export const orderEvents = chat.event({
   id: "order-events",
   endpoint: stripe,
   key: "{event.data.object.customer}",
+  // invoices always carry a customer; events without one would have no session to go to
+  filter: "event.type startsWith 'invoice.'",
   type: "order.event",
 });
 ```

package/docs/ai-chat/transcript-storage.mdx

@@ -226,7 +226,7 @@ A few things to get right:
 ## Guarantees and limits
 
 - Crash recovery of a half-written answer is runtime-owned in every configuration. It comes from the durable session stream, which no application database can reconstruct. A storage holds settled turns; the runtime overlays the recovered tail and hands it to `save` like any other change.
-- Bringing your own database does not remove platform custody. Session streams still hold message content for their retention window.
+- Bringing your own database does not remove platform custody. Session streams still hold message content for their retention window. To keep content out of the run trace, see [Redact chat content from traces](/ai-chat/patterns/redacting-telemetry).
 - The default storage rewrites the whole conversation each turn. A row-per-message storage writes only what changed. That is the reason to plug in your own.
 
 ## Migrating from hydrateMessages

package/docs/apikeys.mdx

@@ -81,8 +81,10 @@ Access presets define what a key can do. On the Free and Hobby plans only the **
 | --- | --- |
 | **Trigger only** | Trigger runs and batches for all or selected tasks. Trigger responses include scoped public access tokens for the runs and batches they create |
 | **Task operator** | Trigger all or selected tasks and inspect or operate on their runs |
-| **Observer** | Read runs, tasks, batches, logs, traces, and queues |
-| **Operator** | Observe and operate on runs and queues, and trigger tasks |
+| **Observer** | Read runs, tasks, batches, logs, traces, queues, errors, and webhooks |
+| **Operator** | Observe and operate on runs, queues, errors, and webhooks, and trigger tasks |
+| **Webhooks only** | Read and write [webhooks](/webhooks/overview), which are in private beta. Replaying deliveries that trigger tasks and creating webhook waiters require task or waitpoint scopes |
+| **Waitpoints only** | Create, list, and retrieve [waitpoint tokens](/wait-for-token). No task or run access |
 | **Deploy only** | Deploy versions, sync environment variables, and manage Preview branches |
 | **Variables only** | Read and write environment variables in this environment |
 | **No restrictions** | Full access to the environment |
@@ -96,11 +98,11 @@ Set a key in `TRIGGER_ACCESS_TOKEN` to authenticate `trigger deploy` without log
 <CodeGroup>
 
 ```bash npm
-TRIGGER_ACCESS_TOKEN="tr_prod_sk_…" npx trigger.dev@latest deploy
+TRIGGER_ACCESS_TOKEN="tr_prod_sk_…" npx trigger.dev@latest deploy --env prod
 ```
 </CodeGroup>
 
-The key must belong to the target environment. Use a Production key for the default deployment, a Staging key with `--env staging`, or a key from the Preview environment with `--env preview`. A Preview deployment key can create and archive Preview branches and sync their environment variables.
+The key must belong to the target environment. Use a Production key with `--env prod`, a Staging key with `--env staging`, or a key from the Preview environment with `--env preview`. If you leave out `--env`, the CLI deploys to the key's environment, and a `--env` that doesn't match the key is an error. A Preview deployment key can create and archive Preview branches and sync their environment variables.
 
 <Note>
   The deploy CLI reads environment API keys from `TRIGGER_ACCESS_TOKEN`, not

package/docs/cli-runs-commands.mdx

@@ -84,8 +84,8 @@ npx trigger.dev@latest runs cancel run_abc123
 
 <ConfigFileOptions />
 <ProjectRefOptions />
-<ParamField body="Preview branch" type="--branch | -b">
-  Required when using `--env preview`. Specify the branch, e.g. `--branch my-branch` or `-b my-branch`.
+<ParamField body="Branch" type="--branch | -b">
+  Required when using `--env preview`. Specify the branch, e.g. `--branch my-branch` or `-b my-branch`. With `--env dev`, it defaults to the same [dev branch](/deployment/dev-branches) as the dev command.
 </ParamField>
 
 ### Common options

package/docs/cli-tasks-commands.mdx

@@ -0,0 +1,95 @@
+---
+title: "CLI tasks commands"
+sidebarTitle: "tasks"
+description: "Use these commands to trigger tasks from your terminal."
+---
+
+import CommonOptions from "/snippets/cli-options-common.mdx";
+import ConfigFileOptions from "/snippets/cli-options-config-file.mdx";
+import ProjectRefOptions from "/snippets/cli-options-project-ref.mdx";
+
+## tasks trigger
+
+Triggers a task and prints the run ID and its dashboard URL. It runs in the `dev` environment unless you pass `--env`, so start the [dev command](/cli-dev-commands) first.
+
+<CodeGroup>
+
+```bash npm
+npx trigger.dev@latest tasks trigger hello-world --payload '{"name":"Ada"}'
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest tasks trigger hello-world --payload '{"name":"Ada"}'
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest tasks trigger hello-world --payload '{"name":"Ada"}'
+```
+
+</CodeGroup>
+
+Add `--wait` to wait for the run to finish. It prints the run's output, or its error and exits with code 1 if the run failed, which makes it useful in scripts and for coding agents testing a task:
+
+```bash
+npx trigger.dev@latest tasks trigger hello-world --payload '{"name":"Ada"}' --wait
+```
+
+The command fails without creating a run if the current version has no task with that ID. In `dev`, it warns you when the dev command isn't running, because the run waits in the queue until it starts.
+
+<ParamField body="Payload" type="--payload">
+  The payload as JSON, e.g. `--payload '{"name":"Ada"}'`. Without it, the task gets no payload.
+</ParamField>
+
+<ParamField body="Payload file" type="--payload-file">
+  Read the payload from a JSON file instead.
+</ParamField>
+
+<ParamField body="Wait" type="--wait">
+  Wait for the run to finish, then print its output or error.
+</ParamField>
+
+<ParamField body="Timeout" type="--timeout">
+  With `--wait`, stop waiting after this many seconds and exit with code 1.
+</ParamField>
+
+<ParamField body="Tag" type="--tag">
+  A tag to add to the run. Repeat it to add more than one, e.g. `--tag cli --tag test`.
+</ParamField>
+
+<ParamField body="Idempotency key" type="--idempotency-key">
+  If a run with this key already exists, return it instead of creating a new one. See [idempotency](/idempotency).
+</ParamField>
+
+<ParamField body="Delay" type="--delay">
+  Wait before running, e.g. `30s`, `5m` or an ISO 8601 date.
+</ParamField>
+
+<ParamField body="TTL" type="--ttl">
+  Expire the run if it hasn't started within this time, e.g. `10m`.
+</ParamField>
+
+<ParamField body="Queue" type="--queue">
+  The queue to run in, instead of the queue set on the task.
+</ParamField>
+
+<ParamField body="Machine" type="--machine">
+  The machine to run on, e.g. `small-2x`. See [machines](/machines). Has no effect in `dev`.
+</ParamField>
+
+## Options
+
+<ParamField body="Environment" type="--env | -e">
+  The environment to use: `dev`, `prod`, `staging` or `preview`. Defaults to `dev`.
+</ParamField>
+
+<ConfigFileOptions />
+<ProjectRefOptions />
+<ParamField body="Branch" type="--branch | -b">
+  The branch to use. Required with `--env preview`. In `dev`, it defaults to the same [dev branch](/deployment/dev-branches) as the dev command.
+</ParamField>
+
+### Common options
+
+These options are available on most commands.
+
+<CommonOptions />

package/docs/config/config-file.mdx

@@ -267,6 +267,64 @@ export default defineConfig({
 });
 ```
 
+### Span processors
+
+Span processors run on every span before it is exported, to Trigger.dev and to any `exporters` you configure. Use them to redact or drop span content before it reaches the run trace.
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+import type { AttributeValue, Attributes } from "@opentelemetry/api";
+import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+
+const EMAIL = /[\w.+-]+@[\w-]+\.[\w.]+/g;
+
+function redact(value: AttributeValue | undefined): AttributeValue | undefined {
+  if (typeof value === "string") return value.replace(EMAIL, "[email]");
+  // Some attributes are string arrays, like the messages sent mid-turn
+  if (Array.isArray(value)) {
+    return value.map((item) =>
+      typeof item === "string" ? item.replace(EMAIL, "[email]") : item
+    ) as AttributeValue;
+  }
+  return value;
+}
+
+function scrub(attributes: Attributes) {
+  for (const key of Object.keys(attributes)) attributes[key] = redact(attributes[key]);
+}
+
+const redactEmails: SpanProcessor = {
+  onStart: () => {},
+  // The span is complete here and still writable
+  onEnding: (span) => {
+    scrub(span.attributes);
+    for (const event of span.events) scrub(event.attributes ?? {});
+  },
+  onEnd: () => {},
+  forceFlush: async () => {},
+  shutdown: async () => {},
+};
+
+export default defineConfig({
+  project: "<project ref>",
+  telemetry: {
+    spanProcessors: [redactEmails],
+  },
+});
+```
+
+Your processors run ahead of ours, so they also see the in-progress copy of each span that the dashboard shows while a span is open. Redact in `onEnding`:
+
+- `onStart` runs before we add the run context, so it sees only the attributes the span was started with.
+- In `onEnd` the span is read-only and `setAttribute` does nothing. Writing to `span.attributes` directly still works.
+- Content can also sit in span events (exceptions, for example). Events are on `span.events`.
+
+After each call we restore the few attributes we use to link a span to its run, such as the run, task and attempt ids. Everything else can be redacted, including run tags and idempotency keys. If a processor throws, the error is reported and the span is still exported.
+
+<Note>
+  Span processors only change span content. Run payloads and outputs, and the messages on a chat agent's session streams, are stored as sent. For chat agents, see [Redact chat content from traces](/ai-chat/patterns/redacting-telemetry).
+</Note>
+
 ## Runtime
 
 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.

package/docs/config/extensions/prismaExtension.mdx

@@ -189,7 +189,7 @@ prismaExtension({
   "scripts": {
     "prebuild": "prisma generate",
     "dev": "trigger dev",
-    "deploy": "trigger deploy"
+    "deploy": "trigger deploy --env prod"
   }
 }
 ```
@@ -331,7 +331,7 @@ steps:
   - name: Generate Prisma client
     run: npx prisma@6.19.0 generate
   - name: Deploy Trigger.dev
-    run: npx trigger.dev@4.1.1 deploy
+    run: npx trigger.dev@4.1.1 deploy --env prod
     env:
       TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
 ```
@@ -902,7 +902,7 @@ datasource db {
   "scripts": {
     "generate": "prisma generate",
     "dev": "pnpm generate && trigger dev",
-    "deploy": "trigger deploy"
+    "deploy": "trigger deploy --env prod"
   }
 }
 ```
@@ -975,7 +975,7 @@ export default defineConfig({
   "scripts": {
     "generate": "prisma generate",
     "dev": "pnpm generate && trigger dev",
-    "deploy": "trigger deploy"
+    "deploy": "trigger deploy --env prod"
   }
 }
 ```

package/docs/deploy-environment-variables.mdx

@@ -3,6 +3,8 @@ title: "Environment Variables"
 description: "Any environment variables used in your tasks need to be added so the deployed code will run successfully."
 ---
 
+import { RollingOut } from "/snippets/feature-status.jsx";
+
 An environment variable in Node.js is accessed in your code using `process.env.MY_ENV_VAR`.
 
 We deploy your tasks and scale them up and down when they are triggered. So any environment variables you use in your tasks need to accessible to us so your code will run successfully.
@@ -43,6 +45,8 @@ When creating an environment variable, you can mark it as a **Secret**. Secret v
 
 You can edit an environment variable's values. You cannot edit the key name, you must delete and create a new one.
 
+<RollingOut flag="allowEmptyEnvironmentVariableValues" />
+
 <Note>
   An empty string is a valid value. Saving a variable with an empty value stores it as an empty
   string (your task sees the variable set to `""`), which is different from deleting the variable

package/docs/deployment/atomic-deployment.mdx

@@ -60,7 +60,7 @@ The id is free-form and opaque to Trigger.dev — a commit SHA, a release tag, a
 <Step title="Deploy your tasks with an external id">
 
 ```bash
-npx trigger.dev@latest deploy --external-id "$(git rev-parse HEAD)"
+npx trigger.dev@latest deploy --env prod --external-id "$(git rev-parse HEAD)"
 ```
 
 </Step>
@@ -240,7 +240,7 @@ Read the commit in the place where it *is* available, and write it into both hal
 
 ```bash
 # 1. Deploy side — name the deployment after the commit.
-npx trigger.dev@latest deploy --external-id "$(git rev-parse HEAD)"
+npx trigger.dev@latest deploy --env prod --external-id "$(git rev-parse HEAD)"
 
 # 2. Application side — give the running app the same value.
 TRIGGER_EXTERNAL_DEPLOYMENT_ID=<the-same-commit-sha>
@@ -385,7 +385,7 @@ If you filter deploys by path, derive the id from the same filter on both sides
 
 ```bash
 TASK_ID=$(git log -1 --format=%H -- trigger/)
-npx trigger.dev@latest deploy --external-id "$TASK_ID"
+npx trigger.dev@latest deploy --env prod --external-id "$TASK_ID"
 ```
 
 Compute the same value where you set your app's variable. In GitHub Actions this needs `fetch-depth: 0` on `actions/checkout` — the default shallow clone can't see far enough back.

package/docs/deployment/overview.mdx

@@ -162,7 +162,7 @@ To keep your app and tasks in sync without coordinating promotion at all, see [a
 
 ## Staging deploys
 
-By default, the `deploy` command will deploy to the `prod` environment. If you want to deploy to a different environment, you can use the `--env` flag:
+Use the `--env` flag to choose the environment you deploy to. If you don't pass it, the `deploy` command deploys to the `prod` environment, unless `TRIGGER_ACCESS_TOKEN` holds an API key for another environment. To deploy to staging:
 
 ```bash
 npx trigger.dev deploy --env staging

package/docs/deployment/preview-branches.mdx

@@ -147,7 +147,7 @@ Creating and deploying a preview branch manually is easy:
 npx trigger.dev@latest deploy --env preview
 ```
 
-This will create and deploy a preview branch, automatically detecting the git branch. If for some reason the auto-detection doesn't work it will let you know and tell you do this:
+This will create and deploy a preview branch, automatically detecting the git branch. When your CI checks out a detached HEAD, the branch is read from the CI provider's branch variable instead (GitLab, Bitbucket, CircleCI, Buildkite, Travis CI, Jenkins and Azure Pipelines are supported). If for some reason the auto-detection doesn't work it will let you know and tell you do this:
 
 ```bash
 npx trigger.dev@latest deploy --env preview --branch your-branch-name

package/docs/github-actions.mdx

@@ -47,7 +47,7 @@ jobs:
         env:
           TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
         run: |
-          npx trigger.dev@latest deploy --external-id ${{ github.sha }}
+          npx trigger.dev@latest deploy --env prod --external-id ${{ github.sha }}
 ```
 
 ```yaml .github/workflows/release-trigger-staging.yml
@@ -184,7 +184,7 @@ Tip: add the `trigger.dev` CLI to your `devDependencies` and the deploy command
 ```json
 {
   "scripts": {
-    "deploy:trigger-prod": "trigger deploy",
+    "deploy:trigger-prod": "trigger deploy --env prod",
     "deploy:trigger": "trigger deploy --env staging"
   },
   "devDependencies": {
@@ -254,7 +254,7 @@ jobs:
           TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
           TRIGGER_API_URL: ${{ secrets.TRIGGER_API_URL }}
         run: |
-          npx trigger.dev@latest deploy
+          npx trigger.dev@latest deploy --env prod
 ```
 
 </CodeGroup>

package/docs/limits.mdx

@@ -12,6 +12,12 @@ You can view your current limits, quotas, and rate limit usage in real-time by v
   [Billing limits and alerts](/billing-limits).
 </Note>
 
+## Run duration
+
+Runs have no maximum duration. You set a default `maxDuration` for your project and can override it per task or per run, or set it to `timeout.None` to let a run execute indefinitely.
+
+Trigger is built for long running AI agents and workflows and we have seen Trigger.dev users with runs lasting more than six months.
+
 ## Concurrency limits
 
 Concurrency is allocated **per environment**, not as a single figure for the whole organization. Each plan sets a separate default for production, staging, preview and development:

package/docs/manual-setup.mdx

@@ -109,7 +109,7 @@ Then add scripts to your `package.json`:
 {
   "scripts": {
     "dev:trigger": "trigger dev",
-    "deploy:trigger": "trigger deploy"
+    "deploy:trigger": "trigger deploy --env prod"
   }
 }
 ```

package/docs/mcp-tools.mdx

@@ -4,6 +4,8 @@ sidebarTitle: "Tools"
 description: "Learn about how to use the tools available in the Trigger.dev MCP Server"
 ---
 
+import WebhooksBetaNote from "/snippets/webhooks-beta-note.mdx";
+
 ## Documentation and Search Tools
 
 ### search_docs
@@ -189,7 +191,7 @@ Execute a TRQL query against your Trigger.dev data. TRQL is a SQL-style query la
 
 ### list_dashboards
 
-List available built-in dashboards with their widgets. Each dashboard contains pre-built queries for common metrics.
+List the built-in dashboards and your organization's custom dashboards, with their widgets.
 
 **Example usage:**
 - `"What dashboards are available?"`
@@ -197,12 +199,28 @@ List available built-in dashboards with their widgets. Each dashboard contains p
 
 ### run_dashboard_query
 
-Execute a single widget query from a built-in dashboard. Use `list_dashboards` first to see available dashboards and widget IDs.
+Execute a single widget query from a built-in or custom dashboard. Use `list_dashboards` first to see available dashboards and widget IDs.
 
 **Example usage:**
 - `"Run the total runs widget from the overview dashboard"`
 - `"Show me the LLM cost over time from the AI dashboard"`
 
+### create_dashboard
+
+Create a custom dashboard, optionally with widgets. Each widget has a title, a TRQL query and a display: a table, a bar or line chart, a big number, or a section title. Queries are checked when the dashboard is saved.
+
+**Example usage:**
+- `"Make a dashboard for the email tasks with total runs, failures and runs per day"`
+- `"Create a dashboard that charts p95 duration by task"`
+
+### set_dashboard_widgets
+
+Replace every widget on a custom dashboard, and optionally rename it.
+
+**Example usage:**
+- `"Add a failed runs widget to the email dashboard"`
+- `"Change the runs per day chart to a line chart"`
+
 ### get_report
 
 Render an interpreted [health report](/reports) — a deterministic verdict, not a raw panel — as text with sparklines. The `health` report answers whether work is flowing, whether the runs that start are healthy, and whether the telemetry is fresh, with a headline verdict and a suggested next action. Returns markdown by default, or ANSI when `color` is set. Read-only.
@@ -239,7 +257,7 @@ Check the status of the dev server and view recent output. Shows whether it is s
 - `"Are there any build errors?"`
 
 <Callout type="warning">
-  The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag. The `--readonly` flag hides deploy, trigger_task, cancel_run, and replay_run.
+  The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag. The `--readonly` flag hides deploy, trigger_task, cancel_run, replay_run, create_dashboard, and set_dashboard_widgets.
 </Callout>
 
 ## Agent Chat Tools
@@ -334,6 +352,8 @@ Append one record to a named side channel's `in` stream. Sends control input to
 
 ## Webhook Tools
 
+<WebhooksBetaNote />
+
 Set up and debug [hosted webhook endpoints](/webhooks/overview). Endpoint ids start with `wh_` and delivery ids with `whd_`; endpoint tools also accept an endpoint's declared id. The same operations are on the [Webhooks API](/management/webhooks/list-endpoints).
 
 ### list_webhook_endpoints