@cursor/bdk 0.2.1

package/docs/deployment.md

@@ -0,0 +1,216 @@
+---
+title: "Deployment"
+description: "Deploy a BDK project from Git with Cursor-managed hosting, or run one secure process on your own infrastructure."
+---
+
+# Deploy a BDK project
+
+Deployment turns a pushed Grok Bot Development Kit (BDK) project into a stable service.
+Cursor-managed hosting builds the selected Git ref and operates the
+runtime; self-hosting gives you control of the network, process, and
+filesystem.
+
+The `@cursor/bdk` imports and `bdk` commands in these examples are
+docs-ahead until publication; see
+[BDK package availability](/#bdk-package-availability).
+
+## Choose managed hosting or self-hosting
+
+| Option | Use it when | You manage |
+| --- | --- | --- |
+| Cursor-managed hosting | You want the shortest path from Git to a running agent | Source, declared egress, secrets, and agent behavior |
+| Self-hosting | You need your own network, proxy, filesystem, or process controls | The Node process, TLS, auth, secrets, state, monitoring, and upgrades |
+
+The rest of this guide starts with managed hosting. The
+[self-host recipe](#self-host-securely) uses the same project and HTTP
+API.
+
+## Deploy from Git
+
+Commit and push the exact ref you want to run, then sign in, validate,
+and deploy. The preferred CLI is `bdk`.
+
+> **Docs ahead:** `@cursor/bdk` is not on npm yet. This block shows future
+> CLI syntax and will not run until the package publishes.
+
+```text
+cd my-agent
+bdk login
+bdk whoami
+bdk validate
+bdk deploy
+```
+
+The deploy command waits until the engine is running and prints the stable
+deployment URL.
+
+`deploy` reads from Git; it does not upload your working tree. Inside a
+checkout, it infers the HTTPS origin, current ref, agent path, and slug.
+Pass them explicitly when the checkout is not the source you want:
+
+```text
+bdk deploy \
+  --repo https://github.com/acme/agents \
+  --ref main \
+  --path agents/weather \
+  --slug weather-agent
+```
+
+The source repository must be available through the team's repository
+integration, and a nested `--path` must contain an installable BDK
+project.
+
+## Add egress and secrets
+
+Declare the external hosts and secret names the agent needs. After the
+deployment exists, set each value at the hidden prompt and follow the
+CLI or dashboard instruction to redeploy.
+
+```ts
+// bot/agent.ts
+import { defineAgent } from "@cursor/bdk";
+
+export default defineAgent({
+  hosting: {
+    egressDomains: ["api.weather.example.com"],
+    secretNames: ["WEATHER_API_KEY"],
+  },
+});
+```
+
+```text
+bdk secrets set weather-agent WEATHER_API_KEY
+bdk secrets list weather-agent
+bdk deploy --dir . --slug weather-agent
+```
+
+Commit secret names, never values. `secrets set` accepts names and reads
+values without echoing them; `secrets list` returns names and creation
+times only. Do not pass `NAME=VALUE`, print a secret to verify it, or
+put names beginning with reserved `CURSOR_` in `secretNames`.
+
+Enter egress hosts without schemes, ports, or paths. The
+[Host MCP OAuth guide](./guides/mcp-oauth.md) owns the extra secret and
+egress steps for OAuth-backed MCP servers.
+
+## Use the hosted agent
+
+The `--prod` commands authenticate through your Cursor credential and
+connect to the deployment directly. Open the playground, run a turn,
+then inspect the same session in logs.
+
+```text
+bdk playground --prod --slug weather-agent
+bdk run --prod --slug weather-agent \
+  --message "Forecast for Paris"
+bdk logs --prod --slug weather-agent
+bdk deployment weather-agent
+```
+
+External HTTP clients use the stable alias URL and send the alias token
+on every request:
+
+```bash
+curl "$AGENT_ALIAS_URL/v1/health" \
+  -H "X-Agent-Alias-Token: $AGENT_ALIAS_TOKEN"
+```
+
+The first deploy prints this token once. Store it outside terminal
+transcripts; it cannot be retrieved later. If it is lost or exposed,
+`bdk rotate-token weather-agent` replaces it and invalidates the
+old value.
+
+`deployment --json` can include short-lived access headers, so treat
+that output as a credential too.
+
+For a custom webhook whose provider cannot send the alias token, use
+`publicEndpoint()` only when the channel verifies the provider
+signature. That opens the custom channel path, not the built-in session
+or tool APIs. See [Webhooks](./guides/webhooks.md).
+
+## Update the deployment
+
+Push the new ref and deploy the same slug. The stable URL remains while
+the new generation replaces the previous one.
+
+```text
+bdk deploy --dir . --slug weather-agent
+```
+
+A redeploy replaces its source, Cursor-event repository list, and any
+egress domains supplied through CLI flags. Repass
+`--cursor-events-repo` and other CLI-only settings each time. Keep
+source-controlled egress in the `hosting` block when possible.
+
+Use `bdk deployment weather-agent` and
+`bdk logs --prod --slug weather-agent` to inspect a rollout.
+The [CLI reference](./reference/cli.md#deploy) owns `--no-wait`,
+multi-agent deployment, stop, and delete behavior.
+
+## Keep state across replacements
+
+Managed hosting persists framework-owned session, KV, and file state
+across normal runtime replacements. Files written elsewhere on the
+engine's local filesystem are disposable; use `ctx.host.kv` or
+`ctx.host.files` for durable application state.
+
+Parked approvals and in-memory reminder handlers do not survive a
+restart. Run the turn again or recreate the reminder after a
+replacement.
+
+## Self-host securely
+
+Run BDK under Node 22.13 or newer, never Bun. One supervised
+process can serve every agent under a directory while a persistent
+state root keeps sessions across restarts.
+
+```text
+export CURSOR_API_KEY="<cursor-api-key>"
+export BDK_BEARER_TOKEN="$(openssl rand -hex 32)"
+
+bdk serve \
+  --dir /srv/agents \
+  --host 127.0.0.1 \
+  --port 3000 \
+  --state-root /var/lib/bdk \
+  --bearer-token "$BDK_BEARER_TOKEN"
+```
+
+Before exposing the host:
+
+- Put TLS or an authenticating proxy in front of the loopback server.
+
+- Keep `--bearer-token` on shared hosts. Use `--allow-anonymous` only
+  behind a proxy that authenticates every caller.
+
+- Mount `--state-root` on a persistent volume outside the agent
+  repository and back it up.
+
+- Inject credentials at startup instead of baking them into an image.
+
+- Run the process under a supervisor and enable schedules on exactly
+  one serving process per project.
+
+Containers use the same command with `--host 0.0.0.0`, a mounted state
+volume, and an authenticating network boundary. The
+[Channels reference](./reference/channels.md#auth-policies) covers
+per-caller and channel-specific auth.
+
+## Observability
+
+Use `bdk logs --prod` for runtime output,
+[OpenTelemetry](./guides/opentelemetry.md) for traces and metrics, and
+[session traces](./reference/sessions.md#inspect-a-saved-event-stream)
+for one conversation.
+
+## Related
+
+- [CLI reference](./reference/cli.md#deploy): inspect, update, stop,
+  delete, and rotate deployments
+- [GitHub](./guides/github.md): Cursor-event repositories and direct
+  webhook delivery
+- [Slack](./guides/slack.md): provision a dedicated hosted Slack app
+- [Host MCP OAuth](./guides/mcp-oauth.md): persist OAuth credentials
+  across hosted replacements
+- [Troubleshooting](./troubleshooting.md): diagnose failed or stale
+  deployments

package/docs/evals.md

@@ -0,0 +1,262 @@
+---
+title: "Evals"
+description: "Protect agent decisions with fixed inputs, trajectory assertions, and regression checks that run locally or in CI."
+---
+
+# Evals
+
+An eval sends a fixed input to the real agent and checks the resulting
+trajectory: whether the turn succeeded, which tools ran, and what shape
+the answer took. Use evals to protect behavior you already understand,
+not to discover what the prompt should do.
+
+Evals run real model turns and real tools. Guard external writes before
+running a suite against an agent that can post, merge, or deploy.
+
+The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
+until publication; see [BDK package availability](/#bdk-package-availability).
+
+## Protect a tool decision
+
+This smoke case asks for a PR verdict, requires the read-only inspection
+tool, and fails if the agent tries to approve. The CLI reports all three
+decisions together instead of stopping at the first miss.
+
+Use the [Jev extension](./guides/jev.md) when host code needs a typed
+choice, score, or boolean before it writes.
+
+```ts
+// evals/readiness.eval.ts
+import { defineEval, includes } from "@cursor/bdk/evals";
+
+export default defineEval({
+  tags: ["smoke"],
+  async test(t) {
+    await t.send(
+      "Is https://github.com/acme/checkout/pull/42 ready to approve?"
+    );
+
+    t.succeeded();
+    t.calledTool("inspect_pr");
+    t.notCalledTool("approve_pr");
+    t.check(t.reply, includes(/ready|blocked|approve/i));
+  },
+});
+```
+
+Evals live in the project-root `evals/` directory, beside `bot/`.
+Add the required concurrency config once:
+
+```ts
+// evals/evals.config.ts
+import { defineEvalConfig } from "@cursor/bdk/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 20,
+});
+```
+
+```text
+bdk eval --dir . --list
+bdk eval --dir . --tag smoke
+```
+
+## Check answer shape or quality
+
+Prefer a deterministic shape check when the output has a contract. The
+failure tells you which field was wrong, and the case remains stable
+when the model changes its wording.
+
+```ts
+import { matches } from "@cursor/bdk/evals";
+import { z } from "zod";
+
+const verdict = JSON.parse(t.reply ?? "{}");
+t.check(
+  verdict,
+  matches(
+    z.object({
+      ready: z.boolean(),
+      blockers: z.array(z.string()),
+    })
+  )
+);
+```
+
+Use a judge when correctness depends on meaning that a schema, regex, or
+known value cannot capture:
+
+```ts
+t.judge
+  .factuality("The lint step failed on src/sidebar.ts.")
+  .atLeast(0.8);
+```
+
+Judge checks are tracked scores until you give them a hard gate.
+Configure the judge model in `evals.config.ts`. The
+[Evals reference](./reference/evals.md#judges) owns grader options and
+severity rules.
+
+## Test a conversation or approval
+
+Several `t.send` calls in one case share a session. Assertions on a
+returned turn inspect only that turn, while assertions on `t` inspect
+the whole conversation.
+
+```ts
+const first = await t.send("Inspect PR 42.");
+first.calledTool("inspect_pr");
+
+const followUp = await t.send("Now summarize only the blockers.");
+followUp.usedNoTools();
+t.check(followUp.message, includes(/blocker/i));
+t.succeeded();
+```
+
+For a tool that requires approval, the expected result is a parked turn
+instead of a completed one:
+
+```ts
+await t.send("Apply the approved policy update.");
+t.parked();
+t.calledTool("apply_policy", {
+  input: { verdict: "update" },
+});
+```
+
+Pair an approval case with a safe branch that calls
+`t.notCalledTool("apply_policy")`, so both sides of the decision stay
+protected.
+
+## Pin realistic inputs
+
+A useful eval changes only when the agent changes. Freeze canonical chat
+prompts, seed workspace evidence directly, and save webhook payloads
+instead of depending on a developer's checkout or live external state.
+
+```ts
+await t.send("Review pr/diff.patch and report blockers.", {
+  workspaceFiles: {
+    "pr/diff.patch": [
+      "diff --git a/app/routes/search.ts b/app/routes/search.ts",
+      "+res.send(`<h1>Results for ${req.query.q}</h1>`);",
+    ].join("\n"),
+  },
+});
+```
+
+For GitHub agents, snapshot a PR into committed fixtures:
+
+```text
+bdk github replay acme/checkout#42 \
+  --events '*' \
+  --dry-run \
+  --out fixtures/github
+```
+
+Keep a small, fast `smoke` set for every change. Put larger datasets and
+drift-prone live cases behind an explicit selection. See
+[Datasets and fixtures](./reference/evals.md#datasets-and-fixtures) for
+loaders and case expansion.
+
+## Run and debug a regression suite
+
+Run one case while iterating, then the smoke suite before review. A
+failure artifact records the input, assertions, tool calls, and final
+text, making it the first place to look before changing the prompt.
+
+```text
+bdk eval --dir . readiness
+bdk eval --dir . --tag smoke
+bdk eval --dir . --json
+```
+
+By default, results land under `evals/<stamp>/` in the project state
+directory. Open `evals/<case-id>.json` inside that run directory for the
+failed case. This artifact location is independent of `--state-root`;
+pass `--artifacts <dir>` to choose another destination.
+
+Model turns need a credential. Resolution checks `CURSOR_API_KEY`,
+`CURSOR_API_KEY_FILE`, `CURSOR_SERVICE_ACCOUNT_KEY`, then a saved
+`bdk login`. `eval --list` only discovers cases and needs none.
+
+## Run evals in CI
+
+Write machine-readable output and JUnit annotations, then let a failed
+gate fail the job:
+
+```text
+# CURSOR_API_KEY comes from the CI secret store.
+bdk eval --dir . --json --no-stream \
+  --junit reports/evals.xml \
+  --artifacts reports/evals \
+  > reports/evals.json
+```
+
+Run `--tag smoke` on pull requests and the full suite on a schedule when
+cost or latency makes every-push coverage impractical. Use soft scores
+for a new probabilistic benchmark until its threshold is trustworthy.
+
+The [CLI reference](./reference/cli.md#eval) covers selectors, hosted
+runs, exit codes, and JSON output.
+
+## Keep side effects out of eval sessions
+
+Eval sessions carry `purpose: "eval"`. Check it at the deterministic
+write boundary and return the decision without performing the external
+action:
+
+```ts
+async execute({ findings }, ctx) {
+  if (ctx.session.purpose === "eval") {
+    return {
+      posted: false,
+      reason: "eval",
+      count: findings.length,
+    };
+  }
+
+  return await postFindings(findings);
+}
+```
+
+This preserves the tool call in the trajectory, so the eval can still
+assert that the agent chose to post.
+
+## Evals, hooks, or hillclimbing?
+
+Use an eval to gate one fixed input. Use a
+[hook](./reference/hooks.md) to observe every live session for metrics,
+auditing, or alerts. Use [hillclimbing](./hillclimbing.md) to decide
+which source change improves a fixed set of inputs; every kept
+hillclimb change should add an eval.
+
+## Gates and scores
+
+`t.succeeded()`, tool assertions, and deterministic checks are hard
+gates by default. A failed gate fails the case. `.soft()` records a
+measurement without blocking, while `.atLeast(threshold)` records a
+score and marks a miss as `scored`.
+
+Start with decisions and output shape: the intended tool, the tempting
+wrong tool, and one structural check. Exact prose is rarely a stable
+contract.
+
+## Keep improvements with regression evals
+
+Every kept improvement needs an eval that would have failed before the
+change. A tool-choice gate, bounded `maxToolCalls`, or output-shape check
+turns the improvement into a durable contract.
+
+Never weaken an existing gate to make a new implementation pass. That
+moves the freeze line instead of proving the change.
+
+## Related
+
+- [Evals reference](./reference/evals.md): complete authoring and runner
+  contracts
+- [`skills/evals/SKILL.md`](../skills/evals/SKILL.md): author and seed
+  cases with a coding agent
+- [Hillclimbing](./hillclimbing.md): measure a change and lock the win
+- [Sessions](./reference/sessions.md): events available to trajectory
+  assertions

package/docs/guides/agent-to-agent.md

@@ -0,0 +1,157 @@
+---
+title: "Peer agents"
+description: "Let one BDK agent consult an independent specialist, continue its session, or call its deterministic tools."
+---
+
+# Peer agents
+
+A peer connection lets one agent ask another agent on the same host for
+help. The specialist keeps its own instructions, tools, and session,
+while the caller decides when to delegate and returns the answer to the
+user. Co-host both projects under one `bdk` process.
+
+The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
+until publication; see [BDK package availability](/#bdk-package-availability).
+
+## Delegate a question to a specialist
+
+Ask the concierge about the weather and it hands the question to the
+specialist. The weather agent answers in its own context, then the
+concierge returns that answer to you.
+
+```ts
+// bot/mcp-connections/weather.ts
+import { defineConnection } from "@cursor/bdk/connections";
+
+export default defineConnection({
+  agent: "weather-agent",
+  description: "Delegate weather questions to the weather specialist.",
+});
+```
+
+Give the concierge a narrow routing rule:
+
+```md
+When a request needs current weather, ask the `weather` peer. Return its
+answer.
+```
+
+```text
+bdk dev ./agents
+bdk chat --url http://127.0.0.1:3000/concierge \
+  --message "What's the weather in Paris right now?"
+```
+
+The connection filename is the MCP server name the concierge calls, and
+`agent` is the specialist's mount slug, normally its directory name.
+
+## Continue the specialist's session
+
+Ask a follow-up about the same forecast and the specialist picks up
+where it left off, with its own instructions and tool history still in
+place. The first `ask` returns `{ status, sessionId, reply }` as text on
+the `callTool` result. Parse `sessionId` and pass it on the next `ask`
+so the peer remembers its earlier work instead of starting fresh.
+
+```ts
+const first = await ctx.host.mcp.callTool("weather", "ask", {
+  message: "What's the weather in Paris right now?",
+});
+const firstText = first.content.find((part) => part.type === "text");
+if (firstText?.text === undefined) {
+  throw new Error("weather ask returned no text payload");
+}
+const { sessionId } = JSON.parse(firstText.text) as { sessionId: string };
+
+await ctx.host.mcp.callTool("weather", "ask", {
+  message: "How does that compare with tomorrow?",
+  sessionId,
+});
+```
+
+If the specialist is still working, `ask` returns `status: "running"`
+with the session ID, and you can do other work before calling `check`.
+
+```ts
+await ctx.host.mcp.callTool("weather", "check", {
+  sessionId,
+  waitSeconds: 20,
+});
+```
+
+The peer owns this session, so follow-ups continue the specialist's
+context.
+
+## Call a deterministic peer tool
+
+You need a forecast for Paris, and the weather agent already has
+`get_forecast`. Host code calls that tool in the specialist's workspace
+and the forecast comes back to the concierge, with no second model turn.
+
+```ts
+const result = await ctx.host.mcp.callTool("weather", "call_tool", {
+  toolName: "get_forecast",
+  input: { city: "Paris" },
+});
+const part = result.content.find((item) => item.type === "text");
+if (part?.text === undefined) {
+  return { ok: false, forecast: null };
+}
+const payload = JSON.parse(part.text) as {
+  isError?: boolean;
+  result?: unknown;
+};
+
+return {
+  ok: result.isError !== true && payload.isError !== true,
+  forecast: payload.result ?? null,
+};
+```
+
+`call_tool` appears only when the peer declares at least one
+deterministic server tool.
+
+## Peer or subagent?
+
+Use a [subagent](../reference/subagents.md) to split one agent's job
+into roles that share its project. Use a peer when the specialist is a
+complete agent you would also run, inspect, or expose on its own.
+
+| | Subagent | Peer |
+| --- | --- | --- |
+| Context | Child role inside one agent | Independent agent and session |
+| Tools and connections | Inherits the parent project | Owns its project surface |
+| Reachability | Parent only | Other co-hosted agents and MCP clients |
+
+## Affinity
+
+Those turns show up in the peer's playground. Only the session owner
+can continue or check them.
+
+## Practices
+
+- Give each caller a one-way routing rule, and don't configure reciprocal
+  routes for the same request.
+
+- Prefer `ask` when the specialist should reason. Use `call_tool` when
+  host code already knows which server tool to run.
+
+## Other hosts
+
+Peers require the default multi-agent layout; unknown slugs and
+self-references fail at startup.
+
+Local-runtime peers on the same serve host use loopback. Turns that run
+elsewhere cannot reach that address, so expose the process separately,
+protect it with `--bearer-token`, and pass its external base URL through
+`--public-url`. The flag advertises the URL; it does not expose the
+process. The [Deployment guide](../deployment.md) owns the hosting setup.
+
+## Related
+
+- [MCP connections](../reference/connections.md#peer-mcp-connection):
+  peer configuration and connection naming
+- [MCP endpoint](../reference/http-api.md#mcp-endpoint): exact `ask`,
+  `check`, and `call_tool` schemas
+- [Subagents](../reference/subagents.md): specialists inside one agent
+- [Deployment](../deployment.md): secure shared-host setup