@cursor/bdk 0.2.8 → 0.2.10

package/docs/reference/cli.md

@@ -34,6 +34,7 @@ provide their own `help` subcommands.
 | [`docs`](#docs) | Serve the documentation bundled with `@cursor/bdk` |
 | [`init`](#init) | Scaffold a BDK project |
 | [`convert-automation`](#convert-automation) | Export a Cursor Automation into a project |
+| [`migrate`](#migrate) | Move an early-alpha project to architecture v2 through a pull request |
 | [`install-skills`](#install-skills) | Refresh the bundled coding-agent skills |
 | [`info`](#info) | Print the discovered project surface |
 | [`validate`](#validate) | Check project diagnostics and set the exit status |
@@ -470,6 +471,35 @@ authentication, export, and file-write failures exit nonzero.
 See [Convert a Cursor Automation](../guides/convert-automation.md) for the
 generated project and features that need manual review.
 
+### Migrate an early-alpha project {#migrate}
+
+```text
+bdk migrate [--dir <path>] [--repo <https-url>] [--ref <git-ref>]
+  [--path <agent-path>] [--no-wait] [--json] [--api-key <key>]
+```
+
+`migrate` applies only to projects deployed on architecture v1 during the BDK
+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.
+
+| Option | Contract |
+| --- | --- |
+| `--dir <path>` | Select the local BDK project. The default is the current directory. |
+| `--repo <https-url>` | Select the source repository. The CLI infers the current checkout's origin when possible. |
+| `--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. |
+| `--api-key <key>` | Override the Cursor credential. |
+
+Credential resolution follows the normal order: `--api-key`,
+`CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`, `CURSOR_SERVICE_ACCOUNT_KEY`, then
+the stored `bdk login` credential. See
+[Migrate an early-alpha project](../guides/migrate.md) for detection, pull
+request review, and deployment cutover.
+
 ### Install coding-agent skills {#install-skills}
 
 ```text
@@ -504,6 +534,13 @@ bdk validate [--dir <path>]
 when any diagnostic has error severity. Use it instead of `info --json` when a
 script needs validation status.
 
+Hosting checks run here too. On architecture v2 (the default), a
+`githubChannel` credential or a GitLab or Bitbucket `webhookSecret` written
+as a literal or a `() => process.env.NAME` getter is an error whose message
+quotes the `{ secretName: "NAME" }` form to use instead. A project that still
+sets `architecture: "v1"` gets the same finding as a warning, so run
+`validate` before removing the pin to list what the migration must rename.
+
 ### Print a deployment manifest {#manifest}
 
 ```text
@@ -904,6 +941,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. |
 | Other commands | Exit nonzero when validation, authentication, a request, or the requested operation fails. |
 
 ## Related
@@ -913,3 +951,4 @@ Credential resolution follows this order: `--api-key`, `CURSOR_API_KEY`,
 - [Evals](./evals.md)
 - [HTTP API](./http-api.md)
 - [Deployment](../deployment.md)
+- [Early-alpha migration](../guides/migrate.md)

package/docs/troubleshooting.md

@@ -57,6 +57,7 @@ Match the visible symptom below.
 
 | What you see | What to do |
 | --- | --- |
+| `validate` or `deploy` reports `architecture "v2" requires a named secret` | A `githubChannel` credential or a GitLab or Bitbucket `webhookSecret` is a literal or a getter. Replace it with the quoted `{ secretName: "NAME" }` and set the value with `bdk secrets set <slug> NAME`. See [Other hosts](./guides/github.md#other-hosts). |
 | Local changes do not appear after deploy | `deploy` reads a pushed Git ref, not the working tree. Commit and push the intended ref, then deploy it again. |
 | The deployment never becomes running | Run `bdk deployment <slug>`, then act on the reported build or startup error. |
 | A secret or egress change has no effect | Confirm the name with `secrets list`, verify the `hosting` block exists on the pushed ref, and follow the CLI or dashboard prompt to redeploy. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/bdk",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Build, test, and deploy BDK bots and agents as code on Cursor's agent harness.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {

package/skills/debug/SKILL.md

@@ -36,6 +36,7 @@ Local `bdk serve`. Hosted start or health failures:
 | Slack `channel idle … missing credentials` | Expected. `slack doctor --prefix <PREFIX>`. |
 | Immediate API-key error | Model turns need a Cursor credential (`CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE`, then `CURSOR_SERVICE_ACCOUNT_KEY`, then `bdk login`). |
 | `validate` clean, CI typecheck fails | tsx skipped types. JSON-shaped returns; `type` not `interface`. |
+| `validate`: `architecture "v2" requires a named secret` | Getter or literal SCM credential. Use the quoted `{ secretName: "NAME" }`; `secrets set <slug> NAME` after deploy. |
 
 Count `action.result` by `toolName` before blaming latency.
 `turn.failed` + `"turn interrupted"` is a follow-up or stop, not a

package/skills/github/SKILL.md

@@ -71,6 +71,29 @@ Without `cursorAccount`, outbound calls prefer App installation
 tokens (`GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY`). Local tests
 can use `GITHUB_TOKEN` / `gh auth login`.
 
+## Credentials
+
+Name secrets; never read them. Each `credentials` field
+(`webhookSecret`, `token`, `installationToken`, `appId`,
+`privateKey`) takes `{ secretName: "NAME" }`: the env var locally,
+the deployment secret of that name on Cursor hosting. The platform
+verifies `X-Hub-Signature-256` against the named secret before any
+compute starts and `deploy` warns when a named secret is unset.
+
+```ts
+credentials: {
+  webhookSecret: { secretName: "GITHUB_WEBHOOK_SECRET" },
+  appId: { secretName: "GITHUB_APP_ID" },
+  privateKey: { secretName: "GITHUB_APP_PRIVATE_KEY" },
+},
+```
+
+A literal or `() => process.env.X` getter fails `bdk validate` on
+architecture v2 (the default) with `requires a named secret`; the
+message quotes the `{ secretName }` to use. Omit a field to keep its
+default name; a numeric `appId` is allowed. Only `architecture: "v1"`
+still accepts getters, and `validate` warns there.
+
 The Cursor stream is metadata, not full webhook bodies. Re-read
 the PR from GitHub.
 

package/skills/migrate-v2/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: bdk-migrate-v2
+description: >-
+  Migrate a BDK project from hosted architecture v1 to v2: upgrade the
+  package, remove v1-only code, and redeploy. Applies only to projects
+  built during the early alpha, which depend on @cursor/july, run the
+  agent-sdk CLI, or set architecture "v1".
+alwaysApply: false
+---
+
+# Migrate a BDK agent to architecture v2
+
+This skill applies only to projects built during the BDK early alpha,
+when hosted agents ran on architecture v1. Projects that never deployed
+on v1 already run on v2 and need nothing here.
+
+## Confirm the project needs it
+
+Migrate when any of these is true:
+
+- `package.json` depends on `@cursor/july`.
+- `agent/agent.ts` sets `architecture: "v1"`.
+- `bdk deployment <slug>` for the hosted copy does not print
+  `architecture: v2`.
+
+Stop when none is true.
+
+## Know what changes
+
+A v1 deployment kept one long-lived process per agent. On v2 the platform
+starts a short-lived runtime when an event arrives, keeps sessions, KV,
+and files in Cursor-managed storage, and stops the runtime when the work
+ends. That model changes code in three places:
+
+- Module-scope state and files written outside `ctx.host.files` vanish
+  between events. Keep durable state in `ctx.host.kv` or `ctx.host.files`.
+- Secrets arrive per request, after modules load. Read `process.env`
+  inside the handler, tool, or callback that needs the value.
+- SCM webhook channels name their secrets instead of reading them.
+  `githubChannel({ credentials })` fields and the `gitlabChannel` /
+  `bitbucketChannel` `webhookSecret` take `{ secretName: "NAME" }`, so
+  the platform can verify the provider signature at ingestion and flag
+  an unset deployment secret before the first API call. A literal or a
+  `() => process.env.X` getter is a validation error on v2.
+- The deployment URL serves only routes your channels declare. It
+  answers `202` at once and runs the handler afterwards, so a route
+  cannot send a response body back to its caller.
+
+## Check what v2 supports
+
+| Capability | On v2 |
+| --- | --- |
+| Slack mentions, DMs, and channel posts | Supported. Provision a new Slack app after the first v2 deploy. |
+| GitHub channels, including `cursorAccount` | Supported. Every `credentials` field must be `{ secretName }`. |
+| GitLab and Bitbucket channels on Cursor hosting | Rolling out. Trial under a new slug first. `webhookSecret` must be `{ secretName }`. |
+| Custom HTTP channel routes | Supported. The caller gets `202`, not the handler's response. |
+| Tools, skills, subagents, MCP connections | Supported |
+| `ctx.host.kv`, `ctx.host.files`, artifacts | Supported, in platform-selected storage |
+| Reminders with `prompt` or a named `handler` | Supported |
+| Secrets and `hosting.egressDomains` | Supported. Same-slug deploys copy v1 secrets. |
+| `persistent: true` and `hosting.image` | Supported, one persistent deployment per team |
+| 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. |
+| 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`. |
+| 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.
+
+## Update the project
+
+Keep the diff to the migration. Leave an `agent/` root in place; it
+still loads.
+
+1. **Upgrade the package.** Replace `@cursor/july` with the latest
+   `@cursor/bdk` in `package.json`, then install with the project's
+   package manager:
+
+   ```bash
+   npm uninstall @cursor/july
+   npm install @cursor/bdk@latest
+   ```
+
+   Commit the lockfile the install writes, since deploys build from Git.
+   Rewrite every `@cursor/july` import to `@cursor/bdk`; subpaths such as
+   `/channels/slack`, `/evals`, and `/reminders` keep their names. Replace
+   `agent-sdk` with `bdk` in scripts, CI jobs, and READMEs.
+
+   The new types are stricter. `ctx.session.continuationKey` is
+   `string | null`, so guard with `typeof key === "string"`, not
+   `!== undefined`. Typecheck with `npx tsc --noEmit` even when the
+   project has no script for it.
+
+2. **Drop the v1 opt-in.** Delete `architecture: "v1"` from
+   `defineAgent`. v2 is the default, so do not add `architecture: "v2"`.
+
+3. **Delete `agent/storage.ts`.** v2 selects storage itself, and
+   `ctx.host.kv` calls keep working against it. Data in a backend you
+   run stays there. Data in Cursor-hosted storage is deleted with the v1
+   deployment, so export what the agent still needs before deploying.
+
+4. **Name inline reminders.** Move each inline `run` into
+   `agent/reminders/<name>.ts` and pass that module as `handler` with
+   serializable `args`. A named handler takes no `until`. Move a function
+   `until` check into the handler and call `cancel()` when it holds.
+
+   ```ts
+   // agent/reminders/ci_recheck.ts
+   import { defineReminder } from "@cursor/bdk/reminders";
+
+   export default defineReminder({
+     async run({ args, followup }) {
+       await followup({ message: `Recheck CI on ${String(args.headSha)}` });
+       return { action: "delivered" };
+     },
+   });
+   ```
+
+   ```ts
+   // agent/tools/watch_ci.ts, inside execute
+   await ctx.host.reminders?.create({
+     purpose: "ci_recheck",
+     channelId: ctx.session.channelId,
+     continuationToken: key,
+     delay: "2h",
+     handler: ciRecheck, // import ciRecheck from "../reminders/ci_recheck.js"
+     args: { headSha },
+   });
+   ```
+
+5. **Rewrite `/v1` continuation selectors.** Delete an explicit
+   `continuation: "<kind>.<scope>/v1"` on a channel so v2 picks its
+   default, or change the suffix to `/v2`. By default, GitHub PR events,
+   Slack threads, and deployment events still continue one session per
+   PR, thread, or deployment.
+
+6. **Name SCM channel credentials.** Replace every literal and
+   `() => process.env.NAME` getter in `githubChannel({ credentials })`
+   with `{ secretName: "NAME" }`, and do the same for the `webhookSecret`
+   of `gitlabChannel` and `bitbucketChannel`. Keep the name the getter
+   read; the channel reads that environment variable locally and the
+   deployment secret of that name on Cursor hosting. A field you omit
+   keeps its default name (`GITHUB_WEBHOOK_SECRET`, `GITHUB_TOKEN`,
+   `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`), a numeric `appId` stays a
+   number, and `cursorAccount` needs no credentials.
+
+   ```ts
+   // before (v1)
+   credentials: {
+     webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET,
+     appId: () => process.env.GITHUB_APP_ID,
+     privateKey: () => process.env.GITHUB_APP_PRIVATE_KEY,
+   },
+
+   // after (v2)
+   credentials: {
+     webhookSecret: { secretName: "GITHUB_WEBHOOK_SECRET" },
+     appId: { secretName: "GITHUB_APP_ID" },
+     privateKey: { secretName: "GITHUB_APP_PRIVATE_KEY" },
+   },
+   ```
+
+   `bdk validate` lists each field still in the old shape. While
+   `architecture: "v1"` is set the finding is a warning, so you can run
+   it before step 2 to see the full list; after step 2 the same finding
+   is an error and blocks `deploy`. Do not set the values: a same-slug
+   deploy copies the v1 secrets, and a new slug takes
+   `bdk secrets set <new-slug> NAME` after the deploy.
+
+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.
+
+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.
+
+## Verify locally
+
+Run the project's installed CLI. Prefix each command with `npx` when
+`bdk` is not on `PATH`.
+
+```bash
+bdk validate --dir .
+bdk info --dir . --json
+bdk run --dir . --message "<a representative request>"
+bdk eval --dir .
+```
+
+Fix every validation error, but never change `runtime` to pass
+validation; stop and report instead. An error ending in `requires a
+named secret` names a channel credential step 6 missed; it quotes the
+`{ secretName }` value to use. `run` and `eval` need a Cursor
+credential. When none is set, skip them and say so in the pull request.
+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.
+
+## Deploy after merge
+
+Deploy from a pushed ref. `bdk deploy` reads Git and never uploads the
+working tree.
+
+```bash
+bdk login
+bdk validate --dir .
+bdk deploy --dir . --slug <existing-slug> \
+  --cursor-events-repo <owner/repo> \
+  --allow-domain <domain>
+```
+
+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
+credentials:
+
+```bash
+bdk deployment <slug> --json | jq '{cursorEventRepos, egressAllowedDomains}'
+```
+
+Choose a cutover before you deploy:
+
+- **Same slug.** One command, and it can't be undone. The deploy copies
+  the v1 secrets, switches traffic once v2 is running, then deletes the
+  v1 deployment along with its Cursor-hosted sessions, KV, files, and
+  eval runs. Slack and webhook traffic stops until you finish the steps
+  below. If the command reports that same-slug replacement is
+  unavailable, use a new slug.
+- **New slug.** v1 keeps serving while you test. Set secrets with
+  `bdk secrets set <new-slug> NAME`. Both deployments act on events from
+  the same repositories, so point the trial at a test repository with
+  `--cursor-events-repo`. Then move senders over and run
+  `bdk delete <old-slug>`, which deletes v1's hosted data the same way.
+
+Prefer a new slug when the agent serves Slack, receives webhooks, or
+keeps data in `ctx.host.kv`.
+
+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.
+- 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>`.
+
+The [deploy skill](../deploy/SKILL.md) covers deploys with an attached
+service account.