@cursor/bdk 0.2.14 → 0.2.16

package/docs/guides/grokbot-agents.md

@@ -15,9 +15,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
@@ -34,7 +33,6 @@ export default cursorGrokBotAgents({
       description: "Routes work and tracks priorities.",
     },
   ],
-  needsApproval: true,
 });
 ```
 
@@ -51,8 +49,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
@@ -89,9 +87,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
 
@@ -100,8 +98,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.
 
@@ -139,6 +137,4 @@ directory and disable that tool. See
 ## What's next
 
 - [Extensions](../reference/extensions.md): namespaces, trust, and
-  overlays
-- [Tool approvals](../reference/tools.md#gate-a-tool-on-human-approval):
-  approve asks
+  overlays

package/docs/guides/hooks.md

@@ -98,7 +98,6 @@ replay recorded events into hooks.
 | --- | --- |
 | Add context before the model | `instructions.md`, skills, or `workspaceFiles` |
 | Deliver to Slack or a PR | Channel [`events`](../reference/channels.md#events) or packs |
-| Block or approve a tool | [`needsApproval`](../reference/tools.md#gate-a-tool-on-human-approval) |
 | Gate final assistant text | `defineResult` |
 | Gate behavior | [Evals](../evals.md) |
 

package/docs/guides/improve.md

@@ -15,9 +15,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
@@ -33,7 +32,6 @@ export default cursorCloudAgents({
     ],
     autoCreatePR: true,
   },
-  needsApproval: true,
 });
 ```
 
@@ -68,8 +66,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.
 

package/docs/guides/mcp-oauth.md

@@ -1,6 +1,6 @@
 ---
 title: "Host MCP OAuth"
-description: "Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent."
+description: "Authorize a private MCP server locally, constrain its tools, and choose where its credentials live."
 ---
 
 # Connect a private MCP server with OAuth
@@ -48,9 +48,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
 
@@ -96,43 +94,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.
+Use this shape when code should own an allowlist or another side-effect
+gate.
 
-## Keep OAuth across hosted replacements
+## Use an OAuth server from a hosted agent
 
-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.
+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](../reference/connections.md#cursor-account-mcp-connection),
+and connect it from **Deployed Agents** in the
+[dashboard](https://cursor.com/dashboard).
 
-```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",
-    ],
-  },
-});
-```
-
-```text
-bdk mcp oauth inventory --store
-bdk secrets list my-agent
-bdk deploy
-```
-
-`--store` writes deployment secrets; it does not restart the current
-process. Follow the CLI or dashboard prompt to redeploy, then exercise
-the hosted agent.
-
-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
 
@@ -141,8 +118,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.
@@ -159,6 +136,6 @@ caller needs a different downstream identity.
   connectors, per-session auth, and tool filtering
 - [CLI reference](../reference/cli.md#mcp-oauth): OAuth command flags
   and browser callback behavior
-- [Deployment](../deployment.md): hosted secrets and egress
+- [Deployment](../deployment.md): hosted egress and secrets
 - [Troubleshooting](../troubleshooting.md): authorization symptoms and
   remedies

package/docs/guides/webhooks.md

@@ -16,9 +16,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
@@ -46,7 +46,7 @@ export default defineChannel<TicketState>({
             title: `Ticket ${body.ticketId}`,
           })
         );
-        return Response.json({ accepted: true }, { status: 202 });
+        return new Response(null, { status: 202 });
       },
     }),
   ],
@@ -65,6 +65,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](../reference/channels.md#route-responses).
+
 ## Keep one conversation per ticket
 
 Without a conversation key, every delivery creates a new session. Add
@@ -98,10 +104,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(
@@ -113,17 +120,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.
@@ -151,9 +160,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.
@@ -189,17 +199,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](../reference/channels.md#auth-policies) for bearer
@@ -208,9 +225,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

package/docs/quickstart.md

@@ -304,8 +304,8 @@ trigger, both tool calls, and the verdict.
 
 - [Evals](./evals.md): freeze these two PRs as regression checks so
 prompt changes can't flip a verdict
-- [Tools](./reference/tools.md): more on typed tools, approvals, and
-direct calls
+- [Tools](./reference/tools.md): more on typed tools, dry-run effects,
+and direct calls
 - [GitHub](./guides/github.md): fixtures, forwarding, and pulling
 events from Cursor
 - [Building agents with agents](./building-with-agents.md): have a

package/docs/reference/agent-config.md

@@ -32,7 +32,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](./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](./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). |
@@ -89,6 +90,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

package/docs/reference/channels.md

@@ -12,8 +12,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](./http-api.md) for request and response
 contracts.
 
@@ -33,14 +33,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 });
       },
     }),
   ],
@@ -51,6 +50,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
@@ -64,8 +80,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
@@ -82,7 +99,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](./artifacts.md); pass `sessionId` when attributing one |
 
@@ -134,7 +151,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
 
@@ -173,7 +189,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](../guides/slack.md) |
+| `@cursor/bdk/channels/slack` | `slackChannel()` | Slack messages, threads, and streaming replies. See [Slack](../guides/slack.md) |
 | `@cursor/bdk/channels/github` | `githubChannel()` | GitHub and GitHub Enterprise webhooks. See [GitHub](../guides/github.md) |
 | `@cursor/bdk/channels/gitlab` | `gitlabChannel()` | GitLab.com and self-managed GitLab hooks. See [GitLab](../guides/gitlab.md) |
 | `@cursor/bdk/channels/bitbucket` | `bitbucketChannel()` | Bitbucket Cloud and Data Center hooks. See [Bitbucket](../guides/bitbucket.md) |