@cursor/bdk 0.2.1

package/package.json

@@ -0,0 +1,384 @@
+{
+  "name": "@cursor/bdk",
+  "version": "0.2.1",
+  "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cursor/cursor"
+  },
+  "homepage": "https://cursor.com",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "bdk": "./dist/bin/agent-serve.js",
+    "agent-sdk": "./dist/bin/agent-sdk.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**/*",
+    "!dist/playground-central/**",
+    "!dist/internal/tenant-mcp/**",
+    "!dist/internal/tenant-slack/**",
+    "!dist/internal/grokbot/**",
+    "!dist/extensions/cursor-grokbot-agents/**",
+    "!dist/internal/review-comments*",
+    "!dist/internal/shallow-clone.*",
+    "!dist/internal/managed-delivery.*",
+    "src/**/*",
+    "!src/**/*.test.ts",
+    "!src/internal/tenant-mcp/**",
+    "!src/internal/tenant-slack/**",
+    "!src/internal/grokbot/**",
+    "!src/extensions/cursor-grokbot-agents/**",
+    "!src/internal/review-comments*",
+    "!src/internal/shallow-clone.ts",
+    "!src/internal/managed-delivery.ts",
+    "skills/**/*",
+    "templates/**/*",
+    "!templates/pr-autofixer/README.md",
+    "docs/**/*.md",
+    "!docs/.cursor/**",
+    "!docs/templates/pr-autofixer.md",
+    "scripts/install-cursor-skills.mjs",
+    "package.json",
+    "LICENSE.md",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "exports": {
+    ".": {
+      "anysphere-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./internal/cursor-hosted": {
+      "anysphere-source": "./src/storage-backends/cursor-hosted.ts",
+      "bun": "./dist/storage-backends/cursor-hosted.js",
+      "types": "./dist/storage-backends/cursor-hosted.d.ts",
+      "import": "./dist/storage-backends/cursor-hosted.js",
+      "default": "./dist/storage-backends/cursor-hosted.js"
+    },
+    "./internal/file-kv": {
+      "anysphere-source": "./src/storage-backends/file-kv.ts",
+      "bun": "./dist/storage-backends/file-kv.js",
+      "types": "./dist/storage-backends/file-kv.d.ts",
+      "import": "./dist/storage-backends/file-kv.js",
+      "default": "./dist/storage-backends/file-kv.js"
+    },
+    "./internal/hosted-delivery-protocol": {
+      "anysphere-source": "./src/internal/hosted-delivery-protocol.ts",
+      "bun": "./dist/internal/hosted-delivery-protocol.js",
+      "types": "./dist/internal/hosted-delivery-protocol.d.ts",
+      "import": "./dist/internal/hosted-delivery-protocol.js",
+      "default": "./dist/internal/hosted-delivery-protocol.js"
+    },
+    "./internal/memory-kv": {
+      "anysphere-source": "./src/kv/memory-kv.ts",
+      "bun": "./dist/kv/memory-kv.js",
+      "types": "./dist/kv/memory-kv.d.ts",
+      "import": "./dist/kv/memory-kv.js",
+      "default": "./dist/kv/memory-kv.js"
+    },
+    "./internal/otel": {
+      "anysphere-source": "./src/otel.ts",
+      "bun": "./dist/otel.js",
+      "types": "./dist/otel.d.ts",
+      "import": "./dist/otel.js",
+      "default": "./dist/otel.js"
+    },
+    "./internal/storage": {
+      "anysphere-source": "./src/internal/storage.ts",
+      "bun": "./dist/internal/storage.js",
+      "types": "./dist/internal/storage.d.ts",
+      "import": "./dist/internal/storage.js",
+      "default": "./dist/internal/storage.js"
+    },
+    "./tools": {
+      "anysphere-source": "./src/tools.ts",
+      "types": "./dist/tools.d.ts",
+      "import": "./dist/tools.js",
+      "default": "./dist/tools.js"
+    },
+    "./channels": {
+      "anysphere-source": "./src/channels.ts",
+      "types": "./dist/channels.d.ts",
+      "import": "./dist/channels.js",
+      "default": "./dist/channels.js"
+    },
+    "./channels/slack": {
+      "anysphere-source": "./src/channels/slack/index.ts",
+      "types": "./dist/channels/slack/index.d.ts",
+      "import": "./dist/channels/slack/index.js",
+      "default": "./dist/channels/slack/index.js"
+    },
+    "./channels/github": {
+      "anysphere-source": "./src/channels/github/index.ts",
+      "types": "./dist/channels/github/index.d.ts",
+      "import": "./dist/channels/github/index.js",
+      "default": "./dist/channels/github/index.js"
+    },
+    "./channels/origin": {
+      "anysphere-source": "./src/channels/origin/index.ts",
+      "types": "./dist/channels/origin/index.d.ts",
+      "import": "./dist/channels/origin/index.js",
+      "default": "./dist/channels/origin/index.js"
+    },
+    "./channels/gitlab": {
+      "anysphere-source": "./src/channels/gitlab/index.ts",
+      "types": "./dist/channels/gitlab/index.d.ts",
+      "import": "./dist/channels/gitlab/index.js",
+      "default": "./dist/channels/gitlab/index.js"
+    },
+    "./channels/bitbucket": {
+      "anysphere-source": "./src/channels/bitbucket/index.ts",
+      "types": "./dist/channels/bitbucket/index.d.ts",
+      "import": "./dist/channels/bitbucket/index.js",
+      "default": "./dist/channels/bitbucket/index.js"
+    },
+    "./channels/deployments": {
+      "anysphere-source": "./src/channels/deployments/index.ts",
+      "types": "./dist/channels/deployments/index.d.ts",
+      "import": "./dist/channels/deployments/index.js",
+      "default": "./dist/channels/deployments/index.js"
+    },
+    "./channels/change-monitors": {
+      "anysphere-source": "./src/channels/change-monitors/index.ts",
+      "types": "./dist/channels/change-monitors/index.d.ts",
+      "import": "./dist/channels/change-monitors/index.js",
+      "default": "./dist/channels/change-monitors/index.js"
+    },
+    "./channels/issues": {
+      "anysphere-source": "./src/channels/issues/index.ts",
+      "types": "./dist/channels/issues/index.d.ts",
+      "import": "./dist/channels/issues/index.js",
+      "default": "./dist/channels/issues/index.js"
+    },
+    "./skills": {
+      "anysphere-source": "./src/skills.ts",
+      "types": "./dist/skills.d.ts",
+      "import": "./dist/skills.js",
+      "default": "./dist/skills.js"
+    },
+    "./extensions": {
+      "anysphere-source": "./src/extensions.ts",
+      "bun": "./dist/extensions.js",
+      "types": "./dist/extensions.d.ts",
+      "import": "./dist/extensions.js",
+      "default": "./dist/extensions.js"
+    },
+    "./extensions/cursor-cloud-agents": {
+      "anysphere-source": "./src/extensions/cursor-cloud-agents/extension.ts",
+      "bun": "./dist/extensions/cursor-cloud-agents/extension.js",
+      "types": "./dist/extensions/cursor-cloud-agents/extension.d.ts",
+      "import": "./dist/extensions/cursor-cloud-agents/extension.js",
+      "default": "./dist/extensions/cursor-cloud-agents/extension.js"
+    },
+    "./extensions/cursor-grokbot-agents": {
+      "anysphere-source": "./src/extensions/cursor-grokbot-agents/extension.ts",
+      "bun": "./dist/extensions/cursor-grokbot-agents/extension.js",
+      "types": "./dist/extensions/cursor-grokbot-agents/extension.d.ts",
+      "import": "./dist/extensions/cursor-grokbot-agents/extension.js",
+      "default": "./dist/extensions/cursor-grokbot-agents/extension.js"
+    },
+    "./extensions/improve": {
+      "anysphere-source": "./src/extensions/improve/extension.ts",
+      "bun": "./dist/extensions/improve/extension.js",
+      "types": "./dist/extensions/improve/extension.d.ts",
+      "import": "./dist/extensions/improve/extension.js",
+      "default": "./dist/extensions/improve/extension.js"
+    },
+    "./extensions/jev": {
+      "anysphere-source": "./src/extensions/jev/extension.ts",
+      "bun": "./dist/extensions/jev/extension.js",
+      "types": "./dist/extensions/jev/extension.d.ts",
+      "import": "./dist/extensions/jev/extension.js",
+      "default": "./dist/extensions/jev/extension.js"
+    },
+    "./extensions/slack-communication": {
+      "anysphere-source": "./src/extensions/slack-communication/extension.ts",
+      "bun": "./dist/extensions/slack-communication/extension.js",
+      "types": "./dist/extensions/slack-communication/extension.d.ts",
+      "import": "./dist/extensions/slack-communication/extension.js",
+      "default": "./dist/extensions/slack-communication/extension.js"
+    },
+    "./schedules": {
+      "anysphere-source": "./src/schedules.ts",
+      "types": "./dist/schedules.d.ts",
+      "import": "./dist/schedules.js",
+      "default": "./dist/schedules.js"
+    },
+    "./reminders": {
+      "anysphere-source": "./src/reminders.ts",
+      "types": "./dist/reminders.d.ts",
+      "import": "./dist/reminders.js",
+      "default": "./dist/reminders.js"
+    },
+    "./connections": {
+      "anysphere-source": "./src/connections.ts",
+      "types": "./dist/connections.d.ts",
+      "import": "./dist/connections.js",
+      "default": "./dist/connections.js"
+    },
+    "./hooks": {
+      "anysphere-source": "./src/hooks.ts",
+      "types": "./dist/hooks.d.ts",
+      "import": "./dist/hooks.js",
+      "default": "./dist/hooks.js"
+    },
+    "./memory": {
+      "anysphere-source": "./src/memory.ts",
+      "types": "./dist/memory.d.ts",
+      "import": "./dist/memory.js",
+      "default": "./dist/memory.js"
+    },
+    "./prompt": {
+      "anysphere-source": "./src/prompt.ts",
+      "types": "./dist/prompt.d.ts",
+      "import": "./dist/prompt.js",
+      "default": "./dist/prompt.js"
+    },
+    "./evals": {
+      "anysphere-source": "./src/evals.ts",
+      "types": "./dist/evals.d.ts",
+      "import": "./dist/evals.js",
+      "default": "./dist/evals.js"
+    },
+    "./evals/reporters": {
+      "anysphere-source": "./src/evals/reporters.ts",
+      "types": "./dist/evals/reporters.d.ts",
+      "import": "./dist/evals/reporters.js",
+      "default": "./dist/evals/reporters.js"
+    },
+    "./evals/loaders": {
+      "anysphere-source": "./src/evals/loaders.ts",
+      "types": "./dist/evals/loaders.d.ts",
+      "import": "./dist/evals/loaders.js",
+      "default": "./dist/evals/loaders.js"
+    },
+    "./artifacts": {
+      "anysphere-source": "./src/artifacts.ts",
+      "types": "./dist/artifacts.d.ts",
+      "import": "./dist/artifacts.js",
+      "default": "./dist/artifacts.js"
+    },
+    "./kv": {
+      "anysphere-source": "./src/kv.ts",
+      "bun": "./dist/kv.js",
+      "types": "./dist/kv.d.ts",
+      "import": "./dist/kv.js",
+      "default": "./dist/kv.js"
+    },
+    "./otel": {
+      "anysphere-source": "./src/otel-public.ts",
+      "types": "./dist/otel-public.d.ts",
+      "import": "./dist/otel-public.js",
+      "default": "./dist/otel-public.js"
+    },
+    "./package.json": {
+      "anysphere-source": "./package.json",
+      "bun": "./package.json",
+      "types": "./package.json",
+      "import": "./package.json",
+      "default": "./package.json"
+    }
+  },
+  "scripts": {
+    "build": "tsgo -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 && tsgo --noEmit && tsgo --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": "tsgo --noEmit && tsgo --noEmit -p playground/tsconfig.json",
+    "build-dev": "echo noop",
+    "build-types": "tsgo -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.31",
+    "@modelcontextprotocol/sdk": "1.25.1",
+    "@octokit/auth-app": "^7.2.0",
+    "@octokit/rest": "^21.1.1",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.208.0",
+    "@opentelemetry/core": "^2.6.1",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.208.0",
+    "@opentelemetry/exporter-logs-otlp-proto": "^0.208.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.208.0",
+    "@opentelemetry/exporter-metrics-otlp-proto": "^0.208.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.208.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.208.0",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-logs": "^0.208.0",
+    "@opentelemetry/sdk-metrics": "^2.2.0",
+    "@opentelemetry/sdk-trace-base": "^2.6.1",
+    "@opentelemetry/sdk-trace-node": "^2.6.1",
+    "@opentelemetry/semantic-conventions": "^1.27.0",
+    "@slack/socket-mode": "^2.0.7",
+    "@slack/web-api": "^7.18.0",
+    "croner": "^8.0.1",
+    "esbuild": "^0.25.0",
+    "javascript-time-ago": "^2.6.4",
+    "js-yaml": "4.1.0",
+    "minimatch": "^10.2.5",
+    "ms": "^2.1.3",
+    "proper-lockfile": "^4.1.2",
+    "slackify-markdown": "^5.0.0",
+    "tsx": "^4.0.0",
+    "zod": "^3.25.0",
+    "zod-to-json-schema": "^3.24.5"
+  },
+  "devDependencies": {
+    "@anysphere/agent-store-sync": "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/pg": "^8.16.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@typescript/native-preview": "7.0.0-dev.20260701.1",
+    "@vitejs/plugin-react": "^5.1.2",
+    "cytoscape": "3.33.3",
+    "cytoscape-cose-bilkent": "4.1.0",
+    "dayjs": "1.11.20",
+    "mermaid": "^11.14.0",
+    "pg": "^8.18.0",
+    "pretty-ms": "^9.2.0",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "react-markdown": "^10.1.0",
+    "rehype-highlight": "^7.0.2",
+    "remark-gfm": "^4.0.1",
+    "typescript": "catalog:",
+    "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"
+  }
+}

package/scripts/install-cursor-skills.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * postinstall: copy Agent SDK coding-agent skills into ~/.cursor/skills/agentsdk
+ * so Cursor discovers them after `npm install` / `npx @cursor/bdk`.
+ *
+ * Never fails the package install. No-op in the monorepo source checkout
+ * (package root is not under node_modules) and when dist is missing.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const distEntry = join(packageRoot, "dist", "internal", "install-cursor-skills.js");
+
+try {
+  if (!existsSync(distEntry)) {
+    process.exit(0);
+  }
+  // Windows: Node's ESM loader rejects bare drive-letter paths
+  // (`ERR_UNSUPPORTED_ESM_URL_SCHEME`). file:// is valid on every platform.
+  const { syncCursorSkillsOnPackageInstall } = await import(pathToFileURL(distEntry).href);
+  await syncCursorSkillsOnPackageInstall({ packageRoot });
+} catch {
+  // Swallow: a skill copy must not fail `npm install`.
+}
+
+process.exit(0);

package/skills/create-agent/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: agentsdk-create-agent
+description: >-
+  Scaffold a new BDK agent: short AskQuestion interview, then
+  verify a turn and hand off to hillclimb. Use when creating a new
+  agent. Ask only what the invoking message left open.
+---
+
+# Create an BDK agent
+
+1. **Interview.** Two `AskQuestion` rounds, then a plan gate.
+2. **Scaffold.** `bdk init`, then shape the files.
+3. **Verify.** `validate` / `info` / `call`, then a model turn.
+4. **Channels.** Slack, GitHub, webhook, or schedule as chosen.
+5. **Hillclimb.** `skills/hillclimb/SKILL.md`.
+
+Read `skills/framework-map/SKILL.md` if you have not. CLI is
+`bdk`. Public docs:
+`node_modules/@cursor/bdk/dist/docs/llms.txt` or `/docs/llms.txt`
+on a running host.
+
+## Interview
+
+`AskQuestion`: batched, recommended option first and labeled
+`(recommended)`.
+
+- Mine the invoking message. Target: two rounds, then files.
+- Round 1 is identity. Round 2 is the surface, tailored by round 1.
+- Multi-select for channels, MCP, capabilities. Other where a
+  custom answer is plausible.
+- Ask decisions, not how to build it. File layout, tool names,
+  env prefix, and eval shape are yours.
+- If `AskQuestion` is missing or the user skips, state defaults
+  in one list and proceed.
+
+### 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 |
+
+### Round 2: surface
+
+| Question | Options | Guidance |
+| --- | --- | --- |
+| **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. |
+
+Close with the plan and file tree, then "Scaffold it" / "Adjust
+something". Write files only after approval.
+
+## Fill the blanks
+
+| Purpose | Shape |
+| --- | --- |
+| Slack chat | `slackChannel({ envPrefix })` + suggested prompts. `bdk slack create` mints the bot. Prefix: `skills/setup-slack/SKILL.md` |
+| PR review with host prep | Channel `callTool` into a trimmed workspace `pr/` tree |
+| GitHub automation | `githubChannel()` hooks, replay fixtures |
+| Domain assistant | Server tools + one MCP connection + a skill |
+| Wrap an existing pipeline | GitHub `{ task }` over a thin `bot/lib/` loop |
+
+Defaults:
+
+- Instructions + 1–2 tools + chosen channels + one smoke eval.
+- `local.cwd` stays outside a monorepo checkout (default: a cache
+  directory under `~/.cache`) unless the agent must inherit that
+  tree.
+- `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`.
+- 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.
+  File bytes that must outlive the process go in `ctx.host.files`.
+  See `skills/framework-map/SKILL.md`.
+
+### Deterministic-path budget
+
+Default to instructions and skills. Promote to TypeScript only
+when it earns the left column:
+
+| Code owns | Model owns |
+| --- | --- |
+| Side-effect gates (approve, deploy, post) | Human-facing output to a stated shape |
+| Dedupe of external writes (`ctx.host.kv`) | Summarizing, classifying, wording |
+| Auth and signature checks | What to do next from ground truth |
+| Evidence seeding | Soft-failure retries |
+| Hard API caps | Formatting under those caps |
+
+Smells: prose builders in `.ts` (write `.md`); `bot/lib/` +
+`tools/` dwarfing instructions + skills on a first cut.
+
+## Scaffold
+
+```bash
+bdk init ./<slug>
+```
+
+`init` writes the project, runs `npm install`, and may wait on
+`login`. Then shape it:
+
+1. `defineAgent` with the chosen model.
+2. Real `instructions.md`. Replace `echo.ts`.
+3. Chosen `channels/`, `mcp-connections/`, `skills/`,
+   `subagents/<id>/` (needs `description`), `schedules/`, `hooks/`.
+   Slack: `bdk slack create --dir ./<slug> --name "<Name>"`,
+   not a hand-written channel. Manual Slack app:
+   `bdk slack init --manual` (Slack CLI, or paste at
+   api.slack.com).
+4. `evals/evals.config.ts` with `maxConcurrency: 20` (required;
+   cap 200) plus `evals/**/*.eval.ts`. Assert `t.succeeded()` +
+   `t.calledTool(...)`. API: `skills/evals/SKILL.md`.
+
+Stay on deps the BDK already ships (`zod`,
+`@modelcontextprotocol/sdk`, `tsx`).
+
+## Verify
+
+```bash
+bdk validate --dir ./<slug>
+bdk info --dir ./<slug> --json
+bdk call <tool> --dir ./<slug> --input '{…}'
+bdk eval --dir ./<slug> --list
+npx tsc --noEmit -p ./<slug>
+```
+
+tsx does not typecheck. Tool `execute` must return JSON-shaped
+values: object literals or `type` aliases, not `interface` types.
+
+Model turns need a Cursor credential (`CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE`, then `CURSOR_SERVICE_ACCOUNT_KEY`, then `bdk login`). Without one, finish the
+key-free checks, confirm `run` fails with only the API-key error,
+and hand these over:
+
+```bash
+bdk run --dir ./<slug> --message "<fixture prompt>"
+bdk serve --dir ./<slug> --mode single --dev
+# http://127.0.0.1:3000/playground
+bdk eval --dir ./<slug>
+```
+
+Serve only this agent's directory. Session files land in the
+project state directory (`--state-root`). That is not harness cwd.
+
+## Channel setup
+
+- **Slack.** `skills/setup-slack/SKILL.md`
+- **GitHub.** `skills/github/SKILL.md`
+- **Custom webhook.** `POST /v1/channels/<id>/<route>`.
+  Loopback-only until you add `bearerAuth(...)`.
+- **Schedules.** Never auto-fire under `--dev`.
+  `POST /v1/dev/schedules/<id>`.
+
+## Hillclimb handoff
+
+Once a smoke turn passes, agree fixtures, success criteria, and a
+freeze line, then follow `skills/hillclimb/SKILL.md`. Seed from
+the smoke session under the project state directory. GitHub:
+snapshot `bdk github replay ... --dry-run --out fixtures/github`.
+
+Do not deploy or post to real Slack/GitHub beyond the smoke the
+user asked for. If the plan grows past ~10 files, cut scope.
+Re-check the budget at hand-off.

package/skills/debug/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: agentsdk-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.
+---
+
+# Debugging the BDK locally
+
+Local `bdk serve`. Hosted start or health failures:
+`docs/troubleshooting.md` and `docs/deployment.md`.
+
+1. **Validate.** `bdk validate --dir <project>`
+2. **Info.** `curl -s http://127.0.0.1:3000/<slug>/v1/info | jq .`
+3. **Trace.** Session events under the project state directory.
+   Then match the table.
+
+| Symptom | Fix |
+| --- | --- |
+| Playground blank / "no agents" | Start `serve`. A built SPA with no backend serves nothing. |
+| Playground UI edits do not show | Open the URL `serve --dev` prints as `playground`, not `:3000`. |
+| Sessions on disk, empty playground list | List is the calling principal. `--dev` or `--allow-anonymous` shows all. Or `?sessionId=ses_...`. |
+| Built-in read/grep fail; retry loops | Bun. Rerun under Node. The tell is `NGHTTP2_FRAME_SIZE_ERROR`. |
+| `github forward` 401s; hook created | Blank `GITHUB_TOKEN`/`GH_TOKEN`. Relay uses `gh` login. |
+| `Hook already exists` | One forwarder per repo. `forward --dir <parent>`. |
+| 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`. |
+| `403` on stream | Wrong principal. Same auth as create; beyond loopback send `--bearer-token`. |
+| Works on loopback, blocked via tunnel | `localDevStrict()` rejects forwarded headers. Use `--bearer-token`. Never `--allow-anonymous` with account MCP. |
+| Slack `channel idle … missing credentials` | Expected. `slack doctor --prefix <PREFIX>`. |
+| Immediate API-key error | Model turns need a Cursor credential (`CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE`, then `CURSOR_SERVICE_ACCOUNT_KEY`, then `bdk login`). |
+| `validate` clean, CI typecheck fails | tsx skipped types. JSON-shaped returns; `type` not `interface`. |
+
+Count `action.result` by `toolName` before blaming latency.
+`turn.failed` + `"turn interrupted"` is a follow-up or stop, not a
+crash. `bdk trajectory --events <file>` renders a saved
+trace.