@cursor/bdk 0.2.1

package/docs/reference/agent-config.md

@@ -0,0 +1,193 @@
+---
+title: "Agent config"
+description: "defineAgent at bot/agent.ts: the model, local workspace, and programmatic serving."
+---
+
+# Agent config
+
+`bot/agent.ts` default-exports `defineAgent(config)`: which model runs
+the agent and its local harness defaults.
+Everything is optional on the root agent.
+
+The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
+until publication; see [BDK package availability](/#bdk-package-availability).
+
+```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
+});
+```
+
+## Agent fields
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `model` | string or `{ id, params }` | Cursor model for turns. Defaults to `grok-4.5` with `effort=high`, `fast=true` on the root agent. Subagents omit it to inherit. |
+| `name` | string | Display name override. Defaults to the package name or directory name. |
+| `description` | string | What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root. |
+| `instructions` | string | Inline instructions. Prefer `instructions.md`; this exists for subagents and generated configs. |
+| `local` | `{ cwd?, workspaceDir?, sandbox? }` | Local harness defaults. See [Local options](#local-options). |
+| `hosting` | `{ egressDomains?, secretNames? }` | Managed-hosting declarations read by `bdk deploy`: the pod's egress allowlist and the secret names the agent expects. Ignored by local serving. |
+| `concurrency` | `{ maxRunningTurns? }` | Engine-wide turn admission limit. See [Concurrency](#concurrency). |
+| `builtinTools` | `{ reminders? }` | Framework-provided model-facing tools, opted in per capability. See [Built-in tools](#built-in-tools). |
+| `tools` | `ToolName[]` | Allowlist of built-in harness tools offered to the model. Unset = the model's full standard toolset. See [Harness tools](#harness-tools). |
+
+## Model
+
+`model` is a Cursor model id string, or `{ id, params }`. Effort and
+speed are params, not id suffixes. The SDK rejects suffix-style ids
+like `grok-4.5-fast`:
+
+```ts
+model: {
+  id: "grok-4.5",
+  params: [
+    { id: "effort", value: "high" },
+    { id: "fast", value: "true" },
+  ],
+}
+```
+
+A plain string works when you don't need params:
+
+```ts
+model: "composer-2.5",
+```
+
+## Local options
+
+`local` sets local-harness defaults.
+
+`local.workspaceDir` points every session at one shared harness cwd,
+for agents that work inside an existing checkout. It takes precedence
+over `cwd`, and a per-send `workspaceDir` still wins over both.
+Sessions share a working tree, so a file one turn writes is visible to
+the next.
+
+`local.sandbox` runs the harness inside Cursor's local sandbox. It's
+off by default: shell then auto-approves and inherits the serve process
+environment, including any credentials the host holds. Turn it on for
+agents whose turns read untrusted input (webhook payloads, PR diffs,
+inbound chat); it's a tool boundary, not a prompt-level one.
+
+### Local cwd
+
+`local.cwd` sets the parent directory for local harness workspaces. Each
+session uses `<cwd>/<sessionId>` unless a per-send `workspaceDir` overrides
+it.
+
+Session workspaces are real Cursor project directories. The harness loads
+`AGENTS.md` and `.cursor` config from ancestor directories. An agent nested
+in another git repo (a monorepo package) defaults to a per-project
+cache directory under `~/.cache` when you omit `cwd`, so the enclosing checkout
+does not leak rules, skills, or MCP servers into the turn. A standalone git
+root keeps the in-project session workspace. Point `cwd` at a checkout only
+when the agent should inherit that tree.
+
+## Harness tools
+
+Use `tools` to limit which built-in Cursor harness tools the model can
+call. Omit it to keep the standard toolset. When you set it, the model
+gets only the tools you list. An empty list disables all native
+built-in tools. New platform tools stay disabled until you add them.
+
+```ts
+export default defineAgent({
+  model: "composer-2.5",
+  // Read-only triage agent: search and read only.
+  // No shell, no edits, no subagents.
+  tools: ["read", "grep", "glob", "ls"],
+});
+```
+
+BDK always adds `"mcp"` to a configured allowlist, because
+authored server tools in `bot/tools/` reach the model over MCP. MCP
+can also expose declared connections and servers from the harness
+directory's ambient `.cursor` config. To exclude a checkout's MCP
+servers, point `local.cwd` outside the checkout. See
+[Local cwd](#local-cwd). `local.sandbox` makes MCP tool calls fail
+closed.
+
+Use the SDK's public tool names, including `"shell"`, `"read"`,
+`"edit"`, `"grep"`, `"glob"`, `"ls"`, and `"task"`. Unknown names
+fail the turn with a `ConfigurationError`.
+
+Two names have broader effects:
+
+- `"shell"` also grants shell input. Tools with
+  `execution: "agent"` need it to run their scripts. Discovery warns
+  when your allowlist would prevent those tools from running.
+- `"task"` lets the root agent start subagents. Each subagent keeps
+  its own curated toolset.
+
+The allowlist controls which tools the model can call. It does not
+isolate the serve host. For agents that process untrusted input, also
+set `local: { sandbox: true }`.
+
+## Concurrency
+
+`concurrency.maxRunningTurns` caps how many model turns run at once
+across all of the agent's sessions (positive integer, hard cap 200).
+When every slot is busy, newly admitted turns queue FIFO instead of
+failing: the stream records a durable `turn.queued` event with the
+queue position, `GET /v1/sessions` reports `queued: true`, and each
+queued turn starts as soon as a slot frees. A queued turn still counts
+as running for busy semantics: follow-ups preempt it, and direct
+write-effect tool calls get `409 session_busy`. Omit for unlimited.
+
+```ts
+export default defineAgent({
+  concurrency: { maxRunningTurns: 3 },
+});
+```
+
+## Built-in tools
+
+`builtinTools` opts into framework-provided model-facing tools. Each
+enabled capability shows up as ordinary server tools, so turns, direct
+calls, `info`, and the playground treat them like authored tools. Authored tools with the same name win, with a
+warning, and like all server tools they run on the local runtime.
+
+`builtinTools: { reminders: true }` adds three tools bound to the
+current conversation over `host.reminders`: `reminders_create`,
+`reminders_list`, and `reminders_cancel`. Sessions without a
+continuation key can't arm reminders. See
+[Schedules and reminders](./schedules.md#reminders).
+
+## Serve programmatically
+
+`serve(dirOrProject, options)` embeds the server in your own process:
+
+```ts
+import { serve } from "@cursor/bdk";
+
+const handle = await serve("./my-agent", {
+  port: 3000,
+  apiKey: process.env.CURSOR_API_KEY,
+});
+console.log(`listening on ${handle.url}`);
+// handle.callTool(...), handle.dispatchSchedule("heartbeat"),
+// handle.createReminder(...), handle.project, await handle.close()
+```
+
+Host settings match the documented [CLI](./cli.md) `serve` flags.
+`serve()` also accepts `discovery` (project-loading options) and
+`mode: "single" | "multi"`. Pass `apiKey` or use the same Cursor
+credential as the CLI: `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`,
+`CURSOR_SERVICE_ACCOUNT_KEY`, or `bdk login`.
+
+## Related
+
+- [Instructions](./instructions.md): the required half of a minimal
+  agent
+- [CLI](./cli.md): the `serve` flags `serve()` accepts
+- [Sessions](./sessions.md): workspaces, identifiers, and turn admission
+- [Schedules](./schedules.md): reminder tools opted in here

package/docs/reference/artifacts.md

@@ -0,0 +1,121 @@
+---
+title: "Artifacts"
+description: "Declare, tag, list, stream, and download durable agent outputs."
+---
+
+# Artifacts
+
+Artifacts are durable outputs such as reviewed pull requests, reports,
+or decision records. An artifact kind defines the data it accepts, and
+the artifacts API tags or updates records by key. Records persist across
+sessions and can be listed, streamed, or downloaded.
+
+The `@cursor/bdk` imports on this page are docs-ahead until publication;
+see [BDK package availability](/#bdk-package-availability).
+
+## Artifact kinds
+
+Author `bot/artifacts.ts` with `defineArtifacts` from
+`@cursor/bdk/artifacts`:
+
+```ts
+import { z } from "zod";
+import { defineArtifacts } from "@cursor/bdk/artifacts";
+
+export default defineArtifacts({
+  kinds: {
+    "reviewed-pr": {
+      description: "A pull request this agent reviewed.",
+      schema: z.object({ url: z.string(), verdict: z.string() }),
+    },
+    report: { description: "A generated report." },
+  },
+  agentTool: true,
+});
+```
+
+| Option | Contract |
+| --- | --- |
+| `kinds` | Map of accepted kind names to a non-empty `description` and optional Zod `schema` |
+| `agentTool` | Expose `tag_artifact` to the model; requires at least one declared kind |
+| `max` | Positive retention cap; defaults to `1000` and evicts the oldest-updated record |
+
+With declared kinds, `tag` rejects any other kind. With no registry, it
+accepts free-form kind names and defaults an omitted kind to
+`"artifact"`. A kind's schema validates `data`, and the parsed value is
+stored, including schema defaults and coercions.
+
+## Tag artifacts from host code
+
+Tools, hooks, channel handlers, channel `onStart`, schedules, and
+reminders receive an `ArtifactsApi` with `tag` and `list`.
+
+```ts
+await ctx.artifacts.tag({
+  kind: "reviewed-pr",
+  key: prUrl,
+  title: `Reviewed ${prUrl}`,
+  data: { url: prUrl, verdict: "approve" },
+});
+```
+
+| Tag field | Contract |
+| --- | --- |
+| `data` | Required JSON data, validated when the kind has a schema |
+| `kind` | Declared or free-form kind |
+| `key` | Agent-wide upsert key; the same key updates one record across kinds |
+| `title` | Optional display title |
+| `contents` | String or bytes served by the content route |
+| `contentType` | MIME type for `contents` |
+| `sessionId`, `turnId` | Attribute the artifact to a session or turn |
+| `source` | `"host"` or `"model"`; defaults to `"host"` |
+
+Tool, hook, result, and channel-event contexts are session-bound, so
+they fill `sessionId` and the current `turnId`. Channel routes,
+`onStart`, schedules, and reminders receive an unbound facade; pass
+`sessionId` to attribute an artifact.
+
+Re-tagging a key without `contents` keeps its file or blob when the
+`sessionId` stays the same. Rebinding the key to another session without
+new contents removes the previous payload. `tag` returns the stored
+`ArtifactRecord`.
+
+| Record field | Contract |
+| --- | --- |
+| `id` | Stable ID derived from `key`, or a generated ID when no key is set |
+| `kind`, `data` | Validated kind and JSON payload |
+| `key`, `title` | Optional upsert key and display title |
+| `content` | Optional `{ size, contentType? }` metadata |
+| `sessionId`, `turnId` | Optional session attribution |
+| `source` | `"host"` or `"model"` |
+| `createdAt`, `updatedAt` | ISO-8601 timestamps |
+
+## Expose `tag_artifact` to the model
+
+With `agentTool: true`, the `tag_artifact` server tool materializes from
+the kinds registry. Its input accepts the declared kinds and validates
+their data with the same schemas as host-side tagging. The kind
+descriptions tell the model which output each one represents.
+
+An authored tool named `tag_artifact` takes precedence over the generated
+tool.
+
+## List artifacts
+
+`list({ kind?, sessionId? })` returns matching records newest-updated
+first. HTTP callers can list records and download content through the
+[artifact routes](./http-api.md#list-and-download-artifacts).
+
+## Stream artifact tags
+
+Tagging an artifact with a `sessionId` emits `artifact.tagged` on that
+session. Its event data contains `id`, `kind`, `key`, `title`, `data`,
+and `source`. See [Stream events](./sessions.md#stream-events) for the
+event envelope.
+
+## Related
+
+- [Sessions](./sessions.md)
+- [Tools](./tools.md)
+- [Evals](./evals.md)
+- [HTTP API](./http-api.md)

package/docs/reference/channels.md

@@ -0,0 +1,203 @@
+---
+title: "Channels"
+description: "Define custom channel routes, schemas, state, events, and authentication."
+---
+
+# Channels
+
+A channel connects an external surface to agent sessions. A file at
+`bot/channels/<id>.ts` defines channel `<id>` and mounts its routes
+under `/v1/channels/<id>`. The built-in HTTP session channel is always
+available alongside any custom or prebuilt channels.
+
+The `@cursor/bdk` imports on this page are docs-ahead until publication;
+see [BDK package availability](/#bdk-package-availability).
+
+## Built-in HTTP channel
+
+The built-in channel serves the session, approval, tool, discovery, and
+health routes. In a multi-agent host, each agent's routes sit under its
+slug. See the [HTTP API](./http-api.md) for request and response
+contracts.
+
+## Define a custom channel
+
+Use `defineChannel` with one or more typed routes:
+
+```ts
+import { defineChannel, POST } from "@cursor/bdk/channels";
+import { z } from "zod";
+
+export default defineChannel({
+  routes: [
+    POST("/review", {
+      description: "Review a pull request on this channel",
+      bodySchema: z.object({
+        message: z.string(),
+        prUrl: z.string().url(),
+      }),
+      handler: async (_request, { send, body }) => {
+        const session = await send(
+          `${body.message}\n\nPull request: ${body.prUrl}`,
+          {
+            continuationToken: `pr:${body.prUrl}`,
+          }
+        );
+        return Response.json({ sessionId: session.id });
+      },
+    }),
+  ],
+});
+```
+
+The route above is
+`POST /v1/channels/<id>/review`. Calls for the same pull request reuse
+one conversation because they pass the same continuation token.
+
+## Route verbs and schemas
+
+Route paths must begin with `/`. The method helper determines which Zod
+schemas the route accepts:
+
+| Helper | Schema contract |
+| --- | --- |
+| `GET` | `querySchema` is required |
+| `POST`, `PUT`, `PATCH` | `bodySchema` is required; `querySchema` is optional |
+| `DELETE` | Both schemas are optional |
+
+Plain JSON Schema objects don't type-check. Use `z.object({})` or
+`z.unknown()` for an open surface. The host validates the body and query
+before calling the handler, returning `400` on failure; an empty body is
+read as `{}`. Declared schemas also appear in `GET /v1/info` for
+playground requests and slash commands.
+
+## Handler arguments
+
+Each handler receives the Fetch `Request` and a typed arguments object.
+
+| Member | Contract |
+| --- | --- |
+| `send(message, options?)` | Start or resume a session on this channel |
+| `getSession(sessionId)` | Return this channel's session, or `null` |
+| `receive(channel, input)` | Hand work to another channel |
+| `callTool(name, input, options?)` | [Call a server tool](./tools.md#call-a-tool-without-a-model-turn) without a model turn |
+| `body`, `query`, `params` | Validated inputs and `:param` path segments |
+| `auth` | The `AuthContext` returned by the route's auth chain |
+| `requestIp` | The TCP peer address, or `null` |
+| `host` | Shared MCP, provider, storage, telemetry, and reminder services |
+| `waitUntil(promise)` | Track work after the response returns |
+| `sessionUrls(request, sessionId)` | Build absolute playground and trace URLs for this mount |
+| `artifacts` | List or tag [artifacts](./artifacts.md); pass `sessionId` when attributing one |
+
+### `send` options
+
+| Option | Contract |
+| --- | --- |
+| `continuationToken` | Resume the session with this channel-local key, or create one when the key is new |
+| `admission` | `"preempt"` interrupts a busy turn; `"coalesce"` queues behind it. The default is `"preempt"` |
+| `workspaceFiles` | Add relative files for the next turn |
+| `workspaceDir` | Use an absolute local working directory |
+| `auth` | Set the session principal; defaults to the request principal |
+| `state` | Set starting channel state for a new session |
+| `title` | Set the display title for a new session |
+| `purpose` | Use `"eval"` to mark a new session as regression traffic |
+| `dryRun` | Run read tools and stub write tools for a new session |
+| `asOf` | Freeze a new session at an ISO-8601 instant with a timezone |
+
+`send` returns a `ChannelSession`. Its `id` identifies the session,
+`continuationToken` contains its current channel key, and `isNew` says
+whether this call created it. A coalesced call also returns
+`coalesced: true`.
+
+## Events
+
+The `events` map subscribes the channel to stream events for the
+sessions it owns. Keys are event types from the
+[event vocabulary](./sessions.md#stream-events), or `"*"`. Each handler
+receives `(event, channel, ctx)`, including the session's
+`channel.state`, session info, and shared host services. Use these
+handlers to deliver progress and replies to the surface that owns the
+channel.
+
+## Session state
+
+`state` on the channel definition supplies starting JSON for each new
+session. A route can instead pass `state` to `send`; event handlers read
+and update the active value through `channel.state`.
+
+## Start and stop a channel
+
+`onStart(args)` runs when the channel mounts, and `onStop()` runs when
+the host stops. `onStart` receives the route helpers plus these
+transport controls:
+
+| Helper | Contract |
+| --- | --- |
+| `emitAssistantMessage(sessionId, text)` | Append final assistant text without starting a model turn |
+| `hasContinuationSession(token)` | Check whether a token maps to a session |
+| `isContinuationBusy(token)` | Check whether a turn is active for a token |
+| `interruptContinuation(token)` | Stop the active turn and clear queued coalesced follow-ups |
+| `resolveApproval(...)` | Approve or deny a parked tool call |
+
+## Auth policies
+
+Every route runs the channel's `auth` array. The default is
+`[localDevStrict()]`. Policies may be asynchronous; the first one to
+return an `AuthContext` admits the request, and an all-null result
+returns `401`.
+
+| Policy | Admits |
+| --- | --- |
+| `localDevStrict()` | Direct loopback requests with a loopback hostname and no proxy-forwarding headers |
+| `localDev()` | Direct loopback requests with no proxy-forwarding headers, without checking the hostname |
+| `loopbackOnly()` | Any loopback TCP peer, including local relays that carry forwarding headers |
+| `bearerAuth(tokenOrVerify)` | A matching bearer token, or a token accepted by the verifier |
+| `sharedSecretAuth({ header, secret })` | A header matching the named environment or deployment secret |
+| `hmacSignatureAuth({ header, secret, prefix? })` | A hex HMAC-SHA256 signature over the raw body using the named secret |
+| `allowAll()` | Every caller as an anonymous principal |
+| `publicEndpoint()` | Every caller on this custom channel; managed hosting also exposes the route without an alias token |
+
+Use `allowAll()` only for an intentionally public surface or one
+protected upstream. With `publicEndpoint()`, the handler must verify the
+provider's signature. The policy applies only to custom channel routes;
+it doesn't open the built-in session or tool API.
+
+The resolved `AuthContext` (`{ authenticator, principalId,
+principalType, attributes? }`) becomes the request principal. Sessions
+belong to the principal that created them, and other principals receive
+`403` on owned routes.
+
+Server flags interact with authored auth: `--bearer-token` swaps the
+default `localDevStrict()` for `bearerAuth(...)` on channels that don't
+author their own chain, and `--allow-anonymous` swaps it for
+`allowAll()`. An authored `auth` array always takes precedence.
+
+## Prebuilt channels
+
+| Import | Factory | Surface |
+| --- | --- | --- |
+| `@cursor/bdk/channels/slack` | `slackChannel()` | Slack messages, threads, streaming replies, and approvals. See [Slack](../guides/slack.md) |
+| `@cursor/bdk/channels/github` | `githubChannel()` | GitHub and GitHub Enterprise webhooks. See [GitHub](../guides/github.md) |
+| `@cursor/bdk/channels/gitlab` | `gitlabChannel()` | GitLab.com and self-managed GitLab hooks. See [GitLab](../guides/gitlab.md) |
+| `@cursor/bdk/channels/bitbucket` | `bitbucketChannel()` | Bitbucket Cloud and Data Center hooks. See [Bitbucket](../guides/bitbucket.md) |
+| `@cursor/bdk/channels/deployments` | `deploymentsChannel()` | Deployment events filtered by source, environment, or event name |
+| `@cursor/bdk/channels/change-monitors` | `changeMonitorsChannel()` | Change Monitor `checkpoint.created` events |
+| `@cursor/bdk/channels/issues` | `issuesChannel()` | Factory `issue.created` events |
+
+For other platforms like Discord or Teams, use the authored
+`defineChannel` route form.
+
+## Continuation tokens
+
+Each channel defines its continuation-token format. The same token
+resumes the same conversation; the built-in HTTP channel rotates its
+opaque token after every accepted follow-up and returns `409` for a
+stale token. See [Session identifiers](./sessions.md#session-identifiers)
+for the full contract.
+
+## Related
+
+- [Webhooks](../guides/webhooks.md)
+- [HTTP API](./http-api.md)
+- [Sessions](./sessions.md)
+- [Hooks](./hooks.md)