@cursor/july 0.1.54 → 0.1.61

package/templates/triage/agent/lib/parse-queue-event.ts

@@ -0,0 +1,168 @@
+import type { QueueIssue } from "./types.js";
+
+export const ISSUE_ID: RegExp = /\b[A-Z][A-Z0-9]{0,9}-\d+\b/;
+export const LINEAR_URL: RegExp =
+  /https:\/\/linear\.app\/(?:[^/\s"'<>]+\/)?issue\/[A-Z][A-Z0-9]{0,9}-\d+[^\s"'<>]*/i;
+export const JIRA_URL: RegExp =
+  /https:\/\/\S+\/(?:browse\/[A-Z][A-Z0-9]{0,9}-\d+|jira\/software\/[^\s"'<>]*selectedIssue=[A-Z][A-Z0-9]{0,9}-\d+)/i;
+
+export type ParseResult =
+  | { ok: true; issue: QueueIssue }
+  | { ok: false; ignored: true }
+  | { ok: false; error: string };
+
+export function isIssueId(value: string): boolean {
+  const match = value.match(ISSUE_ID);
+  return match !== null && match[0] === value;
+}
+
+export function pinIssueIdentifier(
+  continuationKey: string | null | undefined,
+  fallback: string
+): string {
+  if (typeof continuationKey === "string" && isIssueId(continuationKey)) {
+    return continuationKey;
+  }
+  return fallback;
+}
+
+export function isTrackerWebhook(body: unknown): boolean {
+  return (
+    isRecord(body) &&
+    (typeof body["type"] === "string" || typeof body["webhookEvent"] === "string")
+  );
+}
+
+export function parseQueueEvent(body: unknown): ParseResult {
+  if (!isRecord(body)) {
+    return { ok: false, error: "unsupported queue event" };
+  }
+
+  if (typeof body["webhookEvent"] === "string") {
+    if (body["webhookEvent"] !== "jira:issue_created") {
+      return { ok: false, ignored: true };
+    }
+    return parseJiraIssue(body);
+  }
+
+  if (typeof body["type"] === "string") {
+    if (body["type"] !== "Issue" || body["action"] !== "create") {
+      return { ok: false, ignored: true };
+    }
+    return parseLinearIssue(body);
+  }
+
+  if (typeof body["identifier"] === "string") {
+    return queueIssue({
+      identifier: body["identifier"],
+      title: stringValue(body["title"]),
+      description: descriptionValue(body["description"]),
+      url: stringValue(body["url"]),
+      reporter: reporterValue(body["reporter"]),
+    });
+  }
+
+  return { ok: false, error: "identifier is required" };
+}
+
+export function formatQueuePrompt(issue: QueueIssue): string {
+  return [
+    "Triage this existing issue.",
+    "",
+    `identifier: ${issue.identifier}`,
+    `title: ${issue.title}`,
+    `description: ${issue.description}`,
+    `url: ${issue.url}`,
+    `reporter: ${issue.reporter ?? ""}`,
+  ].join("\n");
+}
+
+function parseLinearIssue(body: Record<string, unknown>): ParseResult {
+  const data = body["data"];
+  if (!isRecord(data)) {
+    return { ok: false, ignored: true };
+  }
+  const identifier =
+    stringValue(data["identifier"]) || stringValue(data["key"]);
+  if (identifier.match(ISSUE_ID)?.[0] === undefined) {
+    return { ok: false, ignored: true };
+  }
+  return queueIssue({
+    identifier,
+    title: stringValue(data["title"]),
+    description: descriptionValue(data["description"]),
+    url: stringValue(data["url"]),
+    reporter: reporterValue(data["creator"]),
+  });
+}
+
+function parseJiraIssue(body: Record<string, unknown>): ParseResult {
+  const issue = body["issue"];
+  if (!isRecord(issue)) {
+    return { ok: false, ignored: true };
+  }
+  const fields = isRecord(issue["fields"]) ? issue["fields"] : {};
+  const identifier = stringValue(issue["key"]);
+  if (identifier.match(ISSUE_ID)?.[0] === undefined) {
+    return { ok: false, ignored: true };
+  }
+  return queueIssue({
+    identifier,
+    title: stringValue(fields["summary"]),
+    description: descriptionValue(fields["description"]),
+    url: stringValue(issue["self"]),
+    reporter: reporterValue(fields["reporter"]),
+  });
+}
+
+function queueIssue(input: QueueIssue): ParseResult {
+  const identifier = input.identifier.match(ISSUE_ID)?.[0];
+  if (identifier === undefined) {
+    return { ok: false, error: "identifier is required" };
+  }
+  return { ok: true, issue: { ...input, identifier } };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function stringValue(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+export function richTextValue(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(richTextValue).filter(Boolean).join("\n");
+  }
+  if (!isRecord(value)) {
+    return "";
+  }
+  if (typeof value["text"] === "string") {
+    return value["text"];
+  }
+  return richTextValue(value["content"]);
+}
+
+function descriptionValue(value: unknown): string {
+  return richTextValue(value);
+}
+
+function reporterValue(value: unknown): string | undefined {
+  if (typeof value === "string" && value !== "") {
+    return value;
+  }
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  for (const key of ["displayName", "name", "email", "emailAddress"]) {
+    const candidate = value[key];
+    if (typeof candidate === "string" && candidate !== "") {
+      return candidate;
+    }
+  }
+  return undefined;
+}

package/templates/triage/agent/lib/tracker.ts

@@ -0,0 +1,5 @@
+import type { TrackerConfig } from "./types.js";
+
+const tracker: TrackerConfig = { kind: "none" };
+
+export default tracker;

package/templates/triage/agent/lib/types.ts

@@ -0,0 +1,52 @@
+export type TriageKind = "bug" | "question" | "feedback";
+
+export type TriageSeverity = "low" | "medium" | "high" | "urgent";
+
+export interface QueueIssue {
+  identifier: string;
+  url: string;
+  title: string;
+  description: string;
+  reporter?: string;
+}
+
+export interface TriageVerdict {
+  identifier: string;
+  kind: TriageKind;
+  severity: TriageSeverity;
+  title: string;
+  summary: string;
+  nextStep: string;
+  reporter?: string;
+  duplicateOf?: string;
+  needsInfo?: boolean;
+}
+
+export interface TrackerIssue {
+  identifier: string;
+  url: string;
+}
+
+export type QueueAction =
+  | { op: "commented" }
+  | { op: "prioritized"; severity: TriageSeverity }
+  | { op: "duplicate_of"; of: string }
+  | { op: "needs_info" };
+
+export type TrackerResult =
+  | { status: "not_connected" }
+  | { status: "skipped"; reason: "eval" }
+  | { status: "acted"; issue: TrackerIssue; actions: QueueAction[] }
+  | { status: "failed"; message: string };
+
+export interface RecordTriageResult {
+  verdict: TriageVerdict;
+  evaluatedAt: string;
+  tracker: TrackerResult;
+}
+
+export type TrackerKind = "none" | "linear" | "jira";
+
+export type TrackerConfig =
+  | { kind: "none" }
+  | { kind: "linear" | "jira"; connectionName: string };

package/templates/triage/agent/lib/verify-webhook.ts

@@ -0,0 +1,81 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+const REPLAY_WINDOW_MS = 60_000;
+
+export type VerifyWebhookResult =
+  | { ok: true }
+  | { ok: false; status: 401 };
+
+export function verifyTrackerWebhook(input: {
+  rawBody: string;
+  linearSignature: string | null;
+  hubSignature: string | null;
+  linearSecret: string | undefined;
+  jiraSecret: string | undefined;
+  nowMs: number;
+}): VerifyWebhookResult {
+  if (input.linearSignature !== null && input.linearSignature !== "") {
+    if (
+      input.linearSecret === undefined ||
+      input.linearSecret === "" ||
+      !hmacHexEqual(input.linearSecret, input.rawBody, input.linearSignature)
+    ) {
+      return { ok: false, status: 401 };
+    }
+    return linearReplayFresh(input.rawBody, input.nowMs);
+  }
+
+  if (input.hubSignature !== null && input.hubSignature !== "") {
+    if (
+      input.jiraSecret === undefined ||
+      input.jiraSecret === "" ||
+      !hmacHexEqual(input.jiraSecret, input.rawBody, input.hubSignature)
+    ) {
+      return { ok: false, status: 401 };
+    }
+    return { ok: true };
+  }
+
+  return { ok: false, status: 401 };
+}
+
+function linearReplayFresh(
+  rawBody: string,
+  nowMs: number
+): VerifyWebhookResult {
+  let body: unknown;
+  try {
+    body = JSON.parse(rawBody);
+  } catch {
+    return { ok: false, status: 401 };
+  }
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    return { ok: false, status: 401 };
+  }
+  const timestamp = (body as { webhookTimestamp?: unknown }).webhookTimestamp;
+  if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) {
+    return { ok: false, status: 401 };
+  }
+  if (Math.abs(nowMs - timestamp) > REPLAY_WINDOW_MS) {
+    return { ok: false, status: 401 };
+  }
+  return { ok: true };
+}
+
+function hmacHexEqual(secret: string, rawBody: string, header: string): boolean {
+  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
+  const received = header.replace(/^sha256=/i, "").trim().toLowerCase();
+  let expectedBytes: Buffer;
+  let receivedBytes: Buffer;
+  try {
+    expectedBytes = Buffer.from(expected, "hex");
+    receivedBytes = Buffer.from(received, "hex");
+  } catch {
+    return false;
+  }
+  return (
+    expectedBytes.length > 0 &&
+    expectedBytes.length === receivedBytes.length &&
+    timingSafeEqual(expectedBytes, receivedBytes)
+  );
+}

package/templates/triage/agent/skills/triage-rubric.md

@@ -1,13 +1,14 @@
 ---
-description: Definitions and tie-breakers for classifying a report as bug, question, or feedback, plus the severity ladder.
+description: Definitions and tie-breakers for classifying an issue as bug, question, or feedback, plus the severity ladder.
 ---
 
 # Triage rubric
 
 ## Kinds
 
-- **bug**: something is broken, erroring, slow, or behaving wrong right
-  now, and the reporter wants it diagnosed or fixed. Usually has a
+- **bug**: the issue says something is broken, erroring, slow, or
+  behaving wrong now, and the reporter wants it diagnosed or fixed. It
+  usually has a
   symptom, an error, an id, a timestamp, or steps.
 - **question**: the reporter wants to know something that has an answer
   (how does X work, is Y expected, who owns Z). Someone has to look it
@@ -23,7 +24,7 @@ description: Definitions and tie-breakers for classifying a report as bug, quest
 - A question about a specific failure that already happened is a bug.
   "Why did my export fail yesterday?" needs an investigation, not a
   lookup.
-- A bug report that also suggests a fix is a bug.
+- An issue that reports a bug and suggests a fix is a bug.
 - A known bug with a workaround that only works sometimes is a bug. The
   unreliable workaround is the thing to explain.
 - A feature idea phrased as a question ("could we have dark mode?") is
@@ -39,5 +40,5 @@ description: Definitions and tie-breakers for classifying a report as bug, quest
   costs time.
 - **low**: cosmetic, minor friction, questions, and most feedback.
 
-Questions and feedback default to low unless the report shows real
+Questions and feedback default to low unless the issue shows real
 user impact.

package/templates/triage/agent/tools/record_triage.ts

@@ -1,23 +1,42 @@
 import { defineTool } from "@cursor/july/tools";
 import { z } from "zod";
+import { actuate } from "../lib/actuate.js";
+import tracker from "../lib/tracker.js";
 
 export default defineTool({
   description:
-    "Record the structured triage verdict for the current report. Call exactly once per report, before replying.",
+    "Record the verdict for the current tracker issue and enrich it in place with a comment, priority, or duplicate link. Call exactly once per issue. Never create a ticket.",
   inputSchema: z.object({
+    identifier: z
+      .string()
+      .describe("Identifier of the existing tracker issue."),
     kind: z.enum(["bug", "question", "feedback"]),
     severity: z.enum(["low", "medium", "high", "urgent"]),
     title: z
       .string()
       .max(80)
-      .describe("Short, imperative summary of the report."),
+      .describe("Short title for the issue."),
     summary: z
       .string()
-      .describe("What the reporter said, in two sentences or less."),
+      .describe("What the issue says, in two sentences or less."),
     nextStep: z.string().describe("The single next action for the team."),
     reporter: z.string().optional().describe("Who reported it, when known."),
+    duplicateOf: z
+      .string()
+      .optional()
+      .describe("Identifier of a matching existing issue."),
+    needsInfo: z
+      .boolean()
+      .optional()
+      .describe("Whether the issue needs more information."),
   }),
-  async execute(verdict) {
-    return { recorded: true, at: new Date().toISOString(), verdict };
+  async execute(verdict, ctx) {
+    return actuate({
+      verdict,
+      mcp: ctx.host.mcp,
+      tracker,
+      purpose: ctx.session.purpose,
+      issueKey: ctx.session.continuationKey,
+    });
   },
 });

package/templates/triage/evals/triage.eval.ts

@@ -1,4 +1,5 @@
 import { defineEval, includes } from "@cursor/july/evals";
+import { formatQueuePrompt } from "../agent/lib/parse-queue-event.js";
 
 export default defineEval({
   tags: ["smoke"],
@@ -8,7 +9,14 @@ export default defineEval({
       description: "A concrete failure is recorded as a bug.",
       async test(t) {
         await t.send(
-          "Export to CSV has failed with a 500 since this morning. Request id 41ac. Retrying does not help."
+          formatQueuePrompt({
+            identifier: "TRI-101",
+            title: "CSV export returns 500",
+            description:
+              "Export to CSV has failed with a 500 since this morning. Request id 41ac. Retrying does not help.",
+            url: "https://linear.app/acme/issue/TRI-101",
+            reporter: "Sam",
+          })
         );
         t.succeeded();
         t.calledTool("record_triage");
@@ -20,7 +28,14 @@ export default defineEval({
       description: "A how-does-it-work ask is recorded as a question.",
       async test(t) {
         await t.send(
-          "How do I rotate the API keys for the staging environment?"
+          formatQueuePrompt({
+            identifier: "TRI-102",
+            title: "Rotate staging API keys",
+            description:
+              "How do I rotate the API keys for the staging environment?",
+            url: "https://linear.app/acme/issue/TRI-102",
+            reporter: "Morgan",
+          })
         );
         t.succeeded();
         t.calledTool("record_triage");
@@ -32,7 +47,14 @@ export default defineEval({
       description: "A suggestion is recorded as feedback.",
       async test(t) {
         await t.send(
-          "The onboarding wizard has too many steps. You should collapse the profile pages into one."
+          formatQueuePrompt({
+            identifier: "TRI-103",
+            title: "Collapse onboarding profile pages",
+            description:
+              "The onboarding wizard has too many steps. You should collapse the profile pages into one.",
+            url: "https://linear.app/acme/issue/TRI-103",
+            reporter: "Riley",
+          })
         );
         t.succeeded();
         t.calledTool("record_triage");

package/templates/triage/overlays/jira/README.md

@@ -0,0 +1,21 @@
+# Triage agent for Jira
+
+Comments on existing Jira issues. Scaffold with:
+
+```bash
+npx @cursor/july init ./my-triage-agent --template triage-jira
+```
+
+Connect Jira in Cursor, then:
+
+```bash
+agent-sdk login
+agent-sdk dev
+```
+
+Paste an issue identifier in the playground. To receive Jira
+`issue_created` webhooks, self-host, set `JIRA_WEBHOOK_SECRET`, and
+point the webhook at `POST /<slug>/v1/channels/webhook`.
+
+Edit `agent/skills/triage-rubric.md` for your severity ladder.
+`agent-sdk eval` skips Jira writes.

package/templates/triage/overlays/jira/agent/lib/tracker.ts

@@ -0,0 +1,8 @@
+import type { TrackerConfig } from "./types.js";
+
+const tracker: TrackerConfig = {
+  kind: "jira",
+  connectionName: "tracker",
+};
+
+export default tracker;

package/templates/triage/overlays/jira/agent/mcp-connections/tracker.ts

@@ -0,0 +1,7 @@
+import { defineConnection } from "@cursor/july/connections";
+
+export default defineConnection({
+  cursorAccount: true,
+  servers: ["Jira"],
+  hostOnly: true,
+});

package/templates/triage/overlays/linear/README.md

@@ -0,0 +1,21 @@
+# Triage agent for Linear
+
+Comments on existing Linear issues. Scaffold with:
+
+```bash
+npx @cursor/july init ./my-triage-agent --template triage-linear
+```
+
+Connect Linear in Cursor, then:
+
+```bash
+agent-sdk login
+agent-sdk dev
+```
+
+Paste an issue identifier in the playground. To receive Linear Issue
+create webhooks, self-host, set `LINEAR_WEBHOOK_SECRET`, and point the
+webhook at `POST /<slug>/v1/channels/webhook`.
+
+Edit `agent/skills/triage-rubric.md` for your severity ladder.
+`agent-sdk eval` skips Linear writes.

package/templates/triage/overlays/linear/agent/lib/tracker.ts

@@ -0,0 +1,8 @@
+import type { TrackerConfig } from "./types.js";
+
+const tracker: TrackerConfig = {
+  kind: "linear",
+  connectionName: "tracker",
+};
+
+export default tracker;

package/templates/triage/overlays/linear/agent/mcp-connections/tracker.ts

@@ -0,0 +1,7 @@
+import { defineConnection } from "@cursor/july/connections";
+
+export default defineConnection({
+  cursorAccount: true,
+  servers: ["Linear", "Linear MCP"],
+  hostOnly: true,
+});

package/templates/triage/package.json

@@ -2,7 +2,7 @@
   "name": "triage-agent",
   "private": true,
   "type": "module",
-  "description": "Triage agent: classifies bug reports, questions, and feedback into structured verdicts.",
+  "description": "Comments on existing Linear or Jira issues.",
   "scripts": {
     "check": "tsc --noEmit",
     "dev": "agent-sdk dev"