@cursor/bdk 0.2.14 → 0.2.16

package/docs/troubleshooting.md

@@ -62,10 +62,17 @@ Match the visible symptom below.
 | The deployment never becomes running | Run `bdk deployment <slug>`, then act on the reported build or startup error. |
 | A secret or egress change has no effect | Confirm the name with `secrets list`, verify the `hosting` block exists on the pushed ref, and follow the CLI or dashboard prompt to redeploy. |
 | Cursor events stopped after redeploy | Each redeploy replaces the watched repositories. Pass every `--cursor-events-repo` value again; without the flag, the deployment watches only its GitHub source repository. |
-| `run --prod` prints a `deliveryId` but no `sessionId` | The deployment accepted the turn and is still starting it, which is expected with or without `--dry-run`. Find the session in the deployment's **Sessions** list in the dashboard, then follow [Verify a hosted turn](./deployment.md#verify-a-hosted-turn). |
-| A high-effort turn runs for several minutes while runs look empty | Turns can take about eight minutes. Rerun `bdk session <sessionId> --prod --slug <slug>`; a growing event count means the turn is still working. Escalate only after about two to three minutes with no new events. |
-| A dashboard link to a single session returns 404 | Check the session with `bdk session <sessionId> --prod --slug <slug>`. |
+| `run --prod` prints a `deliveryId` but no `sessionId` | Expected, with or without `--dry-run`: the session is created when the turn starts. Find it with `bdk logs --prod --once --slug <slug>`, then follow [Verify a hosted turn](./deployment.md#verify-a-hosted-turn). |
+| `session <sessionId> --prod` shows a `running` run with no logs | Runs lag behind events, and a high-effort turn can take several minutes. Rerun the command; a growing event count means the turn is still working. |
+| A dashboard link to a single session doesn't open | Check the session with `bdk session <sessionId> --prod --slug <slug>`. |
+| `chat`, `call`, `sessions`, `cost`, or `mcp` with `--prod` says the command is not supported | Hosted deployments accept `--prod` only on `run`, `session`, `logs`, and `playground`. See [Verify a hosted turn](./deployment.md#verify-a-hosted-turn). |
+| `run --prod --session <sessionId>` reports the session belongs to another channel | `--session` continues only sessions that `run --prod` or `session --prod` started. Reach Slack, SCM, and custom-route sessions through their own channel. |
+| A custom route returns `202` with no body | Expected on managed hosting. The handler runs after the response, so deliver results from the channel. See [Route responses](./reference/channels.md#route-responses). |
 | External HTTP rejects the alias token | Update the caller with the current token. If the token is lost or exposed, run `bdk rotate-token <slug>` and replace it everywhere. |
+| `deploy` says deployments are not available under legacy privacy mode | The team uses Privacy Mode (Legacy), which does not let Cursor store code. Managed hosting is not available with this setting. |
+| `deploy` says persistent deployments are limited to 1 per team | Another deployment of the team already sets `persistent: true`. Remove the setting from one agent, or delete that deployment. |
+| A schedule does not fire on the hosted deployment | Make sure the deployment is running and its release has the schedule. Deploy again with `@cursor/bdk` 0.2.14 or newer. |
+| A request to a custom route gets `429` | The deployment received more requests than its limit. Wait for the time in `Retry-After`, then send the request again. |
 
 See [Deployment](./deployment.md) for source, credential, and
 redeployment boundaries.
@@ -89,7 +96,6 @@ direct webhooks.
 | Logs say `channel idle ... missing credentials` | Run `bdk slack create --dir <agent>`, then check the generated prefix with `bdk slack doctor`. Use `slack init --manual` only for an app you own. |
 | `slack create` is waiting for workspace approval | Keep the CLI running, open the **Request approval** link it prints, and select **Retry** in the dashboard's **Add Slack** wizard after an admin approves. See [Slack](./guides/slack.md#connect). |
 | The bot ignores ordinary channel posts | Configure `engagement.channelPosts`, create the app with `--channel-posts`, and invite it to every allowed channel. |
-| Approval buttons do nothing | Set `toolApprovals: true`, then recreate the app if its interactivity is not enabled. |
 
 See the [Slack guide](./guides/slack.md) for app setup and engagement
 choices.
@@ -99,17 +105,16 @@ choices.
 | What you see | What to do |
 | --- | --- |
 | `must be defineConnection({ url, oauth: true })` | Add `oauth: true` to the named URL connection or correct the connection filename passed to `mcp oauth`. |
-| Local auth works but hosted calls return unauthorized | Complete Connect for the running process, or run `mcp oauth <name> --store` and redeploy for future replacements. |
+| Local auth works but hosted calls return unauthorized | Locally stored OAuth tokens don't reach a deployment. Use a `cursorAccount: true` connection and connect the server from **Deployed Agents** in the dashboard. See [Host MCP OAuth](./guides/mcp-oauth.md#use-an-oauth-server-from-a-hosted-agent). |
 | The model invents `mcp_auth` instead of calling the server | Set `advertiseTools: true` for named local tools, or expose a host-side wrapper through `ctx.host.mcp`. |
 
 See [Host MCP OAuth](./guides/mcp-oauth.md) for the credential lifecycle.
 
-## Schedules, reminders, or approvals stall
+## Schedules or reminders stall
 
 | What you see | What to do |
 | --- | --- |
 | A schedule or reminder never fires under `--dev` | Trigger it through the matching `/v1/dev/schedules/<id>` or `/v1/dev/reminders/<id>` route; development mode does not auto-fire. |
-| A pending approval disappears after restart | Parked approvals do not survive restart. Run the turn again. |
 | A reminder is disarmed with `handler_lost_on_restart` | Recreate handler-form reminders after restart, or use a prompt-form reminder. |
 | The same schedule fires on several self-hosted processes | Enable schedules on one serving process per project and pass `--no-schedules` to the others. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/bdk",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Build, test, and deploy BDK bots and agents as code on Cursor's agent harness.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -30,6 +30,7 @@
     "!dist/internal/managed-delivery.*",
     "!dist/filesystem-executors.*",
     "skills/**/*",
+    "schemas/**/*.json",
     "templates/**/*",
     "!templates/pr-autofixer/README.md",
     "docs/**/*.md",
@@ -286,34 +287,13 @@
       "default": "./package.json"
     }
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json && node scripts/bundle-publish-shims.mjs && node scripts/copy-extension-assets.mjs && pnpm run build:playground && pnpm run docs:build",
-    "build:dist": "node scripts/build-hosted-dist.mjs",
-    "postinstall": "node -e \"try{const p='./scripts/install-cursor-skills.mjs';if(require('fs').existsSync(p))require('child_process').execFileSync(process.execPath,[p],{stdio:'inherit'})}catch{}\"",
-    "build:playground": "vite build --config playground/vite.config.ts",
-    "build:playground:central": "vite build --mode central --config playground/vite.config.ts",
-    "dev:playground": "vite --config playground/vite.config.ts",
-    "check": "oxlint src && tsc --noEmit && tsc --noEmit -p playground/tsconfig.json",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs",
-    "docs:verify-links": "node scripts/verify-docs-links.mjs",
-    "fix": "oxlint --fix src && oxfmt --write --no-error-on-unmatched-pattern src",
-    "test": "vitest run --passWithNoTests",
-    "type-check": "tsc --noEmit && tsc --noEmit -p playground/tsconfig.json",
-    "build-dev": "echo noop",
-    "build-types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
-    "verify-publish": "node scripts/verify-publish-artifacts.mjs",
-    "smoke-publish": "node scripts/smoke-publish-artifact.mjs",
-    "publish-check": "pnpm run build && pnpm run verify-publish && pnpm run smoke-publish"
-  },
   "engines": {
     "node": ">=22.13"
   },
   "dependencies": {
     "@bazel/runfiles": "6.5.0",
-    "@cursor/sdk": "1.0.32",
-    "@modelcontextprotocol/sdk": "1.25.1",
+    "@cursor/sdk": "1.0.35",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "@octokit/auth-app": "^7.2.0",
     "@octokit/rest": "^21.1.1",
     "@opentelemetry/api": "^1.9.0",
@@ -336,7 +316,7 @@
     "croner": "^8.0.1",
     "esbuild": "^0.25.0",
     "javascript-time-ago": "^2.6.4",
-    "js-yaml": "4.1.0",
+    "js-yaml": "4.3.2",
     "minimatch": "^10.2.5",
     "ms": "^2.1.3",
     "proper-lockfile": "^4.1.2",
@@ -346,22 +326,17 @@
     "zod-to-json-schema": "^3.24.5"
   },
   "devDependencies": {
-    "@anysphere/agent-exec": "workspace:*",
-    "@anysphere/agent-store-sync": "workspace:*",
-    "@anysphere/context": "workspace:*",
-    "@anysphere/proto": "workspace:*",
-    "@anysphere/ui": "workspace:*",
     "@braintree/sanitize-url": "7.1.2",
     "@stylexswc/rs-compiler": "^0.18.0",
     "@tanstack/react-virtual": "3.13.23",
     "@types/js-yaml": "4.0.9",
     "@types/ms": "^2.1.0",
-    "@types/node": "catalog:",
+    "@types/node": "22.14.1",
     "@types/pg": "^8.16.0",
     "@types/proper-lockfile": "^4.1.4",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "@typescript/native": "catalog:",
+    "@typescript/native": "npm:typescript@^7.0.2",
     "@vitejs/plugin-react": "^5.1.2",
     "cytoscape": "3.33.3",
     "cytoscape-cose-bilkent": "4.1.0",
@@ -374,12 +349,38 @@
     "react-markdown": "^10.1.0",
     "rehype-highlight": "^7.0.2",
     "remark-gfm": "^4.0.1",
-    "typescript": "catalog:",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
     "vite": "^7.3.0",
     "vitepress": "1.6.4",
     "vitepress-plugin-mermaid": "^2.0.17",
     "vitest": "^4.0.18",
     "yaml": "^2.4.2",
-    "zustand": "^5.0.9"
+    "zustand": "^5.0.9",
+    "@anysphere/agent-exec": "1.0.0",
+    "@anysphere/context": "1.0.0",
+    "@anysphere/ui": "1.0.0",
+    "@anysphere/proto": "1.0.0",
+    "@anysphere/agent-store-sync": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/bundle-publish-shims.mjs && node scripts/copy-extension-assets.mjs && pnpm run build:playground && pnpm run docs:build",
+    "build:dist": "node scripts/build-hosted-dist.mjs",
+    "postinstall": "node -e \"try{const p='./scripts/install-cursor-skills.mjs';if(require('fs').existsSync(p))require('child_process').execFileSync(process.execPath,[p],{stdio:'inherit'})}catch{}\"",
+    "build:playground": "vite build --config playground/vite.config.ts",
+    "build:playground:central": "vite build --mode central --config playground/vite.config.ts",
+    "dev:playground": "vite --config playground/vite.config.ts",
+    "check": "oxlint src && tsc --noEmit && tsc --noEmit -p playground/tsconfig.json",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "docs:verify-links": "node scripts/verify-docs-links.mjs",
+    "fix": "oxlint --fix src && oxfmt --write --no-error-on-unmatched-pattern src",
+    "test": "vitest run --passWithNoTests",
+    "type-check": "tsc --noEmit && tsc --noEmit -p playground/tsconfig.json",
+    "build-dev": "echo noop",
+    "build-types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "verify-publish": "node scripts/verify-publish-artifacts.mjs",
+    "smoke-publish": "node scripts/smoke-publish-artifact.mjs",
+    "publish-check": "pnpm run build && pnpm run verify-publish && pnpm run smoke-publish"
   }
-}
+}

package/schemas/grokbot-answers.schema.json

@@ -0,0 +1,343 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "bdk init --from-grokbot answers",
+  "description": "Decisions for exporting a Grok Bot recipe. Every field is optional: a missing answer takes the default an interactive run offers. Names only, never secret values.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Path or URL of this schema, for editors. Ignored."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 1,
+      "description": "Answers format version."
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$",
+      "title": "Name",
+      "description": "Agent name (also its directory)? Directory: `[A-Za-z0-9][A-Za-z0-9_-]*`, not `v1`/`playground`/`docs`",
+      "x-round": "identity"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "title": "Description",
+      "description": "What does the bot do, in a sentence or two?",
+      "x-round": "identity"
+    },
+    "location": {
+      "type": "string",
+      "minLength": 1,
+      "title": "Location",
+      "description": "Directory to scaffold into?",
+      "x-round": "identity"
+    },
+    "model": {
+      "type": "string",
+      "minLength": 1,
+      "title": "Model",
+      "description": "Model id? Params, not id suffixes: `{ id: \"grok-4.5\", params: [{ id: \"effort\", value: \"high\" }, { id: \"fast\", value: \"true\" }] }`",
+      "x-round": "surface",
+      "default": "grok-4.5",
+      "x-labels": {
+        "grok-4.5": "`grok-4.5` + `effort=high`, `fast=true`"
+      }
+    },
+    "channels": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "slack",
+          "github",
+          "webhook",
+          "schedule"
+        ]
+      },
+      "title": "Channels",
+      "description": "Channels beyond the playground and HTTP? Slack: `skills/setup-slack/SKILL.md`. GitHub: `skills/github/SKILL.md`. No Discord/Teams pack; offer custom webhook.",
+      "x-round": "surface",
+      "x-labels": {
+        "slack": "Slack",
+        "github": "GitHub",
+        "webhook": "custom webhook",
+        "schedule": "schedule"
+      }
+    },
+    "memory": {
+      "type": "string",
+      "enum": [
+        "skill",
+        "kv",
+        "drop"
+      ],
+      "title": "Memory",
+      "description": "What should happen to the bot's memories? skill: a knowledge skill the agent reads on demand. kv: data in bot/lib/memory-seed.json for your own seeding code (BDK has no built-in KV seed). drop: leave them behind.",
+      "x-round": "export",
+      "default": "skill"
+    },
+    "skills": {
+      "type": "object",
+      "properties": {
+        "include": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "title": "Include skills",
+          "description": "Which skills should come along?",
+          "x-round": "export"
+        },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "title": "Exclude skills",
+          "description": "Which skills should stay behind, applied after the include list.",
+          "x-round": "export"
+        }
+      },
+      "additionalProperties": false
+    },
+    "routines": {
+      "type": "object",
+      "properties": {
+        "include": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "title": "Include routines",
+          "description": "Which routines should come along?",
+          "x-round": "export"
+        },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "title": "Exclude routines",
+          "description": "Which routines should stay behind, applied after the include list.",
+          "x-round": "export"
+        }
+      },
+      "additionalProperties": false
+    },
+    "plugins": {
+      "type": "object",
+      "properties": {
+        "include": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "title": "Include plugins",
+          "description": "Which plugins should come along?",
+          "x-round": "export"
+        },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "title": "Exclude plugins",
+          "description": "Which plugins should stay behind, applied after the include list.",
+          "x-round": "export"
+        }
+      },
+      "additionalProperties": false
+    },
+    "connectors": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "auth": {
+            "type": "string",
+            "enum": [
+              "cursor-account",
+              "oauth",
+              "secret"
+            ],
+            "title": "Auth",
+            "description": "How should {plugin} authenticate? cursor-account: tools run through your Cursor account's connector, with no secret in the project. oauth: host OAuth against the server URL (`bdk mcp oauth`). secret: a bearer token read from a named secret.",
+            "x-round": "export",
+            "default": "cursor-account"
+          },
+          "server": {
+            "type": "string",
+            "minLength": 1,
+            "title": "Connector name",
+            "description": "Name of the {plugin} connector in your Cursor account?",
+            "x-round": "export"
+          },
+          "url": {
+            "type": "string",
+            "title": "Server URL",
+            "description": "{plugin} MCP server URL?",
+            "x-round": "export"
+          },
+          "secret": {
+            "type": "string",
+            "title": "Secret name",
+            "description": "Secret that holds the {plugin} token? A name only, like LINEAR_API_KEY. Set the value later with `bdk secrets set`.",
+            "x-round": "export"
+          }
+        },
+        "additionalProperties": false
+      },
+      "description": "How each recipe plugin connects, keyed by plugin slug."
+    },
+    "fillIns": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string",
+          "minLength": 1,
+          "title": "{placeholder}",
+          "description": "{routine}: {placeholder}?",
+          "x-round": "export"
+        }
+      },
+      "description": "Values for recipe placeholders, keyed by routine slug, then placeholder id (e.g. slack_channel). Unfilled placeholders stay in the text."
+    },
+    "secrets": {
+      "type": "object",
+      "properties": {
+        "names": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "title": "Secret names",
+          "description": "Other secret names to list in SECRETS.md? Names only, UPPER_SNAKE_CASE. Names the generated files read are always listed.",
+          "x-round": "export"
+        },
+        "reauth": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "title": "Fresh sign-in",
+          "description": "Which other connectors need a fresh sign-in? OAuth connectors always do; they are listed without asking.",
+          "x-round": "export"
+        }
+      },
+      "additionalProperties": false
+    },
+    "repo": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "title": "Repository",
+          "description": "Repository name? (recorded only; bdk does not create repositories)",
+          "x-round": "export"
+        },
+        "namespace": {
+          "type": "string",
+          "title": "Repository namespace",
+          "description": "Repository owner or namespace? (recorded only)",
+          "x-round": "export"
+        }
+      },
+      "additionalProperties": false
+    },
+    "deploy": {
+      "type": "object",
+      "properties": {
+        "when": {
+          "type": "string",
+          "enum": [
+            "after-review",
+            "now",
+            "scheduled",
+            "never"
+          ],
+          "title": "Deploy",
+          "description": "When should it deploy? (recorded only; bdk does not deploy)",
+          "x-round": "export",
+          "default": "after-review"
+        },
+        "at": {
+          "type": "string",
+          "format": "date-time",
+          "title": "Deploy at",
+          "description": "Deploy at (ISO 8601 with a timezone)?",
+          "x-round": "export"
+        }
+      },
+      "additionalProperties": false
+    },
+    "slack": {
+      "type": "object",
+      "properties": {
+        "app": {
+          "type": "string",
+          "enum": [
+            "new",
+            "move"
+          ],
+          "title": "Slack app",
+          "description": "Mint a new Slack app, or move the bot's existing one?",
+          "x-round": "export",
+          "default": "new"
+        },
+        "cutover": {
+          "type": "string",
+          "enum": [
+            "manual",
+            "after-deploy",
+            "scheduled"
+          ],
+          "title": "Slack cutover",
+          "description": "When should Slack traffic switch to the BDK agent?",
+          "x-round": "export",
+          "default": "manual"
+        },
+        "cutoverAt": {
+          "type": "string",
+          "format": "date-time",
+          "title": "Slack cutover at",
+          "description": "Switch Slack traffic at (ISO 8601 with a timezone)?",
+          "x-round": "export"
+        },
+        "teamPrefix": {
+          "type": "string",
+          "minLength": 1,
+          "title": "Team prefix",
+          "description": "Team prefix the Slack bot name must start with?",
+          "x-round": "export"
+        },
+        "botName": {
+          "type": "string",
+          "minLength": 1,
+          "title": "Slack bot name",
+          "description": "Slack bot display name? Starts with the team prefix and must not contain \"Grok\".",
+          "x-round": "export"
+        },
+        "justification": {
+          "type": "string",
+          "minLength": 1,
+          "title": "Security justification",
+          "description": "Security justification for the Slack app review? What the bot does in Slack and why it needs its scopes. Saved for the Slack app setup.",
+          "x-round": "export"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/skills/create-agent/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   agent. Ask only what the invoking message left open.
 ---
 
-# Create an BDK agent
+# Create a BDK agent
 
 1. **Interview.** Two `AskQuestion` rounds, then a plan gate.
 2. **Scaffold.** `bdk init`, then shape the files.
@@ -33,13 +33,14 @@ on a running host.
 - If `AskQuestion` is missing or the user skips, state defaults
   in one list and proceed.
 
+<!-- interview:start (generated from the bdk init questions; do not edit by hand) -->
 ### Round 1: identity
 
-| Question | Options |
-| --- | --- |
-| **Purpose** | chat assistant · PR / repo automation · domain assistant over APIs/tools · scheduled reporter · Other |
-| **Name** | 2–3 slugs from the purpose + Other. Directory: `[A-Za-z0-9][A-Za-z0-9_-]*`, not `v1`/`playground`/`docs` |
-| **Location** | `./<slug>` (default) · another directory |
+| Question | Options | Guidance |
+| --- | --- | --- |
+| **Purpose** | chat assistant · PR / repo automation · domain assistant over APIs/tools · scheduled reporter · Other |  |
+| **Name** | 2–3 slugs from the purpose + Other | Directory: `[A-Za-z0-9][A-Za-z0-9_-]*`, not `v1`/`playground`/`docs` |
+| **Location** | `./<slug>` (default) · another directory |  |
 
 ### Round 2: surface
 
@@ -48,7 +49,8 @@ on a running host.
 | **Model** | `grok-4.5` + `effort=high`, `fast=true` · Other id | Params, not id suffixes: `{ id: "grok-4.5", params: [{ id: "effort", value: "high" }, { id: "fast", value: "true" }] }` |
 | **Channels** (multi) | playground + HTTP (always on) · Slack · GitHub · custom webhook · schedule | Slack: `skills/setup-slack/SKILL.md`. GitHub: `skills/github/SKILL.md`. No Discord/Teams pack; offer custom webhook. |
 | **MCP** (multi) | none · remote URL · local stdio · Cursor account connectors · Other | One file under `bot/mcp-connections/`. Account file is `account.ts`, never `cursor.ts`. Named local tools need `advertiseTools: true`. Privileged servers go in `bot/host-connections/`. |
-| **Capabilities** (multi) | server tools · agent tools · skills · subagents · hooks · sandbox seeds · approvals · evals (recommend) | Always recommend one smoke eval. |
+| **Capabilities** (multi) | server tools · agent tools · skills · subagents · hooks · sandbox seeds · evals (recommend) | Always recommend one smoke eval. |
+<!-- interview:end -->
 
 Close with the plan and file tree, then "Scaffold it" / "Adjust
 something". Write files only after approval.
@@ -72,13 +74,13 @@ Defaults:
 - `bot/instructions.md`: identity, when to use which tool,
   output shape.
 - One tool per file. Prefer `execution: "server"` + zod
-  `inputSchema`. Gate side effects with `needsApproval: true`.
+  `inputSchema`. Declare `effect: "read"` or `"write"` on each tool.
 - Long prompts: `prompt\`…\`` / `prompt.lines\`…\`` from
   `@cursor/bdk`.
 - Host prep is for evidence (`callTool`, `workspaceFiles`), not
   judgment, formatting, or replies.
-- Remembered state is `ctx.host.kv`. The process is not a
-  persistent box: a module `Map` is empty on the next replica.
+- Remembered state is `ctx.host.kv`. On Cursor hosting, a later
+  event can run in a new process, where a module `Map` starts empty.
   File bytes that must outlive the process go in `ctx.host.files`.
   See `skills/framework-map/SKILL.md`.
 
@@ -154,7 +156,10 @@ project state directory (`--state-root`). That is not harness cwd.
 - **Slack.** `skills/setup-slack/SKILL.md`
 - **GitHub.** `skills/github/SKILL.md`
 - **Custom webhook.** `POST /v1/channels/<id>/<route>`.
-  Loopback-only until you add `bearerAuth(...)`.
+  Loopback-only until you add `bearerAuth(...)`. Hosted callers
+  get an empty `202` before the handler runs, so return
+  `new Response(null, { status: 202 })` and deliver results from
+  the channel's `events`.
 - **Schedules.** Never auto-fire under `--dev`.
   `POST /v1/dev/schedules/<id>`.
 

package/skills/debug/SKILL.md

@@ -2,13 +2,13 @@
 name: bdk-debug
 description: >-
   Diagnose a misbehaving local BDK agent: blank playground,
-  missing sessions, failed reads, webhook 401s, 403/409, lost
-  approvals. Use when a project runs but behaves wrong locally.
+  missing sessions, failed reads, webhook 401s, 403/409. Use when
+  a project runs but behaves wrong locally.
 ---
 
 # Debugging the BDK locally
 
-Local `bdk serve`. Hosted start or health failures:
+Local `bdk serve`. Hosted start failures:
 `docs/troubleshooting.md` and `docs/deployment.md`.
 
 1. **Validate.** `bdk validate --dir <project>`
@@ -27,7 +27,6 @@ Local `bdk serve`. Hosted start or health failures:
 | Answers cite ancestor `AGENTS.md` | Nested checkout. Default `local.cwd` is a cache directory under `~/.cache`. |
 | Model lists IDE `cursor` tools, never MCP | `advertiseTools: true`. Check `GET /v1/info`. |
 | Port 3000 in use | `lsof -iTCP:3000 -sTCP:LISTEN` and kill that pid. |
-| Approval vanished after restart | Parked calls do not survive restart. Re-run. |
 | Schedule / reminder silent under `--dev` | Dev never auto-fires. `POST /<slug>/v1/dev/schedules/<id>`. |
 | `409` on follow-up | Stale `continuationToken`, busy session, or a task session. |
 | `409 session_busy` on `call --session` | Wait, or drop `--session`. |

package/skills/evals/SKILL.md

@@ -84,11 +84,11 @@ export default defineEvalConfig({
 ```
 
 Either `test(t)` or `cases`, not both. `t.send` waits for the turn to
-settle (complete, park, or fail) and returns it; `turn.calledTool(...)`
+settle (complete or fail) and returns it; `turn.calledTool(...)`
 reads only that turn, `t.*` reads the whole run. First-send options:
 `workspaceFiles`, `workspaceDir`.
 
-Gates: `t.succeeded()` / `t.parked()`,
+Gates: `t.succeeded()`,
 `calledTool(name, { input, output, status, count })` / `notCalledTool`,
 `toolOrder`, `maxToolCalls`, `taggedArtifact`, `event` / `notEvent`,
 `t.check(value, includes | equals | matches | similarity | satisfies)`.