@zibby/workflow-templates 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/workflow-templates",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Built-in workflow templates for Zibby — browser-test-automation, code-analysis, generate-test-cases, notify-slack, notify-lark, notify-notion, sentry-triage.",
   "type": "module",
   "main": "index.js",
@@ -72,7 +72,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.88.0",
     "@zibby/agent-workflow": "^0.4.2",
-    "@zibby/skills": "^0.1.25",
+    "@zibby/skills": "^0.1.27",
     "axios": "^1.15.0",
     "handlebars": "^4.7.9",
     "zod": "^3.23.0 || ^4.0.0"

package/sentry-triage/graph.mjs

@@ -48,7 +48,17 @@ export class SentryTriageAgent extends WorkflowAgent {
     graph.addNode('dispatch_alerts', dispatchNode);
 
     graph.setEntryPoint('fetch_issues');
-    graph.addEdge('fetch_issues',    'classify');
+    // Short-circuit when Sentry returned nothing for this window. The
+    // empty-list case is the common idle path (steady-state apps don't
+    // throw new errors every hour), and running classify + dispatch on
+    // an empty input wastes two Claude calls per run — at hourly cadence
+    // across many tenants that adds up. Cleaner to route directly to END
+    // at the graph level than to short-circuit inside each downstream
+    // node's prompt (which still spends a model round-trip).
+    graph.addConditionalEdges('fetch_issues', (state) => {
+      const issues = state?.fetch_issues?.issues || [];
+      return issues.length === 0 ? 'END' : 'classify';
+    });
     graph.addEdge('classify',        'dispatch_alerts');
     graph.addEdge('dispatch_alerts', 'END');
 

package/sentry-triage/nodes/dispatch-node.js

@@ -1,41 +1,80 @@
 /**
- * dispatch_alerts node — LLM-driven dispatcher.
+ * dispatch_alerts node — LLM-driven dispatcher with author routing.
  *
- * The agent sees ALL classified issues + their full data and makes
- * judgment calls before calling the chat tool:
- *   - Bulk related issues into ONE message (5 errors in /checkout/ →
- *     "⚠️ Checkout spike: 5 errors, top: ...").
- *   - De-dupe near-duplicates ("seen 3 times, same culprit").
- *   - Honor SEVERITY_THRESHOLD (skip anything below).
- *   - Attach mentions only on CRITICAL.
+ * The agent reads each classified issue (+ its Sentry suspectCommits
+ * author, when available) and decides per-issue where to send the
+ * alert. Three layers of decisioning, top-down:
  *
- * Provider routing: chatNotifySkill.resolve() picks the slack OR lark
- * MCP server based on which ENV var is set, so the LLM only ever sees
- * ONE provider's tools (slack_* or lark_*) — it can't accidentally
- * call the wrong one.
+ *   1. `DISPATCH_RULES` (free-form natural-language override)
+ *      — when set, the agent applies these rules verbatim and treats
+ *        the structured env vars below as defaults. For advanced
+ *        routing ("security tag always pages @security regardless of
+ *        severity", "weekend hours quiet unless CRITICAL", etc.).
  *
- * Reliability: outputSchema enforces a `dispatched` record per
- * group + summary counts. A malformed LLM response triggers a retry
- * with the schema embedded.
+ *   2. Structured env vars (the 90% path):
+ *        SLACK_CHANNEL / LARK_RECEIVE_ID   — pick provider, channel fallback
+ *        SEVERITY_THRESHOLD                — skip anything below
+ *        ROUTING_PREFER_AUTHOR             — if suspectCommit.author email
+ *                                            resolves to a user, DM them
+ *        ROUTING_HIGH_SEVERITY_GROUP       — handle/id of a Slack
+ *                                            usergroup (@oncall) that gets
+ *                                            mentioned on CRITICAL/HIGH
+ *        SLACK_MENTIONS / LARK_MENTIONS    — flat mention list, CRITICAL only
  *
- * ENV tab config:
- *   SLACK_CHANNEL OR LARK_RECEIVE_ID  — required, pick one
+ *   3. Built-in defaults (when neither rules nor env set anything):
+ *        - threshold MEDIUM, no author DM, channel-only post.
+ *
+ * Author-routing tools the agent has access to (from the slack/lark
+ * skills via SKILLS.CHAT_NOTIFY):
+ *   slack:
+ *     - slack_lookup_user_by_email   email → user id (DM target)
+ *     - slack_list_usergroups        list @oncall etc., with handle + count
+ *     - slack_get_usergroup_members  expand a group → user ids
+ *     - slack_post_message           DM user id OR channel
+ *   lark:
+ *     - lark_lookup_user_by_email    email → open_id (DM target)
+ *     - lark_send_message            DM open_id OR oc_* group chat
+ *
+ * Provider selection: chatNotifySkill.resolve() picks slack or lark
+ * based on which env var (`SLACK_CHANNEL` or `LARK_RECEIVE_ID`) the
+ * project sets. The LLM only sees one provider's tools, so it can't
+ * accidentally fan out to the wrong workspace.
+ *
+ * Reliability: outputSchema enforces a per-dispatch record + summary.
+ * A malformed LLM response triggers a retry with the schema embedded.
+ *
+ * ENV tab config — required:
+ *   SLACK_CHANNEL OR LARK_RECEIVE_ID  — provider selector + channel fallback
+ *
+ * ENV tab config — optional:
  *   SEVERITY_THRESHOLD                — NOISE|LOW|MEDIUM|HIGH|CRITICAL (default MEDIUM)
- *   SLACK_MENTIONS OR LARK_MENTIONS   — JSON array, optional, CRITICAL only
+ *   ROUTING_PREFER_AUTHOR             — "true" enables suspectCommit author DM
+ *   ROUTING_HIGH_SEVERITY_GROUP       — e.g. "@oncall" or "S012ABC" (Slack usergroup id)
+ *   SLACK_MENTIONS / LARK_MENTIONS    — JSON array of mentions on CRITICAL
+ *   DISPATCH_RULES                    — free-form natural-language overrides
  */
 
 import { z, SKILLS } from '@zibby/core';
 import { SEVERITY_LEVELS } from '../state.js';
 
+const DispatchedRecordSchema = z.object({
+  issueIds: z.array(z.string()).describe('IDs grouped into this message; usually 1, more when batched.'),
+  severity: z.enum(SEVERITY_LEVELS),
+  status: z.enum(['sent', 'skipped', 'failed']),
+  // Who actually received this message. Helps post-hoc auditing of
+  // routing decisions ("why did the agent send this to @sarah?").
+  recipient: z.object({
+    kind: z.enum(['channel', 'user_dm', 'usergroup']).optional(),
+    id: z.string().optional(),
+    label: z.string().optional(),
+  }).optional(),
+  messageTs: z.string().optional(),  // Slack
+  messageId: z.string().optional(),  // Lark
+  detail: z.string().optional(),
+});
+
 const DispatchAlertsOutputSchema = z.object({
-  dispatched: z.array(z.object({
-    issueIds: z.array(z.string()).describe('IDs grouped into this message; usually 1, more when batched.'),
-    severity: z.enum(SEVERITY_LEVELS),
-    status: z.enum(['sent', 'skipped', 'failed']),
-    messageTs: z.string().optional(),  // Slack
-    messageId: z.string().optional(),  // Lark
-    detail: z.string().optional(),
-  })),
+  dispatched: z.array(DispatchedRecordSchema),
   summary: z.object({
     total: z.number().describe('Number of messages POSTED (not issues — batched groups count as 1).'),
     sent: z.number(),
@@ -44,77 +83,157 @@ const DispatchAlertsOutputSchema = z.object({
   }),
 });
 
+const SEVERITY_ORDER = ['NOISE', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
+
 const DISPATCH_PROMPT = (state = {}) => {
   const issues = state?.fetch_issues?.issues || [];
   const classifications = state?.classify?.classifications || [];
 
-  const threshold     = process.env.SEVERITY_THRESHOLD || 'MEDIUM';
-  const slackChannel  = process.env.SLACK_CHANNEL      || '';
-  const larkReceiveId = process.env.LARK_RECEIVE_ID    || '';
+  const threshold       = process.env.SEVERITY_THRESHOLD       || 'MEDIUM';
+  const slackChannel    = process.env.SLACK_CHANNEL            || '';
+  const larkReceiveId   = process.env.LARK_RECEIVE_ID          || '';
+  const preferAuthor    = /^(1|true|yes|on)$/i.test(process.env.ROUTING_PREFER_AUTHOR || '');
+  const highSevGroup    = process.env.ROUTING_HIGH_SEVERITY_GROUP || '';
+  const dispatchRules   = process.env.DISPATCH_RULES           || '';
+
+  // ── No-op short-circuit ─────────────────────────────────────────
+  // Same three "nothing to do this run" cases as before — keep the
+  // run green without forcing channel setup.
+  const minSeverityRank = SEVERITY_ORDER.indexOf(threshold);
+  const aboveThreshold = minSeverityRank < 0
+    ? classifications
+    : classifications.filter((c) => SEVERITY_ORDER.indexOf(c.severity) >= minSeverityRank);
+
+  if (issues.length === 0 || classifications.length === 0 || aboveThreshold.length === 0) {
+    const reason =
+      issues.length === 0          ? 'fetch_issues returned no issues' :
+      classifications.length === 0 ? 'classifier emitted no records' :
+                                     `all ${classifications.length} issue(s) below SEVERITY_THRESHOLD=${threshold}`;
+    return `No Sentry issues to dispatch this run (${reason}).
+
+Return this exact JSON envelope and call no tools:
+
+\`\`\`json
+{ "dispatched": [], "summary": { "total": 0, "sent": 0, "skipped": 0, "failed": 0 } }
+\`\`\`
+`;
+  }
 
-  let provider, toolName, recipientLine, mentionsRaw;
+  // ── Provider selection ──────────────────────────────────────────
+  let provider, postTool, lookupTool, channelId, mentionsRaw;
   if (slackChannel) {
-    provider = 'slack';
-    toolName = 'slack_post_message';
-    recipientLine = `Post every message to Slack channel: ${JSON.stringify(slackChannel)}\nCall: slack_post_message({ channel: "${slackChannel}", text: "…" })`;
+    provider    = 'slack';
+    postTool    = 'slack_post_message';
+    lookupTool  = 'slack_lookup_user_by_email';
+    channelId   = slackChannel;
     mentionsRaw = process.env.SLACK_MENTIONS || '[]';
   } else if (larkReceiveId) {
-    provider = 'lark';
-    toolName = 'lark_send_message';
-    recipientLine = `Post every message to Lark receive_id: ${JSON.stringify(larkReceiveId)}\nCall: lark_send_message({ receive_id: "${larkReceiveId}", text: "…" })`;
+    provider    = 'lark';
+    postTool    = 'lark_send_message';
+    lookupTool  = 'lark_lookup_user_by_email';
+    channelId   = larkReceiveId;
     mentionsRaw = process.env.LARK_MENTIONS || '[]';
   } else {
-    throw new Error('sentry-triage: configure SLACK_CHANNEL (for Slack) or LARK_RECEIVE_ID (for Lark) in the ENV tab.');
+    throw new Error(
+      'sentry-triage has issues to dispatch but no destination configured. ' +
+      'Go to Project Settings -> ENV and set ONE of:\n' +
+      '  - SLACK_CHANNEL=#your-alerts-channel    (uses connected Slack integration)\n' +
+      '  - LARK_RECEIVE_ID=oc_xxxxxxxx           (uses connected Lark integration)\n' +
+      'The integration OAuth token gives the workflow auth, but you still need to tell it WHERE to post.'
+    );
   }
 
   let mentions;
   try { mentions = JSON.parse(mentionsRaw); } catch { mentions = []; }
   if (!Array.isArray(mentions)) mentions = [];
 
-  return `You are the dispatch_alerts node of a Sentry triage workflow. Post chat alerts using the **${toolName}** tool.
+  // ── Routing policy block ────────────────────────────────────────
+  // Two voices: a default policy (always rendered, derived from env
+  // vars) and the optional natural-language override (rendered only
+  // when DISPATCH_RULES is set). When the override exists, the
+  // agent is told to treat it as authoritative.
+  const defaultPolicyLines = [
+    `Skip any classification below severity ${threshold}.`,
+    `Channel fallback (every alert at minimum goes here): ${JSON.stringify(channelId)}`,
+  ];
+  if (preferAuthor) {
+    defaultPolicyLines.push(
+      `Author-DM enabled: when an issue has \`suspectCommits[0].authorEmail\`, FIRST call \`${lookupTool}({ email })\`. ` +
+      `If \`ok:true\`, send the alert as a DM to that user (use their id as the recipient — Slack ${'`channel`'}, Lark ${'`receive_id`'}). ` +
+      `Also still post to the channel fallback above so the team has visibility. ` +
+      `If \`ok:false\` or there's no email, channel-only.`
+    );
+  } else {
+    defaultPolicyLines.push(
+      `Author-DM disabled (ROUTING_PREFER_AUTHOR=false). Post all alerts to the channel fallback.`
+    );
+  }
+  if (highSevGroup) {
+    defaultPolicyLines.push(
+      provider === 'slack'
+        ? `High-severity escalation: on CRITICAL/HIGH, mention the Slack usergroup ${JSON.stringify(highSevGroup)} in the channel message. ` +
+          `If it's a handle (starts with @), call \`slack_list_usergroups\` once to resolve handle → id, then mention as \`<!subteam^ID>\`. ` +
+          `If it already looks like an id (starts with "S"), mention directly as \`<!subteam^${highSevGroup}>\`.`
+        : `High-severity escalation: on CRITICAL/HIGH, also send the alert to the chat/user ${JSON.stringify(highSevGroup)} (Lark receive_id).`
+    );
+  }
+  if (mentions.length > 0) {
+    defaultPolicyLines.push(`CRITICAL messages prepend: ${JSON.stringify(mentions.join(' '))}`);
+  }
+
+  const policyBlock = defaultPolicyLines.map((l, i) => `${i + 1}. ${l}`).join('\n');
 
-# Recipient
-${recipientLine}
+  const overrideBlock = dispatchRules
+    ? `\n\n# DISPATCH_RULES (override — authoritative)\nThe project has set custom routing rules. Apply these verbatim; the defaults above are only fallbacks for behavior the rules don't cover.\n\n${dispatchRules.trim()}\n`
+    : '';
 
-# Severity threshold
-Skip any issue below: ${threshold}
-(Severity order, low → high: ${SEVERITY_LEVELS.join(' < ')})
+  // ── Prompt body ─────────────────────────────────────────────────
+  return `You are the dispatch_alerts node of a Sentry triage workflow. Post chat alerts using the **${postTool}** tool (and the lookup helpers below for author routing).
 
-# Mentions
-CRITICAL messages only — prepend: ${JSON.stringify(mentions.join(' '))}
-HIGH/MEDIUM/LOW — no mentions.
+# Default routing policy
+${policyBlock}${overrideBlock}
 
-# Your judgment
+# Severity scale
+${SEVERITY_LEVELS.join(' < ')}
+
+# Tools you should use
+- \`${postTool}\` — post the message (channel id OR user/DM id for the recipient field).
+- \`${lookupTool}\` — resolve an email to a user id. **Important**: this can return \`{ ok: false }\` — handle that by falling back to channel-only, don't retry with variations of the email.
+${provider === 'slack' ? '- `slack_list_usergroups` / `slack_get_usergroup_members` — expand @group → user ids.' : ''}
+
+# Your judgment (unchanged from before)
 - Batch issues with the same culprit / metadata.filename into ONE message.
-- De-dupe near-duplicates (e.g. same error text in different paths). Mention "seen N times".
-- Keep each message short. Lead with severity in *[BRACKETS]*. Include the Sentry permalink so the on-call can click through.
+- De-dupe near-duplicates ("seen N times"). Keep messages short. Lead with severity in *[BRACKETS]*. Include Sentry permalinks.
 
-# Message format (template, adapt as needed)
+# Message format
 \`\`\`
 *[CRITICAL]* TypeError: Cannot read 'id' of undefined
 12 users hit /checkout — likely regression on r1234.
 📍 handleCheckout(checkout.ts) · 47 events
+Suspect commit: a1b2c3d4 by sarah@acme.com — "refactor checkout state"
 https://sentry.io/.../1234/
 \`\`\`
 
 # Output (outputSchema-enforced)
-
-Return ONE record per ${toolName} call you actually made (or skipped/failed).
-\`issueIds\` is an array — for batched messages it carries every issue in the group.
-\`severity\` is the highest severity in the group.
+Return ONE record per dispatch call you actually made (or skipped/failed). \`issueIds\` is an array — batched messages carry every issue in the group. \`recipient\` records who got the message (channel id, user id, or usergroup id) so the audit trail shows the routing decision.
 
 \`\`\`json
 {
   "dispatched": [
-    { "issueIds": ["1", "5", "7"], "severity": "CRITICAL", "status": "sent"${provider === 'slack' ? ', "messageTs": "1716109330.555"' : ', "messageId": "om_xxxxx"'} }
+    {
+      "issueIds": ["1", "5"],
+      "severity": "CRITICAL",
+      "status": "sent",
+      "recipient": { "kind": "user_dm", "id": "U012ABC", "label": "sarah@acme.com" }${provider === 'slack' ? ',\n      "messageTs": "1716109330.555"' : ',\n      "messageId": "om_xxxxx"'}
+    }
   ],
   "summary": { "total": 1, "sent": 1, "skipped": 0, "failed": 0 }
 }
 \`\`\`
 
-# Issues + classifications
+# Issues + classifications + suspect commits
 
-Each entry below has the Sentry issue plus the classifier's verdict + reasoning. Use both.
+Each entry has the Sentry issue, the classifier's verdict, and any suspect commits Sentry's GitHub integration could blame. **An empty \`suspectCommits\` array means the team hasn't set up Sentry's GitHub integration OR the file wasn't touched in the last 14 days** — fall back to channel-only routing in that case.
 
 \`\`\`json
 ${JSON.stringify(
@@ -128,10 +247,10 @@ ${JSON.stringify(
 \`\`\`
 
 # Rules
-- Skip below-threshold issues silently (just include them in dispatched with status="skipped"; no chat call).
-- DON'T invent severities or issue IDs. Use what's given.
+- Skip below-threshold issues silently (status="skipped"; no chat call). Include them in \`dispatched\` so the run record is complete.
+- DON'T invent severities, issue IDs, or email addresses. Only use what's in the data block above.
 - DON'T post more messages than necessary. If 5 issues are clearly one bug, post 1 message.
-- DO post if in doubt — under-paging is worse than over-paging for triage.
+- DO post if in doubt — under-paging is worse than over-paging.
 `;
 };
 

package/sentry-triage/nodes/fetch-issues-node.js

@@ -26,7 +26,21 @@
 
 import { z } from 'zod';
 import { SKILLS } from '@zibby/core';
-import { sentryListIssues } from '@zibby/skills/sentry';
+import { sentryListIssues, sentryGetIssue } from '@zibby/skills/sentry';
+
+// Per-commit shape Sentry returns under `suspectCommits[]`. We only
+// surface what the dispatch agent actually uses for routing — author
+// email (→ slack_lookup_user_by_email) + a short SHA + the commit
+// message so the agent can sanity-check "is this commit plausibly the
+// cause?". Everything else (date, repository url, etc.) is dropped to
+// keep the per-issue payload small.
+const SuspectCommitShape = z.object({
+  id: z.string().optional(),
+  shortId: z.string().optional(),
+  message: z.string().optional(),
+  authorEmail: z.string().optional(),
+  authorName: z.string().optional(),
+});
 
 const IssueShape = z.object({
   id: z.string(),
@@ -45,6 +59,11 @@ const IssueShape = z.object({
     value: z.string().optional(),
     filename: z.string().optional(),
   }).optional(),
+  // Populated by the per-issue sentryGetIssue() fetch below. Empty
+  // array when Sentry's GitHub integration can't blame the issue's
+  // stack frames to any recent commits (no integration / no code
+  // mapping / file untouched in 14 days).
+  suspectCommits: z.array(SuspectCommitShape).optional(),
 });
 
 const FetchIssuesOutputSchema = z.object({
@@ -65,10 +84,24 @@ export const fetchIssuesNode = {
       : context;
 
     const sinceMinutes = Number(state?.sinceMinutes) || 60;
+    const query = `is:unresolved is:unassigned firstSeen:-${sinceMinutes}m`;
+
+    // Surface intent BEFORE the call. Deterministic nodes don't go
+    // through an LLM that would print its reasoning, so the activity
+    // panel would otherwise just show "started" then a result count —
+    // operators have no way to tell what query ran or whether the empty
+    // result was "Sentry returned nothing" vs "we asked the wrong
+    // question". Two-line preamble fixes that without log-spam.
+    console.log(`Sentry query: ${query}`);
+    console.log(`Sort: new (firstSeen desc) · Limit: 100`);
 
     const issues = await sentryListIssues({
-      query: `is:unresolved is:unassigned firstSeen:-${sinceMinutes}m`,
-      sort: 'created',
+      query,
+      // Sentry's /projects/{org}/{project}/issues/ endpoint only accepts
+      // these sort keys: date | new | priority | freq | user. `new` sorts
+      // by firstSeen desc which matches our triage intent (newest issues
+      // surface first). `created` was wrong and made Sentry return 400.
+      sort: 'new',
       // 100 issues is the practical ceiling for a triage notification.
       // Beyond that, classify+dispatch lose signal — a "deluge" digest
       // tells the user nothing actionable. If a customer regularly
@@ -77,8 +110,55 @@ export const fetchIssuesNode = {
       limit: 100,
     });
 
+    // Always log the count + a head sample. On 0 issues this prints
+    // "Fetched 0 issues" which is the actionable signal — operator
+    // knows the query worked but there's nothing new to triage.
+    console.log(`Fetched ${issues.length} issue${issues.length === 1 ? '' : 's'} from Sentry`);
+    if (issues.length > 0) {
+      const preview = issues.slice(0, 5).map((i) => `  - ${i.shortId || i.id} [${i.level || '?'}] ${i.title || '(no title)'}`);
+      console.log(preview.join('\n'));
+      if (issues.length > 5) console.log(`  ... (${issues.length - 5} more)`);
+    }
+
+    // Enrich each issue with `suspectCommits` (author email + SHA +
+    // commit message). The /issues/ list endpoint does NOT include
+    // suspectCommits — only /issues/<id>/ does. So we do N parallel
+    // GETs to hydrate. Practical concerns:
+    //
+    //   - N is capped at 100 (the list limit above). One parallel
+    //     batch finishes in ~1-2s against sentry.io.
+    //   - Per-issue failures are swallowed (logged + empty array)
+    //     so one 404 doesn't break the entire run. The classifier
+    //     downstream doesn't NEED suspectCommits to function — it's
+    //     a routing hint, not a classification input.
+    //   - When the customer hasn't installed Sentry's GitHub
+    //     integration OR hasn't configured Code Mappings, every
+    //     issue will come back with suspectCommits=[]. That's the
+    //     designed-for steady state; dispatch agent falls back to
+    //     channel-only routing.
+    const enriched = await Promise.all(
+      issues.map(async (issue) => {
+        try {
+          const detail = await sentryGetIssue(issue.id);
+          const sc = (detail?.suspectCommits || []).map((c) => ({
+            id: c.id,
+            shortId: c.shortId || (c.id ? String(c.id).slice(0, 7) : undefined),
+            message: c.message,
+            authorEmail: c.author?.email,
+            authorName: c.author?.name,
+          }));
+          return { ...issue, suspectCommits: sc };
+        } catch (err) {
+          console.warn(`  · suspectCommits fetch failed for ${issue.shortId || issue.id}: ${err.message}`);
+          return { ...issue, suspectCommits: [] };
+        }
+      })
+    );
+    const withAuthor = enriched.filter((i) => (i.suspectCommits || []).some((c) => c.authorEmail)).length;
+    console.log(`Hydrated suspectCommits — ${withAuthor}/${enriched.length} issue(s) have an identifiable author.`);
+
     return {
-      issues,
+      issues: enriched,
       fetchedAt: new Date().toISOString(),
     };
   },

package/sentry-triage/package.json

@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@zibby/core": "^0.5.1",
-    "@zibby/skills": "^0.1.25",
+    "@zibby/skills": "^0.1.26",
     "zod": "^3.23.0"
   },
   "devDependencies": {