@cursor/bdk 0.2.22 → 0.2.24

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.                                                                                                                                                                                     |
 
@@ -3215,6 +3221,15 @@ Migrate when at least one of these signals is present:
 Stop when none of these is true. An existing `agent/` project root can remain
 in place; BDK still loads it even though current examples use `bot/`.
 
+`bdk migrate` prints `Nothing to migrate.` and exits 0 only when `--dir` shows
+no migration work. The check looks for an `@cursor/july` dependency,
+`architecture: "v1"`, `bot/storage.ts` or `agent/storage.ts`,
+`runtime: "grokbot"`, a literal SCM credential, a `/v1` continuation selector,
+an anonymous reminder, and a `*_MCP_URL` peer connection. When any of those is
+present, or a project file cannot be read, the command starts the agent. It
+does not read the hosted deployment. Run `bdk deployment <slug>` when you still
+need to see whether that copy is on v1.
+
 ## Start the migration
 
 Commit and push the source you want to migrate. `bdk migrate` reads that
@@ -3274,6 +3289,14 @@ Before merging, confirm the pull request:
   removed. The [GitHub guide](/docs/guides/github.md#other-hosts) explains the named
   form.
 
+- Rewrites each peer call that took its URL from a secret or environment
+  variable, such as `BUILDER_MCP_URL`, to
+  `defineConnection({ agent: "<slug>" })` under `bot/mcp-connections/`
+  (or `agent/mcp-connections/` when the project root is `agent/`).
+  Confirm the slug before you merge. The pull request lists each secret the
+  rewrite left unused, and it leaves a TODO where it could not determine
+  the slug.
+
 - Calls out unsupported behavior and any follow-up needed for reminders,
   schedules, Slack, or MCP connections.
 
@@ -3304,10 +3327,33 @@ bdk validate --dir .
 bdk deploy --dir . --slug <existing-or-new-slug>
 ```
 
-After the deployment starts, follow the migration skill's cutover checklist
-for Slack, webhook callers, and Cursor-account MCP connections, then verify a
-hosted turn. The [deployment guide](/docs/deployment.md) covers the managed
-hosting workflow.
+When the folder contains more than one agent, deploy each agent folder
+alone. Run `bdk deploy --dir <agent folder>` one time for each agent. One
+`bdk deploy` on the parent folder prints those commands and does not deploy.
+Do not use `bdk deploy --all`. Repeat `bdk slack create --prod` for each
+agent folder. The Slack app slug is the folder name.
+
+When the pull request calls another agent with
+`defineConnection({ agent: "<slug>" })`, deploy the caller and that peer
+on `@cursor/bdk` 0.2.18 or newer. Both deployments must belong to the
+same team, and the caller reaches the peer once the peer deployment is
+running. The connection file is already in the merged source, so unset
+each URL secret the pull request lists after both deploys:
+
+```bash
+bdk secrets unset <slug> NAME
+```
+
+`bdk migrate` prints the steps that follow the first deploy: one deploy per
+agent folder, `bdk slack create --prod --dir <agent-folder>` for each Slack
+agent, `bdk secrets unset` for peer URL secrets the pull request lists, and
+`bdk secrets list` / `bdk secrets set` when the slug is new. Slack setup
+redeploys the deployment by itself. `bdk secrets set` takes effect on the
+next request. Neither step needs another deploy.
+
+After the deployment starts, follow that checklist for Slack, webhook callers,
+peer connections, and secrets, then verify a hosted turn. The
+[deployment guide](/docs/deployment.md) covers the managed hosting workflow.
 
 ## Related
 
@@ -3315,6 +3361,8 @@ hosting workflow.
   exit status
 - [`bdk-migrate-v2` skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/migrate-v2/SKILL.md): the coding
   procedure and complete capability matrix
+- [Peer agents](/docs/guides/agent-to-agent.md): how a deployed caller reaches another
+  agent by slug
 - [Deployment](/docs/deployment.md): deploy and verify the reviewed project
 
 ---
@@ -3373,6 +3421,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, 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.
+
+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
@@ -3501,8 +3595,8 @@ 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
 
@@ -4794,7 +4888,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"),
@@ -5681,7 +5774,18 @@ bdk migrate [--dir <path>] [--repo <https-url>] [--ref <git-ref>]
 early alpha. It reads a pushed Git ref, starts a Cursor cloud agent with the
 bundled `bdk-migrate-v2` skill, and opens a pull request with the source
 changes. The command waits for the pull request by default and never deploys
-the project or changes deployment secrets.
+the project or changes deployment secrets. When it starts an agent, it prints
+a checklist for the steps after the first deploy: deploy each agent folder,
+create the prod Slack app, unset peer URL secrets, and set secrets a new slug
+still needs.
+
+The command prints `Nothing to migrate.` and exits 0 only when `--dir` shows
+no migration work. That check looks for an `@cursor/july` dependency,
+`architecture: "v1"`, `bot/storage.ts` or `agent/storage.ts`,
+`runtime: "grokbot"`, a literal SCM credential, a `/v1` continuation selector,
+an anonymous reminder, and a `*_MCP_URL` peer connection. When any of those is
+present, or a project file cannot be read, the command starts the agent. It
+does not read the hosted deployment.
 
 | Option | Contract |
 | --- | --- |
@@ -5690,7 +5794,7 @@ the project or changes deployment secrets.
 | `--ref <git-ref>` | Select the pushed ref for the cloud agent. The CLI infers the current branch when possible. |
 | `--path <agent-path>` | Select the project path relative to the repository root. The CLI infers it from `--dir` when possible. |
 | `--no-wait` | Print the cloud agent URL and return after the agent starts. |
-| `--json` | Print a report with `ok`, `status`, `agentId`, and the cloud agent `url`. A completed migration adds `prUrl`; a blocked or failed migration adds its explanation. |
+| `--json` | Print a report with `ok`, `status`, `agentId`, and the cloud agent `url`. A completed migration adds `prUrl` and `checklist`. A run with nothing to migrate uses `status: "current"` and `message` (no agent started) or `summary` (the agent reported it). A blocked or failed migration adds its explanation. |
 | `--api-key <key>` | Override the Cursor credential. |
 
 Credential resolution follows the normal order: `--api-key`,
@@ -5807,8 +5911,8 @@ service-account API key with agent access can deploy.
 
 | Option | Contract |
 | --- | --- |
-| `--slug <slug>` | Select one project and set its deployment slug. |
-| `--all` | Deploy every child project under a multi-agent `--dir`. Mutually exclusive with `--slug`. |
+| `--slug <slug>` | Select one project and set its deployment slug. Under a folder of several agents, this deploys that one agent. |
+| `--all` | Deploy every child under a folder of several agents. For a folder of v2 agents, print one deploy command for each agent. |
 | `--team <id>` | Select the Cursor team. |
 | `--repo <https-url>` | Set the source repository. The CLI infers it from the current checkout when possible. HTTPS is required. |
 | `--ref <git-ref>` | Set the source Git ref. The CLI infers the current branch when possible. |
@@ -6200,7 +6304,7 @@ Credential resolution follows this order: `--api-key`, `CURSOR_API_KEY`,
 | `chat`, `session` | Exit `2` for documented option conflicts or missing required input. |
 | `validate` | Exit `1` when any project diagnostic has error severity. |
 | `convert-automation` | Exit `1` for invalid input, authentication, export, or file-write failure. Warnings and dependency-install failure don't change a successful conversion exit. |
-| `migrate` | Exit `0` after starting with `--no-wait` or after the agent opens a pull request. Exit `1` for invalid input, authentication or agent failure, or a completed run without a pull request. |
+| `migrate` | Exit `0` when nothing needs a migration, after starting with `--no-wait`, or after the agent opens a pull request. Exit `1` for invalid input, authentication or agent failure, or a completed run without a pull request. |
 | Other commands | Exit nonzero when validation, authentication, a request, or the requested operation fails. |
 
 ## Related
@@ -6851,10 +6955,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.
@@ -6939,14 +7046,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
@@ -6996,10 +7104,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"],
+  }),
 });
 ```
 
@@ -7012,9 +7123,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
@@ -7477,10 +7587,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
@@ -8670,13 +8784,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
 ```
 
@@ -8685,21 +8799,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`.
@@ -8711,37 +8827,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
 
@@ -8753,12 +8899,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.
 
 ---