@cursor/bdk 0.2.4 → 0.2.5

package/docs/templates/agentic-owners.md

@@ -12,9 +12,6 @@ what your policy allows. Ownership rules live in
 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

package/docs/templates/grokbot-agents.md

@@ -0,0 +1,60 @@
+---
+title: "Consult named Grok Bot agents"
+description: "Scaffold an agent that delegates a focused question to an allowed Grok Bot agent and carries the reply back."
+---
+
+# Consult named Grok Bot agents
+
+The `grokbot-agents` template lets a BDK agent consult the Grok Bot
+agents you allow. Your BDK conversation stays active while the named
+agent works, and the delivered reply returns to the same conversation.
+A request for an unlisted name is refused.
+
+## Scaffold
+
+```bash
+bdk init ./grokbot-consultant --template grokbot-agents
+```
+
+`init` asks for the names shown in the Grok Bot app. Pass them directly
+in a script:
+
+```bash
+bdk init ./grokbot-consultant --template grokbot-agents \
+  --var agents="Plan Keeper,Chief of Staff"
+```
+
+## Run
+
+Sign in, validate the scaffold, and start the project:
+
+```bash
+cd grokbot-consultant
+bdk login
+bdk validate
+bdk dev
+```
+
+Open the playground and ask the agent to consult one of the names you
+entered. The delivered reply returns to the same conversation.
+
+## Choose who the agent can consult
+
+Edit `bot/extensions/grokbot.ts` to change the allowlist. The template
+supports descriptions that help the model choose the right specialist
+when several names are available.
+
+When someone asks which agents are available, the template lists them
+without sending a message. A consultation sends one self-contained
+question and reports the reply. Long-running consultations can be
+checked later, and an active turn can be interrupted when the task
+changes.
+
+See [Grok Bot agents](../guides/grokbot-agents.md) for the extension's
+conversation and approval boundaries.
+
+## What to edit
+
+- `bot/extensions/grokbot.ts`: allowed agent names
+- `bot/instructions.md`: when to consult them
+- `evals/grokbot-agents.eval.ts`: list-without-sending smoke case

package/docs/templates/security-reviewer.md

@@ -11,9 +11,6 @@ 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

package/docs/templates/thermo-quality-review.md

@@ -6,15 +6,12 @@ description: "Scaffold the agent, deploy it, and open a PR."
 # Review pull requests for structural code quality
 
 This agent reads a pull request diff and posts one review comment. It
-reports missing abstractions, spaghetti branches, feature logic
-leaking into shared paths, and files pushed past 1,000 lines. Style
-nits and behavior disputes stay out.
+reports missing abstractions, deeply nested control flow, feature logic
+leaking into shared paths, and files pushed past 1,000 lines. Style nits
+and behavior disputes 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

package/docs/templates/thermo-review.md

@@ -6,14 +6,12 @@ description: "Scaffold the agent, deploy it, and open a PR."
 # Review pull requests for bugs and breakage
 
 This agent reads a pull request diff and posts one review comment. It
-reports bugs, breaking side effects, devex breaks, and feature-gate
-leaks in added or modified code. Style nits stay out.
+reports bugs, breaking side effects, developer workflow failures, and
+unintended feature exposure in added or modified code. 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

package/docs/templates/triage.md

@@ -12,9 +12,6 @@ duplicate when titles match.
 File the ticket however you already do. This template starts after the
 ticket exists.
 
-The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
-until publication; see [BDK package availability](/#bdk-package-availability).
-
 ## Scaffold
 
 ```text
@@ -22,6 +19,8 @@ bdk init ./triage-agent --template triage-linear
 bdk init ./triage-agent --template triage-jira
 ```
 
+`bdk init --template triage` selects `triage-linear`.
+
 Pick the tracker you use. The agent is the same. The overlay is the
 connection.
 

package/docs/troubleshooting.md

@@ -12,11 +12,7 @@ Start with three checks:
    `bdk info --dir . --json`.
 3. Reproduce once, then inspect the serve log or session trace.
 
-The `bdk` commands on this page are docs-ahead until `@cursor/bdk` is
-published; see [BDK package availability](/#bdk-package-availability).
-
-Match the visible symptom below. The `bdk` binary ships with
-`@cursor/bdk` when the package publishes.
+Match the visible symptom below.
 
 ## Serve or the playground will not work
 
@@ -50,9 +46,9 @@ Match the visible symptom below. The `bdk` binary ships with
 
 | What you see | What to do |
 | --- | --- |
-| `401` outside localhost | Send the configured bearer token, alias token, or channel credential. Default custom routes admit direct loopback only. |
+| `401` outside local development | Send the configured bearer token, alias token, or channel credential. Default custom routes admit direct loopback only. |
 | `403` on a stream or follow-up | Use the same authenticated principal that created the session. |
-| A localhost route fails through a tunnel or LAN | Protect the shared host with `--bearer-token` or authored channel auth. Use `--allow-anonymous` only behind a proxy that authenticates every caller. |
+| A custom channel route fails through a tunnel or LAN | Protect the shared host with `--bearer-token` or authored channel auth. Use `--allow-anonymous` only behind a proxy that authenticates every caller. |
 | `409` on a follow-up | Refresh the rotating `continuationToken` and confirm the target is a chat session; task sessions do not accept follow-ups. |
 | `409 session_busy` from `call --session` | Wait for the turn, omit `--session`, or mark a read-only tool with `effect: "read"` so it can run concurrently. |
 | A custom route fails schema type-checking | Add the required Zod `querySchema` for `GET`, or `bodySchema` for `POST`, `PUT`, and `PATCH`. See [Channels](./reference/channels.md). |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cursor/bdk",
-  "version": "0.2.4",
-  "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
+  "version": "0.2.5",
+  "description": "Build, test, and deploy BDK bots and agents as code on Cursor's agent harness.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
     "type": "git",

package/templates/agentic-owners/README.md

@@ -5,9 +5,6 @@ committed in your repository: risk-tiers the diff, requests the owning
 team or user as reviewers, and approves what the policy allows. Policies
 are always read from the PR's base ref, so a PR cannot exempt itself.
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This command will work
-> after publication.
-
 ```text
 npx @cursor/bdk init ./owners-agent --template agentic-owners
 ```

package/templates/agents-md/README.md

@@ -5,9 +5,6 @@ listed Slack channels. Parks an update until a person approves it, then
 opens a draft follow-up PR. Chores stay quiet. Same-base updates stack
 on `agents-md/<base>`.
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This command will work
-> after publication.
-
 ```text
 npx @cursor/bdk init ./agents-md --template agents-md
 ```
@@ -27,6 +24,10 @@ bdk slack create --dir .
 bdk dev
 ```
 
+The Slack app uses `AGENTS_MD_SLACK_BOT_TOKEN` and
+`AGENTS_MD_SLACK_APP_TOKEN`. `bdk slack create` writes both values to
+`.env.local`.
+
 Schedules do not fire under `dev`. Dispatch the weekly job:
 
 ```text

package/templates/code-wiki/README.md

@@ -4,9 +4,6 @@ Keeps `wiki/` pages current after a pull request merges. Opens a
 follow-up PR against that merge's base when a durable fact changed.
 Skips chores. Same-base updates stack on `wiki/<base>`.
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This command will work
-> after publication.
-
 ```text
 npx @cursor/bdk init ./code-wiki --template code-wiki
 ```

package/templates/demo/README.md

@@ -3,9 +3,6 @@
 Host collects the PR into `pr.md` and `files.md`. The agent records a
 walkthrough and comments the result.
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This command will work
-> after publication.
-
 ```text
 npx @cursor/bdk init ./my-demo --template demo
 ```

package/templates/grokbot-agents/README.md

@@ -3,10 +3,7 @@
 Consults the Grok Bot agents you name. This agent stays in its own
 conversation and reports the reply.
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This command will work
-> after publication.
-
-```text
+```bash
 npx @cursor/bdk init ./grokbot --template grokbot-agents
 ```
 
@@ -15,12 +12,13 @@ with `--var agents="Plan Keeper, Chief of Staff"`.
 
 ## Run
 
-```text
+```bash
 bdk login
+bdk validate
 bdk dev
 ```
 
-In the playground, ask it to talk to one of the names you entered. A
+In the playground, ask it to consult one of the names you entered. A
 name outside the list is refused.
 
 ## Edit

package/templates/security-help/README.md

@@ -3,9 +3,6 @@
 Answers security questions in Slack from your skills and takes a first
 look when someone pastes a GitHub pull request.
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This command will work
-> after publication.
-
 ```text
 npx @cursor/bdk init ./security-help --template security-help
 ```
@@ -18,6 +15,18 @@ npx @cursor/bdk init ./security-help --template security-help
 ```text
 bdk login
 bdk slack create --name "Security Help" --channel-posts
+```
+
+The Slack app uses `SECURITY_HELP_SLACK_BOT_TOKEN` and
+`SECURITY_HELP_SLACK_APP_TOKEN`. `bdk slack create` writes both values
+to `.env.local`.
+
+To watch channel posts, add channel names or IDs to `watch` in
+`bot/channels/slack.ts`, then invite the app to each channel. An empty
+`watch` keeps channel-post dispatch off. Mentions and DMs work without
+this configuration.
+
+```bash
 bdk dev
 ```
 
@@ -34,7 +43,4 @@ one in the playground.
 - `bot/skills/`: how to look at a PR, a leak, or an access ask
 - `bot/instructions.md`: routing
 
-`--channel-posts` is required to watch channels. Mentions and DMs work
-without it.
-
 `bdk eval` runs three smoke turns and writes nothing to Slack or GitHub.

package/templates/security-reviewer/README.md

@@ -2,9 +2,6 @@
 
 Reviews pull requests for exploitable bugs. Posts one review comment.
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This command will work
-> after publication.
-
 ```text
 npx @cursor/bdk init ./security-reviewer --template security-reviewer
 ```

package/templates/thermo-quality-review/README.md

@@ -2,9 +2,6 @@
 
 Reviews pull requests for structural code quality. Posts one review comment.
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This command will work
-> after publication.
-
 ```text
 npx @cursor/bdk init ./thermo-quality-review --template thermo-quality-review
 ```

package/templates/thermo-review/README.md

@@ -2,9 +2,6 @@
 
 Reviews pull requests for bugs and breakage. Posts one review comment.
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This command will work
-> after publication.
-
 ```text
 npx @cursor/bdk init ./thermo-review --template thermo-review
 ```

package/templates/triage/README.md

@@ -4,9 +4,6 @@ Comments on existing Linear or Jira issues. Classifies the ticket, writes
 the next step, links a duplicate, and sets bug priority when the
 connector can.
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This command will work
-> after publication.
-
 ```text
 npx @cursor/bdk init ./my-triage-agent --template triage-linear
 npx @cursor/bdk init ./my-triage-agent --template triage-jira

package/templates/triage/overlays/jira/README.md

@@ -2,9 +2,6 @@
 
 Comments on existing Jira issues. Scaffold with:
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This command will work
-> after publication.
-
 ```text
 npx @cursor/bdk init ./my-triage-agent --template triage-jira
 ```

package/templates/triage/overlays/linear/README.md

@@ -2,9 +2,6 @@
 
 Comments on existing Linear issues. Scaffold with:
 
-> **Docs ahead:** `@cursor/bdk` is not on npm yet. This command will work
-> after publication.
-
 ```text
 npx @cursor/bdk init ./my-triage-agent --template triage-linear
 ```