@cursor/bdk 0.2.14 → 0.2.15

package/docs/reference/cli.md

@@ -70,12 +70,17 @@ provide their own `help` subcommands.
 | [`deployments`](#deployments) | List deployments |
 | [`deployment`](#deployment) | Inspect one deployment |
 | [`stop`](#stop) | Stop a deployment |
+| [`start`](#start) | Start a stopped deployment |
+| [`kill`](#kill) | Stop a deployment, cancel its runs, and lock deploys |
+| [`unlock-deploys`](#unlock-deploys) | Let a killed deployment deploy again |
 | [`cancel-runs`](#cancel-runs) | Cancel active runs and reminder wakes |
 | [`event-repos`](#event-repos) | Replace a deployment's event repositories |
 | [`upgrade`](#upgrade) | Move a deployment to a release |
+| [`rollback`](#rollback) | Move a deployment to an earlier release |
 | [`delete`](#delete) | Delete a deployment |
 | [`rotate-token`](#rotate-token) | Replace a deployment's alias token |
 | [`secrets`](#secrets) | Set, list, or remove deployment secrets |
+| [`images`](#images) | Push, list, or remove container images for persistent agents |
 
 ### Connection and channel commands
 
@@ -98,7 +103,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` | `run`, `session`, `playground` |
+| Hosted deployment | Pass `--prod` | `run`, `session`, `logs`, `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.
@@ -108,8 +113,8 @@ 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 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. |
+| `--prod` | Use the hosted deployment. Only `run`, `session`, `logs`, and `playground` accept it; `chat`, `resume`, `call`, `skill`, `sessions`, `cost`, and `mcp` report that the deployment doesn't support the command, and `eval` rejects the flag. |
+| `--slug <slug>` | Select an agent from a multi-agent project or a hosted deployment. 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. |
 | `--bearer-token <token>` | Authenticate to a running server with a bearer token. |
@@ -234,28 +239,31 @@ bdk run [--dir <path>] [--message <text>]...
 
 | Option | Contract |
 | --- | --- |
-| `--message <text>` | Send a user message. Repeat it for a multi-turn local or `--url` run. `--prod` starts accept one message. |
+| `--message <text>` | Send a user message. Repeat it for a multi-turn local or `--url` run. A `--prod` run takes exactly one message. |
 | `--messages-file <path>` | Read a JSON array of strings. File messages run before repeated `--message` values. |
-| `--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. |
+| `--session <id>` | Continue a session. With `--prod`, pass a hosted `ses_...` ID from a session that `run --prod` or `session --prod` started; Slack, SCM, and custom-route sessions can't be continued this way. |
+| `--continuation-token <token>` | Continue the session selected by `--session` on a running server. `--prod` doesn't accept it. |
 | `--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 `--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. |
+| `--dry-run` | Start a `--prod` session that runs read tools and stubs write tools. |
+| `--as-of <instant>` | Freeze a `--prod` session's clock at an ISO-8601 instant with a timezone, such as `2026-08-31T12:00:00Z`. |
+| `--component <key>` | Wake a named component of a `--prod` deployment instead of its default. A continued session must belong to that component. |
 
 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. 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).
+enabled.
+
+With `--prod`, `run` returns as soon as the deployment accepts the turn and
+exits `0` before the turn outcome is known. It prints `deliveryId`,
+`workflowId`, and `sessionMode`, plus `dryRun` and `asOf` when set. A fresh
+start has no `sessionId` yet; a continuation echoes the `--session` value.
+`--events`, `--no-events`, `--text`, `--timeout-ms`, and `--no-stream` have no
+effect. See [Verify a hosted turn](../deployment.md#verify-a-hosted-turn) for
+finding and following the new session.
 
 ### Call a tool {#call}
 
@@ -301,9 +309,9 @@ 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).
+Hosted deployments don't support `sessions`. Find a hosted session ID in the
+[`logs --prod`](#logs) headers or the deployment's **Sessions** list in the
+dashboard, then check it with [`session <sessionId> --prod`](#session).
 
 ### Inspect a session {#session}
 
@@ -313,7 +321,7 @@ bdk session <sessionId> [--url <baseUrl> | --prod]
   [--json | --text | --events] [--out <file.ndjson>]
 
 bdk session --prod [<sessionId>] --slug <slug> --message <text>
-  [--dry-run] [--as-of <instant>] [--component <key>]
+  [--team <id>] [--dry-run] [--as-of <instant>] [--component <key>]
 ```
 
 | Option | Contract |
@@ -323,28 +331,33 @@ 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 hosted session or continue the supplied hosted session ID. |
+| `--prod --message <text>` | Start a hosted session, or continue the supplied hosted session ID, with the same contract as [`run --prod`](#run). |
 
-`--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.
+`--events` and `--json` are mutually exclusive. Use [`resume`](#resume) to
+continue a conversational session on a local or running server.
+
+With `--prod`, the command prints the session's hosted executions: one line
+per run with its status, duration, and time, followed by that run's log
+lines. `--json` prints `{ sessionId, executions, startLog, ... }`. `--events`
+and `--out` aren't available. While a turn is running, text output also
+reports the event count and latest event type and prints
+`Turn running; runs may lag behind events.` A run can show `running` with no
+logs until the turn ends, so a growing event count is the progress signal.
 
 ### Follow logs {#logs}
 
 ```text
 bdk logs [sessionId] [--url <baseUrl> | --prod]
-  [--session <sessionId>] [--slug <slug>] [--once] [--json]
+  [--session <sessionId>] [--slug <slug>] [--team <id>] [--once] [--json]
 ```
 
 The command follows logs until Ctrl-C. `--once` prints the current buffer and
 exits; `--json` emits newline-delimited JSON events. With `--prod`, it follows
-the output of the hosted deployment's most recent sessions and prints a
-`==> <sessionId> (<channel>) <==` header each time the output switches
-sessions. Pass a session ID, as an argument or with `--session`, to follow only
-that session. Hosted log events carry `sessionId` and `line` rather than
-`index` and `at`.
+the output of the hosted deployment's most recent sessions on every channel
+and prints a `==> <sessionId> (<channel>) <==` header each time the output
+switches sessions. Pass a session ID, as an argument or with `--session`, to
+follow only that session; a session ID requires `--prod`. Hosted log events
+carry `sessionId` and `line` rather than `index` and `at`.
 
 ### Report costs {#cost}
 
@@ -368,8 +381,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.
+With `--prod`, the URL opens the deployment's playground under **Deployed
+Agents** in the dashboard.
 
 ### Inspect a trajectory {#trajectory}
 
@@ -659,6 +672,36 @@ 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.
 
+### Start a deployment {#start}
+
+```text
+bdk start <slug> [--team <id>] [--json]
+```
+
+`start` resumes a stopped deployment. It doesn't remove the deploy lock
+that [`kill`](#kill) sets.
+
+### Kill a deployment {#kill}
+
+```text
+bdk kill <slug> [--team <id>] [--json]
+```
+
+Use `kill` in an emergency. It locks deploys of the slug, stops the
+deployment, and requests cancellation of its active runs and reminder
+wakes. To bring the deployment back, run
+[`unlock-deploys`](#unlock-deploys) and then [`start`](#start).
+
+### Unlock deploys {#unlock-deploys}
+
+```text
+bdk unlock-deploys <slug> [--team <id>] [--json]
+```
+
+`unlock-deploys` removes the lock that `kill` sets, so `deploy`,
+`upgrade`, and `rollback` work for the slug again. It doesn't resume
+traffic; run `start` for that.
+
 ### Cancel active runs {#cancel-runs}
 
 ```text
@@ -689,6 +732,17 @@ bdk upgrade <slug> [--release <id-or-version>]
 `--release` accepts a release ID or version. Omit it to select the newest
 ready release. `--json` prints `{ releaseId }`.
 
+### Roll back a deployment {#rollback}
+
+```text
+bdk rollback <slug> [--release <id-or-version>]
+  [--team <id>] [--json]
+```
+
+`rollback` moves the deployment to an earlier ready release without
+building a new one. Omit `--release` to select the release before the
+current one. `--json` prints `{ releaseId }`.
+
 ### Delete a deployment {#delete}
 
 ```text
@@ -737,6 +791,24 @@ most 4096 bytes, and each deployment holds at most 32 secrets.
 `{ secretNames }` for `set`, `{ secrets }` for `list`, and `{ removed }` for
 `unset`. Changes are available to subsequent hosted work.
 
+### Manage container images {#images}
+
+```text
+bdk images push <local-image> --name <name> [--team <id>] [--json]
+bdk images list [--team <id>] [--json]
+bdk images rm <name> [--team <id>] [--json]
+```
+
+A persistent agent can run inside a container image that your team pushes
+and names in `hosting.image`. `push` needs Docker on your machine. It
+checks the local image first: the image must be `linux/amd64` and have
+`bash`, `git`, `node` 22.13 or newer, and `npm` on `PATH`. The command
+then compresses the image and uploads it under `--name`.
+
+`list` shows the team's images and how many the team can keep, and `rm`
+deletes one image. A deploy pins the image it uses, so after you push a
+new image under the same name, deploy again to pick it up.
+
 ## MCP connections
 
 ### Connect an MCP client {#mcp}
@@ -753,10 +825,13 @@ 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. |
 
+Hosted deployments don't support `mcp` or `mcp install`; both report that the
+deployment doesn't support the command when you pass `--prod`.
+
 ### Authorize MCP OAuth {#mcp-oauth}
 
 ```text
-bdk mcp oauth <connection> [--dir <path>] [--store]
+bdk mcp oauth <connection> [--dir <path>]
   [--slug <slug>] [--team <id>]
 ```
 
@@ -765,13 +840,11 @@ 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 hosted deployment's service account through Cursor. `--store` isn't needed. |
+| `defineConnection({ url, oauth: true })` | Open a browser PKCE flow and save tokens in `mcp-auth.json` under the CLI config directory. |
+| `defineConnection({ cursorAccount: true })` | Authorize the hosted deployment's service account through Cursor. |
 
-Stored secret names are `MCP_OAUTH_<NAME>_ACCESS_TOKEN`,
-`MCP_OAUTH_<NAME>_REFRESH_TOKEN`, and `MCP_OAUTH_<NAME>_CLIENT_ID`. Declare
-them in `hosting.secretNames`. URL-connection tokens are bound to the resource
-URL; authorize again after changing it.
+URL-connection tokens are bound to the resource URL; authorize again after
+changing it.
 
 See [Host MCP OAuth](../guides/mcp-oauth.md) for the full setup flow.
 

package/docs/reference/connections.md

@@ -61,8 +61,9 @@ empty value at connect time, which the server reports as an auth failure.
 
 For servers that speak OAuth, set `oauth: true` and authorize with the
 CLI or mid-run Connect. Tokens live in `mcp-auth.json` under the CLI
-config directory. `--store` copies them onto the deployment as
-`MCP_OAUTH_<NAME>_*` secrets.
+config directory of the machine that authorized them. A hosted agent
+reaches OAuth servers through a
+[Cursor account connection](#cursor-account-mcp-connection) instead.
 
 ```ts
 export default defineConnection({
@@ -72,8 +73,7 @@ export default defineConnection({
 ```
 
 ```text
-bdk mcp oauth inventory           # browser PKCE → local mcp-auth.json
-bdk mcp oauth inventory --store   # also upsert deployment secrets
+bdk mcp oauth inventory   # browser PKCE → local mcp-auth.json
 ```
 
 Full walkthrough: [Host MCP OAuth](../guides/mcp-oauth.md). Companion
@@ -294,7 +294,8 @@ connection.
 
 ## Related
 
-- [Host MCP OAuth](../guides/mcp-oauth.md): `mcp oauth`, Connect, `--store`
+- [Host MCP OAuth](../guides/mcp-oauth.md): `mcp oauth`, Connect, and
+  hosted agents
 - [Tools](./tools.md): authored tools that wrap MCP connections
 - [Webhooks](../guides/webhooks.md): calling MCP connections from handlers
 - [Peer agents](../guides/agent-to-agent.md): when a specialist is its

package/docs/reference/evals.md

@@ -88,8 +88,7 @@ file-level metadata; case reporters add to the file's reporters.
 ## Send turns in a case
 
 `await t.send(message, options?)` runs one turn and waits until it
-finishes, fails, or parks for approval. Several sends in one test share
-the session.
+finishes or fails. Several sends in one test share the session.
 
 The returned turn exposes its assistant `message`, `sessionId`,
 `events`, ordered `toolCalls`, `ok`, and one-based `index`. Assertions
@@ -115,8 +114,7 @@ reports every violated contract.
 
 | Assertion | Checks |
 | --- | --- |
-| `t.succeeded()` | Run finished without failure or an unanswered approval |
-| `t.parked()` | Run stopped on an unanswered approval |
+| `t.succeeded()` | Run finished without failure |
 | `t.calledTool(name, matcher?)` | Matching tool request occurred |
 | `t.notCalledTool(name)` | No request for that tool occurred |
 | `t.loadedSkill(name)` | Agent opened a named skill |

package/docs/reference/hooks.md

@@ -164,7 +164,6 @@ All three consume the same stream, for different jobs:
 | Add context before the model runs                                                     | The channel's `send` message and `workspaceFiles`, `instructions.md`, skills, or `sandbox/workspace/` seed files |
 | Reply on Slack, comment on a PR, or post any other delivery                           | The channel's `events` map, or the Slack and GitHub packs                                                        |
 | Show PR progress (merge-box check, sticky banner)                                     | `githubChannel({ progress: { commitStatus, banner } })`; see [GitHub agents](../guides/github.md)                 |
-| Block, approve, or rewrite a tool call                                                | [`needsApproval`](./tools.md#gate-a-tool-on-human-approval) on the tool                                          |
 | Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn | `defineResult`                                                                                                   |
 | Gate a change on behavior                                                             | [Evals](../evals.md)                                                                                             |
 

package/docs/reference/http-api.md

@@ -13,8 +13,9 @@ chain, and session-owned resources return `403` to another principal.
 Unless a section says otherwise, the default auth policy is
 `localDevStrict()`. `--bearer-token` replaces it with bearer auth, and
 `--allow-anonymous` replaces it with anonymous access. Built-in JSON
-routes use `{ ok: false, error: "<code>", message? }` for errors; MCP
-uses JSON-RPC, and custom channel handlers define their own responses.
+routes use `{ ok: false, error: "<code>", message? }` for errors, and MCP
+uses JSON-RPC. Custom channel routes answer hosted callers with an empty
+`202`; see [Call custom channel routes](#call-custom-channel-routes).
 
 ## Host routes
 
@@ -26,7 +27,6 @@ exist only when the playground is enabled.
 | `GET /` | HTML index of mounted agents; no auth |
 | `GET /v1/agents` | JSON index of mounted agents; no auth |
 | `GET /docs`, `GET /docs/*` | Documentation site in either layout; no auth |
-| `GET /v1/health` | Host liveness; no auth |
 
 `--no-playground` removes the two index routes. `--no-docs` removes the
 documentation site.
@@ -101,15 +101,6 @@ On loopback under `serve --dev`, the session list includes every
 principal so webhook and schedule sessions appear in the playground.
 The cost route returns `404` for an unknown session.
 
-## Resolve tool approvals
-
-| Route | Contract |
-| --- | --- |
-| `GET /v1/session/:sessionId/approvals` | List pending tool approvals |
-| `POST /v1/session/:sessionId/approvals/:callId` | Resolve one with `{"decision":"approve"}` or `{"decision":"deny"}` |
-
-For the lifecycle, see [Gate a tool on human approval](./tools.md#gate-a-tool-on-human-approval).
-
 ## Call a tool without a model turn
 
 `POST /v1/tools/:toolName` runs a server tool with no model turn.
@@ -141,8 +132,7 @@ These read-only routes describe the running agent.
 | --- | --- |
 | `GET /v1/info` | Return the discovered model, tools, skills, connections, subagents, channels, schedules, hooks, and diagnostics |
 | `GET /v1/tools` | Return live server tools and advertised MCP tools as `{ name, title?, source? }`; bind session-specific listings with `session` or `continuationToken` |
-| `GET /v1/tools/:name` | Return one tool's description, execution mode, approval and effect rules, schemas, and source |
-| `GET /v1/health` | Return per-agent liveness; no auth |
+| `GET /v1/tools/:name` | Return one tool's description, execution mode, effect rules, schemas, and source |
 | `GET /v1/logs?after=N` | Return recent server logs and the next polling cursor |
 
 An unknown tool name returns `404` with available names. If an MCP
@@ -162,9 +152,9 @@ The list follows the same ownership rules as `GET /v1/sessions`. See
 ## Call custom channel routes
 
 Authored routes mount under `/v1/channels/<id>` with their declared
-methods and paths. The host validates their Zod body and query schemas
-before calling the handler, returning `400` on failure. Each channel's
-auth chain applies. See [Channels](./channels.md).
+methods and paths, and each channel's auth chain applies. A hosted
+caller receives `202 Accepted` with an empty body, never the handler's
+response. See [Route responses](./channels.md#route-responses).
 
 ## MCP endpoint
 

package/docs/reference/playground.md

@@ -1,6 +1,6 @@
 ---
 title: "Playground"
-description: "The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch."
+description: "The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, and dev-mode dispatch."
 ---
 
 # Playground
@@ -16,9 +16,8 @@ lists them all.
 | --- | --- |
 | Chat | Talk to the agent. Text and reasoning stream live, and tool calls appear inline with their arguments, output, and error state |
 | Slash commands | Custom channel routes without path parameters become composer commands; GitHub and Slack ingress routes are excluded. A `drive` route becomes `/drive <pr-url>`, with `/help` and autocomplete |
-| Try | Invoke a custom channel route from the Agent tab. The modal remembers your last body per endpoint, copies curl, and opens a session when the route creates one |
+| Try | Invoke a custom channel route from the Agent tab. The modal remembers your last body per endpoint and copies curl. Find the session the route starts under Runs |
 | Runs | Browse the sessions you own and eval runs. Search by title or identifier; open sessions in Chat, Trace, or Raw and eval runs in Evals |
-| Approvals | Parked `needsApproval` tool calls render Approve / Deny buttons |
 | Evals | List and run filesystem evals from the browser |
 | Agent | Inspect the discovered tools, skills, subagents, MCP connections, channels, and hooks |
 | Raw | Inspect the selected session's event stream |
@@ -40,5 +39,3 @@ and paste the token into the token field in the navbar.
 
 - [HTTP API](./http-api.md): the HTTP surface the playground uses
 - [Sessions and streaming](./sessions.md): the streams it renders
-- [Gate a tool on human approval](./tools.md#gate-a-tool-on-human-approval):
-  the approval buttons in context

package/docs/reference/schedules.md

@@ -66,6 +66,7 @@ and `host` (shared services: `host.mcp`, `host.github`, `host.slack`,
 
 | Mode | What fires |
 | --- | --- |
+| Cursor-managed hosting | Cron cadence, from the schedules in the deployed release. See [Schedules on Cursor hosting](#schedules-on-cursor-hosting) |
 | Production `bdk serve` | Cron cadence. `--no-schedules` disables them. Run them in exactly one process per project |
 | `serve --dev` | Nothing automatic. Dispatch by hand through the same path production uses |
 
@@ -77,6 +78,27 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/schedules/heartbeat
 The playground can dispatch schedules in dev mode too, and
 `handle.dispatchSchedule("heartbeat")` does it programmatically.
 
+### Schedules on Cursor hosting
+
+Each deploy registers the schedules in its release and replaces the
+previous set, so a schedule you delete from `bot/schedules/` stops after
+the next deploy. Hosted schedules need `@cursor/bdk` 0.2.14 or newer in
+the project. A deployment built with an earlier version has no hosted
+schedules until you upgrade the package and deploy again.
+
+Every fire starts a new runtime. A Markdown schedule starts a task
+session there, and a `run` handler must finish in 26 minutes, including
+the work it passes to `receive` and `waitUntil`. Nothing in module memory
+carries over to the next fire, so keep state in `ctx.host.kv` or
+`ctx.host.files`. Each scheduled time starts at most one run, and a
+stopped deployment skips its fires.
+
+A schedule's name is its path under `bot/schedules/` without the file
+extension. On Cursor hosting, a name has 1 to 100 letters, digits, `.`,
+`_`, `-`, or `/`, and starts with a letter or digit. A release holds at
+most 64 schedules, and `deploy` rejects a release that breaks either
+rule.
+
 ## Reminders
 
 A reminder is created at runtime and bound to a channel continuation. A
@@ -126,14 +148,15 @@ await handle.createReminder({
 });
 ```
 
-Use an anonymous `run` handler only for legacy projects that can re-arm
-it after a restart. New projects should use a named handler.
+Architecture v2, the default, rejects an anonymous `run` handler and a
+function `until`, locally and on Cursor hosting. Use a prompt or a named
+handler.
 
 | Form | What it does | After a restart |
 | --- | --- | --- |
 | Prompt | Sends `prompt` into the session. `until` is the standing cancellation condition for the model | Stays armed |
 | Named handler | Runs a discovered handler with serializable `args`; it starts a model turn only if the handler calls `followup` | Stays armed |
-| Anonymous `run` | Host handler returns `stop`, `skip`, or `delivered` per tick; it starts a model turn only if it calls `followup` | Must be re-armed |
+| Anonymous `run` | Architecture v1 only. Host handler returns `stop`, `skip`, or `delivered` per tick; it starts a model turn only if it calls `followup` | Must be re-armed |
 
 The same API is `host.reminders` on channel handlers, tools, and
 schedule runs. `builtinTools: { reminders: true }` adds

package/docs/reference/sessions.md

@@ -32,7 +32,7 @@ inspection are different jobs.
 | Identifier | Use it for |
 | --- | --- |
 | `continuationToken` | Continue a conversation through its channel |
-| `sessionId` | Stream events, inspect state, resolve approvals, or run a session-bound tool call |
+| `sessionId` | Stream events, inspect state, or run a session-bound tool call |
 
 Channels decide what a continuation token looks like. Slack uses its
 thread identity. A PR channel can use a key such as `pr:owner/repo#1`.
@@ -88,7 +88,6 @@ within one session. The `at` field is an ISO-8601 timestamp.
 | Reasoning | `reasoning.appended`, `reasoning.completed` | Streamed reasoning blocks |
 | Reply | `message.appended`, `message.completed` | Text deltas and finalized assistant messages |
 | Tools | `actions.requested`, `actions.completed`, `action.result`, `action.tool_retry` | Tool names, validated arguments, outputs, and errors. `action.tool_retry` means a read is running again after a transient failure |
-| 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` |
 

package/docs/reference/skills.md

@@ -32,7 +32,7 @@ description: Use when a pull request needs a structured approval checklist.
 
 1. Call `inspect_pr` and confirm required checks passed.
 2. Summarize the PR title, author, and remaining risks.
-3. Call `approve_pr` only after an explicit request; it requires approval.
+3. Call `approve_pr` only after an explicit request.
 ```
 
 Use TypeScript when the content must be generated or include inline

package/docs/reference/tools.md

@@ -1,6 +1,6 @@
 ---
 title: "Tools"
-description: "Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn."
+description: "Define typed actions the model can call, control their dry-run effects, and call any server tool without a model turn."
 ---
 
 # Tools
@@ -217,32 +217,6 @@ use the same exposed names. See
 [MCP connections](./connections.md#advertise-tools) for the full
 contract.
 
-## Gate a tool on human approval
-
-A server tool can require a person to sign off before it runs. Set
-`needsApproval` to `true`, or to a predicate over the validated input:
-
-```ts
-export default defineTool({
-  description: "Promote a verified build to an environment.",
-  needsApproval: true, // or: (input) => input.environment === "production"
-  inputSchema: z.object({
-    service: z.string(),
-    buildId: z.string(),
-    environment: z.string(),
-  }),
-  async execute({ service, buildId, environment }) {
-    return { promoted: true, service, buildId, environment };
-  },
-});
-```
-
-The call parks, the turn stays running, and the stream emits
-`action.approval_requested` until someone resolves it from the
-playground, `POST /v1/session/:id/approvals/:callId`, or Slack
-Approve/Deny cards. Approvals exist for server tools on the local
-runtime only, and parked calls don't survive a host restart.
-
 ## Call a tool without a model turn
 
 Server tools can be called deterministically. You pick the tool and the
@@ -324,8 +298,8 @@ spoofed payload can't steer it.
 Test tools with `call` before blaming prompts. If the tool's output is
 wrong, no instruction change fixes it.
 
-Gate side effects with `needsApproval`. Declare each tool's `effect` so
-dry-run sessions can execute reads and stub writes.
+Declare each tool's `effect` so dry-run sessions can execute reads and
+stub writes.
 
 ## Related
 

package/docs/templates/grokbot-agents.md

@@ -51,7 +51,7 @@ checked later, and an active turn can be interrupted when the task
 changes.
 
 See [Grok Bot agents](../guides/grokbot-agents.md) for the extension's
-conversation and approval boundaries.
+conversation boundaries.
 
 ## What to edit
 

package/docs/troubleshooting.md

@@ -62,10 +62,17 @@ Match the visible symptom below.
 | 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 | 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>`. |
+| `run --prod` prints a `deliveryId` but no `sessionId` | Expected, with or without `--dry-run`: the session is created when the turn starts. Find it with `bdk logs --prod --once --slug <slug>`, then follow [Verify a hosted turn](./deployment.md#verify-a-hosted-turn). |
+| `session <sessionId> --prod` shows a `running` run with no logs | Runs lag behind events, and a high-effort turn can take several minutes. Rerun the command; a growing event count means the turn is still working. |
+| A dashboard link to a single session doesn't open | Check the session with `bdk session <sessionId> --prod --slug <slug>`. |
+| `chat`, `call`, `sessions`, `cost`, or `mcp` with `--prod` says the command is not supported | Hosted deployments accept `--prod` only on `run`, `session`, `logs`, and `playground`. See [Verify a hosted turn](./deployment.md#verify-a-hosted-turn). |
+| `run --prod --session <sessionId>` reports the session belongs to another channel | `--session` continues only sessions that `run --prod` or `session --prod` started. Reach Slack, SCM, and custom-route sessions through their own channel. |
+| A custom route returns `202` with no body | Expected on managed hosting. The handler runs after the response, so deliver results from the channel. See [Route responses](./reference/channels.md#route-responses). |
 | 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. |
+| `deploy` says deployments are not available under legacy privacy mode | The team uses Privacy Mode (Legacy), which does not let Cursor store code. Managed hosting is not available with this setting. |
+| `deploy` says persistent deployments are limited to 1 per team | Another deployment of the team already sets `persistent: true`. Remove the setting from one agent, or delete that deployment. |
+| A schedule does not fire on the hosted deployment | Make sure the deployment is running and its release has the schedule. Deploy again with `@cursor/bdk` 0.2.14 or newer. |
+| A request to a custom route gets `429` | The deployment received more requests than its limit. Wait for the time in `Retry-After`, then send the request again. |
 
 See [Deployment](./deployment.md) for source, credential, and
 redeployment boundaries.
@@ -89,7 +96,6 @@ direct webhooks.
 | 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 | 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. |
 
 See the [Slack guide](./guides/slack.md) for app setup and engagement
 choices.
@@ -99,17 +105,16 @@ choices.
 | What you see | What to do |
 | --- | --- |
 | `must be defineConnection({ url, oauth: true })` | Add `oauth: true` to the named URL connection or correct the connection filename passed to `mcp oauth`. |
-| Local auth works but hosted calls return unauthorized | Complete Connect for the running process, or run `mcp oauth <name> --store` and redeploy for future replacements. |
+| Local auth works but hosted calls return unauthorized | Locally stored OAuth tokens don't reach a deployment. Use a `cursorAccount: true` connection and connect the server from **Deployed Agents** in the dashboard. See [Host MCP OAuth](./guides/mcp-oauth.md#use-an-oauth-server-from-a-hosted-agent). |
 | The model invents `mcp_auth` instead of calling the server | Set `advertiseTools: true` for named local tools, or expose a host-side wrapper through `ctx.host.mcp`. |
 
 See [Host MCP OAuth](./guides/mcp-oauth.md) for the credential lifecycle.
 
-## Schedules, reminders, or approvals stall
+## Schedules or reminders stall
 
 | What you see | What to do |
 | --- | --- |
 | A schedule or reminder never fires under `--dev` | Trigger it through the matching `/v1/dev/schedules/<id>` or `/v1/dev/reminders/<id>` route; development mode does not auto-fire. |
-| A pending approval disappears after restart | Parked approvals do not survive restart. Run the turn again. |
 | A reminder is disarmed with `handler_lost_on_restart` | Recreate handler-form reminders after restart, or use a prompt-form reminder. |
 | The same schedule fires on several self-hosted processes | Enable schedules on one serving process per project and pass `--no-schedules` to the others. |