@cursor/bdk 0.2.14 → 0.2.16

package/skills/framework-map/SKILL.md

@@ -33,9 +33,9 @@ Public docs: `node_modules/@cursor/bdk/dist/docs/llms.txt` or
    `CURSOR_API_KEY_FILE`, then `CURSOR_SERVICE_ACCOUNT_KEY`, then
    `bdk login`). `validate`,
    `info`, `call`, and `serve` bring-up do not.
-7. **Memory is `ctx.host.kv`.** The process is not a persistent
-   box. A later event can run on another replica. Module `Map`s,
-   globals, and ad-hoc files do not survive that.
+7. **Memory is `ctx.host.kv`.** On Cursor hosting, a later event
+   can run in a new process. Module `Map`s, globals, and local files
+   do not carry over.
 
 ## Folder structure
 
@@ -63,8 +63,8 @@ Path is identity. Full list: README "Folder structure".
 
 ## Runtime
 
-Turns run on the serve host. Server tools, approvals, agent tools,
-skills, and sandbox seeds are available there.
+Turns run on the serve host. Server tools, agent tools, skills, and
+sandbox seeds are available there.
 
 ## Sessions
 
@@ -84,9 +84,9 @@ Anything you need to remember goes in `ctx.host.kv`: coalesce,
 dedupe, cursors, a decision a later turn must see. `get`, `put`,
 and `delete`. Values are JSON.
 
-Hosted BDK is multi-tenant. The serve process is replaced,
-and the next hook, tool call, channel event, or footer can land
-on a different process. Do not assume this box is still up.
+On Cursor hosting, the platform can replace the serve process at
+any time. The next hook, tool call, or channel event can run in a
+new process, so do not assume this one is still up.
 
 - The store is shared by every session of the agent. Prefix keys
   with `ctx.session.id` for per-session memory.
@@ -107,14 +107,14 @@ before you return.
 Code: side-effect gates, write dedupe (the record lives in
 `ctx.host.kv`), auth, evidence seeding, hard API caps. Model:
 formatting, summarizing, classification, replies.
-Budget: `skills/create-bot/SKILL.md`.
+Budget: `skills/create-agent/SKILL.md`.
 
 Loop: `validate` / `info` / `call` / `run` / `eval` / `serve`. Serve
 only this agent's directory.
 
 | Task | Skill |
 | --- | --- |
-| Scaffold | `skills/create-bot/SKILL.md` |
+| Scaffold | `skills/create-agent/SKILL.md` |
 | Evals | `skills/evals/SKILL.md` |
 | OpenTelemetry | `skills/otel/SKILL.md` |
 | GitHub | `skills/github/SKILL.md` |

package/skills/mcp-auth/SKILL.md

@@ -2,8 +2,8 @@
 name: bdk-mcp-auth
 description: >-
   Authorize host MCP OAuth for defineConnection({ url, oauth: true }):
-  bdk mcp oauth, local tokens, --store, advertiseTools, egress.
-  Use when wiring or debugging MCP auth.
+  bdk mcp oauth, local tokens, advertiseTools, egress, and the hosted
+  cursorAccount path. Use when wiring or debugging MCP auth.
 ---
 
 # Host MCP OAuth
@@ -24,17 +24,14 @@ can still call `ctx.host.mcp`.
 1. **Declare the connection.** `bot/mcp-connections/<name>.ts`
    with `url` + `oauth: true`. Use `bot/host-connections/` when
    the model must not see it.
-2. **Name the secrets** if you will `--store`:
-   `hosting.secretNames` lists
-   `MCP_OAUTH_<NAME>_{ACCESS_TOKEN,REFRESH_TOKEN,CLIENT_ID}`.
-3. **Allow egress** on hosted non-bootstrap hosts:
+2. **Allow egress** on hosted non-bootstrap hosts:
    `hosting.egressDomains`.
-4. **Authorize.** Local: `bdk mcp oauth <name>`. Hosted:
-   finish Connect so the current process can retry, then
-   `bdk mcp oauth <name> --store` and `bdk deploy` so
-   the next pod gets `MCP_OAUTH_*`. `secrets list` shows the names.
-   Secrets are deployment-wide, not per caller. `cursorAccount: true`
-   stays on the Cursor backend.
+3. **Authorize.** Local: `bdk mcp oauth <name>`, or finish
+   Connect in the playground so the current process can retry.
+   Tokens stay on this machine. Hosted: use a
+   `cursorAccount: true` connection and connect the server from
+   **Deployed Agents** in the dashboard; its tokens stay on the
+   Cursor backend.
 
 ```ts
 // bot/mcp-connections/inventory.ts
@@ -44,41 +41,20 @@ export default defineConnection({
 });
 ```
 
-```ts
-// bot/agent.ts
-export default defineAgent({
-  hosting: {
-    secretNames: [
-      "MCP_OAUTH_INVENTORY_ACCESS_TOKEN",
-      "MCP_OAUTH_INVENTORY_REFRESH_TOKEN",
-      "MCP_OAUTH_INVENTORY_CLIENT_ID",
-    ],
-    egressDomains: ["mcp.example.com"],
-  },
-});
-```
-
-File `inventory.ts` → prefix `MCP_OAUTH_INVENTORY`. Do not put
-`CURSOR_*` names in `secretNames`.
-
 ```bash
 bdk mcp oauth <connection>
-bdk mcp oauth <connection> --store [--slug <slug>]
-bdk secrets list <slug>
-bdk deploy
 ```
 
 Browser callback: `http://127.0.0.1:8787/callback`. Tokens live in
 the CLI config directory (`mcp-auth.json` or
 `$AGENT_SERVE_CONFIG_DIR`). URL change drops the old entry; re-run.
-`--store` does not restart a running engine.
 
 | Symptom | Fix |
 | --- | --- |
 | `must be defineConnection({ url, oauth: true })` | Wrong name or missing `oauth: true` |
 | `Unknown MCP connection` | Filename must match the CLI arg |
 | Callback hang | Free port 8787; finish the browser flow here |
-| Hosted 401 | `secrets list`; Connect or `--store`; redeploy |
+| Hosted 401 | Local tokens don't reach the deployment. Switch to `cursorAccount: true`; connect from **Deployed Agents** |
 | Model invents `mcp_auth` / IDE MCP | `advertiseTools: true` on local turns |
 
 No raw tokens in git.

package/skills/migrate-v2/SKILL.md

@@ -62,18 +62,18 @@ ends. That model changes code in three places:
 | Local `bdk dev`, `run`, `eval`, and the playground | Supported |
 | `defineStorage` in `agent/storage.ts` | Not supported. Delete the file. |
 | Reminders with inline `run` or a function `until` | Not supported. Use a named handler. |
-| Cron schedules in `agent/schedules/` on Cursor hosting | Not delivered yet. Self-hosted `bdk serve` still runs them. |
+| Cron schedules in `agent/schedules/` on Cursor hosting | Supported with `@cursor/bdk` 0.2.14 or newer. Each fire runs in a new runtime and must finish in 26 minutes. |
 | Slack tool-approval buttons on Cursor hosting | Not supported yet |
 | `bdk mcp oauth --store` for host MCP OAuth | Not supported. Connect Cursor-account MCP servers from **Deployed Agents** in the dashboard. |
-| `/v1/health`, session, tool, and MCP APIs on the deployment URL | Not reachable |
-| `--prod` with `chat`, `resume`, `call`, `sessions`, `cost`, or `mcp` | Not supported. Use `run --prod`, `session --prod`, and `logs --prod`. |
+| Session, tool, and MCP APIs on the deployment URL | Not reachable |
+| `--prod` with `chat`, `resume`, `call`, `skill`, `sessions`, `cost`, or `mcp` | Not supported. Use `run --prod`, `logs --prod`, `session --prod`, and `playground --prod`. |
 | v1 sessions, KV, and files | Not carried over. v2 starts empty, and deleting v1 deletes them. |
 
 The steps below rewrite `defineStorage`, inline reminders, SCM channel
 credentials, and secret reads. Stop and ask before migrating an agent
-that depends on cron schedules, Slack tool-approval buttons,
-`mcp oauth --store`, or an HTTP route whose caller reads the response
-body. Name the row and the file that uses it.
+that depends on Slack tool-approval buttons, `mcp oauth --store`, or an
+HTTP route whose caller reads the response body. Name the row and the
+file that uses it.
 
 ## Update the project
 
@@ -181,7 +181,8 @@ still loads.
 
 8. **Stop answering from HTTP routes.** A custom route that returned
    computed data must deliver it another way, such as a callback URL or a
-   tool the turn calls.
+   tool the turn calls. Return `new Response(null, { status: 202 })` so
+   local runs match the hosted response.
 
 ## Verify locally
 
@@ -257,8 +258,11 @@ After the deploy is running:
   secrets go unused.
 - Reconnect Cursor-account MCP servers from **Deployed Agents** in the
   dashboard.
-- Start a turn with `bdk run --prod --slug <slug> --message "..."`, then
-  read it with `bdk session <ses_...> --prod --slug <slug>`.
+- Start a turn with `bdk run --prod --slug <slug> --message "..."`. It
+  prints a `deliveryId`, not a session. Find the `ses_...` header in
+  `bdk logs --prod --once --slug <slug>`, then read the turn with
+  `bdk session <ses_...> --prod --slug <slug>` until the latest run
+  finishes.
 
 The [deploy skill](../deploy/SKILL.md) covers deploys with an attached
 service account.

package/skills/setup-slack/SKILL.md

@@ -134,16 +134,3 @@ export default slackChannel({
 Pass `--channel-posts` on `create` / `init --manual`. Invite the
 bot to each watched channel. Mentions stay on `app_mention`; a
 later mention continues the watch thread.
-
-## Approvals (opt-in)
-
-```ts
-export default slackChannel({
-  envPrefix: "JENNY",
-  toolApprovals: true,
-});
-```
-
-Wizard enables interactivity when this is set. Server tools on
-`local` only. Parked calls die on host restart. Cards truncate
-args; execution uses the full input.

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

@@ -50,5 +50,5 @@ export function sanitizeReviewerHandle(raw: string): string | undefined {
     return `${org}/${team}`;
   }
   const login = trimmed.replace(/^@/, "").toLowerCase();
-  return /^[a-z0-9][a-z0-9-]*$/.test(login) ? `@${login}` : undefined;
+  return /^[a-z0-9][a-z0-9-]*(?:_[a-z0-9]+)?$/.test(login) ? `@${login}` : undefined;
 }

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

@@ -16,13 +16,20 @@ export function patternMatchesFile(pattern: string, filepath: string): boolean {
     return true;
   }
 
-  // Keep the fast prefix path for literal `dir/**` rules. A wildcard before
-  // the terminal `/**` (for example `**/agent-serve/**`) must fall through to
-  // minimatch; treating its wildcard text as a literal prefix never matches.
-  if (normalizedPattern.endsWith("**") && !hasComplexGlob(normalizedPattern.replace(/\*+$/, ""))) {
-    const rawPrefix = normalizedPattern.replace(/\*+$/, "");
-    const prefix = rawPrefix.replace(/\\(.)/g, "$1").replace(/\/+$/, "");
-    return normalizedPath === prefix || (prefix !== "" && normalizedPath.startsWith(`${prefix}/`));
+  const literalPrefix = normalizedPattern.replace(/\*+$/, "");
+  if (normalizedPattern.endsWith("**") && !hasComplexGlob(literalPrefix)) {
+    const prefix = literalPrefix.replace(/\\(.)/g, "$1").replace(/\/+$/, "");
+    if (normalizedPath === prefix || (prefix !== "" && normalizedPath.startsWith(`${prefix}/`))) {
+      return true;
+    }
+    if (literalPrefix === "" || literalPrefix.endsWith("/")) {
+      return false;
+    }
+    if (patternIsRooted && !literalPrefix.includes("/") && normalizedPath.includes("/")) {
+      return false;
+    }
+    // gitignore reads `x**` as `x*`.
+    return globMatches(normalizedPath, `${literalPrefix}*`);
   }
 
   if (normalizedPattern.endsWith("/")) {
@@ -37,10 +44,14 @@ export function patternMatchesFile(pattern: string, filepath: string): boolean {
     return true;
   }
 
+  return globMatches(normalizedPath, normalizedPattern);
+}
+
+function globMatches(filepath: string, pattern: string): boolean {
   try {
-    return minimatch(normalizedPath, normalizedPattern, {
+    return minimatch(filepath, pattern, {
       dot: true,
-      matchBase: !normalizedPattern.includes("/"),
+      matchBase: !pattern.includes("/"),
       nocase: false,
     });
   } catch {

package/templates/agents-md/README.md

@@ -1,9 +1,9 @@
 # Living AGENTS.md
 
 Keeps `AGENTS.md` current from last week's merged pull requests and the
-listed Slack channels. Parks an update until a person approves it, then
-opens a draft follow-up PR. Chores stay quiet. Same-base updates stack
-on `agents-md/<base>`.
+listed Slack channels. Opens each update as a draft follow-up PR for a
+person to review. Chores stay quiet. Same-base updates stack on
+`agents-md/<base>`.
 
 ```text
 npx @cursor/bdk init ./agents-md --template agents-md

package/templates/agents-md/bot/channels/queue.ts

@@ -7,14 +7,9 @@ export default defineChannel({
     POST("/run", {
       description: "Collect last week's PRs and Slack, then review AGENTS.md",
       bodySchema: z.object({}),
-      handler: async (_req, { send, host, auth }) => {
-        const week = await collectWeek(host);
-        const session = await startWeek(send, week, auth);
-        return Response.json({
-          ok: true,
-          sessionId: session.id,
-          window: week.window,
-        });
+      handler: async (_req, { send, waitUntil, host, auth }) => {
+        waitUntil(collectWeek(host).then((week) => startWeek(send, week, auth)));
+        return new Response(null, { status: 202 });
       },
     }),
   ],

package/templates/agents-md/bot/instructions.md

@@ -33,7 +33,6 @@ Call `apply_agents` once.
 Paths must be `AGENTS.md` or `*/AGENTS.md`. Short declarative sentences.
 Edit only the stale or missing rules. Keep the existing voice.
 
-An update parks until a person approves the write. The follow-up PR
-opens as a draft.
+The follow-up PR opens as a draft for a person to review.
 
 Reply with `skip` or `update` and the reason.

package/templates/agents-md/bot/tools/apply_agents.ts

@@ -26,7 +26,6 @@ type Write = {
 
 export default defineTool({
   description: "Skip or open an AGENTS.md follow-up PR for this weekly review. Call once.",
-  needsApproval: (input) => input.verdict === "update",
   effect: (input) => (input.verdict === "update" ? "write" : "read"),
   inputSchema: z.discriminatedUnion("verdict", [
     z.object({

package/templates/agents-md/evals/agents.eval.ts

@@ -78,7 +78,7 @@ export default defineEval({
     },
     {
       id: "update-rule",
-      description: "A repeated billing rule parks the AGENTS.md write.",
+      description: "A repeated billing rule opens an AGENTS.md update.",
       async test(t) {
         await t.send(weekly(), {
           workspaceFiles: {
@@ -91,7 +91,7 @@ export default defineEval({
             "week/tree/AGENTS.md.txt": "# API\n\nKeep handlers thin.\n",
           },
         });
-        t.parked();
+        t.succeeded();
         t.calledTool("apply_agents", { input: { verdict: "update" } });
       },
     },

package/templates/demo/bot/channels/queue.ts

@@ -2,7 +2,7 @@ import { defineChannel, POST } from "@cursor/bdk/channels";
 import { parseGitHubPrRef } from "@cursor/bdk/channels/github";
 import { z } from "zod";
 import { startDemo } from "../lib/collect.js";
-import { REPOS, watches } from "../lib/repos.js";
+import { watches } from "../lib/repos.js";
 
 export default defineChannel({
   routes: [
@@ -11,23 +11,13 @@ export default defineChannel({
       bodySchema: z.object({
         pr: z.string().describe("GitHub PR URL or owner/repo#N"),
       }),
-      handler: async (_req, { send, host, body }) => {
+      handler: async (_req, { send, waitUntil, host, body }) => {
         const ref = parseGitHubPrRef(body.pr);
         if (ref === undefined || !watches(`${ref.owner}/${ref.repo}`)) {
-          return Response.json(
-            {
-              ok: false,
-              error: `need a PR URL or owner/repo#N in ${REPOS.join(", ")}`,
-            },
-            { status: 400 },
-          );
+          return new Response(null, { status: 400 });
         }
-        const session = await startDemo(send, host.github, ref);
-        return Response.json({
-          ok: true,
-          sessionId: session.id,
-          pr: ref.label,
-        });
+        waitUntil(startDemo(send, host.github, ref));
+        return new Response(null, { status: 202 });
       },
     }),
   ],

package/templates/grokbot-agents/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+.env
+.env.local
+memory

package/templates/pr-autofixer/bot/channels/drive.ts

@@ -7,30 +7,17 @@ export default defineChannel({
     POST("/", {
       description: "Start PR autofixer on a GitHub PR (same path as the drive_pr tool).",
       bodySchema: driveStartBodySchema,
-      handler: async (req, { send, sessionUrls, host, body }) => {
+      handler: async (_req, { send, host, body }) => {
         const result = await startDrive({
           pr: body.pr,
           hint: body.hint,
           send,
           host,
         });
-
         if (!result.ok) {
-          return Response.json({ error: result.error }, { status: 400 });
+          return new Response(null, { status: 400 });
         }
-
-        return Response.json({
-          pr: result.pr,
-          sessionId: result.sessionId,
-          continuationToken: result.continuationToken,
-          bcId: result.bcId,
-          agentUrl: result.agentUrl,
-          status: result.status,
-          result: result.result,
-          playgroundUrl:
-            result.sessionId === null ? null : sessionUrls(req, result.sessionId).playgroundUrl,
-          mergeConflictReminderId: result.mergeConflictReminderId,
-        });
+        return new Response(null, { status: 202 });
       },
     }),
   ],

package/templates/security-help/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+.env
+.env.local
+memory

package/templates/triage/bot/channels/queue.ts

@@ -1,6 +1,6 @@
 import { defineChannel, POST } from "@cursor/bdk/channels";
 import { z } from "zod";
-import { formatQueuePrompt, isTrackerWebhook, parseQueueEvent } from "../lib/parse-queue-event.js";
+import { formatQueuePrompt, parseQueueEvent } from "../lib/parse-queue-event.js";
 
 export default defineChannel({
   routes: [
@@ -11,29 +11,18 @@ export default defineChannel({
         const parsed = parseQueueEvent(body);
         if (!parsed.ok) {
           if ("ignored" in parsed) {
-            return Response.json({ ok: true, ignored: true });
+            return new Response(null, { status: 202 });
           }
-          return Response.json({ ok: false, error: parsed.error }, { status: 400 });
+          return new Response(null, { status: 400 });
         }
-        const options = {
-          continuationToken: parsed.issue.identifier,
-          admission: "coalesce" as const,
-          title: parsed.issue.title === "" ? undefined : parsed.issue.title,
-        };
-        const prompt = formatQueuePrompt(parsed.issue);
-        if (isTrackerWebhook(body)) {
-          waitUntil(send(prompt, options));
-          return Response.json({
-            ok: true,
-            identifier: parsed.issue.identifier,
-          });
-        }
-        const session = await send(prompt, options);
-        return Response.json({
-          ok: true,
-          sessionId: session.id,
-          identifier: parsed.issue.identifier,
-        });
+        waitUntil(
+          send(formatQueuePrompt(parsed.issue), {
+            continuationToken: parsed.issue.identifier,
+            admission: "coalesce",
+            title: parsed.issue.title === "" ? undefined : parsed.issue.title,
+          }),
+        );
+        return new Response(null, { status: 202 });
       },
     }),
   ],

package/templates/triage/bot/channels/webhook.ts

@@ -21,11 +21,11 @@ export default defineChannel({
           nowMs: Date.now(),
         });
         if (!verified.ok) {
-          return Response.json({ ok: false }, { status: verified.status });
+          return new Response(null, { status: verified.status });
         }
         const parsed = parseQueueEvent(body);
         if (!parsed.ok) {
-          return Response.json({ ok: true, ignored: true });
+          return new Response(null, { status: 202 });
         }
         waitUntil(
           send(formatQueuePrompt(parsed.issue), {
@@ -34,10 +34,7 @@ export default defineChannel({
             title: parsed.issue.title === "" ? undefined : parsed.issue.title,
           }),
         );
-        return Response.json({
-          ok: true,
-          identifier: parsed.issue.identifier,
-        });
+        return new Response(null, { status: 202 });
       },
     }),
   ],

package/templates/triage/bot/lib/parse-queue-event.ts

@@ -26,12 +26,6 @@ export function pinIssueIdentifier(
   return fallback;
 }
 
-export function isTrackerWebhook(body: unknown): boolean {
-  return (
-    isRecord(body) && (typeof body["type"] === "string" || typeof body["webhookEvent"] === "string")
-  );
-}
-
 export function parseQueueEvent(body: unknown): ParseResult {
   if (!isRecord(body)) {
     return { ok: false, error: "unsupported queue event" };