@cursor/bdk 0.2.4 → 0.2.6

package/README.md

@@ -1,1185 +1,107 @@
 # Grok Bot Development Kit (BDK)
 
-Grok Bot Development Kit (BDK) uses the `@cursor/bdk` package and `bdk`
-binary.
+The Grok Bot Development Kit (BDK) is how Cursor builds bots and
+agents. It is the open-source version of the engine behind Bugbot,
+Security Review, and Approval Bot.
 
-Install the package to obtain the binary, then create and run a bot:
+A BDK project is a folder of Markdown and TypeScript. Combine model
+judgment with deterministic code, then make the result available in
+source control, Slack, issue trackers, and Cursor.
 
-```text
-npm install --global @cursor/bdk
-bdk init ./my-bot
-cd my-bot
-bdk dev
-```
-
-BDK is a filesystem-first framework for building and serving Cursor bots and
-agents. Define a project as ordinary files: Markdown for prose and TypeScript
-for typed behavior. The framework discovers those files, compiles them into a
-manifest, and serves the project over channels with the Cursor SDK
-(`@cursor/sdk`) and harness as the execution engine.
-
-**User-facing documentation lives in [`docs/`](./docs/README.md)**.
-After the package publishes, open it with `bdk docs`, or at `/docs` on every
-running `bdk serve` host. It covers getting started, concepts, guides (Slack,
-GitHub webhooks, approvals, and agent-to-agent), evals, hillclimbing,
-deployment, troubleshooting, and reference pages for each folder. This README
-is the compact package reference.
-
-Instead of one large configuration object, each part of the agent gets a
-clear home. Instructions go in one file, tools in one folder, channels in
-another; a file's location says what it does, and its path gives it its
-name. There is no registry to keep in sync: add the file and it is
-discovered, move or rename it and its identity moves with it.
-
-```text
-my-agent/
-├── package.json
-└── bot/
-    ├── agent.ts             # runtime config: the Cursor model
-    ├── instructions.md      # the always-on system prompt
-    ├── tools/
-    │   └── get_weather.ts   # one typed tool per file
-    ├── skills/
-    │   └── forecast.md      # on-demand procedures (SKILL.md convention)
-    ├── mcp-connections/
-    │   └── linear.ts        # tools from external MCP servers
-    ├── subagents/
-    │   └── researcher/      # specialist child agents
-    ├── channels/
-    │   └── webhook.ts       # HTTP surfaces beyond the built-in session API
-    ├── hooks/
-    │   └── audit.ts         # observe the runtime event stream
-    ├── storage.ts           # optional durable storage
-    ├── artifacts.ts         # optional artifact kinds and retention
-    ├── result.ts            # optional host commit on the final assistant text
-    ├── otel.ts              # optional OpenTelemetry export
-    ├── playground/          # optional custom playground tool chips
-    ├── schedules/
-    │   └── heartbeat.md     # cron-driven runs
-    ├── sandbox/workspace/   # files seeded into each session's workspace
-    └── lib/                 # shared code (import-only, never discovered)
-```
-
-Scaffold a starter project with `bdk init ./my-agent`. It writes
-`AGENTS.md`, `.gitignore`, `package.json`, `tsconfig.json`, `bot/agent.ts`,
-`bot/instructions.md`, `bot/tools/echo.ts`, and `bot/hooks/memory.ts`.
-The project serves immediately and type-checks with `npm run check`. From
-there, grow it folder by folder. The
-[docs](./docs/README.md) walk a weather agent from a single
-`get_weather` tool through skills, channels, evals, and deployment.
-
-Serve one project with `bdk serve --dir ./my-agent --dev`, or point
-`serve` at a folder of agent projects to mount every child under its
-directory name.
-
-## Node only: do not run under Bun
-
-When published, `@cursor/bdk` requires **Node 22.13+** and supplies the
-`bdk` binary. Do not run it under Bun: Bun's HTTP/2 client
-corrupts the Cursor SDK's local harness tool-result streams
-(`NGHTTP2_FRAME_SIZE_ERROR`), so every built-in read/grep the model
-makes fails and turns degrade into failed-read retry loops.
-
-## Serving many agents at once
-
-Point `serve` at a **folder of agent projects** and it hosts all of them on
-one port, each under its own slug (its directory name):
-
-```text
-bdk serve --dir ./agents --dev
-# 2 agents listening
-#   playground  <printed URL>
-```
-
-`serve` always uses multi-agent layout by default: agents are mounted under
-`/<slug>/v1/*` with an index at `/`. A directory that is itself an agent
-project is mounted under its directory name. Opt into the unslugged
-`/v1/*` surface with `serve(dir, { mode: "single" })`.
-
-In multi-agent mode:
-
-- `GET /` is a web index listing every agent, linking to its playground;
-  `GET /v1/agents` is the JSON equivalent.
-- `GET /v1/health` is host-level liveness (for ALB/ECS); each agent also has
-  `/<slug>/v1/health`.
-- each agent is fully namespaced: `/<slug>/v1/session`,
-  `/<slug>/v1/session/:id/stream`, `/<slug>/playground`, `/<slug>/v1/info`,
-  custom channels at `/<slug>/v1/channels/<id>`, etc.
-- sessions are isolated per agent (`<stateRoot>/<slug>/`), and the playground
-  gains a "← all agents" link back to the index.
-- point the terminal client at a slug:
-  `bdk chat --url http://127.0.0.1:3000/weather-agent`.
-
-Slugs come from directory names and must match `[A-Za-z0-9][A-Za-z0-9_-]*`
-and not collide with the reserved `v1` / `playground` / `docs` path
-segments.
-
-## Agent-to-agent: every agent is an MCP server
-
-Every mounted agent also serves the **Model Context Protocol** over
-streamable HTTP at `/<slug>/v1/mcp` (or `/v1/mcp` in single mode), so other
-agents, and any MCP client, can delegate work to it. The surface is
-stateless (session identity travels in tool arguments) and runs the same
-route auth chain as the session API. Tools:
-
-| Tool | Behavior |
-| ---- | -------- |
-| `ask` | Send a message; runs a model turn in **this agent's own session, tools, and context** and returns `{ status, sessionId, reply }`. Omit `sessionId` for a fresh session; pass it to follow up. |
-| `check` | Wait for / poll a running session (`waitSeconds: 0` for a non-blocking poll). |
-| `call_tool` | Call one of the agent's deterministic server tools directly (no model turn). Registered only when the agent has server tools. |
-
-Waits are bounded (~50s, below MCP client request timeouts): a long turn
-returns `status: "running"` and the caller keeps waiting with `check`.
-Sessions created this way live on the `mcp` channel, bind to the calling
-principal, and show up in the playground and `GET /v1/sessions` like any
-other session.
-
-**Peer MCP connections** make delegation first-class between agents on the
-same host. Author an MCP connection whose transport is a peer slug:
-
-```ts
-// agents/concierge/bot/mcp-connections/weather.ts
-import { defineConnection } from "@cursor/bdk/connections";
+## Why use it
 
-export default defineConnection({
-  agent: "weather-agent",
-  description: "Delegate weather questions to the weather agent.",
-});
-```
-
-The parent model then sees the peer's `ask` / `check` (/ `call_tool`) tools
-under the `weather` server name: subagent-style delegation where the peer
-keeps its **own** instructions, tools, MCP connections, and sessions. Peer URLs
-resolve when the server starts, so `run` and `eval` ephemeral ports work.
-Local-runtime turns, host-side `ctx.host.mcp`, and channel handlers use
-loopback under the default `localDevStrict()` auth. Turns that do not run on
-the serve host require `--public-url`; without it, BDK omits peers from those
-turns and prints a warning.
-
-Unknown peer slugs and self-references fail at serve startup. Peers require
-the multi-agent layout (each agent mounted under its slug). There is no
-cross-host loop protection yet: if agent A's instructions delegate to B and
-B's delegate back to A, they can recurse. Scope each agent's delegation
-instructions narrowly (the concierge above delegates *weather questions* to
-`weather-agent`, not everything).
-
-```text
-bdk serve --dir ./agents --dev
-bdk chat --url http://127.0.0.1:3000/concierge \
-  --message "What's the weather in Paris right now?"
-# concierge → weather.ask → weather-agent's own session/tools → reply
-```
-
-## Quick start
-
-A minimal agent is two files.
+- **Bots and agents live in your repo.** Review, version, and ship
+  instructions, tools, and evals with the rest of your code.
 
-`bot/instructions.md`:
+- **Cursor runs the loop.** Your project gets Cursor's models, tool
+  calling, skills, MCP, and subagents.
 
-```md
-You are a concise assistant. Use tools when they are available.
-```
-
-`bot/agent.ts`:
-
-```ts
-import { defineAgent } from "@cursor/bdk";
-
-export default defineAgent({
-  // optional: defaults to grok-4.5 with effort=high and fast=true
-});
-```
+- **Use it where you work.** Trigger a project from source-control
+  events, Slack threads, custom webhooks, or schedules.
 
-Serve it (turns run on the Cursor harness, so the host needs a Cursor
-credential: sign in once, or export an API key):
+- **Test normal TypeScript.** Add evals and unit tests without a
+  separate configuration language.
 
-```text
-bdk login          # browser sign-in; mints + stores a revocable API key
-# or: export CURSOR_API_KEY=key_...
-bdk serve --dir . --port 3000
-# e.g. playground at http://127.0.0.1:3000/<dirname>/playground
-```
+- **Choose where it runs.** Deploy to Cursor-managed hosting or run
+  the process on your infrastructure.
 
-Start a session, then follow the NDJSON event stream (replace `<slug>` with
-the agent directory name):
+## When to use BDK
 
-```bash
-curl -X POST http://127.0.0.1:3000/<slug>/v1/session \
-  -H 'content-type: application/json' \
-  -d '{"message":"What can you do?"}'
-# {"ok":true,"sessionId":"ses_...","continuationToken":"http:..."}
+| | Cursor Automations | Grok Bot | BDK |
+| --- | --- | --- | --- |
+| **Use for** | Repeatable jobs driven by a prompt and trigger | Interactive agents you work with in Cursor | Agents that need custom code, integrations, tests, or deployment choices |
+| **You define** | A prompt, model, and trigger in the dashboard | Instructions, skills, and connected tools in the app | A versioned Markdown and TypeScript project |
+| **Where it runs** | Cursor-managed | Cursor-managed | Cursor-managed hosting or your infrastructure |
+| **Choose it when** | The job fits a schedule or event trigger | You want an agent without creating a software project | You want deterministic code around model judgment and a project your team can review and test |
 
-curl -N http://127.0.0.1:3000/<slug>/v1/session/ses_.../stream
-# {"type":"session.started",...}
-# {"type":"message.appended","data":{"delta":"I can","text":"I can"},...}
-# {"type":"message.completed",...}
-# {"type":"turn.completed",...}
-# {"type":"session.waiting",...}
-```
+## Get started
 
-Send a follow-up to the same durable session with the continuation token
-from the previous response (each accepted follow-up rotates it):
+BDK requires Node 22.13 or newer. Install `@cursor/bdk`, create a
+project, and start the development server:
 
 ```bash
-curl -X POST http://127.0.0.1:3000/<slug>/v1/session/ses_... \
-  -H 'content-type: application/json' \
-  -d '{"continuationToken":"http:...","message":"Shorter, please."}'
-```
-
-Inspect the discovered surface at any time:
-
-```text
-bdk info --dir .        # or GET /<slug>/v1/info on a running server
-bdk validate --dir .    # exit non-zero on error diagnostics
-```
-
-## Terminal client
-
-`bdk chat` talks to a running server over the same public API and
-renders the reply live: streamed text, tool calls, and a per-turn usage
-footer. Pass `--json` for a compact trajectory (same shape as `run`).
-
-```text
-# interactive REPL against a local server
-bdk chat --url http://127.0.0.1:3000
-
-# one-shot (good for piping / scripts)
-bdk chat --url http://127.0.0.1:3000 --message "Weather in Paris?"
-
-# JSON trajectory (for coding agents / scripts)
-bdk chat --url http://127.0.0.1:3000 --message "hello" --json
-
-# against an authed server
-bdk chat --url https://my-agent.example.com --bearer-token "$TOKEN"
-```
-
-## Agent loop
-
-Coding agents should prefer the JSON-first commands: edit files → inspect
-→ run a turn → assert with filesystem evals.
-
-```text
-bdk validate --dir .
-bdk info --dir . --json
-
-# Ephemeral server + one (or more) turns; JSON trajectory on stdout
-bdk run --dir . --message "What's the temperature in NYC?"
-
-# Optional event log for later summarization
-bdk run --dir . --message "..." --events /tmp/run.ndjson
-bdk trajectory --events /tmp/run.ndjson
-
-# Scaffold (or print the setup guide with no directory)
-bdk init ./my-agent
-bdk init
-```
-
-`run` / `eval` boot a temporary server on port `0` with a temp `stateRoot`
-outside the project so session workspaces do not inherit ambient monorepo
-`AGENTS.md` / `.cursor` rules. Pass `--url` to target an already-running
-agent instead.
-
-### Evals
-
-Author cases under `evals/**/*.eval.ts` with `defineEval`. Drive the
-agent and assert inline:
-
-```ts
-import { defineEval, includes } from "@cursor/bdk/evals";
-
-export default defineEval({
-  description: "Uses get_weather for temperature questions.",
-  tags: ["smoke"],
-  async test(t) {
-    await t.send("What's the temperature in NYC?");
-    t.succeeded();
-    t.calledTool("get_weather");
-    t.check(t.reply, includes(/°|[FC]/));
-  },
-});
-```
-
-Case id is the path under `evals/` for a single-`test` file, or
-`<fileId>/<case.id>` when using `cases` in one file.
-
-Use `t.judge` when wording needs an LLM grader. The built-in JUnit and
-Artifacts reporters write CI results and per-case evidence.
-
-Every project with evals needs `evals/evals.config.ts` with a required
-`maxConcurrency` (hard-capped at 200 due to model provider request limits).
-Playground batches are in-memory by default; declare an `evals` table in
-`bot/storage.ts` (`defineStorage`) to keep them across serve restarts.
-Optional `maxPlaygroundRuns` caps how many batches the playground /
-`/v1/dev/evals*` history keeps (default 20):
-
-```ts
-import { defineEvalConfig } from "@cursor/bdk/evals";
-
-export default defineEvalConfig({
-  maxConcurrency: 20,
-  // Optional: playground /v1/dev/evals history window (default 20):
-  // maxPlaygroundRuns: 50,
-});
-```
-
-```text
-bdk eval --dir . --list
-bdk eval --dir . --json
-bdk eval --dir . weather/nyc         # one datapoint
-bdk eval --dir . weather             # whole file
-bdk eval --dir . weather forecast    # multiple files
-bdk eval --dir . --tag smoke
-```
-
-See [`docs/`](./docs/README.md) for the full documentation set,
-[`AGENTS.md`](./AGENTS.md) for the coding-agent guide, and
-[`skills/`](./skills/) for task-shaped guides (create an agent, author
-evals, hillclimb, GitHub webhooks, Slack setup, debugging).
-
-## Web playground
-
-Every served agent ships with a built-in playground. The default multi-agent
-mode serves it at `http://127.0.0.1:3000/<slug>/playground`.
-`--mode single` uses `http://127.0.0.1:3000/playground`. The playground
-uses the same public HTTP API for manual testing and demo recordings:
-
-- chat with the agent and watch text/reasoning stream live, rendered as
-  markdown (headings, lists, tables, blockquotes, links) with syntax
-  highlighting for fenced code blocks (C-like languages, Python, shell,
-  and diffs),
-- invoke custom channels as **slash commands** in the composer (e.g. a
-  `/drive https://github.com/org/repo/pull/1` channel route). Routes from `GET /v1/info`,
-  with `/help` and autocomplete; same HTTP as the Agent surface **Try**
-  buttons,
-- see tool calls inline (args, output, error state) as `actions.requested`
-  / `action.result` events arrive,
-- browse the sessions you own (chat, custom-channel, and schedule
-  task sessions) and replay their event streams. In `--dev` on loopback,
-  or with `--allow-anonymous`, the list includes every principal,
-- dispatch schedules by hand in dev mode,
-- inspect the discovered agent surface (tools, skills, subagents, MCP
-  connections, channels, hooks),
-- flip on the raw NDJSON pane to see the exact wire events.
-
-`bdk serve` serves the playground bundle. Disable it with
-`--no-playground` (CLI) or `serve(dir, { playground: false })`. When
-serving many agents, each has its own playground at `/<slug>/playground`
-and `/` is an index of them all (see "Serving many agents at once").
-`serve --dev` prints a playground URL; open that URL if the UI looks stale.
-
-To share the server beyond localhost (a tunnel, a LAN address, a phone),
-pass `--bearer-token <secret>` (or `serve(dir, { authToken })`). That
-replaces the loopback-only default with `bearerAuth(secret)` on every
-channel that doesn't author its own auth. The default
-`localDevStrict()` only admits direct loopback callers, rejects
-proxy-forwarding headers (`X-Forwarded-For`, `X-Real-IP`, `Forwarded`,
-`X-Forwarded-Host`), and requires a loopback `Host` header, so
-same-host reverse proxies / tunnels do not accidentally re-expose the
-default routes. Open the playground on the remote device and paste the
-token into the top-right field.
-
-Session follow-up, stream, and list routes also bind to the principal that
-created the session (`403` when a different admitted principal addresses
-someone else's handle).
-
-## How it runs on the Cursor harness
-
-Each session is one Cursor SDK agent. Turns run on this host.
-
-Authored files reach the model as instructions, tools, skills, and
-workspace seed files. Sessions and their event
-streams survive server restarts. Reconnect with `?startIndex=` to
-replay.
-
-## Folder structure
-
-### `agent.ts`
-
-```ts
-import { defineAgent } from "@cursor/bdk";
-
-export default defineAgent({
-  model: {
-    id: "grok-4.5",
-    params: [
-      { id: "effort", value: "high" },
-      { id: "fast", value: "true" },
-    ],
-  }, // optional; this is the default
-});
-```
-
-`model` accepts a Cursor model id string or `{ id, params }`. When omitted
-on the root agent, BDK defaults to `grok-4.5` with `effort=high`
-and `fast=true`.
-
-Turns use the Cursor SDK local harness on this machine. Authored tools,
-skills, and sandbox seeds apply.
-
-### Instructions
-
-`bot/instructions.md` is the always-on system prompt (required on the
-root agent). When the prompt needs to be generated, use
-`bot/instructions.ts` with `defineInstructions({ markdown })` or a plain
-string default export, or split prose across a `bot/instructions/`
-directory (composed in filename order).
-
-### Tools (`bot/tools/*.ts`)
-
-One file per tool; the filename is the tool name the model sees.
-
-`execution` chooses where the tool body runs:
-
-| Value | Behavior |
-| ----- | -------- |
-| `"server"` (default) | Runs on the serve host. Requires `execute`. |
-| `"agent"` | Materialized into the agent environment as a shell script. Requires `script` (JSON on stdin, result on stdout). |
-
-Server tool (default):
-
-```ts
-import { defineTool } from "@cursor/bdk/tools";
-import { z } from "zod";
-
-export default defineTool({
-  description: "Get the current weather for a city.",
-  // execution: "server", // default
-  inputSchema: z.object({ city: z.string() }),
-  async execute({ city }, ctx) {
-    return { city, condition: "Sunny", temperatureF: 72 };
-  },
-});
-```
-
-A server tool can call `decide` from
-[`@cursor/bdk/extensions/jev`](./docs/guides/jev.md) for a risk tier or
-a finding gate. Jev is not the turn model on `defineAgent`.
-
-Human-in-the-loop: set `needsApproval: true` (or an
-`(input) => boolean` predicate on validated args) so the host parks the in-flight
-tool call until a human approves or denies. The turn stays running; the
-stream emits `action.approval_requested` / `action.approval_resolved`.
-
-**Resolve surfaces** (park is always on when `needsApproval` is set):
-
-- Playground Approve / Deny buttons
-- HTTP: `POST /v1/session/:sessionId/approvals/:callId` with
-  `{"decision":"approve"|"deny"}`
-- **Slack** (opt-in channel surface): set `toolApprovals: true` on
-  `slackChannel`, and enable `interactivity` in the Slack app
-  manifest:
-
-```ts
-import { slackChannel } from "@cursor/bdk/channels/slack";
-
-export default slackChannel({
-  credentials: { /* … */ },
-  toolApprovals: true, // posts Block Kit Approve/Deny + routes clicks
-});
-```
-
-Or compose the builders yourself:
-
-```typescript
-import {
-  buildDefaultEvents,
-  buildToolApprovalEvents,
-  slackChannel,
-} from "@cursor/bdk/channels/slack";
-
-export default slackChannel({
-  deliverDefaults: false,
-  // Required so Socket Mode routes Approve/Deny clicks when composing
-  // buildToolApprovalEvents by hand (toolApprovals: true also enables this).
-  interactivity: true,
-  events: {
-    ...buildDefaultEvents({ credentials }),
-    ...buildToolApprovalEvents({ credentials }),
-  },
-});
-```
-
-In `--dev`, the playground can list and stream Slack sessions, and Approve/Deny
-parked tools on those sessions (audit `by` records the HTTP caller). That bridge
-does **not** open cross-owner approval for HTTP sessions. Production and
-bearer-auth hosts stay strict: Slack resolve must come from Slack interactivity
-(or a matching principal).
-
-`--allow-anonymous` is for trusted-network demos only. Every HTTP caller shares
-the same `anonymous` principal. Prefer `--bearer-token` when the host is shared.
-
-Slack cards show **redacted / truncated** args for Block Kit limits; execution
-still uses the full validated tool input. Review sensitive tools in the
-playground or a private surface when args may exceed the card.
-
-Example tool:
-
-```ts
-export default defineTool({
-  description: "Post a weather alert to ops.",
-  needsApproval: true,
-  inputSchema: z.object({
-    city: z.string(),
-    message: z.string(),
-  }),
-  async execute({ city, message }) {
-    return { posted: true, city, message };
-  },
-});
-```
-
-Approvals are only supported for `execution: "server"` tools on the
-`local` runtime. Exact resume of a parked SDK tool call does **not**
-survive host process restart. Pending approvals left after a crash are
-treated as interrupted.
-Agent tool (runs in the Cursor agent workspace):
-
-```ts
-import { defineTool } from "@cursor/bdk/tools";
-import { z } from "zod";
-
-export default defineTool({
-  description: "Echo a message from the agent workspace.",
-  execution: "agent",
-  inputSchema: z.object({ message: z.string() }),
-  script: `#!/usr/bin/env bash
-set -euo pipefail
-message=$(python3 -c 'import json,sys; print(json.load(sys.stdin)["message"])')
-printf '%s\\n' "$message"
-`,
-});
+npm install --global @cursor/bdk
+bdk init ./my-bot
+cd my-bot
+bdk dev
 ```
 
-`inputSchema` is a Zod schema (validated and typed for server tools) or a
-plain JSON Schema object (forwarded as-is). `outputSchema` advertises a
-structured result schema. The host doesn't validate results against it.
-Plain objects fill `structuredContent` automatically. Envelope results set
-it explicitly next to `content` and `isError`. For server tools, `ctx` carries
-`{ toolCallId, session, workspaceDir }`.
-
-#### Deterministic tool calls
-
-Server tools can also be called **deterministically**. You pick the tool
-and the input, no model turn decides anything. The input is validated
-against the tool's schema and `execute` runs in-process; the result comes
-back exactly as the model would receive it. No Cursor API key is needed.
-
-Over HTTP (`POST /v1/tools/:toolName`, same auth chain as the session API):
+For a one-off scaffold without a global install:
 
 ```bash
-curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/get_weather \
-  -H 'content-type: application/json' \
-  -d '{"input":{"city":"NYC"}}'
-# {"ok":true,"toolName":"get_weather","callId":"tool_get_weather_...",
-#  "isError":false,"result":{...},"durationMs":12}
+npx @cursor/bdk init ./my-bot
 ```
 
-From the CLI (boots an ephemeral server unless `--url` targets a running
-one):
+Open the project in Cursor. BDK uses `bot/` for the agent and keeps
+`evals/` at the project root:
 
 ```text
-bdk call get_weather --dir . --input '{"city":"NYC"}'
-bdk call get_weather --url http://127.0.0.1:3000/<slug> --input '{"city":"NYC"}'
-```
-
-Programmatically, `callTool(toolName, input, options?)` is available on the
-serve handle, on channel route handlers and `onStart` args, and on schedule
-`run` handlers, so a channel can mix deterministic tool calls with model
-turns (e.g. fetch PR metadata deterministically, then `send()` the review
-prompt):
-
-```ts
-const outcome = await handle.callTool("get_weather", { city: "NYC" });
-// { toolName, callId, isError, result, durationMs }
-```
-
-By default the tool runs against an ephemeral scratch workspace,
-materialized like a session workspace (AGENTS.md, skills, seed files)
-and removed once the call returns. Pass `sessionId` (body field over
-HTTP, `--session` on the CLI, `options.sessionId` programmatically) to
-run it inside an existing session instead: the tool sees that session's
-info and materialized workspace, and the call is recorded on the
-session's event stream as `actions.requested` / `action.result` under a
-per-call `turnId`. That call is visible in the playground, NDJSON
-trace, and trajectories like any model-initiated call. Session-bound
-writes are serialized with model turns: while a turn is running a
-write-effect call is rejected with `409 session_busy`, while a
-read-effect call runs alongside the turn.
-
-Unknown tools are rejected with the available tool names, `execution:
-"agent"` tools cannot be called on the host (400), schema-invalid input is a
-400 before the tool body runs (zod schemas validate; plain JSON Schema
-inputs pass through unvalidated, matching the model path), and a tool body
-that throws is reported as `isError: true` with the same
-`{ content, isError }` envelope the model would see.
-
-### Skills (`bot/skills/*`)
-
-Skills follow the `SKILL.md` convention: model-loadable procedures the
-harness advertises by description and loads on demand. Author them as flat
-markdown (`skills/forecast.md`, optional `description` frontmatter. The
-first body line is the fallback), packaged directories
-(`skills/research/SKILL.md` plus `references/…`, which require `description`
-frontmatter), or TypeScript (`defineSkill` from
-`@cursor/bdk/skills`) when content must be generated.
-
-### MCP connections (`bot/mcp-connections/*.ts`)
-
-```ts
-import { defineConnection } from "@cursor/bdk/connections";
-
-export default defineConnection({
-  url: "https://mcp.linear.app/mcp",
-  headers: { authorization: `Bearer ${process.env.LINEAR_TOKEN}` },
-});
-```
-
-The filename becomes the MCP server name. `{ command, args, env, cwd }`
-declares a local stdio server instead. `{ tools }` authors TypeScript
-handlers that BDK packages as stdio MCP for the agent
-environment, including a repo-less cloud VM. `{ agent: "<slug>" }` declares a
-**peer MCP connection** to another agent mounted on the same serve host (see
-"Agent-to-agent: every agent is an MCP server").
-
-`{ cursorAccount: true }` declares a **Cursor account MCP connection**: the
-agent gets the MCP connectors the signed-in Cursor account already
-authorized (dashboard → MCP) with zero token plumbing. Every tool executes
-on the Cursor backend with the account's stored OAuth credentials; raw
-tokens never reach the serve host, session workspaces, or traces. Omit
-`servers`, or pass `servers: "*"`, to forward every connected HTTP/SSE
-connector. Pass `servers: ["Linear", ...]` to expose only named connectors.
-
-```ts
-// bot/mcp-connections/account.ts: every connected connector
-export default defineConnection({
-  cursorAccount: true,
-  advertiseTools: true,
-});
-// same, spelled out:
-export default defineConnection({
-  cursorAccount: true,
-  servers: "*",
-  advertiseTools: true,
-});
-// only Linear:
-export default defineConnection({
-  cursorAccount: true,
-  servers: ["Linear"],
-  advertiseTools: true,
-});
-```
-
-Name the file `account.ts`. `cursor.ts` collides with the IDE `cursor` MCP
-namespace. `advertiseTools: true` puts connector tools on local turns by
-name.
-
-Requirements and behavior:
-
-- The host must be signed in (`bdk login`, `CURSOR_API_KEY`, or `CURSOR_SERVICE_ACCOUNT_KEY`);
-  `serve` fails fast at startup otherwise, and logs each connector's live
-  status (`connected` / `needsAuth` / `error`) as it starts.
-- Local turns and host-side calls go through a loopback bridge route guarded
-  by a per-boot secret.
-- Backend execution covers the account's HTTP/SSE servers; stdio servers
-  cannot run server-side (author a `{ command }` MCP connection for those).
-- **Exposure**: whoever can talk to the agent can drive these connectors
-  (they are ordinary agent tools). `serve` refuses to start when
-  `--allow-anonymous` is combined with Cursor account MCP connections; use
-  `--bearer-token` on shared hosts.
-
-Every MCP connection is available in three places:
-
-1. the Cursor agent, via SDK `mcpServers`
-2. the serve host, for in-process tools via `ctx.host.mcp`
-3. channel / schedule handlers, via `args.host.mcp` (deterministic; no agent loop)
-
-```ts
-export default defineTool({
-  description: "Search Linear issues.",
-  inputSchema: z.object({ query: z.string() }),
-  async execute({ query }, ctx) {
-    return ctx.host.mcp.callTool("linear", "list_issues", { query });
-  },
-});
-```
-
-```ts
-// bot/channels/webhook.ts: call MCP directly from a webhook
-POST("/sync", {
-  bodySchema: z.object({}),
-  handler: async (_req, { host }) => {
-    const result = await host.mcp.callTool("linear", "list_issues", {});
-    return Response.json(result);
-  },
-});
-```
-
-`host.mcp.names()` lists MCP connection names; `listTools(name)` and
-`callTool(name, tool, args)` open the client lazily on first use.
-
-### Subagents (`bot/subagents/<id>/`)
-
-A subagent is its own directory with the same `agent.ts` +
-`instructions.md` shape. `description` is required. The parent model reads
-it to decide when to delegate, and `model` is optional (`inherit` by
-default). On the Cursor harness, subagents run as SDK custom subagents:
-they inherit the parent's execution surface, so per-subagent `tools/`,
-`skills/`, and `mcp-connections/` are reported as warnings and ignored for now.
-
-### Extensions (`bot/extensions/<ns>.ts`)
-
-An extension is a package of agent contributions mounted with one file;
-the filename is the namespace and every contribution appears as
-`<ns>__<name>`. A Cursor plugin mounts the same way with `cursorPlugin`.
-
-```ts
-// bot/extensions/ci.ts
-import ci from "@acme/ci-triage";
-export default ci({ org: "acme", token: process.env.BUILDKITE_TOKEN! });
-
-// bot/extensions/notion.ts
-import { cursorPlugin } from "@cursor/bdk/extensions";
-export default cursorPlugin({
-  path: "plugins/notion-workspace",
-  variables: { NOTION_TOKEN: process.env.NOTION_TOKEN! },
-});
-```
-
-Mount as a directory (`bot/extensions/<ns>/extension.ts`) to overlay
-any slot; `disableTool()`, `disableConnection()`, and `disable()` remove
-a contribution. Mounting a plugin trusts it like authored code. Details
-in [Extensions](./docs/reference/extensions.md).
-
-### Channels (`bot/channels/*.ts`)
-
-The **built-in HTTP channel** is always mounted (under `/<slug>` in the
-default multi-agent layout; at the server root with `mode: "single"`):
-
-- `POST /v1/session`: start a session (`{"message": "..."}`; returns
-  `sessionId` + `continuationToken`)
-- `POST /v1/session/:sessionId`: follow-up (`{"message", "continuationToken"}`;
-  rotates the token; works for any chat session including custom channels like
-  `drive`; `409` on stale tokens or task sessions;
-  `403` if the caller is not the session owner)
-- `GET /v1/session/:sessionId/stream?startIndex=N`: replay + live NDJSON
-  (same owner check)
-- `GET /v1/session/:sessionId/approvals`: pending human-in-the-loop
-  tool approvals for the session
-- `POST /v1/session/:sessionId/approvals/:callId`: approve or deny
-  (`{"decision":"approve"|"deny"}`)
-- `GET /v1/sessions`: sessions owned by the calling principal
-- `POST /v1/tools/:toolName`: call a server tool deterministically
-  (`{"input": {...}, "sessionId"?}`; see "Deterministic tool calls")
-- `GET /v1/health`, `GET /v1/info`: liveness and the manifest snapshot
-
-**Custom channels** declare their own routes (mounted under
-`/v1/channels/<id>`), observe stream events for the sessions they own, and
-control their continuation-token format (e.g. a thread id):
-
-```ts
-import { defineChannel, POST } from "@cursor/bdk/channels";
-import { z } from "zod";
-
-export default defineChannel({
-  routes: [
-    POST("/message", {
-      description: "Enqueue a chat turn on this channel",
-      bodySchema: z.object({
-        message: z.string(),
-        thread: z.string().optional(),
-      }),
-      handler: async (_req, { send, body }) => {
-        const { message, thread } = body;
-        // `auth` defaults to the request principal resolved by the auth chain.
-        const session = await send(message, {
-          continuationToken: thread, // stable key: same thread, same session
-        });
-        return Response.json({ sessionId: session.id });
-      },
-    }),
-  ],
-  events: {
-    "message.completed"(event, channel, ctx) {
-      // deliver the reply back to the surface that owns this channel
-    },
-  },
-});
-```
-
-`GET` requires a Zod `querySchema` and `POST` / `PUT` / `PATCH` require a
-Zod `bodySchema` at compile time. Plain JSON Schema objects will not
-type-check. Use `z.object({})` or `z.unknown()` when the surface is
-intentionally open. Schemas are validated by the host before the handler
-runs (handlers get typed `args.body` / `args.query`) and projected on
-`GET /v1/info` so the playground Agent surface can **Try** the route, and
-so the composer can offer matching **slash commands** (e.g. `/drive`).
-
-Route handlers receive a Fetch `Request` and helpers: `send`, `getSession`,
-`receive` (cross-channel hand-off), `params`, `requestIp`, `auth`, `host`
-(shared host services: MCP / GitHub / Slack; same as tool `ctx.host`), and
-`waitUntil`. Channel `state` declares initial per-session adapter state,
-persisted across events; handlers receive it on `channel.state`.
-
-**Auth**: channel routes and the session API run an auth-policy chain
-(`auth` on the channel). The host index, docs, and health routes run no
-auth. The default policy is `[localDevStrict()]`: direct loopback
-callers only, with proxy-forwarding headers and non-loopback `Host`
-rejected, so nothing is exposed publicly until you add real auth
-(`bearerAuth(...)`, a custom policy, or the explicit `allowAll()`).
-
-**Slack** (`@cursor/bdk/channels/slack`): a platform channel pack
-that defaults to **Socket Mode**. Author `bot/channels/slack.ts` with
-`slackChannel()`:
-
-```ts
-import { slackChannel } from "@cursor/bdk/channels/slack";
-
-// Single agent: SLACK_BOT_TOKEN + SLACK_APP_TOKEN
-export default slackChannel();
-
-// Multi-agent serve: one Slack app (and token pair) per agent
-export default slackChannel({ envPrefix: "WEATHER_AGENT" });
-// → WEATHER_AGENT_SLACK_BOT_TOKEN + WEATHER_AGENT_SLACK_APP_TOKEN
-```
-
-Transport uses `@slack/socket-mode` + `@slack/web-api`. Socket Mode starts
-on channel mount when both tokens are present; otherwise the channel stays
-**idle** (`channel idle … missing credentials`) so multi-agent serve can
-mount agents that do not have Slack tokens configured yet.
-
-The pack dispatches via `waitUntil`, streams assistant text (`chat.startStream` /
-`appendStream` / `stopStream`) with postMessage fallback, shows rotating status
-+ tool thinking steps, and sets thread titles / suggested prompts. Handlers may
-return a prepared `message` or `workspaceFiles` to host-prepare PR
-reviews from an `@mention`.
-
-**Engagement:** by default the agent is summoned, never proactive. It
-dispatches only on `app_mention` and DMs. Channel watch is an explicit opt-in:
-
-```ts
-export default slackChannel({
-  envPrefix: "TRIAGE",
-  engagement: {
-    // mentions / directMessages default to true
-    channelPosts: {
-      allow: ["#triage-alerts"], // explicit allowlist only; no wildcard
-      posts: "top-level",       // default: never dispatch on thread replies
-      debounceMs: 15_000,       // optional: let rapid edits settle
-    },
-  },
-  onChannelPost: async (ctx, message) => {
-    // Same contract as onAppMention: return null to skip.
-    return message.markdown.length > 20 ? {} : null;
-  },
-});
-```
-
-Watched posts dispatch with the same thread-scoped principal as mentions
-(so a later `@mention` continues the session) plus an
-`engagement: "channel_post"` auth attribute. Posts that mention the bot are
-left to the `app_mention` path; bot-authored posts never dispatch; deleting
-a post inside the debounce window cancels its dispatch. The Slack app must
-subscribe to `message.channels` / `message.groups`
-(`bdk slack create --channel-posts`) and be a member of each watched channel. Watched channels surface in
-`info` via `meta.slackChannelPosts`.
-
-**HITL compose:** park/resume is independent (`needsApproval` on tools). Opt in
-to Slack delivery with `toolApprovals: true` (or spread
-`buildToolApprovalEvents` into `events` and set `interactivity: true` on
-`slackChannel` so Approve/Deny buttons resolve). That posts Block Kit
-Approve/Deny cards and routes Socket Mode `interactive` clicks to
-`resolveApproval`. Enable `interactivity: true` on
-`buildSlackManifest` when you use that surface. Threads bind with
-`continuationToken = channelId:threadTs`. Dev and prod are
-**separate Slack apps**. Requires `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`
-(App-Level Token with `connections:write`).
-
-`bdk slack create` mints one dedicated bot and writes
-`<DIR>_SLACK_*` plus `envPrefix` from the directory name. Keep the
-channel file as `slack-app.ts` when the same app should carry tool
-approvals or channel watch.
-
-For Socket Mode apps (channel watch / approvals), run
-`bdk slack create`. It opens the dashboard wizard, creates and
-installs the app, and writes the token pair to `.env.local`. To own the
-Slack app yourself, run `bdk slack init --manual` and paste the
-manifests at api.slack.com.
-
-CLI (`bdk slack …`; guided setup in `skills/setup-slack/SKILL.md`):
-
-```text
-bdk slack create --dir ./my-agent           # dashboard wizard (dev app)
-bdk slack create --dir ./my-agent --prod    # prod app
-bdk slack init --manual --dir ./my-agent    # manifests for api.slack.com
-bdk slack setup
-bdk slack doctor --prefix MY_AGENT
-```
-
-**GitHub** (`@cursor/bdk/channels/github`): a webhook channel pack
-(Eve-compatible dispatch). Author `bot/channels/github.ts` with
-`githubChannel()` and declare inbound hooks:
-
-```ts
-import { defaultGitHubAuth, githubChannel } from "@cursor/bdk/channels/github";
-
-export default githubChannel({
-  botName: "my-agent", // or GITHUB_APP_SLUG
-  cursorAccount: {
-    repos: ["owner/repo"],
-    // permissions?: "read" | "pr-write" | "contents-write" (default pr-write)
-  },
-  onPullRequest: (ctx, pr) =>
-    pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
-  onCheckSuite: (ctx, suite) =>
-    suite.conclusion === "failure" ? { task: () => triage(ctx) } : null,
-});
-```
-
-Mounts at `POST /<slug>/v1/channels/github`. When a webhook secret is set the
-channel verifies `X-Hub-Signature-256` before parsing (the HMAC becomes the
-request auth); without one it stays loopback-only (`localDevStrict()`), except
-under `serve --dev`, which admits unsigned loopback deliveries so
-`gh webhook forward` and fixtures work with zero config. Hooks return
-`{ auth }` to start a model turn as the actor, `{ task }` for host-side work
-(202 ACK, runs past GitHub's ~10s timeout), or `null` to skip.
-
-**Testing GitHub agents locally.** `cursorAccount` uses the host Cursor
-credential (`bdk login`, `CURSOR_API_KEY`, or
-`CURSOR_SERVICE_ACCOUNT_KEY`) for both Cursor SCM events and a refreshing
-repo-scoped GitHub credential used
-by `ctx.github`, `ctx.host.github`, and child `gh` commands. Default
-`permissions: "pr-write"` covers comments without `contents:write`; opt up to
-`"contents-write"` when the agent must push or post merge-box checks.
-Enabling `progress.commitStatus` opts hosted `cursorAccount` up to that
-tier so github-proxy mints `checks:write`. Without `cursorAccount`, API
-auth prefers GitHub App installation tokens when `GITHUB_APP_ID` /
-`GITHUB_APP_PRIVATE_KEY` (and an installation id) are set, then falls back to
-`GITHUB_TOKEN` / `GH_TOKEN` or `gh auth login`. The channel publishes the
-webhook events it dispatches on (derived from the declared hooks, or pinned
-via `webhookEvents`), so `bdk github …` can forward live
-deliveries with zero hand-listing. It wraps [`gh webhook
-forward`](https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing):
-
-```text
-# One-time: gh + the cli/gh-webhook extension
-bdk github doctor --install
-
-# Terminal A: serve the agent (dev accepts unsigned loopback deliveries)
-bdk serve --dir ./my-agent --dev
-
-# Terminal B: forward this repo's deliveries to the discovered github channel
-# (URL + events auto-derived; repo inferred from the git remote). No secret
-# needed against a --dev server; set GITHUB_WEBHOOK_SECRET to verify signatures.
-bdk github forward --dir ./my-agent
-
-# Inspect what would be forwarded (URL + events per agent)
-bdk github events --dir ./agents --json
-
-# Forward to EVERY discovered github channel at once
-bdk github forward --dir ./agents
-```
-
-When several channels match (e.g. a folder of agent projects with more than
-one github channel), one forwarder fans out to all of them: `gh webhook
-forward` runs against a local proxy that re-posts each raw (still-signed)
-delivery to the channels whose event set matches. This is required. GitHub
-allows only one forwarder per repo, and `gh webhook forward` targets a single
-URL, so N processes would collide with `Hook already exists`.
-
-`gh webhook forward` needs **admin** on the repo (or org owner for `--org`).
-It registers a real webhook, and authenticates its relay with the GitHub CLI's
-own login. If `GITHUB_TOKEN` / `GH_TOKEN` is set in your env, deliveries fail
-with **HTTP 401** (the relay rejects env tokens); blank it for the command
-(`GITHUB_TOKEN= GH_TOKEN= bdk github forward …`) or `unset` it.
-`bdk github doctor` / `forward` warn when they detect this.
-
-Pass `--repo owner/repo` / `--org ORG` to override the inferred target,
-`--events a,b,c` to narrow the set, `--url` for a custom endpoint (e.g. a
-tunnel), and `--slug` / `--channel` to forward to just one of several agents.
-Against a `--dev` server no secret is needed; set `GITHUB_WEBHOOK_SECRET` (or
-`--secret`) to exercise signature verification (required for a non-dev target).
-Only one forwarder per repo/org at a time (a GitHub limitation). Fixture replay
-still works too: `POST` a saved payload with an `x-github-event` header (no
-signature needed in `--dev`).
-
-**No admin? Hillclimbing? Use `github replay`.** `gh webhook forward` needs repo
-admin and a live event. `bdk github replay <pr_url>` instead **reads**
-the PR (pull access is enough: no admin, no relay, and `GITHUB_TOKEN` is fine)
-and synthesizes GitHub-shaped payloads it POSTs straight at the channel:
-
-```text
-# Replay a pull_request delivery for a PR to the discovered channel
-bdk github replay https://github.com/owner/repo/pull/123 --dir ./my-agent
-
-# Replay everything the channel listens for (its declared events), CI failing
-bdk github replay owner/repo#123 --dir ./my-agent --events '*' --conclusion failure
-
-# Inspect payloads without POSTing (and snapshot them as reusable fixtures)
-bdk github replay owner/repo#123 --dir ./my-agent --events '*' --dry-run --out fixtures/github
-```
-
-`--events` defaults to `pull_request` (`*` = the channel's declared events);
-`--action` / `--conclusion` / `--comment` / `--context` tune each synthesized
-event; `--secret` (or `GITHUB_WEBHOOK_SECRET`) signs them so a secret-configured
-channel verifies. Because replay sends a clean, signed loopback request, it
-passes both the `localDevStrict()` and `allowAll()`+signature auth modes, and
-it's fully deterministic, which is what hillclimbing wants.
-
-**Production alternative: pull from Cursor (`--cursor-events`).** If the
-Cursor GitHub App is on the repo, `serve --cursor-events --repo owner/repo`
-long-polls `/v0/scm-events` with the host's Cursor account (no public URL /
-repo admin). Offset + consumer id live under `<state-root>/cursor-events/`.
-The stream is read as your Cursor user, so the flag **requires a signed-in
-host** (`bdk login`, `CURSOR_API_KEY`, `CURSOR_SERVICE_ACCOUNT_KEY`, or `serve({ apiKey })`).
-Serve fails fast rather than starting with a relay that can never receive
-events.
-
-### Hooks (`bot/hooks/*.ts`)
-Observe-only subscribers that run after each event is recorded: audit
-logs, metrics, mirroring transcripts into your own store. Keys are event
-types (or `*`); handler errors are logged, never fatal.
-
-### Schedules (`bot/schedules/*`)
-
-Markdown form (fire-and-forget task session):
-
-```md
----
-cron: "0 9 * * 1-5"
----
-
-Pull open incidents and post a summary to the metrics endpoint.
-```
-
-Handler form (full control, hand off to a channel):
-
-```ts
-import { defineSchedule } from "@cursor/bdk/schedules";
-import webhook from "../channels/webhook.js";
-
-export default defineSchedule({
-  cron: "*/30 * * * *",
-  async run({ receive, waitUntil, appAuth, mcp }) {
-    // optional: await mcp.callTool("units", "celsius_to_fahrenheit", { value: 0 });
-    waitUntil(
-      receive(webhook, {
-        message: "Check for new critical alerts. Report only when there are any.",
-        auth: appAuth,
-      })
-    );
-  },
-});
-```
-
-Cron expressions are standard 5-field, evaluated in UTC with minute
-granularity. In production mode (`bdk serve`) schedules fire on
-cadence; in dev mode (`--dev`) they never fire automatically. Dispatch one
-by hand, exactly once, through the same path production uses:
+my-bot/
+├── package.json
+├── bot/
+│   ├── agent.ts
+│   ├── instructions.md
+│   ├── tools/
+│   ├── skills/
+│   ├── mcp-connections/
+│   ├── subagents/
+│   ├── channels/
+│   ├── hooks/
+│   └── schedules/
+└── evals/
+```
+
+Describe the bot or agent in Cursor, or edit the files yourself.
+
+## Start from a template
+
+Pass a template to `bdk init` when one matches your goal:
+
+| Template | Capability |
+| --- | --- |
+| `grokbot-agents` | Consult named Grok Bot agents |
+| `security-reviewer` | Review pull requests for exploitable bugs |
+| `thermo-quality-review` | Review structural code quality |
+| `thermo-review` | Review bugs and breakage |
+| `agentic-owners` | Apply owners policies to pull requests |
+| `triage-linear` or `triage-jira` | Triage tracker issues |
 
 ```bash
-curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/schedules/heartbeat
-# {"scheduleId":"heartbeat","sessionIds":["ses_..."]}
+bdk init ./security-reviewer --template security-reviewer
+bdk init ./grokbot --template grokbot-agents
 ```
 
-## Sessions, events, and streaming
-
-Two handles do two jobs: the **continuation token** resumes a conversation
-(owned by the channel; one active continuation per session, stale tokens
-rejected), and the **session id** streams and inspects it (owned by the
-runtime).
-
-### Reminders
-
-Per-session durable wakes (distinct from deploy-time `bot/schedules/`):
-
-```ts
-await handle.createReminder({
-  purpose: "ci_recheck",
-  channelId: "drive",
-  continuationToken: "pr-owner-repo-1",
-  delay: "2h",
-  prompt: "Re-check CI. Only act if still failing.",
-  until: "Cancel once CI is green or the PR is merged.",
-});
-```
-
-Host/policy packs may pass `run` (return `stop` / `skip` / `delivered`)
-instead of prompts. `--dev` does not auto-fire reminders. Dispatch one
-with `POST /v1/dev/reminders/:id` or `handle.dispatchReminder`. Run
-handlers are in-memory. After a restart those reminders are disarmed
-(`handler_lost_on_restart`); re-arm from enroll/policy.
-
-The NDJSON stream vocabulary: one JSON object per line, each carrying
-`{ type, index, sessionId, turnId?, at, data }`:
-
-| Event                 | Meaning                                                        |
-| --------------------- | -------------------------------------------------------------- |
-| `session.started`     | A durable session was created.                                 |
-| `message.received`    | An inbound user message was accepted.                          |
-| `turn.started`        | A turn began.                                                  |
-| `step.started` / `step.completed` | Model step boundaries (with duration).            |
-| `reasoning.appended` / `reasoning.completed` | Reasoning deltas and the block end. |
-| `message.appended`    | Assistant text delta (with cumulative text so far).            |
-| `message.completed`   | A finalized assistant text block (`finishReason`: `stop` or `tool_call`). |
-| `actions.requested`   | The model requested a tool call (streams before execution).    |
-| `action.approval_requested` | A `needsApproval` tool is parked awaiting a human.    |
-| `action.approval_resolved` | Human approved or denied the parked tool call.       |
-| `action.result`       | A tool call returned (`output`, `isError`).                    |
-| `subagent.called` / `subagent.completed` | Delegation to a subagent.               |
-| `turn.completed`      | The turn finished (`result`, `usage`).                         |
-| `turn.failed`         | The turn failed (`message`).                                   |
-| `session.waiting`     | The session parked, ready for the next message.                |
-| `session.completed` / `session.failed` | Terminal states for task-mode (schedule) sessions. |
-
-The stream is durable: reconnect with `?startIndex=<n>` to replay from any
-point, or from 0 to rewind the whole session.
-
-## Serving programmatically
-
-```ts
-import { serve } from "@cursor/bdk";
-
-const handle = await serve("./my-agent", {
-  port: 3000,
-  apiKey: process.env.CURSOR_API_KEY, // optional: see credential order below
-});
-console.log(`listening on ${handle.url}`);
-// handle.dispatchSchedule("heartbeat"), handle.project, await handle.close()
-```
-
-The Cursor credential resolves in one order everywhere (SDK turns and
-Cursor account MCP connections): explicit `apiKey` option / `--api-key`
-→ `CURSOR_API_KEY` → `CURSOR_API_KEY_FILE` (hosted default
-`/run/cursor/secrets/CURSOR_API_KEY` when unset) → `CURSOR_SERVICE_ACCOUNT_KEY`
-→ the key stored by `bdk login`. A bind file wins over
-`CURSOR_SERVICE_ACCOUNT_KEY`. `whoami` shows
-which one is active; `logout` removes the stored key (revoke it in the
-Cursor dashboard to kill it outright).
-
-Local-dev note: login/account RPCs honor `CURSOR_API_BASE_URL` while the
-Cursor SDK harness honors `CURSOR_BACKEND_URL`. When pointing at a
-non-production backend, set **both** to the same URL. A key minted on one
-backend is rejected by the other.
-
-`serve` refuses to start when discovery produced error diagnostics; run
-`bdk validate` (or read `project.diagnostics`) to see why.
-
-State lives under the project state directory (override with
-`--state-root`). Forget a conversation by removing that session from
-state.
+`--template triage` selects `triage-linear`.
 
-Session workspaces are real Cursor project directories, so the harness
-also loads ambient project config from ancestor directories. Nested git
-checkouts default `local.cwd` to a per-project cache directory under
-`~/.cache`. Point `cwd` at a checkout only when the agent should inherit
-that tree.
+## Next steps
 
-## Not supported (yet)
+Run `bdk docs` to open the full documentation. By default,
+`bdk serve` also serves the same documentation at `/docs`.
 
-BDK does not load per-subagent tools, skills, or MCP connections.
-It also rejects nested subagents, WebSocket channel routes, and custom
-sandbox backends. Discord and Teams do not have channel packs. Use an
-authored `defineChannel` integration for those platforms.
+The docs include:
 
-Parked approval calls do not resume after a host restart. Context compaction
-is owned by the Cursor harness.
+- A complete PR reviewer quickstart
+- GitHub, Slack, webhook, and MCP guides
+- Evals and hillclimbing
+- Deployment and troubleshooting
+- Project layout, CLI, and API reference