@cursor/bdk 0.2.1

package/docs/reference/skills.md

@@ -0,0 +1,80 @@
+---
+title: "Skills"
+description: "On-demand procedures the model loads only when relevant, in three authoring forms."
+---
+
+# Skills
+
+A skill is an on-demand procedure following the `SKILL.md` convention:
+the harness advertises each skill by its description, and the model
+loads the full content only when the task calls for it. Skills are how
+you give an agent a multi-step workflow without carrying it in the
+always-on [instructions](./instructions.md).
+
+The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
+until publication; see [BDK package availability](/#bdk-package-availability).
+
+## Authoring forms
+
+Skills support three authoring forms.
+
+| Form | Reach for it when |
+| --- | --- |
+| `bot/skills/<name>.md` | Static Markdown. Optional `description` frontmatter; the first body line is the fallback. |
+| `bot/skills/<name>/SKILL.md` plus siblings | A packaged directory with reference files (`references/…`). Requires `description` frontmatter. |
+| `bot/skills/<name>.ts` | Generated content, with `defineSkill` from `@cursor/bdk/skills`. |
+
+Use flat Markdown for static content:
+
+```md
+---
+description: Use when a pull request needs a structured approval checklist.
+---
+
+# PR review checklist
+
+1. Call `inspect_pr` and confirm required checks passed.
+2. Summarize the PR title, author, and remaining risks.
+3. Call `approve_pr` only after an explicit request; it requires approval.
+```
+
+Use TypeScript when the content must be generated or include inline
+sibling files:
+
+```ts
+import { defineSkill } from "@cursor/bdk/skills";
+
+export default defineSkill({
+  description: "Research unfamiliar topics before answering.",
+  markdown: "Gather evidence first, then answer with the key facts.",
+  files: { "references/checklist.md": "# Checklist\n\n- Find sources.\n" },
+});
+```
+
+## Skill delivery
+
+Skills land in the session workspace at
+`.cursor/skills/<name>/SKILL.md`, and the harness advertises and loads
+them natively.
+
+## Skills, instructions, and tools
+
+Instructions are always in context: identity, tool-choice rules, the
+output contract. Keep them short. Skills load when relevant: procedures,
+checklists, house style. Reach for a skill when the model needs to
+follow something but only sometimes needs it loaded. Tools are typed,
+executable behavior: anything that must be correct every time belongs in
+tool code, not in prose the model might paraphrase.
+
+A good skill description is a routing rule, not a title. Say when to
+use it, like "Use when a pull request needs a structured approval
+checklist," because the description is all the model sees before
+deciding to load it.
+
+## Related
+
+- [Instructions](./instructions.md): what stays always-on
+- [Tools](./tools.md): when prose needs to become code
+- [Extensions](./extensions.md): skills installed as a package under a
+  namespace
+- [Project layout](./project-layout.md): where skills sit in the tree

package/docs/reference/subagents.md

@@ -0,0 +1,67 @@
+---
+title: "Subagents"
+description: "Specialist child agents the model delegates to mid-turn, each its own directory under bot/subagents/."
+---
+
+# Subagents
+
+A subagent is a specialist child agent the model can delegate to
+mid-turn. Each one lives under `bot/subagents/<id>/` with a required
+`agent.ts`. Add `instructions.md` or inline `instructions` in `agent.ts`
+for a custom prompt. The parent model delegates through the `task` tool,
+and the stream records `subagent.called` and `subagent.completed`.
+
+The `@cursor/bdk` imports on this page are docs-ahead until publication;
+see [BDK package availability](/#bdk-package-availability).
+
+```text
+bot/subagents/researcher/
+├── agent.ts            # description (required), model (optional)
+└── instructions.md     # optional custom system prompt
+```
+
+```ts
+// bot/subagents/researcher/agent.ts
+import { defineAgent } from "@cursor/bdk";
+
+export default defineAgent({
+  description:
+    "Background research: climate history, records, comparisons across many cities.",
+  // model: omit to inherit the parent's model
+});
+```
+
+## Subagent rules
+
+`description` is required. The parent model uses it to decide whether
+to delegate, so write it as a routing rule ("Background research: …"),
+following the same discipline as a [skill](./skills.md) description.
+`model` is optional; omit it to inherit the parent's model, or set it
+to run the specialist on a different model.
+
+Subagents inherit the parent's execution surface. Every per-subagent
+capability directory is reported as a warning and ignored: `tools/`,
+`skills/`, `extensions/`, `mcp-connections/`, `host-connections/`,
+`channels/`, `schedules/`, `reminders/`, `hooks/`, `sandbox/`, and
+nested `subagents/`.
+
+Delegation needs both halves: the description makes it possible, and the
+parent's [instructions](./instructions.md) make it happen. "When a
+request needs background research, delegate to the `researcher`
+subagent." The parent routes; the specialist executes.
+
+## Subagents and peers
+
+Subagents split one job into roles inside a single agent. When the
+specialist is independently useful, with its own tools, sessions, and
+playground, make it a full agent. See
+[Peer agents](../guides/agent-to-agent.md#peer-or-subagent).
+
+## Related
+
+- [Skills](./skills.md): when a procedure is enough and a child agent
+  is overkill
+- [Peer agents](../guides/agent-to-agent.md): independently useful
+  specialists
+- [Agent config](./agent-config.md#harness-tools): `"task"` on the
+  parent's tool allowlist

package/docs/reference/tools.md

@@ -0,0 +1,329 @@
+---
+title: "Tools"
+description: "Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn."
+---
+
+# Tools
+
+A tool is a typed action the model can call: hit an API, run a query,
+write a file. Each file in `bot/tools/` defines one tool, and the
+filename becomes the tool name the model sees. Tools come in two
+execution flavors: server tools run on the serving host, and
+agent tools run as scripts where the agent runs. Every server tool can
+also be called directly, with no model turn.
+
+The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
+until publication; see [BDK package availability](/#bdk-package-availability).
+
+## Define a server tool
+
+By default, `execute` runs in-process on the serving host with full
+access to `process.env` and your `bot/lib/` code. Turns call server
+tools as SDK custom tools.
+
+```ts
+// bot/tools/inspect_pr.ts
+import { defineTool } from "@cursor/bdk/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Inspect a pull request before approval.",
+  // execution: "server" is the default
+  inputSchema: z.object({ prUrl: z.string().url() }),
+  async execute({ prUrl }, ctx) {
+    return { prUrl, checks: ["unit", "lint"], ready: true };
+  },
+});
+```
+
+A tool definition needs a filename slug (the model-facing name), a
+`description` written for the model, an optional `inputSchema`, and the
+code that runs it. With a Zod `inputSchema`, the input is validated before
+`execute` runs and the input type is inferred. A plain JSON Schema
+object is forwarded as-is and the input arrives as raw JSON.
+
+A server tool can call `decide` from
+[`@cursor/bdk/extensions/jev`](../guides/jev.md) for a risk tier or a
+finding gate without a second model turn.
+
+For multi-line descriptions, reminder prompts, and error messages, use
+[`prompt`](./prompt.md) so the string can sit indented with the surrounding
+TypeScript:
+
+```ts
+import { prompt } from "@cursor/bdk";
+import { defineTool } from "@cursor/bdk/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: prompt`
+    Inspect a pull request before approval.
+    Prefer this over guessing from the title alone.
+  `,
+  inputSchema: z.object({ prUrl: z.string().url() }),
+  async execute({ prUrl }) {
+    return { prUrl };
+  },
+});
+```
+
+### Tool context
+
+`execute` receives a `ctx` with the runtime accessors:
+
+| Member | What it is |
+| --- | --- |
+| `ctx.toolCallId` | The call id, matching the `actions.requested` / `action.result` stream events |
+| `ctx.session` | Read-only session info: id, channel, mode, auth |
+| `ctx.workspaceDir` | The session's workspace directory |
+| `ctx.stateRoot` | The agent's durable state root, shared across every session |
+| `ctx.host` | Shared host services (see below) |
+| `ctx.send(channelId, message, options?)` | Start or resume a session on any channel. `auth` defaults to this call's session principal |
+| `ctx.getSession(channelId, sessionId)` | Look up a session on a channel |
+| `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade: `tag` auto-fills the session |
+
+`ctx.host` carries the shared host services: `host.mcp` (authored MCP
+connections: `names()`, `listTools(name)`, `callTool(name, tool, args)`),
+`host.github` and `host.slack` (shared platform clients), `host.kv` and
+`host.files` (durable storage), `host.otel` (custom
+metrics and session tags; see [OpenTelemetry](../guides/opentelemetry.md)),
+`host.reminders` (per-session wakes, when attached).
+
+### Return values
+
+`execute` may return a string (passed to the model verbatim), a
+JSON-shaped value (serialized), or the envelope
+`{ content: [...], isError? }` for rich results. Returns must be
+JSON-shaped: use object literals or `type` aliases. An `interface` type
+fails assignability (no index signature), and tsx won't catch it. Your
+typecheck will.
+
+Throwing inside `execute` reports an error result to the model
+(`isError: true`). The turn and the server keep running.
+
+### Declare structured output
+
+Set `outputSchema` when MCP clients need a structured result contract. Use a
+Zod schema or plain JSON Schema:
+
+```ts
+const Weather = z.object({
+  city: z.string(),
+  temperatureF: z.number(),
+});
+
+export default defineTool({
+  description: "Read the current weather.",
+  inputSchema: z.object({ city: z.string() }),
+  outputSchema: Weather,
+  async execute({ city }) {
+    return { city, temperatureF: 72 };
+  },
+});
+```
+
+BDK advertises the schema. It does not validate tool results against
+it. Plain object returns fill MCP `structuredContent` automatically. An
+envelope return must set `structuredContent` next to `content` and `isError`.
+
+Use the exported `ToolInput<TSchema>` type when another function needs the
+input type inferred from a tool schema.
+
+### Control dry-run effects
+
+Set `effect` to `"read"`, `"write"`, or a predicate over validated input.
+A dry-run session executes reads and answers writes without running their
+tool bodies. An authored tool without `effect` is treated as a write.
+
+```ts
+export default defineTool({
+  description: "Publish a release.",
+  inputSchema: z.object({ version: z.string() }),
+  effect: "write",
+  dryRunResult: ({ version }) => ({ published: false, version }),
+  async execute({ version }) {
+    return publishRelease(version);
+  },
+});
+```
+
+`dryRunResult` keeps the result shape stable. Without it, a stubbed write
+returns `"Operation acknowledged."`. Traces mark the result as stubbed.
+
+### Bound time arguments under `asOf`
+
+Declare `timeArgs` with the input properties that carry time bounds. In a
+session created with `asOf`, every named argument must be an absolute
+ISO-8601 instant with a timezone, no later than the session's frozen
+instant. A call that omits one, or supplies a relative or later value, is
+refused with an error telling the model to retry with absolute bounds.
+Sessions without `asOf` ignore the declaration.
+
+```ts
+export default defineTool({
+  description: "Query telemetry between two instants.",
+  inputSchema: z.object({ since: z.string(), until: z.string() }),
+  effect: "read",
+  timeArgs: ["since", "until"],
+  async execute({ since, until }) {
+    return queryTelemetry(since, until);
+  },
+});
+```
+
+Every name in `timeArgs` must exist in the input schema; a session with
+`asOf` refuses to start otherwise, because a misspelled name would silently
+check nothing.
+
+## Define an agent tool
+
+Set `execution: "agent"` and the tool materializes as a shell script
+that runs in the Cursor agent workspace. The script receives JSON
+arguments on stdin and prints its
+result on stdout. Use this flavor when the tool must run next to the
+checkout the agent works in.
+
+```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"
+`,
+});
+```
+
+Scripts land in the session workspace with a catalog in `AGENTS.md`.
+
+## Tools from an MCP connection, advertised by name
+
+Set `advertiseTools: true` on a connection to expose its MCP tools by
+name. Add per-session `auth` when credentials depend on the caller.
+Model calls and [direct tool calls](#call-a-tool-without-a-model-turn)
+use the same exposed names. See
+[MCP connections](./connections.md#advertise-tools) for the full
+contract.
+
+## Gate a tool on human approval
+
+A server tool can require a person to sign off before it runs. Set
+`needsApproval` to `true`, or to a predicate over the validated input:
+
+```ts
+export default defineTool({
+  description: "Promote a verified build to an environment.",
+  needsApproval: true, // or: (input) => input.environment === "production"
+  inputSchema: z.object({
+    service: z.string(),
+    buildId: z.string(),
+    environment: z.string(),
+  }),
+  async execute({ service, buildId, environment }) {
+    return { promoted: true, service, buildId, environment };
+  },
+});
+```
+
+The call parks, the turn stays running, and the stream emits
+`action.approval_requested` until someone resolves it from the
+playground, `POST /v1/session/:id/approvals/:callId`, or Slack
+Approve/Deny cards. Approvals exist for server tools on the local
+runtime only, and parked calls don't survive a host restart.
+
+## Call a tool without a model turn
+
+Server tools can be called deterministically. You pick the tool and the
+input. Validation and execution match a model-initiated call, and no
+Cursor API key is needed.
+
+Over HTTP, with the same auth chain as the session API:
+
+```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}
+```
+
+From the CLI, which starts an ephemeral server unless `--url` targets
+a running one:
+
+```text
+bdk call inspect_pr --dir . \
+  --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
+bdk call inspect_pr \
+  --url http://127.0.0.1:3000/<slug> \
+  --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
+```
+
+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 calls with
+model turns:
+
+```ts
+const outcome = await handle.callTool("inspect_pr", {
+  prUrl: "https://github.com/acme/checkout/pull/42",
+});
+if (outcome.isError) {
+  return outcome;
+}
+// { toolName, callId, isError, result, durationMs }
+```
+
+Omit both identifiers to run against an ephemeral workspace that is
+removed when the call returns. Pass `sessionId` (HTTP body, `--session`,
+or `options.sessionId`) or `continuationToken` (`<channelId>:<key>` as
+`/v1/sessions` lists it) to bind the call. The two are mutually
+exclusive.
+
+| Rule | What happens |
+| --- | --- |
+| Existing `sessionId`, or a token that maps to an existing session | Session workspace, owner check, and event recording |
+| Token with no matching session | Scratch workspace; the token's channel id and key are the call identity |
+| Busy session, `effect: "read"` (or an advertised MCP tool marked read-only) | Runs alongside the turn, reading the workspace as the turn left it; recorded under its own `turnId` |
+| Busy session, write or undeclared | `409 session_busy` until the turn finishes |
+| Session workspace cannot be created, read | Scratch workspace; the outcome has `scratchWorkspace: true` |
+| Session workspace cannot be created, write | `500 workspace_unavailable` |
+
+| Error | When |
+| --- | --- |
+| `404 unknown_tool` | Name is not a callable server tool; the response lists available names |
+| `400 tool_not_callable` | Agent-execution tools cannot run on the host |
+| `400 invalid_tool_input` | Zod rejected the input before `execute`. Plain JSON Schema is forwarded unvalidated |
+| `400 invalid_continuation_token` | Malformed token, or passed together with `sessionId` |
+| `404 session_not_found` | `sessionId` does not exist |
+| `409 session_busy` | Write-effect call while a model turn is running |
+| `500 workspace_unavailable` | Write-effect call when the session workspace cannot be created |
+| `isError: true` | The tool body threw; same envelope the model would see |
+
+## Design habits
+
+Keep one decision per tool. Small tools with crisp descriptions beat
+multi-purpose tools with mode flags. The model chooses better and evals
+gate cleaner.
+
+Put deterministic policy in tool code, not model judgment. A PR-approval
+tool should re-read the live PR inside the tool before acting, so a
+spoofed payload can't steer it.
+
+Test tools with `call` before blaming prompts. If the tool's output is
+wrong, no instruction change fixes it.
+
+Gate side effects with `needsApproval`. Declare each tool's `effect` so
+dry-run sessions can execute reads and stub writes.
+
+## Related
+
+- [MCP connections](./connections.md): tools that come from MCP servers
+  instead
+- [Extensions](./extensions.md): tools installed as a package under a
+  namespace
+- [Evals](../evals.md): gating tool decisions with `calledTool`

package/docs/templates/agentic-owners.md

@@ -0,0 +1,100 @@
+---
+title: "Review pull requests with owners policies"
+description: "Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows."
+---
+
+# Review pull requests with owners policies
+
+This agent reviews every pull request in your repository. It risk-tiers
+the diff, requests the owning team or user as reviewers, and approves
+what your policy allows. Ownership rules live in
+`.agentic-owners/policy.yml` files committed at any depth of the repo;
+the closest policy to a changed file wins, and policies are always read
+from the PR's base ref so a PR cannot exempt itself.
+
+The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
+until publication; see [BDK package availability](/#bdk-package-availability).
+
+## Scaffold
+
+```text
+bdk init ./owners-agent --template agentic-owners
+```
+
+`init` writes the project, installs dependencies, and puts `bdk`
+on PATH.
+
+## Log in and run
+
+Set your repositories in `bot/lib/config.ts` (`repos: ["you/your-repo"]`),
+then:
+
+```text
+cd owners-agent
+bdk login
+bdk dev
+```
+
+PR events stream through your Cursor account. No webhook or GitHub App
+setup. Open a PR, or replay a real one deterministically (this also works
+with `repos` empty):
+
+```text
+bdk github replay https://github.com/you/your-repo/pull/123 --dir .
+```
+
+Deploy with `bdk deploy`.
+
+## Policies
+
+With no policy files, every PR gets a default risk review: very-low and
+low risk approve, medium and above hold with a comment. Route reviews by
+committing policies:
+
+```yaml
+# .agentic-owners/policy.yml. Anywhere in the repo; closest wins.
+# paths are repo-root-relative globs, wherever the policy file lives.
+version: 1
+policies:
+  - paths: ["docs/**"]
+    always_approve: true
+  - paths: ["src/api/**"]
+    team: acme/platform # or user: alice
+    prompt: api-review.md # optional extra rubric, same directory
+  - paths: ["src/billing/**"]
+    user: alice
+    human_review_required: true # the agent never approves; a person must
+```
+
+`self_review: true` lets a listed owner's own PRs clear their rule.
+`global_exclusions` in the root policy opts paths out entirely.
+
+## What one review does
+
+One model turn per PR head assesses the host-fetched diff against the
+base rubric plus any matched rule prompts, then records a verdict with
+`record_review`. The host recomputes the policy from trusted state and
+applies the deterministic decision:
+
+- **Approve** when the tier is low and no matched rule demands a human,
+  bound to the head SHA.
+- **Request reviewers** otherwise: the policy owners (max 2, never the
+  author), plus one status comment the agent keeps updated in place.
+
+The model never writes to GitHub. A broken policy file fails closed with
+a comment listing the validation issues.
+
+## Rubric
+
+Edit `bot/lib/owners/prompts/base-review.md` for the risk tiers and
+their boundaries. Per-area guidance belongs in policy `prompt:` files
+next to the policy that names them. The next review reads both.
+
+## Evals
+
+```text
+bdk eval
+```
+
+Three smoke reviews (docs-only, auth deletion, prompt injection). Eval
+sessions skip GitHub writes.

package/docs/templates/security-reviewer.md

@@ -0,0 +1,90 @@
+---
+title: "Review pull requests for exploitable bugs"
+description: "Scaffold the agent, pick repos, replay a PR, and deploy."
+---
+
+# Review pull requests for exploitable bugs
+
+This agent reads a pull request diff and posts one review comment. It
+reports exploitable bugs: injection, authz bypass, secret leaks, SSRF,
+RCE. Style nits stay out.
+
+This template is one model turn: read the diff, then post one comment.
+
+The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
+until publication; see [BDK package availability](/#bdk-package-availability).
+
+## Scaffold
+
+```text
+bdk init ./security-reviewer --template security-reviewer
+```
+
+`init` asks which GitHub repos to watch. Every repo must share one
+owner. Pass `--var repos=acme/api,acme/web` to skip the prompt.
+
+The list lands in `bot/lib/repos.ts`. The GitHub channel reads it for
+`cursorAccount` and for the wake filter. Edit that file when the set
+changes.
+
+## Connect GitHub through Cursor
+
+Connect GitHub in Cursor for those repositories (Settings or
+[cursor.com/dashboard](https://cursor.com/dashboard)). Sign the host in:
+
+```text
+cd security-reviewer
+bdk login
+```
+
+`cursorAccount` pulls SCM events from Cursor and mints a short-lived,
+repo-scoped credential. `ctx.host.github` and child `gh` commands share
+it. See the [GitHub guide](../guides/github.md).
+
+## First review
+
+```text
+bdk dev
+```
+
+`dev` starts the Cursor event relay for the watched repos. To drive a
+known PR without waiting on a live push:
+
+```text
+bdk github replay https://github.com/acme/api/pull/12 --dir .
+```
+
+`replay` needs pull access. Draft PRs and repos outside
+`bot/lib/repos.ts` are ignored. The channel writes `pr/diff.patch`
+after the wake is acknowledged, then starts a model turn. The model
+calls `post_findings` once.
+
+Chat replies stay in the playground. `post_findings` writes the GitHub
+comment.
+
+## What to edit
+
+- `bot/lib/repos.ts`: watched repos
+- `bot/instructions.md`: what counts as a finding and the comment
+  shape
+- `evals/review.eval.ts`: smoke cases
+
+## Evals
+
+Two smoke cases: one XSS fixture and one docs-only change.
+
+```text
+bdk eval
+```
+
+Eval sessions skip the GitHub write.
+
+## Deploy
+
+```text
+bdk deploy
+```
+
+Run it from the agent's git checkout. The command infers repository,
+ref, path, and slug. The deployment uses the team's Cursor GitHub
+connection for the same watched repos.