@zibby/workflow-templates 0.7.1 → 0.9.0

package/index.js

@@ -173,7 +173,7 @@ export const TEMPLATES = {
     description: 'Reusable child workflow — posts a structured Block Kit alert to a Slack channel. Dispatched by other workflows (Sentry triage, autofix, incident) via sub-graph.',
     path: join(__dirname, 'notify-slack'),
     defaultSlug: 'alert-slack',
-    deps: { zod: '^3.23.0' },
+    deps: { zod: '^3.23.0 || ^4.0.0', '@zibby/skills': '^0.1.28' },
     features: [
       'Single-node, no LLM — deterministic ~500ms post',
       'Block Kit message with severity-coded color + emoji',
@@ -215,7 +215,7 @@ export const TEMPLATES = {
     description: 'Reusable child workflow — posts a structured Interactive Card to a Lark / Feishu chat. Dispatched by other workflows via sub-graph.',
     path: join(__dirname, 'notify-lark'),
     defaultSlug: 'alert-lark',
-    deps: { zod: '^3.23.0' },
+    deps: { zod: '^3.23.0 || ^4.0.0', '@zibby/skills': '^0.1.28' },
     features: [
       'Single-node, no LLM',
       'Lark Interactive Card with severity template (red/orange/yellow/grey)',

package/notify-lark/package.json

@@ -10,7 +10,8 @@
   },
   "dependencies": {
     "@zibby/core": "^0.5.1",
-    "zod": "^3.23.0"
+    "@zibby/skills": "^0.1.28",
+    "zod": "^3.23.0 || ^4.0.0"
   },
   "devDependencies": {
     "vitest": "^2.1.5"

package/notify-slack/package.json

@@ -10,7 +10,8 @@
   },
   "dependencies": {
     "@zibby/core": "^0.5.1",
-    "zod": "^3.23.0"
+    "@zibby/skills": "^0.1.28",
+    "zod": "^3.23.0 || ^4.0.0"
   },
   "devDependencies": {
     "vitest": "^2.1.5"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/workflow-templates",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "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",

package/sentry-triage/graph.mjs

@@ -1,28 +1,35 @@
 /**
  * sentry-triage — parent workflow. Hourly Sentry issue triage.
  *
- * Pipeline (3 LLM nodes, end-to-end agent-driven):
+ * Agent-driven first. Nodes are LLM agents by default — because nobody
+ * hand-edits these in practice, they point an AGENT at the prompt and say
+ * "make billing always critical" / "page #oncall after 9pm". A deterministic
+ * for-loop can't be told that in English; an agent can. We drop to
+ * deterministic ONLY where it genuinely makes sense — a pure mechanical step
+ * with zero judgment and nothing a customer would ever want to tune.
  *
- *   fetch_issues    (LLM + SKILLS.SENTRY)        → list recent unresolved issues
+ *   fetch_issues    (deterministic + SKILLS.SENTRY) → pull recent unresolved/
+ *                                                      unassigned issues + suspect
+ *                                                      commits. Pure API pull, no
+ *                                                      judgment, nothing to tune →
+ *                                                      the one place a for-loop
+ *                                                      wins (faster, free, no
+ *                                                      hallucinated queries).
  *        ↓
- *   classify        (LLM, no tools)              → label NOISE/LOW/MEDIUM/HIGH/CRITICAL
+ *   classify        (LLM agent)                     → label NOISE…CRITICAL. Stays
+ *                                                      an agent BECAUSE the rubric
+ *                                                      is customer-tunable, and
+ *                                                      they tune it by having an
+ *                                                      agent edit this prompt — not
+ *                                                      by touching code.
  *        ↓
- *   dispatch_alerts (LLM + SKILLS.CHAT_NOTIFY)   → batch + post to Slack OR Lark for
- *                                                   issues ≥ SEVERITY_THRESHOLD
+ *   dispatch_alerts (LLM agent + SKILLS.CHAT_NOTIFY) → one human-voice digest;
+ *                                                      routing is the user's
+ *                                                      (DISPATCH_RULES) to own.
  *
- * Why all three nodes are LLM (not deterministic for-loops):
- *   - At hourly cadence with ≤20 issues/run, LLM cost is $1.50–$32/mo
- *     depending on model. Trivial relative to Sentry / Slack subscriptions.
- *   - LLM dispatch can BATCH related issues (5 errors in /checkout/ →
- *     1 consolidated message) and DE-DUP near-duplicates. A
- *     deterministic for-loop can't.
- *   - outputSchema enforcement guarantees every above-threshold issue
- *     either gets a "sent" record or an explicit "failed/skipped" —
- *     no silent drops.
- *
- * Customize prompts: each node's prompt lives in its own module under
- * nodes/. Override per-deploy by editing the file or by passing a
- * custom prompt string via inputSchema (planned).
+ * Also: LLM dispatch BATCHES related issues into one message and DE-DUPs —
+ * a for-loop can't. outputSchema enforcement → every above-threshold issue
+ * gets a "sent" or explicit "skipped/failed" record; no silent drops.
  */
 
 import { WorkflowAgent, WorkflowGraph } from '@zibby/core';

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

@@ -61,16 +61,22 @@ 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']),
+  // Every field below a skipped/failed record can't populate is nullish
+  // (not optional) on purpose: the LLM emits an explicit `null` rather than
+  // omitting the key, and `.optional()` rejects null → ZodError → the whole
+  // dispatch node fails even though it did exactly the right thing (skip
+  // below-threshold). So recipient (no send → null), messageTs/messageId (no
+  // message id), and detail all tolerate null.
   // 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(),
+    kind: z.enum(['channel', 'user_dm', 'usergroup']).nullish(),
+    id: z.string().nullish(),
+    label: z.string().nullish(),
+  }).nullish(),
+  messageTs: z.string().nullish(),  // Slack
+  messageId: z.string().nullish(),  // Lark
+  detail: z.string().nullish(),
 });
 
 const DispatchAlertsOutputSchema = z.object({
@@ -85,9 +91,23 @@ const DispatchAlertsOutputSchema = z.object({
 
 const SEVERITY_ORDER = ['NOISE', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
 
+// Turn the trigger's sinceMinutes into a phrase a human would actually say,
+// so the digest can open with the time span ("past hour", "last 3 days")
+// instead of leaving the reader to guess how much history this covers.
+function humanWindow(min) {
+  const m = Number(min);
+  if (!m || m < 1) return 'recently';
+  if (m < 90) return `the past ${Math.round(m)} minutes`;
+  if (m < 1440) return `the past ${Math.round(m / 60)} hours`;
+  const days = Math.round(m / 1440);
+  return days === 1 ? 'the past day' : `the past ${days} days`;
+}
+
 const DISPATCH_PROMPT = (state = {}) => {
   const issues = state?.fetch_issues?.issues || [];
   const classifications = state?.classify?.classifications || [];
+  const windowLabel = humanWindow(state?.sinceMinutes);
+  const fetchedAt = state?.fetch_issues?.fetchedAt || '';
 
   const threshold       = process.env.SEVERITY_THRESHOLD       || 'MEDIUM';
   const slackChannel    = process.env.SLACK_CHANNEL            || '';
@@ -97,8 +117,8 @@ const DISPATCH_PROMPT = (state = {}) => {
   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.
+  // The three "nothing to do this run" cases — keep the run green without a
+  // model round-trip or forcing channel setup.
   const minSeverityRank = SEVERITY_ORDER.indexOf(threshold);
   const aboveThreshold = minSeverityRank < 0
     ? classifications
@@ -147,50 +167,95 @@ Return this exact JSON envelope and call no tools:
   try { mentions = JSON.parse(mentionsRaw); } catch { mentions = []; }
   if (!Array.isArray(mentions)) mentions = [];
 
-  // ── 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.`
-    );
+  // ── Routing policy ──────────────────────────────────────────────
+  // Routing is the USER'S to own. We give the agent only the bare facts it
+  // always needs; everything past that is policy:
+  //   - If DISPATCH_RULES is set, those rules ARE the policy. Hand over the
+  //     facts + the rules and get out of the way — do NOT also stack the
+  //     built-in author-DM / usergroup defaults on top. The user chose to
+  //     drive this themselves; don't fight them.
+  //   - With no DISPATCH_RULES, fall back to sensible built-in defaults
+  //     (channel post + opt-in author-DM / escalation from env vars).
+  const facts = [`Skip anything classified below ${threshold}.`];
+  // Only mention a channel when one is actually configured — never render a
+  // "post here" line pointing at an empty value.
+  if (channelId) facts.push(`Channel configured: ${JSON.stringify(channelId)} (${provider}).`);
+  facts.push(`Post with the \`${postTool}\` tool.`);
+
+  let policyLines;
+  let overrideBlock = '';
+  if (dispatchRules) {
+    policyLines = facts.concat([
+      'Past the facts above, follow YOUR rules below — who gets paged / DM\'d, where, when, what to suppress. They override anything the built-in defaults would have implied.',
+    ]);
+    overrideBlock = `\n\n# Your routing rules (authoritative)\n${dispatchRules.trim()}\n`;
   } 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(' '))}`);
+    policyLines = [...facts];
+    if (channelId) policyLines.push('Every alert at minimum goes to the channel above.');
+    if (preferAuthor) {
+      policyLines.push(
+        `Author-DM: when an issue has \`suspectCommits[0].authorEmail\`, FIRST call \`${lookupTool}({ email })\`. ` +
+        `If \`ok:true\`, DM that user (their id as the recipient) AND still post the channel for team visibility. ` +
+        `If \`ok:false\` or no email, channel-only.`
+      );
+    }
+    if (highSevGroup) {
+      policyLines.push(
+        provider === 'slack'
+          ? `On CRITICAL/HIGH, mention the Slack usergroup ${JSON.stringify(highSevGroup)} in the channel message. ` +
+            `Handle (@…): call \`slack_list_usergroups\` once to resolve → id, mention as \`<!subteam^ID>\`. Id (S…): use \`<!subteam^${highSevGroup}>\`.`
+          : `On CRITICAL/HIGH, also send to ${JSON.stringify(highSevGroup)} (Lark receive_id).`
+      );
+    }
+    if (mentions.length > 0) policyLines.push(`CRITICAL messages prepend: ${JSON.stringify(mentions.join(' '))}`);
   }
 
-  const policyBlock = defaultPolicyLines.map((l, i) => `${i + 1}. ${l}`).join('\n');
+  const policyBlock = policyLines.map((l, i) => `${i + 1}. ${l}`).join('\n');
+
+  // Slack → a Block Kit card (rich, scannable, clickable View buttons). Lark →
+  // the human-voice text digest (no Block Kit there). The JUDGMENT is identical
+  // either way — the one-line read, the grouping, what's urgent — only the
+  // rendering differs by provider.
+  const writeGuide = provider === 'slack'
+    ? `# How to report it — like a human on-call, in TWO messages
+Don't cram everything into one card. Report the way a sharp on-call engineer actually would: FIRST a quick human heads-up so people get the situation in ONE glance, THEN the detailed board. So you call \`slack_post_message\` TWICE.
+
+## Message 1 — greeting + the headline (text only, NO blocks)
+\`slack_post_message({ channel, text })\` with just text. Open with a greeting ("👋 Hey team"). Say the ONE thing that matters most — the headline STORY, not a count ("billing/auth is broken in 3 spots, almost certainly one deploy"). Page plainly if something needs it ("on-call should grab these now"). End pointing down at the list ("Full breakdown 👇"). 2–4 sentences, sounds like a person typed it — THIS is the "one glance and you get it" message.
+Example:
+"👋 *Hey team — Sentry triage, ${windowLabel}.* Headline: *billing/auth is broken in 3 places* (formatSubscription, webhook timeout, Unauthorized) — almost certainly one bad deploy, on-call should grab these now. Plus a cluster of undefined-ref fatals (module/import wiring) and the usual synthetic test noise. Full breakdown 👇"
+
+## Message 2 — the Block Kit board (blocks)
+Then \`slack_post_message({ channel, text, blocks })\` — the scannable card. \`text\` = one-line fallback. \`blocks\`, real Block Kit objects only:
+1. \`header\` — title with the window:
+{ "type": "header", "text": { "type": "plain_text", "text": "🚨 Sentry Triage — ${windowLabel}", "emoji": true } }
+2. \`context\` — ONE-line read of the window (counts + the shape; your call):
+{ "type": "context", "elements": [{ "type": "mrkdwn", "text": "*${aboveThreshold.length}* at *${threshold}+* of ${issues.length} · <your one-line read of what's going on>" }] }
+3. Per group — group by ROOT CAUSE or severity (your call; the header says what connects them). A divider, a section header, then per issue a section (with a View button) FOLLOWED BY a one-line context note:
+{ "type": "divider" }
+{ "type": "section", "text": { "type": "mrkdwn", "text": "🔴 *CRITICAL — billing/auth, page on-call*" } }
+{ "type": "section", "text": { "type": "mrkdwn", "text": "*<title>* — <where> · <the one metric that matters>" }, "accessory": { "type": "button", "text": { "type": "plain_text", "text": "View →", "emoji": true }, "url": "<permalink>", "action_id": "v_<issueId>" } }
+{ "type": "context", "elements": [{ "type": "mrkdwn", "text": "↳ <one short useful detail>" }] }
+   The context line is grey small text under the issue — ~6-12 words of a CONCRETE fact pulled straight from the issue's data, NEVER a vague guess. Use what's actually there: the error value (\`metadata.value\`, e.g. "Cannot read 'plan' of undefined"), the culprit fn/file, a real suspect commit ("a1b2c3 by sarah@"), or first/last-seen spread ("first seen 3d ago, 1.6k/h now"). BANNED — filler with no information: "could exacerbate latency", "potential breach attempt", "needs attention", "affects capacity". If you don't have a concrete fact for an issue, OMIT its context line entirely. Never speculate to fill space.
+4. final \`context\` — what needs a human now vs. just FYI.
 
-  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`
-    : '';
+Rules:
+- TWO slack_post_message calls: the text heads-up FIRST, then the blocks card. Both go to the same channel.
+- header text is plain_text; section & context text is mrkdwn (*bold*, \`code\`, <url|label>).
+- One tight line per issue in the section text; the button carries the link — don't also inline it.
+- Group dots: 🔴 CRITICAL · 🟠 HIGH · 🟡 MEDIUM. Mention a suspect commit only if there genuinely is one.
+- Below-threshold (skipped) issues do NOT appear in the blocks at all.
+- Real Block Kit types only (header / section / divider / context + button accessory) — don't invent types.`
+    : `# How to write it — talk like a human, not a report generator
+You're a teammate dropping a note in the channel, not a dashboard. Open with a real sentence about ${windowLabel} (time span baked in). Group issues that are the same story (same file/area/deploy) and SAY why they're connected. Per issue: what broke, the one number that matters, and the link. End straight: what needs a human now vs. FYI. No "*[SEVERITY]*" form blocks, no "no suspect commits" filler.
+
+Example tone:
+Over ${windowLabel} it's been mostly quiet, but billing's having a bad time — three errors on the checkout/subscription path, almost certainly the same deploy: \`formatSubscription is not a function\` (BillingPage, 1 user), \`POST /billing/webhook\` timing out (6×), \`countWorkflowExecutionsInPeriod\` 15× in usage-limiter. <links> Whoever shipped the billing refactor should roll back. Rest is synthetic test traffic — ignoring it.`;
 
   // ── 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).
 
-# Default routing policy
+# Routing
 ${policyBlock}${overrideBlock}
 
 # Severity scale
@@ -201,18 +266,13 @@ ${SEVERITY_LEVELS.join(' < ')}
 - \`${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 ("seen N times"). Keep messages short. Lead with severity in *[BRACKETS]*. Include Sentry permalinks.
+# Context for THIS run — weave it in, don't make the reader guess
+- Time span: every issue below is unresolved + unassigned from **${windowLabel}**${fetchedAt ? ` (pulled ${fetchedAt})` : ''}. OPEN with the span so people know what they're looking at — "Past hour was quiet…", "Over the last 30 days…". Never leave it out; a reader who doesn't know the window can't judge urgency.
+- Volume: ${aboveThreshold.length} issue(s) at or above ${threshold}, out of ${issues.length} fetched. Mention the count only if it helps the read.
 
-# 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/
-\`\`\`
+${writeGuide}
+
+A standalone CRITICAL that should page someone can get its OWN message. Routing still applies: digest → channel; if author-DM is on and an issue has a known author, also DM that person a short note about just theirs; mention the escalation group on CRITICAL/HIGH.
 
 # Output (outputSchema-enforced)
 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.
@@ -233,7 +293,7 @@ Return ONE record per dispatch call you actually made (or skipped/failed). \`iss
 
 # Issues + classifications + suspect commits
 
-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.
+Each entry is a Sentry issue with the classify agent's \`classification\` (severity + reasoning) 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** — just don't mention a commit in that case.
 
 \`\`\`json
 ${JSON.stringify(
@@ -247,9 +307,10 @@ ${JSON.stringify(
 \`\`\`
 
 # Rules
-- Skip below-threshold issues silently (status="skipped"; no chat call). Include them in \`dispatched\` so the run record is complete.
+- The digest is usually ONE channel message → ONE \`sent\` record whose \`issueIds\` lists every issue you mentioned in it. An extra author-DM or a standalone-CRITICAL message each get their own record too.
+- Skipped (below-threshold) issues: roll them into a single \`skipped\` record (issueIds = all of them) — no chat call, no per-issue noise — so the run record stays complete without bloating it.
 - 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.
+- DON'T pad the digest. If the hour is quiet, a two-line message is the right answer — don't manufacture structure.
 - DO post if in doubt — under-paging is worse than over-paging.
 `;
 };

package/browser-test-automation/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +0,0 @@
-{"version":"4.1.5","results":[[":__tests__/preflight-early-exit.test.mjs",{"duration":6.5747499999999945,"failed":false}]]}

package/code-analysis/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +0,0 @@
-{"version":"4.1.5","results":[[":nodes/__tests__/middleware.integration.test.js",{"duration":0,"failed":true}],[":nodes/__tests__/finalizeNode.test.js",{"duration":8.396791000000007,"failed":false}]]}