@cursor/july 0.1.109 → 0.1.112

package/docs/hillclimbing.md

@@ -1,93 +1,139 @@
 ---
 title: "Hillclimbing"
-description: "Improve an agent one measured round at a time, with the hillclimb skill running the loop with you."
+description: "Improve one agent behavior at a time by measuring fixed inputs, changing one lever, and locking each win with an eval."
 ---
 
 # Hillclimbing
 
-Make an agent better on fixed inputs: measure, change one lever, remeasure, and lock every kept win with an eval.
+Hillclimbing improves an agent through controlled before-and-after
+comparisons. Keep the inputs fixed, name one failure, change one lever,
+and retain the change only when the same run gets better without
+crossing the freeze line.
 
-## What is hillclimbing?
+The companion [`hillclimb` skill](../skills/hillclimb/SKILL.md) can run
+this loop with you.
 
-Hillclimbing is a measured improvement loop. You pin a few fixtures, name the one dominant problem in the run, change one lever, and check the same fixtures again. Keep only what helps. Every kept change lands an [eval](./evals.md) so the win stays put.
+## Correct a wrong tool choice
 
-You don't have to run the loop alone. The package ships a coding-agent skill that drives it with you.
+Suppose a PR reviewer calls `approve_pr` before `inspect_pr`. Pin one PR
+fixture, record the original tool order, then tighten the instruction
+that owns the decision. The improved run should inspect first and leave
+approval untouched.
 
-```mermaid
-flowchart LR
-  measure[Measure] --> change[Change one lever]
-  change --> remeasure[Remeasure]
-  remeasure --> measure
+```bash
+agent-sdk run --dir . \
+  --message "Is https://github.com/acme/checkout/pull/42 ready?"
 ```
 
-## How do I hillclimb an agent with a coding agent?
+Lock the result with the intended and tempting-wrong paths:
 
-Have Cursor read [`skills/hillclimb/SKILL.md`](./skills/hillclimb.md).
+```ts
+t.succeeded();
+t.calledTool("inspect_pr");
+t.notCalledTool("approve_pr");
+```
+
+Do not change the tool implementation, prompt, and evidence together.
+If tool choice improves, you should know which edit caused it.
 
-Tell it:
+## Reduce wandering or latency
 
-1. **Which agent** you're improving (path or slug)
-2. **One to three fixtures** you'll reuse every round: a PR URL, a saved webhook body, or a canonical chat prompt
-3. **What "better" means** this round: correct tool choice, fewer tools, lower latency, or output quality. Name the freeze line too: API shape, public output, and existing evals that must stay green
+A slow run often repeats reads, searches broad directories, or asks the
+model to discover evidence the host already has. Compare the trajectory
+by tool name and wall time, then move deterministic preparation ahead
+of the turn or trim the evidence shape.
 
-The skill serves the agent, hits your fixtures, reads the session trajectory, proposes one change, remeasures, and checks with you before the next round.
+```text
+before: 14 tool calls, 92 seconds, 6 repeated reads
+after:   5 tool calls, 31 seconds, 0 repeated reads
+```
 
-Other skills cover the edges:
+Keep the change only if the answer still finds the same known issue.
+Efficiency without a quality check can make an agent fast by making it
+incomplete.
 
-| When you need… | Skill |
-| --- | --- |
-| The measured improvement loop | [`skills/hillclimb/SKILL.md`](./skills/hillclimb.md) |
-| An eval that locks a kept win | [`skills/evals/SKILL.md`](./skills/evals.md) |
-| Repeatable GitHub webhook inputs | [`skills/github/SKILL.md`](./skills/github.md) |
-| A run that misbehaves | [`skills/debug/SKILL.md`](./skills/debug.md) |
+## Improve quality without changing the contract
 
-See [Building agents with agents](./building-with-agents.md) for every framework skill and a good first prompt.
+For answer quality, freeze the public shape before editing: required
+sections, API fields, side effects, and existing evals. Compare both
+runs against a known-good answer or a small set of gold findings, then
+change the instructions or skill that owns the missing judgment.
+
+```text
+fixture: saved checkout PR diff
+success: report both gold findings with file paths
+freeze:  findings JSON shape; no review post; existing smoke evals
+```
 
-## What do I need before a hillclimb round?
+A wording change is not a win by itself. Keep it when correctness rises
+and every frozen behavior remains intact.
 
-Agree on four things before you edit:
+## Run one measured round
 
-1. **The target agent**: the project you're improving
-2. **Fixtures**: one to three fixed inputs you can compare across runs
-3. **Success criteria**: what better means this round
-4. **The freeze line**: what must not change
+Agree on four inputs before editing:
 
-Pin the input first. A moving fixture is noise. For GitHub agents, use `agent-sdk github replay` (see the [GitHub guide](./guides/github.md)). For a single tool without a model turn, use `agent-sdk call`. For a chat turn, use `agent-sdk run --dir . --message "…"`.
+1. **Target:** the agent path or slug.
+2. **Fixtures:** one to three prompts, saved payloads, or pinned PRs.
+3. **Success:** the metric or decision that should improve.
+4. **Freeze line:** behavior that must not move.
 
-## How do I run one hillclimb round?
+Then run one loop:
 
-**Measure.** Hit the agent the way a user would: playground, channel HTTP, or Slack in `--dev`. Or ask the hillclimb skill to do it. `agent-sdk run` returns a JSON trajectory and writes a trace under the project state directory.
+1. Exercise the agent through the same surface a user would.
+2. Read the trajectory and name the dominant failure in one sentence.
+3. Change one lever.
+4. Rerun the same fixtures.
+5. Compare correctness, efficiency, and contract fit.
+6. Keep, revert, or narrow the change.
 
-**Reflect.** Score the trajectory, not impressions. Was the answer right? Did the model thrash (too many tools, fat evidence, grep loops)? Did it invent work the host should have prepared? Name the single dominant problem for this round in one sentence. Example: "Full-file dumps trigger grep loops."
+Do not replace a fixture mid-round. A moving input makes the comparison
+meaningless.
 
-**Change one lever.** Prefer the smallest change that addresses that problem:
+## Choose the smallest lever
 
-1. Host prep: seed what the model needs so it doesn't hunt
-2. Evidence shape: trim or reorder artifacts
-3. Instructions and skills: tighten the procedure
-4. Tool surface: remove or gate tools that invite wandering
-5. Framework changes: only when the agent can't express the fix
+Start with the earliest place that can remove the failure:
 
-**Remeasure.** Same fixtures. Diff tools, wall time, and quality side by side. Keep the change only if the target metric improves and the freeze line holds.
+1. **Host preparation:** fetch deterministic evidence before the turn.
+2. **Evidence shape:** trim, order, or label what the model receives.
+3. **Instructions or skills:** clarify the decision procedure.
+4. **Tool surface:** remove or gate tools that invite wandering.
+5. **Framework:** change it only when the agent cannot express the fix.
 
-## How do I lock a hillclimb improvement with an eval?
+Changing the host or evidence often improves both quality and latency
+because the model spends less time searching for ground truth.
+
+## Lock every kept win
+
+Each retained change needs an eval that would have failed before it. Use
+a tool-choice assertion, `maxToolCalls` bound, output-shape check, or
+quality score that captures the measured improvement.
+
+```bash
+agent-sdk eval --dir . --tag smoke
+```
 
-Every kept change needs an eval that would have failed before the change: a tool-choice gate, a `maxToolCalls` bound, or an output-shape check. Run `agent-sdk eval --dir . --json` between rounds. Never weaken an existing gate to pass the round.
+Never weaken an existing gate to make the round pass. The eval is the
+record that the improvement survived after the fixture and source
+change leave your working memory.
 
-Details live in [Keep improvements with regression evals](./evals.md#keep-improvements-with-regression-evals). The evals skill will author the case with you.
+## Run the loop with a coding agent
 
-## What habits help hillclimbing stay reliable?
+Ask the coding agent to read
+[`skills/hillclimb/SKILL.md`](../skills/hillclimb/SKILL.md), then give
+it the target, fixtures, success criterion, and freeze line. It will
+measure the current run, propose one change, remeasure, and ask before
+starting another round.
 
-- One problem per round. Don't bundle "trim evidence and rewrite instructions" unless you chose that on purpose.
-- Keep fixtures fixed until you deliberately need a harder case.
-- Separate host work from model tools when you blame latency. Moving deterministic prep onto the host is often the biggest win. In one PR reviewer, host-prepared evidence cut turns from about 8 minutes to about 1 minute.
-- Spot-check quality on at least one fixture against a known-good answer. Efficiency-only climbs quietly drop findings.
-- Treat `turn.failed` with `"turn interrupted"` as expected when a follow-up or stop preempted the turn.
-- Don't deploy, post to real surfaces, or weaken evals as part of a climb.
+Use saved or local surfaces during a climb. Do not deploy or post to a
+real external channel unless that side effect is part of an explicitly
+approved fixture.
 
 ## Related
 
-- [Evals](./evals.md)
-- [Building agents with agents](./building-with-agents.md)
-- [GitHub guide](./guides/github.md)
-- [Fix common agent problems](./troubleshooting.md)
+- [Evals](./evals.md): author the regression check for a kept win
+- [Evals reference](./reference/evals.md): trajectory assertions and
+  scores
+- [Building agents with agents](./building-with-agents.md): delegate
+  creation and verification to a coding agent
+- [Fix common agent problems](./troubleshooting.md): diagnose a run
+  that is broken instead of underperforming

package/docs/quickstart.md

@@ -1,45 +1,36 @@
 ---
-title: "Build your first PR reviewer"
+title: "Build a PR reviewer"
 description: "Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events."
 ---
 
-# Build your first PR reviewer
+# Build a PR reviewer
 
 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.
+review.
 
-## 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.md).
-- **Get started in the CLI:** continue below.
+- Node 22.13 or newer.
+- agent-sdk cli
 
-## Prerequisites
+```
+npm install -g @cursor/agent-sdk
+```
 
-- Node 22.13 or newer. Bun isn't supported.
-- 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) if `agent-sdk` is not on `PATH`.
 - A Cursor credential for model turns. Sign in once:
 
 ```bash
 agent-sdk login
 ```
 
-You can also set `CURSOR_API_KEY` instead of signing in.
-
-- Authenticate with `gh auth login` or `GITHUB_TOKEN`. You can read
-  public pull requests. Posting reviews requires repository write access.
-
 ## Create and run the project
 
 Initialize the project and start the development server:
 
 ```bash
-npx @cursor/july init ./sdk-pr-reviewer
-cd sdk-pr-reviewer
+npx @cursor/agent-sdk init ./pr-reviewer
+cd pr-reviewer
 agent-sdk dev
 ```
 
@@ -79,35 +70,6 @@ For every pull request:
 End with one sentence: the verdict and why.
 ```
 
-Remove the demo echo tool:
-
-```bash
-rm agent/tools/echo.ts
-```
-
-## Add a shared helper
-
-Create `agent/lib/github.ts`:
-
-```ts
-export interface PullRef {
-  owner: string;
-  repo: string;
-  number: number;
-}
-
-/** Split https://github.com/owner/repo/pull/123 into its parts. */
-export function parsePullUrl(prUrl: string): PullRef {
-  const url = new URL(prUrl);
-  const [owner, repo, pulls, number] = url.pathname.split("/").filter(Boolean);
-  const parsed = Number.parseInt(number ?? "", 10);
-  if (pulls !== "pull" || owner === undefined || Number.isNaN(parsed)) {
-    throw new Error(`Not a pull request URL: ${prUrl}`);
-  }
-  return { owner, repo, number: parsed };
-}
-```
-
 ## Add the inspect tool
 
 Create `agent/tools/inspect_pr.ts`:
@@ -115,18 +77,18 @@ Create `agent/tools/inspect_pr.ts`:
 ```ts
 import { defineTool } from "@cursor/july/tools";
 import { z } from "zod";
-import { parsePullUrl } from "../lib/github.js";
 
 export type Complexity = "trivial" | "moderate" | "large";
 
-/** Rate complexity from fixed line and file-count thresholds. */
 function rateComplexity(linesChanged: number, changedFiles: number): Complexity {
   if (linesChanged <= 25 && changedFiles <= 2) {
     return "trivial";
   }
+
   if (linesChanged <= 400 && changedFiles <= 15) {
     return "moderate";
   }
+
   return "large";
 }
 
@@ -135,6 +97,7 @@ function trimPatch(patch: string | undefined): string | undefined {
   if (patch === undefined || patch.length <= 3000) {
     return patch;
   }
+
   return `${patch.slice(0, 3000)}\n[... patch trimmed ...]`;
 }
 
@@ -147,17 +110,24 @@ export default defineTool({
       .describe("Pull request URL: https://github.com/owner/repo/pull/123"),
   }),
   async execute({ prUrl }, ctx) {
-    const { owner, repo, number } = parsePullUrl(prUrl);
+    const url = new URL(prUrl);
+    const [owner, repo, pulls, number] = url.pathname.split("/").filter(Boolean);
+    const pull_number = Number.parseInt(number ?? "", 10);
+    if (pulls !== "pull" || owner === undefined || Number.isNaN(pull_number)) {
+      throw new Error(`Not a pull request URL: ${prUrl}`);
+    }
+
     const octokit = await ctx.host.github.getOctokit();
     const { data: pr } = await octokit.rest.pulls.get({
       owner,
       repo,
-      pull_number: number,
+      pull_number,
     });
+
     const { data: files } = await octokit.rest.pulls.listFiles({
       owner,
       repo,
-      pull_number: number,
+      pull_number,
       per_page: 100,
     });
 
@@ -165,6 +135,7 @@ export default defineTool({
       pr.additions + pr.deletions,
       pr.changed_files
     );
+
     return {
       title: pr.title,
       author: pr.user?.login,
@@ -178,7 +149,6 @@ export default defineTool({
         path: file.filename,
         additions: file.additions,
         deletions: file.deletions,
-        // Large changes get a stats-only skim; a human reads the code.
         ...(complexity === "large" ? {} : { patch: trimPatch(file.patch) }),
       })),
     };
@@ -214,7 +184,6 @@ Create `agent/tools/submit_review.ts` to post each verdict:
 ```ts
 import { defineTool } from "@cursor/july/tools";
 import { z } from "zod";
-import { parsePullUrl } from "../lib/github.js";
 
 export default defineTool({
   description:
@@ -229,7 +198,13 @@ export default defineTool({
       .describe("One or two sentences explaining the verdict."),
   }),
   async execute({ prUrl, verdict, summary }, ctx) {
-    const { owner, repo, number } = parsePullUrl(prUrl);
+    const url = new URL(prUrl);
+    const [owner, repo, pulls, number] = url.pathname.split("/").filter(Boolean);
+    const pull_number = Number.parseInt(number ?? "", 10);
+    if (pulls !== "pull" || owner === undefined || Number.isNaN(pull_number)) {
+      throw new Error(`Not a pull request URL: ${prUrl}`);
+    }
+
     const review =
       verdict === "approve"
         ? { event: "APPROVE" as const, body: `PR reviewer: ${summary}` }
@@ -242,7 +217,7 @@ export default defineTool({
     await octokit.rest.pulls.createReview({
       owner,
       repo,
-      pull_number: number,
+      pull_number,
       event: review.event,
       body: review.body,
     });
@@ -280,20 +255,16 @@ const REVIEW_ACTIONS = new Set(["opened", "reopened", "ready_for_review"]);
 
 export default githubChannel({
   botName: "sdk-pr-reviewer",
-  webhookEvents: ["pull_request"],
-  deliverReplies: false,
-  progress: { reactions: false },
+  cursorAccount: { repos: ["acme/checkout"] },
   onPullRequest: (ctx, pr) => {
     if (!REVIEW_ACTIONS.has(pr.action) || pr.draft) {
       return null;
     }
+
     return {
       auth: defaultGitHubAuth(ctx),
       title: `Review ${ctx.repository.fullName}#${pr.number}`,
-      context: [
-        "",
-        `Review ${pr.url}. Inspect it first, then submit your verdict with submit_review.`,
-      ],
+      context: `Review ${pr.url}. Inspect it first, then submit your verdict with submit_review.`,
     };
   },
 });
@@ -313,56 +284,24 @@ trigger, both tool calls, and the verdict.
 ## Run options
 
 1. **CLI message**
-
-   ```bash
+  ```bash
    agent-sdk run --dir . --message "Review https://github.com/acme/checkout/pull/42"
-   ```
-
+  ```
 2. **Local replay**
-
-   ```bash
+  ```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 .
-   ```
-
-   Keep the local `dev` or `serve` process running.
-
-4. **Hosted deployment**
-
-   Deploy once, set the GitHub App secrets, then redeploy:
-
-   ```bash
-   agent-sdk deploy
-   agent-sdk secrets set sdk-pr-reviewer GITHUB_APP_ID GITHUB_APP_PRIVATE_KEY
-   agent-sdk deploy
-   ```
-
-See [GitHub](./guides/github.md) for local event delivery and
-[Deployment](./deployment.md) for hosting.
+  ```
 
 ## Where to go next
 
 - [PR autofixer template](./templates/pr-autofixer.md): drive a PR on a
-  Cursor cloud VM
+Cursor cloud VM
 - [Evals](./evals.md): freeze these two PRs as regression checks so
-  prompt changes can't flip a verdict
+prompt changes can't flip a verdict
 - [Tools](./reference/tools.md): more on typed tools, approvals, and
-  direct calls
+direct calls
 - [GitHub](./guides/github.md): fixtures, forwarding, and pulling
-  events from Cursor
+events from Cursor
 - [Building agents with agents](./building-with-agents.md): have a
-  coding agent extend the project for you
+coding agent extend the project for you

package/docs/reference/channels.md

@@ -19,22 +19,6 @@ session create, follow-up, stream, stop, the sessions list, approvals,
 deterministic tool calls, health, and info. For the route-by-route
 contract, see the [HTTP API reference](./http-api.md).
 
-Author `agent/channels/http.ts` only to override its defaults:
-
-```ts
-import {
-  bearerAuth,
-  httpChannel,
-  localDevStrict,
-} from "@cursor/july/channels";
-
-export default httpChannel({
-  auth: [localDevStrict(), bearerAuth(process.env.AGENT_TOKEN ?? "")],
-  onMessage: (message, { auth }) =>
-    `[caller ${auth?.principalId ?? "anonymous"}] ${message}`,
-});
-```
-
 ## Define a custom channel
 
 Author `agent/channels/<id>.ts`. The filename is the channel id and the

package/docs/reference/cli.md

@@ -42,7 +42,6 @@ also provide `agent-sdk slack help` and `agent-sdk github help`.
 | [`stop`](#stop)                                         | Stop a hosted deployment                                       |
 | [`delete`](#delete)                                     | Delete a hosted deployment                                     |
 | [`rotate-token`](#rotate-token)                         | Replace a deployment's alias token                             |
-| [`rotate-pod-credential`](#rotate-pod-credential)       | Replace a deployment's pod credential                          |
 | [`secrets`](#secrets)                                   | Manage deployment secrets                                      |
 | [`mcp`](#mcp)                                           | Proxy the agent's MCP endpoint over stdio; `mcp install` writes `~/.cursor/mcp.json` |
 | [`mcp oauth`](#mcp-oauth)                               | Authorize host MCP OAuth; optional `--store` to deployment secrets |
@@ -420,6 +419,8 @@ agent-sdk init ./grokbot --template grokbot-agents    # talk to Grok Bot agents
 agent-sdk init ./code-wiki --template code-wiki       # keep wiki pages current after merge
 agent-sdk init ./agents-md --template agents-md       # keep AGENTS.md current from last week's PRs and Slack
 agent-sdk init ./my-reviewer --template security-reviewer   # review PRs for security bugs
+agent-sdk init ./thermo-review --template thermo-review       # review PRs for bugs and breakage
+agent-sdk init ./thermo-quality --template thermo-quality-review # review PRs for code quality
 agent-sdk init ./security-help --template security-help   # answer security questions in Slack
 agent-sdk init ./my-triage --template triage-linear   # comment on Linear issues
 agent-sdk init ./my-triage --template triage-jira     # comment on Jira issues
@@ -704,21 +705,6 @@ agent-sdk rotate-token <slug> [--team <id>] [--json]
 The old token stops working immediately. The replacement is shown once.
 `--json` prints `{ aliasToken }`.
 
-## rotate-pod-credential
-
-`rotate-pod-credential` replaces the credential used by the running
-engine pod.
-
-```bash
-agent-sdk rotate-pod-credential <slug> [--team <id>] [--json]
-```
-
-The command prints only the masked key (`--json` prints
-`{ podCredentialMaskedKey }`). The running pod keeps the old credential
-until the next deploy, so nothing breaks in between. Run
-`agent-sdk deploy --slug <slug>` to inject the replacement and retire
-the old credential.
-
 ## mcp
 
 `mcp` proxies an agent's MCP endpoint over stdio for MCP clients that

package/docs/reference/connections.md

@@ -54,7 +54,7 @@ agent-sdk mcp oauth inventory --store   # also upsert deployment secrets
 ```
 
 Full walkthrough: [Host MCP OAuth](../guides/mcp-oauth.md). Companion
-skill: [`skills/mcp-auth/SKILL.md`](../skills/mcp-auth.md).
+skill: [`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md).
 
 Account MCP (`cursorAccount: true`) is the right choice for connectors
 already linked in the Cursor dashboard. Omit `servers` (or pass `"*"`)
@@ -255,9 +255,8 @@ export default defineConnection({
 });
 ```
 
-Unknown slugs and self-references fail `serve` at startup. Resolution
-(loopback versus `--public-url`), loop caveats, and the delegation model
-are in the [Agent-to-agent guide](../guides/agent-to-agent.md).
+Unknown slugs and self-references fail `serve` at startup. Walkthrough:
+[Agent-to-agent](../guides/agent-to-agent.md#how-do-i-wire-two-agents).
 
 ## Every model-visible MCP connection is available in three places
 
@@ -302,6 +301,5 @@ lazily on first use.
 Continue with these pages:
 
 - [Host MCP OAuth](../guides/mcp-oauth.md): `mcp oauth`, Connect, `--store`
-- [Agent-to-agent](../guides/agent-to-agent.md): peers in depth
 - [Tools](./tools.md): authored tools that wrap MCP connections
 - [Webhooks](../guides/webhooks.md): calling MCP connections from handlers