@cursor/bdk 0.2.8 → 0.2.9

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-MijLHTbB.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-DPKLl4C_.css">
+    <script type="module" crossorigin src="./assets/index-Co4CUVTQ.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-C1g_PTTZ.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/bdk",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "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/migrate-v2/SKILL.md

@@ -0,0 +1,223 @@
+---
+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.
+- 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 |
+| GitLab and Bitbucket channels on Cursor hosting | Rolling out. Trial under a new slug first. |
+| 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, 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. **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.
+
+7. **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. `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.