@trigger.dev/sdk 4.8.0 → 4.8.1

package/dist/commonjs/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = "4.8.0";
+exports.VERSION = "4.8.1";
 //# sourceMappingURL=version.js.map

package/dist/esm/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "4.8.0";
+export const VERSION = "4.8.1";
 //# sourceMappingURL=version.js.map

package/docs/ai/prompts.mdx

@@ -219,8 +219,9 @@ Prompts integrate with `chat.agent()` via `chat.prompt` — a run-scoped store f
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
 import { prompts } from "@trigger.dev/sdk";
-import { streamText, createProviderRegistry } from "ai";
+import { createProviderRegistry, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
+import { z } from "zod";
 
 const registry = createProviderRegistry({ anthropic });
 
@@ -234,13 +235,14 @@ const systemPrompt = prompts.define({
 
 export const myChat = chat.agent({
   id: "my-chat",
+  registry,
+  clientDataSchema: z.object({ name: z.string() }),
   onChatStart: async ({ clientData }) => {
     const resolved = await systemPrompt.resolve({ name: clientData.name });
     chat.prompt.set(resolved);
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
-      ...chat.toStreamTextOptions({ registry }),
       messages,
       abortSignal: signal,
       stopWhen: stepCountIs(15),
@@ -249,9 +251,11 @@ export const myChat = chat.agent({
 });
 ```
 
+The `streamText` passed to `run()` applies the stored prompt: its system text, its model (resolved through the agent's `registry`), its `config`, and telemetry that links each generation to the prompt version. Options you pass at the call site win, apart from `system`, which throws when a prompt already sets one.
+
 ### chat.toStreamTextOptions()
 
-Returns an options object ready to spread into `streamText()`. When a prompt is stored via `chat.prompt.set()`, it includes:
+Inside a `chat.agent` you don't need this: the `streamText` passed to `run()` applies the same options. Use `chat.toStreamTextOptions()` when you call `streamText` yourself, as in a [custom agent](/ai-chat/custom-agents). It returns an options object ready to spread into `streamText()`. When a prompt is stored via `chat.prompt.set()`, it includes:
 
 - `system` — the compiled prompt text
 - `model` — resolved via the `registry` when provided
@@ -277,14 +281,13 @@ const options = chat.toStreamTextOptions();
 Access the stored prompt from anywhere in the run:
 
 ```ts
-run: async ({ messages, signal }) => {
+run: async ({ messages, signal, streamText }) => {
   const prompt = chat.prompt(); // Throws if not set
   console.log(prompt.text);     // The compiled prompt
   console.log(prompt.model);    // "anthropic:claude-sonnet-4-5"
   console.log(prompt.version);  // 3
 
   return streamText({
-    ...chat.toStreamTextOptions({ registry }),
     messages,
     abortSignal: signal,
     stopWhen: stepCountIs(15),

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

@@ -16,7 +16,7 @@ Declare locals at module level with a unique `id`, then initialize them inside a
 
 ```ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, tool, stepCountIs } from "ai";
+import { tool, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 import { db } from "@/lib/db";
@@ -44,7 +44,7 @@ export const myChat = chat.agent({
       messageCount: user.messageCount,
     });
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     userContext.messageCount++;
 
     return streamText({
@@ -88,7 +88,7 @@ When you use `ai.toolExecute()` inside AI SDK `tool()` to expose a subtask, chat
 ```ts
 import { chat, ai } from "@trigger.dev/sdk/ai";
 import { schemaTask } from "@trigger.dev/sdk";
-import { streamText, tool } from "ai";
+import { tool, stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 
@@ -115,7 +115,7 @@ export const myChat = chat.agent({
   onBoot: async ({ clientData }) => {
     userContext.init({ name: "Alice", plan: "pro" });
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-5"),
       messages,

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

@@ -80,7 +80,7 @@ export const myChat = chat.agent({
     if (preloaded) return; // Already initialized in onPreload
     // ... fallback initialization for non-preloaded runs
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });

package/docs/ai-chat/overview.mdx

@@ -12,12 +12,12 @@ A `chat.agent` task takes `messages`, calls `streamText`, and returns the result
 
 ```ts trigger/chat.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs } from "ai";
+import { stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 
 export const myChat = chat.agent({
   id: "my-chat",
-  run: async ({ messages, signal }) =>
+  run: async ({ messages, signal, streamText }) =>
     streamText({
       model: anthropic("claude-sonnet-4-5"),
       messages,
@@ -56,11 +56,12 @@ See [Quick Start](/ai-chat/quick-start) for the matching server actions and a ru
 
 ## How it fits together
 
-Three primitives, related but distinct:
+Four primitives, related but distinct:
 
 - **Chat agents** — the SDK surface you define with [`chat.agent()`](/ai-chat/backend#chat-agent). Owns the turn loop, lifecycle hooks, and the response stream.
 - **Sessions** — the durable, bi-directional channel keyed on `chatId` that holds the conversation across run boundaries. A chat agent runs *on top of* a [Session](/ai-chat/sessions).
 - **Sub-agents** — Delegate work from one agent to another via [`AgentChat`](/ai-chat/patterns/sub-agents). The sub-agent runs as its own durable agent on its own session; its response streams back through the parent as preliminary tool results, so the frontend sees the sub-agent working inside the parent's tool card.
+- **Channels** connect an agent to a surface other than your frontend. [`slack()`](/webhooks/slack) and [`linear()`](/webhooks/linear) turn an agent into a Slack or Linear agent, and [`chat.channels.custom()`](/webhooks/channels) connects any chat surface that sends webhooks. Each conversation there is still a durable session, and the reply posts back to the surface.
 
 ## Next steps
 

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

@@ -226,7 +226,7 @@ export const myChat = chat.agent({
       }),
     ]);
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
   },
 });
@@ -254,7 +254,7 @@ End-to-end implementation across the three files involved: agent task, server ac
 <CodeGroup>
 ```ts trigger/chat.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs } from "ai";
+import { stepCountIs } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 import { db } from "@/lib/db";
@@ -296,7 +296,7 @@ export const myChat = chat.agent({
       }),
     ]);
   },
-  run: async ({ messages, signal }) => {
+  run: async ({ messages, signal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-5"),
       messages,

package/docs/ai-chat/patterns/native-compaction.mdx

@@ -31,7 +31,7 @@ The fix: read the `appliedEdits` counts as they stream in `onStepFinish`, then a
 
 ```ts /trigger/native-persist.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs, tool, type UIMessage } from "ai";
+import { stepCountIs, tool, type UIMessage } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
 
@@ -75,7 +75,7 @@ export const nativePersist = chat.agent({
   id: "native-persist",
   idleTimeoutInSeconds: 120,
   tools: { fetchRecord },
-  run: async ({ messages, chatId, tools, signal }) => {
+  run: async ({ messages, chatId, tools, signal, streamText }) => {
     return streamText({
       model: anthropic("claude-sonnet-4-5"),
       messages,
@@ -132,7 +132,7 @@ OpenAI's `store: true` keeps the thread server-side and returns a `responseId`.
 
 ```ts /trigger/openai-store.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, stepCountIs, type ModelMessage } from "ai";
+import { stepCountIs, type ModelMessage } from "ai";
 import { openai } from "@ai-sdk/openai";
 
 // Persist the stored-response handle between turns. Replace with your database.
@@ -151,7 +151,7 @@ function messagesSinceLastAssistant(messages: ModelMessage[]): ModelMessage[] {
 export const openaiStore = chat.agent({
   id: "openai-store",
   idleTimeoutInSeconds: 120,
-  run: async ({ messages, chatId, signal }) => {
+  run: async ({ messages, chatId, signal, streamText }) => {
     const native = nativeStore.get(chatId);
     const outbound = native ? messagesSinceLastAssistant(messages) : messages;
 
@@ -186,7 +186,7 @@ A native handle is a per-provider cache. An OpenAI `previousResponseId` means no
 
 ```ts /trigger/resilient-chat.ts
 import { chat } from "@trigger.dev/sdk/ai";
-import { streamText, generateText, stepCountIs, generateId, type ModelMessage } from "ai";
+import { generateText, stepCountIs, generateId, type ModelMessage } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { openai } from "@ai-sdk/openai";
 
@@ -241,7 +241,7 @@ export const resilientChat = chat.agent({
     if (chatId) nativeStore.delete(chatId);
   },
 
-  run: async ({ messages, chatId, signal }) => {
+  run: async ({ messages, chatId, signal, streamText }) => {
     let lastError: unknown;
     for (const providerId of FALLBACK_ORDER) {
       const native = nativeStore.get(chatId);

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

@@ -275,7 +275,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,

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

@@ -1,7 +1,7 @@
 ---
 title: "Trigger.dev docs"
 sidebarTitle: "Introduction"
-description: "Build and run durable AI agents and workflows in TypeScript. Long-running tasks with retries, queues, observability, and elastic scaling. Open source and self-hostable."
+description: "Build and run durable AI agents and workflows in TypeScript. Long-running tasks with retries, queues, webhooks, observability, and elastic scaling. Open source and self-hostable."
 mode: "center"
 ---
 
@@ -11,8 +11,8 @@ import AgentSetupPrompt from "/snippets/agent-setup-prompt.mdx";
   <Card title="Quick start" icon="rocket" href="/quick-start" color="#A8FF53">
     Go from zero to your first task in 3 minutes.
   </Card>
-  <Card title="Build AI agents" icon="robot" href="/guides/ai-agents/overview" color="#a855f7">
-    Agent patterns, worked examples, and the tools to run them in production.
+  <Card title="Build AI agents" icon="robot" href="/ai-chat/overview" color="#a855f7">
+    Durable, multi-turn agents with `chat.agent`, from your frontend to Slack and Linear.
   </Card>
   <Card title="AI coding assistants" icon="wand-magic-sparkles" href="/building-with-ai" color="#3B82F6">
     Let Claude Code, Cursor and Windsurf write correct Trigger.dev code with the MCP server, Skills and rules.
@@ -28,48 +28,124 @@ import AgentSetupPrompt from "/snippets/agent-setup-prompt.mdx";
 
 ## What is Trigger.dev?
 
-Trigger.dev is the open source platform for building and running durable AI agents and workflows in TypeScript. Run them for hours, configure automatic retries, control concurrency, and manage queues. There's no execution timeout, and no queue or worker infrastructure for you to build.
+Trigger.dev is the open source platform for building and running durable AI agents and workflows in TypeScript. You write tasks and agents in your existing codebase, and they run on Trigger.dev with retries, queues, waits, full tracing, and elastic scaling. There's no execution timeout, and no queue or worker infrastructure for you to build.
 
-You write agents and tasks in your existing codebase using our CLI and SDK, and get durable execution, queues, waits, full tracing, and elastic scaling without building any of it yourself.
+Trigger.dev's core is Apache-2.0 licensed. [Self-host it](/self-hosting/overview) on your own infrastructure, or let [Trigger.dev Cloud](https://cloud.trigger.dev) run it for you.
 
-Trigger.dev's core is Apache-2.0 licensed, a genuine OSI license. [Self-host it](/self-hosting/overview) on your own infrastructure, or let [Trigger.dev Cloud](https://cloud.trigger.dev) run it for you.
+## Build agents with `chat.agent`
 
-## Core concepts
+A `chat.agent` runs each conversation as one durable task. It wakes when a message arrives and idles between turns, and its state survives page refreshes, deploys, and crashes. Turn lifecycle, resuming a stream mid-reply, and approvals are handled for you, and your frontend connects with the AI SDK's `useChat`, with no API routes to write.
+
+```ts trigger/chat.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export const supportAgent = chat.agent({
+  id: "support-agent",
+  run: async ({ messages, signal, streamText }) =>
+    streamText({
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      abortSignal: signal,
+    }),
+});
+```
+
+<CardGroup cols={3}>
+  <Card title="Agent quick start" icon="rocket" href="/ai-chat/quick-start">
+    Build a chat agent and its frontend end to end.
+  </Card>
+  <Card title="Sessions" icon="layer-group" href="/ai-chat/sessions">
+    Each conversation's durable state and two-way stream, across all its runs.
+  </Card>
+  <Card title="Tools" icon="screwdriver-wrench" href="/ai-chat/tools">
+    Declare tools on your agent and get them back typed in `run()`.
+  </Card>
+  <Card title="Human in the loop" icon="hand" href="/ai-chat/patterns/human-in-the-loop">
+    Pause a tool call for approval and resume when a person decides.
+  </Card>
+  <Card title="Slack agents" icon="slack" href="/webhooks/slack">
+    Turn an agent into a native Slack agent with `@trigger.dev/slack`.
+  </Card>
+  <Card title="Linear agents" icon="list-check" href="/webhooks/linear">
+    Assign Linear issues to an agent with `@trigger.dev/linear`.
+  </Card>
+</CardGroup>
+
+Version your [prompts](/ai/prompts) in code and change them from the dashboard, and see every model step and tool call, with tokens, cost and latency, in [AI observability](/ai/observability).
+
+## Run work
 
 <CardGroup cols={2}>
   <Card title="Writing tasks" icon="pen-to-square" href="/tasks/overview" color="#A8FF53">
-    The durable functions at the core of Trigger.dev. Write them in your existing codebase, with retries and no timeouts.
+    The durable functions at the core of Trigger.dev, written in your existing codebase.
   </Card>
   <Card title="Triggering tasks" icon="bullseye-pointer" href="/triggering" color="#3b82f6">
-    Trigger a task from your backend, your frontend, a schedule, or another task.
+    Trigger a task from your backend, your frontend, or another task.
   </Card>
   <Card title="Runs" icon="play" href="/runs" color="#28bf5c">
-    Every execution of a task is a run, with its status, retries, and logs recorded.
+    Every execution of a task is a run, with its status, retries, logs and trace.
+  </Card>
+  <Card title="Realtime" icon="bolt" href="/realtime/overview" color="#F43F5E">
+    Stream run status and LLM output to your frontend with React hooks.
+  </Card>
+</CardGroup>
+
+## React to events
+
+<CardGroup cols={2}>
+  <Card title="Webhooks" icon="webhook" href="/webhooks/overview" color="#a855f7">
+    Hosted, verified endpoints for Stripe, GitHub and more, delivered to your tasks and agents.
+  </Card>
+  <Card title="Scheduled tasks" icon="clock" href="/tasks/scheduled" color="#f6cd46">
+    Run a task on a cron schedule, with timezone support.
+  </Card>
+  <Card title="Webhook waiters" icon="bell" href="/webhooks/waiters" color="#3b82f6">
+    Pause a run until a matching webhook arrives, like a payment confirmation.
   </Card>
-  <Card title="Idempotency" icon="fingerprint" href="/idempotency" color="#F43F5E">
-    Use an idempotency key so a retried or duplicated trigger runs once, not twice.
+  <Card title="Waits" icon="hourglass" href="/wait" color="#28bf5c">
+    Pause a run for a duration, until a date, or until a token is completed. A waiting run doesn't use compute.
   </Card>
 </CardGroup>
 
-## Build with agents
+## Run in production
 
-Build durable, multi-turn agents with the [chat agent](/ai-chat/overview): one long-running task per conversation, with the tools it can call, streaming, and resumability handled for you. Add human-in-the-loop approval by pausing a run on a [waitpoint](/wait-for-token) until a person signs off, and a waiting run doesn't consume compute. Stream run status and LLM output straight to your frontend with the [Realtime API](/realtime/overview) and React hooks, and record your Vercel AI SDK calls as spans with the model, token counts, cost and latency using [AI observability](/ai/observability). Version your [prompts](/ai/prompts) in code, then edit the text or swap the model from the dashboard without redeploying.
+<CardGroup cols={2}>
+  <Card title="Queues & concurrency" icon="layer-group" href="/queues" color="#3b82f6">
+    Control how many runs execute at once, globally or per tenant.
+  </Card>
+  <Card title="Machines" icon="microchip" href="/machines" color="#a855f7">
+    Choose the CPU and memory each task runs on.
+  </Card>
+  <Card title="Deployment" icon="cloud-arrow-up" href="/deployment/overview" color="#28bf5c">
+    Atomic, versioned deploys, with preview branches and environments.
+  </Card>
+  <Card title="Errors & retries" icon="arrows-rotate" href="/errors-retrying" color="#F43F5E">
+    Retry failed attempts automatically, and decide what happens when a task throws.
+  </Card>
+  <Card title="Logs, traces & metrics" icon="chart-line" href="/logging" color="#f6cd46">
+    A full trace of every run, with your logs and spans.
+  </Card>
+  <Card title="Query & dashboards" icon="table" href="/observability/query" color="#A8FF53">
+    Query your runs with TRQL, and build dashboards from the results.
+  </Card>
+</CardGroup>
 
-## Scale and scheduling
+## Frequently asked questions
 
-Set how many runs of a task execute at once, globally or per tenant, with [concurrency](/concurrency) and [queues](/queues). Run a task on a [cron schedule](/tasks/scheduled) with timezone support, choose the CPU and memory each task runs on with [machines](/machines), and control what happens when a task throws with [errors and retries](/errors-retrying).
+**Can I use Trigger.dev for background jobs, not just AI?** Yes. The same durable tasks, queues, retries, and [cron schedules](/tasks/scheduled) run any background job or workflow, with or without AI.
 
-## Self-hosting
+**How long can a run take?** As long as it needs. Runs have no maximum duration by default, and you can set a [`maxDuration`](/runs/max-duration) for a project, a task, or a single run to cap it.
 
-Trigger.dev is open source and you can self-host. Read the [overview guide](/self-hosting/overview), or how to do it with [Docker](/self-hosting/docker) or [Kubernetes](/self-hosting/kubernetes).
+**Do my serverless function timeouts apply?** No. Tasks run on Trigger.dev, not inside your serverless functions, so your platform's function timeout isn't in the execution path. Your backend triggers the task and returns.
 
-## Frequently asked questions
+**Can I receive webhooks without running a server?** Yes. Declare a [webhook endpoint](/webhooks/overview) in your code, and Trigger.dev hosts its URL, verifies each request, and delivers the event to your tasks and agents.
 
-**How do I add human-in-the-loop approval to an agent?** Pause the run on a [waitpoint](/wait-for-token) until a person approves the action. A waiting run doesn't consume compute, so it can wait minutes or days.
+**How do I add human-in-the-loop approval?** Pause the run on a [waitpoint](/wait-for-token) until a person approves, or use a [chat agent's approvals](/ai-chat/patterns/human-in-the-loop) for tool calls. A waiting run doesn't use compute, so it can wait minutes or days.
 
 **Does Trigger.dev support tool calling and MCP?** Yes. Agents call the tools you define, and the [MCP server](/building-with-ai) lets AI coding assistants trigger tasks, deploy, and read run traces.
 
-**Can I use Trigger.dev for background jobs, not just AI?** Yes. The same durable tasks, queues, retries, and [cron schedules](/tasks/scheduled) run any background job or workflow, with or without AI.
+**Can I self-host?** Yes. Trigger.dev is open source. Read the [self-hosting overview](/self-hosting/overview), or set it up with [Docker](/self-hosting/docker) or [Kubernetes](/self-hosting/kubernetes).
 
 ## Getting help
 
@@ -85,7 +161,7 @@ We'd love to hear from you or give you a hand getting started. Here are some way
     Our Discord is the best place to get help with any questions about Trigger.dev.
   </Card>
   <Card
-    title="Follow us on X (Twitter)"
+    title="Follow us on X"
     icon={
       <svg xmlns="http://www.w3.org/2000/svg" height="20" viewBox="0 0 512 512">
         <path d="M389.2 48h70.6L305.6 224.2 487 464H345L233.7 318.6 106.5 464H35.8L200.7 275.5 26.8 48H172.4L272.9 180.9 389.2 48zM364.4 421.8h39.1L151.1 88h-42L364.4 421.8z" />
@@ -112,7 +188,7 @@ We'd love to hear from you or give you a hand getting started. Here are some way
     href="https://github.com/triggerdotdev/trigger.dev"
     color="#fbbf24"
   >
-    Check us out our GitHub repo and give us a star if you like what we're doing.
+    Check out our GitHub repo, and give us a star if you like what we're doing.
   </Card>
 </CardGroup>
 
@@ -122,12 +198,16 @@ We'd love to hear from you or give you a hand getting started. Here are some way
 
 **Current major version:** v4 (`@trigger.dev/sdk` 4.x). Documentation under `/docs/v2` and `/docs/v3` describes superseded versions and should not be used.
 
-**Execution model:** tasks run on Trigger.dev infrastructure, not inside your serverless functions, so a platform function timeout is not in the execution path. A task runs until it finishes; you can cap runtime with `maxDuration` (minimum 5 seconds).
+**Execution model:** tasks run on Trigger.dev infrastructure, not inside your serverless functions, so a platform function timeout is not in the execution path. Runs have no maximum duration by default; `maxDuration` caps a run's compute time for a project, a task, or a single run, and `timeout.None` removes the cap.
 
 **Deploys:** each deploy is an atomic version. A run already in progress is not affected by code shipped after it started.
 
 **Durability and retries:** retries are automatic and configurable. A failed attempt is retried according to the task's retry settings; once retries are exhausted the run ends terminally as `FAILED`, and some crashes (for example out of memory) end the run as `CRASHED` without a retry. Idempotency keys deduplicate the task triggers and waits you key, so the same key runs once instead of again.
 
+**Agents:** `chat.agent` is imported from `@trigger.dev/sdk/ai`, not from `@trigger.dev/sdk`. Inside `run()`, call the `streamText` passed in the run options. It records each model step and tool call as a span by default. Slack and Linear agents use the `@trigger.dev/slack` and `@trigger.dev/linear` packages, and `slack()` requires a `startOn` filter (`appMentions()` answers @mentions).
+
+**Webhooks:** `webhooks.endpoint.define()` declares a hosted, verified endpoint that syncs on `trigger dev` and on deploy; `webhook()` subscribes a task with a filter, and `webhooks.waiter` pauses a run until a matching event arrives. Both come from `@trigger.dev/sdk`.
+
 **License:** the platform core is Apache-2.0 and the `@trigger.dev/sdk` package is MIT, permissive open source, not fair-code or source-available. Some features are gated, but the open source core is not relicensed or held back.
 
 **LLM observability coverage:** only Vercel AI SDK calls (`generateText`, `streamText`, `generateObject`) are recorded as spans. Raw `fetch` calls and provider SDKs used directly are not captured.

package/docs/mcp-tools.mdx

@@ -411,6 +411,10 @@ Generate a new signing secret for an endpoint and return it once, for providers
 
 **Parameters:**
 - `endpointId` (required): the endpoint's declared id (such as `payments`) or `wh_` id
+- `previousSecretTtlSeconds` (optional): keep accepting the replaced secret for this many seconds (up to 604800, 7 days) while the provider switches to the new one. Omit it, or pass `0`, to replace the secret immediately, for example when it leaked. The response says when the old secret stops working.
+
+**Example usage:**
+- `"Rotate the GitHub endpoint's secret and keep the old one working for a day"`
 
 ### set_webhook_secret
 
@@ -419,6 +423,7 @@ Store a signing secret or public key the provider issued, such as Stripe's `whse
 **Parameters:**
 - `endpointId` (required): the endpoint's declared id (such as `payments`) or `wh_` id
 - `secret` (required): the secret or public key
+- `previousSecretTtlSeconds` (optional): keep accepting the replaced secret for this many seconds (up to 604800, 7 days) while the provider switches to the new one. Omit it, or pass `0`, to replace the secret immediately, for example when it leaked. The response says when the old secret stops working.
 
 <Callout type="warning">
   `replay_webhook_delivery`, `generate_webhook_secret` and `set_webhook_secret` are write operations and are not available in readonly mode.

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

@@ -52,6 +52,7 @@ mode: "wide"
 | `KUBERNETES_IMAGE_PULL_SECRETS`             | No       | —           | Image pull secrets (CSV).                                   |
 | `KUBERNETES_EPHEMERAL_STORAGE_SIZE_LIMIT`   | No       | 10Gi        | Ephemeral storage size limit. Applies to all runs.          |
 | `KUBERNETES_EPHEMERAL_STORAGE_SIZE_REQUEST` | No       | 2Gi         | Ephemeral storage size request. Applies to all runs.        |
+| `KUBERNETES_POD_RESERVED_SOURCE_PORTS`      | No       | —           | Ports runs never use as the source port of an outbound connection, so they can't clash with services on those ports. CSV of ports or ranges, e.g. `50080,50081` or `50080-50090`. Sets the pod's `net.ipv4.ip_local_reserved_ports` sysctl. |
 | **Metrics**                                 |          |             |                                                             |
 | `METRICS_ENABLED`                           | No       | true        | Enable metrics.                                             |
 | `METRICS_COLLECT_DEFAULTS`                  | No       | true        | Collect default metrics.                                    |

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

@@ -192,6 +192,18 @@ mode: "wide"
 | `RUN_ENGINE_DEFAULT_MAX_TTL`                     | No       | —                     | Maximum TTL for all runs (e.g. "14d"). Runs without a TTL use this as default; runs with a larger TTL are clamped. |
 | `MAXIMUM_DEV_QUEUE_SIZE`                         | No       | —                     | Maximum queued runs per queue in development environments.                                                         |
 | `MAXIMUM_DEPLOYED_QUEUE_SIZE`                    | No       | —                     | Maximum queued runs per queue in deployed (staging/prod) environments.                                             |
+| **Webhooks**                                     |          |                       |                                                                                                                    |
+| `WEBHOOK_ENABLED`                                | No       | 0                     | Set to `1` to run hosted webhooks: ingest, delivery and waiters. See [Webhooks](#webhooks). |
+| `WEBHOOK_REDIS_HOST`                             | No       | localhost             | A node of the Redis cluster webhooks use for their queue and waiters. It must run in cluster mode. |
+| `WEBHOOK_REDIS_PORT`                             | No       | 6379                  | Port of that node. |
+| `WEBHOOK_REDIS_USERNAME`                         | No       | —                     | Webhooks Redis username. |
+| `WEBHOOK_REDIS_PASSWORD`                         | No       | —                     | Webhooks Redis password. |
+| `WEBHOOK_REDIS_TLS_DISABLED`                     | No       | `REDIS_TLS_DISABLED`  | Set to `true` to connect to the webhooks Redis without TLS. |
+| `WEBHOOK_INGRESS_ORIGIN`                         | No       | `API_ORIGIN`          | Public origin of the webhook URLs, for when you serve them from their own host. |
+| `WEBHOOK_INGRESS_BODY_SIZE_LIMIT_MB`             | No       | 1                     | Largest webhook request body accepted, in MB. |
+| `WEBHOOK_DATABASE_URL`                           | No       | `DATABASE_URL`        | A separate PostgreSQL database for webhook endpoints and deliveries. |
+| `WEBHOOK_DELIVERY_RETENTION_DAYS`                | No       | 30                    | How many days of deliveries the dashboard and API show. It doesn't delete anything: deliveries are kept for `WEBHOOK_DELIVERY_STORAGE_DAYS`, or longer when this is higher. |
+| `WEBHOOK_DELIVERY_STORAGE_DAYS`                  | No       | 30                    | How long deliveries are stored before they're deleted. Must be one of `3`, `7`, `30`, `90`, `180` or `365`; any other value stops the webapp from starting. |
 | **Misc**                                         |          |                       |                                                                                                                    |
 | `TRIGGER_TELEMETRY_DISABLED`                     | No       | —                     | Disable telemetry.                                                                                                 |
 | `NODE_MAX_OLD_SPACE_SIZE`                        | No       | 8192                  | Maximum memory allocation for Node.js heap in MiB (e.g. "4096" for 4GB).                                           |
@@ -202,6 +214,18 @@ mode: "wide"
 | `ADMIN_DASHBOARD_ENABLED`                        | No       | 1                     | Set to anything other than `1` or `true` to disable the admin dashboard and user impersonation on this instance.   |
 | `EVENT_LOOP_MONITOR_ENABLED`                     | No       | 1                     | Node.js event loop lag monitor.                                                                                    |
 
+## Webhooks
+
+Hosted webhooks are off on a self-hosted instance until you turn them on:
+
+1. Run a Redis (or Valkey) cluster for webhooks and point `WEBHOOK_REDIS_HOST` and `WEBHOOK_REDIS_PORT` at one of its nodes. The webhook engine connects in cluster mode, so a standalone Redis won't work.
+2. Set `WEBHOOK_ENABLED=1` on the webapp.
+3. Give organizations access with the `hasWebhooksAccess` feature flag: turn it on for everyone on the admin dashboard's **Global Feature Flags** page, or for one organization from its feature flags on the **Organizations** page. An organization without it doesn't see Webhooks in the dashboard, and its deploys don't sync endpoints.
+
+Webhook URLs are served from `WEBHOOK_INGRESS_ORIGIN`, which defaults to `API_ORIGIN`, so providers need to reach that origin from the internet.
+
+The Docker Compose setup only passes the variables listed under the webapp service's `environment` in `hosting/docker/webapp/docker-compose.yml`, so add the webhook variables there. With the Helm chart, set them in `webapp.extraEnvVars`.
+
 ## Multi-Provider Object Storage
 
 The object storage system supports multiple S3-compatible providers (R2, S3, GCS, MinIO, etc.) using protocol prefixes. This enables migrating between providers without breaking existing runs.

package/docs/self-hosting/overview.mdx

@@ -121,6 +121,8 @@ You own a custom base image. It must provide:
 
 A `DEPLOY_BUILD_BASE_IMAGES` image needs everything the base image provides, plus `python3`, `make` and `g++`. Build extensions that add image instructions are replayed on it. Without an entry, the build stage uses the published build image, except for projects whose build extensions add image instructions: those build from your base image and install the toolchain with `apt-get`, so that base must be Debian-based. To avoid the published images entirely, set both variables.
 
+A custom image is yours to harden. Deploys on the published images remove trust in publicly compromised certificate authorities and point Node.js and Python at the OS trust store. Stages built on a custom image get neither, and run with the certificate settings the image ships with. Keeping a custom image patched, trust store included, is your responsibility.
+
 <Warning>
   `image.pkgs` and build extensions that run `apt-get` (such as `aptGet` and `playwright`) assume a
   Debian base. On other distributions, install those packages in your base image instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "4.8.0",
+  "version": "4.8.1",
   "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.0",
+    "@trigger.dev/core": "4.8.1",
     "uncrypto": "^0.1.3"
   },
   "devDependencies": {