@cursor/bdk 0.2.14 → 0.2.16

package/dist/docs/llms-full.txt

@@ -24,8 +24,8 @@ Give the coding agent a purpose and the surfaces people will use. The
 then scaffolds and verifies a small first version.
 
 > Use the BDK create-agent skill to build a PR triage agent
-> reachable through GitHub. It should summarize failed checks, require
-> approval before posting a review, and include one smoke eval.
+> reachable through GitHub. It should summarize failed checks, post one
+> review comment per pull request, and include one smoke eval.
 
 Ask it to read
 [`skills/create-agent/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md). The
@@ -44,7 +44,7 @@ Examples:
 > skill, keep replies in the source thread, and verify one local mention.
 
 > Connect the private inventory MCP server with host OAuth. Keep its
-> write tools behind an approved server-tool wrapper.
+> write tools behind a narrow server-tool wrapper.
 
 > Add a GitHub ready-for-review trigger and replay PR 42 before posting
 > anything live.
@@ -75,8 +75,8 @@ validation and exposes its real output.
 ## Verify one end-to-end turn
 
 Once deterministic inputs are correct, send the same request a user
-will. The coding agent should check the final answer, tool trajectory,
-and any parked approval before declaring the capability complete.
+will. The coding agent should check the final answer and tool trajectory
+before declaring the capability complete.
 
 ```text
 bdk run --dir . \
@@ -195,6 +195,18 @@ The source repository must be available through the team's repository
 integration, and a nested `--path` must contain an installable BDK
 project.
 
+### Privacy Mode
+
+A hosted deployment stores a snapshot of its source repository, along
+with the sessions, KV, files, and logs the agent creates for your team.
+Whether you can deploy depends on the privacy setting that applies to
+you, which is your team's setting when the team enforces one:
+
+| Privacy setting | Managed hosting |
+| --- | --- |
+| Privacy Mode | Available. Cursor stores deployment data the same way it does without Privacy Mode, and the agent's model requests get the same Privacy Mode handling as your other Cursor requests. |
+| Privacy Mode (Legacy) | Not available. `deploy` fails, because this setting doesn't let Cursor store code. |
+
 ## Add egress and secrets
 
 Declare the external hosts and secret names the agent needs. Mounted
@@ -242,54 +254,80 @@ platform can verify each delivery's signature before any compute starts.
 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
 reads no hostname from. The
-[Host MCP OAuth guide](/docs/guides/mcp-oauth.md) owns the extra secret and
-egress steps for OAuth-backed MCP servers.
+[Host MCP OAuth guide](/docs/guides/mcp-oauth.md) covers OAuth-backed MCP
+servers on a hosted agent.
 
 ## Use the hosted agent
 
 ### Verify a hosted turn
 
-Start a turn on the deployment:
+After `deploy` reports `running`, message the deployment from the CLI:
 
-```text
+```bash
 bdk run --prod --slug weather-agent \
   --message "Forecast for Paris"
 ```
 
-The command returns as soon as the deployment accepts the turn, so the output
-has a `deliveryId` but no `sessionId` yet. That's expected, with or without
-`--dry-run`. Open the deployment from **Deployed Agents** in the
-[dashboard](https://cursor.com/dashboard) and select **Sessions** to find the
-new session's `ses_...` ID.
+The command returns as soon as the deployment accepts the turn, so its
+output has a `deliveryId` and `workflowId` but no `sessionId` yet; the
+session is created when the turn starts. Add `--dry-run` to check a
+deployment without side effects: read tools run and write tools are
+stubbed.
 
-Check the session from the CLI:
+Find the new session in the deployment's recent output, which prints a
+`==> ses_... (http) <==` header for each session, or open the deployment
+from **Deployed Agents** in the [dashboard](https://cursor.com/dashboard)
+and select **Sessions**:
 
-```text
+```bash
+bdk logs --prod --once --slug weather-agent
+```
+
+Then follow the turn:
+
+```bash
 bdk session ses_... --prod --slug weather-agent
 ```
 
-While the turn runs, the command reports how many events have arrived and
-prints `Turn running; runs may lag behind events.` Rerun it until the latest
-run shows a final status such as `finished`. High-effort turns can take about
-eight minutes, and runs can stay empty until the turn ends, so a growing event
-count is the progress signal. Escalate only when no new events arrive for about
-two to three minutes.
+The command lists each hosted run with its status and log lines. While
+the turn is still working, it reports how many events have arrived and
+prints `Turn running; runs may lag behind events.` Rerun it until the
+latest run shows a final status such as `finished`. A high-effort turn
+can take several minutes, and its run can show no logs until it ends, so
+a growing event count is the progress signal.
 
-Hosted deployments don't support `bdk call` or `bdk sessions`, so use
-`bdk run --prod` and `bdk session` instead. Dashboard links to a single session
-may not open yet, so confirm the result with `bdk session`.
+To continue the same conversation, pass `--session ses_...` to
+`run --prod`. `bdk playground --prod --slug weather-agent --session ses_...`
+opens the session in the dashboard playground. Hosted deployments don't
+support `bdk chat`, `call`, `sessions`, `cost`, or `mcp`; use
+`run --prod`, `logs --prod`, and `session --prod` instead.
 
-### Call the hosted HTTP API
+### Send work to the deployment
 
-External HTTP clients use the stable alias URL and send the alias token
-on every request:
+A hosted agent wakes from its channels: Slack mentions and DMs, SCM
+events, and custom channel routes. External HTTP clients call a custom
+route on the stable alias URL and send the alias token on every
+request:
 
 ```bash
-curl "$AGENT_ALIAS_URL/v1/health" \
-  -H "X-Agent-Alias-Token: $AGENT_ALIAS_TOKEN"
+curl -X POST "$AGENT_ALIAS_URL/v1/channels/tickets/ticket" \
+  -H "X-Agent-Alias-Token: $AGENT_ALIAS_TOKEN" \
+  -H 'content-type: application/json' \
+  -d '{"ticketId":"ENG-142","message":"CSV export returns 500"}'
 ```
 
-The first deploy prints this token once. Store it outside terminal
+The deployment answers `202 Accepted` with an empty body as soon as the
+request arrives, then runs the route's handler, so the caller never
+receives a session ID or a result. Deliver results from the channel, as
+described in [Route responses](/docs/reference/channels.md#route-responses).
+
+To confirm the work started, find the new session with
+`bdk logs --prod` and follow it with `bdk session --prod`, as in
+[Verify a hosted turn](#verify-a-hosted-turn).
+
+### Protect the alias token
+
+The first deploy prints the alias token once. Store it outside terminal
 transcripts; it cannot be retrieved later. If it is lost or exposed,
 `bdk rotate-token weather-agent` replaces it and invalidates the
 old value.
@@ -327,9 +365,8 @@ across normal runtime replacements. Files written elsewhere on the
 runtime's local filesystem are disposable; use `ctx.host.kv` or
 `ctx.host.files` for durable application state.
 
-Parked approvals and in-memory reminder handlers do not survive a
-restart. Run the turn again or recreate the reminder after a
-replacement.
+On architecture v2, the default, reminders take a prompt or a named
+handler. See [Reminders](/docs/reference/schedules.md#reminders).
 
 ## Self-host securely
 
@@ -371,8 +408,8 @@ per-caller and channel-specific auth.
 
 ## Observability
 
-Use `bdk session <sessionId> --prod` for a hosted session's runs and logs,
-[OpenTelemetry](/docs/guides/opentelemetry.md) for traces and metrics, and
+Use `bdk logs --prod` and `bdk session <sessionId> --prod` for a hosted
+session's runs and logs, [OpenTelemetry](/docs/guides/opentelemetry.md) for traces and metrics, and
 [session traces](/docs/reference/sessions.md#inspect-a-saved-event-stream)
 for a local conversation.
 
@@ -385,8 +422,8 @@ for a local conversation.
 - [GitHub](/docs/guides/github.md): Cursor-event repositories and direct
   webhook delivery
 - [Slack](/docs/guides/slack.md): provision a dedicated hosted Slack app
-- [Host MCP OAuth](/docs/guides/mcp-oauth.md): persist OAuth credentials
-  across hosted replacements
+- [Host MCP OAuth](/docs/guides/mcp-oauth.md): reach OAuth-backed MCP
+  servers from a hosted agent
 - [Troubleshooting](/docs/troubleshooting.md): diagnose failed or stale
   deployments
 
@@ -485,7 +522,7 @@ Configure the judge model in `evals.config.ts`. The
 [Evals reference](/docs/reference/evals.md#judges) owns grader options and
 severity rules.
 
-## Test a conversation or approval
+## Test a conversation
 
 Several `t.send` calls in one case share a session. Assertions on a
 returned turn inspect only that turn, while assertions on `t` inspect
@@ -501,21 +538,6 @@ t.check(followUp.message, includes(/blocker/i));
 t.succeeded();
 ```
 
-For a tool that requires approval, the expected result is a parked turn
-instead of a completed one:
-
-```ts
-await t.send("Apply the approved policy update.");
-t.parked();
-t.calledTool("apply_policy", {
-  input: { verdict: "update" },
-});
-```
-
-Pair an approval case with a safe branch that calls
-`t.notCalledTool("apply_policy")`, so both sides of the decision stay
-protected.
-
 ## Pin realistic inputs
 
 A useful eval changes only when the agent changes. Freeze canonical chat
@@ -1124,16 +1146,13 @@ export default cursorCloudAgents({
     repos: [{ url: "https://github.com/acme/api", startingRef: "main" }],
     autoCreatePR: true,
   },
-  needsApproval: true,
 });
 ```
 
 Launches run under the host's signed-in account (`bdk login`,
 `CURSOR_API_KEY`, or `CURSOR_SERVICE_ACCOUNT_KEY`) and spend its
-cloud-agent budget. Name the repositories the agent may target, and
-keep approval on when you can't.
-
-Launch approval resolves through the serving host.
+cloud-agent budget. Name the repositories the agent may target in
+`cloud.repos`.
 
 ## What the agent can do
 
@@ -1171,7 +1190,6 @@ their own.
 | `cloud`         | Launch defaults for repositories, environment, and pull request behavior.                                                                                                                                                                           |
 | `cloud.repos`   | The repositories the agent may hand work to, with a default branch or pull request for each. Without it, launches run with no repository and the model can't name one, so secrets in `cloud.envVars` never reach a repository you didn't list. |
 | `model`         | The model launched agents run. Omit it to use the account default.                                                                                                                                                                             |
-| `needsApproval` | Park launches and follow-ups for a [human decision](/docs/reference/tools.md#gate-a-tool-on-human-approval). Defaults to `true` when no `cloud.repos` are configured, `false` otherwise.                                                          |
 | `apiKey`        | A Cursor API key to launch with instead of the host's own.                                                                                                                                                                                     |
 
 
@@ -1189,8 +1207,6 @@ Continue with these pages:
 
 - [Extensions](/docs/reference/extensions.md): how mounts, namespaces, and
 overrides work
-- [Gate a tool on human approval](/docs/reference/tools.md#gate-a-tool-on-human-approval):
-where parked launches get approved
 
 ---
 
@@ -2075,9 +2091,8 @@ it does not move this agent onto a Grok Bot runtime.
 
 ## Mount it
 
-List the bots your agent may contact and decide whether each new message
-needs approval. Descriptions teach the model when to choose one bot over
-another.
+List the bots your agent may contact. Descriptions teach the model when
+to choose one bot over another.
 
 ```ts
 // bot/extensions/grokbot.ts
@@ -2094,7 +2109,6 @@ export default cursorGrokBotAgents({
       description: "Routes work and tracks priorities.",
     },
   ],
-  needsApproval: true,
 });
 ```
 
@@ -2111,8 +2125,8 @@ bdk init ./grokbot --template grokbot-agents
 ## Ask a named bot
 
 When someone says, "Ask Plan Keeper whether we should move the picnic,"
-your agent prepares one self-contained message, requests approval, and
-waits for the bot's delivered reply. That reply appears in the current
+your agent prepares one self-contained message, sends it, and waits for
+the bot's delivered reply. That reply appears in the current
 conversation as the consultation result.
 
 The message must include who is asking, the relevant facts, and the
@@ -2149,9 +2163,9 @@ existing memory.
 > Stop Plan Keeper's current turn. Then ask it to compare indoor venues
 > instead of changing the time.
 
-Only `ask` uses `needsApproval`. `check` and `interrupt` execute without
-an approval card, so expose this extension only to callers who may read
-or stop those bot conversations.
+`check` and `interrupt` act on the bot conversation directly, so expose
+this extension only to callers who may read or stop those
+conversations.
 
 ## Configure it
 
@@ -2160,8 +2174,8 @@ list is refused, but a misspelled configured name may create a new empty
 bot on first use. If a result says `created: true`, tell the person and
 check the name before sending more work.
 
-With no `agents` list, any name is allowed and approval defaults on.
-Prefer an explicit list for a shared agent. `list` returns configured
+With no `agents` list, any name is allowed. Prefer an explicit list for
+a shared agent. `list` returns configured
 bots and bots this caller already contacted; it does not enumerate the
 whole account.
 
@@ -2200,8 +2214,6 @@ directory and disable that tool. See
 
 - [Extensions](/docs/reference/extensions.md): namespaces, trust, and
   overlays
-- [Tool approvals](/docs/reference/tools.md#gate-a-tool-on-human-approval):
-  approve asks
 
 ---
 
@@ -2302,7 +2314,6 @@ replay recorded events into hooks.
 | --- | --- |
 | Add context before the model | `instructions.md`, skills, or `workspaceFiles` |
 | Deliver to Slack or a PR | Channel [`events`](/docs/reference/channels.md#events) or packs |
-| Block or approve a tool | [`needsApproval`](/docs/reference/tools.md#gate-a-tool-on-human-approval) |
 | Gate final assistant text | `defineResult` |
 | Gate behavior | [Evals](/docs/evals.md) |
 
@@ -2335,9 +2346,8 @@ deployed.
 
 ## Mount it
 
-Mount Cloud agents with the agent's own repository allowlisted, keep
-launch approval explicit, then mount `improve` with the source
-directory.
+Mount Cloud agents with the agent's own repository allowlisted, then
+mount `improve` with the source directory.
 
 ```ts
 // bot/extensions/cloud.ts
@@ -2353,7 +2363,6 @@ export default cursorCloudAgents({
     ],
     autoCreatePR: true,
   },
-  needsApproval: true,
 });
 ```
 
@@ -2388,8 +2397,8 @@ a narrow behavior request into an unrelated refactor.
 
 ## Follow the source change
 
-The agent requests approval and launches one cloud agent on the
-configured repository and ref. It reports the complete cloud-agent ID
+The agent launches one cloud agent on the configured repository and
+ref. It reports the complete cloud-agent ID
 and URL immediately, then checks the same run instead of launching
 another agent for follow-up work.
 
@@ -2807,9 +2816,7 @@ retries and the turn continues without restarting the agent.
 bdk serve --dir . --dev
 ```
 
-Connect authorizes the process that is running now. It does not seed
-credentials for a future hosted replacement; use `--store` for that
-separate outcome.
+Connect authorizes the process that is running now.
 
 ## Keep privileged tools behind a wrapper
 
@@ -2855,43 +2862,22 @@ export default defineTool({
 ```
 
 The model sees `get_stock`, not the unrestricted inventory server.
-Use this shape when code should own an allowlist, approval, or other
-side-effect gate.
-
-## Keep OAuth across hosted replacements
-
-Declare the server's egress domain and the OAuth secret names, authorize
-from a signed-in machine, then store the credentials and redeploy. The
-next hosted process can reconnect without opening a browser.
-
-```ts
-// bot/agent.ts
-export default defineAgent({
-  hosting: {
-    egressDomains: ["mcp.example.com"],
-    secretNames: [
-      "MCP_OAUTH_INVENTORY_ACCESS_TOKEN",
-      "MCP_OAUTH_INVENTORY_REFRESH_TOKEN",
-      "MCP_OAUTH_INVENTORY_CLIENT_ID",
-    ],
-  },
-});
-```
+Use this shape when code should own an allowlist or another side-effect
+gate.
 
-```text
-bdk mcp oauth inventory --store
-bdk secrets list my-agent
-bdk deploy
-```
+## Use an OAuth server from a hosted agent
 
-`--store` writes deployment secrets; it does not restart the current
-process. Follow the CLI or dashboard prompt to redeploy, then exercise
-the hosted agent.
+Tokens from `mcp oauth` stay in the CLI config directory of the machine
+that authorized them, so a hosted deployment doesn't receive them. For a
+Cursor-managed agent, add the server under MCP in the Cursor dashboard,
+reach it through a
+[`cursorAccount: true` connection](/docs/reference/connections.md#cursor-account-mcp-connection),
+and connect it from **Deployed Agents** in the
+[dashboard](https://cursor.com/dashboard).
 
-These credentials belong to the deployment, not to the person who
-clicked Connect. Anyone able to use that agent can reach the MCP
-capabilities you expose, so keep privileged servers host-only or narrow
-their tool list.
+Anyone able to use that agent can reach the MCP capabilities you
+expose, so narrow the connection's `servers` list and keep privileged
+operations behind a host-side wrapper.
 
 ## Choose where credentials live
 
@@ -2900,8 +2886,8 @@ Use the credential shape that matches who should own access:
 - Choose `cursorAccount: true` for connectors already authorized under
   MCP in the Cursor dashboard. Their tokens stay on the Cursor backend.
 
-- Choose `url` with `oauth: true` when the serve host or hosted
-  deployment should hold OAuth credentials.
+- Choose `url` with `oauth: true` when the machine running `bdk serve`
+  should hold OAuth credentials.
 
 - Choose `url` with static `headers` when the server uses an API key or
   bearer token instead of OAuth.
@@ -2918,7 +2904,7 @@ caller needs a different downstream identity.
   connectors, per-session auth, and tool filtering
 - [CLI reference](/docs/reference/cli.md#mcp-oauth): OAuth command flags
   and browser callback behavior
-- [Deployment](/docs/deployment.md): hosted secrets and egress
+- [Deployment](/docs/deployment.md): hosted egress and secrets
 - [Troubleshooting](/docs/troubleshooting.md): authorization symptoms and
   remedies
 
@@ -3496,9 +3482,9 @@ Author `bot/channels/<id>.ts`. Its routes mount under
 ## Receive a webhook and send the answer back
 
 When a ticket system sends a new message, this endpoint responds with
-`202 Accepted` right away. The agent keeps working after the HTTP
-request ends, and its completed answer appears as a comment on the
-ticket.
+`202 Accepted` and an empty body right away. The agent keeps working
+after the HTTP request ends, and its completed answer appears as a
+comment on the ticket.
 
 ```ts
 // bot/channels/tickets.ts
@@ -3526,7 +3512,7 @@ export default defineChannel<TicketState>({
             title: `Ticket ${body.ticketId}`,
           })
         );
-        return Response.json({ accepted: true }, { status: 202 });
+        return new Response(null, { status: 202 });
       },
     }),
   ],
@@ -3545,6 +3531,12 @@ export default defineChannel<TicketState>({
 SDK. Keeping that write in the event handler means the webhook request
 does not stay open while the model works.
 
+The caller only ever receives that empty `202`. On Cursor-managed
+hosting, the deployment sends it before your handler runs and discards
+whatever the handler returns, so deliver every result, including
+failures, back through the provider's API. See
+[Route responses](/docs/reference/channels.md#route-responses).
+
 ## Keep one conversation per ticket
 
 Without a conversation key, every delivery creates a new session. Add
@@ -3578,10 +3570,11 @@ handler: async (_request, { callTool, send, waitUntil, body }) => {
     ticketId: body.ticketId,
   });
   if (prepared.isError) {
-    return Response.json(
-      { error: prepared.errorMessage ?? "Could not prepare ticket" },
-      { status: 502 }
+    await postTicketComment(
+      body.ticketId,
+      "I couldn't load this ticket, so I didn't draft a reply."
     );
+    return new Response(null, { status: 202 });
   }
 
   waitUntil(
@@ -3593,17 +3586,19 @@ handler: async (_request, { callTool, send, waitUntil, body }) => {
       },
     })
   );
-  return Response.json({ accepted: true }, { status: 202 });
+  return new Response(null, { status: 202 });
 },
 ```
 
 The same `message.completed` handler from the first example delivers
-the answer back to the ticket.
+the answer back to the ticket. When preparation fails, the handler
+reports that on the ticket instead.
 
 ## Routes receive, events deliver
 
 Routes own inbound HTTP. A route validates the request, decides whether
-to start or resume a turn, and responds to the caller. The channel's
+to start or resume a turn, and acknowledges the caller with `202`. The
+channel's
 `events` handlers receive session events later, which is where you
 deliver the model's answer or report a failure to the originating
 system.
@@ -3631,9 +3626,10 @@ route:
 - `callTool` runs an authored server tool without starting a model
   turn.
 
-- `waitUntil` keeps background work alive after the HTTP response. Await
-  `send` when the caller needs the session handle, then call
-  `session.waitForCompletion()` if it also needs the turn outcome.
+- `waitUntil` keeps background work alive after the handler returns.
+  Await `send` when later handler code needs the session handle, such
+  as calling `session.waitForCompletion()` before reporting the turn
+  outcome to the provider.
 
 - `host` provides authenticated services for API calls made by channel
   code.
@@ -3669,17 +3665,24 @@ export default defineChannel({
         const rawBody = await request.text();
         const signature = request.headers.get("x-provider-signature");
         if (!verifyProviderSignature(rawBody, signature)) {
-          return Response.json({ ok: false }, { status: 401 });
+          return new Response(null, { status: 202 });
         }
 
         // Parse and dispatch only after the signature passes.
-        return Response.json({ ok: true });
+        return new Response(null, { status: 202 });
       },
     }),
   ],
 });
 ```
 
+Because a hosted handler runs after the `202`, a delivery with a bad
+signature is dropped silently rather than rejected. When the provider
+sends a shared secret header or signs the raw body with HMAC-SHA256,
+use `sharedSecretAuth()` or `hmacSignatureAuth()` instead. Hosting
+checks those policies before the handler runs and answers a bad
+delivery with `401`.
+
 `publicEndpoint()` only opens this channel's routes. The built-in
 session and tool APIs stay private. See
 [Auth policies](/docs/reference/channels.md#auth-policies) for bearer
@@ -3688,9 +3691,9 @@ tokens and the complete policy reference.
 ## Test locally
 
 Run the agent in development mode, then replay the same payload the
-provider will send. The response should return immediately, and the
-resulting session should appear in the playground while the reply is
-delivered.
+provider will send. The route should answer `202` with an empty body
+right away, and the resulting session should appear in the playground
+while the reply is delivered.
 
 ```text
 bdk serve --dir . --dev
@@ -3864,7 +3867,7 @@ Source: /docs/index.md
 
 The Grok Bot Development Kit (BDK) lets you define, test, and deploy agents
 as code. It uses the Cursor SDK harness that powers Bugbot, Security Review,
-and Approval Bot.
+Approval Bot, and Rollouts.
 
 A BDK project is a folder of Markdown and TypeScript. Combine deterministic
 code with model judgment, then make the bot or agent available in source
@@ -4273,8 +4276,8 @@ trigger, both tool calls, and the verdict.
 
 - [Evals](/docs/evals.md): freeze these two PRs as regression checks so
 prompt changes can't flip a verdict
-- [Tools](/docs/reference/tools.md): more on typed tools, approvals, and
-direct calls
+- [Tools](/docs/reference/tools.md): more on typed tools, dry-run effects,
+and direct calls
 - [GitHub](/docs/guides/github.md): fixtures, forwarding, and pulling
 events from Cursor
 - [Building agents with agents](/docs/building-with-agents.md): have a
@@ -4313,7 +4316,8 @@ export default defineAgent({
 | `description` | string | What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root. |
 | `instructions` | string | Inline instructions. Prefer `instructions.md`; this exists for subagents and generated configs. |
 | `local` | `{ cwd?, workspaceDir?, sandbox? }` | Local harness defaults. See [Local options](#local-options). |
-| `hosting` | `{ egressDomains?, secretNames? }` | Managed-hosting declarations read by `bdk deploy`: the deployment's egress allowlist and the secret names the agent expects. Mounted [extensions](/docs/reference/extensions.md#build-an-extension) add their own. Ignored by local serving. |
+| `persistent` | boolean | Keep one long-lived runtime for the hosted deployment. Defaults to `false`. See [Persistent hosting](#persistent-hosting). |
+| `hosting` | `{ egressDomains?, secretNames?, image? }` | Managed-hosting declarations read by `bdk deploy`: the deployment's egress allowlist, the secret names the agent expects, and a container image for a [persistent agent](#persistent-hosting). Mounted [extensions](/docs/reference/extensions.md#build-an-extension) add their own. Ignored by local serving. |
 | `concurrency` | `{ maxRunningTurns? }` | Agent-wide concurrent turn limit. See [Concurrency](#concurrency). |
 | `builtinTools` | `{ reminders? }` | Framework-provided model-facing tools, opted in per capability. See [Built-in tools](#built-in-tools). |
 | `tools` | `ToolName[]` | Allowlist of built-in harness tools offered to the model. Unset = the model's full standard toolset. See [Harness tools](#harness-tools). |
@@ -4370,6 +4374,30 @@ does not leak rules, skills, or MCP servers into the turn. A standalone git
 root keeps the in-project session workspace. Point `cwd` at a checkout only
 when the agent should inherit that tree.
 
+## Persistent hosting
+
+By default, a hosted deployment starts a runtime when an event arrives
+and stops it when the work ends. Set `persistent: true` to keep one
+long-lived runtime for the deployment instead, with its state directory
+on the runtime's own disk. On a redeploy, the new version starts beside
+the old one on the same state, and the old version stops after the new
+one takes over. Each team can have one persistent deployment. Local
+serving ignores the flag.
+
+```ts
+export default defineAgent({
+  persistent: true,
+  hosting: { image: "incident-bot-base" },
+});
+```
+
+`hosting.image` names a container image that your team pushed with
+`bdk images push`. The agent runs inside that image instead of the
+default Node 22 image. Only persistent agents can use it, and `deploy`
+rejects `hosting.image` on any other agent. A deploy pins the image it
+finds, so after you push a new image under the same name, deploy again
+to pick it up.
+
 ## Harness tools
 
 Use `tools` to limit which built-in Cursor harness tools the model can
@@ -4601,8 +4629,8 @@ available alongside any custom or prebuilt channels.
 
 ## Built-in HTTP channel
 
-The built-in channel serves the session, approval, tool, discovery, and
-health routes. In a multi-agent host, each agent's routes sit under its
+The built-in channel serves the session, tool, and discovery routes. In
+a multi-agent host, each agent's routes sit under its
 slug. See the [HTTP API](/docs/reference/http-api.md) for request and response
 contracts.
 
@@ -4622,14 +4650,13 @@ export default defineChannel({
         message: z.string(),
         prUrl: z.string().url(),
       }),
-      handler: async (_request, { send, body }) => {
-        const session = await send(
-          `${body.message}\n\nPull request: ${body.prUrl}`,
-          {
+      handler: async (_request, { send, waitUntil, body }) => {
+        waitUntil(
+          send(`${body.message}\n\nPull request: ${body.prUrl}`, {
             continuationToken: `pr:${body.prUrl}`,
-          }
+          })
         );
-        return Response.json({ sessionId: session.id });
+        return new Response(null, { status: 202 });
       },
     }),
   ],
@@ -4640,6 +4667,23 @@ The route above is
 `POST /v1/channels/<id>/review`. Calls for the same pull request reuse
 one conversation because they pass the same continuation token.
 
+## Route responses
+
+A custom route acknowledges the caller and nothing more. On
+Cursor-managed hosting, the deployment answers every custom route with
+`202 Accepted` and an empty body as soon as the request arrives, then
+runs the handler. The caller never receives the handler's `Response`,
+so a route can't return a session ID, a computed result, or an error
+status. Requests rejected before the handler runs, such as a missing
+alias token or a failed `sharedSecretAuth` or `hmacSignatureAuth`
+check, still get `401`.
+
+Deliver results through the channel's [`events`](#events) handlers, a
+callback to the system that sent the request, or a tool the turn calls.
+Local `serve` passes the handler's response through, so return
+`new Response(null, { status: 202 })` to keep local calls matching
+hosted ones.
+
 ## Route verbs and schemas
 
 Route paths must begin with `/`. The method helper determines which Zod
@@ -4653,8 +4697,9 @@ schemas the route accepts:
 
 Plain JSON Schema objects don't type-check. Use `z.object({})` or
 `z.unknown()` for an open surface. The host validates the body and query
-before calling the handler, returning `400` on failure; an empty body is
-read as `{}`. Declared schemas also appear in `GET /v1/info` for
+before calling the handler, and an empty body is read as `{}`. A request
+that fails validation never reaches the handler; local `serve` answers it
+with `400`, while a hosted caller has already received its `202`. Declared schemas also appear in `GET /v1/info` for
 playground requests and slash commands.
 
 ## Handler arguments
@@ -4671,7 +4716,7 @@ Each handler receives the Fetch `Request` and a typed arguments object.
 | `auth` | The `AuthContext` returned by the route's auth chain |
 | `requestIp` | The TCP peer address, or `null` |
 | `host` | Shared MCP, provider, storage, telemetry, and reminder services |
-| `waitUntil(promise)` | Track work after the response returns |
+| `waitUntil(promise)` | Keep work running after the handler returns |
 | `sessionUrls(request, sessionId)` | Build absolute playground and trace URLs for this mount |
 | `artifacts` | List or tag [artifacts](/docs/reference/artifacts.md); pass `sessionId` when attributing one |
 
@@ -4723,7 +4768,6 @@ transport controls:
 | `hasContinuationSession(token)` | Check whether a token maps to a session |
 | `isContinuationBusy(token)` | Check whether a turn is active for a token |
 | `interruptContinuation(token)` | Stop the active turn and clear queued coalesced follow-ups |
-| `resolveApproval(...)` | Approve or deny a parked tool call |
 
 ## Auth policies
 
@@ -4762,7 +4806,7 @@ author their own chain, and `--allow-anonymous` swaps it for
 
 | Import | Function | Surface |
 | --- | --- | --- |
-| `@cursor/bdk/channels/slack` | `slackChannel()` | Slack messages, threads, streaming replies, and approvals. See [Slack](/docs/guides/slack.md) |
+| `@cursor/bdk/channels/slack` | `slackChannel()` | Slack messages, threads, and streaming replies. See [Slack](/docs/guides/slack.md) |
 | `@cursor/bdk/channels/github` | `githubChannel()` | GitHub and GitHub Enterprise webhooks. See [GitHub](/docs/guides/github.md) |
 | `@cursor/bdk/channels/gitlab` | `gitlabChannel()` | GitLab.com and self-managed GitLab hooks. See [GitLab](/docs/guides/gitlab.md) |
 | `@cursor/bdk/channels/bitbucket` | `bitbucketChannel()` | Bitbucket Cloud and Data Center hooks. See [Bitbucket](/docs/guides/bitbucket.md) |
@@ -4857,12 +4901,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
 
@@ -4885,7 +4934,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.
@@ -4895,8 +4944,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. |
@@ -5021,28 +5070,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](/docs/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](/docs/deployment.md#verify-a-hosted-turn) for
+finding and following the new session.
 
 ### Call a tool {#call}
 
@@ -5088,9 +5140,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}
 
@@ -5100,7 +5152,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 |
@@ -5110,28 +5162,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}
 
@@ -5155,8 +5212,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}
 
@@ -5386,7 +5443,7 @@ automatic warning.
 ```text
 bdk deploy [--dir <path>] [--slug <slug> | --all] [--team <id>]
   [--repo <https-url>] [--ref <git-ref>] [--path <agent-path>]
-  [--cursor-events-repo <owner/name>]...
+  [--cursor-events-repo <repo>]...
   [--allow-domain <domain>]... [--no-wait] [--json]
 ```
 
@@ -5401,7 +5458,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>` | 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. |
+| `--cursor-events-repo <repo>` | Watch a repository's Cursor events. Write `owner/name` for GitHub and Origin, `gitlab.com/<group>/<project>` for GitLab (subgroups allowed), or `bitbucket.org/<workspace>/<repo>` for Bitbucket. 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. |
@@ -5446,6 +5503,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
@@ -5476,6 +5563,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
@@ -5524,6 +5622,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}
@@ -5540,10 +5656,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>]
 ```
 
@@ -5552,13 +5671,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](/docs/guides/mcp-oauth.md) for the full setup flow.
 
@@ -5802,8 +5919,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({
@@ -5813,8 +5931,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](/docs/guides/mcp-oauth.md). Companion
@@ -6035,7 +6152,8 @@ connection.
 
 ## Related
 
-- [Host MCP OAuth](/docs/guides/mcp-oauth.md): `mcp oauth`, Connect, `--store`
+- [Host MCP OAuth](/docs/guides/mcp-oauth.md): `mcp oauth`, Connect, and
+  hosted agents
 - [Tools](/docs/reference/tools.md): authored tools that wrap MCP connections
 - [Webhooks](/docs/guides/webhooks.md): calling MCP connections from handlers
 - [Peer agents](/docs/guides/agent-to-agent.md): when a specialist is its
@@ -6130,8 +6248,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
@@ -6157,8 +6274,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 |
@@ -6251,6 +6367,19 @@ call, with the nearest value winning.
 Treat agent output as untrusted input: wrap it with `fenceUntrusted` and
 include `EVAL_JUDGE_INJECTION_GUARD` in the judge prompt.
 
+## Judge host
+
+A judge grades by calling a Cursor model. It needs a Cursor credential
+(`bdk login`, `CURSOR_API_KEY`, or `CURSOR_SERVICE_ACCOUNT_KEY`) and a
+judge model. The grading session offers no tools and turns the local SDK
+sandbox off, including any per-user sandbox config on the machine, so the
+same case grades on macOS, a Linux cloud agent, and a Linux CI runner.
+
+Without a credential, or when that credential belongs to a different
+backend than the SDK will call, the case is skipped and the suite
+continues. Without a judge model, the case fails and the assertion names
+where to set one.
+
 ## Datasets and fixtures
 
 Load committed JSON, JSONL, or YAML relative to the project root:
@@ -6702,7 +6831,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](/docs/guides/github.md)                 |
-| Block, approve, or rewrite a tool call                                                | [`needsApproval`](/docs/reference/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](/docs/evals.md)                                                                                             |
 
@@ -6745,8 +6873,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
 
@@ -6758,7 +6887,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.
@@ -6833,15 +6961,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](/docs/reference/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.
@@ -6873,8 +6992,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
@@ -6894,9 +7012,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](/docs/reference/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](/docs/reference/channels.md#route-responses).
 
 ## MCP endpoint
 
@@ -7049,9 +7167,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 |
@@ -7073,8 +7190,6 @@ and paste the token into the token field in the navbar.
 
 - [HTTP API](/docs/reference/http-api.md): the HTTP surface the playground uses
 - [Sessions and streaming](/docs/reference/sessions.md): the streams it renders
-- [Gate a tool on human approval](/docs/reference/tools.md#gate-a-tool-on-human-approval):
-  the approval buttons in context
 
 ---
 
@@ -7315,6 +7430,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 |
 
@@ -7326,6 +7442,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
@@ -7375,14 +7512,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
@@ -7453,7 +7591,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`.
@@ -7509,7 +7647,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](/docs/reference/artifacts.md) was tagged for this session, by host code or `tag_artifact` |
 
@@ -7616,7 +7753,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
@@ -7942,32 +8079,6 @@ use the same exposed names. See
 [MCP connections](/docs/reference/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
@@ -8049,8 +8160,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
 
@@ -8211,7 +8322,7 @@ checked later, and an active turn can be interrupted when the task
 changes.
 
 See [Grok Bot agents](/docs/guides/grokbot-agents.md) for the extension's
-conversation and approval boundaries.
+conversation boundaries.
 
 ## What to edit
 
@@ -8634,10 +8745,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](/docs/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](/docs/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](/docs/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](/docs/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](/docs/deployment.md) for source, credential, and
 redeployment boundaries.
@@ -8661,7 +8779,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](/docs/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](/docs/guides/slack.md) for app setup and engagement
 choices.
@@ -8671,17 +8788,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](/docs/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](/docs/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. |