@cursor/july 0.1.53 → 0.1.55

package/src/internal/slack-provision-client.ts

@@ -467,7 +467,7 @@ function mapErrorResponse(
       );
     case 403:
       return new SlackProvisionApiError(
-        `${serverError ?? "Not authorized"} — Slack provisioning needs team membership and the cloud-agent entitlement on that team.`,
+        serverError ?? "Not authorized for this team",
         { status: 403 }
       );
     case 404: {

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.