@cursor/july 0.1.43 → 0.1.45

package/docs/quickstart.md

@@ -1,29 +1,27 @@
 ---
-title: "Build your first PR approver"
-description: "Create an agent that reviews pull requests by complexity, approves the safe ones, and wakes from GitHub webhooks."
+title: "Build your first PR reviewer"
+description: "Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events."
 ---
 
-# Build your first PR approver
+# Build your first PR reviewer
 
-Build an agent that reviews GitHub pull requests. It fetches the diff,
-rates the change's complexity in plain TypeScript, approves the safe
-ones, and flags the rest for a human. Then wire it to GitHub webhooks
-and watch a pull request wake it.
+Build a GitHub PR reviewer that classifies changes as `trivial`,
+`moderate`, or `large`, then approves safe changes or requests human
+review. Add GitHub event handling so pull requests can trigger reviews.
 
-The split is the point of the exercise: deterministic policy lives in
-typed tools, judgment lives in the model, and every decision is
-inspectable in the playground.
+## Getting started
 
-## Prerequisites
+- **Get started with an agent in Cursor:** follow
+  [Scaffold an agent with Cursor](./scaffolding-agents.md) and ask Cursor
+  to read [`skills/create-agent/SKILL.md`](../skills/create-agent/SKILL.md).
+- **Get started in the CLI:** continue below.
 
-You need:
+## Prerequisites
 
 - Node 22.13 or newer. Bun isn't supported.
-- The `agent-sdk` CLI. `npx @cursor/july init ./pr-approver` bootstraps
-  it with no prior install: `init` scaffolds the project, runs
-  `npm install`, links `agent-sdk` onto your PATH, and offers a Cursor
-  sign-in. See [Run the CLI](/#run-the-cli) for other setups, such as a
-  monorepo source checkout.
+- Run commands as `agent-sdk <command>`, or use
+  `npx @cursor/july <command>` when the CLI isn't on `PATH`. See
+  [Run the CLI](/#run-the-cli) for monorepo checkouts and other setups.
 - A Cursor credential for model turns. Sign in once:
 
 ```bash
@@ -32,122 +30,33 @@ agent-sdk login
 
 You can also set `CURSOR_API_KEY` instead of signing in.
 
-- A GitHub credential. `gh auth login` is enough, or set
-  `GITHUB_TOKEN`. The tools you write resolve either one
-  automatically. Reading pull requests works on any public repo;
-  posting reviews needs write access to the repo you review.
+- Authenticate with `gh auth login` or `GITHUB_TOKEN`. You can read
+  public pull requests. Posting reviews requires repository write access.
 
-## First run in 10 minutes
+## Create and run the project
 
-Want a working agent before the full tutorial? Four commands get you
-there:
+Initialize the project and start the development server:
 
 ```bash
-npx @cursor/july init ./pr-approver     # scaffold + npm install + PATH link + sign-in offer
-cd pr-approver
-agent-sdk dev                           # serve, and print the playground URL
-```
-
-Open the playground URL and chat with the scaffold. Then, in a second
-terminal (`dev` keeps running), run one turn from the command line:
-
-```bash
-agent-sdk run --dir . --message "Introduce yourself in one sentence."
-```
-
-That's the whole loop: files become an agent, `dev` serves it, and
-`run` exercises it. The rest of this page turns that scaffold into a
-real PR approver.
-
-## Scaffolding Agents
-
-Have Cursor read [`skills/create-agent/SKILL.md`](../skills/create-agent/SKILL.md)
-and describe what you want:
-
-> Build me a PR approver for the playground. Start with one tool that
-> inspects a pull request and guide me through the remaining decisions.
-
-Cursor asks for missing choices, shows you the plan, then builds and
-verifies the agent. Continue below to do the same by hand.
-
-See [Scaffold an agent with Cursor](./scaffolding-agents.md) for the
-full guided workflow.
-
-## Create your project
-
-Start with the built-in scaffold:
-
-```bash
-npx @cursor/july init ./pr-approver
-cd pr-approver
+npx @cursor/july init ./sdk-pr-reviewer
+cd sdk-pr-reviewer
 agent-sdk dev
 ```
 
-The scaffold creates the files the Agent SDK discovers, plus empty capability
-folders (each with a `.gitkeep`) so you can drop tools, channels, and
-evals in place:
-
-```text
-pr-approver/
-├── agent/
-│   ├── agent.ts
-│   ├── instructions.md
-│   ├── tools/
-│   │   └── echo.ts
-│   ├── skills/
-│   ├── mcp-connections/
-│   ├── subagents/
-│   ├── channels/
-│   ├── hooks/
-│   │   └── memory.ts
-│   ├── ab/
-│   ├── schedules/
-│   ├── sandbox/workspace/
-│   └── lib/
-├── evals/
-├── package.json
-└── tsconfig.json
-```
-
-`agent.ts` holds the model and runtime settings. `instructions.md` is
-the always-on system prompt, and the scaffold's version includes a
-memory section that tells the agent how to consult its journal. Each
-file under `agent/tools/` becomes a tool, and `agent/hooks/memory.ts`
-journals every turn so future sessions can recall past work (delete it
-to opt out). `tsconfig.json` type-checks the project (`npm run check`);
-the framework runs your TypeScript directly, so nothing compiles.
-
-`agent-sdk dev` blocks until you stop it. Keep it running and open a
-second terminal for every other command on this page, starting with
-these checks:
+Keep `agent-sdk dev` running. In a second terminal, run:
 
 ```bash
-agent-sdk validate --dir .
-agent-sdk info --dir .
-```
-
-These commands inspect the project without starting a model turn.
-
-## Run your agent
-
-The scaffold already works. Run one turn from the terminal:
-
-```bash
-agent-sdk run --dir . \
-  --message "Introduce yourself in one sentence."
+agent-sdk run --dir . --message "Introduce yourself in one sentence."
 ```
 
-`run` starts the agent, sends the message, and waits for the final
-reply. It prints a JSON trajectory with the response, tool calls, and
-token usage. It also writes an NDJSON trace under
-`.agent-serve/traces/`.
+Confirm the agent replies.
 
-## Teach it to review
+## Add review instructions
 
 Replace `agent/instructions.md`:
 
 ```md
-# PR approver
+# PR reviewer
 
 You review GitHub pull requests. Be specific and brief.
 
@@ -178,9 +87,6 @@ rm agent/tools/echo.ts
 
 ## Add a shared helper
 
-Both tools need to split a PR URL into its parts. Shared code lives in
-`agent/lib/`, which the framework never loads as tools.
-
 Create `agent/lib/github.ts`:
 
 ```ts
@@ -213,7 +119,7 @@ import { parsePullUrl } from "../lib/github.js";
 
 export type Complexity = "trivial" | "moderate" | "large";
 
-/** Deterministic policy: the tool rates the change, not the model. */
+/** Rate complexity from fixed line and file-count thresholds. */
 function rateComplexity(linesChanged: number, changedFiles: number): Complexity {
   if (linesChanged <= 25 && changedFiles <= 2) {
     return "trivial";
@@ -280,58 +186,30 @@ export default defineTool({
 });
 ```
 
-The file adds one tool named `inspect_pr`:
-
-- `description` tells the model when to call it.
-- `inputSchema` defines and validates the arguments.
-- `execute` runs on the server and returns data to the model.
+## Verify complexity classification
 
-Two details carry the design. `rateComplexity` is the review policy,
-and it lives in code: the model never decides what counts as a big
-change. And `ctx.host.github` is the shared host GitHub client, so the
-tool inherits whatever credential the host has (a token, `gh auth`, or
-a GitHub App) without parsing any of it.
-
-## Try the inspect tool
-
-Call the tool directly first, on a real merged pull request:
+Run `inspect_pr` against a small pull request:
 
 ```bash
 agent-sdk call inspect_pr --dir . \
   --input '{"prUrl":"https://github.com/facebook/react/pull/35623"}'
 ```
 
-`call` validates the input and runs `execute` without a model turn.
-This PR is a one-character typo fix, so the result comes back rated
-`trivial` with the whole patch inline:
-
-```json
-{
-  "title": "Fix typo: accomodate -> accommodate",
-  "additions": 1,
-  "deletions": 1,
-  "changedFiles": 1,
-  "complexity": "trivial",
-  "files": [{ "path": "compiler/packages/...", "patch": "@@ -1315,7 ..." }]
-}
-```
+Confirm the result contains `"complexity": "trivial"`.
 
-Now call it on the PR that added `experimental_useEvent` to React:
-1,027 additions across 26 files.
+Run it against a large pull request:
 
 ```bash
 agent-sdk call inspect_pr --dir . \
   --input '{"prUrl":"https://github.com/facebook/react/pull/25229"}'
 ```
 
-The rating flips to `large` and the patches disappear from the result.
-The policy in the tool decides how much the model gets to see, before
-any model turn spends a token on it.
+Confirm the result contains `"complexity": "large"` and no `patch`
+fields.
 
 ## Add the review tool
 
-The approver needs a way to act on its verdict. Create
-`agent/tools/submit_review.ts`:
+Create `agent/tools/submit_review.ts` to post each verdict:
 
 ```ts
 import { defineTool } from "@cursor/july/tools";
@@ -354,10 +232,10 @@ export default defineTool({
     const { owner, repo, number } = parsePullUrl(prUrl);
     const review =
       verdict === "approve"
-        ? { event: "APPROVE" as const, body: `PR approver: ${summary}` }
+        ? { event: "APPROVE" as const, body: `PR reviewer: ${summary}` }
         : {
             event: "COMMENT" as const,
-            body: `PR approver: this change needs a human review. ${summary}`,
+            body: `PR reviewer: this change needs a human review. ${summary}`,
           };
 
     const octokit = await ctx.host.github.getOctokit();
@@ -373,47 +251,24 @@ export default defineTool({
 });
 ```
 
-The tool posts a real review: an APPROVE when the agent approves, a
-comment asking for a human otherwise. Two GitHub rules shape how you
-test it. Your credential needs write access to the repo it reviews,
-and GitHub rejects approving your own pull request, so hand the agent
-a teammate's PR rather than one you authored. When a post fails, the
-tool call reports the GitHub error to the model and the turn keeps
-going.
-
-Want a person to sign off before the review lands? Set
-`needsApproval: true` on the tool and the call parks until someone
-approves it from the playground or Slack.
-[Human-in-the-loop approvals](./guides/human-in-the-loop.md) shows the
-flow.
+Use a GitHub credential with write access and a pull request you didn't
+author.
 
 ## Review a pull request
 
-Run the whole loop on a pull request your credential can review. A
-teammate's open PR is the right pick: write access to the repo, and
-not authored by you.
+Review an open pull request:
 
 ```bash
 agent-sdk run --dir . \
   --message "Review https://github.com/acme/checkout/pull/42"
 ```
 
-The trajectory shows two tool calls. The agent inspects the PR, reads
-the patches, and submits its verdict. A small, clean change gets an
-APPROVE review on the spot, with a one-line summary of what it checked.
-A large one gets a comment asking for a human review, pointing at the
-files a reviewer should start with. Same instructions, different
-behavior, because the policy in the tool decided how much the model got
-to see.
-
-Open the PR on GitHub: the review is on the timeline, posted by
-whatever identity your credential belongs to.
+Confirm `inspect_pr` runs before `submit_review`, then verify the review
+on GitHub.
 
-## Wake it from GitHub
+## Trigger reviews from GitHub
 
-A reviewer you have to prompt is only half useful. Give the agent a
-GitHub channel so pull requests wake it. Create
-`agent/channels/github.ts`:
+Create `agent/channels/github.ts`:
 
 ```ts
 import {
@@ -424,10 +279,8 @@ import {
 const REVIEW_ACTIONS = new Set(["opened", "reopened", "ready_for_review"]);
 
 export default githubChannel({
-  botName: "pr-approver",
+  botName: "sdk-pr-reviewer",
   webhookEvents: ["pull_request"],
-  // submit_review owns every GitHub write. Without these flags the channel
-  // also posts chat replies and reactions to the PR when the token allows it.
   deliverReplies: false,
   progress: { reactions: false },
   onPullRequest: (ctx, pr) => {
@@ -446,57 +299,66 @@ export default githubChannel({
 });
 ```
 
-The channel mounts `POST /v1/channels/github` and dispatches on the
-`pull_request` events you declared. Opened, reopened, and undrafted PRs
-start a model turn; everything else returns `null` and is skipped.
-
-Serve the agent, then replay a real PR at it from a second terminal.
-`replay` reads the PR through `gh api`, synthesizes a GitHub-shaped
-webhook delivery, and POSTs it to the channel. No repo admin, no
-tunnel:
+Keep `agent-sdk dev` running. In a second terminal, replay an open pull
+request. Pull access is enough; repo admin isn't required:
 
 ```bash
-agent-sdk dev
-# second terminal:
 agent-sdk github replay https://github.com/acme/checkout/pull/42 \
   --dir . --action opened
 ```
 
-The replay prints the delivery, and the serve terminal shows the wake:
+Open the playground and confirm `Review acme/checkout#42` contains the
+trigger, both tool calls, and the verdict.
 
-```text
-[agent-sdk] replaying acme/checkout#42 (pull_request) → 1 channel
-[agent-sdk]   pull_request.opened → pr-approver/github 200
-```
+## Run options
+
+1. **CLI message**
+
+   ```bash
+   agent-sdk run --dir . --message "Review https://github.com/acme/checkout/pull/42"
+   ```
+
+2. **Local replay**
+
+   ```bash
+   agent-sdk github replay https://github.com/acme/checkout/pull/42 \
+     --dir . --action opened
+   ```
+
+3. **Forward or `--cursor-events`**
+
+   Pull Cursor events:
+
+   ```bash
+   agent-sdk serve --dir . --cursor-events --repo owner/repo
+   ```
+
+   Forward GitHub webhooks:
+
+   ```bash
+   agent-sdk github forward --dir .
+   ```
 
-The agent runs the same inspect-then-submit loop, unprompted this time.
-Replay the same PR again and the channel resumes that PR's session
-instead of starting a new one: each pull request keeps one running
-conversation.
+   Keep the local `dev` or `serve` process running.
 
-## Open the playground
+4. **Hosted deployment**
 
-Keep `agent-sdk dev` running and open the playground URL it printed. The
-webhook session is in the session list, titled
-`Review acme/checkout#42`, with the trigger message, both tool calls,
-and the verdict laid out. Start a new chat there and ask for another
-review to watch a turn stream live.
+   Deploy once, set the GitHub App secrets, then redeploy:
 
-## Go live
+   ```bash
+   agent-sdk deploy
+   agent-sdk secrets set sdk-pr-reviewer GITHUB_APP_ID GITHUB_APP_PRIVATE_KEY
+   agent-sdk deploy
+   ```
 
-Replay is for development. For real deliveries, serve with
-`--cursor-events --repo owner/repo` to pull events for repositories
-connected to Cursor with no public URL, or run
-`agent-sdk github forward` to relay webhooks to your dev server. The
-[GitHub guide](./guides/github.md) compares the options. In production,
-give the host GitHub App credentials so reviews post as your app's bot
-identity instead of a personal account.
+See [GitHub](./guides/github.md) for local event delivery and
+[Deployment](./deployment.md) for hosting.
 
 ## Where to go next
 
-- [`examples/approval-buddy`](../examples/approval-buddy/): the
-  production-shaped sibling, with commit statuses, review subagents,
-  and a deterministic stamp policy
+- [`examples/approval-buddy`](../examples/approval-buddy/): an example
+  with commit statuses, review subagents, and a deterministic stamp
+  policy
 - [Evals](./evals.md): freeze these two PRs as regression checks so
   prompt changes can't flip a verdict
 - [Tools](./reference/tools.md): more on typed tools, approvals, and

package/docs/reference/agent-config.md

@@ -44,6 +44,7 @@ export default defineAgent({
 | `hosting` | `{ egressDomains?, secretNames? }` | Managed-hosting declarations read by `agent-sdk 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 [Allowlist built-in harness tools](#allowlist-built-in-harness-tools). |
 
 ## Choose a model
 
@@ -120,6 +121,57 @@ outside it (or runs with `--state-root` under `/tmp`). An agent that
 *needs* a specific checkout's skills and rules points `cwd` inside that
 checkout.
 
+## Allowlist built-in harness tools
+
+`tools` names which of the Cursor harness's built-in tools the model
+is offered, riding the SDK's `AgentOptions.tools`. It is opt-in by
+design: unset keeps the model's full standard toolset, and once set
+the agent gets exactly what it names — nothing more. `[]` removes
+every native built-in tool. There is deliberately no exclusion form:
+an agent that restricts tools states what it keeps, so tools the
+platform adds later stay off until someone opts in.
+
+```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"],
+});
+```
+
+One name is injected for you: **`"mcp"` is always granted alongside a
+configured allowlist**. It is transport, not capability — this kit's
+authored server tools reach the model over the SDK custom-tool MCP
+path, so omitting it would silently strand `agent/tools/`. What MCP
+actually exposes stays governed by the second layer: the tools you
+author, the connections you declare, and the harness cwd's ambient
+`.cursor` config. An agent that must not see a checkout's MCP servers
+points `local.cwd` outside it (see [Local cwd](#local-cwd)), and
+`local.sandbox` makes MCP tool calls fail closed.
+
+The other names use the SDK's public tool vocabulary (`"shell"`,
+`"read"`, `"edit"`, `"grep"`, `"glob"`, `"ls"`, `"task"`, ...);
+unknown names fail the turn with a `ConfigurationError`. Two deserve
+care: `"shell"` is a capability group that also grants shell stdin
+writes — and is what `execution: "agent"` tool scripts run through,
+so an allowlist without it strands them (discovery warns about that
+combination). `"task"` gates subagents (which otherwise keep their
+own curated toolsets).
+
+The allowlist states runtime-agnostic intent, but the SDK cannot
+enforce tool restrictions on cloud agents yet — and a restriction
+must never silently not apply. A `runtime: "cloud"` agent that sets
+`tools` fails at serve start with an error diagnostic, and a hybrid
+agent's per-send cloud sessions are refused (the turn errors) rather
+than run unrestricted. When the SDK lifts the limitation, the same
+field will simply start applying to cloud turns.
+
+Not a security boundary against the serve host: like `local.sandbox`,
+the allowlist only shapes what the model can call; pair with
+`sandbox: true` when the concern is untrusted input steering the
+model.
+
 ## The `cloud` block
 
 Cloud agent defaults forwarded to the Cursor SDK: `repos` (each

package/docs/reference/cli.md

@@ -141,8 +141,8 @@ agent folder as a positional path, or run it from inside the project:
 
 ```bash
 agent-sdk dev
-agent-sdk dev ./pr-approver
-agent-sdk dev ./pr-approver --port 3000
+agent-sdk dev ./sdk-pr-reviewer
+agent-sdk dev ./sdk-pr-reviewer --port 3000
 ```
 
 `dev` accepts the same flags as [`serve`](#serve). You can use `--dir`

package/docs/reference/tools.md

@@ -82,10 +82,11 @@ export default defineTool({
 `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](../storage.md)), `host.reminders`
-(per-session wakes, when attached), `host.evals` (playground eval
-batches, when attached), and `host.slackNudges` (Slack ask-dedupe
-helpers).
+`host.files` (durable [storage](../storage.md)), `host.otel` (custom
+metrics and session tags; see [OpenTelemetry](../guides/opentelemetry.md)),
+`host.reminders` (per-session wakes, when attached), `host.evals`
+(playground eval batches, when attached), and `host.slackNudges`
+(Slack ask-dedupe helpers).
 
 ### Return values
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -215,7 +215,7 @@
     "node": ">=22.13"
   },
   "dependencies": {
-    "@cursor/sdk": "1.0.26",
+    "@cursor/sdk": "1.0.27",
     "@modelcontextprotocol/sdk": "1.25.1",
     "@octokit/auth-app": "^7.2.0",
     "@octokit/rest": "^21.1.1",

package/skills/otel/SKILL.md

@@ -2,8 +2,8 @@
 name: agentkit-otel
 description: >-
   Wire OpenTelemetry export for an Agent SDK agent (defineOtel, OTLP env,
-  traces/metrics/logs). Use when adding observability, Datadog/Grafana/OTLP
-  export, or session/turn/tool tracing.
+  traces/metrics/logs, ctx.host.otel). Use when adding observability,
+  Datadog/Grafana/OTLP export, session/turn/tool tracing, or custom metrics.
 ---
 
 # Agent SDK OpenTelemetry (`defineOtel`)
@@ -61,6 +61,24 @@ Precedence: `serve({ otel })` over `agent/otel.ts` over env.
 Prompt text, tool payloads, and failure text stay off the wire unless
 those flags are set.
 
+## Custom metrics (`ctx.host.otel`)
+
+Always present. `increment` / `record` no-op without a meter.
+`setAttributes` still tags the open session when a collector is
+attached. Prefix names with team or agent. No custom spans. Reserved
+metric names: `cursor.token.usage`, `cursor.tool.calls`,
+`cursor.cost.usage`, `agent_sdk.session.count`,
+`agent_sdk.turn.count`, `agent_sdk.subagent.count`,
+`agent_sdk.http.duration`. Reserved attributes:
+`cursor.conversation.id`, `agent_sdk.agent`, `agent_sdk.turn_id`,
+`agent_sdk.framework`.
+
+```ts
+ctx.host.otel.setAttributes({ "abc.ticket_id": "INC-123" });
+ctx.host.otel.increment("abc.ticket.resolved");
+ctx.host.otel.record("abc.approval.duration_ms", 1420);
+```
+
 ## Attributes worth joining on
 
 - `cursor.conversation.id` (session id)

package/src/channels/github/github-channel.ts

@@ -137,6 +137,12 @@ const githubPullRequestPayloadSchema: z.ZodType<GitHubPullRequestPayload> =
     }),
     sender: senderSchema,
     installation: installationSchema,
+    label: z
+      .object({
+        name: z.string().min(1),
+      })
+      .nullable()
+      .optional(),
   });
 
 /**
@@ -336,6 +342,9 @@ export function parseGitHubPullRequestEvent(args: {
     ...(payload.pull_request.user?.login === undefined
       ? {}
       : { authorLogin: payload.pull_request.user.login }),
+    ...(payload.label?.name === undefined
+      ? {}
+      : { label: { name: payload.label.name } }),
   };
   return { ctx, pullRequest };
 }

package/src/channels/github/types.ts

@@ -171,6 +171,8 @@ export type GitHubPullRequestPayload = {
     type?: string;
   } | null;
   installation?: { id?: number } | null;
+  /** Present on `labeled` / `unlabeled` pull_request deliveries. */
+  label?: { name: string } | null;
 };
 
 /** Normalized `pull_request` event handed to {@link GitHubPullRequestHook}. */
@@ -188,6 +190,8 @@ export interface GitHubPullRequestEvent {
   /** True when the PR was merged (from the webhook payload). */
   merged: boolean;
   authorLogin?: string;
+  /** Label added/removed on `labeled` / `unlabeled` actions. */
+  label?: { name: string };
 }
 
 /** Normalized `issues` event. */