@cursor/july 0.1.1 → 0.1.2

package/docs/guides/github.md

@@ -18,16 +18,51 @@ The companion skill for coding agents is
 Connect GitHub in Cursor for the repositories you care about (Settings or
 [cursor.com/dashboard](https://cursor.com/dashboard)). That gives your
 account access and lets Cursor receive the repo's webhooks. Sign the host
-in (`agentkit login` or `CURSOR_API_KEY`), define a GitHub
-channel, then serve with `--cursor-events` and at least one `--repo`:
+in (`agentkit login` or `CURSOR_API_KEY`), then opt the channel into the
+Cursor account connection:
+
+```ts
+export default githubChannel({
+  cursorAccount: {
+    repos: ["owner/repo"],
+    // permissions?: "read" | "pr-write" | "contents-write"
+    // default "pr-write" (comments / PR writes, no contents:write)
+  },
+  // hooks...
+});
+```
+
+`cursorAccount` starts the event relay and mints one short-lived GitHub
+credential scoped to those repositories. `ctx.github`, `ctx.host.github`,
+and child `gh` commands share it. Agentkit refreshes the credential before
+expiry. No GitHub App key, PAT, or separate `gh auth login` is needed on
+the host.
+
+Choose `permissions` by what the agent needs:
+
+| `permissions` | Use when |
+| --- | --- |
+| `"read"` | Inspect PRs / issues / statuses only |
+| `"pr-write"` (default) | Comment, review, update PR/issue metadata |
+| `"contents-write"` | Push code (`contents:write`) |
+
+`contents-write` is an explicit opt-up. The host holds a push-capable
+token shared with model-driven tools and untrusted webhook content —
+prefer `"pr-write"` unless the agent must push.
+
+Selected repositories must share one GitHub owner (one App installation).
+Configuration that spans owners fails at startup / mint time.
+
+To keep repository scope in deployment config instead, use
+`cursorAccount: true` and pass it at serve time:
 
 ```bash
 agentkit serve --dir . --cursor-events --repo owner/repo
 ```
 
-Repeat `--repo` for each repository. The stream is read as the host's
-Cursor user. `serve` refuses to start signed out rather than run a relay
-that can never receive events.
+Repeat `--repo` for each repository. The stream and credential are
+resolved as the signed-in Cursor principal. `serve` refuses to start
+signed out.
 
 Offset and consumer id live under `<state-root>/cursor-events/`.
 `CURSOR_API_BASE_URL` overrides the backend. The stream carries event
@@ -51,7 +86,7 @@ import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
 
 export default githubChannel({
   botName: "my-agent", // or GITHUB_APP_SLUG; used to ignore self-comments
-  credentials: { webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET },
+  cursorAccount: { repos: ["owner/repo"] },
   onPullRequest: (ctx, pr) =>
     pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
   onCheckSuite: (ctx, suite) =>
@@ -72,10 +107,10 @@ things:
 
 Return `{ task }` when the wake drives deterministic code. A security
 reviewer can run its whole review loop this way and report
-through commit statuses. Return `{ auth }` when the model needs to reason
+through PR comments. Return `{ auth }` when the model needs to reason
 about the event.
 
-Outbound GitHub API calls prefer App installation tokens when
+Without `cursorAccount`, outbound GitHub API calls prefer App installation tokens when
 `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` are set (with an
 installation id from the event or `GITHUB_APP_INSTALLATION_ID`). On
 serve warmup, App-backed hosts also export a short-lived installation

package/docs/guides/slack.md

@@ -53,7 +53,7 @@ import { slackChannel } from "@cursor/july/channels/slack";
 
 export default slackChannel({
   cursorAccount: true,
-  agentName: "Weatherbot", // defaults to a name derived from the mount slug
+  agentName: "Weatherbot", // single token — no spaces; defaults from mount slug (PascalCase)
   agentIcon: { emoji: ":robot_face:" },
 });
 ```

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,14 +53,14 @@ full guided workflow.
 Start with the built-in scaffold:
 
 ```bash
-agentkit init ./weather-agent
-cd weather-agent
+agentkit init ./pr-approver
+cd pr-approver
 ```
 
 The scaffold creates the files agentkit discovers:
 
 ```text
-weather-agent/
+pr-approver/
 ├── agent/
 │   ├── agent.ts
 │   ├── instructions.md
@@ -85,18 +96,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 +130,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
+# 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 `serve --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/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)