@zibby/workflow-templates 0.3.0 → 0.4.2

package/notify-slack/nodes/notify-slack-node.js

@@ -0,0 +1,268 @@
+/**
+ * notify-slack node — deterministic, no LLM.
+ *
+ * Posts a single Block Kit message to Slack via chat.postMessage. We
+ * don't use an LLM for this because:
+ *   - The output is fully specified by the input (no decisions to make).
+ *   - Notifications need to be fast (<500ms) and predictable.
+ *   - LLM cost on every alert is silly when the parent has already
+ *     decided the severity + body.
+ *
+ * Auth: pulls the Slack OAuth token via @zibby/core's
+ * `resolveIntegrationToken('slack')`. Same path slackSkill uses for the
+ * LLM-tool variant. Tokens are cached per-process for ~50min so a
+ * parent dispatching 20 alerts in a row only pays one round-trip to the
+ * backend integrations endpoint.
+ *
+ * Severity → color + decoration:
+ *   low      → grey   (#7f8c8d), no mentions
+ *   medium   → yellow (#f1c40f), no mentions
+ *   high     → orange (#e67e22), mentions appended if caller provided
+ *   critical → red    (#c0392b), mentions appended (caller usually
+ *                                supplies <!subteam^...> or @here)
+ *
+ * Severity emoji ⏺ in the header keeps the message scannable even when
+ * Slack collapses attachment colors on mobile.
+ *
+ * Failure modes (no retry — sub-graph caller handles retries):
+ *   - Slack token not connected → throws "slack is not connected" via
+ *     resolveIntegrationToken. Caller sees SUBGRAPH_NOT_FOUND-shaped err.
+ *   - Channel not found → Slack API returns ok=false with
+ *     error="channel_not_found". We surface a clear typed error.
+ *   - Bot not in channel → error="not_in_channel". Same.
+ *   - Network blip → fetch throws. Parent's onComplete sees a failed
+ *     execution row and can re-dispatch.
+ */
+
+import { z } from 'zod';
+import { SKILLS } from '@zibby/core';
+import { resolveIntegrationToken } from '@zibby/core/backend-client.js';
+// reportToBlockKit lives in @zibby/skills (universal renderer for any
+// destination). When the parent passes a `report` object, we delegate
+// rendering entirely; the legacy severity/title/body path is unchanged
+// for sentry-triage and other callers still on the simple shape.
+import { reportToBlockKit } from '@zibby/skills/report';
+
+const SEVERITY_COLORS = Object.freeze({
+  low:      '#7f8c8d',
+  medium:   '#f1c40f',
+  high:     '#e67e22',
+  critical: '#c0392b',
+});
+
+const SEVERITY_EMOJI = Object.freeze({
+  low:      ':white_circle:',
+  medium:   ':large_yellow_circle:',
+  high:     ':large_orange_circle:',
+  critical: ':rotating_light:',
+});
+
+const NotifySlackOutputSchema = z.object({
+  delivered: z.boolean().describe('true if chat.postMessage returned ok'),
+  channel: z.string().describe('Channel id Slack actually posted to (canonical form).'),
+  messageTs: z.string().optional().describe('Slack message timestamp — use as thread_ts for follow-ups.'),
+  blocksCount: z.number().int().optional().describe('Block count in the rendered message — diagnostic only.'),
+});
+
+/**
+ * Build the Slack Block Kit `attachments[0].blocks` payload from the
+ * input. Exposed for unit tests so we can pin the rendered shape
+ * without going through fetch.
+ */
+export function buildSlackBlocks(input) {
+  const {
+    severity = 'medium',
+    title,
+    body,
+    sentryLink,
+    affectedUsers,
+    events,
+    release,
+    firstSeen,
+    codeSnippet,
+    actionUrl,
+    actionLabel,
+    mentions,
+  } = input;
+
+  const emoji = SEVERITY_EMOJI[severity] || SEVERITY_EMOJI.medium;
+  const blocks = [];
+
+  // Header — severity emoji + uppercased severity + title.
+  blocks.push({
+    type: 'header',
+    text: {
+      type: 'plain_text',
+      // Slack header text caps at 150 chars; truncate defensively.
+      text: `${emoji} ${severity.toUpperCase()}  ${title}`.slice(0, 150),
+      emoji: true,
+    },
+  });
+
+  // Metadata fields (2-column grid). Only rendered when at least one
+  // optional field is present — keeps the alert tight for "headline-only" messages.
+  const fields = [];
+  if (typeof affectedUsers === 'number') {
+    fields.push({ type: 'mrkdwn', text: `*Users affected:*\n${affectedUsers}` });
+  }
+  if (typeof events === 'number') {
+    fields.push({ type: 'mrkdwn', text: `*Events:*\n${events}` });
+  }
+  if (release) {
+    fields.push({ type: 'mrkdwn', text: `*Release:*\n\`${release}\`` });
+  }
+  if (firstSeen) {
+    fields.push({ type: 'mrkdwn', text: `*First seen:*\n${firstSeen}` });
+  }
+  if (fields.length > 0) {
+    blocks.push({ type: 'section', fields });
+  }
+
+  // Body — mrkdwn-rendered. Empty body still posts (header alone is OK).
+  if (body && body.trim().length > 0) {
+    blocks.push({
+      type: 'section',
+      text: { type: 'mrkdwn', text: body },
+    });
+  }
+
+  // Code snippet — fenced triple-backtick block. Slack treats these as
+  // monospaced when posted inside a mrkdwn section.
+  if (codeSnippet) {
+    blocks.push({
+      type: 'section',
+      text: { type: 'mrkdwn', text: '```' + codeSnippet + '```' },
+    });
+  }
+
+  // Action buttons.
+  const actions = [];
+  if (sentryLink) {
+    actions.push({
+      type: 'button',
+      text: { type: 'plain_text', text: 'Open in Sentry' },
+      url: sentryLink,
+      style: 'primary',
+    });
+  }
+  if (actionUrl && actionLabel) {
+    actions.push({
+      type: 'button',
+      text: { type: 'plain_text', text: actionLabel.slice(0, 40) },
+      url: actionUrl,
+    });
+  }
+  if (actions.length > 0) {
+    blocks.push({ type: 'actions', elements: actions });
+  }
+
+  // Mentions go into a small-text context block at the bottom so they
+  // don't dominate the visual. Caller-supplied strings are joined with
+  // spaces. We don't validate the mention syntax — Slack will silently
+  // ignore malformed ones.
+  if (Array.isArray(mentions) && mentions.length > 0) {
+    blocks.push({
+      type: 'context',
+      elements: [{ type: 'mrkdwn', text: mentions.join(' ') }],
+    });
+  }
+
+  return blocks;
+}
+
+/**
+ * Post the message via Slack's chat.postMessage. Exposed for tests so
+ * we can stub fetch + assert payload shape without invoking
+ * resolveIntegrationToken.
+ */
+export async function postToSlack({ token, channel, blocks, text }) {
+  // `text` is the plain-text fallback shown in notifications / when
+  // blocks can't render. Slack recommends ALWAYS setting it.
+  const payload = { channel, blocks, text };
+  const res = await fetch('https://slack.com/api/chat.postMessage', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json; charset=utf-8',
+    },
+    body: JSON.stringify(payload),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!data.ok) {
+    const err = new Error(`Slack chat.postMessage failed: ${data.error || `http ${res.status}`}`);
+    err.code = data.error || 'unknown';
+    err.status = res.status;
+    throw err;
+  }
+  return { channel: data.channel, ts: data.ts };
+}
+
+export const notifySlackNode = {
+  name: 'notify_slack',
+  // Declares the Slack integration as a hard requirement so the
+  // marketplace card surfaces "Slack required" via the backend's
+  // automatic deriveRequiredIntegrations(). The MCP slack server tools
+  // aren't actually invoked here (custom-execute path), but the
+  // declaration is the canonical way to wire the marketplace gate.
+  skills: [SKILLS.SLACK],
+  outputSchema: NotifySlackOutputSchema,
+  // 15s — chat.postMessage is fast, and we want to fail-out quick if
+  // Slack is degraded so the parent's sync-dispatch doesn't hang.
+  timeout: 15 * 1000,
+  execute: async (context) => {
+    // Custom-execute gets either the merged state object or the new
+    // {state, agent, ...} context wrapper. Normalize to a plain state.
+    const state = (context?.state && typeof context.state.getAll === 'function')
+      ? context.state.getAll()
+      : context;
+
+    const channel = state.channel;
+    if (!channel) {
+      throw new Error('notify-slack: input.channel is required');
+    }
+    if (!state.report && !state.title) {
+      throw new Error('notify-slack: input.title is required when input.report is absent');
+    }
+
+    // Resolve the bot token. The cache inside resolveIntegrationToken
+    // means this is a single HTTP RTT the first time per process; later
+    // dispatches in the same Fargate task are zero-cost.
+    const { token } = await resolveIntegrationToken('slack');
+
+    // Two rendering paths:
+    //   1. Rich `report` object (digest workflows like
+    //      ai-spend-weekly-digest) → reportToBlockKit produces the full
+    //      structured card. The plain-text fallback is sourced from
+    //      report.title (best summary for mobile push).
+    //   2. Legacy severity/title/body shape (sentry-triage et al.) →
+    //      buildSlackBlocks renders the simple alert card.
+    //
+    // The two paths are mutually exclusive at runtime; `report` wins
+    // if both are present (a misconfiguration the parent shouldn't do,
+    // but we resolve it predictably rather than mixing the outputs).
+    let blocks;
+    let text;
+    if (state.report && typeof state.report === 'object') {
+      blocks = reportToBlockKit(state.report);
+      const title = state.report.title || 'Report';
+      const headline = state.report.headline?.primary
+        ? `: ${state.report.headline.primary}`
+        : '';
+      text = `${title}${headline}`.slice(0, 200);
+    } else {
+      blocks = buildSlackBlocks(state);
+      // Plain-text fallback — Slack renders this in mobile push
+      // notifications when blocks are absent. Severity + title is the
+      // most useful summary in <100 chars.
+      text = `${(state.severity || 'medium').toUpperCase()}: ${state.title}`.slice(0, 200);
+    }
+
+    const result = await postToSlack({ token, channel, blocks, text });
+    return {
+      delivered: true,
+      channel: result.channel,
+      messageTs: result.ts,
+      blocksCount: blocks.length,
+    };
+  },
+};

package/notify-slack/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "notify-slack",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Post a structured alert to a Slack channel — child workflow, dispatched by parent workflows (Sentry triage / autofix / incident / etc.) via sub-graph.",
+  "main": "graph.mjs",
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@zibby/core": "^0.5.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.5"
+  }
+}

package/notify-slack/state.js

@@ -0,0 +1,112 @@
+/**
+ * notify-slack — three-schema state model.
+ *
+ * Designed to be invoked as a sub-graph child from any parent workflow
+ * that wants to fan-out alerts to Slack. The shape is intentionally
+ * provider-neutral on the wire (severity / title / body / link / users)
+ * so that notify-lark can accept the SAME inputs without the parent
+ * having to branch on which notifier it's dispatching to.
+ *
+ * Three schemas:
+ *   - notifySlackInputSchema   — payload from the parent's
+ *                                `dispatchSubgraph('notify-slack', { input: … })`
+ *   - notifySlackContextSchema — runner-injected fields + node outputs
+ *   - notifySlackStateSchema   — merge of the two (tests + tooling)
+ */
+
+import { z } from 'zod';
+
+export const SEVERITIES = /** @type {const} */ (['low', 'medium', 'high', 'critical']);
+
+// ── Parent-supplied payload ────────────────────────────────────────────
+// Keep this minimal + provider-neutral. Anything Slack-specific (channel
+// id format, Block Kit, mention strings) is RESOLVED inside the node,
+// not declared on the inputSchema.
+export const notifySlackInputSchema = z.object({
+  severity: z.enum(SEVERITIES)
+    .default('medium')
+    .describe('Alert severity. Drives color + mention strategy.'),
+
+  // Required in legacy-mode (severity/title/body alerts from sentry-triage
+  // and friends). In rich-mode (when `report` is set), title is sourced
+  // from `report.title` so the top-level field is optional. The execute
+  // path enforces "at least one source of title" at runtime.
+  title: z.string().min(1).max(300).optional()
+    .describe('Short one-line headline (renders in the Slack header). Required when `report` is absent.'),
+
+  body: z.string().max(3000).optional()
+    .describe('Body text. Supports Slack mrkdwn (e.g. *bold*, `code`, <url|text>).'),
+
+  channel: z.string().min(1).max(100)
+    .describe('Target channel ID (C012345) or #channel-name. Provided by the parent at dispatch.'),
+
+  // ── Sentry-flavored optional context — used to render rich blocks
+  //    when the alert originates from a Sentry workflow. Other workflows
+  //    can ignore these.
+  sentryLink: z.string().url().optional()
+    .describe('Sentry issue/event URL. Adds an "Open in Sentry" button.'),
+
+  affectedUsers: z.number().int().min(0).optional()
+    .describe('Count of users hit by this issue (rendered in the fields block).'),
+
+  events: z.number().int().min(0).optional()
+    .describe('Total event count for this issue.'),
+
+  release: z.string().max(120).optional()
+    .describe('Release/version tag this error appeared in.'),
+
+  firstSeen: z.string().optional()
+    .describe('ISO timestamp or human-friendly "N min ago".'),
+
+  codeSnippet: z.string().max(2000).optional()
+    .describe('Optional code block to render verbatim (e.g. the throwing line + context).'),
+
+  // Action button — optional, opens a URL when clicked.
+  actionUrl: z.string().url().optional()
+    .describe('Secondary URL (e.g. PR link). Renders as a non-primary button next to "Open in Sentry".'),
+  actionLabel: z.string().max(40).optional()
+    .describe('Label for the secondary action button (e.g. "View PR").'),
+
+  // ── Mentions — Slack-specific syntax provided by the caller. Parent
+  //    decides who to mention based on severity (e.g. <!subteam^S0...>
+  //    for critical, <@U_USERID> for the deploy author).
+  mentions: z.array(z.string().max(60))
+    .max(20)
+    .optional()
+    .describe('Slack mention strings appended to the context block, e.g. ["<!here>", "<@U123>"].'),
+
+  // Idempotency: if the parent retries dispatch (or two parents dispatch
+  // the same alert), we want at most ONE Slack post. ts is returned in
+  // the output for thread replies later.
+  idempotencyKey: z.string().max(128).optional()
+    .describe('Caller-supplied dedup key. The node still posts; idempotency is the parent\'s job today.'),
+
+  // ── Rich-report mode ──────────────────────────────────────────────
+  // When `report` is present, the node renders the report-object via
+  // reportToBlockKit() and IGNORES severity/title/body/sentryLink/etc.
+  // (those legacy fields are exclusively for the simple-alert path
+  // used by sentry-triage et al.).
+  //
+  // Schema validation is intentionally permissive here — the contract
+  // lives in @zibby/skills's reportObjectSchema. We declare it as a
+  // free-form object on the wire so old runtimes that don't know about
+  // the field don't fail validation, and the actual structure is
+  // validated by reportToBlockKit at render time. New consumers should
+  // import reportObjectSchema from @zibby/skills for tighter typing.
+  report: z.record(z.any()).optional()
+    .describe('Rich report-object (see @zibby/skills/report). When set, supersedes severity/title/body — the node renders a full Block-Kit card.'),
+});
+
+export const notifySlackContextSchema = z.object({
+  // Node outputs land here keyed by node name.
+  notify_slack: z.object({
+    delivered: z.boolean(),
+    channel: z.string(),
+    messageTs: z.string().optional(),
+    blocksCount: z.number().int().optional(),
+  }).optional()
+    .describe('Output of the notify_slack node — set after dispatch completes.'),
+});
+
+export const notifySlackStateSchema =
+  notifySlackInputSchema.merge(notifySlackContextSchema);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zibby/workflow-templates",
-  "version": "0.3.0",
-  "description": "Built-in workflow templates for Zibby — browser-test-automation, code-analysis, generate-test-cases. Carved out of @zibby/core@0.4.6 so the engine ships without scaffolding payload.",
+  "version": "0.4.2",
+  "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",
   "exports": {
@@ -15,6 +15,16 @@
     "./code-analysis/*": "./code-analysis/*",
     "./generate-test-cases": "./generate-test-cases/graph.mjs",
     "./generate-test-cases/*": "./generate-test-cases/*",
+    "./notify-slack": "./notify-slack/graph.mjs",
+    "./notify-slack/*": "./notify-slack/*",
+    "./notify-lark": "./notify-lark/graph.mjs",
+    "./notify-lark/*": "./notify-lark/*",
+    "./notify-notion": "./notify-notion/graph.mjs",
+    "./notify-notion/*": "./notify-notion/*",
+    "./sentry-triage": "./sentry-triage/graph.mjs",
+    "./sentry-triage/*": "./sentry-triage/*",
+    "./ai-spend-weekly-digest": "./ai-spend-weekly-digest/graph.mjs",
+    "./ai-spend-weekly-digest/*": "./ai-spend-weekly-digest/*",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -42,6 +52,10 @@
     "browser-test-automation/",
     "code-analysis/",
     "generate-test-cases/",
+    "notify-slack/",
+    "notify-lark/",
+    "notify-notion/",
+    "sentry-triage/",
     "index.js",
     "register-nodes.js",
     "global-setup.js",
@@ -57,7 +71,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.88.0",
-    "@zibby/agent-workflow": "^0.4.1",
+    "@zibby/agent-workflow": "^0.4.2",
     "axios": "^1.15.0",
     "handlebars": "^4.7.9",
     "zod": "^3.23.0 || ^4.0.0"

package/sentry-triage/graph.mjs

@@ -0,0 +1,81 @@
+/**
+ * sentry-triage — parent workflow.
+ *
+ * Pipeline:
+ *
+ *   fetch_issues   (LLM + SKILLS.SENTRY)
+ *        ↓
+ *   filter_noise   (pure JS regex pre-filter — kills ~80% of LLM cost)
+ *        ↓
+ *   classify       (LLM — assigns CRITICAL/HIGH/MEDIUM/LOW/NOISE per issue)
+ *        ↓
+ *   dispatch_alerts (custom execute — sub-graphs to notify-slack OR notify-lark
+ *                    per issue at or above severityThreshold)
+ *
+ * Sub-graph dispatch: each "real" alert fans out to ONE notify-* child
+ * workflow (configurable per deploy via state.notifyWorker). Failures
+ * on individual alerts don't kill the triage run — failed entries are
+ * reported in dispatch_alerts.summary.failed and surfaced in
+ * onComplete logging.
+ *
+ * In-process sub-graph execution (when both parent + child are bundled
+ * in the same Fargate task) means each fan-out adds ~5ms overhead vs
+ * an HTTP /trigger round-trip's 80s cold-start. For 20 issues that's
+ * 100ms vs 1600s — the architecture is what makes this template
+ * cheap enough to run hourly.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+
+import { fetchIssuesNode } from './nodes/fetch-issues-node.js';
+import { filterNoiseNode } from './nodes/filter-noise-node.js';
+import { classifyNode } from './nodes/classify-node.js';
+import { dispatchAlertsNode } from './nodes/dispatch-alerts-node.js';
+
+import {
+  sentryTriageInputSchema,
+  sentryTriageContextSchema,
+} from './state.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function loadPrompt(filename) {
+  const path = join(__dirname, 'prompts', filename);
+  return existsSync(path) ? readFileSync(path, 'utf-8') : '';
+}
+
+export class SentryTriageAgent extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph
+      .setInputSchema(sentryTriageInputSchema)
+      .setContextSchema(sentryTriageContextSchema);
+
+    graph.addNode('fetch_issues', fetchIssuesNode, { prompt: loadPrompt('fetch-issues.md') });
+    graph.addNode('filter_noise', filterNoiseNode);
+    graph.addNode('classify',     classifyNode,    { prompt: loadPrompt('classify.md') });
+    graph.addNode('dispatch_alerts', dispatchAlertsNode);
+
+    graph.setEntryPoint('fetch_issues');
+    graph.addEdge('fetch_issues',    'filter_noise');
+    graph.addEdge('filter_noise',    'classify');
+    graph.addEdge('classify',        'dispatch_alerts');
+    graph.addEdge('dispatch_alerts', 'END');
+
+    return graph;
+  }
+
+  async onComplete(result) {
+    const s = result?.state?.dispatch_alerts?.summary || {};
+    const dropped = result?.state?.filter_noise?.dropped?.length || 0;
+    const fetched = result?.state?.fetch_issues?.issues?.length || 0;
+    console.log(
+      `[sentry-triage] complete — fetched=${fetched}, noise=${dropped}, ` +
+      `sent=${s.sent || 0}, skipped=${s.skipped || 0}, failed=${s.failed || 0}`,
+    );
+  }
+}
+
+export default SentryTriageAgent;

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

@@ -0,0 +1,38 @@
+/**
+ * classify node — LLM-driven severity classification.
+ *
+ * No tools — pure prompt + structured output. The prompt
+ * (prompts/classify.md) carries the rubric (CRITICAL/HIGH/MEDIUM/LOW/
+ * NOISE) and the LLM emits one classification record per kept issue.
+ *
+ * Temperature should be 0 (set by the runner via `model: 'auto'`'s
+ * defaults for classification-style nodes). Schema enforcement
+ * guarantees the emitted shape; bad models get a retry with the
+ * outputSchema in the prompt.
+ */
+
+import { z } from '@zibby/core';
+import { SEVERITY_LEVELS } from '../state.js';
+
+const ClassificationShape = z.object({
+  issueId: z.string(),
+  severity: z.enum(SEVERITY_LEVELS),
+  confidence: z.number().min(0).max(1).optional(),
+  reasoning: z.string().optional(),
+  suggestedAction: z.string().optional(),
+  ruleMatched: z.string().optional(),
+});
+
+const ClassifyOutputSchema = z.object({
+  classifications: z.array(ClassificationShape),
+});
+
+export const classifyNode = {
+  name: 'classify',
+  // NO skills — this is a pure reasoning step; the LLM has all data
+  // it needs in state.filter_noise.kept. Adding skills would let the
+  // LLM call Sentry tools for "more context", which we don't want
+  // (rubric is supposed to be deterministic).
+  outputSchema: ClassifyOutputSchema,
+  timeout: 90 * 1000,
+};