@cursor/bdk 0.2.4 → 0.2.6

package/dist/internal/server.d.ts

@@ -24,6 +24,12 @@ export interface StartServerInternalOptions {
     sessionRunLog?: ReturnType<typeof selectSessionRunLogStore>;
     /** Test seam: persist the engine start.log tee without a live store. */
     startLogStore?: ReturnType<typeof selectStartLogStore>;
+    /**
+     * `bdk eval` server. Cases drive seeded sessions, so live SCM and deployment
+     * ingest stay off, and a Cursor account GitHub credential that cannot be
+     * minted fails only the calls that need it.
+     */
+    evals?: boolean;
 }
 /**
  * Start an HTTP server hosting one or more agents. A single agent with an

package/dist/internal/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/internal/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiDH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAQhB,YAAY,EACb,MAAM,aAAa,CAAC;AA2FrB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAgDpE,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,iBAAiB,CAAC;AAUpE,OAAO,EAEL,wBAAwB,EAEzB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAsB,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAW/E,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;CACvB;AAuCD,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,yEAAyE;IACzE,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;IAC5D,wEAAwE;IACxE,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,YAAY,GAAG,0BAA+B,GACtD,OAAO,CAAC,gBAAgB,CAAC,CAwlC3B"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/internal/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiDH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAQhB,YAAY,EACb,MAAM,aAAa,CAAC;AA2FrB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAgDpE,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,iBAAiB,CAAC;AAUpE,OAAO,EAEL,wBAAwB,EAEzB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAsB,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAW/E,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;CACvB;AAuCD,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,yEAAyE;IACzE,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;IAC5D,wEAAwE;IACxE,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;IACvD;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,YAAY,GAAG,0BAA+B,GACtD,OAAO,CAAC,gBAAgB,CAAC,CAwmC3B"}

package/dist/internal/server.js

@@ -177,7 +177,9 @@ export function startServer(mounts_1) {
             explicitRepos: (_o = (_b = options.cursorEvents) === null || _b === void 0 ? void 0 : _b.repos) !== null && _o !== void 0 ? _o : [],
             targets: cursorOriginTargets,
         });
-        const effectiveCursorEvents = (_p = cursorGithubConfig.cursorEvents) !== null && _p !== void 0 ? _p : (cursorOriginScope === undefined ? undefined : { repos: [...cursorOriginScope.repos] });
+        const effectiveCursorEvents = options.evals === true
+            ? undefined
+            : ((_p = cursorGithubConfig.cursorEvents) !== null && _p !== void 0 ? _p : (cursorOriginScope === undefined ? undefined : { repos: [...cursorOriginScope.repos] }));
         // One resolution for every Cursor credential consumer (SDK runner, account
         // MCP bridge, SCM event relay, GitHub credentials): explicit option →
         // CURSOR_API_KEY → CURSOR_API_KEY_FILE (or the hosted default path) →
@@ -788,7 +790,15 @@ export function startServer(mounts_1) {
             validateMountConnectionsConfig(Object.assign(Object.assign({ slug,
                 project, accountRefs: accountRefsBySlug.get(slug) }, (options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl })), { cloudToolsBridge: options.cloudToolsUrl !== undefined }));
         }
-        yield cursorGithubCredentials === null || cursorGithubCredentials === void 0 ? void 0 : cursorGithubCredentials.start();
+        try {
+            yield cursorGithubCredentials === null || cursorGithubCredentials === void 0 ? void 0 : cursorGithubCredentials.start();
+        }
+        catch (error) {
+            if (options.evals !== true) {
+                throw error;
+            }
+            logger(`[agent-sdk] GitHub auth: no Cursor account credential (${error instanceof Error ? error.message : String(error)}); GitHub calls from eval sessions will fail`);
+        }
         // Cursor SCM events: v1 stays on the engine poll. v2 ingest is local-CP
         // only — hosted `--no-control-plane` skips the July poll (hosted CP wakes).
         const routeContinuation = localControlPlaneRoute(runtimes);
@@ -820,12 +830,14 @@ export function startServer(mounts_1) {
         }
         // Cursor deployment-events relay: automatic when a mounted agent authored
         // `deploymentsChannel({ ... })`.
-        const cursorDeploymentRelay = startCursorDeploymentRelay({
-            options,
-            runtimes,
-            accountKey,
-            logger,
-        });
+        const cursorDeploymentRelay = options.evals === true
+            ? undefined
+            : startCursorDeploymentRelay({
+                options,
+                runtimes,
+                accountKey,
+                logger,
+            });
         // Trust --public-url's host when a reverse proxy rewrites Host.
         const browserOriginGuard = browserOriginGuardOptionsForPublicUrl(options.publicUrl);
         const server = createServer((req, res) => {

package/dist/internal/session-links.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-links.d.ts","sourceRoot":"","sources":["../../src/internal/session-links.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAElE,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,CAAC,EAAE,iBAAiB,CAAC;CACnC,CAAC;AAKF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,oBAAoB,CAKpF"}
+{"version":3,"file":"session-links.d.ts","sourceRoot":"","sources":["../../src/internal/session-links.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAElE,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,CAAC,EAAE,iBAAiB,CAAC;CACnC,CAAC;AAKF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,oBAAoB,CAKpF"}

package/dist/internal/session-links.js

@@ -1,3 +1,4 @@
+import { parseGitHubPrContinuationKey } from "../channels/github/github-channel.js";
 import { parseGitHubPrRef } from "../channels/github/replay.js";
 import { slackThreadPermalink } from "../channels/slack/links.js";
 import { extractGithubPrRef } from "../channels/slack/pr-ref.js";
@@ -40,17 +41,17 @@ function slackUrl(record) {
     })) !== null && _j !== void 0 ? _j : undefined);
 }
 function githubUrl(record) {
-    var _a, _b;
-    var _c, _d;
-    const fromTitle = extractGithubPrRef((_c = record.title) !== null && _c !== void 0 ? _c : "");
+    var _a;
+    var _b, _c;
+    const fromTitle = extractGithubPrRef((_b = record.title) !== null && _b !== void 0 ? _b : "");
     if (fromTitle !== undefined) {
         return fromTitle.url;
     }
-    const key = (_d = record.continuationKey) !== null && _d !== void 0 ? _d : "";
-    if (key.startsWith("github-pr:")) {
-        return (_a = parseGitHubPrRef(key.slice("github-pr:".length))) === null || _a === void 0 ? void 0 : _a.url;
+    const fromKey = parseGitHubPrContinuationKey((_c = record.continuationKey) !== null && _c !== void 0 ? _c : "");
+    if (fromKey !== undefined) {
+        return `https://github.com/${fromKey.owner}/${fromKey.repo}/pull/${fromKey.number}`;
     }
-    const repos = (_b = record.cloudOverride) === null || _b === void 0 ? void 0 : _b.repos;
+    const repos = (_a = record.cloudOverride) === null || _a === void 0 ? void 0 : _a.repos;
     if (repos === undefined) {
         return undefined;
     }

package/dist/internal/sessions-client.d.ts

@@ -27,6 +27,7 @@ export declare function fetchSessionEvents(args: {
     sessionId: string;
     auth?: RequestAuth;
     fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
 }): Promise<SessionEvent[]>;
 /**
  * Pick the previous (most recently updated) followable session for

package/dist/internal/sessions-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sessions-client.d.ts","sourceRoot":"","sources":["../../src/internal/sessions-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEnF,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAEpF;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CA8B5F;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAiE1B;AAkCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAClC,cAAc,GAAG,SAAS,CAQ5B;AAED,+DAA+D;AAC/D,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO9B;AAED,+DAA+D;AAC/D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAIzE;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAAE,GACvC,MAAM,CAgBR"}
+{"version":3,"file":"sessions-client.d.ts","sourceRoot":"","sources":["../../src/internal/sessions-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEnF,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAEpF;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CA8B5F;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAmE1B;AAkCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAClC,cAAc,GAAG,SAAS,CAQ5B;AAED,+DAA+D;AAC/D,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO9B;AAED,+DAA+D;AAC/D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAIzE;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAAE,GACvC,MAAM,CAgBR"}

package/dist/internal/sessions-client.js

@@ -60,6 +60,7 @@ export function fetchSessionEvents(args) {
         try {
             const jsonResp = yield fetchImpl(`${baseUrl}${path}?format=json`, {
                 headers: mergeRequestHeaders(args.auth),
+                signal: args.signal,
             });
             if (jsonResp.ok) {
                 const body = (yield jsonResp.json());
@@ -83,6 +84,7 @@ export function fetchSessionEvents(args) {
         try {
             const resp = yield fetchImpl(`${baseUrl}${path}`, {
                 headers: mergeRequestHeaders(args.auth),
+                signal: args.signal,
             });
             if (resp.status === 404) {
                 throw new Error(`Session ${args.sessionId} not found.`);

package/docs/README.md

@@ -5,9 +5,9 @@ description: "Build, test, and deploy BDK bots and agents as code on Cursor's ag
 
 # Grok Bot Development Kit (BDK)
 
-The Grok Bot Development Kit (BDK) is how Cursor builds agents. It's the
-open-source version of the engine behind Bugbot, Security Review, and
-Approval Bot.
+The Grok Bot Development Kit (BDK) lets you define, test, and deploy agents
+as code. It uses the Cursor SDK harness that powers Bugbot, Security Review,
+and Approval Bot.
 
 A BDK project is a folder of Markdown and TypeScript. Combine deterministic
 code with model judgment, then make the bot or agent available in source
@@ -47,17 +47,9 @@ sandboxing on Cursor infrastructure or on your own host.
 
 ![BDK architecture: you bring the agent as code, and the platform provides triggers, runtime, integrations, and operations](/architecture.svg)
 
-## BDK package availability
-
-BDK uses the `@cursor/bdk` package and `bdk` binary. The package isn't on npm
-yet, so its install commands won't run until publication.
-
 ## Get started
 
-The preferred BDK workflow starts with `bdk init` and `bdk dev`.
-
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. The package will install
-> the `bdk` binary; this block will not run until it publishes.
+Install `@cursor/bdk`, then start with `bdk init` and `bdk dev`.
 
 ```text
 npm install --global @cursor/bdk
@@ -82,7 +74,7 @@ my-bot/
 │   ├── mcp-connections/
 │   │   └── linear.ts          # tools from an MCP server
 │   ├── host-connections/
-│   │   └── internal.ts        # host-only MCP tools
+│   │   └── inventory.ts       # host-only MCP tools
 │   ├── subagents/
 │   │   └── verifier/
 │   │       ├── agent.ts
@@ -102,10 +94,11 @@ Describe your bot or agent in Cursor, or edit the files yourself.
 - [Build your first PR reviewer](./quickstart.md): a working GitHub
   reviewer, one step at a time.
 
-- Start from a template with the docs-ahead `bdk init --template` command:
+- Start from a template:
+  [Grok Bot agents](./templates/grokbot-agents.md),
   [security reviewer](./templates/security-reviewer.md),
-  [thermo reviewer](./templates/thermo-review.md),
-  [thermo quality reviewer](./templates/thermo-quality-review.md),
+  [Thermo review](./templates/thermo-review.md),
+  [Thermo quality review](./templates/thermo-quality-review.md),
   [owners-policy approver](./templates/agentic-owners.md),
   [issue triager](./templates/triage.md).
 

package/docs/building-with-agents.md

@@ -10,9 +10,6 @@ a coding agent can create the project, exercise its tools, run a real
 turn, and inspect the result. You approve the plan and side effects
 while the coding agent owns the implementation loop.
 
-The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
-until publication; see [BDK package availability](/#bdk-package-availability).
-
 This page covers a coding agent working inside a checkout. To let a
 running agent propose changes to its own source, use the separate
 [self-improvement extension](./guides/improve.md).

package/docs/deployment.md

@@ -10,10 +10,6 @@ Cursor-managed hosting builds the selected Git ref and operates the
 runtime; self-hosting gives you control of the network, process, and
 filesystem.
 
-The `@cursor/bdk` imports and `bdk` commands in these examples are
-docs-ahead until publication; see
-[BDK package availability](/#bdk-package-availability).
-
 ## Choose managed hosting or self-hosting
 
 | Option | Use it when | You manage |
@@ -30,9 +26,6 @@ API.
 Commit and push the exact ref you want to run, then sign in, validate,
 and deploy. The preferred CLI is `bdk`.
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This block shows future
-> CLI syntax and will not run until the package publishes.
-
 ```text
 cd my-agent
 bdk login
@@ -41,7 +34,7 @@ bdk validate
 bdk deploy
 ```
 
-The deploy command waits until the engine is running and prints the stable
+The deploy command waits until the runtime is running and prints the stable
 deployment URL.
 
 `deploy` reads from Git; it does not upload your working tree. Inside a
@@ -184,7 +177,7 @@ multi-agent deployment, stop, and delete behavior.
 
 Managed hosting persists framework-owned session, KV, and file state
 across normal runtime replacements. Files written elsewhere on the
-engine's local filesystem are disposable; use `ctx.host.kv` or
+runtime's local filesystem are disposable; use `ctx.host.kv` or
 `ctx.host.files` for durable application state.
 
 Parked approvals and in-memory reminder handlers do not survive a

package/docs/evals.md

@@ -13,9 +13,6 @@ not to discover what the prompt should do.
 Evals run real model turns and real tools. Guard external writes before
 running a suite against an agent that can post, merge, or deploy.
 
-The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
-until publication; see [BDK package availability](/#bdk-package-availability).
-
 ## Protect a tool decision
 
 This smoke case asks for a PR verdict, requires the read-only inspection
@@ -197,8 +194,8 @@ Run `--tag smoke` on pull requests and the full suite on a schedule when
 cost or latency makes every-push coverage impractical. Use soft scores
 for a new probabilistic benchmark until its threshold is trustworthy.
 
-The [CLI reference](./reference/cli.md#eval) covers selectors, hosted
-runs, exit codes, and JSON output.
+The [CLI reference](./reference/cli.md#eval) covers selectors,
+server-side batches, exit codes, and JSON output.
 
 ## Keep side effects out of eval sessions
 

package/docs/guides/agent-to-agent.md

@@ -10,9 +10,6 @@ help. The specialist keeps its own instructions, tools, and session,
 while the caller decides when to delegate and returns the answer to the
 user. Co-host both projects under one `bdk` process.
 
-The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
-until publication; see [BDK package availability](/#bdk-package-availability).
-
 ## Delegate a question to a specialist
 
 Ask the concierge about the weather and it hands the question to the

package/docs/guides/bitbucket.md

@@ -10,9 +10,6 @@ current pull-request or commit state, and writes the result back to
 Bitbucket. `bitbucketChannel()` gives the same hooks and normalized
 payloads on Bitbucket Cloud and Data Center.
 
-The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
-until publication; see [BDK package availability](/#bdk-package-availability).
-
 ## Review a pull request
 
 Creating a pull request, or pushing new commits to a Data Center pull

package/docs/guides/cloud-agents.md

@@ -13,10 +13,6 @@ same branch.
 
 ## Mount it
 
-The extension will ship with `@cursor/bdk` when the package publishes.
-This import is docs-ahead; see
-[BDK package availability](/#bdk-package-availability).
-
 ```ts
 // bot/extensions/cloud.ts
 import cursorCloudAgents from "@cursor/bdk/extensions/cursor-cloud-agents";

package/docs/guides/convert-automation.md

@@ -14,9 +14,6 @@ path.
 configuration and prints a checklist for everything that still needs
 your judgment.
 
-The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
-until publication; see [BDK package availability](/#bdk-package-availability).
-
 ## Convert and run locally
 
 The command creates a project named after the Automation, installs its
@@ -101,9 +98,9 @@ reply experience and app setup.
 
 The generated GitHub channel keeps mechanical filters such as PR
 actions, branches, issue actions, repositories, and simple user
-allowlists. Conditions that depended on backend-only context stay
+allowlists. Conditions that depend on dashboard-only context stay
 fail-closed, so the corresponding hook returns `null` until you replace
-it.
+them.
 
 For example, a converted CI trigger can wake only when the suite fails:
 

package/docs/guides/github.md

@@ -10,9 +10,6 @@ latest PR and CI state, then write back reviews, comments, checks, or
 pushes. Pull events from Cursor, so you don't expose a public webhook
 URL.
 
-The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
-until publication; see [BDK package availability](/#bdk-package-availability).
-
 Connect GitHub in Cursor for the repos you care about (Settings or
 [cursor.com/dashboard](https://cursor.com/dashboard)). Sign the host in
 with `bdk login`. `cursorAccount` reuses that connection for
@@ -239,7 +236,7 @@ Every wake for the same repo and PR number resumes the same session. The
 channel keys turns as `github-pr:acme/checkout#42`. Opens, comments, and
 CI results share that conversation.
 
-## Call GitHub from determistic code via `ctx`
+## Call GitHub from deterministic code via `ctx`
 
 `cursorAccount` puts one credential on both surfaces:
 

package/docs/guides/gitlab.md

@@ -10,9 +10,6 @@ project or merge-request state, and writes the result back to GitLab.
 `gitlabChannel()` supports the same hooks on GitLab.com and self-managed
 GitLab.
 
-The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
-until publication; see [BDK package availability](/#bdk-package-availability).
-
 ## Review a merge request
 
 Opening, reopening, or pushing commits to a merge request starts a

package/docs/guides/grokbot-agents.md

@@ -10,9 +10,6 @@ the Grok Bot agents on its serve host's Cursor account. The bot keeps
 its existing conversation, memory, and tools, while your agent carries
 the delivered reply back into the current conversation.
 
-The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
-until publication; see [BDK package availability](/#bdk-package-availability).
-
 Use this extension on the local runtime. It consults another Grok Bot;
 it does not move this agent onto a Grok Bot runtime.
 
@@ -62,7 +59,7 @@ The message must include who is asking, the relevant facts, and the
 shape of the answer. The Grok Bot does not see the current BDK
 conversation.
 
-> Netto is deciding whether to move Saturday's picnic. The forecast is
+> Avery is deciding whether to move Saturday's picnic. The forecast is
 > 70% rain from 1-4pm. Recommend keep or move, give one reason, and name
 > the best alternate time.
 

package/docs/guides/hooks.md

@@ -10,9 +10,6 @@ as updating metrics or sending alerts. They never change the turn, prompt, or
 reply. Author them under `bot/hooks/` with `defineHook` from
 `@cursor/bdk/hooks`.
 
-The `@cursor/bdk` imports on this page are docs-ahead until publication;
-see [BDK package availability](/#bdk-package-availability).
-
 ## Meter token usage
 
 With [OpenTelemetry](./opentelemetry.md) configured, this hook adds a live

package/docs/guides/improve.md

@@ -10,9 +10,6 @@ work" into a source change. The agent prepares a brief, a Cursor cloud
 agent edits a checkout and opens a pull request, and the running agent
 reports the verified PR for human review.
 
-The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
-until publication; see [BDK package availability](/#bdk-package-availability).
-
 Durable behavior does not change until that source is merged and
 deployed.
 

package/docs/guides/jev.md

@@ -11,9 +11,6 @@ risk, choose a reviewer, or decide whether a merge needs a documentation
 follow-up. Jev returns a choice, score, or probability; your TypeScript
 decides what happens next.
 
-The `@cursor/bdk` imports on this page are docs-ahead until publication;
-see [BDK package availability](/#bdk-package-availability).
-
 Set `TYPESAFE_API_KEY`. The default model is `jev-latest`.
 
 ```ts

package/docs/guides/mcp-oauth.md

@@ -10,9 +10,6 @@ without putting tokens in the agent's source or workspace. Use it when
 the server speaks OAuth and its credentials should belong to the serve
 host instead of a person's Cursor account.
 
-The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
-until publication; see [BDK package availability](/#bdk-package-availability).
-
 ## Use a private MCP tool locally
 
 Declare the remote server, authorize it once in the browser, and start
@@ -129,7 +126,7 @@ bdk deploy
 ```
 
 `--store` writes deployment secrets; it does not restart the current
-engine. Follow the CLI or dashboard prompt to redeploy, then exercise
+process. Follow the CLI or dashboard prompt to redeploy, then exercise
 the hosted agent.
 
 These credentials belong to the deployment, not to the person who

package/docs/guides/opentelemetry.md

@@ -13,16 +13,13 @@ cost metrics from the serve process.
 Export is opt-in. Nothing leaves the process until you configure a
 destination.
 
-The `bdk` commands on this page are docs-ahead until `@cursor/bdk` is
-published; see [BDK package availability](/#bdk-package-availability).
-
 ## Connect an OTLP collector
 
 Set the collector endpoint, start the agent, and send it a message. You
 should see an `agent_sdk.http` request span and an `agent_sdk.turn`
 trace, with any tool or subagent work nested under the turn.
 
-```text
+```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
@@ -35,7 +32,9 @@ The default protocol is OTLP/HTTP protobuf. If you already call
 code:
 
 ```ts
-await serve(dir, {
+import { serve } from "@cursor/bdk";
+
+await serve(".", {
   otel: {
     serviceName: "incident-agent",
     exporters: [

package/docs/guides/slack.md

@@ -10,9 +10,6 @@ in a channel it watches. From there, it keeps the conversation in one
 thread and can reply all at once, stream the answer live, or decide for
 itself when to post updates.
 
-The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
-until publication; see [BDK package availability](/#bdk-package-availability).
-
 Run `bdk slack create --dir .`, then `bdk slack doctor`.
 
 ## Answer a mention or DM
@@ -47,7 +44,7 @@ export default slackChannel({
       reasoning: true,
       // Tool names as they start ("Running grep, glob...").
       tools: true,
-      idle: ["Checking the monorepo...", "Poking Datadog..."],
+      idle: ["Checking the request...", "Reviewing recent activity..."],
     },
   },
 });
@@ -108,15 +105,12 @@ This example watches `#triage-alerts`, so any substantial top-level
 message starts a thread even when nobody mentions the bot. The length
 guard filters out short posts before they can start a turn.
 
-Mentions are global — the bot answers an @mention in any channel it has
-joined — but listening without a mention names its channels: `allow`
-must include at least one channel id (`C…`/`G…`) and at most 10 distinct
-ids. `#name` entries may accompany the ids for readability. A lone `"*"`
-watches every channel the bot is in, thread replies only
-(`posts: "replies"`). Mixing `"*"` with ids is an error. `"*"` is the
-guest watcher: it is not a hosting subscription. A thread reply on
-Cursor-managed hosting is delivered when a mention already opened that
-thread, and a top-level post does not match.
+Mentions work in any channel the bot has joined. Listening without a
+mention requires an explicit allowlist with at least one channel ID
+starting with `C` or `G` and at most 10 distinct IDs. You can add
+`#name` entries for readability. A lone `"*"` watches replies in every
+joined channel (`posts: "replies"`), but it does not wake on top-level
+posts. Do not mix `"*"` with channel IDs.
 
 ```ts
 export default slackChannel({
@@ -140,15 +134,11 @@ export default slackChannel({
 When you create the app, pass `--channel-posts` and invite the bot to
 every channel in the allowlist.
 
-On Cursor-managed hosting the id entries also define the delivery set:
-each becomes a channel-scoped subscription, and a channel post outside
-the allowlist is dropped at ingress before any compute wakes (replies in
-threads the agent is already part of still arrive). The same watch runs
-at admission for each delivered event. `debounceMs` is ignored there:
-the control plane answers every delivery immediately, and edits arrive
-as separate deliveries that are dropped at the edge. Channel ids match
-without any Slack call; `#name` entries are resolved once per pod with
-the bot token and need the `channels:read` scope.
+On Cursor-managed hosting, the channel IDs in `allow` define which
+top-level posts can wake the agent. Replies in threads the agent has
+already joined still arrive. `debounceMs` applies only when you
+self-host. Add the `channels:read` scope when you include `#name`
+labels.
 
 ## Control who can message
 
@@ -230,7 +220,7 @@ Use the IDs on the hook `ctx` when handling an event, and
 
 ## Connect
 
-```text
+```bash
 bdk login
 bdk slack create --dir .
 bdk slack doctor --prefix TRIAGE
@@ -256,7 +246,7 @@ and tokens.
 Run `doctor` first to catch missing credentials, then start the agent
 and send it the same mention or DM a teammate would.
 
-```text
+```bash
 bdk slack doctor --prefix TRIAGE
 bdk serve --dir . --dev
 ```

package/docs/guides/webhooks.md

@@ -10,9 +10,6 @@ conversation, then sends the result back to the system that started it.
 Use one when the built-in [HTTP API](../reference/http-api.md) does not
 match the provider's payload, conversation key, or reply path.
 
-The `@cursor/bdk` imports on this page are docs-ahead until publication;
-see [BDK package availability](/#bdk-package-availability).
-
 Author `bot/channels/<id>.ts`. Its routes mount under
 `/<slug>/v1/channels/<id>`.
 

package/docs/hillclimbing.md

@@ -13,9 +13,6 @@ crossing the freeze line.
 The companion [`hillclimb` skill](../skills/hillclimb/SKILL.md) can run
 this loop with you.
 
-The `bdk` commands on this page are docs-ahead until `@cursor/bdk` is
-published; see [BDK package availability](/#bdk-package-availability).
-
 ## Correct a wrong tool choice
 
 Suppose a PR reviewer calls `approve_pr` before `inspect_pr`. Pin one PR

package/docs/quickstart.md

@@ -13,15 +13,13 @@ review.
 
 - Node 22.13 or newer.
 
-- The docs-ahead BDK package and CLI. `@cursor/bdk` is not on npm yet,
-  so these commands will not run until publication. See
-  [BDK package availability](/#bdk-package-availability).
+- The `@cursor/bdk` package:
 
 ```text
 npm install -g @cursor/bdk
 ```
 
-- A Cursor credential for model turns. After publication, sign in once:
+- A Cursor credential for model turns. Sign in once:
 
 ```text
 bdk login
@@ -31,9 +29,6 @@ bdk login
 
 The preferred BDK workflow uses `bdk init` and `bdk dev`.
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This block shows future
-> CLI syntax and will not run until the package publishes.
-
 ```text
 bdk init ./pr-reviewer
 cd pr-reviewer

package/docs/reference/agent-config.md

@@ -9,9 +9,6 @@ description: "defineAgent at bot/agent.ts: the model, local workspace, and progr
 the agent and its local harness defaults.
 Everything is optional on the root agent.
 
-The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
-until publication; see [BDK package availability](/#bdk-package-availability).
-
 ```ts
 import { defineAgent } from "@cursor/bdk";
 
@@ -35,15 +32,15 @@ export default defineAgent({
 | `description` | string | What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root. |
 | `instructions` | string | Inline instructions. Prefer `instructions.md`; this exists for subagents and generated configs. |
 | `local` | `{ cwd?, workspaceDir?, sandbox? }` | Local harness defaults. See [Local options](#local-options). |
-| `hosting` | `{ egressDomains?, secretNames? }` | Managed-hosting declarations read by `bdk deploy`: the pod's egress allowlist and the secret names the agent expects. Mounted [extensions](./extensions.md#build-an-extension) add their own. Ignored by local serving. |
-| `concurrency` | `{ maxRunningTurns? }` | Engine-wide turn admission limit. See [Concurrency](#concurrency). |
+| `hosting` | `{ egressDomains?, secretNames? }` | Managed-hosting declarations read by `bdk deploy`: the deployment's egress allowlist and the secret names the agent expects. Mounted [extensions](./extensions.md#build-an-extension) add their own. Ignored by local serving. |
+| `concurrency` | `{ maxRunningTurns? }` | Agent-wide concurrent turn limit. See [Concurrency](#concurrency). |
 | `builtinTools` | `{ reminders? }` | Framework-provided model-facing tools, opted in per capability. See [Built-in tools](#built-in-tools). |
 | `tools` | `ToolName[]` | Allowlist of built-in harness tools offered to the model. Unset = the model's full standard toolset. See [Harness tools](#harness-tools). |
 
 ## Model
 
 `model` is a Cursor model id string, or `{ id, params }`. Effort and
-speed are params, not id suffixes. The SDK rejects suffix-style ids
+speed are params, not id suffixes. BDK rejects suffix-style ids
 like `grok-4.5-fast`:
 
 ```ts
@@ -116,7 +113,7 @@ servers, point `local.cwd` outside the checkout. See
 [Local cwd](#local-cwd). `local.sandbox` makes MCP tool calls fail
 closed.
 
-Use the SDK's public tool names, including `"shell"`, `"read"`,
+Use the Cursor SDK's public tool names, including `"shell"`, `"read"`,
 `"edit"`, `"grep"`, `"glob"`, `"ls"`, and `"task"`. Unknown names
 fail the turn with a `ConfigurationError`.
 

package/docs/reference/artifacts.md

@@ -10,9 +10,6 @@ or decision records. An artifact kind defines the data it accepts, and
 the artifacts API tags or updates records by key. Records persist across
 sessions and can be listed, streamed, or downloaded.
 
-The `@cursor/bdk` imports on this page are docs-ahead until publication;
-see [BDK package availability](/#bdk-package-availability).
-
 ## Artifact kinds
 
 Author `bot/artifacts.ts` with `defineArtifacts` from