@cursor/bdk 0.2.1

package/README.md

@@ -0,0 +1,1190 @@
+# Grok Bot Development Kit (BDK)
+
+> [!WARNING]
+> **Docs ahead.** `@cursor/bdk` is not on npm yet. The commands and imports
+> below won't run until publication.
+
+Grok Bot Development Kit (BDK) uses the `@cursor/bdk` package and `bdk`
+binary.
+
+Install the package to obtain the binary, then create and run a bot. These
+docs-ahead commands will not run until `@cursor/bdk` publishes:
+
+```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";
+
+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.
+
+`bot/instructions.md`:
+
+```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
+});
+```
+
+Serve it (turns run on the Cursor harness, so the host needs a Cursor
+credential: sign in once, or export an API key):
+
+```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
+```
+
+Start a session, then follow the NDJSON event stream (replace `<slug>` with
+the agent directory name):
+
+```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:..."}
+
+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",...}
+```
+
+Send a follow-up to the same durable session with the continuation token
+from the previous response (each accepted follow-up rotates it):
+
+```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"
+`,
+});
+```
+
+`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):
+
+```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}
+```
+
+From the CLI (boots an ephemeral server unless `--url` targets a running
+one):
+
+```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:
+
+```bash
+curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/schedules/heartbeat
+# {"scheduleId":"heartbeat","sessionIds":["ses_..."]}
+```
+
+## 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.
+
+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.
+
+## Not supported (yet)
+
+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.
+
+Parked approval calls do not resume after a host restart. Context compaction
+is owned by the Cursor harness.