@cursor/bdk 0.2.23 → 0.2.25

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.23",
+  "version": "0.2.25",
   "description": "Build, test, and deploy BDK bots and agents as code on Cursor's agent harness.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -141,6 +141,13 @@
       "import": "./dist/channels/bitbucket/index.js",
       "default": "./dist/channels/bitbucket/index.js"
     },
+    "./channels/pagerduty": {
+      "anysphere-source": "./src/channels/pagerduty/index.ts",
+      "bun": "./dist/channels/pagerduty/index.js",
+      "types": "./dist/channels/pagerduty/index.d.ts",
+      "import": "./dist/channels/pagerduty/index.js",
+      "default": "./dist/channels/pagerduty/index.js"
+    },
     "./channels/deployments": {
       "anysphere-source": "./src/channels/deployments/index.ts",
       "types": "./dist/channels/deployments/index.d.ts",
@@ -329,17 +336,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 +351,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": "4.6.5",
     "zustand": "^5.0.9",
     "@anysphere/agent-exec": "1.0.0",
+    "@anysphere/agent-store-sync": "1.0.0",
     "@anysphere/proto": "1.0.0",
     "@anysphere/context": "1.0.0",
-    "@anysphere/ui": "1.0.0",
-    "@anysphere/agent-store-sync": "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 +401,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

@@ -393,5 +393,5 @@ After the deploy is running:
   `bdk session <ses_...> --prod --slug <slug>` until the latest run
   finishes.
 
-The [deploy skill](../deploy/SKILL.md) covers deploys with an attached
+The deploy skill (`skills/deploy/SKILL.md`) covers deploys with an attached
 service account.

package/skills/otel/SKILL.md

@@ -22,10 +22,26 @@ 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.
+Metrics use delta temporality by default. For Grafana Cloud, set
+`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative`.
+
+`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 |
 | --- | --- |
@@ -34,9 +50,10 @@ customer agent. Hosted secrets can arrive after startup; env and
 | Logs | off (`logs: true` or `OTEL_LOGS_EXPORTER=otlp`) |
 
 Prompt text and tool payloads stay off the wire unless you set
-`OTEL_LOG_USER_PROMPTS` / `OTEL_LOG_TOOL_CONTENT`. A failed tool
-span status includes a short failure reason. BDK keeps its own
-exporters when the process already has a provider.
+`OTEL_LOG_USER_PROMPTS` / `OTEL_LOG_TOOL_CONTENT`. A failed tool's
+span status and its `action.result` log include a short failure
+reason. BDK keeps its own exporters when the process already has a
+provider.
 
 ## Custom metrics
 

package/templates/agentic-owners/README.md

@@ -51,7 +51,12 @@ policies:
 `self_review: true` lets a listed `user:` owner's own PRs auto-approve
 (team membership is not resolved with repo-scoped credentials, so team
 ownership stays fail-closed for authors). `global_exclusions` (root
-policy only) opts paths out entirely.
+policy only) opts paths out entirely. `global_overrides` (root policy
+only, `self_review: true` required) let their owners self-review a file
+whose advisory winner they do not own. They add no owners and leave a file
+with no owner unowned. They leave exclusions, always-approve, hard, and
+notify winners unchanged, and they skip a `skip_teams` team or a
+`skip_paths` path.
 
 ## What the agent does
 

package/templates/agentic-owners/bot/lib/owners/decision.ts

@@ -140,16 +140,42 @@ export function authorOwnsRule(
   return rule.users.some((user) => normalizeHandle(user) === handle);
 }
 
+/**
+ * Whether the author may clear `rule` by self-review. A merged override
+ * records who may self-review in `selfReviewTeams` / `selfReviewUsers`:
+ * the winner's owners when that rule sets `self_review`, and the override's
+ * owners when the override sets it.
+ */
+export function authorMaySelfReview(
+  rule: AgenticOwnersPathRule,
+  author: ApprovalAuthor | undefined,
+): boolean {
+  if (!rule.selfReview) {
+    return false;
+  }
+  if (rule.selfReviewTeams === undefined && rule.selfReviewUsers === undefined) {
+    return authorOwnsRule(rule, author);
+  }
+  return authorOwnsRule(
+    {
+      ...rule,
+      teams: rule.selfReviewTeams ?? [],
+      users: rule.selfReviewUsers ?? [],
+    },
+    author,
+  );
+}
+
 /**
  * The first matched rule (closest-match order is preserved) for which the author
- * is an owner AND `self_review` is enabled — i.e. the rule that authorizes the
- * author to approve their own change. Undefined when none applies.
+ * may self-review — the rule that authorizes the author to approve their own
+ * change. Undefined when none applies.
  */
 function selfReviewRuleForAuthor(
   matchedRules: readonly AgenticOwnersPathRule[],
   author: ApprovalAuthor | undefined,
 ): AgenticOwnersPathRule | undefined {
-  return matchedRules.find((rule) => rule.selfReview && authorOwnsRule(rule, author));
+  return matchedRules.find((rule) => authorMaySelfReview(rule, author));
 }
 
 /**
@@ -180,7 +206,7 @@ export function authorSelfReviewCoversMatchedRules(
   );
   return (
     reviewCapableRules.length > 0 &&
-    reviewCapableRules.every((rule) => rule.selfReview && authorOwnsRule(rule, author))
+    reviewCapableRules.every((rule) => authorMaySelfReview(rule, author))
   );
 }
 
@@ -384,7 +410,7 @@ function baseApprovalVerdict(input: {
   // owner self_review on that same rule. Low-risk auto-approve never clears a
   // hard gate without self_review.
   const blockingHardGate = reviewRequiredRules.find(
-    (rule) => ruleIsHardGate(rule) && !(rule.selfReview && authorOwnsRule(rule, author)),
+    (rule) => ruleIsHardGate(rule) && !authorMaySelfReview(rule, author),
   );
   if (blockingHardGate !== undefined) {
     return requestVerdict("a matched policy requires human review");

package/templates/agentic-owners/bot/lib/owners/globalOverride.ts

@@ -0,0 +1,60 @@
+// Vendored from the Agentic Owners policy core; see README.md in this
+// directory. Precedence must stay identical to the source's.
+
+import type { AgenticOwnersPathRule } from "./types.js";
+
+/**
+ * Winners a root `global_overrides` entry must not change: owner-clearing
+ * carve-outs, hard gates, and notify rules.
+ */
+export function blocksGlobalOverride(rule: AgenticOwnersPathRule): boolean {
+  return (
+    rule.globalExclusion === true ||
+    rule.alwaysApprove ||
+    rule.mode === "hard" ||
+    rule.humanReviewRequired ||
+    rule.mode === "notify"
+  );
+}
+
+function unionOwners(lists: readonly (readonly string[])[]): string[] {
+  return [...new Set(lists.flat())];
+}
+
+function selfReviewOwners(rule: AgenticOwnersPathRule): {
+  readonly selfReviewTeams: readonly string[];
+  readonly selfReviewUsers: readonly string[];
+} {
+  return {
+    selfReviewTeams: rule.selfReviewTeams ?? rule.teams,
+    selfReviewUsers: rule.selfReviewUsers ?? rule.users,
+  };
+}
+
+/**
+ * Let override owners clear a file the winner owns by self-review. The
+ * winner's owners, reviewers, and lane are unchanged, so an author outside the
+ * override needs exactly the review they would without it. The winner's
+ * owners self-review only when the winner sets `self_review`. An override
+ * whose `self_review` a policy edit withheld grants nothing.
+ */
+export function mergeGlobalOverride(
+  winner: AgenticOwnersPathRule,
+  overrides: readonly AgenticOwnersPathRule[],
+): AgenticOwnersPathRule {
+  const granting = overrides.filter((rule) => rule.selfReview);
+  if (granting.length === 0) {
+    return winner;
+  }
+  const selfReviewers = winner.selfReview ? [winner, ...granting] : granting;
+  return {
+    ...winner,
+    selfReview: true,
+    selfReviewTeams: unionOwners(
+      selfReviewers.map((rule) => selfReviewOwners(rule).selfReviewTeams),
+    ),
+    selfReviewUsers: unionOwners(
+      selfReviewers.map((rule) => selfReviewOwners(rule).selfReviewUsers),
+    ),
+  };
+}

package/templates/agentic-owners/bot/lib/owners/match.ts

@@ -3,6 +3,7 @@
 
 import { posix } from "node:path";
 import { AGENTIC_OWNERS_DIR } from "./constants.js";
+import { blocksGlobalOverride, mergeGlobalOverride } from "./globalOverride.js";
 import { patternMatchesFile, patternSpecificity } from "./matching.js";
 import type {
   AgenticOwnersMatchedConfig,
@@ -16,6 +17,11 @@ type PathScopedRule = {
   readonly paths: readonly string[];
   /** Root-only repository-wide exemption, produced from `global_exclusions`. */
   readonly globalExclusion?: boolean;
+  /**
+   * Root `global_overrides` entry. Applied after precedence, not as a
+   * candidate for it.
+   */
+  readonly globalOverride?: boolean;
 };
 
 /**
@@ -116,23 +122,84 @@ function compareRulePrecedence(
   return left.sourcePath.localeCompare(right.sourcePath);
 }
 
-function pickWinningRuleForFile<T extends PathScopedRule>({
-  filepath,
-  rules,
-}: {
-  filepath: string;
-  rules: readonly T[];
-}): T | undefined {
-  let winner: T | undefined;
-  for (const rule of rules) {
+function selectRuleForFile(
+  filepath: string,
+  rules: readonly AgenticOwnersPathRule[],
+): {
+  readonly winner: { readonly rule: AgenticOwnersPathRule; readonly order: number } | undefined;
+  readonly overrides: readonly { readonly rule: AgenticOwnersPathRule; readonly order: number }[];
+} {
+  let winner: { readonly rule: AgenticOwnersPathRule; readonly order: number } | undefined;
+  const overrides: { readonly rule: AgenticOwnersPathRule; readonly order: number }[] = [];
+  for (const [order, rule] of rules.entries()) {
     if (!ruleMatchesFile({ rule, filepath })) {
       continue;
     }
-    if (winner === undefined || compareRulePrecedence(rule, winner, filepath) > 0) {
-      winner = rule;
+    if (rule.globalOverride === true) {
+      overrides.push({ rule, order });
+      continue;
+    }
+    if (winner === undefined || compareRulePrecedence(rule, winner.rule, filepath) > 0) {
+      winner = { rule, order };
     }
   }
-  return winner;
+  return { winner, overrides };
+}
+
+function teamsSkippedByOverride(
+  winner: AgenticOwnersPathRule,
+  override: AgenticOwnersPathRule,
+): boolean {
+  const skipped = override.skipTeams;
+  if (skipped === undefined || skipped.length === 0) {
+    return false;
+  }
+  const names = new Set(skipped.map((team) => team.trim().toLowerCase()));
+  return winner.teams.some((team) => names.has(team.trim().toLowerCase()));
+}
+
+function overrideAppliesToFile(
+  override: AgenticOwnersPathRule,
+  winner: AgenticOwnersPathRule,
+  filepath: string,
+): boolean {
+  if (teamsSkippedByOverride(winner, override)) {
+    return false;
+  }
+  const skipPaths = override.skipPaths;
+  if (skipPaths === undefined || skipPaths.length === 0) {
+    return true;
+  }
+  return !ruleMatchesFile({ rule: { ...override, paths: skipPaths }, filepath });
+}
+
+function effectiveRuleSelector(
+  rules: readonly AgenticOwnersPathRule[],
+): (filepath: string) => AgenticOwnersPathRule | undefined {
+  const cache = new Map<string, AgenticOwnersPathRule>();
+  return (filepath) => {
+    const { winner, overrides } = selectRuleForFile(filepath, rules);
+    if (winner === undefined || blocksGlobalOverride(winner.rule)) {
+      return winner?.rule;
+    }
+    const applicable = overrides.filter((entry) =>
+      overrideAppliesToFile(entry.rule, winner.rule, filepath),
+    );
+    if (applicable.length === 0) {
+      return winner.rule;
+    }
+    const key = `${winner.order}:${applicable.map((entry) => entry.order).join(",")}`;
+    const cached = cache.get(key);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const effective = mergeGlobalOverride(
+      winner.rule,
+      applicable.map((entry) => entry.rule),
+    );
+    cache.set(key, effective);
+    return effective;
+  };
 }
 
 export function matchRepoConfigForChangedFiles({
@@ -147,8 +214,9 @@ export function matchRepoConfigForChangedFiles({
   // file path would silently drop one (e.g. a hard-gate rule lost behind an
   // advisory rule from the same policy).
   const winners = new Set<AgenticOwnersPathRule>();
+  const ruleForFile = effectiveRuleSelector(config.rules);
   for (const filepath of changedFiles) {
-    const winner = pickWinningRuleForFile({ filepath, rules: config.rules });
+    const winner = ruleForFile(filepath);
     if (winner !== undefined) {
       winners.add(winner);
     }
@@ -175,9 +243,8 @@ export function changedFilesWithoutWinningRule({
   changedFiles: readonly string[];
   rules: readonly AgenticOwnersPathRule[];
 }): string[] {
-  return changedFiles.filter(
-    (filepath) => pickWinningRuleForFile({ filepath, rules }) === undefined,
-  );
+  const ruleForFile = effectiveRuleSelector(rules);
+  return changedFiles.filter((filepath) => ruleForFile(filepath) === undefined);
 }
 
 /**
@@ -198,9 +265,8 @@ export function everyChangedFileGloballyExcluded({
   if (changedFiles.length === 0) {
     return false;
   }
-  return changedFiles.every(
-    (filepath) => pickWinningRuleForFile({ filepath, rules })?.globalExclusion === true,
-  );
+  const ruleForFile = effectiveRuleSelector(rules);
+  return changedFiles.every((filepath) => ruleForFile(filepath)?.globalExclusion === true);
 }
 
 function hasOwners(rule: AgenticOwnersPathRule): boolean {