@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/webhooks/linear.mdx

@@ -0,0 +1,186 @@
+---
+title: "Linear agents"
+description: "Turn a chat.agent into a Linear agent: assign it an issue or @mention it, and it works the issue inside Linear's agent session UI."
+sidebarTitle: "Linear agents"
+---
+
+Linear opens an **agent session** when someone @mentions your app in an issue or delegates (assigns) an issue to it. `linear()` from `@trigger.dev/linear` is a [channel](/webhooks/channels) connector for those sessions: each one becomes a durable Trigger.dev [session](/ai-chat/sessions), the user's prompt runs as a turn, and the agent's work shows up in Linear as thoughts, actions, a plan, an approval card when it needs a decision, and a response when it is done.
+
+```ts
+import { webhooks } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+import { linear, webhookSource } from "@trigger.dev/linear";
+import { anthropic } from "@ai-sdk/anthropic";
+
+const linearEvents = webhooks.endpoint.define({ id: "linear", source: webhookSource() });
+
+export const triage = chat.agent({
+  id: "triage",
+  channels: [linear({ id: "linear", endpoint: linearEvents, token: process.env.LINEAR_ACCESS_TOKEN! })],
+  tools: { searchDocs, createSubIssues },
+  run: async ({ messages, tools, signal, streamText }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages, tools, abortSignal: signal }),
+});
+```
+
+The `run()` loop is the same one a browser chat or a Slack thread uses. Verification, the five second webhook acknowledgment, the first activity Linear expects within ten seconds, per-session state, dedup of Linear's retries, replay and the transcript are handled for you.
+
+## Setup
+
+<Steps>
+  <Step title="Create the OAuth app">
+    In Linear, create an OAuth application under **Settings, API**. Enable **Webhooks** on it and turn on the **Agent session events** category (Inbox notifications and Permission changes are useful too). Copy the webhook **signing secret**.
+  </Step>
+  <Step title="Install it as an agent">
+    Authorize the app with `actor=app` in the authorization URL and request the `app:assignable` and `app:mentionable` scopes, so members can assign issues to it and @mention it. Installation needs a workspace admin. Keep the resulting access token; pass it as `token`.
+  </Step>
+  <Step title="Deploy and connect the endpoint">
+    Declare the endpoint with `webhookSource()` from `@trigger.dev/linear` and pass it to `linear({ endpoint })`. Deploying registers the hosted [endpoint](/webhooks/connect). Paste the app's webhook signing secret as the endpoint's signing secret, and set the app's webhook URL to the endpoint's URL. The endpoint's setup prompt walks an AI coding agent through these settings.
+  </Step>
+  <Step title="Try it">
+    Open an issue and assign it to the app, or write a comment that @mentions it. Linear shows the agent's first thought within a few seconds and then its work.
+  </Step>
+</Steps>
+
+## What the agent sees
+
+On the first turn of a session the connector frames Linear's payload for the model: who summoned it and on which issue, the workspace **guidance** rules for agents, Linear's formatted **issue context** (title, description, labels, project, comments), and the comment that mentioned it. An assignment with no comment reads as "assigned ENG-412 to you". Prior comments on the issue are seeded as transcript messages, so the agent can answer with the context a reader of the issue has.
+
+A follow-up prompt on the session is just the message. If the user hits **Stop** in Linear, see [Stopping](#stopping).
+
+Images and PDFs uploaded to Linear reach the model as files: screenshots in the prompt, in the comment that mentioned the agent, or in the issue description. The transcript keeps the upload link, and the `streamText` passed to `run()` downloads the file with the app's token when the model reads it, at most ten per message. A file that can't be downloaded reaches the model as a short note. A custom `inbound` keeps this by adding `linearFileParts(markdown)` to its message parts.
+
+Turn any of that off with `context`:
+
+```ts
+linear({ id: "linear", endpoint: linearEvents, token, context: { guidance: false, promptContext: true, previousComments: true } })
+```
+
+## What Linear shows
+
+| Moment | Activity in Linear |
+| --- | --- |
+| Turn starts | An ephemeral `thought` ("Looking into this...") |
+| A tool is called | An ephemeral `action` with the tool name and input, then the same action with its `result` |
+| The reply is ready | A `response` with the reply as markdown |
+| The turn fails | An `error` saying "Something went wrong answering this. Try again." (`errorMessage` changes it) |
+| A tool needs a human decision | An `elicitation` with Approve and Deny options, or the tool's own options from `interactions` (see [Approvals and choices](#approvals-and-choices)) |
+| The user picks an option | A `thought` recording the decision ("Approved by Jane.", "Jane chose "High".") |
+| A prompt arrives while the agent works | A `thought` ("Got it, I'll take that into account.") as soon as it arrives (see [Prompts sent while the agent is working](#prompts-sent-while-the-agent-is-working)) |
+
+Tool mirroring is on by default; pass `progress: "off"` to post only the response. Bare Linear URLs in a reply become mentions, so link issues and documents by URL.
+
+## The plan
+
+Linear shows an agent's plan as a checklist under the conversation. The model owns it: add `linearPlanTool()` to the agent's tools and ask for a plan in the system prompt, and the model sets it when it starts and updates it as steps finish. The whole list is replaced on each call. On a turn that is not a Linear session the tool reports that nothing was updated, so `run()` needs no Linear-specific code.
+
+```ts
+import { linear, linearPlanTool } from "@trigger.dev/linear";
+
+export const triage = chat.agent({
+  id: "triage",
+  channels: [linear({ id: "linear", endpoint: linearEvents, token })],
+  tools: { searchDocs, createSubIssues, updatePlan: linearPlanTool() },
+  run: async ({ messages, tools, signal, streamText }) =>
+    streamText({
+      model,
+      messages,
+      tools,
+      abortSignal: signal,
+      system: "Start by setting a short plan with updatePlan and keep it current as you work.",
+    }),
+});
+```
+
+## Helpers
+
+For manual control, `chat.surface<LinearRunSurface>()` returns the current turn's helpers from anywhere inside the run, including a tool's `execute`. The same object is handed to `run()` as `channel`.
+
+| Helper | Effect |
+| --- | --- |
+| `plan(steps)` | Replace the session's plan. Each step is `{ content, status }` with status `pending`, `inProgress`, `completed` or `canceled`. What `linearPlanTool()` calls. |
+| `thought(text, { ephemeral })` | Post a thought. |
+| `action(action, parameter, result?)` | Post an action, optionally with its result. |
+| `link(label, url)` | Add an external link to the session header (a pull request, a dashboard). |
+| `summary(text)` | Set the one-line session summary. |
+| `session` | The bound agent session and issue ids. |
+
+## Approvals and choices
+
+A tool with no `execute` pauses the turn for a human decision, exactly as on [any channel](/webhooks/human-in-the-loop). On Linear the connector posts an elicitation card with Approve and Deny options. The card lays the tool input out as markdown: a list of proposed items becomes a numbered list with a bold title per item, a flat object becomes key and value bullets, and only shapes it cannot lay out fall back to JSON. For a card written for the tool, pass a renderer per tool name:
+
+```ts
+linear({
+  id: "linear",
+  endpoint: linearEvents,
+  token,
+  approvals: {
+    createSubIssues: (input) => ({
+      title: "Create these sub-issues?",
+      body: (input as { issues: { title: string }[] }).issues.map((i) => `- ${i.title}`).join("\n"),
+    }),
+  },
+})
+```
+
+The user picks one and presses Continue; the choice shows in the session as "Approve createSubIssues [call_a]" (the tool and the call it applies to, so the decision always lands on the call whose input the card shows) and resumes the run with `{ approved: true | false }`, and the decision is recorded as a thought. Typing a free-text reply instead dismisses the options and runs as a normal turn, so the model can take the reply into account (and ask again) with the approval still pending.
+
+`interactions` gives a tool its own choices instead of Approve and Deny. The card is a select of `options`, and the chosen option resolves the tool to `{ selected }`:
+
+```ts
+linear({
+  id: "linear",
+  endpoint: linearEvents,
+  token,
+  interactions: {
+    pickPriority: (call) => ({
+      title: "What priority should this be?",
+      body: (call.input as { reason: string }).reason,
+      options: ["Urgent", "High", "Medium", "Low"],
+    }),
+  },
+})
+```
+
+The choice shows in the session as "High [choice:call_a]", resumes the run with `{ selected: "High" }`, and is recorded as a thought.
+
+## Stopping
+
+Pressing Stop in Linear sends the session a prompt with the `stop` signal. While a turn is running, the connector aborts it through the agent's stop signal (the same one the browser's stop button uses): generation halts, the text written so far posts as the response with `stopped: true`, and the stop prompt itself is consumed. Pressed while the agent is idle, the prompt runs as a turn that tells the model to stop taking actions and summarize. A Stop pressed while a turn was running that arrives after the turn finished is consumed, so pressing Stop twice never adds a wind-down turn.
+
+## Prompts sent while the agent is working
+
+A prompt sent while the agent is still working gets a thought as soon as it arrives ("Got it, I'll take that into account."), so the user knows it was picked up. It then waits and runs as the next turn. With [`pendingMessages`](/ai-chat/pending-messages) on the agent, `shouldInject` can fold it into the work in progress at the next step instead; a prompt it declines still runs as its own turn. `receivedThought` changes the text, takes a function of the event for wording per prompt, and `null` posts nothing; since the prompt may be answered either way, keep the wording true for both. Stop and the approval card's options are never acknowledged or folded in.
+
+## Answering into the session from elsewhere
+
+The first Linear turn binds the session to the agent session ([bound sessions](/webhooks/channels#bound-sessions)). A [`chat.event`](/webhooks/session-routing) routed to the same session key, a Sentry alert keyed on the issue identifier for example, can return `chat.turn()` from `onAction` and its answer posts into the Linear session as a response, with no Linear event involved. Linear reopens a completed session when new activity arrives.
+
+## Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Connector id, unique per agent. |
+| `endpoint` | endpoint | The Linear endpoint, declared with `webhooks.endpoint.define({ id, source: webhookSource() })`. Other `webhook()` tasks can subscribe to the same endpoint. |
+| `token` | `string` or resolver | The app's OAuth access token, or a function of the event (keyed on `organizationId`) for multi-workspace installs. |
+| `key` | `string` | Session [key](/webhooks/session-routing) template over `{event.*}`, `{header.*}` and `{webhook.*}`. Defaults to one session per Linear agent session. |
+| `filter` | filter string | Extra [filter](/webhooks/filters), composed with the built-in agent-session guard. Checked against the endpoint's event type, like `webhook()`'s `filter`. |
+| `startOn` | filter string | Only start a session when the event matches. Existing sessions always resume. Checked against the endpoint's event type. |
+| `context` | `{ guidance?, promptContext?, previousComments? }` | What from Linear's payload is put in front of the model on the first turn. All on by default. |
+| `progress` | `"actions"` or `"off"` | Mirror tool calls as action activities (default) or post only the response. |
+| `summarize` | `boolean` | Set the session title from each response's first line. Off by default; Linear titles the session itself. |
+| `approvals` | `{ [toolName]: (input, call) => { title?, body } }` | Custom approval card body per tool. Default lays the tool input out as markdown. |
+| `interactions` | `{ [toolName]: (call) => { title?, body, options } }` | A tool's own select card; the chosen option resolves the tool to `{ selected }`. |
+| `receivedThought` | `string`, function or `null` | Thought posted as soon as a prompt arrives while the agent is working. Default "Got it, I'll take that into account.", null for none. |
+| `errorMessage` | `string \| (ctx) => string` | The error activity's text when a turn fails, fixed or built from the failure ([details](/webhooks/channels#when-a-turn-fails)). Default "Something went wrong answering this. Try again." |
+| `ack` | message, `null`, or function | The first thought. Pass `null` to post nothing before the response. |
+| `inbound` / `outbound` | functions | Map the event to the turn, and the reply to an activity. |
+| `delivery` | `"final"` or `"stream"` | `"final"` (default) posts the response when the turn ends. `"stream"` also posts ephemeral thoughts as the reply streams. |
+| `apiUrl` | `string` | Override the Linear GraphQL URL, for testing against a mock. Files on its origin are treated as Linear uploads. |
+
+<Note>
+  Linear expects the first activity within ten seconds of opening a session. The connector posts it at
+  the top of the run, so on a cold start close to that limit the session can show as unresponsive for a
+  moment; it recovers as soon as the thought lands. Linear retries a failed delivery after one minute,
+  one hour and six hours, and the endpoint deduplicates those retries.
+</Note>

package/docs/webhooks/overview.mdx

@@ -0,0 +1,115 @@
+---
+title: "Webhooks overview"
+description: "Receive provider webhooks on hosted, verified endpoints and route each event to tasks, agents, and waiting runs."
+sidebarTitle: "Overview"
+---
+
+**A webhook endpoint is one hosted URL that you register with a provider.** Trigger.dev verifies every request against the endpoint's [source](/webhooks/sources), records it as a [delivery](/webhooks/deliveries), and hands the event to everything subscribed to the endpoint.
+
+Declare the endpoint once, then subscribe to it:
+
+```ts /trigger/stripe.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const stripe = webhooks.endpoint.define({
+  id: "stripe",
+  source: webhooks.stripe(),
+});
+
+export const fulfillOrder = webhook({
+  id: "fulfill-order",
+  endpoint: stripe,
+  filter: "event.type == 'checkout.session.completed'",
+  onEvent: async ({ event }) => {
+    console.log("Fulfilling", event.data.object.id);
+  },
+});
+
+export const recordRefund = webhook({
+  id: "record-refund",
+  endpoint: stripe,
+  filter: "event.type == 'charge.refunded'",
+  onEvent: async ({ event, headers, endpoint, ctx }) => {
+    console.log("Refund", event.id, "on", endpoint?.id, "in run", ctx.run.id);
+  },
+});
+```
+
+Stripe gets one URL. A checkout event runs `fulfill-order`, a refund runs `record-refund`, and anything else is recorded as `FILTERED`.
+
+## What can subscribe
+
+| Subscriber | Declared with | What a delivery does |
+| --- | --- | --- |
+| Task | `webhook({ endpoint, onEvent })` | Starts a run of the task with the event. |
+| Agent session | [`chat.event({ endpoint, key })`](/webhooks/session-routing) listed on a `chat.agent` | Delivers an action to the session the `key` names. |
+| Chat frontend | a [channel connector](/webhooks/channels) such as `chat.channels.custom({ endpoint })` | Runs a turn on the conversation's session and posts the reply back. |
+| Waiting run | [`webhooks.waiter.create(endpoint, { match })`](/webhooks/waiters) | Resumes a run that is waiting for this event. |
+
+Each subscriber has its own [filter](/webhooks/filters), so one delivery can reach several subscribers and skip the rest. An endpoint can have up to 25 subscribers. An endpoint with no subscribers still gets a URL, so you can register it with the provider before writing the handlers.
+
+## The handler
+
+`onEvent` receives:
+
+| Argument | Value |
+| --- | --- |
+| `event` | The verified request body, parsed as JSON. Its TypeScript type comes from the [source](/webhooks/sources#typing-the-event). |
+| `headers` | Request headers as a Web `Headers` object, with case-insensitive `get()` and `has()` methods. Credentials such as signatures are removed. |
+| `endpoint` | The endpoint the delivery arrived on: `id`, `declaredId`, `tenantId`, `externalRef`, and the `metadata` you declared. |
+| `ctx` | The same [run context](/context) that regular tasks receive. |
+
+`webhook()` also takes the options a [task](/tasks/overview) does, such as `queue`, `concurrency`, `machine`, `retry`, `maxDuration` and the lifecycle hooks. For example, to handle one delivery at a time:
+
+```ts
+export const orders = webhook({
+  id: "stripe-orders",
+  endpoint: stripe,
+  queue: { concurrencyLimit: 1 },
+  retry: { maxAttempts: 5 },
+  onEvent: async ({ event }) => {
+    // ...
+  },
+});
+```
+
+The limit covers every delivery the task handles. To process each customer's events in order while different customers run in parallel, route them to an agent with [session routing](/webhooks/session-routing): deliveries with the same key land in one session and are handled one after another.
+
+`webhooks.endpoint.define` also takes a `description` and `metadata`. The metadata is passed to every subscriber as `endpoint.metadata`. The endpoint `id` can't start with `wh_`, which is reserved for the ids Trigger.dev generates.
+
+## How it works
+
+The CLI finds your endpoints and subscribers during `trigger dev` and deployment, and each environment gets one endpoint per declared id. The endpoint holds the URL and the credential used to verify requests.
+
+A request must pass verification before anything else happens. Provider handshakes are answered directly and create no delivery. A verified request is checked for duplicates, recorded, and then routed: each subscriber's filter is checked, matching subscribers run, and waiting runs whose match fits the event are resumed. The delivery records a result per subscriber.
+
+## Connect it
+
+Every endpoint can produce a setup prompt for an AI coding agent. It holds the URL, the events your subscribers filter on, and the steps for registering the endpoint and its signing secret with the provider. Copy it from the endpoints list or the endpoint's page, or read it with the MCP server's `get_webhook_endpoint_details` tool. See [Connect a provider](/webhooks/connect).
+
+<CardGroup cols={2}>
+  <Card title="Connect a provider" icon="plug" href="/webhooks/connect">
+    Register the URL and signing secret, then send a test event.
+  </Card>
+  <Card title="Sources and verification" icon="shield-check" href="/webhooks/sources">
+    Choose a provider source or define a custom verification scheme.
+  </Card>
+  <Card title="Filters" icon="filter" href="/webhooks/filters">
+    Choose which events reach each subscriber.
+  </Card>
+  <Card title="Waiters" icon="hourglass" href="/webhooks/waiters">
+    Pause a run until a matching webhook arrives.
+  </Card>
+  <Card title="Deliveries and endpoints" icon="inbox" href="/webhooks/deliveries">
+    Inspect received events and where each one went.
+  </Card>
+  <Card title="Session routing" icon="arrows-to-dot" href="/webhooks/session-routing">
+    Route deliveries to a durable per-key agent session.
+  </Card>
+  <Card title="Channels" icon="comments" href="/webhooks/channels">
+    Turn a webhook into a chat frontend for an agent.
+  </Card>
+  <Card title="Human-in-the-loop" icon="user-check" href="/webhooks/human-in-the-loop">
+    Approvals and interactive controls over a channel.
+  </Card>
+</CardGroup>

package/docs/webhooks/session-routing.mdx

@@ -0,0 +1,141 @@
+---
+title: "Routing to a session"
+description: "Route verified webhook deliveries to a durable per-key session instead of a fresh run."
+sidebarTitle: "Session routing"
+---
+
+A plain [`webhook()`](/webhooks/overview) runs a fresh, stateless run for every delivery. Sometimes you want the opposite: deliveries that share a key (a customer, an installation, an issue) should land on **one durable [session](/ai-chat/sessions)** and be handled in order, with state carried across them. That is what session routing does.
+
+Instead of a handler, you declare a `chat.event` on an [endpoint](/webhooks/overview) and list it on an agent. The verified delivery is routed to a find-or-created session and arrives as an [action](/ai-chat/actions).
+
+## Declaring a chat event
+
+`chat.event` describes the routing only: the endpoint it subscribes to, a `key` that identifies the session, and a `type` label for the delivered action. It has no handler.
+
+```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,
+  // one session per customer
+  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",
+});
+```
+
+The endpoint's other subscribers, such as a `webhook()` task, still get the same deliveries.
+
+### The key
+
+The `key` is what makes routing durable: two deliveries that resolve to the same key reach the same session; a different key gets its own. It is a template string, evaluated server-side at ingest, whose `{...}` placeholders read three namespaces:
+
+- `{event.*}`: the parsed event body.
+- `{webhook.*}`: endpoint metadata (`externalRef`, `tenantId`, `id`, `source`, `deliveryId`).
+- `{header.name}`: an inbound header.
+
+These are the same namespaces [filter](/webhooks/filters) expressions use. Every placeholder names one: a bare `{customer}` is an error.
+
+`{a || b}` falls back to `b` when `a` is missing or empty. Compose several placeholders into one key: `"{webhook.externalRef}-{event.issue.id}"`. Each placeholder is checked against the event type at build time, so a bad field is a red squiggle on the `key` line, not a runtime surprise.
+
+### The `type` label
+
+`type` is a name you choose for the delivered action. It flows straight through to `action.type` on the envelope, so your handler can tell webhook actions apart from each other and from browser actions. It is optional and defaults to the descriptor `id`.
+
+## Handling deliveries on an agent
+
+List the descriptor on a [`chat.agent`](/ai-chat/overview) (or a session agent). The delivery arrives at `onAction`, not as a chat message:
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { orderEvents } from "./order-events";
+
+export const orderAgent = chat.agent({
+  id: "order-agent",
+  events: [orderEvents],
+  onAction: async ({ action }) => {
+    switch (action.type) {
+      case "order.event":
+        // action.event is the verified Stripe event, fully typed
+        console.log("order for", action.event.data.object.customer);
+        break;
+    }
+  },
+  run: async ({ messages, signal }) => {
+    /* ... */
+  },
+});
+```
+
+`action.type` is a closed union of the `type` labels of the events you listed, and each arm narrows `action.event` to that event's payload type. The full envelope is `{ type, event, source, headers, deliveryId, externalDeliveryId, endpoint }`. `deliveryId` is the delivery's `whd_` id, as in the dashboard and the [deliveries API](/webhooks/deliveries): a [replay](/webhooks/deliveries#replay) gets a new one. `externalDeliveryId` is the provider's id for the delivery (Stripe's `evt_` id, for example), the same across replays. `endpoint` is the endpoint the delivery arrived on.
+
+Because it is an [action](/ai-chat/actions), the handler is not a turn by default: it can read the event, mutate session state with `chat.history`, and return nothing. To have the agent answer, return `chat.turn()`: the edit is saved, then a full turn runs on the session's history exactly as a message turn does. Webhook actions bypass your `actionSchema` (their shape is fixed and already verified by the source), so `action.type` and `action.event` are typed from the descriptor, not the schema.
+
+## Answering into a channel
+
+When the same session is also a [channel](/webhooks/channels) conversation (a Slack thread keyed to the same customer, say), a turn requested from a webhook action posts its answer into that thread. The first channel message **binds** the session to its connector; every later turn on the session, whatever started it, egresses through the binding.
+
+```ts
+export const orderAgent = chat.agent({
+  id: "order-agent",
+  channels: [
+    slack({
+      id: "support-slack",
+      endpoint: slackEvents,
+      token: process.env.SLACK_BOT_TOKEN!,
+      startOn: appMentions(),
+    }),
+  ],
+  events: [orderEvents],
+  onAction: async ({ action }) => {
+    if (action.type === "order.event") {
+      // A user-role note, so the model lane ends on a user message. A system-role
+      // injection becomes instructions and leaves the lane ending on the assistant's
+      // last reply, which most models treat as a prefill and answer with nothing.
+      chat.inject([
+        {
+          role: "user",
+          content: `[payments] Order ${action.event.data.object.id} was paid. Tell the thread in one sentence.`,
+        },
+      ]);
+      return chat.turn(); // the agent tells the thread about the payment
+    }
+  },
+  run: async ({ messages, streamText }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages }),
+});
+```
+
+A bound turn posts the final answer as a fresh message in the thread (no placeholder, since there is no triggering message to react to). If the session has never had a channel message, there is nothing to post into and the turn's answer stays on the session's stream only.
+
+<Note>
+  The descriptor never names the agent, and the agent references the descriptor, so there is no
+  circular dependency. Whichever agent lists it becomes the routing target.
+</Note>
+
+## Several agents on one endpoint
+
+Listing a descriptor on an agent subscribes that agent to the descriptor's endpoint, with the subscriber id `agentId:eventId`. If two agents list the same descriptor, the endpoint has two subscribers and every delivery goes to both, on the one URL the provider already knows.
+
+A session belongs to the agent that created it. When two agents compute the same key, the second agent's delivery to that session fails with an error naming the owner. Both agents see the same endpoint, so a `{webhook.*}` placeholder resolves the same for each and can't separate them. Give each agent its own descriptor with a constant prefix in the key instead, for example `"billing-{event.data.object.customer}"` and `"support-{event.data.object.customer}"`.
+
+An exported `chat.event` that no agent lists routes nothing. `trigger dev` warns about it (it is not an error, since declaring the descriptor before wiring the agent is a normal step), so wire it onto an agent once you are ready.
+
+## Filtering
+
+A [`filter`](/webhooks/filters) works here exactly as on a `webhook()` task: a delivery that doesn't match never reaches the session, and the delivery records the reason.
+
+```ts
+export const orderEvents = chat.event({
+  id: "order-events",
+  endpoint: stripe,
+  key: "{event.data.object.customer}",
+  type: "order.event",
+  filter: "event.type == 'payment_intent.succeeded'",
+});
+```