@cursor/bdk 0.2.23 → 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.                                                                                                                                                                                     |
 
@@ -3415,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
@@ -3543,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
 
@@ -4836,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"),
@@ -6904,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.
@@ -6992,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
@@ -7049,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"],
+  }),
 });
 ```
 
@@ -7065,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
@@ -7530,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
@@ -8723,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
 ```
 
@@ -8738,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`.
@@ -8764,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
 
@@ -8806,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.
 
 ---