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

package/dist/esm/v3/webhooks.js

@@ -1,5 +1,8 @@
-import { Webhook } from "@trigger.dev/core/v3";
+import { Webhook, resourceCatalog } from "@trigger.dev/core/v3";
 import { subtle } from "../imports/uncrypto.js";
+import { cancelWebhookWaiter, createWebhookWaiter, waitForWebhookWaiter, } from "./webhookWaiters.js";
+import { createTask } from "./shared.js";
+import { discordVerifierConfig, githubVerifierConfig, squareVerifierConfig, standardWebhooksVerifierConfig, stripeVerifierConfig, svixVerifierConfig, webhookProviderConfigs, webhookSetupPrompts, } from "@trigger.dev/core/webhooks";
 /**
  * The type of error thrown when a webhook fails to parse or verify
  */
@@ -11,12 +14,326 @@ export class WebhookError extends Error {
 }
 /** Header name used for webhook signatures */
 const SIGNATURE_HEADER_NAME = "x-trigger-signature-hmacsha256";
+// ── Source producers (presets carry the event type) ──
+export const webhookSources = {
+    custom(config, options) {
+        if (config.scheme === "url-secret" && config.placement === "path") {
+            throw new Error('webhooks.custom(): url-secret verification cannot use placement "path" on the hosted ingress URL. Use placement "query" or a header-based scheme.');
+        }
+        // Roll-your-own webhooks: you control both ends, so offer paste AND generate.
+        return {
+            provider: "custom",
+            verifier: {
+                kind: "config",
+                config,
+                ...(options?.response ? { response: options.response } : {}),
+            },
+            secretProvisioning: "either",
+            ...(options?.setupPrompt ? { setupPrompt: options.setupPrompt } : {}),
+        };
+    },
+    // Stripe: `Stripe-Signature: t=…,v1=…` (comma-kv), signed `{t}.{body}`, hex.
+    // Defaults to a minimal event shape; pass the official type for full typing: stripe<Stripe.Event>().
+    stripe(opts) {
+        return {
+            provider: "stripe",
+            verifier: { kind: "preset", preset: "stripe", config: stripeVerifierConfig(opts) },
+            secretProvisioning: "provider",
+        };
+    },
+    // GitHub: `X-Hub-Signature-256: sha256=<hex>` (prefixed), signed raw body.
+    // Defaults to an open shape; pass your event type for full typing: github<MyPushEvent>().
+    github() {
+        return {
+            provider: "github",
+            verifier: { kind: "preset", preset: "github", config: githubVerifierConfig() },
+            secretProvisioning: "integrator",
+        };
+    },
+    // Svix family (Svix, Clerk, Resend): `svix-signature: v1,<b64> v1,<b64>` (space-list),
+    // signed `{id}.{timestamp}.{body}`, base64; the `whsec_` secret is base64-decoded. Providers that
+    // send the spec's `webhook-*` header names instead use `standardWebhooks()`.
+    svix() {
+        return {
+            provider: "svix",
+            verifier: { kind: "preset", preset: "svix", config: svixVerifierConfig() },
+            secretProvisioning: "provider",
+        };
+    },
+    // Standard Webhooks (Composio, and any provider implementing the spec directly): the Svix scheme under
+    // the spec's `webhook-id` / `webhook-timestamp` / `webhook-signature` header names.
+    standardWebhooks() {
+        return {
+            provider: "standard-webhooks",
+            verifier: {
+                kind: "preset",
+                preset: "standard-webhooks",
+                config: standardWebhooksVerifierConfig(),
+            },
+            secretProvisioning: "provider",
+        };
+    },
+    // Square: bare base64 signature over `{notificationURL}{body}` (URL template var, no separator).
+    square() {
+        return {
+            provider: "square",
+            verifier: { kind: "preset", preset: "square", config: squareVerifierConfig() },
+            secretProvisioning: "provider",
+        };
+    },
+    /**
+     * Discord: asymmetric Ed25519 over `{timestamp}{body}`. The "secret" stored on the endpoint is the
+     * application PUBLIC KEY (hex by default); there is no shared secret. Discord's response contract
+     * is declared as data on the artifact: the `{ type: 0 }` PING sent when the URL is saved is answered
+     * with a bodiless 204 and never recorded, accepted events are acknowledged with 204, and a bad
+     * signature gets 401.
+     */
+    discord(opts = {}) {
+        return {
+            provider: "discord",
+            verifier: {
+                kind: "preset",
+                preset: "discord",
+                config: discordVerifierConfig(opts),
+                handshake: { matchPath: "type", matchValue: "0", respondStatus: 204 },
+                response: { acceptedStatus: 204, rejectedStatus: 401 },
+            },
+            secretProvisioning: "provider",
+        };
+    },
+    /**
+     * Per-provider producers over shared presets. Each is a thin wrapper: same verifier config as the
+     * preset it references, differing only in `provider` (routing + picker identity) and who provisions
+     * the secret. Pass the provider's own published type for full typing, e.g. clerk<WebhookEvent>().
+     */
+    clerk() {
+        return {
+            provider: "clerk",
+            verifier: { kind: "preset", preset: "svix", config: svixVerifierConfig() },
+            secretProvisioning: "provider",
+        };
+    },
+    resend() {
+        return {
+            provider: "resend",
+            verifier: { kind: "preset", preset: "svix", config: svixVerifierConfig() },
+            secretProvisioning: "provider",
+        };
+    },
+    openai() {
+        return {
+            provider: "openai",
+            verifier: {
+                kind: "preset",
+                preset: "standard-webhooks",
+                config: standardWebhooksVerifierConfig(),
+            },
+            secretProvisioning: "provider",
+        };
+    },
+    replicate() {
+        return {
+            provider: "replicate",
+            verifier: {
+                kind: "preset",
+                preset: "standard-webhooks",
+                config: standardWebhooksVerifierConfig(),
+            },
+            secretProvisioning: "provider",
+        };
+    },
+    recallai() {
+        return {
+            provider: "recall-ai",
+            verifier: {
+                kind: "preset",
+                preset: "standard-webhooks",
+                config: standardWebhooksVerifierConfig(),
+            },
+            secretProvisioning: "provider",
+        };
+    },
+    brex() {
+        return {
+            provider: "brex",
+            verifier: { kind: "preset", preset: "svix", config: svixVerifierConfig() },
+            secretProvisioning: "provider",
+        };
+    },
+    composio() {
+        return {
+            provider: "composio",
+            verifier: {
+                kind: "preset",
+                preset: "standard-webhooks",
+                config: standardWebhooksVerifierConfig(),
+            },
+            secretProvisioning: "provider",
+        };
+    },
+    gitlab() {
+        return {
+            provider: "gitlab",
+            verifier: {
+                kind: "config",
+                config: { scheme: "shared-secret", placement: "header", fieldName: "x-gitlab-token" },
+            },
+            secretProvisioning: "integrator",
+        };
+    },
+    /**
+     * WhatsApp Cloud API (Meta): `X-Hub-Signature-256` HMAC over the raw body, keyed by the App Secret,
+     * which Meta issues and you paste in as the endpoint's signing secret (it cannot be generated here).
+     * Meta verifies the callback URL with a GET carrying `hub.mode`, `hub.verify_token` and
+     * `hub.challenge`; the endpoint answers it when the token equals the verify token generated in
+     * the endpoint's Connect panel, which you paste into Meta's Verify Token field.
+     */
+    whatsapp() {
+        return {
+            provider: "whatsapp",
+            verifier: {
+                kind: "preset",
+                preset: "github",
+                config: githubVerifierConfig(),
+                getHandshake: {
+                    matchParam: "hub.mode",
+                    matchValue: "subscribe",
+                    tokenParam: "hub.verify_token",
+                    challengeParam: "hub.challenge",
+                },
+            },
+            secretProvisioning: "provider",
+        };
+    },
+};
+function producerName(provider) {
+    return provider.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+export const providerProducers = Object.fromEntries(Object.entries(webhookProviderConfigs)
+    // Zoom needs a computed URL-validation response that the hosted ingress does not support yet.
+    .filter(([provider]) => provider !== "slack" && provider !== "zoom")
+    .map(([provider, entry]) => [
+    producerName(provider),
+    () => {
+        const setupPrompt = webhookSetupPrompts[provider];
+        return {
+            provider,
+            verifier: { kind: "config", config: entry.config() },
+            secretProvisioning: entry.secretProvisioning,
+            ...(setupPrompt ? { setupPrompt } : {}),
+        };
+    },
+]));
+/**
+ * Declare a webhook endpoint: one URL you register with the provider. Subscribe to it with
+ * `webhook({ endpoint })`, `chat.event({ endpoint })` or a channel connector, and wait on it with
+ * `webhooks.waiter.create(endpoint, ...)`. An endpoint with no subscribers still gets a URL.
+ */
+export function defineWebhookEndpoint(options) {
+    const { id, source, description, metadata } = options;
+    if (id.startsWith("wh_")) {
+        throw new Error(`webhooks.endpoint.define("${id}"): an endpoint id can't start with "wh_"; that prefix is reserved for generated endpoint ids.`);
+    }
+    const setupPrompt = source.setupPrompt ??
+        (source.verifier.kind === "preset"
+            ? webhookSetupPrompts[source.verifier.preset]
+            : undefined);
+    resourceCatalog.registerWebhookEndpointMetadata({
+        id,
+        source: source.provider,
+        verifierArtifact: source.verifier,
+        ...(description ? { description } : {}),
+        ...(source.secretProvisioning ? { secretProvisioning: source.secretProvisioning } : {}),
+        ...(setupPrompt ? { setupPrompt } : {}),
+        ...(metadata ? { metadata } : {}),
+    });
+    return { id, source: source.provider };
+}
+export function webhook(options) {
+    const { id, endpoint, onEvent, filter } = options;
+    if (!endpoint?.id) {
+        throw new Error(`webhook("${id}"): an endpoint is required. Declare one with webhooks.endpoint.define() and pass it as { endpoint }.`);
+    }
+    const task = createTask({
+        id,
+        triggerSource: "webhook",
+        run: async (payload, runOptions) => {
+            await onEvent({
+                event: payload.event,
+                headers: new Headers(payload.headers ?? {}),
+                endpoint: payload.endpoint,
+                ctx: runOptions.ctx,
+            });
+        },
+    });
+    resourceCatalog.registerWebhookSubscriber({
+        endpointId: endpoint.id,
+        target: { type: "task", id, taskId: id, ...(filter ? { filter } : {}) },
+    });
+    return task;
+}
+// ── chat.event(): a session subscriber an agent claims via chat.agent({ events }). No handler. ──
+// Carries the endpoint, a validated string `key`, and a `type` discriminant. The `key` validates
+// against the event/header/webhook namespaces, like a filter path, and compiles to the stored
+// {body.x} wire template.
+export function chatEvent(options) {
+    const { id, endpoint, key, type, filter } = options;
+    if (!endpoint?.id) {
+        throw new Error(`chat.event("${id}"): an endpoint is required. Declare one with webhooks.endpoint.define() and pass it as { endpoint }.`);
+    }
+    // Record the descriptor as declared so the indexer can flag it if no agent ever claims it.
+    resourceCatalog.registerDeclaredSessionWebhook(id);
+    return {
+        id,
+        type: type ?? id,
+        key: normalizeKeyString(key),
+        endpointId: endpoint.id,
+        source: endpoint.source,
+        filter,
+    };
+}
+/**
+ * Compiles a key template to its stored form. Each placeholder names its namespace the way a filter
+ * path does: `{event.x}` reads the event body (stored as `{body.x}`), `{header.x}` a header and
+ * `{webhook.x}` the endpoint. A placeholder without one of those namespaces throws.
+ */
+export function normalizeKeyString(key) {
+    const namespaceAlternative = (alternative) => {
+        const trimmed = alternative.trim();
+        if (trimmed.startsWith("event."))
+            return `body.${trimmed.slice("event.".length)}`;
+        if (trimmed.startsWith("webhook.") || trimmed.startsWith("header."))
+            return trimmed;
+        const path = trimmed.startsWith("body.") ? trimmed.slice("body.".length) : trimmed;
+        throw new Error(`Invalid key "${key}": "{${trimmed}}" needs a namespace. Use {event.${path}} for the event body, {header.<name>} or {webhook.<field>}.`);
+    };
+    return key.replace(/\{([^{}]+)\}/g, (_match, path) => `{${path.split("||").map(namespaceAlternative).join(" || ")}}`);
+}
 /**
  * Webhook utilities for handling incoming webhook requests
  */
 export const webhooks = {
+    ...providerProducers,
     constructEvent,
     SIGNATURE_HEADER_NAME,
+    custom: webhookSources.custom,
+    stripe: webhookSources.stripe,
+    github: webhookSources.github,
+    svix: webhookSources.svix,
+    standardWebhooks: webhookSources.standardWebhooks,
+    square: webhookSources.square,
+    discord: webhookSources.discord,
+    clerk: webhookSources.clerk,
+    resend: webhookSources.resend,
+    openai: webhookSources.openai,
+    replicate: webhookSources.replicate,
+    recallai: webhookSources.recallai,
+    brex: webhookSources.brex,
+    composio: webhookSources.composio,
+    gitlab: webhookSources.gitlab,
+    whatsapp: webhookSources.whatsapp,
+    endpoint: { define: defineWebhookEndpoint },
+    waiter: { create: createWebhookWaiter, wait: waitForWebhookWaiter, cancel: cancelWebhookWaiter },
 };
 async function constructEvent(request, secret) {
     let payload;

package/dist/esm/v3/webhooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../../src/v3/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAEhD;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,8CAA8C;AAC9C,MAAM,qBAAqB,GAAG,gCAAgC,CAAC;AAwC/D;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAa;IAChC,cAAc;IACd,qBAAqB;CACtB,CAAC;AAEF,KAAK,UAAU,cAAc,CAC3B,OAAwC,EACxC,MAAc;IAEd,IAAI,OAAe,CAAC;IACpB,IAAI,SAAiB,CAAC;IAEtB,IAAI,OAAO,YAAY,OAAO,EAAE,CAAC;QAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,YAAY,CAAC,kDAAkD,CAAC,CAAC;QAC7E,CAAC;QAED,MAAM,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QACnE,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,MAAM,IAAI,YAAY,CAAC,2BAA2B,CAAC,CAAC;QACtD,CAAC;QACD,SAAS,GAAG,eAAe,CAAC;QAE5B,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;IACjC,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QAErC,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,YAAY,CAAC,qCAAqC,CAAC,CAAC;QAChE,CAAC;QACD,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;IACxC,CAAC;IAED,uBAAuB;IACvB,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IAElE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,YAAY,CAAC,mBAAmB,CAAC,CAAC;IAC9C,CAAC;IAED,iCAAiC;IACjC,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACxC,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QACjD,OAAO,aAAa,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,MAAM,IAAI,YAAY,CAAC,2BAA2B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACrE,CAAC;QACD,MAAM,IAAI,YAAY,CAAC,wBAAwB,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,KAAK,UAAU,eAAe,CAC5B,OAAe,EACf,SAAiB,EACjB,MAAc;IAEd,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,YAAY,CAAC,+CAA+C,CAAC,CAAC;QAC1E,CAAC;QAED,4CAA4C;QAC5C,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAClD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAEhD,wBAAwB;QACxB,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,SAAS,CAChC,KAAK,EACL,UAAU,EACV,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EACjC,KAAK,EACL,CAAC,MAAM,EAAE,QAAQ,CAAC,CACnB,CAAC;QAEF,mCAAmC;QACnC,MAAM,eAAe,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;QACpE,MAAM,kBAAkB,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAExE,kDAAkD;QAClD,OAAO,eAAe,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;IACxD,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QAChB,MAAM,IAAI,YAAY,CAAC,+BAA+B,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED,mDAAmD;AACnD,SAAS,eAAe,CAAC,CAAS,EAAE,CAAS;IAC3C,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,MAAM,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,MAAM,KAAK,CAAC,CAAC;AACtB,CAAC"}
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../../src/v3/webhooks.ts"],"names":[],"mappings":"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"}

package/dist/esm/version.js

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

package/docs/ai-chat/actions.mdx

@@ -73,11 +73,16 @@ onAction: async ({ action }) => {
       chat.history.slice(0, -1);
       chat.inject([{ role: "system", content: "Answer formally this time." }]);
       return chat.turn(); // with a one-shot instruction
+
+    case "ask":
+      return chat.turn(action.question); // answer a new user message
   }
 }
 ```
 
-`run()` receives the edited history with no incoming user message, the same shape as a `regenerate-message` turn, and its `trigger` is `"action-turn"`, so a `run()` that returns early on `"action"` (the pre-May behaviour, when actions invoked `run()` directly) still answers. Returning anything other than `chat.turn()` or nothing is an error; a response can no longer be returned from `onAction` directly.
+`chat.turn(message)` appends `message` (a string, or a `UIMessage`) to the history as a user message after the edit, and the turn answers it. That is how a button click becomes a question, such as a follow-up suggestion in [Slack](/webhooks/slack#buttons-that-send-the-agent-an-action).
+
+Without a message, `run()` receives the edited history with no incoming user message, the same shape as a `regenerate-message` turn, and its `trigger` is `"action-turn"`, so a `run()` that returns early on `"action"` (the pre-May behaviour, when actions invoked `run()` directly) still answers. Returning anything other than `chat.turn()` or nothing is an error; a response can no longer be returned from `onAction` directly.
 
 ### Actions and persistence
 

package/docs/ai-chat/backend.mdx

@@ -497,6 +497,40 @@ Custom actions let the frontend send structured commands (undo, rollback, edit,
 
 See [Actions](/ai-chat/actions).
 
+### Webhook events and channels
+
+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
+import { webhooks } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+import { slack, webhookSource } from "@trigger.dev/slack";
+
+const slackEvents = webhooks.endpoint.define({ id: "slack", source: webhookSource() });
+const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe() });
+
+export const orderEvents = chat.event({
+  id: "order-events",
+  endpoint: stripe,
+  key: "{event.data.object.customer}",
+  type: "order.event",
+});
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  events: [orderEvents],
+  channels: [slack({ id: "support-slack", endpoint: slackEvents, token: process.env.SLACK_BOT_TOKEN! })],
+  onAction: async ({ action }) => {
+    // A verified order-events delivery arrives here as an action.
+  },
+  run: async (payload) => {
+    // Inbound Slack messages run here as normal turns.
+  },
+});
+```
+
+See [session routing](/webhooks/session-routing) and [channels](/webhooks/channels). For the interactive approvals layer, where a turn pauses on a human decision (buttons in the thread) and resumes on the click, see [human-in-the-loop](/webhooks/human-in-the-loop).
+
 ### Chat history
 
 Imperative API for reading and modifying the accumulated message history. Works from any hook (`onAction`, `onTurnStart`, `onBeforeTurnComplete`, `onTurnComplete`, `hydrateMessages`) or from `run()` and AI SDK tools.

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

@@ -134,6 +134,39 @@ The parent LLM naturally calls this tool multiple times:
 2. `researchAgent({ conversationId: "competitors", message: "Go deeper on pricing" })` — same run, sub-agent has full context
 3. `researchAgent({ conversationId: "new-topic", message: "..." })` — different ID = different sub-agent
 
+## Limiting parallel sub-agents per session
+
+Give every sub-agent task a shared named limit with a `perKey`, pass the parent session's id as each sub-agent's `concurrencyKey`, and raise that key's cap when the user picks a parallelism:
+
+```ts trigger/limits.ts
+import { concurrencyLimit } from "@trigger.dev/sdk";
+
+// one sub-agent at a time per session unless a session is given more
+export const subagentsLimit = concurrencyLimit({ name: "subagents", perKey: 1 });
+```
+
+```ts trigger/research-agent.ts
+export const researchAgent = chat.agent({
+  id: "research-agent",
+  concurrency: subagentsLimit,
+  // ...
+});
+```
+
+```ts
+// in the parent agent, once per session, when the user picks a parallelism of 3
+await concurrencyLimits.override("subagents", { concurrencyKey: sessionId, perKey: 3 });
+
+// every sub-agent for this session carries the session's key
+const agent = new AgentChat({
+  agent: "research-agent",
+  id: conversationId,
+  triggerConfig: { concurrencyKey: sessionId },
+});
+```
+
+Three sub-agent runs for this session execute at once; a fourth waits. Other sessions keep the declared cap of one, and any tenant-level limit the sub-agent task also holds keeps applying. The override expires after 7 days by default (`ttl` sets it, up to 30 days), so a session that outlives that should call `override` again. See [Overriding a limit for one key](/concurrency#overriding-a-limit-for-one-key).
+
 ### Cross-turn persistence
 
 Sub-agent conversations persist across **parent turns** because the `Map` lives in the parent's process heap. When the parent suspends and restores via snapshot, the heap is preserved — the Map still has the conversations, the sessions still have the run IDs.

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

@@ -12,6 +12,8 @@ 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.
+
 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.
 
 ## How it works

package/docs/ai-chat/reference.mdx

@@ -47,7 +47,9 @@ Options for `chat.agent()`.
 | `storage`                     | `TranscriptStorage`                                         | `defaultStorage`               | Where the conversation is persisted and read back. The platform snapshot by default; bring your own to write each change to your database. See [Transcript storage](/ai-chat/transcript-storage) |
 | `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, or nothing for an edit only. 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). |
 | `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)                                                     |
@@ -232,7 +234,7 @@ The persistence adapter set through `chat.agent({ storage })`. See [Transcript s
 | Type | Shape |
 | --- | --- |
 | `TranscriptScope<TClientData>` | `{ chatId: string; clientData: TClientData }` |
-| `TranscriptStorageContext<TClientData>` | `TranscriptScope` plus `{ turn: number; trigger: "submit-message" \| "regenerate-message" \| "action"; runId: string; ctx: TaskRunContext }` |
+| `TranscriptStorageContext<TClientData>` | `TranscriptScope` plus `{ turn: number; trigger: "submit-message" \| "regenerate-message" \| "action" \| "action-turn"; source?: "client" \| "channel" \| "webhook"; connectorId?: string; runId: string; ctx: TaskRunContext }`. `action-turn` is the turn `chat.turn()` requested; `source` names the surface that drove the write |
 | `TranscriptChange` | `{ op: "put"; message: UIMessage; final?: boolean }` \| `{ op: "remove"; id: string }` \| `{ op: "truncateAfter"; afterId: string }` \| `{ op: "state"; value: unknown \| null }` |
 | `TranscriptChangeset` | `{ reason: "turn-complete" \| "turn-error" \| "action" \| "compaction" \| "recovery"; changes: TranscriptChange[]; transcript: TranscriptState; cursors?: TranscriptCursors }` |
 | `TranscriptState` | `{ entries: Array<{ id: string; final: boolean; message: UIMessage }>; state: unknown \| null }`: the whole conversation after the changeset's changes, for stores that write one document |
@@ -275,6 +277,7 @@ Passed to the `onAction` callback. See [Actions](/ai-chat/actions).
 | `clientData` | Typed by `clientDataSchema` | Custom data from the frontend                            |
 | `uiMessages` | `UIMessage[]`               | Accumulated UI messages (after hydration, if set)        |
 | `messages`   | `ModelMessage[]`            | Accumulated model messages (after hydration, if set)     |
+| `channel`    | `{ connectorId, provider, event, deliveryId }` | For a channel action (a button the agent posted, such as a Slack `slackButton()`): the verified click event. Absent otherwise |
 
 ## TurnStartEvent
 
@@ -538,6 +541,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.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 }`                                                         |
@@ -570,6 +575,49 @@ All methods available on the `chat` object from `@trigger.dev/sdk/ai`.
 | `chat.withUIMessage(config?)`               | Returns a [ChatBuilder](/ai-chat/types#chatbuilder) with a fixed `UIMessage` subtype. See [Types](/ai-chat/types)            |
 | `chat.withClientData({ schema })`           | Returns a [ChatBuilder](/ai-chat/types#chatbuilder) with a fixed client data schema. See [Types](/ai-chat/types#typed-client-data-with-chatwithclientdata) |
 
+## `chat.event`
+
+Declare an inbound webhook event that an agent claims via [`events`](#chatagentoptions) on `chat.agent()`. It is a descriptor only, with no handler: it names the [endpoint](/webhooks/overview) it subscribes to, a `key` template that resolves each delivery to a durable [session](/ai-chat/sessions), and an optional `type` label (defaults to the descriptor `id`). Verified deliveries are routed to that session and arrive at `onAction` as a `{ type, event, source, headers, deliveryId, endpoint }` envelope, not as a chat turn. See [session routing](/webhooks/session-routing).
+
+```ts
+import { webhooks } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+
+export const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe() });
+
+export const orderEvents = chat.event({
+  id: "order-events",
+  endpoint: stripe,
+  key: "{event.data.object.customer}",
+  type: "order.event",
+});
+```
+
+## `chat.channels.custom`
+
+Create a generic chat-frontend channel on any [endpoint](/webhooks/overview), claimed via [`channels`](#chatagentoptions) on `chat.agent()`. You supply the session `key`, the `inbound` map from event to turn message, and your own `send` egress that posts the reply back, so the whole round-trip is under your control. Inbound messages run as normal turns and the reply is posted back. The `slack()` preset ships in `@trigger.dev/slack` and wires the egress for you. See [channels](/webhooks/channels), and the interactive approvals layer at [human-in-the-loop](/webhooks/human-in-the-loop).
+
+```ts
+import { webhooks } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+
+const surface = webhooks.endpoint.define({
+  id: "my-surface",
+  source: webhooks.custom<MyEvent>({ /* verifier config */ }),
+});
+
+export const mySurface = chat.channels.custom({
+  id: "my-surface",
+  endpoint: surface,
+  key: "{event.conversationId}",
+  inbound: (event) => event.text,
+  send: async (message, ctx) => {
+    const ref = await postToMySurface(ctx.event, message.text, ctx.previousRef);
+    return { ref };
+  },
+});
+```
+
 ## `chat.withUIMessage`
 
 Returns a [`ChatBuilder`](/ai-chat/types#chatbuilder) with a fixed `UIMessage` subtype. Chain `.withClientData()`, hook methods, and `.agent()`.

package/docs/apikeys.mdx

@@ -75,7 +75,7 @@ The default API URL is `https://api.trigger.dev`.
 
 ## Access presets
 
-Access presets define what a key can do. Some presets require a paid plan. The dashboard shows which presets your organization can use — see [pricing](https://trigger.dev/pricing).
+Access presets define what a key can do. On the Free and Hobby plans only the **No restrictions** preset is available. All other presets require the Pro or Enterprise plan.
 
 | Preset | Access |
 | --- | --- |
@@ -87,7 +87,7 @@ Access presets define what a key can do. Some presets require a paid plan. The d
 | **Variables only** | Read and write environment variables in this environment |
 | **No restrictions** | Full access to the environment |
 
-**Trigger only** and **Task operator** can be restricted to selected tasks. Task restrictions use task identifiers, such as `send-email`. A request involving multiple tasks — such as a batch trigger — succeeds only when the key can access every task in the request, so a task-restricted key can batch-trigger only its selected tasks.
+**Trigger only** and **Task operator** can be restricted to selected tasks, up to 10 tasks per key. Task restrictions use task identifiers, such as `send-email`. A request involving multiple tasks — such as a batch trigger — succeeds only when the key can access every task in the request, so a task-restricted key can batch-trigger only its selected tasks.
 
 ## Deploy with an API key
 
@@ -124,7 +124,7 @@ Use `@trigger.dev/sdk` version 4.5.8 or later to create public tokens with envir
 
 - The token must request at least one scope.
 - Its scopes cannot exceed the key's access.
-- Its expiration cannot exceed 30 days.
+- Its expiration cannot exceed 30 days (the default is 15 minutes).
 
 <Note>
 Revoking or expiring an API key does not revoke tokens it already created. Those tokens remain valid until their own expiration.

package/docs/billing-limits.mdx

@@ -49,7 +49,7 @@ When your organization's spend reaches the billing limit, billable environments
 2. New runs can still be triggered and are queued, but they won't start executing. Queued runs incur no compute cost until they start.
 3. You have **24 hours** to review and decide what to do.
 
-If you don't act before the grace period ends, queued runs are canceled and new triggers are rejected for the rest of the billing cycle.
+If you don't act before the grace period ends, new triggers are rejected until you increase or remove the limit (limits also reset at the start of each billing cycle). Queued runs stay queued until you resolve the limit and choose to resume or cancel them. If the limit is still in place when a new billing cycle starts, queued runs resume automatically. Runs that have a TTL still expire if they stay queued past it.
 
 <Note>
   Billing limits are **soft limits**, not instantaneous hard caps. Usage is evaluated on a short