@cursor/july 0.1.111 → 0.1.113

package/docs/guides/github.md

@@ -1,316 +1,331 @@
 ---
 title: "GitHub"
-description: "Wake your agent from pull requests, CI, and comments by pulling Cursor SCM events, with fixtures and replay for local tests."
+description: "Let your agent read pull requests and CI, then write back reviews, comments, and checks."
 ---
 
 # GitHub agents
 
-Wake your agent from repository events without exposing a public webhook
-URL. Prefer `serve --cursor-events`: the host long-polls Cursor's SCM
-event stream for repos you've connected to Cursor. You still declare a
-`githubChannel` so hooks decide what each event does.
+GitHub agents work both directions. They wake from repo events, read the
+latest PR and CI state, then write back reviews, comments, checks, or
+pushes. Pull events from Cursor, so you don't expose a public webhook
+URL.
 
-The companion skill for coding agents is
-[`skills/github/SKILL.md`](../../skills/github/SKILL.md).
+Connect GitHub in Cursor for the repos you care about (Settings or
+[cursor.com/dashboard](https://cursor.com/dashboard)). Sign the host in
+with `agent-sdk login`. `cursorAccount` reuses that connection for
+events and API calls. You don't set up a GitHub App or a PAT.
 
-## Pull events from Cursor
+Start from a template when one fits:
+[security reviewer](../templates/security-reviewer.md),
+[PR autofixer](../templates/pr-autofixer.md), or
+[issue triager](../templates/triage.md).
 
-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 (`agent-sdk login`, `CURSOR_API_KEY`, or
-`CURSOR_SERVICE_ACCOUNT_KEY`), then opt the channel into the
-Cursor account connection:
+## Review a pull request
+
+Wake when a PR is ready for review. Fetch the latest diff in a tool,
+then post a verdict.
 
 ```ts
+// agent/channels/github.ts
+import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
+
 export default githubChannel({
-  cursorAccount: {
-    repos: ["owner/repo"],
-    // permissions?: "read" | "pr-write" | "contents-write"
-    // default "pr-write" (comments / PR writes, no contents:write)
+  // Skip the agent's own comments so replies don't re-trigger it.
+  botName: "my-agent",
+  cursorAccount: { repos: ["acme/checkout"] },
+  onPullRequest: (ctx, pr) => {
+    if (pr.draft) {
+      return null;
+    }
+    if (pr.action !== "opened" && pr.action !== "ready_for_review") {
+      return null;
+    }
+    // `auth` starts a model turn running as the sender.
+    return { auth: defaultGitHubAuth(ctx) };
   },
-  // 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. The Agent SDK 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, or post merge-box checks |
+```ts
+// agent/tools/submit_review.ts
+import { parseGitHubPrContinuationKey } from "@cursor/july/channels/github";
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description:
+    "Post the review decision on this session's pull request. Call once.",
+  inputSchema: z.object({
+    verdict: z.enum(["approve", "request_changes"]),
+    summary: z
+      .string()
+      .describe("One or two sentences explaining the verdict."),
+  }),
+  async execute({ verdict, summary }, ctx) {
+    if (ctx.session.purpose === "eval") {
+      return { posted: false, reason: "eval" };
+    }
+    const ref = parseGitHubPrContinuationKey(ctx.session.continuationKey ?? "");
+    if (ref === undefined) {
+      throw new Error("submit_review requires a GitHub pull request session");
+    }
+
+    let event: "APPROVE" | "REQUEST_CHANGES" = "REQUEST_CHANGES";
+    if (verdict === "approve") {
+      event = "APPROVE";
+    }
+    const octokit = await ctx.host.github.getOctokit();
+    await octokit.rest.pulls.createReview({
+      owner: ref.owner,
+      repo: ref.repo,
+      pull_number: ref.number,
+      event,
+      body: summary,
+    });
+    return { posted: true, pr: `${ref.owner}/${ref.repo}#${ref.number}` };
+  },
+});
+```
 
-`contents-write` is an explicit opt-up. `progress.commitStatus` posts a
-GitHub check run (`checks:write`). Hosted `cursorAccount` mints that
-permission on `"contents-write"` tokens. Enabling `commitStatus` opts a
-`"pr-write"` channel up to that tier because it needs check-write
-permission. `"pr-write"` without `commitStatus` is enough for comments
-and banners.
-Prefer `"pr-write"` unless the agent must push or post a merge-box check.
+The wake tells you the PR changed. Fetch title, files, and checks inside
+the turn or a tool.
 
-Set `checks: true` when channel code posts its own Checks API runs through
-`ctx.github.createCheck`. The flag grants access. It does not post a check.
+## Answer a mention
 
-Selected repositories must share one GitHub owner (one App installation).
-Configuration that spans owners fails at startup / mint time.
+`onComment` replaces the default `@botName` gate. Return a turn when the
+comment is for this agent, then post the reply from a tool.
 
-To keep repository scope in deployment config instead, use
-`cursorAccount: true` and pass it at serve time:
+```ts
+onComment: (ctx, comment) => {
+  if (!comment.body.includes("@my-agent")) {
+    return null;
+  }
+  return { auth: defaultGitHubAuth(ctx) };
+},
+```
 
-```bash
-agent-sdk serve --dir . --cursor-events --repo owner/repo
+```ts
+// agent/tools/reply.ts
+import { parseGitHubPrContinuationKey } from "@cursor/july/channels/github";
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Post a comment on this session's pull request.",
+  inputSchema: z.object({
+    body: z.string().describe("Markdown to post on the PR timeline."),
+  }),
+  async execute({ body }, ctx) {
+    if (ctx.session.purpose === "eval") {
+      return { posted: false, reason: "eval" };
+    }
+    const ref = parseGitHubPrContinuationKey(ctx.session.continuationKey ?? "");
+    if (ref === undefined) {
+      throw new Error("reply requires a GitHub pull request session");
+    }
+
+    const octokit = await ctx.host.github.getOctokit();
+    await octokit.rest.issues.createComment({
+      owner: ref.owner,
+      repo: ref.repo,
+      issue_number: ref.number,
+      body,
+    });
+    return { posted: true };
+  },
+});
 ```
 
-Repeat `--repo` for each repository. The stream and credential are
-resolved as the signed-in Cursor principal. `serve` refuses to start
-signed out.
+Resolve owner, repo, and number from the session. Do not take a PR URL
+from the model. A later mention on the same PR resumes this
+conversation.
 
-The stream carries event metadata, not full webhook bodies, so your
-agent should re-read the PR or checks from GitHub instead of trusting a
-snapshot in the wake.
+## Triage a failing check
 
-This is the preferred production path: no public URL, no repo admin
-webhook, and no inbound network for GitHub deliveries.
+Start a model turn when CI fails. Run host code when the next step is
+already decided.
 
-## Connect GitHub Enterprise Server
+```ts
+onCheckSuite: (ctx, suite) => {
+  if (suite.conclusion !== "failure") {
+    return null;
+  }
+  // `auth` starts a model turn to read logs and comment.
+  return { auth: defaultGitHubAuth(ctx) };
+},
+```
 
-GitHub Enterprise Server uses the same `githubChannel()` hooks and normalized
-events. Connect it through the direct webhook route. Set the REST API base and
-credentials for your server:
+```ts
+onCheckSuite: (ctx, suite) => {
+  if (suite.conclusion !== "failure") {
+    return null;
+  }
+  // `task` runs host code instead of a model turn. No chat session.
+  return { task: () => labelFailure(ctx, suite) };
+},
+```
 
 ```ts
-export default githubChannel({
-  api: {
-    apiBaseUrl: "https://github.example.com/api/v3",
-  },
-  credentials: {
-    token: () => process.env.GITHUB_TOKEN,
-    webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET,
-  },
-  onPullRequest: (ctx, pr) =>
-    pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
-});
+async function labelFailure(ctx, suite) {
+  const pr = suite.pullRequests[0];
+  if (pr === undefined) {
+    return;
+  }
+  const octokit = await ctx.github.getOctokit();
+  await octokit.rest.issues.addLabels({
+    owner: ctx.repository.owner,
+    repo: ctx.repository.name,
+    issue_number: pr.number,
+    labels: ["ci-failed"],
+  });
+}
 ```
 
-Add a repository webhook for
-`https://<your-host>/<slug>/v1/channels/github`. Use the same webhook secret
-on the server and in `GITHUB_WEBHOOK_SECRET`. The channel verifies
-`X-Hub-Signature-256` before it parses the payload.
+## Events
 
-Cursor account event pull, `github replay`, and `github forward` target
-GitHub.com. Test Enterprise Server integrations by posting saved webhook
-fixtures to a local `--dev` server. Leave `GITHUB_WEBHOOK_SECRET` unset for
-this local test so the channel admits unsigned loopback deliveries. Use a real
-delivery from your server so the fixture matches its version.
+Declare a hook for each event that should wake the agent:
+`onPullRequest`, `onComment`, `onIssue`, `onCheckSuite`, `onCheckRun`,
+`onWorkflowRun`, `onStatus`, and the catch-all `onEvent`.
 
-## Define the channel
+Each hook returns one of three outcomes:
 
-Author `agent/channels/github.ts` with `githubChannel()` from
-`@cursor/july/channels/github`. It mounts
-`POST /<slug>/v1/channels/github` and publishes the events it
-dispatches on. That event set comes from the hooks you declare, or you
-pin it with `webhookEvents`. Cursor event pull and local replay both use
-it.
+| Return     | Use when                                                                      |
+| ---------- | ----------------------------------------------------------------------------- |
+| `{ auth }` | The model should reason about the event. The turn shows up in the playground. |
+| `{ task }` | Host code can handle the wake. No chat session.                               |
+| `null`     | Skip the event.                                                               |
 
-```ts
-import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
+[Channels](../reference/channels.md) covers the shared session behavior.
 
-export default githubChannel({
-  botName: "my-agent", // or GITHUB_APP_SLUG; used to ignore self-comments
-  cursorAccount: { repos: ["owner/repo"] },
-  onPullRequest: (ctx, pr) =>
-    pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
-  onCheckSuite: (ctx, suite) =>
-    suite.conclusion === "failure" ? { task: () => triage(ctx) } : null,
-});
-```
+## PR and agent affinity
 
-The hooks are `onPullRequest`, `onComment`, `onIssue`, `onCheckSuite`,
-`onCheckRun`, `onWorkflowRun`, `onStatus`, the catch-all `onEvent`, and
-the lifecycle pair `onStart` / `onStop`. Each hook returns one of three
-things:
+Every wake for the same repo and PR number resumes the same session. The
+channel keys turns as `github-pr:acme/checkout#42`. Opens, comments, and
+CI results share that conversation.
 
-| Return | Meaning |
-| --- | --- |
-| `{ auth }` | Start or continue a model turn as that actor. A chat session exists and shows up in the playground. |
-| `{ task }` | Host-side work. The delivery is 202-ACKed immediately and the task runs past GitHub's ~10-second timeout. No chat session. |
-| `null` | Skip this delivery. |
+## Call GitHub from determistic code via `ctx`
 
-`{ auth }` may also carry `workspaceFiles`, the same session seed Slack
-and `send()` use. Pass a function to fetch after a 202 so I/O can miss
-GitHub's ~10s window.
+`cursorAccount` puts one credential on both surfaces:
 
-Return `{ task }` when the wake drives deterministic code. A security
-reviewer can run its whole review loop this way and report
-through PR comments. Return `{ auth }` when the model needs to reason
-about the event.
+- Channel hooks: `ctx.github.getOctokit()`, `ctx.thread.post()`,
+  `ctx.repository`, and `ctx.conversation`
 
-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
-token as `GH_TOKEN` so tools that shell out to `gh` (a host-side
-`prepare_review` tool, say) authenticate without a PAT. For
-local testing, skip the App credentials and use `GITHUB_TOKEN`,
-`GH_TOKEN`, or `gh auth login`.
+- Tools: `ctx.host.github.getOctokit()`
 
-## Test wakes locally
+```ts
+onPullRequest: async (ctx, pr) => {
+  if (pr.action !== "opened") {
+    return null;
+  }
+  const octokit = await ctx.github.getOctokit();
+  const { data } = await octokit.rest.pulls.get({
+    owner: ctx.repository.owner,
+    repo: ctx.repository.name,
+    pull_number: pr.number,
+  });
+  if (data.draft) {
+    return null;
+  }
+  await ctx.thread.post(`Reviewing ${pr.url}`);
+  return { auth: defaultGitHubAuth(ctx) };
+},
+```
 
-Use fixtures and `github replay` so you can develop without waiting on
-live pushes. Both target the same channel route the Cursor relay uses.
+Re-read the PR here when the hook must decide. Tools use the host
+client for the same API during the turn.
 
-### Post a saved fixture
+## Batch events
 
-For offline tests, POST a saved payload with an `x-github-event` header.
-A `--dev` server does not require a signature:
+A change to a single request typically fans out multiple events, sometimes hundreds. A push can fire `synchronize`, several check runs,
+and comments in a few seconds. By default, individual channel hooks or webhooks do not debounce for you.
 
-```bash
-curl -s -X POST http://127.0.0.1:3000/<slug>/v1/channels/github \
-  -H 'content-type: application/json' \
-  -H 'x-github-event: pull_request' \
-  -d @fixtures/github/pull_request.synchronize.json
+Coalesce per PR. Flush the latest wake. Skip a flush when a turn for
+that PR is already running.
+
+```ts
+const pending = new Map();
+
+function enqueue(pr, flush) {
+  const key = `${pr.owner}/${pr.repo}#${pr.number}`;
+  const existing = pending.get(key);
+  if (existing !== undefined) {
+    clearTimeout(existing);
+  }
+  pending.set(
+    key,
+    setTimeout(() => {
+      pending.delete(key);
+      flush();
+    }, 3_000)
+  );
+}
 ```
 
-Don't hand-write payloads. Snapshot real ones with replay's
-`--dry-run --out`, below.
+The [PR autofixer](../templates/pr-autofixer.md) ships a buffer that
+persists across restarts and drops the queue when the PR closes.
 
-### Test with `github replay`
+## Test with replay
 
-Use `replay` for deterministic tests and
-[hillclimbing](../hillclimbing.md). It reads a real PR with `gh api`,
-synthesizes GitHub-shaped payloads, signs them when a secret is
-configured, and POSTs them at the channel. Pull access is enough: no
-admin, and an env `GITHUB_TOKEN` is fine here. The same input produces
-the same delivery.
+The AgentSDK makes it convenient for you to replay a PR you can read.
 
 ```bash
-# Replay a pull_request delivery for a PR
-agent-sdk github replay https://github.com/owner/repo/pull/123 --dir .
+agent-sdk github replay https://github.com/acme/checkout/pull/42 --dir . --action opened
 
 # Replay everything the channel listens for, with CI failing
-agent-sdk github replay owner/repo#123 --dir . --events '*' --conclusion failure
+agent-sdk github replay acme/checkout#42 --dir . --events '*' --conclusion failure
 
-# Inspect payloads without POSTing, and snapshot them as fixtures
-agent-sdk github replay owner/repo#123 --dir . --events '*' --dry-run --out fixtures/github
+# Snapshot payloads as fixtures instead of POSTing
+agent-sdk github replay acme/checkout#42 --dir . --events '*' --dry-run --out fixtures/github
 ```
 
-`--events` defaults to `pull_request`. `'*'` replays the events the channel
-declares and the CLI can synthesize. `--action`, `--conclusion`, `--comment`,
-and `--context` shape each event. `--secret` or `GITHUB_WEBHOOK_SECRET` signs
-them.
-
-## Receive webhooks directly
-
-Most hosts should pull events from Cursor instead. Use the HTTP channel
-route when you already terminate GitHub webhooks yourself, or when you
-are POSTing fixtures and replay locally.
-
-With a webhook secret configured, the route admits everyone
-(`allowAll()`) and the channel verifies `X-Hub-Signature-256` before
-parsing. The HMAC becomes the request principal. Without a secret, the
-route is loopback-only. The exception is `serve --dev`, which admits
-unsigned loopback deliveries so fixtures and replay work with zero
-config. Non-dev targets that accept real GitHub POSTs always need the
-secret, and the same value must live on the server and on whatever signs
-deliveries.
-
-## Handle high event volume
-
-These patterns come from running a PR agent against real traffic:
-
-- Debounce per PR (~3 seconds, latest event wins), and re-buffer while
-  CI settles. Skip a flush when a turn for that PR is already running.
-- Persist the buffer in `host.kv` before you acknowledge a wake, and
-  restore it on channel start. A restart must not drop buffered wakes.
-- Key sessions with a stable continuation token (`pr:owner/repo#N`) so
-  every wake resumes the PR's conversation.
-- Keep payload details out of wake prompts. Send a generic "re-check
-  the PR" and let the agent re-read source of truth instead of trusting a
-  stale snapshot.
-- Cancel PR-scoped reminders on `pull_request.closed`.
-- Decide explicitly which repos the agent may act on. Without an
-  allowlist the channel wakes for whatever deliveries reach it, and
-  every wake spends real model budget.
-
-## Show PR progress
-
-Autofix-style agents need a deterministic merge-box check and a sticky
-PR comment that converges when the turn ends. Configure that on the
-channel with `progress.commitStatus` and `progress.banner`. A hook can
-read and write `ctx.host.kv` and `ctx.host.files` after a turn. Use
-that for derived state. Keep GitHub check-run and banner writes on the
-channel.
+## Practices
 
-```ts
-import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
+- Re-read GitHub in the turn or a tool. Do not stuff the event payload
+  into the prompt.
+
+- Set `botName` so replies do not re-wake the agent.
+
+- Watch an explicit repo list (`cursorAccount.repos`). Repos under one
+  channel must share one GitHub owner.
+
+- Cancel leftover work on `pull_request.closed`.
 
+
+## Other hosts
+
+The same hooks work on GitHub Enterprise Server. Point the channel at
+your server and add a repo webhook:
+
+```ts
 export default githubChannel({
-  botName: "autofix",
-  deliverReplies: false,
-  progress: {
-    reactions: false,
-    commitStatus: {
-      context: "autofix",
-      pending: "Autofix running",
-      success: "Autofix finished",
-      failure: "Autofix failed",
-    },
-    banner: {
-      pending: "Autofix running…",
-      success: "Autofix finished",
-      failure: "Autofix failed",
-    },
+  api: {
+    apiBaseUrl: "https://github.example.com/api/v3",
   },
-  // commitStatus posts a Checks API run. Hosted cursorAccount opts the
-  // minted token up to contents-write (checks:write). Banner also works
-  // on pr-write without commitStatus.
-  cursorAccount: {
-    repos: ["owner/repo"],
+  credentials: {
+    token: () => process.env.GITHUB_TOKEN,
+    webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET,
   },
-  onPullRequest: (ctx, pr) =>
-    pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
 });
 ```
 
-Default stream events drive the lifecycle:
-
-| Event | Check run | Banner |
-| --- | --- | --- |
-| `turn.started` | `in_progress` | create (or keep) the sticky comment |
-| `turn.completed` | `completed` / `success` | PATCH the same comment |
-| `turn.failed` / `session.failed` | `completed` / `failure` | PATCH the same comment |
-
-Omit `commitStatus` / `banner`, or set them to `false`, to keep today's
-behavior. Reactions still default on; set `reactions: false` when the
-eyes emoji is noise. Descriptions are optional; defaults derive from
-`botName` or the check `context`.
-
-To match dashboard automations, set `detailsUrl(sessionId)`,
-`summaryLinkText: "View agent"`, and `outputTitle: "context"` so the
-check title is the check name, the summary includes `[View agent](…)`,
-and Details opens the session.
-
-A comment-only first wake has no head SHA, so the check waits for a
-PR or CI event. The banner still posts. A later turn on the same SHA
-creates a new check run; GitHub cannot reopen a completed run.
+Add a repository webhook for
+`https://<your-host>/<slug>/v1/channels/github` with the same secret.
+Event pull and `github replay` target GitHub.com, so test Enterprise
+Server with saved fixtures.
 
-Override `events` when the mapping is custom. A handler can post commit
-status from `turn.started` / `action.result` / `turn.failed` and stay
-never-red; that pattern still wins when you replace a default handler
-key. Handlers you author replace the matching defaults (same as
-`progress.reactions` composition today).
+Prefer event pull on github.com. Use the channel route directly when
+you already terminate GitHub webhooks yourself. Set a webhook secret on
+both sides. The [Webhooks guide](./webhooks.md) covers the shared
+mechanism.
 
 ## Related
 
-- [Webhooks and custom channels](./webhooks.md): the HTTP mechanism under
-  this pack
+- [Build a PR reviewer](../quickstart.md): the full read and write
+  loop, one step at a time
+- [PR autofixer](../templates/pr-autofixer.md): push fixes and show
+  progress on the PR
+- [Webhooks and custom channels](./webhooks.md): the HTTP mechanism
+  under this pack
 - [Evals](../evals.md): turn replay snapshots into regression fixtures
-- [Hooks](../reference/hooks.md): observe-only; use channel `progress` for
-  GitHub surfaces
+- [`skills/github/SKILL.md`](../../skills/github/SKILL.md): the companion
+  skill for coding agents