@cursor/bdk 0.2.24 → 0.2.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/bdk",
-  "version": "0.2.24",
+  "version": "0.2.26",
   "description": "Build, test, and deploy BDK bots and agents as code on Cursor's agent harness.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -41,6 +41,7 @@
     "package.json",
     "LICENSE.md",
     "README.md",
+    "CHANGELOG.md",
     "AGENTS.md"
   ],
   "exports": {
@@ -57,6 +58,20 @@
       "import": "./dist/executors.js",
       "default": "./dist/executors.js"
     },
+    "./internal/continuation": {
+      "anysphere-source": "./src/internal/continuation.ts",
+      "bun": "./dist/internal/continuation.js",
+      "types": "./dist/internal/continuation.d.ts",
+      "import": "./dist/internal/continuation.js",
+      "default": "./dist/internal/continuation.js"
+    },
+    "./internal/discovery": {
+      "anysphere-source": "./src/internal/discovery.ts",
+      "bun": "./dist/internal/discovery.js",
+      "types": "./dist/internal/discovery.d.ts",
+      "import": "./dist/internal/discovery.js",
+      "default": "./dist/internal/discovery.js"
+    },
     "./internal/cursor-hosted": {
       "anysphere-source": "./src/storage-backends/cursor-hosted.ts",
       "bun": "./dist/storage-backends/cursor-hosted.js",
@@ -92,6 +107,13 @@
       "import": "./dist/otel.js",
       "default": "./dist/otel.js"
     },
+    "./internal/otel-env": {
+      "anysphere-source": "./src/internal/otel-env.ts",
+      "bun": "./dist/internal/otel-env.js",
+      "types": "./dist/internal/otel-env.d.ts",
+      "import": "./dist/internal/otel-env.js",
+      "default": "./dist/internal/otel-env.js"
+    },
     "./internal/storage": {
       "anysphere-source": "./src/internal/storage.ts",
       "bun": "./dist/internal/storage.js",
@@ -141,6 +163,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",
@@ -336,7 +365,13 @@
     "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {
+    "@anysphere/agent-exec": "1.0.0",
+    "@anysphere/agent-store-sync": "1.0.0",
+    "@anysphere/context": "1.0.0",
+    "@anysphere/proto": "1.0.0",
+    "@anysphere/ui": "1.0.0",
     "@braintree/sanitize-url": "7.1.2",
+    "@microsoft/api-extractor": "7.59.4",
     "@stylexswc/rs-compiler": "^0.18.0",
     "@tanstack/react-virtual": "3.13.23",
     "@types/js-yaml": "4.0.9",
@@ -365,13 +400,8 @@
     "vitepress-plugin-mermaid": "^2.0.17",
     "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/agent-store-sync": "1.0.0",
-    "@anysphere/proto": "1.0.0",
-    "@anysphere/ui": "1.0.0"
+    "zod": "4.6.5",
+    "zustand": "^5.0.9"
   },
   "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",
@@ -380,6 +410,7 @@
     "build:playground": "vite build --config playground/vite.config.ts",
     "build:playground:central": "vite build --mode central --config playground/vite.config.ts",
     "dev:playground": "vite --config playground/vite.config.ts",
+    "api:report": "node scripts/api-report.mjs",
     "check": "oxlint src && tsc --noEmit && tsc --noEmit -p playground/tsconfig.json",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",

package/schemas/grokbot-answers.schema.json

@@ -159,6 +159,9 @@
     },
     "connectors": {
       "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
       "additionalProperties": {
         "type": "object",
         "properties": {
@@ -200,8 +203,14 @@
     },
     "fillIns": {
       "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
       "additionalProperties": {
         "type": "object",
+        "propertyNames": {
+          "type": "string"
+        },
         "additionalProperties": {
           "type": "string",
           "minLength": 1,
@@ -273,6 +282,7 @@
         },
         "at": {
           "type": "string",
+          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})$",
           "format": "date-time",
           "title": "Deploy at",
           "description": "Deploy at (ISO 8601 with a timezone)?",
@@ -309,6 +319,7 @@
         },
         "cutoverAt": {
           "type": "string",
+          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})$",
           "format": "date-time",
           "title": "Slack cutover at",
           "description": "Switch Slack traffic at (ISO 8601 with a timezone)?",

package/skills/framework-map/SKILL.md

@@ -54,12 +54,13 @@ Path is identity. Full list: README "Folder structure".
 | `bot/channels/*.ts` | Slack / GitHub / custom HTTP |
 | `bot/hooks/*.ts` | Observe-only |
 | `bot/artifacts.ts` | Durable tagged outputs (`defineArtifacts`) |
-| `bot/otel.ts` | Factory-only OpenTelemetry (`defineOtel`) |
 | `bot/schedules/*` | Cron. Never auto-fire under `--dev` |
 | `bot/sandbox/workspace/` | Session seed files (local only) |
 | `bot/lib/` | Import-only. Never discovered |
 | `evals/**/*.eval.ts` | Case id is the path under `evals/` |
 
+OpenTelemetry export uses `OTEL_*` environment variables. See the guide section "Migrating from serve({ otel })".
+
 Discovery rejects `bot/result.ts`. To act on a turn's decision, record it with
 an authored tool and act on it from a `turn.completed` hook.
 

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

@@ -1,64 +1,48 @@
 ---
 name: bdk-otel
 description: >-
-  Wire OpenTelemetry export (OTLP env, serve({ otel }), traces/metrics/logs,
-  ctx.host.otel). Use when adding collector export or custom metrics.
+  Wire OpenTelemetry export with OTEL_* environment variables.
+  Use when adding a collector, headers, or metrics temporality.
 ---
 
 # BDK OpenTelemetry
 
-Push traces and metrics from the serve process to an OTLP
-collector. Logs are off until you opt in.
+Customers configure export with standard `OTEL_*` environment variables
+and secrets. There is no instrumentation file and no `defineOtel`.
+`ctx.host.otel` is deprecated. Use `metrics.getMeter` and
+`trace.getTracer`. A span during a turn gets `cursor.conversation.id`
+from the active context. A metric does not. Call
+`currentConversationId` from `@cursor/bdk/otel` and set it yourself.
 
 Guide: `docs/guides/opentelemetry.md`.
 
-## Enable
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $OTEL_TOKEN"
+export OTEL_SERVICE_NAME=incident-agent
+```
 
-Public surface (use one of these):
+BDK installs trace, metric, and log providers before `bot/agent.ts`.
+A module-scope `trace.getTracer()`, `metrics.getMeter()`, or
+`logs.getLogger()` binds to those providers. Exporters attach when
+secrets load. With no `OTEL_EXPORTER_OTLP_*` endpoint, export stays
+off. Outbound fetch does not gain a `traceparent` header, and the
+session collector stays disabled.
 
-1. `OTEL_EXPORTER_OTLP_ENDPOINT` (optional
-   `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_HEADERS`,
-   `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf|http/json`)
-2. `serve(dir, { otel: { … } })`. `otel: false` disables env and
-   authored config.
+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.
+Do not pass `otel` to `serve`. Do not add `bot/otel.ts`.
+Read the guide section "Migrating from serve({ otel })".
 
 Hosted agents:
 
-- Set `OTEL_EXPORTER_OTLP_ENDPOINT` and
-  `OTEL_EXPORTER_OTLP_HEADERS` with `bdk secrets set`. Add the
-  collector host to `hosting.egressDomains`.
+- Put the same variables in `bdk secrets set`, and 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 |
-| --- | --- |
-| Traces | on (`agent_sdk.http`; `agent_sdk.turn` → tool / subagent) |
-| Metrics | on (`cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`) |
-| 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.
-
-## Custom metrics
-
-```ts
-ctx.host.otel.setAttributes({ "abc.ticket_id": "INC-123" });
-ctx.host.otel.increment("abc.ticket.resolved");
-ctx.host.otel.record("abc.approval.duration_ms", 1420);
-```
+- A new header or URL from `bdk secrets set` applies on the next export.
 
-Prefix names with team or agent. No custom spans. Join on
-`agent_sdk.session_id` / `cursor.conversation.id` and
-`agent_sdk.agent`.
+Not supported yet: custom span processors, samplers, views, your own
+SDK, and library auto-instrumentation. A span that ends before the
+exporters attach is still exported. `OTEL_TRACES_SAMPLER` and
+`OTEL_METRIC_EXPORT_INTERVAL` are read when the provider is built.

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 {