@cursor/july 0.1.55 → 0.1.61

package/docs/templates/agentic-owners.md

@@ -0,0 +1,97 @@
+---
+title: "Review pull requests with owners policies"
+description: "Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows."
+---
+
+# Review pull requests with owners policies
+
+This agent reviews every pull request in your repository. It risk-tiers
+the diff, requests the owning team or user as reviewers, and approves
+what your policy allows. Ownership rules live in
+`.agentic-owners/policy.yml` files committed at any depth of the repo;
+the closest policy to a changed file wins, and policies are always read
+from the PR's base ref so a PR cannot exempt itself.
+
+## Scaffold
+
+```bash
+npx @cursor/july init ./owners-agent --template agentic-owners
+```
+
+`init` writes the project, installs dependencies, and puts `agent-sdk`
+on PATH.
+
+## Log in and run
+
+Set your repositories in `agent/lib/config.ts` (`repos: ["you/your-repo"]`),
+then:
+
+```bash
+cd owners-agent
+agent-sdk login
+agent-sdk dev
+```
+
+PR events stream through your Cursor account — no webhook or GitHub App
+setup. Open a PR, or replay a real one deterministically (this also works
+with `repos` empty):
+
+```bash
+agent-sdk github replay https://github.com/you/your-repo/pull/123 --dir .
+```
+
+Deploy with `agent-sdk deploy`.
+
+## Policies
+
+With no policy files, every PR gets a default risk review: very-low and
+low risk approve, medium and above hold with a comment. Route reviews by
+committing policies:
+
+```yaml
+# .agentic-owners/policy.yml — anywhere in the repo; closest wins.
+# paths are repo-root-relative globs, wherever the policy file lives.
+version: 1
+policies:
+  - paths: ["docs/**"]
+    always_approve: true
+  - paths: ["src/api/**"]
+    team: acme/platform # or user: alice
+    prompt: api-review.md # optional extra rubric, same directory
+  - paths: ["src/billing/**"]
+    user: alice
+    human_review_required: true # the agent never approves; a person must
+```
+
+`self_review: true` lets a listed owner's own PRs clear their rule.
+`global_exclusions` in the root policy opts paths out entirely.
+
+## What one review does
+
+One model turn per PR head assesses the host-fetched diff against the
+base rubric plus any matched rule prompts, then records a verdict with
+`record_review`. The host recomputes the policy from trusted state and
+applies the deterministic decision:
+
+- **Approve** when the tier is low and no matched rule demands a human,
+  bound to the head SHA.
+- **Request reviewers** otherwise — the policy owners (max 2, never the
+  author), plus one status comment the agent keeps updated in place.
+
+The model never writes to GitHub. A broken policy file fails closed with
+a comment listing the validation issues.
+
+## Rubric
+
+Edit `agent/lib/owners/prompts/base-review.md` for the risk tiers and
+their boundaries. Per-area guidance belongs in policy `prompt:` files
+next to the policy that names them. The next review reads both.
+
+## Evals
+
+```bash
+agent-sdk eval
+```
+
+Three smoke reviews (docs-only, auth deletion, prompt injection). Eval
+sessions skip GitHub writes.

package/docs/templates/demo.md

@@ -0,0 +1,84 @@
+---
+title: "Record a walkthrough from a collected PR"
+description: "Scaffold the agent, seed the PR on the host, record a walkthrough, and comment the result."
+---
+
+# Record a walkthrough from a collected PR
+
+This agent records a walkthrough for a pull request you already opened.
+The host fetches title, body, and files, writes `pr.md` and `files.md`,
+then starts the turn. The model reads those files. It does not fetch
+the PR.
+
+## Scaffold
+
+```bash
+npx @cursor/july init ./demo-agent --template demo
+```
+
+`init` writes the project, installs dependencies, and puts `agent-sdk`
+on PATH.
+
+## Log in
+
+Model turns use your Cursor account.
+
+```bash
+cd demo-agent
+agent-sdk login
+```
+
+The command opens a browser if you have no stored credential.
+
+## Collect the PR
+
+The host needs GitHub credentials so it can read the PR and comment:
+`GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth`.
+
+In the playground, run `/queue/pr` and paste a PR URL or `owner/repo#N`.
+
+```bash
+curl -X POST http://127.0.0.1:3000/demo-agent/v1/channels/queue/pr \
+  -H 'content-type: application/json' \
+  -d '{ "pr": "acme/shop#42" }'
+```
+
+The host fetches title, body, and files, writes `pr.md` and `files.md`,
+and starts the turn. Retries coalesce on `pr:owner/repo#N`.
+
+GitHub label `demo` or comment `/demo` when you terminate webhooks
+yourself: self-host and set `GITHUB_WEBHOOK_SECRET`. Hosted Cursor
+aliases require `X-Agent-Alias-Token`, which GitHub cannot send.
+
+`record_demo` comments on that key. Eval sessions skip the comment.
+
+## First walkthrough
+
+```bash
+agent-sdk dev
+```
+
+Open the playground. Run `/queue/pr` with a PR. The model reads the
+seeded files and calls `record_demo` once. Turns are sandboxed with
+`read` and `grep` only: PR title and body are untrusted.
+
+## Evals
+
+One smoke case. The host seeds `pr.md` and `files.md`. No GitHub call.
+
+```bash
+agent-sdk eval
+```
+
+## Deploy
+
+```bash
+agent-sdk deploy
+```
+
+Run it from the agent's git checkout. It infers repository, ref, path,
+and slug, builds on Cursor-managed hosting, and prints the URL.
+`agent-sdk deployments` shows status.
+
+Playground and `/queue/pr` need the alias token. GitHub label and
+`/demo` stay on a self-hosted agent with a webhook secret.

package/docs/templates/pr-autofixer.md

@@ -0,0 +1,136 @@
+---
+title: "Fix pull requests on a Cursor cloud VM"
+description: "Scaffold the agent, point it at your repos, and opt in to auto-fix a PR."
+---
+
+# Fix pull requests on a Cursor cloud VM
+
+This agent coordinates from chat and Slack, then hands each opted-in
+pull request to a Cursor cloud VM with a real checkout. The same cloud
+conversation resumes when you drive the PR again, GitHub reports a
+change on that PR, or a merge-conflict reminder fires.
+
+Chat never has the target checkout. `gh` and `git` run on the VM.
+Opening a pull request does not start a session. Drive a PR from the
+playground, Slack, or HTTP to opt in. After that, the agent auto-fixes:
+it pushes verified fixes to the PR head and performs workflow actions.
+It never merges, enables auto-merge, or force-pushes.
+
+## Scaffold
+
+On a TTY, `init` asks which GitHub repos to watch. Scripts pass the
+same answer with `--var`:
+
+```bash
+npx @cursor/july init ./pr-autofixer --template pr-autofixer
+npx @cursor/july init ./pr-autofixer --template pr-autofixer \
+  --var repos=acme/widgets,acme/api --json
+```
+
+`init` writes the project, installs dependencies, and puts `agent-sdk`
+on PATH. You can still edit `agent/lib/repos.ts` later, or override the
+list with `PR_AUTOFIXER_REPOS`.
+
+## Log in
+
+Model turns and cloud agents use your Cursor account.
+
+```bash
+cd pr-autofixer
+agent-sdk login
+```
+
+The command opens a browser if you have no stored credential. Cloud
+turns spend cloud-agent budget under that account.
+
+## Point it at a repo
+
+`init` writes the repo list into `agent/lib/repos.ts`. One owner. Up to
+20 repos. The GitHub channel requests `contents-write` so the agent can
+push to the PR head.
+
+## First drive
+
+```bash
+agent-sdk dev
+```
+
+Open the playground. Paste a PR URL or `owner/repo#N`. The local
+agent calls `drive_pr`, which attaches the PR to a cloud session and
+returns when that session exists. Autofix continues in the background.
+`bcId` / `agentUrl` are included when already bound.
+
+You can also POST:
+
+```bash
+curl -X POST http://127.0.0.1:3000/pr-autofixer/v1/channels/drive \
+  -H 'content-type: application/json' \
+  -d '{
+    "pr": "https://github.com/acme/widgets/pull/1"
+  }'
+```
+
+HTTP and `drive_pr` both return when the session exists, not when
+triage finishes. `bcId` / `agentUrl` are included when already bound.
+
+A merged or closed PR returns `status: "finished"` and does not start
+a session.
+
+The VM starts from the PR base. The agent creates `autofix/pr-<N>` off
+the PR head the first time it needs code, then pushes verified fixes
+with `git push origin HEAD:<headRef>`. Workflow actions run through
+`gh`. `autoCreatePR` is off, so the agent never opens a new PR.
+
+## GitHub wakes
+
+Mounted at `/v1/channels/github`. Cursor relays pull request, comment,
+review, check, and failing status events for the repos you listed. A
+wake only starts or resumes a cloud conversation after that PR has been
+driven. `pull_request.opened` is ignored. A PR comment or review on an
+opted-in PR wakes the agent. A comment on a plain GitHub issue does
+not. The channel buffers about 3 seconds per PR. Payload details are
+dropped on purpose. The follow-up says something changed.
+
+Pending wakes snapshot to `host.kv` (`webhook-buffer`) before the
+webhook is ACKed, and restore on restart. Affinity is
+`affinity/{owner/repo#N}` → `bc-…` in the same store, written from
+`agent.bound`. `agent/storage.ts` uses `cursorHostedStorage`, so both
+survive host replace. Local serve without that plug-in falls back to
+`--state-root/kv`.
+
+Closing a PR cancels its merge-conflict reminder and drops buffered
+wakes.
+
+See [GitHub](../guides/github.md) for `cursorAccount` login and
+fixture replay.
+
+## Slack
+
+`agent/channels/slack.ts` uses your signed-in Cursor account. Mention
+the agent or DM it with a PR URL. Same `drive_pr` path as the
+playground. See [Slack](../guides/slack.md).
+
+## Evals
+
+One smoke case. Chat without a PR must not call `drive_pr`, so a
+routine eval cannot spawn a cloud agent.
+
+```bash
+agent-sdk eval
+```
+
+Do not add cases that pass a PR URL unless you intend to spend cloud
+budget.
+
+## Deploy
+
+```bash
+agent-sdk deploy
+```
+
+Run it from the agent's git checkout. It infers repository, ref, path,
+and slug, builds on Cursor-managed hosting, and prints the URL.
+`agent-sdk deployments` shows status.
+
+See [Cloud runtime](../guides/cloud-runtime.md) for what changes on
+the VM.

package/docs/templates/security-reviewer.md

@@ -0,0 +1,89 @@
+---
+title: "Review pull requests for exploitable bugs"
+description: "Scaffold the agent, pick repos, replay a PR, and deploy."
+---
+
+# Review pull requests for exploitable bugs
+
+This agent reads a pull request diff and posts one review comment. It
+reports exploitable bugs: injection, authz bypass, secret leaks, SSRF,
+RCE. Style nits stay out.
+
+The factory [Security Reviewer](../example-agents/security-reviewer.md)
+runs a staged pipeline with parallel workers. This template is one
+model turn.
+
+## Scaffold
+
+```bash
+npx @cursor/july init ./security-reviewer --template security-reviewer
+```
+
+`init` asks which GitHub repos to watch. Every repo must share one
+owner. Pass `--var repos=acme/api,acme/web` to skip the prompt.
+
+The list lands in `agent/lib/repos.ts`. The GitHub channel reads it for
+`cursorAccount` and for the wake filter. Edit that file when the set
+changes.
+
+## Connect GitHub through Cursor
+
+Connect GitHub in Cursor for those repositories (Settings or
+[cursor.com/dashboard](https://cursor.com/dashboard)). Sign the host in:
+
+```bash
+cd security-reviewer
+agent-sdk login
+```
+
+`cursorAccount` pulls SCM events from Cursor and mints a short-lived,
+repo-scoped credential. `ctx.host.github` and child `gh` commands share
+it. See the [GitHub guide](../guides/github.md).
+
+## First review
+
+```bash
+agent-sdk dev
+```
+
+`dev` starts the Cursor event relay for the watched repos. To drive a
+known PR without waiting on a live push:
+
+```bash
+agent-sdk github replay https://github.com/acme/api/pull/12 --dir .
+```
+
+`replay` needs pull access. Draft PRs and repos outside
+`agent/lib/repos.ts` are ignored. The channel writes `pr/diff.patch`
+after the wake is acknowledged, then starts a model turn. The model
+calls `post_findings` once.
+
+Chat replies stay in the playground. `post_findings` writes the GitHub
+comment.
+
+## What to edit
+
+- `agent/lib/repos.ts`: watched repos
+- `agent/instructions.md`: what counts as a finding and the comment
+  shape
+- `evals/review.eval.ts`: smoke cases
+
+## Evals
+
+Two smoke cases: one XSS fixture and one docs-only change.
+
+```bash
+agent-sdk eval
+```
+
+Eval sessions skip the GitHub write.
+
+## Deploy
+
+```bash
+agent-sdk deploy
+```
+
+Run it from the agent's git checkout. The command infers repository,
+ref, path, and slug. The deployment uses the team's Cursor GitHub
+connection for the same watched repos.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.55",
+  "version": "0.1.61",
   "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": {
@@ -70,6 +70,12 @@
       "import": "./dist/channels/github/index.js",
       "default": "./dist/channels/github/index.js"
     },
+    "./channels/origin": {
+      "anysphere-source": "./src/channels/origin/index.ts",
+      "types": "./dist/channels/origin/index.d.ts",
+      "import": "./dist/channels/origin/index.js",
+      "default": "./dist/channels/origin/index.js"
+    },
     "./skills": {
       "anysphere-source": "./src/skills.ts",
       "types": "./dist/skills.d.ts",
@@ -261,6 +267,7 @@
     "@types/react-dom": "^19.0.0",
     "@typescript/native-preview": "7.0.0-dev.20260701.1",
     "@vitejs/plugin-react": "^5.1.2",
+    "minimatch": "^10.2.5",
     "pg": "^8.18.0",
     "pretty-ms": "^9.2.0",
     "react": "^19.2.1",
@@ -272,6 +279,7 @@
     "vite": "^7.3.0",
     "vitepress": "1.6.4",
     "vitest": "^4.0.18",
+    "yaml": "^2.4.2",
     "zustand": "^5.0.9"
   }
 }

package/skills/github/SKILL.md

@@ -142,12 +142,11 @@ first real delivery.
 
 - **Debounce per PR** (~3s, latest event wins) and re-buffer while CI
   settles; skip a flush when a turn for that PR is already in flight.
-- **Persist the buffer before ACKing** the webhook
-  (e.g. `.agent-serve/<slug>/webhook-buffer.json`) and restore it on channel
-  start — a restart must not drop buffered wakes.
+- **Persist the buffer before ACKing** the webhook in `host.kv`, then
+  restore it on channel start. A restart must not drop buffered wakes.
 - **Stable continuation key** `pr:owner/repo#N` so every wake resumes the
-  PR's session; cross-channel resume needs an affinity store mapping PR →
-  SDK agent id (write it from an `agent.bound` hook).
+  PR's session. Cross-channel resume needs an affinity store mapping PR →
+  SDK agent id (write it from an `agent.bound` hook with `ctx.host.kv`).
 - **Discard payload details in wake prompts** — send a generic "re-check
   the PR" refresh; the agent re-reads ground truth instead of trusting a
   stale payload.

package/src/bin/agent-serve.ts

@@ -108,7 +108,7 @@ Usage:
   ${CLI} trajectory  --events <file.ndjson> [--text]
   ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl> | --prod]
                           [--session <id>] [--slug <slug>] [--team <id>]
-  ${CLI} init        [dir] [--template <name>] [--json]
+  ${CLI} init        [dir] [--template <name>] [--var id=value]... [--json]
   ${CLI} convert-automation <url> [--dir <path>] [--json]
   ${CLI} install-skills [--print] [--json]
   ${CLI} mcp         --prod [--slug <slug>] [--team <id>] [--dir <path>]
@@ -198,9 +198,10 @@ Commands:
               via POST /v1/tools/:toolName. --session runs it inside an
               existing session and records it on that session's event stream.
   init        Scaffold a project (skipping existing files), npm install,
-              run login when unsigned, then print next steps. --json is
-              machine-readable and never blocks on login. No directory:
-              print the setup guide.
+              run login when unsigned, then print next steps. Templates
+              with init.json interview on a TTY; --var answers without a
+              prompt. --json is machine-readable and never blocks on
+              login. No directory: print the setup guide.
   convert-automation
               Export a Cursor Automation into an agentkit project. <url> is
               the dashboard URL (…/automations/<uuid> or
@@ -481,6 +482,7 @@ async function main(argv: string[]): Promise<number> {
     options: {
       dir: { type: "string", default: "." },
       template: { type: "string" },
+      var: { type: "string", multiple: true },
       port: { type: "string" },
       host: { type: "string" },
       mode: { type: "string" },
@@ -540,7 +542,7 @@ async function main(argv: string[]): Promise<number> {
       org: { type: "string" },
       "cursor-events": { type: "boolean", default: false },
       secret: { type: "string" },
-      channel: { type: "string" },
+      channel: { type: "string", multiple: true },
       install: { type: "boolean", default: false },
       action: { type: "string" },
       conclusion: { type: "string" },
@@ -594,6 +596,7 @@ async function main(argv: string[]): Promise<number> {
         prefix: values.prefix,
         noPrefix: values["no-prefix"],
         channelPosts: values["channel-posts"],
+        channels: values.channel,
         slackTeam: values["slack-team"],
         prod: values.prod,
         team: values.team,
@@ -620,7 +623,9 @@ async function main(argv: string[]): Promise<number> {
       return cmdGithub(positionals[0], {
         dir,
         slug: values.slug,
-        channel: values.channel,
+        // `--channel` is repeatable for `slack doctor`; the github
+        // subcommands target a single channel, so the last one wins.
+        channel: values.channel?.at(-1),
         host: values.host,
         port,
         url: values.url,
@@ -646,6 +651,7 @@ async function main(argv: string[]): Promise<number> {
         dir,
         initTarget: positionals[0],
         template: values.template,
+        vars: values.var,
         json: values.json,
       });
     }
@@ -1375,6 +1381,7 @@ function axFromOptions(
     tags: partial.tags,
     evalIds: partial.evalIds,
     initTarget: partial.initTarget,
+    vars: partial.vars,
     toolName: partial.toolName,
     toolInput: partial.toolInput,
     url: partial.url,

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

@@ -136,6 +136,16 @@ const githubPullRequestPayloadSchema: z.ZodType<GitHubPullRequestPayload> =
         sha: z.string().optional(),
       }),
     }),
+    changes: z
+      .object({
+        base: z
+          .object({
+            ref: z.object({ from: z.string().min(1).optional() }).optional(),
+          })
+          .optional(),
+      })
+      .nullable()
+      .optional(),
     sender: senderSchema,
     installation: installationSchema,
     label: z
@@ -184,6 +194,32 @@ export function githubContinuationKey(ctx: GitHubParsedContext): string {
   return `${kind}:${ctx.repository.fullName}#${ctx.conversation.number}`;
 }
 
+export interface GitHubPullRequestRef {
+  owner: string;
+  repo: string;
+  number: number;
+}
+
+/**
+ * Parse a pull-request continuation key minted by
+ * {@link githubContinuationKey} back into its repo + number. Undefined for
+ * issue keys and non-GitHub sessions — lets a server tool recover which PR
+ * its session is pinned to without trusting model-provided identifiers.
+ */
+export function parseGitHubPrContinuationKey(
+  key: string
+): GitHubPullRequestRef | undefined {
+  const match = /^github-pr:([^/#\s]+)\/([^#\s]+)#(\d+)$/.exec(key);
+  if (match === null) {
+    return undefined;
+  }
+  return {
+    owner: match[1]!,
+    repo: match[2]!,
+    number: Number(match[3]!),
+  };
+}
+
 /** @deprecated Prefer {@link githubContinuationKey}. */
 export function githubPullRequestContinuationKey(
   ctx: GitHubParsedContext
@@ -338,6 +374,9 @@ export function parseGitHubPullRequestEvent(args: {
     ...(payload.pull_request.base.sha === undefined
       ? {}
       : { baseSha: payload.pull_request.base.sha }),
+    ...(payload.changes?.base?.ref?.from === undefined
+      ? {}
+      : { baseRefChangedFrom: payload.changes.base.ref.from }),
     draft: payload.pull_request.draft ?? false,
     merged: payload.pull_request.merged === true,
     ...(payload.pull_request.user?.login === undefined
@@ -1469,15 +1508,34 @@ async function startTurn(input: {
   cloud?: AgentCloudOptions;
   state: GitHubChannelState;
 }): Promise<Response> {
-  const session = await input.args.send(input.message, {
-    auth: input.dispatch.auth,
-    continuationToken: githubContinuationKey(input.ctx),
-    title: input.dispatch.title ?? defaultGitHubTitle(input.ctx),
-    ...(input.cloud === undefined ? {} : { cloud: input.cloud }),
-    state: input.state as unknown as JsonValue,
-    // Resume must refresh headSha / refs without wiping sticky banner id.
-    refreshState: input.state as unknown as JsonValue,
-  });
+  const files = input.dispatch.workspaceFiles;
+  const lazy = typeof files === "function";
+
+  const sendTurn = async () => {
+    const workspaceFiles = lazy ? await files() : files;
+    return input.args.send(input.message, {
+      auth: input.dispatch.auth,
+      continuationToken: githubContinuationKey(input.ctx),
+      title: input.dispatch.title ?? defaultGitHubTitle(input.ctx),
+      ...(input.cloud === undefined ? {} : { cloud: input.cloud }),
+      ...(workspaceFiles === undefined ? {} : { workspaceFiles }),
+      state: input.state as unknown as JsonValue,
+      // Resume must refresh headSha / refs without wiping sticky banner id.
+      refreshState: input.state as unknown as JsonValue,
+    });
+  };
+
+  if (lazy) {
+    scheduleAfterAck(input.args, async () => {
+      await sendTurn();
+    });
+    return Response.json(
+      { ok: true, dispatched: true, mode: "turn" },
+      { status: 202 }
+    );
+  }
+
+  const session = await sendTurn();
   return Response.json({
     ok: true,
     sessionId: session.id,
@@ -1486,22 +1544,41 @@ async function startTurn(input: {
   });
 }
 
-function acknowledgeTask(
+function reportBackgroundFailure(error: unknown): void {
+  const detail =
+    error instanceof Error ? (error.stack ?? error.message) : String(error);
+  console.error(`[github] background dispatch failed: ${detail}`);
+}
+
+function scheduleAfterAck(
   args: ChannelHandlerArgs,
-  dispatch: GitHubTaskDispatch,
-  extra: Record<string, unknown>
-): Response {
-  // Defer the task past the current turn so the 202 can flush before work
-  // starts (and so tests can assert scheduling without racing microtasks).
+  work: () => void | Promise<void>
+): void {
+  // Defer past the current turn so the 202 can flush before work starts
+  // (and so tests can assert scheduling without racing microtasks).
   args.waitUntil(
-    new Promise<void>((resolve, reject) => {
+    new Promise<void>((resolve) => {
       setImmediate(() => {
         Promise.resolve()
-          .then(dispatch.task)
-          .then(() => resolve(), reject);
+          .then(work)
+          .then(
+            () => resolve(),
+            (error: unknown) => {
+              reportBackgroundFailure(error);
+              resolve();
+            }
+          );
       });
     })
   );
+}
+
+function acknowledgeTask(
+  args: ChannelHandlerArgs,
+  dispatch: GitHubTaskDispatch,
+  extra: Record<string, unknown>
+): Response {
+  scheduleAfterAck(args, dispatch.task);
   return Response.json(
     { ok: true, dispatched: true, mode: "task", ...extra },
     { status: 202 }