@cursor/bdk 0.2.22 → 0.2.24

package/docs/reference/extensions.md

@@ -27,10 +27,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.
@@ -115,14 +118,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
@@ -172,10 +176,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"],
+  }),
 });
 ```
 
@@ -188,9 +195,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](./project-layout.md) owns each contribution's
 authoring contract. Keep extension instructions and tool descriptions

package/docs/reference/instructions.md

@@ -22,10 +22,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](../deployment.md#add-egress-and-secrets).
+
 ## Delivery
 
 Instructions land in the session workspace as `AGENTS.md`, and the

package/docs/templates/agentic-owners.md

@@ -8,13 +8,13 @@ description: "Scaffold the agent, commit .agentic-owners policies, and let it ri
 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
 ```
 
@@ -23,21 +23,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`.
@@ -49,37 +51,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
 
@@ -91,9 +123,9 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/bdk",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "description": "Build, test, and deploy BDK bots and agents as code on Cursor's agent harness.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -329,17 +329,14 @@
     "ms": "^2.1.3",
     "proper-lockfile": "^4.1.2",
     "slackify-markdown": "^5.0.0",
-    "tsx": "^4.0.0",
-    "zod": "^3.25.0",
-    "zod-to-json-schema": "^3.24.5"
+    "tsx": "4.23.15",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {
     "@braintree/sanitize-url": "7.1.2",
-    "@cursor/sdk-darwin-arm64": "1.0.37",
-    "@cursor/sdk-darwin-x64": "1.0.37",
-    "@cursor/sdk-linux-arm64": "1.0.37",
-    "@cursor/sdk-linux-x64": "1.0.37",
-    "@cursor/sdk-win32-x64": "1.0.37",
     "@stylexswc/rs-compiler": "^0.18.0",
     "@tanstack/react-virtual": "3.13.23",
     "@types/js-yaml": "4.0.9",
@@ -347,33 +344,34 @@
     "@types/node": "22.14.1",
     "@types/pg": "^8.16.0",
     "@types/proper-lockfile": "^4.1.4",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "@vitejs/plugin-react": "^5.1.2",
+    "@vitejs/plugin-react": "6.1.2",
     "cytoscape": "3.33.3",
     "cytoscape-cose-bilkent": "4.1.0",
     "dayjs": "1.11.20",
     "mermaid": "^11.14.0",
     "pg": "^8.18.0",
     "pretty-ms": "^9.2.0",
-    "react": "^19.2.1",
-    "react-dom": "^19.2.1",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
     "react-markdown": "^10.1.0",
     "rehype-highlight": "^7.0.2",
     "remark-gfm": "^4.0.1",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "vite": "^7.3.0",
+    "vite": "8.3.1",
     "vitepress": "1.6.4",
     "vitepress-plugin-mermaid": "^2.0.17",
-    "vitest": "^4.0.18",
+    "vitest": "5.0.3",
     "yaml": "^2.4.2",
+    "zod": "^3.25.0",
     "zustand": "^5.0.9",
     "@anysphere/agent-exec": "1.0.0",
     "@anysphere/context": "1.0.0",
-    "@anysphere/ui": "1.0.0",
     "@anysphere/agent-store-sync": "1.0.0",
-    "@anysphere/proto": "1.0.0"
+    "@anysphere/proto": "1.0.0",
+    "@anysphere/ui": "1.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node scripts/bundle-publish-shims.mjs && node scripts/copy-extension-assets.mjs && pnpm run build:playground && pnpm run docs:build",
@@ -396,4 +394,4 @@
     "smoke-publish": "node scripts/smoke-publish-artifact.mjs",
     "publish-check": "pnpm run build && pnpm run verify-publish && pnpm run smoke-publish"
   }
-}
+}

package/skills/migrate-v2/SKILL.md

@@ -23,7 +23,21 @@ Migrate when any of these is true:
 - `bdk deployment <slug>` for the hosted copy does not print
   `architecture: v2`.
 
-Stop when none is true.
+Stop when none is true. Your final message must start with
+`Nothing to migrate.` and must name the checks you ran. Open no pull
+request.
+
+`bdk migrate` checks `--dir` before it starts an agent. It starts an
+agent when it finds any of these: an `@cursor/july` dependency or
+import, `architecture: "v1"`, `bot/storage.ts` or `agent/storage.ts`,
+`runtime: "grokbot"`, a literal or `() => process.env` SCM credential,
+`continuation: ".../v1"`, an anonymous reminder `run` or function
+`until`, or a `defineConnection` whose URL comes from a `*_MCP_URL`
+secret. When none of those is present it prints `Nothing to migrate.`
+and exits. When it cannot read a file, it starts the agent. It does
+not run `bdk deployment`. A hosted copy can still be on v1 after the
+source has moved. Check with `bdk deployment <slug>`, and deploy when
+that output does not show `architecture: v2`.
 
 ## Know what changes
 
@@ -66,12 +80,14 @@ ends. That model changes code in three places:
 | Slack tool-approval buttons on Cursor hosting | Not supported yet |
 | `bdk mcp oauth --store` for host MCP OAuth | Not supported. Connect Cursor-account MCP servers from **Deployed Agents** in the dashboard. |
 | Session, tool, and MCP APIs on the deployment URL | Not reachable |
+| Another BDK agent reached through a deployment URL secret | Not supported. Declare `defineConnection({ agent: "<slug>" })`. Both agents must be team-owned and deployed on `@cursor/bdk` 0.2.18 or newer. |
 | `--prod` with `chat`, `resume`, `call`, `skill`, `sessions`, `cost`, or `mcp` | Not supported. Use `run --prod`, `logs --prod`, `session --prod`, and `playground --prod`. |
 | v1 sessions, KV, and files | Not carried over. v2 starts empty, and deleting v1 deletes them. |
 
 The steps below rewrite `defineStorage`, inline reminders, SCM channel
-credentials, and secret reads. Stop and ask before migrating an agent
-that depends on Slack tool-approval buttons, `mcp oauth --store`, or an
+credentials, secret reads, and peer calls that use a URL secret. Stop and
+ask before migrating an agent that depends on Slack tool-approval buttons,
+`mcp oauth --store`, or an
 HTTP route whose caller reads the response body. Name the row and the
 file that uses it.
 
@@ -177,9 +193,74 @@ still loads.
 
 7. **Move secret reads.** Replace module-scope `process.env.NAME` reads
    with reads inside the function that uses them. Give MCP connections a
-   `${NAME}` header or env template instead.
+   `${NAME}` header or env template instead. A URL that points at another
+   BDK agent's deployment is not one of those secrets. Step 8 replaces
+   that connection, including a URL you templated here.
+
+8. **Rewrite peer calls that use a URL secret.** Do this in the migration
+   pull request. The deployment URL does not serve MCP, so a connection
+   left on that URL fails after deploy.
+
+   Treat the call as a peer when its URL comes from a `*_MCP_URL` secret
+   or a similar name, a `${NAME}` template, `process.env.NAME`, or a
+   string built from a deployment URL or slug, and the target is another
+   BDK agent. Leave a third-party MCP server as a URL connection and
+   apply step 7 to its secrets.
+
+   Use a slug only when the repo states it: the URL path, a `--slug`
+   value, a sibling directory that deploy would use as the slug, or a
+   comment that names the deployment. A secret name is a hint. Use
+   `BUILDER_MCP_URL` as `builder` only when something else in the repo
+   confirms that slug. When nothing confirms it, keep the URL connection
+   and add a TODO that names the secret and asks for the slug. Name that
+   TODO in the pull request body.
 
-8. **Stop answering from HTTP routes.** A custom route that returned
+   ```ts
+   // before (v1), agent/mcp-connections/builder.ts
+   import { defineConnection } from "@cursor/bdk/connections";
+
+   export default defineConnection({
+     url: process.env.BUILDER_MCP_URL,
+     headers: { authorization: `Bearer ${process.env.BUILDER_TOKEN}` },
+   });
+
+   // after (v2)
+   import { defineConnection } from "@cursor/bdk/connections";
+
+   export default defineConnection({
+     agent: "builder",
+     description: "Ask the builder agent to handle this work.",
+   });
+   ```
+
+   `agent` is the peer's lowercase deployment slug. Keep an existing
+   connection file in place. When the project has no connection file,
+   add `bot/mcp-connections/<name>.ts`, or
+   `agent/mcp-connections/<name>.ts` when the project root is `agent/`.
+   Use `host-connections/` only when host code calls the peer and the
+   model must not see it. The filename is the connection name.
+
+   Hosting authenticates the peer call. Remove the URL, its headers, and
+   any token this call was the only reader of. Point host code that
+   called the deployment URL at
+   `ctx.host.mcp.callTool("<name>", "ask", { message })`. The peer
+   project needs no matching file. Do not edit a peer that sits outside
+   this folder.
+
+   Remove the unused URL secret from code and from `hosting.secretNames`
+   on `defineAgent`, and from an extension `hosting` block that declares
+   it. Leave every secret something else still reads.
+
+   Do not change deployment secrets, and do not run `bdk secrets unset`.
+   In the pull request body, list each secret this step stopped using,
+   with the command `bdk secrets unset <slug> NAME`, so the user can
+   unset it after both agents are deployed.
+
+   Both agents must be team-owned and deployed with `@cursor/bdk` 0.2.18
+   or newer before the connection resolves. This pull request does not
+   deploy them.
+
+9. **Stop answering from HTTP routes.** A custom route that returned
    computed data must deliver it another way, such as a callback URL or a
    tool the turn calls. Return `new Response(null, { status: 202 })` so
    local runs match the hosted response.
@@ -206,14 +287,29 @@ Run the project's own typecheck and tests.
 ## Open the pull request
 
 Describe each removed or changed behavior, each unsupported row the
-agent touched, and the deploy steps. Do not deploy from the pull request
-branch.
+agent touched, and the deploy steps. For each peer URL you rewrote, name
+the slug and the connection file. List every secret name the rewrite
+left unused, and the `bdk secrets unset <slug> NAME` command for it.
+Name each TODO whose slug you could not determine. Do not deploy from
+the pull request branch, and do not change deployment secrets.
+
+Copy this post-merge checklist into the pull request body. One
+`bdk deploy --dir <agent-folder>` per agent. Do not use `bdk deploy --all`.
+Then `bdk slack create --prod --dir <agent-folder> [--team <team-id>]`
+for each agent that uses Slack. Then `bdk secrets unset <slug> NAME` for
+each unused peer URL secret, and `bdk secrets list <slug>` plus
+`bdk secrets set <slug> NAME` when the slug is new. Do not tell the user
+to deploy again after Slack setup or after `bdk secrets set`. The server
+redeploys after Slack setup, and a secret is injected on the next
+request.
 
 ## Deploy after merge
 
 Deploy from a pushed ref. `bdk deploy` reads Git and never uploads the
 working tree.
 
+When the folder contains one agent:
+
 ```bash
 bdk login
 bdk validate --dir .
@@ -222,6 +318,31 @@ bdk deploy --dir . --slug <existing-slug> \
   --allow-domain <domain>
 ```
 
+When the folder contains more than one agent, deploy each agent alone.
+Run the command one time for each agent folder. A `bdk deploy` on the
+parent folder prints those commands and does not deploy. Do not run
+`bdk deploy --all`. Repeat `bdk slack create --prod` for each agent
+folder too.
+The app slug is the folder name, so that name must match the deployed
+slug.
+
+```bash
+bdk deploy --dir <agent-folder> --slug <that-agent-slug> \
+  --cursor-events-repo <owner/repo> \
+  --allow-domain <domain>
+```
+
+When this migration declares `defineConnection({ agent: "<slug>" })`,
+deploy the caller and the peer. Both deployments must be team-owned and
+must run `@cursor/bdk` 0.2.18 or newer. The connection file is already
+in the merged source. The caller reaches the peer after the peer
+deployment is running. The peer needs no matching file. After both
+deploys are running, unset each URL secret the pull request lists:
+
+```bash
+bdk secrets unset <slug> NAME
+```
+
 Pass every `--cursor-events-repo` and `--allow-domain` value the v1
 deployment used. Domains already in `hosting.egressDomains` need no
 flag. Print only those two fields, because the full output holds
@@ -252,10 +373,18 @@ After the deploy is running:
 
 - Store the alias token the deploy prints. Point every webhook sender
   and HTTP caller at the new alias URL.
-- For Slack, run `bdk slack create --prod --dir .`, then deploy again so
-  the deployment binds the workspace. The new app is a different bot, so
-  invite it to the channels the old one joined. The copied v1 Slack
-  secrets go unused.
+- For Slack, log in as a person. A team service-account key cannot
+  create the app. Run `bdk slack create --prod --dir <agent-folder>`
+  once per agent (`--team <team-id>` selects the Cursor team that owns
+  the deployment). The server redeploys by itself. Do not deploy again
+  for Slack. The new app is a different bot. Uninstall the old Slack app
+  and invite the new bot to the channels the old one joined. The copied
+  v1 Slack secrets go unused.
+- For secrets, a same-slug deploy copies the v1 secrets. A new slug
+  needs `bdk secrets set <slug> NAME`. Check with
+  `bdk secrets list <slug> [--team <team-id>]`. `deploy` warns when a
+  declared secret is unset. A secret is injected on the next request.
+  Do not deploy again after `bdk secrets set`.
 - Reconnect Cursor-account MCP servers from **Deployed Agents** in the
   dashboard.
 - Start a turn with `bdk run --prod --slug <slug> --message "..."`. It

package/skills/otel/SKILL.md

@@ -22,10 +22,23 @@ Public surface (use one of these):
 2. `serve(dir, { otel: { … } })`. `otel: false` disables env and
    authored config.
 
-`defineOtel` / `bot/otel.ts` is factory-only
-(`@cursor/bdk/internal/otel`). Do not import that path from a
-customer agent. Hosted secrets can arrive after startup; env and
-`serve({ otel })` are the supported public late-bind.
+`bot/otel.ts` is factory-only. Import `defineOtel` from
+`@cursor/bdk/internal/otel` only in a Cursor factory agent.
+A customer agent uses the environment variables above.
+
+Hosted agents:
+
+- Set `OTEL_EXPORTER_OTLP_ENDPOINT` and
+  `OTEL_EXPORTER_OTLP_HEADERS` with `bdk secrets set`. Add the
+  collector host to `hosting.egressDomains`.
+- Header values are URL-encoded (`Authorization=Basic%20...`).
+- A new header from `bdk secrets set` applies on the next export.
+  You do not redeploy for a token change.
+- BDK logs an error when an exporter host is not in
+  `hosting.egressDomains`.
+- Spans and metrics from before the first request are not exported.
+- If the OpenTelemetry config fails, BDK logs the error and the
+  request still completes.
 
 | Signal | Default |
 | --- | --- |