@zibby/workflow-templates 0.3.0 → 0.4.1

package/notify-lark/state.js

@@ -0,0 +1,75 @@
+/**
+ * notify-lark — three-schema state model.
+ *
+ * Mirrors notify-slack's input shape EXACTLY (provider-neutral fields)
+ * so a parent workflow that wants to fan-out alerts to both Slack and
+ * Lark can use the same `input: (state) => ({...})` block for both
+ * dispatchSubgraph calls. The notifier-specific bits (`receiveId` vs
+ * `channel`, mention syntax) are caller-supplied; we don't try to
+ * translate between providers.
+ *
+ * Lark differences vs Slack:
+ *   - Target is `receiveId` (chat_id `oc_…`, open_id `ou_…`, or email)
+ *     — Lark needs the right `receive_id_type` query param, inferred
+ *     from the id prefix.
+ *   - Color is a theme template name (`red`, `orange`, `yellow`, `grey`,
+ *     `purple`, `green`), not a hex.
+ *   - Mention syntax: `<at user_id="ou_xxx">name</at>` — caller passes
+ *     these strings ready-formatted, same as Slack.
+ */
+
+import { z } from 'zod';
+
+export const SEVERITIES = /** @type {const} */ (['low', 'medium', 'high', 'critical']);
+
+export const notifyLarkInputSchema = z.object({
+  severity: z.enum(SEVERITIES)
+    .default('medium')
+    .describe('Alert severity. Drives header color + mention strategy.'),
+
+  title: z.string().min(1).max(300)
+    .describe('Card header text (Lark caps at ~100 chars; we truncate to 150).'),
+
+  body: z.string().max(3000).optional()
+    .describe('Body text. Supports Lark lark_md (e.g. **bold**, `code`, [text](url)).'),
+
+  receiveId: z.string().min(1).max(120)
+    .describe(
+      'Lark target. Format determines receive_id_type automatically:\n' +
+      '  oc_…  → chat_id (group/DM)\n' +
+      '  ou_…  → open_id (user)\n' +
+      '  on_…  → union_id\n' +
+      '  email → email',
+    ),
+
+  // Sentry-flavored fields (same shape as notify-slack).
+  sentryLink: z.string().url().optional()
+    .describe('Sentry issue URL — adds an "Open in Sentry" primary button.'),
+  affectedUsers: z.number().int().min(0).optional(),
+  events: z.number().int().min(0).optional(),
+  release: z.string().max(120).optional(),
+  firstSeen: z.string().optional(),
+  codeSnippet: z.string().max(2000).optional(),
+  actionUrl: z.string().url().optional(),
+  actionLabel: z.string().max(40).optional(),
+
+  // Mentions — caller-supplied Lark <at> strings.
+  mentions: z.array(z.string().max(200))
+    .max(20)
+    .optional()
+    .describe('Lark @-mentions, e.g. [\'<at user_id="ou_alice">@Alice</at>\'].'),
+
+  idempotencyKey: z.string().max(128).optional(),
+});
+
+export const notifyLarkContextSchema = z.object({
+  notify_lark: z.object({
+    delivered: z.boolean(),
+    receiveId: z.string(),
+    receiveIdType: z.string(),
+    messageId: z.string().optional(),
+  }).optional(),
+});
+
+export const notifyLarkStateSchema =
+  notifyLarkInputSchema.merge(notifyLarkContextSchema);

package/notify-slack/README.md

@@ -0,0 +1,94 @@
+# notify-slack
+
+A reusable **child workflow** that posts a structured Block Kit alert to a Slack channel.
+
+Designed to be dispatched via sub-graph from any parent workflow — most commonly the Sentry templates (`sentry-triage`, `sentry-autofix`, `sentry-incident`), but works anywhere you want a structured Slack message: cron summaries, deploy notifications, PR review pings, etc.
+
+## What it does
+
+- Takes a provider-neutral payload (severity, title, body, channel, optional Sentry-flavored fields)
+- Builds a Slack Block Kit message with severity-coded color + emoji + action buttons
+- Posts via `chat.postMessage` to the channel you specify
+- Returns the message timestamp so the parent can thread follow-ups
+
+No LLM call — single deterministic API request, typically <500ms.
+
+## Dispatch shape (parent workflow)
+
+```js
+import { WorkflowGraph, SKILLS } from '@zibby/core';
+
+const graph = new WorkflowGraph();
+
+graph.addNode('alert', {
+  workflow: 'notify-slack',
+  async: false,
+  input: (state) => ({
+    severity:      'critical',
+    title:         'Checkout: TypeError on session.user.id',
+    body:          '*12 users* affected in the last 1h. Likely regression from `1.42.0`.',
+    channel:       '#sentry-alerts',
+    sentryLink:    'https://sentry.io/.../1234567890/',
+    affectedUsers: 12,
+    events:        47,
+    release:       '1.42.0',
+    firstSeen:     '8 min ago',
+    codeSnippet:   'src/handlers/checkout.ts:142\nconst userId = session.user.id;',
+    mentions:      ['<!subteam^S0BACKEND>'],
+  }),
+  output: 'notify_slack.messageTs',  // capture the message ts for thread replies
+});
+```
+
+## Inputs
+
+| Field | Required | Description |
+|---|---|---|
+| `severity` | yes | `low \| medium \| high \| critical` — drives color + emoji |
+| `title` | yes | Headline (max 300 chars) |
+| `channel` | yes | Slack channel id (`C012345`) or `#name` |
+| `body` | no | mrkdwn body (max 3000 chars) |
+| `sentryLink` | no | Renders an "Open in Sentry" primary button |
+| `affectedUsers` | no | Renders in the metadata grid |
+| `events` | no | " |
+| `release` | no | " |
+| `firstSeen` | no | " |
+| `codeSnippet` | no | Renders as a fenced code block |
+| `actionUrl` + `actionLabel` | no | Secondary button (e.g. "View PR") |
+| `mentions` | no | Array of Slack mention strings appended in the context block |
+
+## Output
+
+```js
+{ delivered: true, channel: 'C012345', messageTs: '1716109330.123456', blocksCount: 5 }
+```
+
+The `messageTs` is what you pass back as `thread_ts` if you want to reply in-thread later (use case: incident-commander posting periodic updates).
+
+## Prerequisites
+
+The deploying project must have the **Slack** integration connected. Bot needs:
+- `chat:write` (post messages)
+- `chat:write.public` (optional — post to public channels the bot isn't a member of)
+
+## Severity → color
+
+| Severity | Hex | Emoji |
+|---|---|---|
+| low | `#7f8c8d` | ⚪ |
+| medium | `#f1c40f` | 🟡 |
+| high | `#e67e22` | 🟠 |
+| critical | `#c0392b` | 🚨 |
+
+## Tests
+
+```bash
+cd packages/workflow-templates/notify-slack
+npm test
+```
+
+Tests cover:
+- Block-Kit rendering for each severity
+- Conditional sections (omits fields/code/actions when input missing)
+- Slack API contract (mocked `fetch`)
+- Error mapping (channel_not_found, not_in_channel, network blip)

package/notify-slack/graph.mjs

@@ -0,0 +1,51 @@
+/**
+ * notify-slack — single-node child workflow.
+ *
+ * Designed to be dispatched as a sub-graph from parent workflows
+ * (sentry-triage, sentry-autofix, sentry-incident, etc.) via
+ *
+ *   g.addNode('notify', { workflow: 'notify-slack',
+ *     input: (state) => ({
+ *       severity: 'critical',
+ *       title:    'Checkout: TypeError',
+ *       body:     '12 users affected in last 1h',
+ *       channel:  '#sentry-alerts',
+ *       sentryLink: 'https://sentry.io/.../1234567890/',
+ *       affectedUsers: 12,
+ *     }),
+ *   });
+ *
+ * Returns `{ delivered, channel, messageTs }` — the parent typically
+ * stores `messageTs` if it wants to post follow-up replies as thread
+ * messages later (e.g. incident-commander posting progress updates).
+ */
+
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { notifySlackNode } from './nodes/notify-slack-node.js';
+import {
+  notifySlackInputSchema,
+  notifySlackContextSchema,
+} from './state.js';
+
+export class NotifySlackAgent extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph
+      .setInputSchema(notifySlackInputSchema)
+      .setContextSchema(notifySlackContextSchema);
+
+    graph.addNode('notify_slack', notifySlackNode);
+    graph.setEntryPoint('notify_slack');
+    graph.addEdge('notify_slack', 'END');
+
+    return graph;
+  }
+
+  async onComplete(result) {
+    const delivered = !!result?.state?.notify_slack?.delivered;
+    const ts = result?.state?.notify_slack?.messageTs || '?';
+    console.log(`[notify-slack] ${delivered ? 'delivered' : 'failed'} (ts=${ts})`);
+  }
+}
+
+export default NotifySlackAgent;

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

@@ -0,0 +1,238 @@
+/**
+ * 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';
+
+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');
+    }
+
+    // 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');
+
+    const 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.
+    const 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,93 @@
+/**
+ * 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.'),
+
+  title: z.string().min(1).max(300)
+    .describe('Short one-line headline (renders in the Slack header).'),
+
+  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.'),
+});
+
+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.1",
+  "description": "Built-in workflow templates for Zibby — browser-test-automation, code-analysis, generate-test-cases, notify-slack, notify-lark, sentry-triage.",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -15,6 +15,12 @@
     "./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/*",
+    "./sentry-triage": "./sentry-triage/graph.mjs",
+    "./sentry-triage/*": "./sentry-triage/*",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -42,6 +48,9 @@
     "browser-test-automation/",
     "code-analysis/",
     "generate-test-cases/",
+    "notify-slack/",
+    "notify-lark/",
+    "sentry-triage/",
     "index.js",
     "register-nodes.js",
     "global-setup.js",
@@ -57,7 +66,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"