@cursor/bdk 0.2.24 → 0.2.26

package/dist/docs/llms-full.txt

@@ -143,6 +143,97 @@ works; a measured climb proves it works better on fixed inputs.
 
 ---
 
+Source: /docs/changelog.md
+
+# Changelog
+
+## 0.2.26 (2026-10-16)
+
+### Breaking changes
+
+- `serve({ otel })` is removed. Delete `bot/otel.ts`, `agent/otel.ts`, and `bot/instrumentation.ts`. Set `OTEL_*` variables. Read [Migrating from serve({ otel })](/docs/guides/opentelemetry.md#migrating-from-serve-otel).
+
+### Behavior changes
+
+- `ctx.host.otel` is deprecated. It still runs for this release. The first call emits one deprecation warning. Set `OTEL_*` variables. Record with `metrics.getMeter` and `trace.getTracer` from `@opentelemetry/api`.
+- A span started during a turn or a tool gets `cursor.conversation.id` from the active context when the span does not set it. A metric does not. Call `currentConversationId` from `@cursor/bdk/otel` and set the attribute yourself. See [OpenTelemetry](/docs/guides/opentelemetry.md#what-you-can-record).
+- A turn waits for MCP OAuth only when a person can connect. That is a playground or HTTP chat turn, or a Slack message on a channel that shows Connect. `toolApprovals: true` shows Connect, and so does `buildToolApprovalEvents` in `events`. A schedule, a reminder, a webhook, an eval, or a Slack channel without Connect does not wait. A required connection fails with `Reconnect <connection>`. An optional connection is skipped.
+- A turn never waits to authorize an `optional` connection, also in the playground.
+- A turn that waits for MCP OAuth stops after 10 minutes with `Reconnect <connection>`. `interrupt()` also stops the wait.
+- `bdk deploy` rejects a source host other than GitHub, gitlab.com, or Origin.
+- A new scaffold imports `zod/v4`. A zod 3 schema and a zod 4 schema both still parse.
+- `bdk deploy` with no terminal lists a connector that needs sign-in as pending.
+
+### New
+
+- `bdk deploy` deploys a bot from a gitlab.com repository.
+- When you omit `--cursor-events-repo`, a GitLab deploy watches that project. A nested group is part of the path.
+- When that deploy cannot watch the project, the deploy still finishes. The CLI says the deployment is not watching the project.
+- An agentic Slack reply can set `cards: { display: "plan" }`. Slack shows the `post-card` steps from that turn as one checklist.
+- A `title` names that checklist. A title has at most 256 characters.
+- With no `cards` option, Slack keeps one card for each step.
+- `send()` returns a delivery id. Set `deliveryId` to choose it. `nudge.delivered` and `message.received` include that id.
+
+### Fixes
+
+- Public helper signatures use portable types. A webhook body is a `string` or a `Uint8Array`. An environment map is `Record<string, string | undefined>`.
+- `HostFilesApi.read` takes a `HostFileTextEncoding`. A `Buffer` and `process.env` still type-check.
+- OpenTelemetry ends each tool span when that tool finishes.
+- With no OpenTelemetry endpoint, the process holds at most 2048 spans and 2048 log records.
+- A follow-up after a redeploy resumes the same agent. A changed workspace path does not start a new conversation.
+- In a Slack Connect channel, sender checks use the workspace where the app is installed.
+- A `cursorAccount` GitHub GraphQL call includes the repository.
+- A Slack bot with a lapsed MCP connection replies with a reconnect message.
+
+## 0.2.25 (2026-10-14)
+
+### New
+
+- `bdk validate --json` writes one JSON object. Each diagnostic has a code.
+
+### Fixes
+
+- OpenTelemetry metrics follow `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`. The default stays delta.
+- `ctx.host.github.getOctokit()` tries again after a failed lookup. A later call can succeed after a GitHub token becomes available.
+
+## 0.2.24 (2026-10-13)
+
+### Breaking changes
+
+- Install `zod` in the project. The peer range is `^3.25.0` or `^4.0.0`. A new scaffold imports `zod/v3`.
+
+### Behavior changes
+
+- `setContinuationToken(null)` releases the continuation key. The next delivery starts a new session.
+- Model fallback continues when a blocked model sends progress updates and no assistant text. Those updates are `user-message-appended`, `step-started`, and `step-completed`.
+- Read a secret inside a handler, a tool, or a callback. A `process.env` read while the module is still loading returns an empty value on a Cursor-managed deploy.
+- In the Agentic Approver template, a `paths` glob is relative to the policy directory.
+- The package depends on `tsx` 4.23.15.
+
+### New
+
+- `hmacSignatureAuth` takes an optional `separator`. One header can then carry several HMAC signatures. PagerDuty uses a comma.
+- `cursorCloudAgents` accepts `cloud.teamMcpServers`. The launch uses the team MCP servers you name.
+
+### Fixes
+
+- On Cursor-managed hosting, OpenTelemetry reads the endpoint, the headers, and the resource after secrets load. You can remove a workaround that reads `OTEL_EXPORTER_OTLP_HEADERS` again.
+
+## 0.2.23 (2026-10-09)
+
+### Behavior changes
+
+- `bdk migrate` rewrites a URL-secret MCP peer to `defineConnection({ agent })` in the migration pull request.
+- `bdk migrate` prints a checklist after the migration. It says when there is nothing to migrate.
+- `bdk slack create --prod` says the deployment redeploys by itself.
+- `bdk deploy` on a folder of several agents prints one command per agent. You run each command to deploy that agent.
+
+### New
+
+- A Slack app can opt in to the `chat:write.customize` scope. A post can then set its username and its icon. An app that leaves the scope off keeps its current scopes.
+
+---
+
 Source: /docs/deployment.md
 
 # Deploy a BDK project
@@ -2520,8 +2611,13 @@ so the dashboard reflects live traffic instead of the test suite.
 
 ```ts
 // bot/hooks/usage.ts
+import { metrics } from "@opentelemetry/api";
 import { defineHook } from "@cursor/bdk/hooks";
 
+const meter = metrics.getMeter("acme");
+const inputTokens = meter.createCounter("acme.tokens.input");
+const outputTokens = meter.createCounter("acme.tokens.output");
+
 export default defineHook({
   events: {
     async "turn.completed"(event, ctx) {
@@ -2532,9 +2628,8 @@ export default defineHook({
         return;
       }
 
-      const { inputTokens, outputTokens } = event.data.usage;
-      ctx.host.otel.increment("acme.tokens.input", inputTokens);
-      ctx.host.otel.increment("acme.tokens.output", outputTokens);
+      inputTokens.add(event.data.usage.inputTokens);
+      outputTokens.add(event.data.usage.outputTokens);
     },
   },
 });
@@ -3106,6 +3201,18 @@ bdk serve --dir . --dev
 
 Connect authorizes the process that is running now.
 
+A turn waits for Connect only when a person can click it:
+
+- A playground or HTTP chat turn.
+- A Slack message, when the channel shows Connect. `slackChannel({ toolApprovals: true })` shows
+  Connect, and so does `buildToolApprovalEvents` in `events`.
+
+The wait stops after 10 minutes, or when the turn is interrupted. Other
+turns do not wait. These are schedules, reminders, webhooks, evals, and
+Slack channels without Connect. A required connection fails the call with
+`Reconnect <connection>`. An `optional` connection is skipped, also in the
+playground. Authorize those connections ahead of time with `mcp oauth`.
+
 ## Keep privileged tools behind a wrapper
 
 Put a connection under `bot/host-connections/` when the model should
@@ -3369,21 +3476,14 @@ peer connections, and secrets, then verify a hosted turn. The
 
 Source: /docs/guides/opentelemetry.md
 
-# Observe an agent with OpenTelemetry
-
-OpenTelemetry connects an agent turn to the observability system your
-team already uses. Once you configure an OTLP collector, each request,
-model turn, tool call, and subagent appears alongside token, tool, and
-cost metrics from the serve process.
-
-Export is opt-in. Nothing leaves the process until you configure a
-destination.
+# OpenTelemetry
 
-## Connect an OTLP collector
-
-Set the collector endpoint, start the agent, and send it a message. You
-should see an `agent_sdk.http` request span and an `agent_sdk.turn`
-trace, with any tool or subagent work nested under the turn.
+BDK exports traces, metrics, and logs to an OTLP collector. You
+configure that with standard `OTEL_*` environment variables. There is
+no `defineOtel` or `register()` hook. `ctx.host.otel` is deprecated.
+It still runs for this release and logs one warning per process. Set
+`OTEL_*` variables and record with `metrics.getMeter` and
+`trace.getTracer` from `@opentelemetry/api`.
 
 ```bash
 export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com
@@ -3393,212 +3493,535 @@ export OTEL_SERVICE_NAME=incident-agent
 bdk serve --dir . --dev
 ```
 
-The default protocol is OTLP/HTTP protobuf. If you already call
-`serve()` from TypeScript, you can configure the same destination in
-code:
+The default protocol is OTLP/HTTP protobuf. Set
+`OTEL_EXPORTER_OTLP_PROTOCOL=http/json` when the collector only accepts
+JSON. `grpc` is not supported. BDK logs a warning and uses
+`http/protobuf`.
+
+Metrics use delta temporality by default. BDK logs that default when
+export starts. For Grafana Cloud or Prometheus, set
+`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` to `cumulative`.
+Grafana Cloud rejects delta metrics.
+
+BDK installs trace, metric, and log providers before it imports
+`bot/agent.ts`. A meter, tracer, or logger created at module scope
+binds to those providers. Exporters attach when the process has the
+`OTEL_*` variables. On a hosted agent that is the first request, after
+secrets are in the environment.
+
+With no OTLP endpoint, BDK adds no exporters. Outbound `fetch` does
+not gain a `traceparent` header. The session collector stays disabled.
+
+## Variables
+
+| Variable | Effect |
+| --- | --- |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base URL. BDK appends `/v1/traces`, `/v1/metrics`, and `/v1/logs`. |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Traces URL, used as written. It wins over the base URL. |
+| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Metrics URL, used as written. It wins over the base URL. |
+| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Logs URL, used as written. It wins over the base URL. |
+| `OTEL_EXPORTER_OTLP_HEADERS` | Headers on every export. Values are URL-encoded. Read again on each export. |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf` (default) or `http/json`. gRPC is not supported. |
+| `OTEL_SERVICE_NAME` | `service.name`. Default is the agent name, then `unknown_service:node`. |
+| `OTEL_RESOURCE_ATTRIBUTES` | Resource attributes, including `service.namespace`, `service.version`, and `deployment.environment.name`. |
+| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | `delta` (default), `cumulative`, or `lowmemory`. Use `cumulative` for Grafana Cloud. |
+| `OTEL_LOGS_EXPORTER` | `otlp` turns logs on. Unset, `none`, and `console` leave OTLP logs off. |
+| `OTEL_SDK_DISABLED` | `true` turns export off. |
+| `OTEL_TRACES_EXPORTER` | `none` turns traces off. |
+| `OTEL_METRICS_EXPORTER` | `none` turns metrics off. |
+| `OTEL_LOG_USER_PROMPTS` | `1` puts prompt text on log records. |
+| `OTEL_LOG_TOOL_CONTENT` | `1` puts tool payloads on log records. |
+
+## Hosted agents
+
+Set the endpoint, headers, and service name as secrets. Add the
+collector host to `hosting.egressDomains`. The host is a hostname
+with no scheme and no path.
 
 ```ts
-import { serve } from "@cursor/bdk";
+export default defineAgent({
+  hosting: {
+    egressDomains: ["otlp-gateway-prod-us-east-0.grafana.net"],
+    secretNames: [
+      "OTEL_EXPORTER_OTLP_ENDPOINT",
+      "OTEL_EXPORTER_OTLP_HEADERS",
+      "OTEL_SERVICE_NAME",
+    ],
+  },
+});
+```
+
+Secrets arrive with the first request that has an endpoint. That
+request's export uses those headers and `service.name`. A later
+`bdk secrets set` updates headers on the next export, including a
+rotated key. BDK also replaces the exporter when the URL, protocol,
+or signal list changes. `service.name` is fixed on the first export
+that attaches. Redeploy to change the service name.
+
+## What you can record
+
+Create the tracer, meter, and logger at module scope.
+
+```ts
+import { metrics, trace } from "@opentelemetry/api";
+import { logs } from "@opentelemetry/api-logs";
 
+const tracer = trace.getTracer("incident-agent");
+const lookups = metrics.getMeter("incident-agent").createCounter("incident.lookups");
+const logger = logs.getLogger("incident-agent");
+```
+
+Record during a request, after secrets have loaded. A span or a log
+record that ends before the exporters attach is still exported. BDK
+holds up to 2048 spans and 2048 log records until the exporters
+attach, then sends them. BDK drops each record past that limit. A
+metric recorded before the first collect is included in that collect.
+
+BDK also records HTTP spans, token counts, and tool calls on the
+session. Those spans carry `cursor.conversation.id`. A span you start
+with `trace.getTracer` during a turn or a tool call gets the same
+attribute from the active context. A value you set on the span stays.
+BDK does not overwrite it. The id stays in this process. It is not
+propagated.
+
+A metric does not get `cursor.conversation.id`. Read the id and set
+the attribute yourself.
+
+```ts
+import { metrics } from "@opentelemetry/api";
+import { currentConversationId } from "@cursor/bdk/otel";
+
+const lookups = metrics.getMeter("incident-agent").createCounter("incident.lookups");
+
+lookups.add(1, { "cursor.conversation.id": currentConversationId() });
+```
+
+Prompt text and tool payloads stay off log records unless logs are on
+(`OTEL_LOGS_EXPORTER=otlp`) and you set `OTEL_LOG_USER_PROMPTS` or
+`OTEL_LOG_TOOL_CONTENT`.
+
+## Limits
+
+These are not supported yet.
+
+- Custom span processors, samplers, and views.
+- Bringing your own OpenTelemetry SDK.
+- Library auto-instrumentation.
+- A `register()` hook. There is no ticket for it yet.
+- `OTEL_TRACES_SAMPLER` and `OTEL_METRIC_EXPORT_INTERVAL` that arrive
+  only with hosted secrets. BDK reads them when it builds the provider,
+  which is before that secret load. Set them on the process, then
+  restart. BDK logs a warning when a later value differs.
+
+Do not import your own SDK providers next to BDK's. BDK logs a warning
+when a module replaces a provider BDK registered. The global API then
+uses that module's provider. BDK shuts down a provider it created
+only when that provider is not the one it registered.
+
+## Migrating from serve({ otel })
+
+`serve({ otel })` is removed. Delete the option. Set the same
+values with `OTEL_*` variables. Delete `bot/otel.ts`,
+`agent/otel.ts`, and `bot/instrumentation.ts`. Do not call
+`defineOtel`.
+
+BDK sends each signal to one URL. A second exporter for the same
+signal has no variable.
+
+| Old option | Set this instead |
+| --- | --- |
+| `serviceName` | `OTEL_SERVICE_NAME` |
+| `serviceVersion` | `service.version` in `OTEL_RESOURCE_ATTRIBUTES` |
+| `resourceAttributes` | `OTEL_RESOURCE_ATTRIBUTES`. Separate pairs with commas. URL-encode each value. |
+| `exporters[].url` | `OTEL_EXPORTER_OTLP_ENDPOINT`. BDK appends `/v1/traces`, `/v1/metrics`, and `/v1/logs`. |
+| `exporters[].url` with `signals` | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, or `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`. BDK uses that URL as written. |
+| `exporters[].headers` | `OTEL_EXPORTER_OTLP_HEADERS`. Separate pairs with commas. URL-encode each value. |
+| `exporters[].protocol` | `OTEL_EXPORTER_OTLP_PROTOCOL`. Use `http/protobuf` or `http/json`. For one signal, use `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`, `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`, or `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL`. |
+| `exporters[].signals` | Set the signal URL above. Set `OTEL_TRACES_EXPORTER`, `OTEL_METRICS_EXPORTER`, or `OTEL_LOGS_EXPORTER` to `none` to stop that signal. |
+| `traces: false` | `OTEL_TRACES_EXPORTER=none` |
+| `traces: true` | Leave `OTEL_TRACES_EXPORTER` unset. Traces start when an endpoint is set. |
+| `traces.sampleRatio` | `OTEL_TRACES_SAMPLER=parentbased_traceidratio` and `OTEL_TRACES_SAMPLER_ARG` set to the ratio. Set both before the process starts. |
+| `metrics: false` | `OTEL_METRICS_EXPORTER=none` |
+| `metrics: true` | Leave `OTEL_METRICS_EXPORTER` unset. Metrics start when a metrics URL is set. |
+| `metrics.exportIntervalMillis` | `OTEL_METRIC_EXPORT_INTERVAL`, in milliseconds. Set it before the process starts. |
+| `logs: false` | Leave `OTEL_LOGS_EXPORTER` unset, or set it to `none`. |
+| `logs: true` | `OTEL_LOGS_EXPORTER=otlp` |
+| `logs.userPrompts` | `OTEL_LOGS_EXPORTER=otlp` and `OTEL_LOG_USER_PROMPTS=1` |
+| `logs.toolContent` | `OTEL_LOGS_EXPORTER=otlp` and `OTEL_LOG_TOOL_CONTENT=1` |
+| `otel: false` | Set no endpoint, or set `OTEL_SDK_DISABLED=true`. |
+
+Before:
+
+```ts
 await serve(".", {
   otel: {
     serviceName: "incident-agent",
     exporters: [
       {
         url: "https://otel.example.com",
-        headers: {
-          Authorization: `Bearer ${process.env.OTEL_TOKEN ?? ""}`,
-        },
+        headers: { Authorization: `Bearer ${process.env.OTEL_TOKEN ?? ""}` },
       },
     ],
   },
 });
 ```
 
-Use environment variables when you start the agent with
-`bdk serve`. Use `serve({ otel })` when your TypeScript
-application starts the server itself. When that application
-already uses OpenTelemetry, BDK sends its traces, metrics, and
-logs to the collector configured here.
+After:
 
-## Export from a hosted agent
+```bash
+export OTEL_SERVICE_NAME=incident-agent
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20$OTEL_TOKEN"
+bdk serve --dir . --dev
+```
 
-Set the collector endpoint and headers as secrets, and add the
-collector host to `hosting.egressDomains`. The host is a hostname
-with no scheme and no path. The first request loads the secrets,
-and export starts with those headers.
+On a hosted agent, put the same names in `hosting.secretNames`. Add
+the collector host to `hosting.egressDomains`. Then run:
+
+```bash
+bdk secrets set my-agent OTEL_SERVICE_NAME OTEL_EXPORTER_OTLP_ENDPOINT OTEL_EXPORTER_OTLP_HEADERS
+```
+
+---
+
+Source: /docs/guides/pagerduty.md
+
+# PagerDuty agents
+
+A PagerDuty agent wakes when an incident triggers, investigates it, and
+writes what it found back to the incident. `pagerdutyChannel()` receives
+PagerDuty's v3 webhooks, verifies them, and keeps every later event for
+the same incident in one session, so the agent sees an acknowledgement,
+a note, or a responder's reply in the context of the investigation it
+already started. Every setting has a default read from a well-known secret, so
+the channel needs no configuration beyond its hooks; see
+[Connect](#connect) for the variables.
+
+## Investigate a new incident
+
+When an incident triggers, the agent starts a turn with the incident's
+title, service, urgency, and link. It reads whatever the investigation
+needs, and with `deliverReplies: true` its reply is posted as a note on
+the incident, where the person on call already looks.
+
+```ts
+// bot/channels/pagerduty.ts
+import { defaultPagerDutyAuth, pagerdutyChannel } from "@cursor/bdk/channels/pagerduty";
+
+export default pagerdutyChannel({
+  deliverReplies: true,
+  onIncident: (ctx, event) => {
+    if (event.eventType !== "incident.triggered") {
+      return null;
+    }
+    return {
+      // `auth` starts a model turn running as the event's PagerDuty actor.
+      auth: defaultPagerDutyAuth(ctx),
+      message: `Investigate PagerDuty incident #${event.incident.number}: ${event.incident.title}`,
+      context: [`Service: ${event.incident.service?.summary ?? "unknown"}`],
+    };
+  },
+});
+```
+
+Reply notes are off unless you set `deliverReplies: true`, so the channel
+writes nothing to PagerDuty on its own. An agent that writes to PagerDuty
+through its own path, such as a service that audits each write, leaves it
+off and posts only what it chooses, from `events` or `ctx.pagerduty`.
+
+With `deliverReplies: true`, the channel posts each completed reply as a
+note on the session's incident, and a short note if a turn fails, using
+the `PAGERDUTY_TOKEN` secret. The note goes to the incident in the
+verified event's state, so the model never chooses which incident it
+writes to. Eval runs and agents without a token post nothing. Nothing is
+posted until the channel knows the agent's own PagerDuty user (see
+[Ignore your own actions](#ignore-your-own-actions)), because each note
+comes back as a webhook event that only the echo skip keeps from starting
+another turn. Handlers you write in `events` replace the built-in ones.
+
+Hooks also get `ctx.pagerduty`, a REST client with the channel's
+credentials, for reads and writes of their own:
+
+```ts
+onIncident: async (ctx, event) => {
+  const incident = await ctx.pagerduty.getIncident(event.incident.id);
+  // …
+},
+```
+
+Hosted, the agent also declares PagerDuty's API host and the token:
 
 ```ts
 // bot/agent.ts
 import { defineAgent } from "@cursor/bdk";
 
 export default defineAgent({
+  architecture: "v2",
   hosting: {
-    egressDomains: ["otlp-gateway-prod-us-east-0.grafana.net"],
-    secretNames: ["OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_HEADERS"],
+    egressDomains: ["api.pagerduty.com"],
+    secretNames: ["PAGERDUTY_TOKEN"],
   },
 });
 ```
 
-```bash
-bdk secrets set my-agent OTEL_EXPORTER_OTLP_ENDPOINT OTEL_EXPORTER_OTLP_HEADERS
+## Follow the incident in one session
+
+People act on an incident while the agent investigates: someone
+acknowledges it, adds a note, pulls in a responder, or resolves it.
+Return a dispatch for those events too, and each one arrives in the
+session that is already working on the incident, with the earlier
+findings in context.
+
+```ts
+onIncident: (ctx, event) => {
+  const followUps = ["incident.acknowledged", "incident.reassigned", "incident.resolved"];
+  if (event.eventType !== "incident.triggered" && !followUps.includes(event.eventType)) {
+    return null;
+  }
+  return {
+    auth: defaultPagerDutyAuth(ctx),
+    message: `${event.eventType} by ${ctx.agent?.summary ?? "PagerDuty"}`,
+  };
+},
+onNote: (ctx, note) => {
+  return {
+    auth: defaultPagerDutyAuth(ctx),
+    message: `Note on the incident: ${note.content}`,
+  };
+},
 ```
 
-`OTEL_EXPORTER_OTLP_HEADERS` is a comma-separated list of
-`name=value` pairs. Each value is URL-encoded, so a space is
-`%20` (`Authorization=Basic%20...`).
+Add these to the same `pagerdutyChannel()` declaration as the
+investigation handler.
 
-A later `bdk secrets set` changes the headers on the next export.
-You do not redeploy to rotate a token. The URL, service name,
-resource attributes, signals, sample ratio, and metric export
-interval stay as they were on the first export. Redeploy to change
-one of those. BDK logs a warning when one of them changes on a
-running agent.
+## Ignore your own actions
 
-When an exporter host is missing from `hosting.egressDomains`, BDK
-logs an error that names the host. Add the host and redeploy.
+PagerDuty sends the agent's own changes back as webhook events: the
+note it posted, or an acknowledgement or resolve made through its
+PagerDuty user. The channel acknowledges those events without running a
+hook or starting a turn. The same action by a person is still delivered.
 
-Spans and metrics from before the first request are not exported,
-including spans from channel `onStart`. If the OpenTelemetry config
-fails, BDK logs the error and the request still completes.
+The channel finds the agent's user in this order, on each delivery:
 
-Logs stay off until `serve({ otel })` sets `logs`, or until
-`OTEL_LOGS_EXPORTER` is `otlp`. Prompt text and tool payloads stay
-off until you set `OTEL_LOG_USER_PROMPTS` or
-`OTEL_LOG_TOOL_CONTENT`.
+1. The `selfUserIds` option, when you pass one. Nothing below is used.
+2. The `PAGERDUTY_USER_ID` secret: one PagerDuty user id.
+3. The user `PAGERDUTY_TOKEN` acts as, which PagerDuty reports at
+   `GET /users/me`.
 
-## Follow one conversation
+When none of these names a user, echo skip is off. `bdk deploy` warns
+while neither `PAGERDUTY_USER_ID` nor `PAGERDUTY_TOKEN` is set, and the
+agent logs a warning when its token names no single user.
 
-Copy the complete session ID from the playground or session API, then
-filter your observability system on either `agent_sdk.session_id` or
-`cursor.conversation.id`. Every turn in that conversation carries the
-same value, including follow-ups and tool work.
+Inference depends on the kind of token:
 
-The trace shape stays small:
+| `PAGERDUTY_TOKEN` | Inferred user |
+| --- | --- |
+| User token REST API key | The key's own user |
+| OAuth user token (Classic User OAuth or Scoped OAuth), written as `Bearer <token>` | The user who authorized the app |
+| General access (account-level) REST API key | The user whose email is exactly `PAGERDUTY_FROM_EMAIL`, if set |
+| Scoped OAuth app token (client credentials) | The user whose email is exactly `PAGERDUTY_FROM_EMAIL`, if set |
+
+PagerDuty serves
+[`GET /users/me`](https://developer.pagerduty.com/api-reference/0b6f8b0c3e8d1-get-the-current-user)
+only to a user-level API key or a token from an OAuth flow, not to an
+account-level key. An app token
+[acts as the app](https://docs.pagerduty.com/developer/private-apps),
+not as a user. With either, the channel looks up `PAGERDUTY_FROM_EMAIL`,
+the `From` user the token writes as, through `GET /users?query=` and uses
+the one user whose email matches exactly. The inferred id is kept in the
+agent's memory for an hour per token, never in agent storage, and an
+unresolved answer is retried after five minutes. Hosted, the lookup needs
+`api.pagerduty.com` (or your `PAGERDUTY_API_BASE_URL` host) in
+`hosting.egressDomains`, the same entry write-backs need.
+
+A read-only agent with no token sets the id directly:
 
-```text
-request: agent_sdk.http
+```bash
+bdk secrets set incident-responder PAGERDUTY_USER_ID
+```
+
+`PAGERDUTY_USER_ID` holds one id because a deployment has one token
+and so acts as one PagerDuty user. To skip several users, or to keep the
+id in code, pass `selfUserIds`:
 
-turn: agent_sdk.turn
-      |- agent_sdk.tool
-      `- agent_sdk.subagent
-         `- agent_sdk.tool
+```ts
+export default pagerdutyChannel({
+  selfUserIds: ["PBOT001"],
+  onIncident: (ctx) => ({ auth: defaultPagerDutyAuth(ctx) }),
+});
 ```
 
-A conversation can produce several turn traces, so use the session ID
-as the join key instead of expecting one long-lived session span.
+`selfUserIds: { secretName: "OTHER_NAME" }` reads one id from another
+secret and never falls back to inference.
 
-### Subagents
+## Events
 
-A subagent's tool calls are `agent_sdk.tool` spans under its
-`agent_sdk.subagent` span. Its `reasoning.completed` and
-`message.completed` events sit on that span too, so the subagent span
-shows where its time went. Time between two tool spans is the model
-choosing the next step. A subagent that fails or is cancelled ends its
-span with ERROR status when it stops.
+Each hook receives one family of v3 events:
 
-### Computer use
+| Hook | Events |
+| --- | --- |
+| `onIncident` | `incident.triggered`, `.acknowledged`, `.unacknowledged`, `.escalated`, `.reassigned`, `.delegated`, `.resolved`, `.reopened`, `.priority_updated`, `.incident_type.changed` |
+| `onNote` | `incident.annotated` |
+| `onResponder` | `incident.responder.added`, `incident.responder.replied` |
+| `onEvent` | Everything else, such as status updates and workflow events |
 
-Each computer use action is an `agent_sdk.tool` span with
-`cursor.tool.name` set to `computerUse`, under the computer use
-subagent's span. A failed action has ERROR status. These attributes
-describe the action without typed text, coordinates, or screenshots:
+Without `onIncident`, a triggered or reopened incident starts a turn and
+other lifecycle events are acknowledged. Notes, responder events, and
+the rest are acknowledged until you add their hook. Each hook returns
+one of three decisions:
 
-| Attribute | Value |
+| Return | What happens |
 | --- | --- |
-| `agent_sdk.computer.actions` | The action type, such as `click`, `type`, or `screenshot` |
-| `agent_sdk.computer.executor_duration_ms` | Time the desktop took to run the action and capture the screen |
-| `agent_sdk.computer.settle_ms` | Part of that time spent waiting for the screen to settle |
+| `{ auth }` | Start or continue a model turn as the event's actor |
+| `{ task }` | Acknowledge the webhook, then run host code that may also call `send` |
+| `null` | Skip the event |
 
-The two durations appear only on actions that succeed.
+## Incident affinity
 
-To export the full actions, turn on tool content as shown in
-[Control what leaves the process](#control-what-leaves-the-process).
-Tool content includes the text the agent typed, which can contain
-passwords.
+Every event for one incident joins one session, keyed on the incident
+id. Lifecycle events carry the incident, and notes and responder events
+name it by reference, so all of them reach the same session.
 
-## Add domain telemetry
+A re-trigger after a resolve is a new PagerDuty incident, so it starts a
+new session. `ctx.incidentKey` carries the dedup key of the alert that
+opened an incident (its `incident_key`, set per alert by a Datadog
+monitor, a Sentry issue, or a Grafana rule), for an agent that wants to
+recall what it found the last time the same alert fired.
 
-Use `ctx.host.otel` when your dashboard should answer questions the
-built-in telemetry cannot, such as which incident a turn handled or how
-long approval took. Attributes appear on the active turn and tool
-spans, while counters and histograms give you metrics to graph and
-alert on.
+## Connect
 
-```ts
-ctx.host.otel.setAttributes({
-  "support.ticket_id": "INC-123",
-  "support.queue": "p1",
-});
+Create a v3 webhook subscription in PagerDuty for the services that
+should wake the agent, and point it at
+`https://<your-host>/<slug>/v1/channels/pagerduty`. Then set the
+channel's secrets on the deployment. Locally the same names are
+environment variables.
 
-ctx.host.otel.increment("support.ticket.resolved", {
-  outcome: "fixed",
-});
+| Variable | Used for | Override |
+| --- | --- | --- |
+| `PAGERDUTY_WEBHOOK_SECRET` | Verifying `X-PagerDuty-Signature`. Hosted, the platform checks it before any compute starts and answers a bad delivery with `401` | `webhookSecret: { secretName }` |
+| `PAGERDUTY_USER_ID` | Skipping the agent's own actions: its PagerDuty user id. Optional when `PAGERDUTY_TOKEN` names a user | `selfUserIds: [ids]` or `{ secretName }` |
+| `PAGERDUTY_TOKEN` | Reply notes (with `deliverReplies: true`), `ctx.pagerduty`, and inferring the agent's user: a REST API key, or an OAuth token as `Bearer <token>` | `token: { secretName }` |
+| `PAGERDUTY_FROM_EMAIL` | The `From` user PagerDuty requires for writes made with an account-level key or app token, and the user inferred for those tokens | `from: { secretName }` |
+| `PAGERDUTY_API_BASE_URL` | The REST host, such as `https://api.eu.pagerduty.com`. Defaults to `https://api.pagerduty.com` | `apiBaseUrl` |
 
-ctx.host.otel.record("support.approval.duration_ms", 1420, {
-  outcome: "approved",
-});
+Set `token`, `from`, and `apiBaseUrl` on `pagerdutyChannel()`; they cover
+reply notes, `ctx.pagerduty`, and inference. `createPagerDutyClient()`
+takes the same options for code outside the channel.
+
+```bash
+bdk deploy --dir . --slug incident-responder
+bdk secrets set incident-responder PAGERDUTY_WEBHOOK_SECRET PAGERDUTY_TOKEN
+bdk secrets list incident-responder
 ```
 
-This API is available in tools, hooks, and channel handlers. A
-session-bound context adds `cursor.conversation.id` and
-`agent_sdk.agent` automatically, so custom measurements join the
-first-party telemetry without extra plumbing.
+`bdk deploy` warns until `PAGERDUTY_WEBHOOK_SECRET` is set, and until
+either `PAGERDUTY_USER_ID` or `PAGERDUTY_TOKEN` is. The next delivery
+uses a new value without another deploy.
 
-Prefix custom names with your team or agent. First-party metric names
-and join keys are reserved, and this surface does not create custom
-spans.
+### Several subscriptions
 
-## Choose signals
+PagerDuty gives each webhook subscription its own signing secret, so an
+agent fed by several subscriptions (one per service, say) needs all of
+them. Put them in `PAGERDUTY_WEBHOOK_SECRET`, one per line:
 
-Once export has a destination, traces and metrics are on by default;
-logs remain off until you opt in.
+```text
+<signing secret of subscription 1>
+<signing secret of subscription 2>
+```
 
-| Signal | What appears |
-| --- | --- |
-| Traces | HTTP requests, turns, tools, and subagents |
-| Metrics | Token usage, tool calls, cost, and BDK session or turn counts |
-| Logs | Session events, after you enable log export |
+A delivery is admitted when any `v1=` signature in its
+`X-PagerDuty-Signature` header matches any line. Each line is trimmed,
+blank lines are ignored, and a value without a line break is one secret,
+used as-is. The value holds at most 32 secrets. Past that, every delivery
+is rejected rather than checked against only some of them.
 
-The first metrics to look for are `cursor.token.usage`,
-`cursor.tool.calls`, and `cursor.cost.usage`. Configure
-`traces: false`, `metrics: false`, or `logs: true` under
-`serve({ otel })` when you need a different signal mix.
+Keep the list in a file, since `bdk secrets list` never shows values,
+and set it from stdin, which keeps the line breaks:
 
-## Control what leaves the process
+```bash
+bdk secrets set incident-responder PAGERDUTY_WEBHOOK_SECRET < pagerduty-webhook-secrets.txt
+```
+
+Rotate by adding before removing. Add the new secret as a line before
+PagerDuty starts signing with it, for example before creating the
+replacement subscription. Remove the old line only once nothing signs
+with the old secret, for example after deleting the subscription it
+replaced. While both are live, a delivery signed with either secret
+verifies, including one whose header carries both signatures. Removing
+the old line first rejects those deliveries until the new one is added.
+
+The same format works for every `hmacSignatureAuth()` secret, including
+`GITHUB_WEBHOOK_SECRET` and `BITBUCKET_WEBHOOK_SECRET`. It needs
+`@cursor/bdk` 0.2.25 or later. Earlier versions check the signature again
+in the agent with the whole value as one secret, so they reject every
+delivery once the value has a second line.
 
-Traces include structure, tool names, usage metrics, and span
-status. A failed tool's status includes a short failure reason.
-A tool or subagent that is still open when the turn ends gets
-ERROR status with the reason `no result`. User prompts, tool
-arguments, and full tool results stay off the wire until you opt in.
+Only signature checks read the value as a list. Everywhere else it is
+used whole: a `sharedSecretAuth()` header compares the entire value, and
+a `${NAME}` template in an MCP connection's `headers` would put the line
+breaks into the header. Keep a list secret for webhook signing only.
+
+Until `PAGERDUTY_WEBHOOK_SECRET` is set, the route accepts only local
+traffic: loopback deliveries under `bdk dev`, nothing in production.
+
+## Test locally
 
-Turn on logs first, then opt into prompt or tool content separately:
+`bdk pagerduty replay` posts synthesized v3 deliveries for one incident
+to the running agent, in order. With `PAGERDUTY_WEBHOOK_SECRET` unset,
+`bdk dev` admits them unsigned from loopback; with it set, replay signs
+them the way PagerDuty does:
 
 ```bash
-export OTEL_LOGS_EXPORTER=otlp
-export OTEL_LOG_USER_PROMPTS=1
-export OTEL_LOG_TOOL_CONTENT=1
+bdk dev &
+bdk pagerduty replay --events triggered,acknowledged,annotated,resolved \
+  --comment "Rolled back the 09:30 deploy."
 ```
 
-`OTEL_LOG_USER_PROMPTS` exports user text. `OTEL_LOG_TOOL_CONTENT`
-exports tool inputs, outputs, and failure details. Enable either only
-when the collector's access and retention policies are appropriate for
-that data.
+The trigger comes from PagerDuty itself, and the later events come from a
+person, so each one joins the session the trigger started. Pass an
+incident id to start another session, `--dry-run` to print the bodies,
+or `--out fixtures/pagerduty` to save them as fixtures for
+[evals](/docs/evals.md). `bdk pagerduty events` lists the channels and the
+events each accepts.
 
-The same controls are available as
-`logs: { userPrompts, toolContent }` under `serve({ otel })`.
+To post a real delivery saved from the webhook's delivery log, sign it
+with the secret:
+
+```bash
+export PAGERDUTY_WEBHOOK_SECRET=local-test-secret
+bdk dev &
+
+body=fixtures/pagerduty/incident-triggered.json
+signature=$(openssl dgst -sha256 -hmac "$PAGERDUTY_WEBHOOK_SECRET" -hex < "$body" | awk '{print $NF}')
+curl -X POST http://127.0.0.1:3000/v1/channels/pagerduty \
+  -H 'content-type: application/json' \
+  -H "x-pagerduty-signature: v1=$signature" \
+  --data-binary @"$body"
+```
+
+Set `event.agent.id` in a saved body to the agent's own user id to see
+the delivery skipped as an echo.
+
+## Practices
+
+- Write back from host code with the incident in channel state or
+  `ctx`, never from an incident id the model produced.
+
+- Make sure the agent knows its own user before it acts on incidents, so
+  its own notes and resolves do not wake it again: a user-level token, a
+  `PAGERDUTY_FROM_EMAIL` with an account-level key, or `PAGERDUTY_USER_ID`.
+
+- Scope the webhook subscription to the services the agent responds to;
+  every delivery it sends reaches the channel.
 
 ## Related
 
-- [`skills/otel/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/otel/SKILL.md): compact
-  configuration and custom-metric reference for coding agents
-- [Hooks](/docs/reference/hooks.md): emit domain telemetry from session
-  events
-- [Deployment](/docs/deployment.md): declare `hosting.egressDomains`
-  and set collector secrets on a hosted agent
-- [Cursor enterprise OpenTelemetry Export](https://cursor.com/docs/enterprise/opentelemetry-export):
-  send organization-wide Cursor telemetry to the same collector
+- [Channels reference](/docs/reference/channels.md): channel hooks,
+  dispatch decisions, and session behavior
+- [Webhooks and custom channels](/docs/guides/webhooks.md): direct webhook auth
+  and reply delivery
+- [Evals](/docs/evals.md): turn saved PagerDuty payloads into regression
+  fixtures
 
 ---
 
@@ -3700,6 +4123,47 @@ export default slackChannel({
 });
 ```
 
+### Show steps as cards or as a checklist
+
+The agent calls `post-card` to show one step of its work, such as
+"Scan the repo". Each card has an `id`, a `title`, a `status`, and
+optional `details`. When the agent calls `post-card` again with the same
+`id`, Slack updates that card. The agent uses this to move a step from
+`in_progress` to `complete`.
+
+`cards` sets how Slack draws these steps:
+
+| `cards` | What Slack shows | Use it when |
+| --- | --- | --- |
+| `{ display: "timeline" }` (default) | Each step is a separate card in the thread. | The turn has one or two short steps. |
+| `{ display: "plan" }` | All steps from one turn are in one checklist. | The turn has several steps, and readers want to see progress in one place. |
+
+This bot shows its steps as one checklist with the title "Release check":
+
+```ts
+export default slackChannel({
+  reply: {
+    mode: "agentic",
+    cards: { display: "plan", title: "Release check" },
+  },
+});
+```
+
+Know these rules for a plan:
+
+- The `title` is optional. It can have at most 256 characters.
+- You set the `title` in the channel configuration. The agent cannot
+  change the title.
+- Each turn starts a new checklist with the same title.
+- The `pending` status shows a step that has not started. Use `pending`
+  only in a plan.
+- `slackChannel` stops at startup if `cards` is not valid. For example,
+  a `title` with `display: "timeline"` stops startup.
+
+`display` is Slack's
+[`task_display_mode`](https://docs.slack.dev/reference/methods/chat.startStream/),
+and the channel sends `title` as a `plan_update` chunk.
+
 ## Wake on a channel post
 
 This example watches `#triage-alerts`, so any substantial top-level
@@ -4891,15 +5355,35 @@ const handle = await serve("./my-agent", {
 });
 console.log(`listening on ${handle.url}`);
 // handle.callTool(...), handle.dispatchSchedule("heartbeat"),
-// handle.createReminder(...), handle.project, await handle.close()
+// handle.createReminder(...), handle.agents, await handle.close()
 ```
 
+`handle.agents` lists each mount as `slug`, `url`, and `info`. `handle.project` is the first agent's project. It is deprecated.
+
 Host settings match the documented [CLI](/docs/reference/cli.md) `serve` flags.
 `serve()` also accepts `discovery` (project-loading options) and
 `mode: "single" | "multi"`. Pass `apiKey` or use the same Cursor
 credential as the CLI: `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`,
 `CURSOR_SERVICE_ACCOUNT_KEY`, or `bdk login`.
 
+## Inspect a project in tests
+
+`loadProject(dir)` reads one project and does not serve it. The result is a `Project`. The only field is `info`. That object matches the `GET /v1/info` body for the project. `bdk info --json` on a project directory prints `{ agents: [{ slug, ...info }] }`. It prints the bare object only when the single mount slug is empty.
+
+```ts
+import { loadProject } from "@cursor/bdk";
+
+const project = await loadProject("./my-agent");
+console.log(project.info.name);
+console.log(project.info.tools.map((tool) => tool.name));
+```
+
+`loadProject` throws `ProjectLoadError` when discovery reports an error. Pass `{ strict: true }` to throw on a warning as well. `error.diagnostics` lists the findings. Each `path` is relative to the project directory. A path outside that directory starts with `../`. `loadProject` does not take `importModule`. `serve` still accepts `discovery.importModule` for that override.
+
+`info.local` is `{ cwd }` when the project sets a cwd. The serve banner reads `agents[].info`.
+
+`serve` accepts that `Project` or a directory path.
+
 ## Related
 
 - [Instructions](/docs/reference/instructions.md): the required half of a minimal
@@ -5144,11 +5628,15 @@ Each handler receives the Fetch `Request` and a typed arguments object.
 | `purpose` | Use `"eval"` to mark a new session as regression traffic |
 | `dryRun` | Run read tools and stub write tools for a new session |
 | `asOf` | Freeze a new session at an ISO-8601 instant with a timezone |
+| `deliveryId` | Name this send on the session's events, at most 256 characters. Defaults to a fresh `dlv_…` ID |
 
 `send` returns a `ChannelSession`. Its `id` identifies the session,
 `continuationToken` contains its current channel key, and `isNew` says
 whether this call created it. A coalesced call also returns
-`coalesced: true`.
+`coalesced: true`. `deliveryId` names this send on the event where the
+message reaches the agent; see
+[Track which follow-up reached the agent](/docs/reference/sessions.md#track-which-follow-up-reached-the-agent).
+A hosted channel's `send` returns the same ID before the session exists.
 
 ## Events
 
@@ -5193,7 +5681,7 @@ returns `401`.
 | `loopbackOnly()` | Any loopback TCP peer, including local relays that carry forwarding headers |
 | `bearerAuth(tokenOrVerify)` | A matching bearer token, or a token accepted by the verifier |
 | `sharedSecretAuth({ header, secret })` | A header matching the named environment or deployment secret |
-| `hmacSignatureAuth({ header, secret, prefix? })` | A hex HMAC-SHA256 signature over the raw body using the named secret |
+| `hmacSignatureAuth({ header, secret, prefix?, separator? })` | A hex HMAC-SHA256 signature over the raw body using the named secret. With `separator`, any of several signatures in the header. A secret holding one value per line verifies under any of them (at most 32, `@cursor/bdk` 0.2.25 or later) |
 | `allowAll()` | Every caller as an anonymous principal |
 | `publicEndpoint()` | Every caller on this custom channel; managed hosting also exposes the route without an alias token |
 
@@ -5220,6 +5708,7 @@ author their own chain, and `--allow-anonymous` swaps it for
 | `@cursor/bdk/channels/github` | `githubChannel()` | GitHub and GitHub Enterprise webhooks. See [GitHub](/docs/guides/github.md) |
 | `@cursor/bdk/channels/gitlab` | `gitlabChannel()` | GitLab.com and self-managed GitLab hooks. See [GitLab](/docs/guides/gitlab.md) |
 | `@cursor/bdk/channels/bitbucket` | `bitbucketChannel()` | Bitbucket Cloud and Data Center hooks. See [Bitbucket](/docs/guides/bitbucket.md) |
+| `@cursor/bdk/channels/pagerduty` | `pagerdutyChannel()` | PagerDuty v3 incident webhooks. Replies post as incident notes only with `deliverReplies: true`. See [PagerDuty](/docs/guides/pagerduty.md) |
 | `@cursor/bdk/channels/deployments` | `deploymentsChannel()` | Deployment events filtered by source, environment, or event name |
 
 For other platforms like Discord or Teams, use the authored
@@ -6265,6 +6754,33 @@ follow the GitHub replay contract.
 
 See [Bitbucket](/docs/guides/bitbucket.md) for Cloud and Data Center setup.
 
+### Test PagerDuty webhooks {#pagerduty}
+
+```text
+bdk pagerduty replay [incident-id]
+  [--events a,b,c | '*'] [--comment <body>]
+  [--dir <path>] [--slug <slug>] [--channel <id>]
+  [--url <url>] [--host <host>] [--port <n>]
+  [--secret <secret>] [--dry-run] [--out <dir>] [--json]
+bdk pagerduty events [--dir <path>] [--host <host>] [--port <n>] [--json]
+```
+
+| Subcommand | Contract |
+| --- | --- |
+| `replay` | Synthesize v3 webhook bodies for one incident and post them, in order, to matching channels. The default event is `incident.triggered`; `'*'` selects every declared event replay supports. |
+| `events` | List discovered PagerDuty channel URLs and event types. |
+
+Replay supports `incident.triggered`, `.acknowledged`, `.annotated`,
+`.escalated`, `.resolved`, and `.reopened`, by full name or by action alone
+(`resolved`). It needs no PagerDuty account. The incident id defaults to
+`PREPLAY1`, and `--comment` is the note body for `annotated`. `--secret`
+defaults to `PAGERDUTY_WEBHOOK_SECRET`, signing with its first line when it
+lists several; without either the deliveries are unsigned, which `bdk dev`
+admits from loopback. `--dry-run` and `--out`
+follow the GitHub replay contract.
+
+See [PagerDuty](/docs/guides/pagerduty.md) for channel setup.
+
 ## Environment variables
 
 Credential resolution follows this order: `--api-key`, `CURSOR_API_KEY`,
@@ -7170,20 +7686,26 @@ Author `bot/hooks/<name>.ts` with `defineHook` from
 
 ```ts
 // bot/hooks/usage.ts
+import { metrics } from "@opentelemetry/api";
 import { defineHook } from "@cursor/bdk/hooks";
 
+const meter = metrics.getMeter("acme");
+const inputTokens = meter.createCounter("acme.tokens.input");
+const outputTokens = meter.createCounter("acme.tokens.output");
+const turnFailed = meter.createCounter("acme.turn.failed");
+
 export default defineHook({
   events: {
     async "turn.completed"(event, ctx) {
       if (ctx.session.purpose === "eval" || event.data.usage === undefined) {
         return;
       }
-      const { inputTokens, outputTokens } = event.data.usage;
-      ctx.host.otel.increment("acme.tokens.input", inputTokens);
-      ctx.host.otel.increment("acme.tokens.output", outputTokens);
+      const usage = event.data.usage;
+      inputTokens.add(usage.inputTokens);
+      outputTokens.add(usage.outputTokens);
     },
     async "turn.failed"(_event, ctx) {
-      ctx.host.otel.increment("acme.turn.failed", { channel: ctx.channel.id });
+      turnFailed.add(1, { channel: ctx.channel.id });
     },
   },
 });
@@ -7235,7 +7757,6 @@ exported from `@cursor/bdk`.
 | `ctx.channel`                                       | `{ id, continuationToken }`. The token is `null` when the session can't take follow-ups                                                                    |
 | `ctx.host.kv`                                       | Durable JSON, shared by every session of the agent. Prefix keys with `ctx.session.id` for per-session state                                                |
 | `ctx.host.files`                                    | Durable files, bound to this session. Pass `{ scope: "deployment" }` for agent-wide files                                                                  |
-| `ctx.host.otel`                                     | Counters, histograms, and tags, attributed to this session                                                                                                 |
 | `ctx.host.mcp`, `ctx.host.github`, `ctx.host.slack` | The same shared clients tools get                                                                                                                          |
 | `ctx.host.reminders`                                | Per-session [reminders](/docs/reference/schedules.md#reminders), the same API tools get                                                                                  |
 | `ctx.artifacts`                                     | Session-bound [artifacts](/docs/reference/artifacts.md) facade: `tag` fills in `sessionId` and `turnId`                                                                  |
@@ -8227,6 +8748,51 @@ the session is already busy depends on the channel:
 Pass `admission: "coalesce"` on `send()` to opt into the Slack policy from
 other callers. Omit it (or pass `"preempt"`) to keep interrupt semantics.
 
+### Track which follow-up reached the agent
+
+Every `send()` returns a `deliveryId`. Pass your own as the `deliveryId`
+option, such as the webhook delivery ID you already hold, or omit it to
+get a fresh `dlv_…` ID. A coalesced follow-up reaches the agent in one of
+two ways, and the ID is on the event for that path:
+
+| Path | Event | Field |
+| --- | --- | --- |
+| Steered into the running turn | `nudge.delivered` | `data.deliveryId` |
+| Fell back to the next turn | That turn's `message.received` | `data.deliveryIds` |
+
+`message.received` lists every send its prompt carries, in arrival order.
+Follow-ups queued behind a busy turn drain into one turn, so the list can
+hold several IDs. A direct send that starts a turn gets a one-item list.
+
+```ts
+// In a route or channel hook: name the steer after the webhook delivery.
+await send(`Incident ${incident.id} was acknowledged.`, {
+  continuationToken: incident.id,
+  admission: "coalesce",
+  deliveryId: webhookId,
+});
+
+// In the channel's `events` map:
+const steered = new Set<string>();
+const prompted = new Set<string>();
+const events: ChannelEventHandlers = {
+  "nudge.delivered": async (event) => {
+    if (event.data.deliveryId !== undefined) {
+      steered.add(event.data.deliveryId);
+    }
+  },
+  "message.received": async (event) => {
+    for (const id of event.data.deliveryIds ?? []) {
+      prompted.add(id);
+    }
+  },
+};
+```
+
+A local Slack session can also pick up follow-ups at a tool boundary from
+its own thread store. That `nudge.delivered` has no `deliveryId`, which
+tells it apart from a steered send.
+
 `POST /v1/session/:id/stop` interrupts a turn without sending a new
 message. The stream records `turn.failed` with `status: "cancelled"`;
 the session stays a chat session and can take another follow-up. A
@@ -8245,7 +8811,7 @@ within one session. The `at` field is an ISO-8601 timestamp.
 | Phase | Events | What they tell you |
 | --- | --- | --- |
 | Session | `session.started`, `session.waiting`, `session.completed`, `session.failed` | Session creation, readiness, and task completion |
-| Input | `message.received` | A user message was accepted |
+| Input | `message.received`, `nudge.delivered` | A user message was accepted as a turn's prompt, or reached a running turn mid-turn. Both name the [sends they carry](#track-which-follow-up-reached-the-agent) |
 | Turn | `turn.queued`, `turn.started`, `turn.completed`, `turn.failed` | Queue position under a [`maxRunningTurns` cap](/docs/reference/agent-config.md#concurrency), then turn status, final result, and token usage |
 | Steps | `step.started`, `step.completed` | Model step boundaries and duration |
 | Reasoning | `reasoning.appended`, `reasoning.completed` | Streamed reasoning blocks |
@@ -8537,6 +9103,7 @@ export default defineTool({
 | --- | --- |
 | `ctx.toolCallId` | The call id, matching the `actions.requested` / `action.result` stream events |
 | `ctx.session` | Read-only session info: id, channel, mode, auth |
+| `ctx.approvedBy` | For a `needsApproval` tool, the auth of whoever approved this call, in the same shape as `ctx.session.auth`. On Slack, `attributes.user_id` is the person who clicked Approve, who can differ from the person who started the thread. Unset when the call needed no approval |
 | `ctx.workspaceDir` | The session's workspace directory |
 | `ctx.stateRoot` | The agent's durable state root, shared across every session |
 | `ctx.host` | Shared host services (see below) |
@@ -8547,9 +9114,9 @@ export default defineTool({
 `ctx.host` carries the shared host services: `host.mcp` (authored MCP
 connections: `names()`, `listTools(name)`, `callTool(name, tool, args)`),
 `host.github` and `host.slack` (shared platform clients), `host.kv` and
-`host.files` (durable storage), `host.otel` (custom
-metrics and session tags; see [OpenTelemetry](/docs/guides/opentelemetry.md)),
-`host.reminders` (per-session wakes, when attached).
+`host.files` (durable storage), and `host.reminders` (per-session wakes,
+when attached). Custom metrics use the
+[OpenTelemetry](/docs/guides/opentelemetry.md) API.
 
 ### Return values