@cursor/bdk 0.2.1

package/docs/reference/extensions.md

@@ -0,0 +1,198 @@
+---
+title: "Extensions"
+description: "Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds."
+---
+
+# Extensions
+
+An extension packages capabilities that would otherwise live under
+`bot/`: tools, skills, instructions, connections, hooks, channels,
+schedules, subagents, artifacts, and workspace seeds. One mount file
+adds them under a namespace without copying their source into your
+project.
+
+The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
+until publication; see [BDK package availability](/#bdk-package-availability).
+
+Extensions and Cursor plugins execute as trusted host code. A namespace
+prevents name collisions; it does not sandbox the package or limit its
+side effects. Review the package before mounting it.
+
+## Mount an extension
+
+Install the package and add one file under `bot/extensions/`. The
+filename becomes the namespace, so this mount contributes names such as
+`ci__failed_jobs` and `ci__triage`.
+
+```ts
+// bot/extensions/ci.ts
+import ci from "@acme/ci-triage";
+
+export default ci({
+  org: "acme",
+  token: process.env.BUILDKITE_TOKEN,
+});
+```
+
+The extension validates its configuration while the project loads.
+Missing or mistyped settings fail `bdk validate` before a turn
+can call the contributed code.
+
+Extension instructions are appended to the root agent's instructions.
+The root agent still needs its own `bot/instructions.md`.
+
+## Inspect a mount
+
+Run discovery after mounting or upgrading an extension:
+
+```text
+bdk validate --dir .
+bdk info --dir . --json
+```
+
+`info` lists each mount and its namespaced tools, skills, connections,
+hooks, channels, schedules, subagents, and artifact kinds. The same
+data appears under `extensions` in `GET /v1/info`.
+
+Names inside the extension stay short. A tool authored as
+`tools/failed_jobs.ts` appears to the mounting agent as
+`<namespace>__failed_jobs`. The `__` separator is reserved, so root
+contributions cannot impersonate a mounted one.
+
+## Adjust a mounted extension
+
+Mount as a directory when you need to replace or remove one
+contribution. Keep the package mount in `extension.ts`, then overlay the
+extension's short name beneath it.
+
+```text
+bot/extensions/ci/
+  extension.ts
+  tools/
+    job_log.ts
+    retry_job.ts
+```
+
+```ts
+// bot/extensions/ci/tools/job_log.ts
+import { defineTool } from "@cursor/bdk/tools";
+import {
+  jobLogInput,
+  readRedactedLog,
+} from "../../../lib/ci.js";
+
+export default defineTool({
+  description: "Read a redacted CI log.",
+  inputSchema: jobLogInput,
+  execute: readRedactedLog,
+});
+```
+
+```ts
+// bot/extensions/ci/tools/retry_job.ts
+import { disableTool } from "@cursor/bdk/extensions";
+
+export default disableTool();
+```
+
+The first file replaces `ci__job_log`; the second removes
+`ci__retry_job`. Use the matching `disable*` helper for another slot, or
+generic `disable()` when the file location already identifies it.
+Validation fails when an overlay names a contribution the package does
+not provide.
+
+## Mount a Cursor plugin
+
+`cursorPlugin()` adapts a vendored Cursor or Claude plugin into the same
+namespace model. Skills, commands, agents, and MCP servers become Agent
+SDK skills, subagents, and connections.
+
+```ts
+// bot/extensions/notion.ts
+import { cursorPlugin } from "@cursor/bdk/extensions";
+
+export default cursorPlugin({
+  path: "plugins/notion-workspace",
+  variables: {
+    NOTION_TOKEN: process.env.NOTION_TOKEN,
+  },
+});
+```
+
+`path` is relative to the project root. `variables` fills placeholders
+declared by the plugin's MCP configuration; unresolved placeholders
+fail validation instead of mounting a partial server.
+
+Plugin rules and hooks are not mounted. Overlay a generated
+`mcp-connections/<server>.ts` file to replace or disable one plugin
+server. OAuth-backed plugin servers use
+[Host MCP OAuth](../guides/mcp-oauth.md); transport and tool-filter
+details live in [MCP connections](./connections.md).
+
+## Extension contents
+
+| Ships under the namespace | Ignored |
+| --- | --- |
+| Instructions, tools, skills, MCP and host connections | `agent.ts`, storage, OpenTelemetry |
+| Hooks, channels, schedules, and subagents | Playground code, custom sandbox backends |
+| Artifact kinds and workspace seed files | Nested extensions |
+
+`bdk validate` reports unsupported paths.
+
+## Build an extension
+
+Lay out the package like the shareable part of `bot/`. The root
+`extension.ts` supplies a description and validates any settings the
+consumer must provide.
+
+```text
+@acme/ci-triage/
+  package.json
+  extension.ts
+  instructions.md
+  tools/
+    failed_jobs.ts
+    job_log.ts
+  skills/
+    triage.md
+  hooks/
+    audit.ts
+  lib/
+    buildkite.ts
+```
+
+```ts
+// extension.ts
+import { defineExtension } from "@cursor/bdk/extensions";
+import { z } from "zod";
+
+export default defineExtension({
+  root: import.meta.dirname,
+  description: "Investigate failing Buildkite jobs.",
+  config: z.object({
+    org: z.string(),
+    token: z.string(),
+    logTailLines: z.number().int().positive().default(200),
+  }),
+});
+```
+
+Modules inside the package import this definition and read
+`extension.config`, which is already validated and has defaults
+applied. Publish the built entry point with its slot directories and
+prose assets beside it.
+
+The [Project layout](./project-layout.md) owns each contribution's
+authoring contract. Keep extension instructions and tool descriptions
+namespace-neutral because the consumer chooses the final prefix.
+
+## Related
+
+- [Cloud agents](../guides/cloud-agents.md): delegate repository work
+  through an extension
+- [Grok Bot agents](../guides/grokbot-agents.md): consult named bots
+- [Jev](../guides/jev.md): typed answers, then gated writes
+- [Self-improvement](../guides/improve.md): propose source changes
+  through pull requests
+- [Project layout](./project-layout.md): contribution slots
+- [Tools](./tools.md) and [Skills](./skills.md): capability contracts

package/docs/reference/hooks.md

@@ -0,0 +1,195 @@
+---
+title: "Hooks"
+description: "Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."
+---
+
+# Hooks
+
+A hook subscribes to selected session events and can run a side effect
+after each matching event is recorded: an audit line, a metric, a
+transcript copy, or derived state. Hooks run in the serving process for
+every session of the agent. They cannot change the turn, the prompt, or
+the reply; a handler that throws is logged and skipped.
+
+The `@cursor/bdk` imports on this page are docs-ahead until publication;
+see [BDK package availability](/#bdk-package-availability).
+
+Treat the event as read-only. Later subscribers see the same object.
+That makes hooks safe to add to a production agent, and the wrong
+surface for anything that must run before the model or must fail a
+turn; see [Hook boundaries](#hook-boundaries).
+
+`defineHook` is unrelated to
+[Cursor Agent hooks](https://cursor.com/docs/agent/hooks), the
+`.cursor/hooks.json` scripts that can observe, block, or modify the
+agent loop. Those still run inside a local session workspace.
+
+## Author a hook
+
+Author `bot/hooks/<name>.ts` with `defineHook` from
+`@cursor/bdk/hooks`. This one meters tokens:
+
+```ts
+// bot/hooks/usage.ts
+import { defineHook } from "@cursor/bdk/hooks";
+
+export default defineHook({
+  events: {
+    async "turn.completed"(event, ctx) {
+      if (ctx.session.purpose === "eval" || event.data.usage === undefined) {
+        return;
+      }
+      const { inputTokens, outputTokens } = event.data.usage;
+      ctx.host.otel.increment("acme.tokens.input", inputTokens);
+      ctx.host.otel.increment("acme.tokens.output", outputTokens);
+    },
+    async "turn.failed"(_event, ctx) {
+      ctx.host.otel.increment("acme.turn.failed", { channel: ctx.channel.id });
+    },
+  },
+});
+```
+
+Any module under `bot/hooks/`, subfolders included, is a hook named by
+its path without the extension: `bot/hooks/audit/usage.ts` is
+`audit/usage`. `*.test.ts` and `*.spec.ts` files are skipped. The
+default export must be `defineHook(...)`, names can't contain `__`, and
+an empty `events` map skips the hook with a warning; `bdk validate`
+reports all three. An extension mounts its hooks as `<ns>__<name>`, and
+`disableHook()` removes one
+([Adjust a mounted extension](./extensions.md#adjust-a-mounted-extension)).
+
+`bdk init` scaffolds `bot/hooks/memory.ts`, which exports
+`memoryHook()` from `@cursor/bdk/memory` and journals every turn for
+later sessions to read. Delete the file to opt out.
+
+## Events and payloads
+
+Keys are event types from the
+[event vocabulary](./sessions.md#stream-events), or `"*"`
+for every event. A typed key narrows `event.data`; a `"*"` handler
+receives the union, so switch on `event.type`. Every event carries the
+stream envelope `{ type, index, sessionId, turnId?, at, data }`, with
+`turnId` set on turn-scoped events. Skip `*.appended` deltas when you
+want the final text; `message.completed` already has it.
+
+| Event               | `event.data`                                                                                                                                                                                                |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `message.received`  | `{ text }`                                                                                                                                                                                                  |
+| `turn.completed`    | `{ result?, usage?, cost? }`. `usage` has `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, and optional `reasoningTokens`. `cost` has `totalUsd` and the `model` it was priced against |
+| `turn.failed`       | `{ message, status? }`. `status` is `"error"` or `"cancelled"` when present                                                                                                                                 |
+| `actions.requested` | `{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }`. `parentCallId` marks subagent work                                                                                                |
+| `action.result`     | `{ callId, toolName, output?, isError, stubbed?, parentCallId? }`. `stubbed` means a dry-run session answered a write without running it                                                                    |
+
+The types are `SessionEvent`, `SessionEventType`, and `HookContext`,
+exported from `@cursor/bdk`.
+
+## Handler context
+
+| Member                                              | What it is                                                                                                                                                 |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx.session`                                       | Read-only session info: `id`, `channelId`, `mode` (`chat` or `task`), `purpose` (`live` or `eval`), `auth`, plus `title` and `sdkAgentId` when set         |
+| `ctx.agent`                                         | `{ name }` of the agent the event belongs to                                                                                                               |
+| `ctx.channel`                                       | `{ id, continuationToken }`. The token is `null` when the session can't take follow-ups                                                                    |
+| `ctx.host.kv`                                       | Durable JSON, shared by every session of the agent. Prefix keys with `ctx.session.id` for per-session state                                                |
+| `ctx.host.files`                                    | Durable files, bound to this session. Pass `{ scope: "deployment" }` for agent-wide files                                                                  |
+| `ctx.host.otel`                                     | Counters, histograms, and tags, attributed to this session                                                                                                 |
+| `ctx.host.mcp`, `ctx.host.github`, `ctx.host.slack` | The same shared clients tools get                                                                                                                          |
+| `ctx.host.reminders`                                | Per-session [reminders](./schedules.md#reminders), the same API tools get                                                                                  |
+| `ctx.artifacts`                                     | Session-bound [artifacts](./artifacts.md) facade: `tag` fills in `sessionId` and `turnId`                                                                  |
+| `ctx.stateRoot`                                     | Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in `kv` or `files`                               |
+
+## Hook dispatch
+
+A hook runs after the event is recorded. It never delays the model and
+never sees an event that wasn't recorded.
+
+| Rule | What happens |
+| --- | --- |
+| Same session | Events dispatch one at a time |
+| Eval sessions | The same stream fires; skip metering or paging when `ctx.session.purpose === "eval"` |
+| Host restart | Recorded events are not replayed into hooks, so a mirror needs no dedupe |
+| Slow handler | Holds the next event's handlers on that session, not the model. Keep handlers short and queue anything slow |
+
+Read hosted secrets inside the handler, not at module scope. Give
+outbound calls a timeout; a stalled request holds later handlers on that
+session. Skip cancelled turns when paging; they record interrupted work.
+
+```ts
+// bot/hooks/page-on-failure.ts
+import { defineHook } from "@cursor/bdk/hooks";
+
+export default defineHook({
+  events: {
+    async "turn.failed"(event, ctx) {
+      const pagerUrl = process.env.PAGER_WEBHOOK_URL;
+      if (
+        pagerUrl === undefined ||
+        ctx.session.purpose === "eval" ||
+        event.data.status === "cancelled"
+      ) {
+        return;
+      }
+      await fetch(pagerUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          agent: ctx.agent.name,
+          session: ctx.session.id,
+          channel: ctx.channel.id,
+          message: event.data.message,
+        }),
+        signal: AbortSignal.timeout(5_000),
+      });
+    },
+  },
+});
+```
+
+## Hooks vs channels vs evals
+
+All three consume the same stream, for different jobs:
+
+|                    | Hooks                                           | Channel `events`                                                  | Evals                             |
+| ------------------ | ----------------------------------------------- | ----------------------------------------------------------------- | --------------------------------- |
+| Scope              | every session of the agent                      | sessions the channel owns                                         | one test turn                     |
+| Job                | observe: audit, metrics, mirrors, derived state | deliver: replies back to the channel's surface                    | assert: gates over the trajectory |
+| Context            | `ctx.host`, `ctx.artifacts`, session info       | `channel.state`, `setContinuationToken`, `ctx.host`, session info | the `t` assertion helpers         |
+| Can affect the run | no                                              | yes, it owns the surface                                          | n/a                               |
+| Authored at        | `bot/hooks/*.ts`                              | channel config                                                    | `evals/**/*.eval.ts`              |
+
+## Hook boundaries
+
+| You want to                                                                           | Use instead                                                                                                      |
+| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Add context before the model runs                                                     | The channel's `send` message and `workspaceFiles`, `instructions.md`, skills, or `sandbox/workspace/` seed files |
+| Reply on Slack, comment on a PR, or post any other delivery                           | The channel's `events` map, or the Slack and GitHub packs                                                        |
+| Show PR progress (merge-box check, sticky banner)                                     | `githubChannel({ progress: { commitStatus, banner } })`; see [GitHub agents](../guides/github.md)                 |
+| Block, approve, or rewrite a tool call                                                | [`needsApproval`](./tools.md#gate-a-tool-on-human-approval) on the tool                                          |
+| Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn | `defineResult`                                                                                                   |
+| Gate a change on behavior                                                             | [Evals](../evals.md)                                                                                             |
+
+## Test a hook
+
+A hook definition is a plain object, so a unit test calls
+`hook.events["turn.completed"]` directly with an event and a stub
+`HookContext`. Discovery skips `*.test.ts`, so the test can live next to
+the hook.
+
+| Command | What it reports |
+| --- | --- |
+| `bdk validate --dir .` | Discovery errors and the empty-handlers warning |
+| `bdk info --dir . --json` | Loaded hooks under `agents[].hooks` |
+| `bdk run --dir . --message "…"` | Serve log on stderr, including `hook "<name>" handler for <event> threw: …` |
+
+On hosting, read the same log with [`bdk logs`](./cli.md#logs).
+
+## Related
+
+- [Hooks guide](../guides/hooks.md): meter usage and page on failure
+- [Sessions and streaming](./sessions.md): the event vocabulary hooks observe
+- [OpenTelemetry](../guides/opentelemetry.md): OTLP traces and metrics
+  from the same event stream
+- [Deployment](../deployment.md#observability): runtime logs and export
+  paths
+- [Channels](./channels.md#events): the delivery-side counterpart

package/docs/reference/http-api.md

@@ -0,0 +1,236 @@
+---
+title: "HTTP API"
+description: "Public session, discovery, and channel routes callers use."
+---
+
+# HTTP API
+
+Grok Bot Development Kit (BDK) hosts expose one public HTTP surface. In the default
+multi-agent layout, each agent uses `/<slug>/v1/*`; `--mode single`
+serves the same routes at `/v1/*`. Routes use the agent's HTTP auth
+chain, and session-owned resources return `403` to another principal.
+
+Unless a section says otherwise, the default auth policy is
+`localDevStrict()`. `--bearer-token` replaces it with bearer auth, and
+`--allow-anonymous` replaces it with anonymous access. Built-in JSON
+routes use `{ ok: false, error: "<code>", message? }` for errors; MCP
+uses JSON-RPC, and custom channel handlers define their own responses.
+
+## Host routes
+
+These routes live at the host root in multi-agent mode. The index routes
+exist only when the playground is enabled.
+
+| Route | Contract |
+| --- | --- |
+| `GET /` | HTML index of mounted agents; no auth |
+| `GET /v1/agents` | JSON index of mounted agents; no auth |
+| `GET /docs`, `GET /docs/*` | Documentation site in either layout; no auth |
+| `GET /v1/health` | Host liveness; no auth |
+
+`--no-playground` removes the two index routes. `--no-docs` removes the
+documentation site.
+
+## Start a session
+
+`POST /v1/session` opens a durable conversation.
+
+```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:…",
+#  "playgroundUrl":"…?sessionId=ses_…","traceUrl":"…/v1/session/ses_…/events"}
+```
+
+Once accepted, the response returns `sessionId` for inspection and
+`continuationToken` for follow-ups; follow the stream for progress.
+
+| Body field | Contract |
+| --- | --- |
+| `message` | Required user message |
+| `title` | Display title |
+| `dryRun` | Run read tools and stub write tools |
+| `asOf` | ISO-8601 instant with a timezone; sets `ctx.now()` and rejects omitted, relative, or later declared tool time arguments. Invalid values return `400` |
+| `workspaceFiles` | Relative files added to the session workspace |
+| `purpose` | Use `"eval"` to mark regression traffic |
+
+## Send a follow-up
+
+`POST /v1/session/:sessionId` continues an existing conversation.
+
+```bash
+curl -X POST http://127.0.0.1:3000/<slug>/v1/session/ses_… \
+  -H 'content-type: application/json' \
+  -d '{"continuationToken":"http:…","message":"Make it shorter."}'
+```
+
+The route accepts any chat session, including one created by a custom
+channel. Each accepted follow-up rotates the continuation token and
+returns the replacement. A message sent to a busy session interrupts
+the active turn before starting.
+
+The route returns `409` for a stale token or task session, and `403`
+when the caller doesn't own the session.
+
+## Stream or replay session events
+
+`GET /v1/session/:sessionId/stream` is the live NDJSON feed.
+
+```bash
+curl -N 'http://127.0.0.1:3000/<slug>/v1/session/ses_…/stream?startIndex=0'
+```
+
+The route replays one event per line from `startIndex`, then follows new
+events. The default `0` replays the full stream. To reconnect without
+duplicates, pass the last index you received plus one.
+
+`GET /v1/session/:sessionId/events` returns a one-shot NDJSON dump.
+Pass `?format=json` for `{ sessionId, events, playgroundUrl }`. See
+[Stream events](./sessions.md#stream-events) for the event vocabulary.
+
+## Manage sessions
+
+| Route | Contract |
+| --- | --- |
+| `POST /v1/session/:sessionId/stop` | Interrupt the active turn without sending another message |
+| `GET /v1/sessions` | List sessions owned by the caller |
+| `GET /v1/session/:sessionId/cost` | Return per-turn token usage and estimated cost |
+
+On loopback under `serve --dev`, the session list includes every
+principal so webhook and schedule sessions appear in the playground.
+The cost route returns `404` for an unknown session.
+
+## Resolve tool approvals
+
+| Route | Contract |
+| --- | --- |
+| `GET /v1/session/:sessionId/approvals` | List pending tool approvals |
+| `POST /v1/session/:sessionId/approvals/:callId` | Resolve one with `{"decision":"approve"}` or `{"decision":"deny"}` |
+
+For the lifecycle, see [Gate a tool on human approval](./tools.md#gate-a-tool-on-human-approval).
+
+## Call a tool without a model turn
+
+`POST /v1/tools/:toolName` runs a server tool with no model turn.
+
+```bash
+curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/inspect_pr \
+  -H 'content-type: application/json' \
+  -d '{"input":{"prUrl":"https://github.com/acme/checkout/pull/42"}}'
+# {"ok":true,"toolName":"inspect_pr","callId":"tool_inspect_pr_…",
+#  "isError":false,"result":{…},"durationMs":12}
+```
+
+| Body field | Contract |
+| --- | --- |
+| `input` | Tool input; defaults to `{}` |
+| `sessionId` | Bind the call to an existing session |
+| `continuationToken` | Bind the call by its wire continuation token; mutually exclusive with `sessionId` |
+
+Omit both identifiers for an unbound call. Agent-execution tools return
+`400`, and an unknown name returns `404` with the available names. See
+[Tools](./tools.md#call-a-tool-without-a-model-turn) for session
+binding, busy-session rules, and error codes.
+
+## Discovery routes
+
+These read-only routes describe the running agent.
+
+| Route | Contract |
+| --- | --- |
+| `GET /v1/info` | Return the discovered model, tools, skills, connections, subagents, channels, schedules, hooks, and diagnostics |
+| `GET /v1/tools` | Return live server tools and advertised MCP tools as `{ name, title?, source? }`; bind tenant-scoped listings with `session` or `continuationToken` |
+| `GET /v1/tools/:name` | Return one tool's description, execution mode, approval and effect rules, schemas, and source |
+| `GET /v1/health` | Return per-agent liveness; no auth |
+| `GET /v1/logs?after=N` | Return recent server logs and the next polling cursor |
+
+An unknown tool name returns `404` with available names. If an MCP
+connection can't list its tools, the catalog skips that connection and
+includes it in `connectionErrors`.
+
+## List and download artifacts
+
+| Route | Contract |
+| --- | --- |
+| `GET /v1/artifacts` | Return `{ artifacts }`, newest-updated first; filter with `kind`, `sessionId`, and a positive `limit` |
+| `GET /v1/artifacts/:id/content` | Download an artifact's file or blob as an attachment; return `404` when no content exists |
+
+The list follows the same ownership rules as `GET /v1/sessions`. See
+[Artifacts](./artifacts.md) for tagging and record fields.
+
+## Call custom channel routes
+
+Authored routes mount under `/v1/channels/<id>` with their declared
+methods and paths. The host validates their Zod body and query schemas
+before calling the handler, returning `400` on failure. Each channel's
+auth chain applies. See [Channels](./channels.md).
+
+## MCP endpoint
+
+Both MCP routes use stateless streamable HTTP. Send protocol requests
+with `POST`; `GET` and `DELETE` return `405`.
+
+| Route | Tools and auth |
+| --- | --- |
+| `/v1/mcp` | `ask`, `check`, and `call_tool` when server tools exist; uses the session API auth chain |
+| `/v1/mcp/tools` | Deterministic server tools only; uses the CLI-level loopback, bearer, or anonymous auth chain |
+
+See [MCP connections](./connections.md#peer-mcp-connection) to connect
+one agent to another.
+
+## Playground eval routes
+
+The playground Evals tab and remote eval commands use these routes:
+
+| Route | Contract |
+| --- | --- |
+| `GET /v1/dev/evals` | List discovered cases and eval config |
+| `GET /v1/dev/evals/runs` | List recent run snapshots, newest first |
+| `POST /v1/dev/evals/runs` | Start `{ filterIds?, tags?, timeoutMs?, verbose? }`; return `202`, `404` for no match, or `409` while another run is active |
+| `GET /v1/dev/evals/runs/:runId` | Return progress and the final snapshot |
+| `POST /v1/dev/evals/runs/:runId/cancel` | Cancel an active run; return `404` when unknown or `409` when no longer running |
+
+Poll the run route until its status is `completed`, `failed`, or
+`cancelled`. Entries within `filterIds` and `tags` use OR semantics;
+when both fields are present, a case must match each group.
+
+## Dev-mode routes
+
+These routes exist only under `serve --dev`.
+
+| Route | Contract |
+| --- | --- |
+| `POST /v1/dev/schedules/:scheduleId` | Dispatch a schedule by hand, exactly once. Returns `{scheduleId, sessionIds}` |
+| `GET /v1/dev/reminders` | List reminders |
+| `POST /v1/dev/reminders/:reminderId` | Fire a reminder by hand |
+
+Schedules and reminders never fire automatically in dev mode. These
+routes run them manually.
+
+## Playground assets
+
+`GET /playground` and `GET /playground/assets/:file` serve the
+playground. `--no-playground` removes both routes.
+
+## Status codes
+
+Built-in routes use these common status codes.
+
+| Code | Meaning |
+| --- | --- |
+| `400` | Invalid body, query, tool input, or request shape |
+| `401` | No auth policy admitted the request |
+| `403` | The caller is authenticated but doesn't own the resource |
+| `404` | A named resource doesn't exist, or an eval selection matches no cases |
+| `405` | The route doesn't accept this method |
+| `409` | The resource state rejects the request, such as a stale token or busy write |
+| `202` | The request was accepted for asynchronous work |
+| `500` | A write-effect tool can't create its session workspace (`workspace_unavailable`) |
+
+## Related
+
+- [Sessions](./sessions.md)
+- [Channels](./channels.md)
+- [Tools](./tools.md)
+- [Deployment](../deployment.md)