@cursor/bdk 0.2.1 → 0.2.3

package/docs/reference/cli.md

@@ -53,12 +53,12 @@ provide their own `help` subcommands.
 | --- | --- |
 | [`chat`](#chat) | Talk to a running agent |
 | [`resume`](#resume) | Reattach chat to a previous session |
-| [`run`](#run) | Start or continue work on a local, running, or managed agent |
+| [`run`](#run) | Start or continue work on a local, running, or hosted agent |
 | [`call`](#call) | Call a server tool without a model turn |
 | [`skill`](#skill) | Read an authored skill without a model turn |
 | [`logs`](#logs) | Follow or dump agent logs |
 | [`sessions`](#sessions) | List sessions |
-| [`session`](#session) | Inspect a session or start a managed session turn |
+| [`session`](#session) | Inspect a session or start a hosted session turn |
 | [`cost`](#cost) | Report token usage and estimated cost |
 | [`playground`](#playground) | Open an agent's playground |
 | [`trajectory`](#trajectory) | Summarize a saved event stream |
@@ -73,8 +73,8 @@ provide their own `help` subcommands.
 | [`deployment`](#deployment) | Inspect one deployment |
 | [`stop`](#stop) | Stop a deployment |
 | [`cancel-runs`](#cancel-runs) | Cancel active runs and reminder wakes |
-| [`event-repos`](#event-repos) | Replace a managed application's event repositories |
-| [`upgrade`](#upgrade) | Move a managed application to a release |
+| [`event-repos`](#event-repos) | Replace a deployment's event repositories |
+| [`upgrade`](#upgrade) | Move a deployment to a release |
 | [`delete`](#delete) | Delete a deployment |
 | [`rotate-token`](#rotate-token) | Replace a deployment's alias token |
 | [`secrets`](#secrets) | Set, list, or remove deployment secrets |
@@ -100,8 +100,7 @@ Commands that send requests support these targets:
 | Ephemeral local server | Omit `--url` and `--prod` | `run`, `call`, `skill`, `eval` |
 | Running server | Pass `--url <baseUrl>` | `chat`, `resume`, `run`, `call`, `skill`, `eval`, `logs`, `sessions`, `session`, `cost`, `playground`, `mcp` |
 | Default local server | Omit `--url` and `--prod`; uses `http://127.0.0.1:3000` | `chat`, `resume`, `logs`, `sessions`, `session`, `cost`, `playground` |
-| Hosted deployment | Pass `--prod` | `chat`, `resume`, `run`, `call`, `skill`, `eval`, `logs`, `sessions`, `session`, `cost`, `playground`, `mcp` |
-| Managed application | Pass `--prod` | `run`, `session` |
+| Hosted deployment | Pass `--prod` | `run`, `session`, `playground` |
 
 An explicit `--url` must include the slug for a multi-agent server, such as
 `http://127.0.0.1:3000/pr-approver`. `--slug` never changes an explicit URL.
@@ -111,7 +110,7 @@ An explicit `--url` must include the slug for a multi-agent server, such as
 | --- | --- |
 | `--dir <path>` | Select the project root. The default is the current directory. |
 | `--url <baseUrl>` | Use a running agent instead of local project discovery. |
-| `--prod` | Use a hosted deployment or managed application. Command support depends on the target type as listed above. |
+| `--prod` | Use the hosted deployment. Only `run`, `session`, and `playground` accept it. |
 | `--slug <slug>` | Select an agent from a multi-agent project or a hosted resource. Under `--prod`, the default is the `--dir` basename. |
 | `--team <id>` | Select a Cursor team. The signed-in account's team is the default. |
 | `--api-key <key>` | Override the Cursor credential for commands that authenticate with Cursor. |
@@ -189,9 +188,9 @@ prints the URL without opening a browser.
 `chat` connects to a running server and never starts an ephemeral one:
 
 ```text
-bdk chat [--url <baseUrl> | --prod] [--message <text>]
+bdk chat [--url <baseUrl>] [--message <text>]
   [--session <id> | --resume] [--continuation-token <token>]
-  [--slug <slug>] [--team <id>] [--json] [--text] [--no-color]
+  [--slug <slug>] [--json] [--text] [--no-color]
 ```
 
 | Input mode | Behavior |
@@ -213,9 +212,9 @@ token. An explicit session ID takes precedence.
 `resume` provides the same reattachment contract as `chat --session`:
 
 ```text
-bdk resume [sessionId] [--url <baseUrl> | --prod]
+bdk resume [sessionId] [--url <baseUrl>]
   [--message <text>] [--json] [--text]
-  [--continuation-token <token>] [--slug <slug>] [--team <id>]
+  [--continuation-token <token>] [--slug <slug>]
 ```
 
 Omit the session ID to select the most recently updated followable session.
@@ -237,27 +236,28 @@ bdk run [--dir <path>] [--message <text>]...
 
 | Option | Contract |
 | --- | --- |
-| `--message <text>` | Send a user message. Repeat it for a multi-turn local or `--url` run. Managed starts accept one message. |
+| `--message <text>` | Send a user message. Repeat it for a multi-turn local or `--url` run. `--prod` starts accept one message. |
 | `--messages-file <path>` | Read a JSON array of strings. File messages run before repeated `--message` values. |
-| `--session <id>` | Continue a session. Managed session starts accept a hosted `ses_...` ID. |
-| `--continuation-token <token>` | Continue the session selected by `--session` on a running server. Managed session starts use `--session` instead. |
+| `--session <id>` | Continue a session. With `--prod`, pass a hosted `ses_...` ID. |
+| `--continuation-token <token>` | Continue the session selected by `--session` on a running server. `--prod` starts use `--session` instead. |
 | `--events <file>` | Write the raw NDJSON stream to this path. |
 | `--no-events` | Skip the NDJSON trace. |
 | `--text` | Print a compact trajectory instead of JSON. |
 | `--timeout-ms <n>` | Stop waiting after a positive number of milliseconds. There is no default timeout. |
 | `--no-stream` | Hide live tool and reply progress on stderr. |
-| `--dry-run` | Mark a managed session turn as non-mutating. |
-| `--as-of <instant>` | Freeze a managed session's clock at a timezone-bearing ISO-8601 instant. |
-| `--component <key>` | Select a managed application's component instead of its default. |
+| `--dry-run` | Mark a `--prod` turn as non-mutating. |
+| `--as-of <instant>` | Freeze a `--prod` session's clock at a timezone-bearing ISO-8601 instant. |
+| `--component <key>` | Select a hosted deployment's component instead of its default. |
 
 For local and running-server targets, JSON output contains `ok`, `sessionId`,
 `continuationToken`, `trace`, `playgroundUrl`, `playgroundHint`, `visualize`,
 and `trajectory`. The `trace` value gives the saved path when event output is
-enabled. A managed session start confirms acceptance; a continuation also
-returns `sessionId`. Managed starts return before the turn finishes and ignore
-`--events`, `--no-events`, `--text`, `--timeout-ms`, and `--no-stream`.
-A successful managed start exits `0` on acceptance, before its turn outcome is
-known. A fresh start doesn't return `sessionId` synchronously.
+enabled. With `--prod`, `run` prints a `deliveryId` when the deployment accepts
+the turn and returns before the turn finishes. A fresh start has no
+`sessionId` yet, even with `--dry-run`; a continuation includes it. `--prod`
+starts ignore `--events`, `--no-events`, `--text`, `--timeout-ms`, and
+`--no-stream`, and a successful start exits `0` before the turn outcome is
+known. See [Verify a hosted turn](../deployment.md#verify-a-hosted-turn).
 
 ### Call a tool {#call}
 
@@ -265,8 +265,8 @@ known. A fresh start doesn't return `sessionId` synchronously.
 
 ```text
 bdk call <tool> [--input <json>]
-  [--dir <path> | --url <baseUrl> | --prod]
-  [--session <id>] [--slug <slug>] [--team <id>]
+  [--dir <path> | --url <baseUrl>]
+  [--session <id>] [--slug <slug>]
 ```
 
 `--input` accepts JSON and defaults to `{}`. `--session` uses the session
@@ -274,6 +274,9 @@ workspace and records the call on its event stream. The command prints the
 server's JSON response and succeeds only when the HTTP response succeeds with
 `ok: true`.
 
+Hosted deployments don't support `call`. Start a model turn with `run --prod`
+and check it with [`session`](#session).
+
 See [Tools](./tools.md#call-a-tool-without-a-model-turn) for validation,
 busy-session behavior, and error codes.
 
@@ -282,8 +285,8 @@ busy-session behavior, and error codes.
 `skill` reads an authored skill without a model turn:
 
 ```text
-bdk skill <name> [--dir <path> | --url <baseUrl> | --prod]
-  [--slug <slug>] [--team <id>] [--text]
+bdk skill <name> [--dir <path> | --url <baseUrl>]
+  [--slug <slug>] [--text]
 ```
 
 The default output is the server's JSON response. `--text` prints the rendered
@@ -292,14 +295,18 @@ The default output is the server's JSON response. `--text` prints the rendered
 ### List sessions {#sessions}
 
 ```text
-bdk sessions [--url <baseUrl> | --prod]
-  [--slug <slug>] [--team <id>] [--bearer-token <token>] [--json]
+bdk sessions [--url <baseUrl>]
+  [--slug <slug>] [--bearer-token <token>] [--json]
 ```
 
 Text output shows the session ID, channel, mode, turn count, running status,
 and update time. `--json` prints `{ sessions }`, including continuation
 tokens.
 
+Hosted deployments don't support `sessions`. Find a hosted session in the
+deployment's **Sessions** list in the dashboard, then check it with
+[`session <sessionId> --prod`](#session).
+
 ### Inspect a session {#session}
 
 ```text
@@ -318,29 +325,31 @@ bdk session --prod [<sessionId>] --slug <slug> --message <text>
 | `--json` | Print the trajectory object. |
 | `--events` | Print `{ sessionId, events }` with the raw event list. |
 | `--out <file.ndjson>` | Write the raw NDJSON trace instead of printing it. |
-| `--prod --message <text>` | Start a managed session or continue the supplied managed session ID. |
+| `--prod --message <text>` | Start a hosted session or continue the supplied hosted session ID. |
 
-`--events` and `--json` are mutually exclusive. Managed sessions without an
-event trajectory return hosted execution status and logs in text or JSON;
-`--events` and `--out` require an event trajectory. Use [`resume`](#resume) to
-continue a conversational session.
+`--events` and `--json` are mutually exclusive. With `--prod`, the command
+prints the session's runs and logs in text or JSON, and `--events` and `--out`
+aren't available. While a hosted turn is running, text output also reports the
+event count so far and prints `Turn running; runs may lag behind events.` Use
+[`resume`](#resume) to continue a conversational session.
 
 ### Follow logs {#logs}
 
 ```text
-bdk logs [--url <baseUrl> | --prod]
-  [--slug <slug>] [--team <id>] [--once] [--json]
+bdk logs [--url <baseUrl>]
+  [--slug <slug>] [--once] [--json]
 ```
 
 The command follows logs until Ctrl-C. `--once` prints the current buffer and
-exits; `--json` emits newline-delimited JSON events. A hosted deployment
-reports deployment progress before runtime logs become available.
+exits; `--json` emits newline-delimited JSON events. For a hosted deployment,
+use [`deployment`](#deployment) for rollout status and
+[`session <sessionId> --prod`](#session) for a session's runs and logs.
 
 ### Report costs {#cost}
 
 ```text
-bdk cost [sessionId] [--url <baseUrl> | --prod]
-  [--slug <slug>] [--team <id>] [--json]
+bdk cost [sessionId] [--url <baseUrl>]
+  [--slug <slug>] [--json]
 ```
 
 With a session ID, `cost` prints per-turn token usage and estimated cost.
@@ -358,6 +367,8 @@ bdk playground [--url <baseUrl> | --prod] [--session <id>]
 The command prints the playground URL and opens it unless `--print` is set.
 `--session` opens a deep link. A running target with credentials that a
 browser can't send starts a loopback proxy and stays open until Ctrl-C.
+`--session` links for a hosted deployment may not open yet; check that session
+with [`session <sessionId> --prod`](#session) instead.
 
 ### Inspect a trajectory {#trajectory}
 
@@ -380,8 +391,7 @@ bdk eval [--dir <path>] [evalId...]
   [--timeout-ms <n>] [--strict] [--max-concurrency <n>]
   [--junit <path>] [--artifacts <dir> | --no-artifacts]
   [--skip-report] [--out <file.json>] [--no-stream]
-  [--url <baseUrl> | --prod] [--no-wait]
-  [--slug <slug>] [--team <id>]
+  [--url <baseUrl>] [--no-wait] [--slug <slug>]
 ```
 
 Select an exact case such as `weather/nyc`, a file prefix such as `weather`,
@@ -404,22 +414,18 @@ between 1 and 200.
 | `--no-artifacts` | Skip artifacts for an ephemeral local run. |
 | `--skip-report` | Ignore reporters from eval files and the eval config during an ephemeral local run. |
 | `--out <file.json>` | Also write the full result JSON. |
-| `--no-wait` | Return after a running server or hosted deployment accepts the batch. |
+| `--no-wait` | Return after a running server accepts the batch. |
 
-A running server or hosted deployment prints its Eval ID when it accepts the
-batch.
+A running server prints its Eval ID when it accepts the batch.
 Use these commands to inspect or cancel it:
 
 ```text
-bdk eval status [evalId] --prod [--slug <slug>] [--team <id>]
 bdk eval status [evalId] --url <baseUrl>
-bdk eval cancel <evalId> --prod [--slug <slug>] [--team <id>]
 bdk eval cancel <evalId> --url <baseUrl>
 ```
 
 `eval status` without an ID lists recent remote runs. `eval status --out`
-requires an ID. The `status` and `cancel` subcommands require `--url` or
-`--prod`.
+requires an ID. The `status` and `cancel` subcommands require `--url`.
 
 ## Projects
 
@@ -571,7 +577,7 @@ service-account API key with agent access can deploy.
 | `--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. |
 | `--path <agent-path>` | Set the project path relative to the repository root. |
-| `--cursor-events-repo <owner/name>` | Add a repository whose SCM events reach the deployment. Repeat for multiple repositories. |
+| `--cursor-events-repo <owner/name>` | Watch a repository's Cursor events. Repeat the flag for each repository; the repositories you pass replace the previous list. Without the flag, the deployment watches its GitHub source repository. |
 | `--allow-domain <domain>` | Add an egress hostname. Repeat for multiple domains; values are combined with `hosting.egressDomains`. |
 | `--no-wait` | Return after the deployment request is accepted. |
 | `--json` | Print one object for one target or an array for multiple targets. |
@@ -579,7 +585,8 @@ service-account API key with agent access can deploy.
 Deployment slugs contain lowercase letters, digits, `_`, or `-`, start with a
 letter or digit, and have at most 64 characters. Egress entries are lowercase
 hostnames with an alphabetic top-level domain; one leading `*.` wildcard is
-allowed, with at most 20 entries.
+allowed, or a trailing `:port` for a protocol that is not HTTPS, with at most
+64 entries.
 
 By default, `deploy` waits until the deployment is running and exits nonzero
 if it reaches a failed state. A first deployment can return an alias token
@@ -614,8 +621,7 @@ bdk stop <slug> [--team <id>] [--no-wait] [--cancel-runs] [--json]
 
 The command waits for `stopped` by default. `--no-wait` returns after the
 request is accepted. `--cancel-runs` also requests cancellation of active
-runs and reminder wakes for a managed application. Other deployment types
-reject this option.
+runs and reminder wakes.
 
 ### Cancel active runs {#cancel-runs}
 
@@ -623,8 +629,8 @@ reject this option.
 bdk cancel-runs <slug> [--team <id>] [--json]
 ```
 
-The command requests cancellation for a managed application's active runs and
-reminder wakes. Other deployment types reject it. For a multi-tenant
+The command requests cancellation for a deployment's active runs and reminder
+wakes. For a multi-tenant
 application, this cancels every install; use `stop --cancel-runs` for
 install-local cancellation. It exits nonzero if any cancellation request fails
 to start.
@@ -636,11 +642,11 @@ bdk event-repos <slug> [--repo <owner/name>]...
   [--team <id>] [--json]
 ```
 
-The supplied repositories replace the managed application's complete event
-repository list; they aren't merged with the previous list. Omit `--repo` to
-clear the list.
+The supplied repositories replace the deployment's complete event repository
+list; they aren't merged with the previous list. Omit `--repo` to clear the
+list.
 
-### Upgrade a managed application {#upgrade}
+### Upgrade a deployment {#upgrade}
 
 ```text
 bdk upgrade <slug> [--release <id-or-version>]
@@ -695,11 +701,8 @@ most 4096 bytes, and each deployment holds at most 32 secrets.
 ### Connect an MCP client {#mcp}
 
 ```text
-bdk mcp --prod [--slug <slug>] [--team <id>]
 bdk mcp --url <baseUrl> [--bearer-token <token>]
 
-bdk mcp install --prod [--slug <slug>] [--team <id>]
-  [--name <server-name>] [--print] [--json] [--remote]
 bdk mcp install --url <baseUrl> [--bearer-token <token>]
   [--name <server-name>] [--print] [--json]
 ```
@@ -708,7 +711,6 @@ bdk mcp install --url <baseUrl> [--bearer-token <token>]
 | --- | --- |
 | `mcp` | Read newline-delimited JSON-RPC from stdin and proxy it to the selected agent's MCP endpoint. stdout is reserved for MCP messages. A target is required. |
 | `mcp install` | Add the selected agent to `~/.cursor/mcp.json`. `--name` sets the server name, `--print` previews the entry, and `--json` prints a machine-readable result. A `--url` entry with `--bearer-token` contains that token; handle printed and written copies as credentials. |
-| `mcp install --remote --prod` | Write a remote HTTP entry for clients that can't spawn a stdio process. The entry contains the API key in plain text and must be handled as a credential. |
 
 ### Authorize MCP OAuth {#mcp-oauth}
 
@@ -723,7 +725,7 @@ bdk mcp oauth <connection> [--dir <path>] [--store]
 | Connection | Result |
 | --- | --- |
 | `defineConnection({ url, oauth: true })` | Open a browser PKCE flow and save tokens in `mcp-auth.json` under the CLI config directory. `--store` also sets the matching deployment secrets. |
-| `defineConnection({ cursorAccount: true })` | Authorize the managed deployment's service account through Cursor. `--store` isn't needed. |
+| `defineConnection({ cursorAccount: true })` | Authorize the hosted deployment's service account through Cursor. `--store` isn't needed. |
 
 Stored secret names are `MCP_OAUTH_<NAME>_ACCESS_TOKEN`,
 `MCP_OAUTH_<NAME>_REFRESH_TOKEN`, and `MCP_OAUTH_<NAME>_CLIENT_ID`. Declare

package/docs/reference/connections.md

@@ -28,11 +28,37 @@ import { defineConnection } from "@cursor/bdk/connections";
 
 export default defineConnection({
   url: "https://mcp.linear.app/mcp",
-  headers: { authorization: `Bearer ${process.env.LINEAR_TOKEN}` },
+  headers: { authorization: "Bearer ${LINEAR_TOKEN}" },
 });
 ```
 
-Tokens come from env vars. Never hardcode them in the file.
+## Credentials in headers and env
+
+Write a credential as a `${NAME}` template in `headers` on a remote
+connection or in `env` on a stdio one. The connection stores the template
+as you wrote it and reads `NAME` from the environment every time it opens a
+client, so the value can arrive after the project loads.
+
+```ts
+export default defineConnection({
+  command: "slack-mcp-server",
+  args: ["--transport", "stdio"],
+  env: { SLACK_MCP_XOXB_TOKEN: "${SLACK_BOT_TOKEN}" },
+});
+```
+
+That timing is the point of the template. Your connection file is imported
+once, when the project loads, and a hosted deployment has none of its
+secrets in the environment yet, because the platform passes them to the
+agent per request. So a `process.env.SLACK_BOT_TOKEN` read at the top of
+the file captures an empty string and keeps sending it for the life of the
+process, while the same file works locally because `.env.local` was read
+before the import. The template form is right in both places.
+
+`bdk validate` warns about a template the environment does not define and
+names the variable. It stays a warning rather than an error, since a
+hosted deployment resolves it later. An unset variable resolves to an
+empty value at connect time, which the server reports as an auth failure.
 
 ## Host MCP OAuth
 

package/docs/reference/evals.md

@@ -270,19 +270,18 @@ disables them. This location is independent of `--state-root`.
 
 ## Run evals against a server
 
-The playground **Evals** view starts batches on its running server.
-`--url` targets a named running server, and `--prod --slug <slug>`
-targets a hosted deployment.
+The playground **Evals** view starts batches on its running server, and
+`--url` targets a named running server:
 
 ```text
-bdk eval --prod --slug vulnerability-scanner --tag smoke
-bdk eval status <eval-id> --prod --slug vulnerability-scanner
-bdk eval cancel <eval-id> --prod --slug vulnerability-scanner
+bdk eval --url http://127.0.0.1:3000/vulnerability-scanner --tag smoke
+bdk eval status <eval-id> --url http://127.0.0.1:3000/vulnerability-scanner
+bdk eval cancel <eval-id> --url http://127.0.0.1:3000/vulnerability-scanner
 ```
 
 Server-side batches use the target's discovered cases and return an eval
 ID for `status` or `cancel`. Local reporter and concurrency flags don't
-apply to `--url` or `--prod` runs.
+apply to `--url` runs.
 
 ## Related
 

package/docs/reference/hooks.md

@@ -78,8 +78,9 @@ want the final text; `message.completed` already has it.
 | `message.received`  | `{ text }`                                                                                                                                                                                                  |
 | `turn.completed`    | `{ result?, usage?, cost? }`. `usage` has `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, and optional `reasoningTokens`. `cost` has `totalUsd` and the `model` it was priced against |
 | `turn.failed`       | `{ message, status? }`. `status` is `"error"` or `"cancelled"` when present                                                                                                                                 |
-| `actions.requested` | `{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }`. `parentCallId` marks subagent work                                                                                                |
-| `action.result`     | `{ callId, toolName, output?, isError, stubbed?, parentCallId? }`. `stubbed` means a dry-run session answered a write without running it                                                                    |
+| `actions.requested` | `{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }`. One envelope per model step once that step has listed its tools. A single tool is a batch of one. `parentCallId` marks subagent work |
+| `actions.completed`    | `{ results: [{ callId, toolName, output?, isError, stubbed?, parentCallId? }], parentCallId? }`. Pair with `actions.requested`; emitted when every call in that batch has a result                          |
+| `action.result`     | `{ callId, toolName, output?, isError, stubbed?, parentCallId? }`. Live per-call envelope for chips and spans. `stubbed` means a dry-run session answered a write without running it                         |
 
 The types are `SessionEvent`, `SessionEventType`, and `HookContext`,
 exported from `@cursor/bdk`.

package/docs/reference/sessions.md

@@ -90,13 +90,14 @@ within one session. The `at` field is an ISO-8601 timestamp.
 | Steps | `step.started`, `step.completed` | Model step boundaries and duration |
 | Reasoning | `reasoning.appended`, `reasoning.completed` | Streamed reasoning blocks |
 | Reply | `message.appended`, `message.completed` | Text deltas and finalized assistant messages |
-| Tools | `actions.requested`, `action.result` | Tool names, validated arguments, outputs, and errors |
+| Tools | `actions.requested`, `actions.completed`, `action.result` | Tool names, validated arguments, outputs, and errors |
 | Approvals | `action.approval_requested`, `action.approval_resolved` | A parked tool call and the human decision |
 | Subagents | `subagent.called`, `subagent.completed` | Delegated work |
 | Artifacts | `artifact.tagged` | A durable [artifact](./artifacts.md) was tagged for this session, by host code or `tag_artifact` |
 
-Pair `actions.requested` with `action.result` to reconstruct the tool
-trajectory. Read `turn.completed.data.usage` for input, output, and
+Pair `actions.requested` with `actions.completed` for each model-step
+batch. `action.result` is the live per-call envelope. Read
+`turn.completed.data.usage` for input, output, and
 cache token counts. With `bot/result.ts`, `turn.failed` is emitted when
 `commit` throws, the turn has no assistant text, or `ctx.reject(message)`
 doesn't lead to an accepted revision.

package/docs/troubleshooting.md

@@ -35,6 +35,7 @@ Match the visible symptom below. The `bdk` binary ships with
 | File reads and greps fail repeatedly with `NGHTTP2_FRAME_SIZE_ERROR` | Run the agent under Node 22.13 or newer, never Bun. |
 | The turn immediately reports a missing API key | Set `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`, or `CURSOR_SERVICE_ACCOUNT_KEY`, or run `bdk login`. |
 | Login succeeds but the model host rejects the key | Point login and model traffic at the same API host; check `CURSOR_API_BASE_URL` and `CURSOR_BACKEND_URL`. |
+| The first turn reports `[resource_exhausted]` | Treat it as a capacity-shaped error. For a GitHub wake, also check the connected GitHub credential and any GitHub `429` rate limit before assuming the model quota is exhausted. |
 
 ## A turn behaves unexpectedly
 
@@ -61,9 +62,12 @@ Match the visible symptom below. The `bdk` binary ships with
 | What you see | What to do |
 | --- | --- |
 | 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>` and `bdk logs --prod --slug <slug>`, then act on the reported build or startup error. |
+| 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. |
-| Cursor events stopped after redeploy | Redeploy replaces CLI-supplied event repositories. Pass every `--cursor-events-repo` value again. |
+| Cursor events stopped after redeploy | Each redeploy replaces the watched repositories. Pass every `--cursor-events-repo` value again; without the flag, the deployment watches only its GitHub source repository. |
+| `run --prod` prints a `deliveryId` but no `sessionId` | The deployment accepted the turn and is still starting it, which is expected with or without `--dry-run`. Find the session in the deployment's **Sessions** list in the dashboard, then follow [Verify a hosted turn](./deployment.md#verify-a-hosted-turn). |
+| A high-effort turn runs for several minutes while runs look empty | Turns can take about eight minutes. Rerun `bdk session <sessionId> --prod --slug <slug>`; a growing event count means the turn is still working. Escalate only after about two to three minutes with no new events. |
+| A dashboard link to a single session returns 404 | Check the session with `bdk session <sessionId> --prod --slug <slug>`. |
 | External HTTP rejects the alias token | Update the caller with the current token. If the token is lost or exposed, run `bdk rotate-token <slug>` and replace it everywhere. |
 
 See [Deployment](./deployment.md) for source, credential, and
@@ -86,7 +90,7 @@ direct webhooks.
 | What you see | What to do |
 | --- | --- |
 | Logs say `channel idle ... missing credentials` | Run `bdk slack create --dir <agent>`, then check the generated prefix with `bdk slack doctor`. Use `slack init --manual` only for an app you own. |
-| `slack create` is waiting for workspace approval | Open the approval link printed by the CLI, keep the command running, and retry after an admin approves. |
+| `slack create` is waiting for workspace approval | Keep the CLI running, open the **Request approval** link it prints, and select **Retry** in the dashboard's **Add Slack** wizard after an admin approves. See [Slack](./guides/slack.md#connect). |
 | The bot ignores ordinary channel posts | Configure `engagement.channelPosts`, create the app with `--channel-posts`, and invite it to every allowed channel. |
 | Approval buttons do nothing | Set `toolApprovals: true`, then recreate the app if its interactivity is not enabled. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/bdk",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -25,7 +25,6 @@
     "!dist/internal/tenant-mcp/**",
     "!dist/internal/tenant-slack/**",
     "!dist/internal/grokbot/**",
-    "!dist/extensions/cursor-grokbot-agents/**",
     "!dist/internal/review-comments*",
     "!dist/internal/shallow-clone.*",
     "!dist/internal/managed-delivery.*",
@@ -34,7 +33,6 @@
     "!src/internal/tenant-mcp/**",
     "!src/internal/tenant-slack/**",
     "!src/internal/grokbot/**",
-    "!src/extensions/cursor-grokbot-agents/**",
     "!src/internal/review-comments*",
     "!src/internal/shallow-clone.ts",
     "!src/internal/managed-delivery.ts",
@@ -314,7 +312,7 @@
   },
   "dependencies": {
     "@bazel/runfiles": "6.5.0",
-    "@cursor/sdk": "1.0.31",
+    "@cursor/sdk": "1.0.32",
     "@modelcontextprotocol/sdk": "1.25.1",
     "@octokit/auth-app": "^7.2.0",
     "@octokit/rest": "^21.1.1",

package/scripts/install-cursor-skills.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * postinstall: copy Agent SDK coding-agent skills into ~/.cursor/skills/agentsdk
+ * postinstall: copy BDK coding-agent skills into ~/.cursor/skills/bdk
  * so Cursor discovers them after `npm install` / `npx @cursor/bdk`.
  *
  * Never fails the package install. No-op in the monorepo source checkout

package/skills/create-agent/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentsdk-create-agent
+name: bdk-create-agent
 description: >-
   Scaffold a new BDK agent: short AskQuestion interview, then
   verify a turn and hand off to hillclimb. Use when creating a new

package/skills/debug/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentsdk-debug
+name: bdk-debug
 description: >-
   Diagnose a misbehaving local BDK agent: blank playground,
   missing sessions, failed reads, webhook 401s, 403/409, lost

package/skills/deploy/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentsdk-deploy
+name: bdk-deploy
 description: >-
   Deploy or redeploy an BDK project to Cursor-managed hosting
   with an attached service account. Use when asked to deploy,

package/skills/evals/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentsdk-evals
+name: bdk-evals
 description: >-
   Author and run defineEval cases. Use when writing, fixing, seeding,
   or hillclimbing evals. Ask whether to generate samples or take

package/skills/framework-map/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentsdk-framework-map
+name: bdk-framework-map
 description: >-
   Orient on BDK layout, local runtime, sessions, and
   invariants (Node not Bun, root evals/, typecheck after tsx,

package/skills/github/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentsdk-github
+name: bdk-github
 description: >-
   Build and test GitHub-driven BDK agents: githubChannel hooks
   (auth turn vs host task), cursorAccount / --cursor-events, and

package/skills/hillclimb/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentsdk-hillclimb
+name: bdk-hillclimb
 description: >-
   Improve one existing BDK agent: pin fixtures, measure, change
   one lever, remeasure, lock the win with an eval. Use when an agent

package/skills/mcp-auth/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentsdk-mcp-auth
+name: bdk-mcp-auth
 description: >-
   Authorize host MCP OAuth for defineConnection({ url, oauth: true }):
   bdk mcp oauth, local tokens, --store, advertiseTools, egress.

package/skills/otel/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentsdk-otel
+name: bdk-otel
 description: >-
   Wire OpenTelemetry export (OTLP env, serve({ otel }), traces/metrics/logs,
   ctx.host.otel). Use when adding collector export or custom metrics.

package/skills/setup-slack/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentsdk-setup-slack
+name: bdk-setup-slack
 description: >-
   Wire Slack to an BDK agent. Mint a dedicated Socket Mode app
   with slack create, then doctor and smoke. Use slack init --manual

package/src/artifacts.ts

@@ -39,7 +39,10 @@ export type {
   ArtifactTagInput,
 } from "./types.js";
 
-/** Default {@link ArtifactsConfig.max} retention cap. */
+/**
+ * Default {@link ArtifactsConfig.max}. Architecture v1 and self-hosted v2
+ * evict to this cap. Hosted architecture v2 does not evict.
+ */
 export const ARTIFACTS_DEFAULT_MAX = 1_000;
 
 export function defineArtifacts(config: ArtifactsConfig): ArtifactsDefinition {
@@ -59,7 +62,7 @@ export function defineArtifacts(config: ArtifactsConfig): ArtifactsDefinition {
   return brandDefinition("artifacts", config);
 }
 
-/** Effective retention cap for a config (default {@link ARTIFACTS_DEFAULT_MAX}). */
+/** Effective cap where eviction still runs (default {@link ARTIFACTS_DEFAULT_MAX}). */
 export function resolveArtifactsMax(config: ArtifactsConfig | undefined): number {
   return config?.max ?? ARTIFACTS_DEFAULT_MAX;
 }