@cursor/bdk 0.2.23 → 0.2.25

package/dist/docs/llms-full.txt

@@ -235,9 +235,9 @@ agent and doesn't train on it.
 Declare the external hosts and secret names the agent needs. Mounted
 extensions add the ones they declare, so list only what your own code
 calls; `bdk info --dir .` shows the combined list and what each mount
-adds. After the
-deployment exists, set each value at the hidden prompt and follow the
-CLI or dashboard instruction to redeploy.
+adds. Deploy the agent, then set each value at the hidden prompt.
+The next task uses the new value. You do not deploy again to apply
+that value.
 
 ```ts
 // bot/agent.ts
@@ -252,9 +252,9 @@ export default defineAgent({
 ```
 
 ```text
+bdk deploy --dir . --slug weather-agent
 bdk secrets set weather-agent WEATHER_API_KEY
 bdk secrets list weather-agent
-bdk deploy --dir . --slug weather-agent
 ```
 
 Commit secret names, never values. `secrets set` accepts names and reads
@@ -268,6 +268,11 @@ loading sees nothing. Read a secret inside the handler, tool, or callback
 that needs it, and give an MCP connection its credential as a `${NAME}`
 template, which resolves when the connection opens. See
 [credentials in headers and env](/docs/reference/connections.md#credentials-in-headers-and-env).
+
+`bdk deploy` runs the top-level code in your files one time to build
+the snapshot. No secrets exist at that time. The snapshot keeps those
+values.
+
 SCM webhook channels go one step further and name their secrets in the
 channel definition, as `{ secretName: "GITHUB_WEBHOOK_SECRET" }`, so the
 platform can verify each delivery's signature before any compute starts.
@@ -1225,6 +1230,7 @@ their own.
 | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `cloud`         | Launch defaults for repositories, environment, and pull request behavior.                                                                                                                                                                           |
 | `cloud.repos`   | The repositories the agent may hand work to, with a default branch or pull request for each. Without it, launches run with no repository and the model can't name one, so secrets in `cloud.envVars` never reach a repository you didn't list. |
+| `cloud.teamMcpServers` | The team MCP servers, by name, that launched agents may use (up to 50 names, matched case-insensitively; every team server with a listed name is kept). Every other team server is left out. Personal servers and `cloud.mcpServers` aren't filtered. Omit it to give agents every team server the launching account can use. |
 | `model`         | The model launched agents run. Omit it to use the account default.                                                                                                                                                                             |
 | `apiKey`        | A Cursor API key to launch with instead of the host's own.                                                                                                                                                                                     |
 
@@ -3387,6 +3393,10 @@ export OTEL_SERVICE_NAME=incident-agent
 bdk serve --dir . --dev
 ```
 
+Metrics use delta temporality by default. For Grafana Cloud, set
+`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` to `cumulative`.
+Grafana Cloud rejects delta metrics.
+
 The default protocol is OTLP/HTTP protobuf. If you already call
 `serve()` from TypeScript, you can configure the same destination in
 code:
@@ -3415,6 +3425,52 @@ application starts the server itself. When that application
 already uses OpenTelemetry, BDK sends its traces, metrics, and
 logs to the collector configured here.
 
+## Export from a hosted agent
+
+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.
+
+```ts
+// bot/agent.ts
+import { defineAgent } 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"],
+  },
+});
+```
+
+```bash
+bdk secrets set my-agent OTEL_EXPORTER_OTLP_ENDPOINT OTEL_EXPORTER_OTLP_HEADERS
+```
+
+`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...`).
+
+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, metric export interval,
+and metrics temporality 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.
+
+When an exporter host is missing from `hosting.egressDomains`, BDK
+logs an error that names the host. Add the host and redeploy.
+
+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.
+
+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`.
+
 ## Follow one conversation
 
 Copy the complete session ID from the playground or session API, then
@@ -3516,7 +3572,8 @@ The first metrics to look for are `cursor.token.usage`,
 ## Control what leaves the process
 
 Traces include structure, tool names, usage metrics, and span
-status. A failed tool's status includes a short failure reason.
+status. A failed tool's span status and its `action.result` log
+include 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.
@@ -3543,13 +3600,354 @@ The same controls are available as
   configuration and custom-metric reference for coding agents
 - [Hooks](/docs/reference/hooks.md): emit domain telemetry from session
   events
-- [Deployment](/docs/deployment.md): set collector endpoints and secrets
-  on hosted or self-hosted agents
+- [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
 
 ---
 
+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: ["api.pagerduty.com"],
+    secretNames: ["PAGERDUTY_TOKEN"],
+  },
+});
+```
+
+## 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}`,
+  };
+},
+```
+
+Add these to the same `pagerdutyChannel()` declaration as the
+investigation handler.
+
+## Ignore your own actions
+
+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.
+
+The channel finds the agent's user in this order, on each delivery:
+
+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`.
+
+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.
+
+Inference depends on the kind of token:
+
+| `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:
+
+```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`:
+
+```ts
+export default pagerdutyChannel({
+  selfUserIds: ["PBOT001"],
+  onIncident: (ctx) => ({ auth: defaultPagerDutyAuth(ctx) }),
+});
+```
+
+`selfUserIds: { secretName: "OTHER_NAME" }` reads one id from another
+secret and never falls back to inference.
+
+## Events
+
+Each hook receives one family of v3 events:
+
+| 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 |
+
+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:
+
+| Return | What happens |
+| --- | --- |
+| `{ 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 |
+
+## Incident affinity
+
+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.
+
+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.
+
+## Connect
+
+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.
+
+| 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` |
+
+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
+```
+
+`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.
+
+### Several subscriptions
+
+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:
+
+```text
+<signing secret of subscription 1>
+<signing secret of subscription 2>
+```
+
+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.
+
+Keep the list in a file, since `bdk secrets list` never shows values,
+and set it from stdin, which keeps the line breaks:
+
+```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.
+
+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
+
+`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
+bdk dev &
+bdk pagerduty replay --events triggered,acknowledged,annotated,resolved \
+  --comment "Rolled back the 09:30 deploy."
+```
+
+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.
+
+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
+
+- [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
+
+---
+
 Source: /docs/guides/slack.md
 
 # Slack agents
@@ -4836,7 +5234,6 @@ import { serve } from "@cursor/bdk";
 
 const handle = await serve("./my-agent", {
   port: 3000,
-  apiKey: process.env.CURSOR_API_KEY,
 });
 console.log(`listening on ${handle.url}`);
 // handle.callTool(...), handle.dispatchSchedule("heartbeat"),
@@ -5142,7 +5539,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 |
 
@@ -5169,6 +5566,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
@@ -6214,6 +6612,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`,
@@ -6904,10 +7329,13 @@ import ci from "@acme/ci-triage";
 
 export default ci({
   org: "acme",
-  token: process.env.BUILDKITE_TOKEN,
+  token: () => process.env.BUILDKITE_TOKEN ?? "",
 });
 ```
 
+Pass `token` as a function so a tool can call it. The function reads
+`BUILDKITE_TOKEN` when the tool calls it.
+
 The extension validates its configuration while the project loads.
 Missing or mistyped settings fail `bdk validate` before a turn
 can call the contributed code.
@@ -6992,14 +7420,15 @@ import { cursorPlugin } from "@cursor/bdk/extensions";
 export default cursorPlugin({
   path: "plugins/notion-workspace",
   variables: {
-    NOTION_TOKEN: process.env.NOTION_TOKEN,
+    NOTION_TOKEN: "${NOTION_TOKEN}",
   },
 });
 ```
 
 `path` is relative to the project root. `variables` fills placeholders
-declared by the plugin's MCP configuration; unresolved placeholders
-fail validation instead of mounting a partial server.
+declared by the plugin's MCP configuration. Pass a `${NAME}` template.
+The connection reads `NAME` when it opens. An unresolved placeholder
+fails validation instead of mounting a partial server.
 
 Plugin rules and hooks are not mounted. Overlay a generated
 `mcp-connections/<server>.ts` file to replace or disable one plugin
@@ -7049,10 +7478,13 @@ export default defineExtension({
   description: "Investigate failing Buildkite jobs.",
   config: z.object({
     org: z.string(),
-    token: z.string(),
+    token: z.function().args().returns(z.string()),
     logTailLines: z.number().int().positive().default(200),
   }),
-  hosting: () => ({ egressDomains: ["api.buildkite.com"] }),
+  hosting: () => ({
+    egressDomains: ["api.buildkite.com"],
+    secretNames: ["BUILDKITE_TOKEN"],
+  }),
 });
 ```
 
@@ -7065,9 +7497,8 @@ prose assets beside it.
 from the environment. It receives the validated settings, and the
 mounting agent's `hosting.egressDomains` and `hosting.secretNames` gain
 whatever it returns, so a hosted deploy reaches Buildkite without the
-consumer listing `api.buildkite.com`. Leave out secrets that arrive
-through settings, such as `token` here; the consumer decides where that
-value comes from.
+consumer listing `api.buildkite.com`. List `BUILDKITE_TOKEN` in
+`secretNames`. Call `extension.config.token()` inside a tool.
 
 The [Project layout](/docs/reference/project-layout.md) owns each contribution's
 authoring contract. Keep extension instructions and tool descriptions
@@ -7530,10 +7961,14 @@ on every turn. A root agent requires them; a subagent may inline
 import { defineInstructions } from "@cursor/bdk";
 
 export default defineInstructions({
-  markdown: `You are the on-call assistant for ${process.env.TEAM_NAME}.`,
+  markdown: "You are the on-call assistant for the payments team.",
 });
 ```
 
+The `markdown` string is fixed when this file loads. Read a secret in
+a handler, a tool, or a callback. See
+[Add egress and secrets](/docs/deployment.md#add-egress-and-secrets).
+
 ## Delivery
 
 Instructions land in the session workspace as `AGENTS.md`, and the
@@ -8476,6 +8911,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) |
@@ -8723,13 +9159,13 @@ Source: /docs/templates/agentic-owners.md
 This agent reviews every pull request in your repository. It risk-tiers
 the diff, requests the owning team or user as reviewers, and approves
 what your policy allows. Ownership rules live in
-`.agentic-owners/policy.yml` files committed at any depth of the repo;
-the closest policy to a changed file wins, and policies are always read
-from the PR's base ref so a PR cannot exempt itself.
+`.agentic-owners/policy.yml` files committed at any depth of the repo.
+The closest policy to a changed file wins, and policies are always read
+from the PR's base ref, so a PR cannot exempt itself.
 
 ## Scaffold
 
-```text
+```bash
 bdk init ./owners-agent --template agentic-owners
 ```
 
@@ -8738,21 +9174,23 @@ on PATH.
 
 ## Log in and run
 
-Set your repositories in `bot/lib/config.ts` (`repos: ["you/your-repo"]`),
+Set your repositories in `bot/lib/config.ts` (`repos: ["acme/api"]`),
 then:
 
-```text
+```bash
 cd owners-agent
 bdk login
 bdk dev
 ```
 
 PR events stream through your Cursor account. No webhook or GitHub App
-setup. Open a PR, or replay a real one deterministically (this also works
+setup. The agent reviews a PR when it is opened, reopened, pushed to,
+marked ready for review, or retargeted to another base. Draft PRs wait
+until they are ready. Open a PR, or replay a real one (this also works
 with `repos` empty):
 
-```text
-bdk github replay https://github.com/you/your-repo/pull/123 --dir .
+```bash
+bdk github replay https://github.com/acme/api/pull/123 --dir .
 ```
 
 Deploy with `bdk deploy`.
@@ -8764,37 +9202,67 @@ low risk approve, medium and above hold with a comment. Route reviews by
 committing policies:
 
 ```yaml
-# .agentic-owners/policy.yml. Anywhere in the repo; closest wins.
-# paths are repo-root-relative globs, wherever the policy file lives.
+# .agentic-owners/policy.yml at any depth; the closest policy wins.
 version: 1
 policies:
   - paths: ["docs/**"]
     always_approve: true
   - paths: ["src/api/**"]
-    team: acme/platform # or user: alice
+    team: platform # bare slug in the repo's org; or acme/platform, or user: alice
     prompt: api-review.md # optional extra rubric, same directory
   - paths: ["src/billing/**"]
-    user: alice
-    human_review_required: true # the agent never approves; a person must
+    users: [alice, bob]
+    mode: hard # the agent never approves; a person must
 ```
 
-`self_review: true` lets a listed owner's own PRs clear their rule.
-`global_exclusions` in the root policy opts paths out entirely.
+`paths` are globs relative to the directory that holds the
+`.agentic-owners/` folder, so a root policy sees repo-relative paths and
+`src/.agentic-owners/policy.yml` matches `api/**` against
+`src/api/**`. Leading `../` segments reach a sibling tree. A path cannot
+escape the repo.
+
+| Key | Meaning |
+| --- | --- |
+| `paths` | Globs relative to the policy's directory. Required. |
+| `team` / `teams` | Owner teams. A bare slug resolves in the repo's org. An `org/team` handle names a team directly. |
+| `user` / `users` | Owner GitHub logins, without `@`. |
+| `prompt` | Markdown filename in the same directory, added to the rubric for matching PRs. |
+| `mode` | `advisory` (default): low risk approves. `hard`: a person must approve. `notify`: the rule never blocks and its owners are not requested. |
+| `human_review_required` | `true` is the older spelling of `mode: hard`. |
+| `self_review` | A listed `user:` owner's own PRs clear this rule. |
+| `always_approve` | Satisfied at every risk tier. Cannot combine with owners, `prompt`, `mode`, `self_review`, or `human_review_required`. |
+
+A rule without owners must set `always_approve: true`.
+`global_exclusions` in the root policy opts paths out entirely. The
+agent rejects `delegated_automations`: nothing in this template consumes
+automation approvals.
 
 ## What one review does
 
 One model turn per PR head assesses the host-fetched diff against the
-base rubric plus any matched rule prompts, then records a verdict with
+base rubric plus any matched rule prompts, then records a risk tier of
+`very_low`, `low`, `medium`, `medium_high`, or `high` with
 `record_review`. The host recomputes the policy from trusted state and
 applies the deterministic decision:
 
-- **Approve** when the tier is low and no matched rule demands a human,
-  bound to the head SHA.
+- **Approve** when every matched rule is `always_approve` or `notify`,
+  or when the tier is very low or low and every matched `hard` rule is
+  cleared by an owner-author with `self_review`. At medium and above,
+  the agent approves only when the author's `self_review` covers every
+  rule that can require review.
 - **Request reviewers** otherwise: the policy owners (max 2, never the
   author), plus one status comment the agent keeps updated in place.
 
+An approval binds to the head SHA, and a later hold dismisses the
+agent's earlier approvals. The agent also holds when the PR edits
+`.agentic-owners/` or `CODEOWNERS`, when the diff is empty or truncated,
+or when GitHub capped the changed-file list. `self_review` never clears
+a governance edit.
+
 The model never writes to GitHub. A broken policy file fails closed with
-a comment listing the validation issues.
+a comment listing the validation issues. Team membership is not
+resolved, because repo-scoped credentials cannot read org teams, so
+`self_review` applies to `user:` owners only.
 
 ## Rubric
 
@@ -8806,12 +9274,12 @@ next to the policy that names them. The next review reads both.
 
 Use the three smoke reviews as a local exercise:
 
-```text
+```bash
 bdk eval
 ```
 
-Three smoke reviews (docs-only, auth deletion, prompt injection). Eval
-sessions skip GitHub writes.
+The cases are a docs-only change, an auth deletion, and a prompt
+injection. Eval sessions skip GitHub writes.
 
 ---