@cursor/july 0.1.1 → 0.1.3

package/docs/quickstart.md

@@ -1,12 +1,18 @@
 ---
-title: "Build your first weather agent"
-description: "Create a weather agent, add a typed tool, run it from the terminal, and open it in the playground."
+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."
 ---
 
-# Build your first weather agent
+# Build your first PR approver
 
-Create an agent, give it a weather tool, run a complete turn, and chat
-with it in the browser.
+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.
+
+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.
 
 ## Prerequisites
 
@@ -23,13 +29,18 @@ agentkit 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.
+
 ## Scaffolding Agents
 
 Have Cursor read [`skills/create-agent/SKILL.md`](../skills/create-agent/SKILL.md)
 and describe what you want:
 
-> Build me a weather agent for the playground. Start with one weather
-> tool and guide me through the remaining decisions.
+> 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.
@@ -42,25 +53,40 @@ full guided workflow.
 Start with the built-in scaffold:
 
 ```bash
-agentkit init ./weather-agent
-cd weather-agent
+agentkit init ./pr-approver
+cd pr-approver
+agentkit dev
 ```
 
-The scaffold creates the files agentkit discovers:
+The scaffold creates the files agentkit discovers, plus empty capability
+folders (each with a `.gitkeep`) so you can drop tools, channels, and
+evals in place:
 
 ```text
-weather-agent/
+pr-approver/
 ├── agent/
 │   ├── agent.ts
 │   ├── instructions.md
-│   └── tools/
-│       └── echo.ts
-└── package.json
+│   ├── tools/
+│   │   └── echo.ts
+│   ├── skills/
+│   ├── mcp-connections/
+│   ├── subagents/
+│   ├── channels/
+│   ├── hooks/
+│   ├── 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. Each file under `agent/tools/` becomes a
-tool.
+tool. `tsconfig.json` type-checks the project (`npm run check`); the
+framework runs your TypeScript directly, so nothing compiles.
 
 Check the project before you run it:
 
@@ -85,18 +111,32 @@ reply. It prints a JSON trajectory with the response, tool calls, and
 token usage. It also writes an NDJSON trace under
 `.agentkit/traces/`.
 
-## Add weather instructions
+## Teach it to review
 
 Replace `agent/instructions.md`:
 
 ```md
-# Weather agent
-
-You are a concise weather assistant.
-
-- Use `get_weather` before answering questions about current weather.
-- Tell the user the weather data is simulated.
-- Keep replies to two sentences or fewer.
+# PR approver
+
+You review GitHub pull requests. Be specific and brief.
+
+For every pull request:
+
+1. Call `inspect_pr` first. Never judge a change you haven't fetched.
+2. Match your review to the complexity it reports:
+   - `trivial`: read the patches. If the diff does what the title says
+     and nothing looks risky, call `submit_review` with verdict
+     `approve`.
+   - `moderate`: read every patch. Approve only when you understand the
+     whole change and see no risk. Otherwise ask for a human review and
+     say which files worry you.
+   - `large`: call `submit_review` with verdict `request_human_review`
+     right away. Use the stats you already have to point the reviewer at
+     the biggest files; don't dig further.
+3. Never approve a draft. Point out anything surprising, even when you
+   approve.
+
+End with one sentence: the verdict and why.
 ```
 
 Remove the demo echo tool:
@@ -105,79 +145,332 @@ Remove the demo echo tool:
 rm agent/tools/echo.ts
 ```
 
-## Add a weather tool
+## 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
+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/get_weather.ts`:
+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";
+
+/** Deterministic policy: the tool rates the change, not the model. */
+function rateComplexity(linesChanged: number, changedFiles: number): Complexity {
+  if (linesChanged <= 25 && changedFiles <= 2) {
+    return "trivial";
+  }
+  if (linesChanged <= 400 && changedFiles <= 15) {
+    return "moderate";
+  }
+  return "large";
+}
+
+/** Keep one oversized file from flooding the model's context. */
+function trimPatch(patch: string | undefined): string | undefined {
+  if (patch === undefined || patch.length <= 3000) {
+    return patch;
+  }
+  return `${patch.slice(0, 3000)}\n[... patch trimmed ...]`;
+}
 
 export default defineTool({
-  description: "Get simulated current weather for a city.",
+  description:
+    "Fetch a pull request's title, stats, and per-file patches, plus a deterministic complexity rating (trivial, moderate, or large). Call this before any review decision.",
   inputSchema: z.object({
-    city: z.string().describe("City name, such as San Francisco"),
+    prUrl: z
+      .string()
+      .describe("Pull request URL: https://github.com/owner/repo/pull/123"),
   }),
-  async execute({ city }) {
-    const temperatureF = Math.round(Math.random() * (90 - 32) + 32);
-
+  async execute({ prUrl }, ctx) {
+    const { owner, repo, number } = parsePullUrl(prUrl);
+    const octokit = await ctx.host.github.getOctokit();
+    const { data: pr } = await octokit.rest.pulls.get({
+      owner,
+      repo,
+      pull_number: number,
+    });
+    const { data: files } = await octokit.rest.pulls.listFiles({
+      owner,
+      repo,
+      pull_number: number,
+      per_page: 100,
+    });
+
+    const complexity = rateComplexity(
+      pr.additions + pr.deletions,
+      pr.changed_files
+    );
     return {
-      city,
-      temperatureF,
-      conditions: "sunny",
+      title: pr.title,
+      author: pr.user?.login,
+      state: pr.state,
+      draft: pr.draft ?? false,
+      additions: pr.additions,
+      deletions: pr.deletions,
+      changedFiles: pr.changed_files,
+      complexity,
+      files: files.map((file) => ({
+        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) }),
+      })),
     };
   },
 });
 ```
 
-The file adds one tool named `get_weather`:
+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.
 
-This version uses simulated data so you can run it without another API
-key. Replace `execute` with a weather API when you're ready.
+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 weather tool
+## Try the inspect tool
 
-Call the tool directly first:
+Call the tool directly first, on a real merged pull request:
 
 ```bash
-agentkit call get_weather --dir . \
-  --input '{"city":"San Francisco"}'
+agentkit call inspect_pr --dir . \
+  --input '{"prUrl":"https://github.com/react/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 ..." }]
+}
+```
+
+Now call it on the PR that added `experimental_useEvent` to React:
+1,027 additions across 26 files.
+
+```bash
+agentkit call inspect_pr --dir . \
+  --input '{"prUrl":"https://github.com/react/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.
+
+## Add the review tool
+
+The approver needs a way to act on its verdict. Create
+`agent/tools/submit_review.ts`:
+
+```ts
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+import { parsePullUrl } from "../lib/github.js";
+
+export default defineTool({
+  description:
+    "Post the review decision to GitHub: approve the pull request, or comment asking for a human review.",
+  inputSchema: z.object({
+    prUrl: z
+      .string()
+      .describe("Pull request URL: https://github.com/owner/repo/pull/123"),
+    verdict: z.enum(["approve", "request_human_review"]),
+    summary: z
+      .string()
+      .describe("One or two sentences explaining the verdict."),
+  }),
+  async execute({ prUrl, verdict, summary }, ctx) {
+    const { owner, repo, number } = parsePullUrl(prUrl);
+    const review =
+      verdict === "approve"
+        ? { event: "APPROVE" as const, body: `PR approver: ${summary}` }
+        : {
+            event: "COMMENT" as const,
+            body: `PR approver: this change needs a human review. ${summary}`,
+          };
+
+    const octokit = await ctx.host.github.getOctokit();
+    await octokit.rest.pulls.createReview({
+      owner,
+      repo,
+      pull_number: number,
+      event: review.event,
+      body: review.body,
+    });
+    return { posted: true, ...review };
+  },
+});
 ```
 
-`call` validates the input and runs `execute` without a model turn. If
-the result looks right, ask the agent:
+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.
+
+## 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.
 
 ```bash
 agentkit run --dir . \
-  --message "What's the weather in San Francisco?"
+  --message "Review https://github.com/acme/checkout/pull/42"
 ```
 
-The agent calls `get_weather`, receives the result, and uses it in the
-final reply. agentkit runs the tool loop for you.
+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 playground
+Open the PR on GitHub: the review is on the timeline, posted by
+whatever identity your credential belongs to.
+
+## Wake it from GitHub
 
-Start the development server:
+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`:
+
+```ts
+import {
+  defaultGitHubAuth,
+  githubChannel,
+} from "@cursor/july/channels/github";
+
+const REVIEW_ACTIONS = new Set(["opened", "reopened", "ready_for_review"]);
+
+export default githubChannel({
+  botName: "pr-approver",
+  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) => {
+    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.`,
+      ],
+    };
+  },
+});
+```
+
+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:
 
 ```bash
-agentkit serve --dir . --dev
+agentkit dev
+# second terminal:
+agentkit github replay https://github.com/acme/checkout/pull/42 \
+  --dir . --action opened
 ```
 
-Open the playground URL printed in the terminal. Ask the same weather
-question. The playground streams the reply and shows the tool arguments
-and result inline.
+The replay prints the delivery, and the serve terminal shows the wake:
+
+```text
+[agentkit] replaying acme/checkout#42 (pull_request) → 1 channel
+[agentkit]   pull_request.opened → pr-approver/github 200
+```
+
+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.
+
+## Open the playground
+
+Keep `agentkit 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.
+
+## Go live
+
+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
+`agentkit 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.
 
 ## Where to go next
 
-- [Tools](./reference/tools.md): add more typed capabilities, like
-  replacing the simulated weather tool with live Open-Meteo data
-- [Evals](./evals.md): turn this weather question into a regression
-  check
-- [Channels](./reference/channels.md): expose the agent through HTTP,
-  Slack, or another webhook
+- [`examples/approval-buddy`](../examples/approval-buddy/): the
+  production-shaped sibling, 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
+  direct calls
+- [GitHub](./guides/github.md): fixtures, forwarding, and pulling
+  events from Cursor
 - [Building agents with agents](./building-with-agents.md): have a
   coding agent extend the project for you

package/docs/reference/cli.md

@@ -12,7 +12,9 @@ required argument is missing.
 | Command                                                 | Description                                           |
 | ------------------------------------------------------- | ----------------------------------------------------- |
 | [`serve`](#serve)                                       | Serve agents over HTTP (multi-agent by default)       |
+| [`dev`](#dev)                                           | Local development: same as `serve --dev`              |
 | [`chat`](#chat)                                         | Talk to a running server from the terminal            |
+| [`resume`](#resume)                                     | Reattach chat to an existing session id               |
 | [`run`](#run)                                           | One-shot turn on an ephemeral server; JSON trajectory |
 | [`call`](#call)                                         | Call a server tool directly, no model turn            |
 | [`eval`](#eval)                                         | Run filesystem evals                                  |
@@ -62,6 +64,23 @@ agent code.
 | `--no-docs`         | Skip the documentation site at `/docs` (and its auto-build).                                                                                                                                                                               |
 | `--cursor-events`   | Pull SCM webhook events from Cursor's `/v0/scm-events` instead of receiving webhooks. Requires a signed-in host and `--repo` (repeatable). Offset state lives under `<state-root>/cursor-events/`.                                         |
 
+## dev
+
+`dev` is the local-development shortcut for `serve --dev`. Pass the
+agent folder as a positional path, or run it from inside the project:
+
+```bash
+agentkit dev
+agentkit dev ./pr-approver
+agentkit dev ./pr-approver --port 3000
+```
+
+Same flags as [`serve`](#serve) (`--dir` still works if you prefer it).
+Dev mode is always on: schedules and reminders wait for manual dispatch,
+GitHub accepts unsigned loopback deliveries, and Vite HMR starts when
+the toolchain is present. Prefer this over `serve --dev` while
+iterating.
+
 ## chat
 
 `chat` talks to a running server from the terminal.
@@ -78,6 +97,21 @@ Streams the reply live: text, tool calls, and a per-turn usage footer.
 `{ ok, sessionId, continuationToken, trajectory }`. `--text` prints a
 compact dump, and `--no-color` forces plain output.
 
+## resume
+
+`resume` reattaches the chat REPL to an existing session.
+
+```bash
+agentkit resume ses_… --url http://127.0.0.1:3000/<slug>
+agentkit resume ses_… --prod --team 1 --slug approval-buddy
+agentkit resume ses_… --prod --message "continue from here"
+```
+
+Same as `chat --session <id>`: looks up the continuation token via
+`/v1/sessions` when `--continuation-token` is omitted, replays the
+transcript, then accepts follow-ups. Accepts the same output flags as
+[`chat`](#chat) (`--json`, `--text`, `--no-color`).
+
 ## run
 
 `run` executes one turn on an ephemeral server and prints a JSON trajectory.
@@ -156,11 +190,25 @@ prints.
 `init` scaffolds a new project.
 
 ```bash
-agentkit init ./my-agent   # scaffold package.json + agent/ + a demo tool
-agentkit init              # no directory: print the setup guide
+agentkit init ./my-agent          # scaffold package.json, tsconfig.json, agent/ + a demo tool
+agentkit init ./my-agent --json   # machine-readable summary for tooling
+agentkit init                     # no directory: print the setup guide
 ```
 
-Refuses to overwrite existing files.
+The scaffold summary lists each file as `create` or `exist` (existing
+files are left alone) and the project folder path, then runs
+`npm install` so `@cursor/july` resolves for `dev` / `run`. On a TTY,
+on a TTY, `init` asks before installing (or updating) the package
+coding-agent skills into `~/.cursor/skills/agentkit/`, always overwriting
+with the version from the installed package (skipped for `--json` /
+non-interactive hosts). When the host has no Cursor credential yet,
+`init` runs `agentkit login` and waits for the browser sign-in to
+finish, then prints next steps: `cd` into the project (when needed),
+`agentkit login` (when still unsigned), and `agentkit dev`. `--json`
+still installs dependencies but never blocks on login or skill install;
+it prints
+`{ ok, directory, created, skipped, installed, installError, next }`
+(with `login` in `next` when unsigned).
 
 ## info
 

package/docs/reference/instructions.md

@@ -43,16 +43,18 @@ covers controlling that.
 ## Best Practices
 
 Keep them a few lines: identity, when to use which tool, output shape.
-The [quickstart weather agent](../quickstart.md) is the pattern:
+The [quickstart PR approver](../quickstart.md) is the pattern:
 
 ```md
-# Weather agent
+# PR approver
 
-You are a concise weather assistant.
+You review GitHub pull requests. Be specific and brief.
 
-- Use `get_weather` before answering questions about current weather.
-- Tell the user the weather data is simulated.
-- Keep replies to two sentences or fewer.
+1. Call `inspect_pr` first. Never judge a change you haven't fetched.
+2. Match your review to the complexity it reports.
+3. Never approve a draft.
+
+End with one sentence: the verdict and why.
 ```
 
 - Name the tools and the decision rule ("use X before answering about

package/docs/scaffolding-agents.md

@@ -106,7 +106,7 @@ inputs again, and adds an eval for each improvement you keep.
 
 ## Related
 
-- [Build your first weather agent](./quickstart.md)
+- [Build your first PR approver](./quickstart.md)
 - [Building agents with agents](./building-with-agents.md)
 - [Evals](./evals.md)
 - [Hillclimbing](./hillclimbing.md)