@cursor/july 0.1.54 → 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/docs/templates/triage.md

@@ -1,147 +1,105 @@
 ---
-title: "Ship a triage agent from the template"
-description: "Scaffold the triage template, make its rubric yours, prove it with evals, and deploy it to Cursor-managed hosting."
+title: "Triage Linear or Jira issues in place"
+description: "Scaffold the agent, point it at an existing ticket, tune the rubric, run evals, and deploy."
 ---
 
-# Ship a triage agent from the template
+# Triage Linear or Jira issues in place
 
-The triage template is a working agent you own from the first command.
-It reads a report, classifies it as a bug, a question, or feedback,
-judges severity against a rubric, records a structured verdict, and
-replies with the next step. This page walks the whole arc: scaffold,
-first verdict, customize, prove, wire Slack, deploy.
+This agent comments on tickets you already filed. It classifies the
+issue, writes a `Triage:` comment, sets bug priority, and links a
+duplicate when titles match.
 
-Every file the template ships is yours to edit. The only dependency is
-`@cursor/july` itself, pinned to the version the template was tested
-against. Nothing phones home to a template registry.
+File the ticket however you already do. This template starts after the
+ticket exists.
 
-## Scaffold it
+## Scaffold
 
 ```bash
-npx @cursor/july init ./triage-agent --template triage
+npx @cursor/july init ./triage-agent --template triage-linear
+npx @cursor/july init ./triage-agent --template triage-jira
 ```
 
-One command with no prior install. It writes twelve files, runs
-`npm install`, puts `agent-sdk` on your PATH, and offers a browser
-sign-in when the machine has no Cursor credential. Model turns need
-that credential, so sign in now rather than mid-flow:
+Pick the tracker you use. The agent is the same. The overlay is the
+connection.
 
-```bash
-agent-sdk login
-```
+`init` writes the project, installs dependencies, and puts `agent-sdk`
+on PATH.
 
-The scaffold is a plain directory. Commit it to your own repo.
+## Log in
 
-## Get the first verdict
+Model turns and Cursor MCP use your Cursor account.
 
 ```bash
 cd triage-agent
-agent-sdk dev
+agent-sdk login
 ```
 
-Open the playground URL it prints and type a real report:
+The command opens a browser if you have no stored credential.
+
+## Connect the tracker
 
-> Export to CSV has returned 500s since this morning. Request id 41ac.
-> Retrying does not help.
+In the Cursor dashboard, open MCP and connect Linear or Jira.
 
-Watch the turn. The agent reads the `triage-rubric` skill, calls
-`record_triage` with a structured verdict, and replies in six lines or
-fewer. The tool call renders inline, so you see the exact kind,
-severity, and next step it recorded.
+The connection stays on the host. The model calls `record_triage`.
+Linear and Jira tools stay off the model's tool list.
 
-Integrations use the same door your playground does. The `intake`
-channel accepts reports over HTTP:
+## First verdict
 
 ```bash
-curl -X POST http://127.0.0.1:3000/triage-agent/v1/channels/intake/report \
-  -H 'content-type: application/json' \
-  -d '{"message":"How do I rotate staging API keys?","reporter":"dana"}'
+agent-sdk dev
 ```
 
-The composer also autocompletes `/report`, which drives this route.
-
-## Make the rubric yours
-
-`agent/skills/triage-rubric.md` holds the judgment: what counts as a
-bug, the tie-breakers, and the severity ladder. Edit it first. Your
-team's definition of `urgent` belongs there, in plain markdown, and the
-next turn uses it without a restart step.
+Open the playground. Run `/queue/issue` and paste an existing issue.
 
-`agent/instructions.md` owns the flow around the rubric: when to ask a
-clarifying question, the one-call `record_triage` rule, and the reply
-shape.
-
-## Prove it with evals
-
-The template ships three smoke cases, one per kind. Run them after
-every rubric edit:
+Local multi-agent mode mounts this project as `triage-agent`. You can
+also POST:
 
 ```bash
-agent-sdk eval
+curl -X POST http://127.0.0.1:3000/triage-agent/v1/channels/queue/issue \
+  -H 'content-type: application/json' \
+  -d '{
+    "identifier": "ENG-142",
+    "title": "CSV export returns 500",
+    "description": "Export has returned 500 since this morning."
+  }'
 ```
 
-Each case sends a realistic report and asserts a verdict was recorded
-with the expected kind. When you tighten the rubric, add a case for the
-report style you tightened it for. The eval suite is the regression
-net for prompt changes, so grow it with the rubric.
-
-## File verdicts into your tracker
-
-`agent/tools/record_triage.ts` defines the verdict shape with a zod
-schema and returns it. Point its `execute` at Linear, GitHub Issues, or
-a webhook to file real tickets. Test the tool without a model turn:
+`POST /v1/channels/queue/issue` accepts
+`{ identifier, title?, description? }` from the playground.
 
-```bash
-agent-sdk call record_triage --dir . --input '{
-  "kind": "bug",
-  "severity": "high",
-  "title": "CSV export 500s",
-  "summary": "Export returns 500 since this morning.",
-  "nextStep": "Check export service logs."
-}'
-```
+Hosted Cursor aliases require `X-Agent-Alias-Token`, which Linear and
+Jira cannot send. For create webhooks, self-host, set
+`LINEAR_WEBHOOK_SECRET` or `JIRA_WEBHOOK_SECRET`, and POST the signed
+body to `/v1/channels/webhook`. The channel ACKs immediately and
+coalesces retries onto the same issue.
 
-The call validates against the schema and runs your `execute` body
-in-process, so tracker wiring gets a fast loop.
+`record_triage` comments on the issue in the continuation key, not
+whatever identifier the model copies out of the ticket body.
 
-## Wire it to Slack
+## Rubric
 
-The `slack` channel idles until its tokens exist, so local work never
-blocks on Slack. When you want it live:
+Edit `agent/skills/triage-rubric.md` for kinds, tie-breakers, and what
+`urgent` means on your team. The next turn reads the file.
 
-```bash
-agent-sdk slack setup
-```
+`agent/instructions.md` is the procedure around the rubric: missing
+details, when to call `record_triage`, how to reply.
 
-The guided flow creates the Slack app and writes the token pair to
-`.env.local`. Restart `agent-sdk dev`, invite the bot to a channel, and
-@mention it with a report. The [Slack guide](../guides/slack.md) covers
-channel watching and approvals when you outgrow mentions.
+## Evals
 
-## Deploy it
+Three smoke cases, one per kind. Run them after you change the rubric.
 
 ```bash
-agent-sdk deploy
+agent-sdk eval
 ```
 
-From your git checkout, `deploy` infers the repo, ref, and slug, builds
-the ref on Cursor-managed hosting, and prints the hosted URL plus a
-one-time alias token. Store the token. Production Slack tokens go in as
-deployment secrets:
+Eval sessions skip tracker writes.
+
+## Deploy
 
 ```bash
-agent-sdk secrets set SLACK_BOT_TOKEN SLACK_APP_TOKEN --slug triage-agent
 agent-sdk deploy
 ```
 
-Check on it with `agent-sdk deployments`. The
-[deployment guide](../deployment.md) covers self-hosting, storage, and
-auth when you need them.
-
-## Where to go next
-
-- Add a GitHub intake with the [GitHub guide](../guides/github.md), so
-  issue comments triage themselves.
-- Persist verdicts across restarts with [storage](../storage.md).
-- Measure rubric changes on live traffic with
-  [A/B metrics](../ab.md).
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.54",
+  "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.