@cursor/july 0.1.54 → 0.1.61

package/templates/security-reviewer/README.md

@@ -0,0 +1,31 @@
+# Security reviewer
+
+Reviews pull requests for exploitable bugs. Posts one review comment.
+
+```bash
+npx @cursor/july init ./security-reviewer --template security-reviewer
+```
+
+`init` asks which repos to watch. Skip the prompt with
+`--var repos=owner/repo`.
+
+## Run
+
+Connect GitHub in Cursor for those repos. Then sign the host in:
+
+```bash
+agent-sdk login
+agent-sdk dev
+```
+
+Events and API calls use your Cursor GitHub connection. Replay a PR:
+
+```bash
+agent-sdk github replay https://github.com/owner/repo/pull/1 --dir .
+```
+
+## Files
+
+- `agent/lib/repos.ts`: watched repos
+- `agent/instructions.md`: what counts as a finding
+- `evals/review.eval.ts`: two smoke cases

package/templates/security-reviewer/agent/agent.ts

@@ -0,0 +1,15 @@
+import { defineAgent } from "@cursor/july";
+
+export default defineAgent({
+  model: {
+    id: "grok-4.5",
+    params: [
+      { id: "effort", value: "high" },
+      { id: "fast", value: "true" },
+    ],
+  },
+  tools: ["read", "grep"],
+  local: {
+    sandbox: true,
+  },
+});

package/templates/security-reviewer/agent/channels/github.ts

@@ -0,0 +1,46 @@
+import {
+  defaultGitHubPullRequestDispatch,
+  githubChannel,
+} from "@cursor/july/channels/github";
+import { REPOS, watches } from "../lib/repos.js";
+
+const MAX_DIFF_CHARS = 150_000;
+
+export default githubChannel({
+  cursorAccount: { repos: REPOS },
+  deliverReplies: false,
+  onComment: () => null,
+  onPullRequest: (ctx, pr) => {
+    if (!watches(ctx.repository.fullName) || pr.draft) {
+      return null;
+    }
+    const dispatch = defaultGitHubPullRequestDispatch(ctx, pr);
+    if (dispatch === null) {
+      return null;
+    }
+    return {
+      auth: dispatch.auth,
+      context: ["Read pr/diff.patch."],
+      async workspaceFiles() {
+        const octokit = await ctx.github.getOctokit();
+        const pull = {
+          owner: ctx.repository.owner,
+          repo: ctx.repository.name,
+          pull_number: pr.number,
+        };
+        const [meta, diff] = await Promise.all([
+          octokit.rest.pulls.get(pull),
+          octokit.rest.pulls.get({ ...pull, mediaType: { format: "diff" } }),
+        ]);
+        const text = String(diff.data);
+        return {
+          "pr/diff.patch":
+            text.length > MAX_DIFF_CHARS
+              ? `${text.slice(0, MAX_DIFF_CHARS)}\n…[truncated]\n`
+              : text,
+          "pr/head.sha": meta.data.head.sha,
+        };
+      },
+    };
+  },
+});

package/templates/security-reviewer/agent/instructions.md

@@ -0,0 +1,22 @@
+# Security reviewer
+
+You review pull requests for exploitable security bugs.
+
+## Review
+
+The workspace has `pr/diff.patch`. Read it. Report only exploitable
+issues: injection, authz bypass, secret leak, unsafe deserialization,
+SSRF, RCE. Skip style, tests, and hypotheticals.
+
+Call `post_findings` once with structured findings. Reply with the
+count and one line per finding. Clean review: empty findings.
+
+The host writes the GitHub comment. Verdict is CLEAN when the list
+is empty.
+
+## Finding
+
+- `severity`: `high`, `medium`, or `low`
+- `file`, `line`: path and line in the diff
+- `title`: short name
+- `detail`: one-line impact and fix

package/templates/security-reviewer/agent/lib/repos.ts

@@ -0,0 +1,5 @@
+export const REPOS: readonly string[] = ["owner/repo"];
+
+export function watches(fullName: string): boolean {
+  return REPOS.some((repo) => repo.toLowerCase() === fullName.toLowerCase());
+}

package/templates/security-reviewer/agent/tools/post_findings.ts

@@ -0,0 +1,72 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseGitHubPrRef } from "@cursor/july/channels/github";
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+const SHA = /^[0-9a-f]{40}$/i;
+
+const finding = z.object({
+  severity: z.enum(["high", "medium", "low"]),
+  file: z.string().min(1).max(240),
+  line: z.number().int().positive(),
+  title: z.string().min(1).max(160),
+  detail: z.string().min(1).max(280),
+});
+
+type Finding = z.infer<typeof finding>;
+
+export default defineTool({
+  description:
+    "Post the security review on this session's pull request. Call once. Empty findings = CLEAN.",
+  inputSchema: z.object({
+    findings: z
+      .array(finding)
+      .describe("Exploitable issues. Empty for CLEAN."),
+  }),
+  async execute({ findings }, ctx) {
+    if (ctx.session.purpose === "eval") {
+      return { posted: false, reason: "eval" };
+    }
+    const key = ctx.session.continuationKey ?? "";
+    if (!key.startsWith("github-pr:")) {
+      throw new Error("post_findings requires a GitHub pull request session");
+    }
+    const ref = parseGitHubPrRef(key.slice("github-pr:".length));
+    if (ref === undefined) {
+      throw new Error(`unrecognized PR: ${key}`);
+    }
+    const headSha = (
+      await readFile(join(ctx.workspaceDir, "pr/head.sha"), "utf8")
+    ).trim();
+    if (!SHA.test(headSha)) {
+      throw new Error("missing pr/head.sha");
+    }
+    const octokit = await ctx.host.github.getOctokit();
+    const response = await octokit.rest.pulls.createReview({
+      owner: ref.owner,
+      repo: ref.repo,
+      pull_number: ref.number,
+      commit_id: headSha,
+      body: reviewBody(findings),
+      event: "COMMENT",
+    });
+    return { posted: true, pr: ref.label, url: response.data.html_url };
+  },
+});
+
+function flatten(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function reviewBody(findings: Finding[]): string {
+  const verdict = findings.length === 0 ? "CLEAN" : "FINDINGS";
+  const lines = ["## Security review", "", `**Verdict:** ${verdict}`];
+  for (const item of findings) {
+    lines.push(
+      `- **${item.severity}** \`${flatten(item.file)}:${item.line}\` — ${flatten(item.title)}`
+    );
+    lines.push(`  ${flatten(item.detail)}`);
+  }
+  return lines.join("\n");
+}

package/templates/security-reviewer/evals/evals.config.ts

@@ -0,0 +1,5 @@
+import { defineEvalConfig } from "@cursor/july/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 10,
+});

package/templates/security-reviewer/evals/review.eval.ts

@@ -0,0 +1,53 @@
+import { defineEval, includes } from "@cursor/july/evals";
+
+const OPENED = [
+  "GitHub pull request trigger: acme/api#12",
+  "Action: opened",
+  "PR: https://github.com/acme/api/pull/12",
+  "Title: Search results",
+  "Head: feat/search (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa)",
+  "Base: main",
+  "Author: sam",
+  "",
+  "Read pr/diff.patch.",
+].join("\n");
+
+export default defineEval({
+  tags: ["smoke"],
+  cases: [
+    {
+      id: "xss",
+      description: "Unescaped query reflection is posted as a finding.",
+      async test(t) {
+        await t.send(OPENED, {
+          workspaceFiles: {
+            "pr/diff.patch": [
+              "diff --git a/app/routes/search.ts b/app/routes/search.ts",
+              "+res.send(`<h1>Results for ${req.query.q}</h1>`);",
+            ].join("\n"),
+          },
+        });
+        t.succeeded();
+        t.calledTool("post_findings");
+        t.check(t.reply, includes(/xss|cross-site|injection|finding/i));
+      },
+    },
+    {
+      id: "clean",
+      description: "A docs-only change is posted as clean.",
+      async test(t) {
+        await t.send(OPENED.replace("Search results", "Docs"), {
+          workspaceFiles: {
+            "pr/diff.patch": [
+              "diff --git a/README.md b/README.md",
+              "+# API",
+            ].join("\n"),
+          },
+        });
+        t.succeeded();
+        t.calledTool("post_findings");
+        t.check(t.reply, includes(/clean|no findings|no vulnerabilities/i));
+      },
+    },
+  ],
+});

package/templates/security-reviewer/init.json

@@ -0,0 +1,25 @@
+{
+  "questions": [
+    {
+      "id": "repos",
+      "prompt": "Which GitHub repos should this agent review?",
+      "hint": "Comma-separated owner/repo. One GitHub owner.",
+      "placeholder": "acme/api, acme/web",
+      "parse": "owner-repo-list"
+    }
+  ],
+  "replace": [
+    {
+      "file": "agent/lib/repos.ts",
+      "find": "[\"owner/repo\"]",
+      "answer": "repos",
+      "as": "json-array"
+    },
+    {
+      "file": "README.md",
+      "find": "owner/repo",
+      "answer": "repos",
+      "as": "first"
+    }
+  ]
+}

package/templates/security-reviewer/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "security-reviewer",
+  "private": true,
+  "type": "module",
+  "description": "Reviews pull requests for exploitable security bugs.",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "dev": "agent-sdk dev"
+  },
+  "dependencies": {
+    "@cursor/july": "latest",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "typescript": "^5.8.0"
+  }
+}

package/templates/security-reviewer/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["agent/**/*", "evals/**/*"]
+}

package/templates/triage/README.md

@@ -1,48 +1,46 @@
 # Triage agent
 
-A triage front door for your team. Send it bug reports, questions, and
-feedback; it classifies each report against a rubric, judges severity,
-records a structured verdict, and replies with the next step.
-
-Scaffolded with:
+Comments on existing Linear or Jira issues. Classifies the ticket, writes
+the next step, links a duplicate, and sets bug priority when the
+connector can.
 
 ```bash
-npx @cursor/july init ./my-triage-agent --template triage
+npx @cursor/july init ./my-triage-agent --template triage-linear
+npx @cursor/july init ./my-triage-agent --template triage-jira
 ```
 
-## Run it
+## Run
+
+Connect the tracker in Cursor.
 
 ```bash
-agent-sdk login   # once per machine
+agent-sdk login
 agent-sdk dev
 ```
 
-Open the playground URL it prints. Chat directly, or use the `/report`
-slash command to submit a report the way an integration would
-(`POST /v1/channels/intake/report`).
+In the playground, paste an issue identifier or run `/queue/issue`.
 
-## Wire it to Slack
+```text
+POST /<slug>/v1/channels/queue/issue
+```
 
-The Slack channel idles until its tokens exist. Create a Slack app and
-its env with:
+Hosted Cursor aliases require `X-Agent-Alias-Token`. Linear and Jira
+cannot send that header, so point create webhooks at a self-hosted
+agent instead:
 
-```bash
-agent-sdk slack setup
+```text
+POST /<slug>/v1/channels/webhook
 ```
 
-Then @mention the bot or DM it. The setup-slack skill in the
-@cursor/july package has the full walkthrough.
+Set `LINEAR_WEBHOOK_SECRET` or `JIRA_WEBHOOK_SECRET` to the signing
+secret from the tracker. The identifier is the continuation key.
+Questions and feedback get comments. A duplicate match gets a comment
+on both issues. `agent-sdk eval` classifies and skips tracker writes.
 
-## Make it yours
+## Files to edit
 
-- `agent/instructions.md` owns the flow every report follows.
-- `agent/skills/triage-rubric.md` owns the kinds, the tie-breakers, and
-  the severity ladder. Edit this first; it is the judgment.
-- `agent/tools/record_triage.ts` owns the verdict shape. Point its
-  `execute` at your tracker (Linear, GitHub Issues, a webhook) to file
-  real tickets.
-- `evals/triage.eval.ts` holds three smoke cases. Run `agent-sdk eval`
-  after every rubric change.
+- `agent/skills/triage-rubric.md`: kinds, tie-breakers, severity
+- `agent/instructions.md`: procedure around the rubric
+- `evals/triage.eval.ts`: three smoke cases
 
-The full walkthrough, from scaffold through deploy, is the triage
-cookbook: run `agent-sdk docs` and open Templates, then Triage agent.
+`agent/lib/actuate.ts` talks to the tracker. The connection is host-only.

package/templates/triage/agent/agent.ts

@@ -8,6 +8,7 @@ export default defineAgent({
       { id: "fast", value: "true" },
     ],
   },
+  tools: ["read", "grep", "glob", "ls"],
   local: {
     sandbox: true,
   },

package/templates/triage/agent/channels/queue.ts

@@ -0,0 +1,47 @@
+import { defineChannel, POST } from "@cursor/july/channels";
+import { z } from "zod";
+import {
+  formatQueuePrompt,
+  isTrackerWebhook,
+  parseQueueEvent,
+} from "../lib/parse-queue-event.js";
+
+export default defineChannel({
+  routes: [
+    POST("/issue", {
+      description: "Triage an existing tracker issue",
+      bodySchema: z.unknown(),
+      handler: async (_req, { send, waitUntil, body }) => {
+        const parsed = parseQueueEvent(body);
+        if (!parsed.ok) {
+          if ("ignored" in parsed) {
+            return Response.json({ ok: true, ignored: true });
+          }
+          return Response.json(
+            { ok: false, error: parsed.error },
+            { status: 400 }
+          );
+        }
+        const options = {
+          continuationToken: parsed.issue.identifier,
+          admission: "coalesce" as const,
+          ...(parsed.issue.title === "" ? {} : { title: parsed.issue.title }),
+        };
+        const prompt = formatQueuePrompt(parsed.issue);
+        if (isTrackerWebhook(body)) {
+          waitUntil(send(prompt, options));
+          return Response.json({
+            ok: true,
+            identifier: parsed.issue.identifier,
+          });
+        }
+        const session = await send(prompt, options);
+        return Response.json({
+          ok: true,
+          sessionId: session.id,
+          identifier: parsed.issue.identifier,
+        });
+      },
+    }),
+  ],
+});

package/templates/triage/agent/channels/webhook.ts

@@ -0,0 +1,50 @@
+import { allowAll, defineChannel, POST } from "@cursor/july/channels";
+import { z } from "zod";
+import {
+  formatQueuePrompt,
+  parseQueueEvent,
+} from "../lib/parse-queue-event.js";
+import { verifyTrackerWebhook } from "../lib/verify-webhook.js";
+
+export default defineChannel({
+  auth: [allowAll()],
+  routes: [
+    POST("/", {
+      description: "Signed Linear or Jira issue-created webhook",
+      bodySchema: z.unknown(),
+      handler: async (request, { send, waitUntil, body }) => {
+        const rawBody = await request.text();
+        const verified = verifyTrackerWebhook({
+          rawBody,
+          linearSignature: request.headers.get("linear-signature"),
+          hubSignature:
+            request.headers.get("x-hub-signature-256") ??
+            request.headers.get("x-hub-signature"),
+          linearSecret: process.env.LINEAR_WEBHOOK_SECRET,
+          jiraSecret: process.env.JIRA_WEBHOOK_SECRET,
+          nowMs: Date.now(),
+        });
+        if (!verified.ok) {
+          return Response.json({ ok: false }, { status: verified.status });
+        }
+        const parsed = parseQueueEvent(body);
+        if (!parsed.ok) {
+          return Response.json({ ok: true, ignored: true });
+        }
+        waitUntil(
+          send(formatQueuePrompt(parsed.issue), {
+            continuationToken: parsed.issue.identifier,
+            admission: "coalesce",
+            ...(parsed.issue.title === ""
+              ? {}
+              : { title: parsed.issue.title }),
+          })
+        );
+        return Response.json({
+          ok: true,
+          identifier: parsed.issue.identifier,
+        });
+      },
+    }),
+  ],
+});

package/templates/triage/agent/instructions.md

@@ -1,27 +1,38 @@
 # Triage agent
 
-You are the triage front door for this team. People send you reports:
-bug reports, questions, feedback, feature ideas. You classify each one,
-judge its severity, and hand back a verdict the team can act on.
+You triage an existing Linear or Jira issue. The prompt includes its
+identifier. Classify the issue, judge its severity, and record a verdict
+that helps the team act on it.
 
 Read the `triage-rubric` skill before classifying. It defines the three
 kinds and the tie-breakers.
 
-## Every report
+## Every issue
 
-1. Read the report. If it is too thin to classify (no symptom, no
-   question, no opinion), ask for the missing piece once. Otherwise do
-   not ask; classify with what you have.
-2. If a `memory/` directory exists in your workspace, grep the journal
-   for similar past reports and say when one matches.
-3. Call `record_triage` exactly once with your verdict.
-4. Reply with the verdict: kind, severity, a one-line reason, and the
-   next step. Keep the reply under six lines. No preamble.
+1. Read the identifier, title, description, URL, and reporter from the
+   prompt. Never invent missing fields.
+2. If the issue is too thin to classify, set `needsInfo` to true. Put the
+   exact missing detail in `nextStep`, then ask for it once in your reply.
+   Otherwise classify with what you have.
+3. If a `memory/` directory exists in your workspace, grep the journal
+   for similar issues. Set `duplicateOf` to the matching identifier when
+   the evidence is strong.
+4. Call `record_triage` exactly once. Pass the identifier from the
+   prompt with your verdict. The tool comments on the existing issue,
+   records duplicates, and sets bug priority when supported.
+5. Reply with the identifier, kind, severity, one-line reason, and next
+   step. If the tracker is not connected, tell the user to connect
+   Linear or Jira in Cursor. Keep the reply under eight lines. No
+   preamble.
 
 ## Boundaries
 
 - You classify and route. You do not fix bugs, write code, or promise
   timelines.
-- When a report mixes kinds, pick the dominant one and name the split
+- You never create or file an issue. Native Slack @Cursor handles ticket
+  creation. This agent only enriches the issue in the prompt.
+- Questions and feedback still go through `record_triage` so the issue
+  receives a comment.
+- When an issue mixes kinds, pick the dominant one and name the split
   in your reason.
 - Never invent reporter details. Missing fields stay empty.