@cursor/bdk 0.2.21 → 0.2.23

package/dist/playground/index.html

@@ -8,8 +8,8 @@
     />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>agent-serve playground</title>
-    <script type="module" crossorigin src="./assets/index-DAlf9lxD.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-BfePgvWh.css">
+    <script type="module" crossorigin src="./assets/index-CD8VRa25.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-BtsbIqV9.css">
   </head>
   <body>
     <div id="root"></div>

package/docs/guides/migrate.md

@@ -24,6 +24,15 @@ Migrate when at least one of these signals is present:
 Stop when none of these is true. An existing `agent/` project root can remain
 in place; BDK still loads it even though current examples use `bot/`.
 
+`bdk migrate` prints `Nothing to migrate.` and exits 0 only when `--dir` shows
+no migration work. The check looks for an `@cursor/july` dependency,
+`architecture: "v1"`, `bot/storage.ts` or `agent/storage.ts`,
+`runtime: "grokbot"`, a literal SCM credential, a `/v1` continuation selector,
+an anonymous reminder, and a `*_MCP_URL` peer connection. When any of those is
+present, or a project file cannot be read, the command starts the agent. It
+does not read the hosted deployment. Run `bdk deployment <slug>` when you still
+need to see whether that copy is on v1.
+
 ## Start the migration
 
 Commit and push the source you want to migrate. `bdk migrate` reads that
@@ -83,6 +92,14 @@ Before merging, confirm the pull request:
   removed. The [GitHub guide](./github.md#other-hosts) explains the named
   form.
 
+- Rewrites each peer call that took its URL from a secret or environment
+  variable, such as `BUILDER_MCP_URL`, to
+  `defineConnection({ agent: "<slug>" })` under `bot/mcp-connections/`
+  (or `agent/mcp-connections/` when the project root is `agent/`).
+  Confirm the slug before you merge. The pull request lists each secret the
+  rewrite left unused, and it leaves a TODO where it could not determine
+  the slug.
+
 - Calls out unsupported behavior and any follow-up needed for reminders,
   schedules, Slack, or MCP connections.
 
@@ -113,10 +130,33 @@ bdk validate --dir .
 bdk deploy --dir . --slug <existing-or-new-slug>
 ```
 
-After the deployment starts, follow the migration skill's cutover checklist
-for Slack, webhook callers, and Cursor-account MCP connections, then verify a
-hosted turn. The [deployment guide](../deployment.md) covers the managed
-hosting workflow.
+When the folder contains more than one agent, deploy each agent folder
+alone. Run `bdk deploy --dir <agent folder>` one time for each agent. One
+`bdk deploy` on the parent folder prints those commands and does not deploy.
+Do not use `bdk deploy --all`. Repeat `bdk slack create --prod` for each
+agent folder. The Slack app slug is the folder name.
+
+When the pull request calls another agent with
+`defineConnection({ agent: "<slug>" })`, deploy the caller and that peer
+on `@cursor/bdk` 0.2.18 or newer. Both deployments must belong to the
+same team, and the caller reaches the peer once the peer deployment is
+running. The connection file is already in the merged source, so unset
+each URL secret the pull request lists after both deploys:
+
+```bash
+bdk secrets unset <slug> NAME
+```
+
+`bdk migrate` prints the steps that follow the first deploy: one deploy per
+agent folder, `bdk slack create --prod --dir <agent-folder>` for each Slack
+agent, `bdk secrets unset` for peer URL secrets the pull request lists, and
+`bdk secrets list` / `bdk secrets set` when the slug is new. Slack setup
+redeploys the deployment by itself. `bdk secrets set` takes effect on the
+next request. Neither step needs another deploy.
+
+After the deployment starts, follow that checklist for Slack, webhook callers,
+peer connections, and secrets, then verify a hosted turn. The
+[deployment guide](../deployment.md) covers the managed hosting workflow.
 
 ## Related
 
@@ -124,4 +164,6 @@ hosting workflow.
   exit status
 - [`bdk-migrate-v2` skill](../../skills/migrate-v2/SKILL.md): the coding
   procedure and complete capability matrix
+- [Peer agents](./agent-to-agent.md): how a deployed caller reaches another
+  agent by slug
 - [Deployment](../deployment.md): deploy and verify the reviewed project

package/docs/reference/cli.md

@@ -533,7 +533,18 @@ bdk migrate [--dir <path>] [--repo <https-url>] [--ref <git-ref>]
 early alpha. It reads a pushed Git ref, starts a Cursor cloud agent with the
 bundled `bdk-migrate-v2` skill, and opens a pull request with the source
 changes. The command waits for the pull request by default and never deploys
-the project or changes deployment secrets.
+the project or changes deployment secrets. When it starts an agent, it prints
+a checklist for the steps after the first deploy: deploy each agent folder,
+create the prod Slack app, unset peer URL secrets, and set secrets a new slug
+still needs.
+
+The command prints `Nothing to migrate.` and exits 0 only when `--dir` shows
+no migration work. That check looks for an `@cursor/july` dependency,
+`architecture: "v1"`, `bot/storage.ts` or `agent/storage.ts`,
+`runtime: "grokbot"`, a literal SCM credential, a `/v1` continuation selector,
+an anonymous reminder, and a `*_MCP_URL` peer connection. When any of those is
+present, or a project file cannot be read, the command starts the agent. It
+does not read the hosted deployment.
 
 | Option | Contract |
 | --- | --- |
@@ -542,7 +553,7 @@ the project or changes deployment secrets.
 | `--ref <git-ref>` | Select the pushed ref for the cloud agent. The CLI infers the current branch when possible. |
 | `--path <agent-path>` | Select the project path relative to the repository root. The CLI infers it from `--dir` when possible. |
 | `--no-wait` | Print the cloud agent URL and return after the agent starts. |
-| `--json` | Print a report with `ok`, `status`, `agentId`, and the cloud agent `url`. A completed migration adds `prUrl`; a blocked or failed migration adds its explanation. |
+| `--json` | Print a report with `ok`, `status`, `agentId`, and the cloud agent `url`. A completed migration adds `prUrl` and `checklist`. A run with nothing to migrate uses `status: "current"` and `message` (no agent started) or `summary` (the agent reported it). A blocked or failed migration adds its explanation. |
 | `--api-key <key>` | Override the Cursor credential. |
 
 Credential resolution follows the normal order: `--api-key`,
@@ -659,8 +670,8 @@ service-account API key with agent access can deploy.
 
 | Option | Contract |
 | --- | --- |
-| `--slug <slug>` | Select one project and set its deployment slug. |
-| `--all` | Deploy every child project under a multi-agent `--dir`. Mutually exclusive with `--slug`. |
+| `--slug <slug>` | Select one project and set its deployment slug. Under a folder of several agents, this deploys that one agent. |
+| `--all` | Deploy every child under a folder of several agents. For a folder of v2 agents, print one deploy command for each agent. |
 | `--team <id>` | Select the Cursor team. |
 | `--repo <https-url>` | Set the source repository. The CLI infers it from the current checkout when possible. HTTPS is required. |
 | `--ref <git-ref>` | Set the source Git ref. The CLI infers the current branch when possible. |
@@ -1052,7 +1063,7 @@ Credential resolution follows this order: `--api-key`, `CURSOR_API_KEY`,
 | `chat`, `session` | Exit `2` for documented option conflicts or missing required input. |
 | `validate` | Exit `1` when any project diagnostic has error severity. |
 | `convert-automation` | Exit `1` for invalid input, authentication, export, or file-write failure. Warnings and dependency-install failure don't change a successful conversion exit. |
-| `migrate` | Exit `0` after starting with `--no-wait` or after the agent opens a pull request. Exit `1` for invalid input, authentication or agent failure, or a completed run without a pull request. |
+| `migrate` | Exit `0` when nothing needs a migration, after starting with `--no-wait`, or after the agent opens a pull request. Exit `1` for invalid input, authentication or agent failure, or a completed run without a pull request. |
 | Other commands | Exit nonzero when validation, authentication, a request, or the requested operation fails. |
 
 ## Related

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/bdk",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "description": "Build, test, and deploy BDK bots and agents as code on Cursor's agent harness.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -335,6 +335,11 @@
   },
   "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",
@@ -364,11 +369,11 @@
     "vitest": "^4.0.18",
     "yaml": "^2.4.2",
     "zustand": "^5.0.9",
-    "@anysphere/agent-store-sync": "1.0.0",
     "@anysphere/agent-exec": "1.0.0",
     "@anysphere/proto": "1.0.0",
+    "@anysphere/context": "1.0.0",
     "@anysphere/ui": "1.0.0",
-    "@anysphere/context": "1.0.0"
+    "@anysphere/agent-store-sync": "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",

package/skills/migrate-v2/SKILL.md

@@ -23,7 +23,21 @@ Migrate when any of these is true:
 - `bdk deployment <slug>` for the hosted copy does not print
   `architecture: v2`.
 
-Stop when none is true.
+Stop when none is true. Your final message must start with
+`Nothing to migrate.` and must name the checks you ran. Open no pull
+request.
+
+`bdk migrate` checks `--dir` before it starts an agent. It starts an
+agent when it finds any of these: an `@cursor/july` dependency or
+import, `architecture: "v1"`, `bot/storage.ts` or `agent/storage.ts`,
+`runtime: "grokbot"`, a literal or `() => process.env` SCM credential,
+`continuation: ".../v1"`, an anonymous reminder `run` or function
+`until`, or a `defineConnection` whose URL comes from a `*_MCP_URL`
+secret. When none of those is present it prints `Nothing to migrate.`
+and exits. When it cannot read a file, it starts the agent. It does
+not run `bdk deployment`. A hosted copy can still be on v1 after the
+source has moved. Check with `bdk deployment <slug>`, and deploy when
+that output does not show `architecture: v2`.
 
 ## Know what changes
 
@@ -66,12 +80,14 @@ ends. That model changes code in three places:
 | 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. |
 | Session, tool, and MCP APIs on the deployment URL | Not reachable |
+| Another BDK agent reached through a deployment URL secret | Not supported. Declare `defineConnection({ agent: "<slug>" })`. Both agents must be team-owned and deployed on `@cursor/bdk` 0.2.18 or newer. |
 | `--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 Slack tool-approval buttons, `mcp oauth --store`, or an
+credentials, secret reads, and peer calls that use a URL secret. Stop and
+ask before migrating an agent 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.
 
@@ -177,9 +193,74 @@ still loads.
 
 7. **Move secret reads.** Replace module-scope `process.env.NAME` reads
    with reads inside the function that uses them. Give MCP connections a
-   `${NAME}` header or env template instead.
+   `${NAME}` header or env template instead. A URL that points at another
+   BDK agent's deployment is not one of those secrets. Step 8 replaces
+   that connection, including a URL you templated here.
+
+8. **Rewrite peer calls that use a URL secret.** Do this in the migration
+   pull request. The deployment URL does not serve MCP, so a connection
+   left on that URL fails after deploy.
+
+   Treat the call as a peer when its URL comes from a `*_MCP_URL` secret
+   or a similar name, a `${NAME}` template, `process.env.NAME`, or a
+   string built from a deployment URL or slug, and the target is another
+   BDK agent. Leave a third-party MCP server as a URL connection and
+   apply step 7 to its secrets.
+
+   Use a slug only when the repo states it: the URL path, a `--slug`
+   value, a sibling directory that deploy would use as the slug, or a
+   comment that names the deployment. A secret name is a hint. Use
+   `BUILDER_MCP_URL` as `builder` only when something else in the repo
+   confirms that slug. When nothing confirms it, keep the URL connection
+   and add a TODO that names the secret and asks for the slug. Name that
+   TODO in the pull request body.
 
-8. **Stop answering from HTTP routes.** A custom route that returned
+   ```ts
+   // before (v1), agent/mcp-connections/builder.ts
+   import { defineConnection } from "@cursor/bdk/connections";
+
+   export default defineConnection({
+     url: process.env.BUILDER_MCP_URL,
+     headers: { authorization: `Bearer ${process.env.BUILDER_TOKEN}` },
+   });
+
+   // after (v2)
+   import { defineConnection } from "@cursor/bdk/connections";
+
+   export default defineConnection({
+     agent: "builder",
+     description: "Ask the builder agent to handle this work.",
+   });
+   ```
+
+   `agent` is the peer's lowercase deployment slug. Keep an existing
+   connection file in place. When the project has no connection file,
+   add `bot/mcp-connections/<name>.ts`, or
+   `agent/mcp-connections/<name>.ts` when the project root is `agent/`.
+   Use `host-connections/` only when host code calls the peer and the
+   model must not see it. The filename is the connection name.
+
+   Hosting authenticates the peer call. Remove the URL, its headers, and
+   any token this call was the only reader of. Point host code that
+   called the deployment URL at
+   `ctx.host.mcp.callTool("<name>", "ask", { message })`. The peer
+   project needs no matching file. Do not edit a peer that sits outside
+   this folder.
+
+   Remove the unused URL secret from code and from `hosting.secretNames`
+   on `defineAgent`, and from an extension `hosting` block that declares
+   it. Leave every secret something else still reads.
+
+   Do not change deployment secrets, and do not run `bdk secrets unset`.
+   In the pull request body, list each secret this step stopped using,
+   with the command `bdk secrets unset <slug> NAME`, so the user can
+   unset it after both agents are deployed.
+
+   Both agents must be team-owned and deployed with `@cursor/bdk` 0.2.18
+   or newer before the connection resolves. This pull request does not
+   deploy them.
+
+9. **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. Return `new Response(null, { status: 202 })` so
    local runs match the hosted response.
@@ -206,14 +287,29 @@ Run the project's own typecheck and tests.
 ## Open the pull request
 
 Describe each removed or changed behavior, each unsupported row the
-agent touched, and the deploy steps. Do not deploy from the pull request
-branch.
+agent touched, and the deploy steps. For each peer URL you rewrote, name
+the slug and the connection file. List every secret name the rewrite
+left unused, and the `bdk secrets unset <slug> NAME` command for it.
+Name each TODO whose slug you could not determine. Do not deploy from
+the pull request branch, and do not change deployment secrets.
+
+Copy this post-merge checklist into the pull request body. One
+`bdk deploy --dir <agent-folder>` per agent. Do not use `bdk deploy --all`.
+Then `bdk slack create --prod --dir <agent-folder> [--team <team-id>]`
+for each agent that uses Slack. Then `bdk secrets unset <slug> NAME` for
+each unused peer URL secret, and `bdk secrets list <slug>` plus
+`bdk secrets set <slug> NAME` when the slug is new. Do not tell the user
+to deploy again after Slack setup or after `bdk secrets set`. The server
+redeploys after Slack setup, and a secret is injected on the next
+request.
 
 ## Deploy after merge
 
 Deploy from a pushed ref. `bdk deploy` reads Git and never uploads the
 working tree.
 
+When the folder contains one agent:
+
 ```bash
 bdk login
 bdk validate --dir .
@@ -222,6 +318,31 @@ bdk deploy --dir . --slug <existing-slug> \
   --allow-domain <domain>
 ```
 
+When the folder contains more than one agent, deploy each agent alone.
+Run the command one time for each agent folder. A `bdk deploy` on the
+parent folder prints those commands and does not deploy. Do not run
+`bdk deploy --all`. Repeat `bdk slack create --prod` for each agent
+folder too.
+The app slug is the folder name, so that name must match the deployed
+slug.
+
+```bash
+bdk deploy --dir <agent-folder> --slug <that-agent-slug> \
+  --cursor-events-repo <owner/repo> \
+  --allow-domain <domain>
+```
+
+When this migration declares `defineConnection({ agent: "<slug>" })`,
+deploy the caller and the peer. Both deployments must be team-owned and
+must run `@cursor/bdk` 0.2.18 or newer. The connection file is already
+in the merged source. The caller reaches the peer after the peer
+deployment is running. The peer needs no matching file. After both
+deploys are running, unset each URL secret the pull request lists:
+
+```bash
+bdk secrets unset <slug> NAME
+```
+
 Pass every `--cursor-events-repo` and `--allow-domain` value the v1
 deployment used. Domains already in `hosting.egressDomains` need no
 flag. Print only those two fields, because the full output holds
@@ -252,10 +373,18 @@ After the deploy is running:
 
 - Store the alias token the deploy prints. Point every webhook sender
   and HTTP caller at the new alias URL.
-- For Slack, run `bdk slack create --prod --dir .`, then deploy again so
-  the deployment binds the workspace. The new app is a different bot, so
-  invite it to the channels the old one joined. The copied v1 Slack
-  secrets go unused.
+- For Slack, log in as a person. A team service-account key cannot
+  create the app. Run `bdk slack create --prod --dir <agent-folder>`
+  once per agent (`--team <team-id>` selects the Cursor team that owns
+  the deployment). The server redeploys by itself. Do not deploy again
+  for Slack. The new app is a different bot. Uninstall the old Slack app
+  and invite the new bot to the channels the old one joined. The copied
+  v1 Slack secrets go unused.
+- For secrets, a same-slug deploy copies the v1 secrets. A new slug
+  needs `bdk secrets set <slug> NAME`. Check with
+  `bdk secrets list <slug> [--team <team-id>]`. `deploy` warns when a
+  declared secret is unset. A secret is injected on the next request.
+  Do not deploy again after `bdk secrets set`.
 - Reconnect Cursor-account MCP servers from **Deployed Agents** in the
   dashboard.
 - Start a turn with `bdk run --prod --slug <slug> --message "..."`. It

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

@@ -51,12 +51,15 @@ export function patternMatchesFile(
   const literalPrefix = normalizedPattern.replace(/\*+$/, "");
   if (normalizedPattern.endsWith("**") && !hasComplexGlob(literalPrefix)) {
     const prefix = literalPrefix.replace(/\\(.)/g, "$1").replace(/\/+$/, "");
-    if (normalizedPath === prefix || (prefix !== "" && normalizedPath.startsWith(`${prefix}/`))) {
+    if (prefix !== "" && normalizedPath.startsWith(`${prefix}/`)) {
       return true;
     }
     if (literalPrefix === "" || literalPrefix.endsWith("/")) {
       return false;
     }
+    if (normalizedPath === prefix) {
+      return true;
+    }
     if (patternIsRooted && !literalPrefix.includes("/") && normalizedPath.includes("/")) {
       return false;
     }