@cursor/bdk 0.2.8 → 0.2.10

package/dist/docs/llms-full.txt

@@ -132,6 +132,8 @@ works; a measured climb proves it works better on fixed inputs.
 
 ## Related
 
+- [Early-alpha migration](/docs/guides/migrate.md): hand an architecture v1
+  migration to `bdk migrate` or the bundled coding-agent skill
 - [Quickstart](/docs/quickstart.md): build the first agent manually
 - [Evals](/docs/evals.md): protect behavior with regression cases
 - [Hillclimbing](/docs/hillclimbing.md): run one measured improvement round
@@ -231,6 +233,11 @@ loading sees nothing. Read a secret inside the handler, tool, or callback
 that needs it, and give an MCP connection its credential as a `${NAME}`
 template, which resolves when the connection opens. See
 [credentials in headers and env](/docs/reference/connections.md#credentials-in-headers-and-env).
+SCM webhook channels go one step further and name their secrets in the
+channel definition, as `{ secretName: "GITHUB_WEBHOOK_SECRET" }`, so the
+platform can verify each delivery's signature before any compute starts.
+`validate` rejects a literal or getter there. The
+[GitHub guide](/docs/guides/github.md#other-hosts) shows the named form.
 
 Enter egress hosts without schemes or paths. An HTTPS host needs no port;
 add one, as `clickhouse.example.com:9440`, only for a protocol the proxy
@@ -371,6 +378,8 @@ for a local conversation.
 
 ## Related
 
+- [Early-alpha migration](/docs/guides/migrate.md): move a hosted architecture
+  v1 project to v2 through a reviewed pull request
 - [CLI reference](/docs/reference/cli.md#deploy): inspect, update, stop,
   delete, and rotate deployments
 - [GitHub](/docs/guides/github.md): Cursor-event repositories and direct
@@ -1045,7 +1054,7 @@ and allowed repositories. Data Center also needs its REST API base:
 ```ts
 export default bitbucketChannel({
   repos: ["PLATFORM/api"],
-  webhookSecret: () => process.env.BITBUCKET_WEBHOOK_SECRET,
+  webhookSecret: { secretName: "BITBUCKET_WEBHOOK_SECRET" },
   token: () => process.env.BITBUCKET_TOKEN ?? "",
   apiBaseUrl: "https://bitbucket.example.com/rest/api/1.0",
 });
@@ -1056,6 +1065,14 @@ loopback-only. Setting it admits deliveries signed with the matching
 repository-hook secret; `token` authorizes the API reads and writes in
 the examples.
 
+Name the secret rather than reading it. Locally the channel reads that
+environment variable, and on Cursor hosting the platform verifies
+`X-Hub-Signature` with the deployment secret of that name at ingestion,
+so an unsigned or mis-signed delivery gets a `401` before any compute
+starts. `architecture: "v2"` requires the named form and `bdk validate`
+rejects a literal or `() => process.env.X` getter there; set the value
+with `bdk secrets set <slug> BITBUCKET_WEBHOOK_SECRET`.
+
 Register the repository webhook at
 `https://<your-host>/<slug>/v1/channels/bitbucket` with the same secret.
 For Bitbucket Cloud, omit `apiBaseUrl`.
@@ -1696,8 +1713,8 @@ export default githubChannel({
     apiBaseUrl: "https://github.example.com/api/v3",
   },
   credentials: {
-    token: () => process.env.GITHUB_TOKEN,
-    webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET,
+    token: { secretName: "GITHUB_TOKEN" },
+    webhookSecret: { secretName: "GITHUB_WEBHOOK_SECRET" },
   },
 });
 ```
@@ -1709,8 +1726,24 @@ Server with saved fixtures.
 
 Prefer event pull on github.com. Use the channel route directly when
 you already terminate GitHub webhooks yourself. Set a webhook secret on
-both sides. The [Webhooks guide](/docs/guides/webhooks.md) covers the shared
-mechanism.
+both sides and name it, as above, rather than reading it: locally the
+channel reads that environment variable, and on Cursor hosting the
+platform verifies `X-Hub-Signature-256` with the deployment secret of
+that name at ingestion, so an unsigned or mis-signed delivery gets a
+`401` back to GitHub before any compute starts. A literal or function
+value keeps verification inside the handler only. The
+[Webhooks guide](/docs/guides/webhooks.md) covers the shared mechanism.
+
+Name the API credentials the same way. Every `credentials` field —
+`token`, `installationToken`, `appId`, `privateKey`, `webhookSecret` —
+takes `{ secretName: "NAME" }`: locally the channel reads that
+environment variable, and on Cursor hosting the deployment secret of
+that name. `deploy` then lists the names the agent expects and warns
+about any that are not set yet, before the first API call fails inside
+the guest. `architecture: "v2"` requires the named form (a numeric
+`appId` is configuration and stays allowed); omitting a field keeps its
+env fallback. `architecture: "v1"` still accepts literals and
+`() => process.env.X` getters.
 
 ## Related
 
@@ -1979,7 +2012,7 @@ self-managed host:
 ```ts
 export default gitlabChannel({
   projects: ["acme/platform"],
-  webhookSecret: () => process.env.GITLAB_WEBHOOK_SECRET,
+  webhookSecret: { secretName: "GITLAB_WEBHOOK_SECRET" },
   token: () => process.env.GITLAB_TOKEN ?? "",
   apiBaseUrl: "https://gitlab.example.com/api/v4",
 });
@@ -1990,6 +2023,14 @@ loopback-only. Setting it admits deliveries that carry the matching
 project-hook secret; `token` authorizes the API reads and writes in the
 examples.
 
+Name the secret rather than reading it. Locally the channel reads that
+environment variable, and on Cursor hosting the platform compares
+`X-Gitlab-Token` with the deployment secret of that name at ingestion,
+so a delivery with the wrong token gets a `401` before any compute
+starts. `architecture: "v2"` requires the named form and `bdk validate`
+rejects a literal or `() => process.env.X` getter there; set the value
+with `bdk secrets set <slug> GITLAB_WEBHOOK_SECRET`.
+
 Register the project webhook at
 `https://<your-host>/<slug>/v1/channels/gitlab` with the same secret.
 For GitLab.com, omit `apiBaseUrl`.
@@ -2883,6 +2924,133 @@ caller needs a different downstream identity.
 
 ---
 
+Source: /docs/guides/migrate.md
+
+# Migrate an early-alpha project to architecture v2
+
+Use this guide only for projects deployed during the Grok Bot Development Kit
+(BDK) early alpha. Projects that never deployed on architecture v1 already use
+v2 and need no migration.
+
+## Check whether your project needs migration
+
+Migrate when at least one of these signals is present:
+
+- `package.json` depends on the legacy early-alpha package `@cursor/july`.
+
+- A script or CI job runs the legacy early-alpha `agent-sdk` binary.
+
+- `agent/agent.ts` sets `architecture: "v1"`.
+
+- `bdk deployment <slug>` does not print `architecture: v2`.
+
+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/`.
+
+## Start the migration
+
+Commit and push the source you want to migrate. `bdk migrate` reads that
+pushed Git ref, starts a Cursor cloud agent with the bundled migration skill,
+and waits for the agent to open a pull request. It does not deploy the project.
+
+```bash
+bdk login
+bdk migrate --dir .
+```
+
+Inside a checkout, the command infers the repository, current ref, and project
+path. Pass them when you need to target a different pushed source:
+
+```bash
+bdk migrate \
+  --dir ./bots/triage \
+  --repo https://github.com/acme/agents \
+  --ref migrate-triage-v2 \
+  --path bots/triage
+```
+
+Use `--no-wait` to print the cloud agent URL and return while it works. Use
+`--json` for machine-readable status. The
+[CLI reference](/docs/reference/cli.md#migrate) covers every flag, output, and
+exit status.
+
+## Use the coding-agent skill directly
+
+You can instead ask a coding agent working in the project checkout to follow
+the bundled
+[`bdk-migrate-v2` skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/migrate-v2/SKILL.md). The skill owns the
+code changes, capability checks, local verification, and deployment handoff.
+
+> Follow the `bdk-migrate-v2` skill for this project. Open one pull request
+> with the migration, but do not deploy it or change deployment secrets.
+
+If the project depends on a v1 capability without a supported v2 path, the
+skill tells the coding agent to stop and name the blocker instead of removing
+the behavior.
+
+## Review the pull request
+
+Before merging, confirm the pull request:
+
+- Uses `@cursor/bdk` and `bdk`, and removes the v1 architecture opt-in.
+
+- Moves durable state to `ctx.host.kv` or `ctx.host.files`, reads secrets
+  inside the handler that needs them, and accounts for hosted HTTP routes
+  returning `202`.
+
+- Names SCM channel secrets instead of reading them: every
+  `githubChannel({ credentials })` field and the GitLab or Bitbucket
+  `webhookSecret` is `{ secretName: "NAME" }`. `bdk validate` reports each
+  field still written as a literal or `() => process.env.NAME` getter, as a
+  warning while `architecture: "v1"` is set and as an error once it is
+  removed. The [GitHub guide](/docs/guides/github.md#other-hosts) explains the named
+  form.
+
+- Calls out unsupported behavior and any follow-up needed for reminders,
+  schedules, Slack, or MCP connections.
+
+- Reports the validation, type checks, tests, and credential-dependent checks
+  it ran or handed off.
+
+The migration pull request should change source only. Deploy after it merges.
+
+## Choose a cutover
+
+| Cutover | What happens | Choose it when |
+| --- | --- | --- |
+| Same slug | The v2 deployment copies the v1 secrets and replaces v1 after it starts. The cutover cannot be undone, and it deletes v1's hosted sessions, KV, files, and eval runs. | A service interruption and an empty v2 state are acceptable. |
+| New slug | The v1 deployment keeps serving while you configure and test v2. Move senders to the new URL, then delete the old deployment. | You use Slack, webhooks, or hosted state, or want a staged cutover. |
+
+Prefer a new slug for Slack, webhooks, or data in `ctx.host.kv`. Point the trial
+at a test repository so both deployments do not act on the same source-control
+events. If the CLI reports that same-slug replacement is unavailable, use a
+new slug.
+
+## Deploy after merge
+
+Deploy from the merged, pushed ref. Reuse every `--cursor-events-repo` and
+`--allow-domain` value from the v1 deployment.
+
+```bash
+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](/docs/deployment.md) covers the managed
+hosting workflow.
+
+## Related
+
+- [CLI reference](/docs/reference/cli.md#migrate): migration flags, output, and
+  exit status
+- [`bdk-migrate-v2` skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/migrate-v2/SKILL.md): the coding
+  procedure and complete capability matrix
+- [Deployment](/docs/deployment.md): deploy and verify the reviewed project
+
+---
+
 Source: /docs/guides/opentelemetry.md
 
 # Observe an agent with OpenTelemetry
@@ -4653,6 +4821,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 |
@@ -5089,6 +5258,35 @@ authentication, export, and file-write failures exit nonzero.
 See [Convert a Cursor Automation](/docs/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](/docs/guides/migrate.md) for detection, pull
+request review, and deployment cutover.
+
 ### Install coding-agent skills {#install-skills}
 
 ```text
@@ -5123,6 +5321,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
@@ -5523,6 +5728,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
@@ -5532,6 +5738,7 @@ Credential resolution follows this order: `--api-key`, `CURSOR_API_KEY`,
 - [Evals](/docs/reference/evals.md)
 - [HTTP API](/docs/reference/http-api.md)
 - [Deployment](/docs/deployment.md)
+- [Early-alpha migration](/docs/guides/migrate.md)
 
 ---
 
@@ -8409,6 +8616,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](/docs/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/dist/docs/llms.txt

@@ -37,6 +37,7 @@
 - [Self-improvement](/docs/guides/improve.md): Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate.
 - [Jev](/docs/guides/jev.md): Use typed Jev decisions to filter findings, route pull requests, and gate review actions.
 - [Host MCP OAuth](/docs/guides/mcp-oauth.md): Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent.
+- [Migrate an early-alpha project](/docs/guides/migrate.md): Move a hosted BDK architecture v1 project to v2 through a reviewed pull request.
 - [OpenTelemetry](/docs/guides/opentelemetry.md): Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry.
 - [Slack](/docs/guides/slack.md): Wake your agent from mentions, DMs, and watched posts, then reply in the thread.
 - [Webhooks & custom channels](/docs/guides/webhooks.md): Receive provider events, keep one conversation per domain object, and deliver agent replies back out.