@zibby/workflow-templates 0.10.4 → 0.10.10

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

@@ -0,0 +1,182 @@
+/**
+ * fetch_issue — FIX-scenario entry. DETERMINISTIC. Pulls the FULL details
+ * for ONE Sentry issue (state.issueId) via the @zibby/skills client.
+ *
+ * Mirrors fetch-issues-node (the TRIAGE scenario's bulk pull) exactly:
+ *   - deterministic (no LLM round-trip, no hallucinated query),
+ *   - still declares `skills: [SKILLS.SENTRY]` so the backend bundler marks
+ *     Sentry a REQUIRED integration for THIS scenario too — without it a fix
+ *     run would 401 on the first call. The skill's runtime tool injection is a
+ *     no-op here; the integration-requirement signal is what matters.
+ *
+ * Where TRIAGE lists+classifies MANY issues, FIX targets ONE: a Sentry webhook
+ * (or a manual run) hands us the issue id, and we pull the full record —
+ * culprit, metadata.type/value/filename, the latest event's stacktrace if
+ * available, permalink, and suspect commits — so the `fix` node's coding agent
+ * can locate the defect.
+ *
+ * Auth: same path as fetch-issues — sentryGetIssue resolves the project-scoped
+ * Sentry token via PROJECT_API_TOKEN + PROGRESS_API_URL.
+ */
+
+import { z } from 'zod';
+import { SKILLS } from '@zibby/core';
+import { resolveIntegrationToken } from '@zibby/core/backend-client.js';
+import { sentryGetIssue } from '@zibby/skills/sentry';
+
+const SuspectCommitShape = z.object({
+  id: z.string().optional(),
+  shortId: z.string().optional(),
+  message: z.string().optional(),
+  authorEmail: z.string().optional(),
+  authorName: z.string().optional(),
+});
+
+// The single-issue shape FIX consumes. Superset of fetch-issues' IssueShape:
+// adds `latestEventStacktrace` (a compact text rendering of the newest event's
+// stack frames) which the bulk list endpoint never returns — only the single
+// /issues/<id>/events/latest/ endpoint does, and the agent uses it to find the
+// failing line.
+const FetchIssueOutputSchema = z.object({
+  found: z.boolean(),
+  issue: z.object({
+    id: z.string(),
+    shortId: z.string().optional(),
+    title: z.string(),
+    culprit: z.string().optional(),
+    level: z.string().optional(),
+    status: z.string().optional(),
+    count: z.union([z.string(), z.number()]).optional(),
+    userCount: z.number().optional(),
+    firstSeen: z.string().optional(),
+    lastSeen: z.string().optional(),
+    permalink: z.string().optional(),
+    metadata: z.object({
+      type: z.string().optional(),
+      value: z.string().optional(),
+      filename: z.string().optional(),
+    }).optional(),
+    suspectCommits: z.array(SuspectCommitShape).optional(),
+    latestEventStacktrace: z.string().optional(),
+  }).optional(),
+  fetchedAt: z.string(),
+});
+
+/**
+ * Render the newest event's stack frames to a compact, agent-readable string.
+ * Sentry's issue detail does NOT include the event payload — its
+ * `/issues/<id>/events/latest/` endpoint does. We surface the in-app frames
+ * (filename:lineno · function) so the agent can jump to the failing code; this
+ * is best-effort and never throws (no stacktrace → undefined, no harm).
+ */
+function renderStacktrace(event) {
+  try {
+    const entries = event?.entries || [];
+    const exc = entries.find((e) => e?.type === 'exception');
+    const values = exc?.data?.values || [];
+    const lines = [];
+    for (const v of values) {
+      if (v?.type || v?.value) lines.push(`${v.type || 'Error'}: ${v.value || ''}`.trim());
+      const frames = v?.stacktrace?.frames || [];
+      // Sentry orders frames oldest→newest; show the last ~20, prefer in-app.
+      const inApp = frames.filter((f) => f?.inApp);
+      const chosen = (inApp.length ? inApp : frames).slice(-20);
+      for (const f of chosen) {
+        const where = [f.filename || f.module, f.lineNo ? `:${f.lineNo}` : '']
+          .filter(Boolean).join('');
+        const fn = f.function ? ` in ${f.function}` : '';
+        if (where || fn) lines.push(`  at ${where}${fn}`);
+      }
+    }
+    const text = lines.join('\n').trim();
+    return text || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export const fetchIssueNode = {
+  name: 'fetch_issue',
+  skills: [SKILLS.SENTRY],
+  outputSchema: FetchIssueOutputSchema,
+  execute: async (context) => {
+    // Same state-access pattern as fetch-issues-node: the runner passes a
+    // context with .state.getAll(); tests pass the flat state directly.
+    const state = (context?.state && typeof context.state.getAll === 'function')
+      ? context.state.getAll()
+      : context;
+
+    const issueId = state?.issueId && String(state.issueId).trim();
+    if (!issueId) {
+      throw new Error(
+        'fetch_issue: state.issueId is required for the fix scenario. ' +
+        'Pass it on the trigger payload (e.g. from a Sentry "issue alert" webhook ' +
+        'or a manual run), alongside trigger:"fix".',
+      );
+    }
+
+    console.log(`Fetching Sentry issue ${issueId} (fix scenario)`);
+    const detail = await sentryGetIssue(issueId);
+
+    const suspectCommits = (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,
+    }));
+
+    // Best-effort hydrate the latest event for its stacktrace. The issue detail
+    // endpoint does NOT carry the event payload — the global
+    // /issues/<id>/events/latest/ endpoint does. Same global (non-org-scoped)
+    // route + token resolution as sentryGetIssue. A failure here (no events,
+    // perms) must NOT block the fix — the agent still has culprit +
+    // metadata.filename to work from.
+    let latestEventStacktrace;
+    try {
+      const { token } = await resolveIntegrationToken('sentry');
+      const res = await fetch(
+        `https://sentry.io/api/0/issues/${issueId}/events/latest/`,
+        { headers: { Authorization: `Bearer ${token}` } },
+      );
+      if (res.ok) {
+        latestEventStacktrace = renderStacktrace(await res.json());
+      } else {
+        console.warn(`  · latest-event fetch returned ${res.status} — proceeding without a stacktrace.`);
+      }
+    } catch (err) {
+      console.warn(`  · latest-event fetch failed (${err.message}) — proceeding without a stacktrace.`);
+    }
+
+    const issue = {
+      id: String(detail?.id || issueId),
+      shortId: detail?.shortId,
+      title: detail?.title || detail?.metadata?.value || `Sentry issue ${issueId}`,
+      culprit: detail?.culprit,
+      level: detail?.level,
+      status: detail?.status,
+      count: detail?.count,
+      userCount: detail?.userCount,
+      firstSeen: detail?.firstSeen,
+      lastSeen: detail?.lastSeen,
+      permalink: detail?.permalink,
+      metadata: detail?.metadata
+        ? {
+            type: detail.metadata.type,
+            value: detail.metadata.value,
+            filename: detail.metadata.filename,
+          }
+        : undefined,
+      suspectCommits,
+      latestEventStacktrace,
+    };
+
+    console.log(
+      `Fetched ${issue.shortId || issue.id} [${issue.level || '?'}] ${issue.title} ` +
+      `· culprit=${issue.culprit || 'n/a'} · stacktrace=${latestEventStacktrace ? 'yes' : 'no'} ` +
+      `· suspectCommits=${suspectCommits.length}`,
+    );
+
+    return { found: true, issue, fetchedAt: new Date().toISOString() };
+  },
+};

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

@@ -0,0 +1,338 @@
+/**
+ * fix node — FIX-scenario heart. Clone the repo, have a coding agent make the
+ * SMALLEST correct fix for one Sentry issue, gate it on the repo's tests with
+ * ONE bounded retry, then commit + push a feature branch.
+ *
+ * SELF-CONTAINED BY DESIGN. This template does NOT dispatch the `code-fix`
+ * sub-graph — a customer who deploys ONLY this agent would hit SUBGRAPH_NOT_FOUND
+ * (sub-graphs require the child to be separately deployed). So the clone/edit/
+ * test/push logic is brought IN here, adapted from
+ * code-fix/nodes/{clone-node,fix-code-node}.js. Deploy one agent, it works.
+ *
+ * Differences from code-fix's two-node clone+fix_code split:
+ *   - Clone is DETERMINISTIC here (a direct `git clone` with the runtime token
+ *     spliced into the URL), not an LLM `git_checkout` call — one fewer model
+ *     round-trip, and the token-splice mechanics already live in code-fix's push
+ *     path so we reuse them for clone too. We still declare `skills:[SKILLS.GIT]`
+ *     so the backend marks the repo integration REQUIRED for this scenario
+ *     (same "deterministic node, real integration-requirement signal" pattern
+ *     as fetch_issues declaring SKILLS.SENTRY).
+ *   - The "ticket" is built from the Sentry issue (id→key, title, body =
+ *     culprit + type + message + filename + stacktrace + permalink) so the agent
+ *     can locate the bug from the error, not a hand-written ticket.
+ *
+ * Test-gate (verbatim from code-fix): after the edit, run the repo's test
+ * command; a non-zero exit feeds the captured output back into the prompt for
+ * ONE re-edit, then stop. No test command detectable → tested:false, the PR
+ * still goes to a human (their call).
+ */
+
+import { spawn } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { invokeAgent, SKILLS } from '@zibby/core';
+import { z } from 'zod';
+
+const MAX_TEST_RETRIES = 1; // one re-edit on test failure, then stop (design lock)
+
+const FixOutputSchema = z.object({
+  success: z.boolean(),
+  branch: z.string().optional(),
+  repoPath: z.string().optional(),
+  cloneError: z.string().optional(),
+  tested: z.boolean(),
+  testsPassed: z.boolean().optional(),
+  attempts: z.number().optional(),
+  testCommand: z.string().optional(),
+  changedFiles: z.array(z.string()).optional(),
+  diffStat: z.string().optional(),
+  commitMessage: z.string().optional(),
+  agentOutput: z.string().optional(),
+});
+
+/**
+ * Safe spawn wrapper — explicit args array, never shell:true. Resolves
+ * `{ code, stdout, stderr }` (does NOT reject on non-zero) so the test-gate
+ * can inspect a failing exit code. Verbatim from code-fix/fix-code-node.js.
+ */
+function run(bin, args, cwd, env) {
+  return new Promise((res) => {
+    const proc = spawn(bin, args, {
+      cwd,
+      shell: false,
+      env: env || process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => { const s = d.toString(); stdout += s; console.log(s.trimEnd()); });
+    proc.stderr.on('data', (d) => { const s = d.toString(); stderr += s; console.log(s.trimEnd()); });
+    proc.on('close', (code) => res({ code, stdout, stderr }));
+    proc.on('error', (err) => res({ code: 1, stdout, stderr: stderr + `\n${err.message}` }));
+  });
+}
+
+/** Run a shell-style command string (e.g. "npm test") via sh -c. */
+function runShell(cmd, cwd, env) {
+  return run('/bin/sh', ['-c', cmd], cwd, env);
+}
+
+/**
+ * Splice the runtime token into a clone/push URL, GitHub OR GitLab. Same
+ * mechanics as code-fix's push path (which did GitHub only); generalized here so
+ * the fix scenario clones + pushes private repos on either provider.
+ *   GitHub: https://x-access-token:<tok>@github.com/...
+ *   GitLab: https://oauth2:<tok>@gitlab.com/...
+ * Returns the original url unchanged when no token / unknown host.
+ */
+export function authedUrl(url, token) {
+  if (!url || !token) return url;
+  if (url.includes('github.com')) {
+    return url.replace(/^https:\/\/(?:[^@/]+@)?github\.com/, `https://x-access-token:${token}@github.com`);
+  }
+  if (url.includes('gitlab.com')) {
+    return url.replace(/^https:\/\/(?:[^@/]+@)?gitlab\.com/, `https://oauth2:${token}@gitlab.com`);
+  }
+  return url;
+}
+
+/**
+ * Resolve the repo URL: explicit state.repoUrl (input field) wins, else the
+ * REPO_URL env (ENV-tab config). Matches code-fix's "repo from input/env"
+ * approach but for a single repo (the fix scenario fixes ONE repo).
+ */
+function resolveRepoUrl(state) {
+  return (state?.repoUrl && String(state.repoUrl).trim())
+    || (process.env.REPO_URL && String(process.env.REPO_URL).trim())
+    || '';
+}
+
+function repoNameFromUrl(url) {
+  const m = (url || '').match(/[/:]([^/]+?)(?:\.git)?$/);
+  return m ? m[1] : 'repo';
+}
+
+/**
+ * Detect the repo's test command. TEST_COMMAND env wins; else sniff the repo.
+ * Verbatim from code-fix/fix-code-node.js.
+ */
+function detectTestCommand(repoPath) {
+  const override = (process.env.TEST_COMMAND || '').trim();
+  if (override) return override;
+
+  if (existsSync(join(repoPath, 'package.json'))) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(repoPath, 'package.json'), 'utf-8'));
+      if (pkg.scripts && pkg.scripts.test && !/no test specified/i.test(pkg.scripts.test)) {
+        return 'npm test --silent';
+      }
+    } catch { /* fall through */ }
+  }
+  if (
+    existsSync(join(repoPath, 'pytest.ini')) ||
+    existsSync(join(repoPath, 'pyproject.toml')) ||
+    existsSync(join(repoPath, 'setup.py')) ||
+    existsSync(join(repoPath, 'requirements.txt')) ||
+    existsSync(join(repoPath, 'tests'))
+  ) {
+    return 'pytest -q';
+  }
+  return null;
+}
+
+/**
+ * Build the fix "ticket" from a Sentry issue. The body packs everything the
+ * agent needs to locate the defect: error type + message, culprit, filename,
+ * the latest-event stacktrace (when fetch_issue hydrated one), suspect commits,
+ * and the permalink. Adapted from code-fix's buildFixPrompt ticket section.
+ */
+export function ticketFromIssue(issue) {
+  const md = issue?.metadata || {};
+  const lines = [];
+  if (md.type || md.value) lines.push(`Error: ${[md.type, md.value].filter(Boolean).join(': ')}`);
+  if (issue.culprit) lines.push(`Culprit: ${issue.culprit}`);
+  if (md.filename) lines.push(`File (Sentry's best guess): ${md.filename}`);
+  if (issue.level) lines.push(`Level: ${issue.level}`);
+  if (issue.count != null || issue.userCount != null) {
+    lines.push(`Impact: ${issue.count ?? '?'} event(s), ${issue.userCount ?? '?'} user(s) affected`);
+  }
+  const sc = (issue.suspectCommits || []).filter((c) => c.shortId || c.message);
+  if (sc.length) {
+    lines.push('Suspect commits:');
+    for (const c of sc.slice(0, 3)) {
+      lines.push(`  - ${c.shortId || '?'} ${c.message ? `“${String(c.message).split('\n')[0]}”` : ''} ${c.authorEmail ? `(${c.authorEmail})` : ''}`.trim());
+    }
+  }
+  if (issue.latestEventStacktrace) {
+    lines.push('\nLatest event stacktrace:\n```\n' + issue.latestEventStacktrace.slice(0, 6000) + '\n```');
+  }
+  if (issue.permalink) lines.push(`\nSentry: ${issue.permalink}`);
+
+  return {
+    key: issue.shortId || issue.id,
+    title: issue.title,
+    body: lines.join('\n'),
+    url: issue.permalink,
+  };
+}
+
+function buildFixPrompt(ticket, repoPath, extraTestFeedback) {
+  const body = ticket.body ? `\n\n## Error details (from Sentry)\n${ticket.body}` : '';
+  const base = `You are an autonomous bug-fixing agent. Fix exactly ONE production error in the repository checked out at:
+
+  ${repoPath}
+
+# Sentry issue ${ticket.key}: ${ticket.title}${body}
+
+# Your job
+1. Use the error type/message, culprit, filename, and stacktrace above to locate the defect. Read the relevant code and follow the repo's own conventions.
+2. Make the SMALLEST correct change that fixes the error. Don't refactor unrelated code, don't reformat files you didn't need to touch.
+3. If the repo has tests, add or update a test that would catch this bug — but only if it's natural to do so. Don't fabricate a test framework that isn't there.
+4. Do NOT commit, branch, or push — the workflow does that for you after you finish editing. Just leave the working tree edited.
+
+Keep the change tight and reviewable: a human will read this diff before merging.`;
+
+  if (extraTestFeedback) {
+    return `${base}
+
+# IMPORTANT — your previous attempt failed the test suite
+The test command was run after your last edit and FAILED. Here is the output. Read it carefully and fix the failures (your earlier change may be incomplete or wrong). This is your final attempt before the change goes to a human regardless.
+
+\`\`\`
+${extraTestFeedback.slice(-8000)}
+\`\`\``;
+  }
+  return base;
+}
+
+export const fixNode = {
+  name: 'fix',
+  // SKILLS.GIT → marks the repo integration REQUIRED for the fix scenario
+  // (renders "GitHub or GitLab" in the marketplace). Clone/push are done
+  // deterministically below with the runtime token; the skill declaration is
+  // the integration-requirement signal, same as fetch_issues + SKILLS.SENTRY.
+  skills: [SKILLS.GIT],
+  outputSchema: FixOutputSchema,
+  // Generous: clone + agent edit + up to two test runs on a real repo.
+  timeout: 20 * 60 * 1000,
+  execute: async (context) => {
+    const state = (context?.state && typeof context.state.getAll === 'function')
+      ? context.state.getAll()
+      : context;
+
+    const issue = state?.fetch_issue?.issue;
+    if (!issue) {
+      throw new Error('fix: no issue on state.fetch_issue.issue — fetch_issue must run first.');
+    }
+    const repoUrl = resolveRepoUrl(state);
+    if (!repoUrl) {
+      throw new Error(
+        'fix: no repo configured. Pass `repoUrl` on the trigger payload OR set the ' +
+        'REPO_URL ENV-tab var to the repository to fix (e.g. https://github.com/acme/web).',
+      );
+    }
+
+    const token = state?.githubToken || state?.gitlabToken || state?.gitToken;
+    const repoName = repoNameFromUrl(repoUrl);
+    const repoPath = join(state.workspace || process.cwd(), repoName);
+    const model = state?.model || 'auto';
+    const ticket = ticketFromIssue(issue);
+
+    console.log(`\n🔧 Fixing Sentry ${ticket.key}: ${ticket.title}`);
+    console.log(`   repo=${repoUrl} → ${repoPath}`);
+
+    // ── 0. Clone (deterministic, token-spliced URL) ─────────────────
+    const cloneRes = await run('git', ['clone', '--depth', '1', authedUrl(repoUrl, token), repoPath]);
+    if (cloneRes.code !== 0) {
+      const cloneError = `git clone failed (exit ${cloneRes.code}): ${cloneRes.stderr.slice(-500)}`;
+      console.error(`❌ ${cloneError}`);
+      return { success: false, tested: false, cloneError, changedFiles: [] };
+    }
+    // Identity for the eventual commit (no global git config on a fresh task).
+    await run('git', ['config', 'user.email', 'zibby@agent.com'], repoPath);
+    await run('git', ['config', 'user.name', 'Zibby Agent'], repoPath);
+
+    // ── 1. First edit pass ──────────────────────────────────────────
+    let agentOutput = await invokeAgent(buildFixPrompt(ticket, repoPath), { state, model });
+
+    // ── 2 + 3. Inline test-gate with ONE bounded retry ──────────────
+    const testCommand = detectTestCommand(repoPath);
+    let tested = false;
+    let testsPassed;
+    let attempts = 1;
+
+    if (!testCommand) {
+      console.log('🧪 No test command detected. Skipping test-gate — PR still goes to a human.');
+    } else {
+      console.log(`🧪 Test-gate command: ${testCommand}`);
+      tested = true;
+      let result = await runShell(testCommand, repoPath);
+      testsPassed = result.code === 0;
+      console.log(testsPassed ? '✅ Tests passed on first attempt.' : `❌ Tests failed (exit ${result.code}).`);
+
+      while (!testsPassed && attempts <= MAX_TEST_RETRIES) {
+        attempts += 1;
+        console.log(`🔁 Re-editing with test feedback (attempt ${attempts}/${MAX_TEST_RETRIES + 1})…`);
+        const feedback = `$ ${testCommand}\n${result.stdout}\n${result.stderr}`;
+        agentOutput = await invokeAgent(buildFixPrompt(ticket, repoPath, feedback), { state, model });
+        result = await runShell(testCommand, repoPath);
+        testsPassed = result.code === 0;
+        console.log(testsPassed ? '✅ Tests passed after retry.' : `❌ Tests still failing (exit ${result.code}).`);
+      }
+    }
+
+    // ── 4. Branch + commit + push ───────────────────────────────────
+    const status = await run('git', ['status', '--porcelain'], repoPath);
+    if (!status.stdout.trim()) {
+      console.warn('⚠️ Agent made no changes — nothing to commit. open_pr will skip.');
+      return {
+        success: false,
+        repoPath,
+        tested,
+        testsPassed,
+        attempts,
+        testCommand: testCommand || undefined,
+        changedFiles: [],
+        agentOutput,
+      };
+    }
+
+    const shortId = String(issue.shortId || issue.id).toLowerCase().replace(/[^a-z0-9-]+/g, '-');
+    const branch = `zibby/sentry-fix-${shortId}-${Math.random().toString(36).slice(2, 6)}`;
+    const commitMessage = `fix: ${ticket.title}\n\nAutomated fix for Sentry ${ticket.key} by Zibby sentry-triage. `
+      + `Tests: ${tested ? (testsPassed ? 'passing' : 'FAILING — needs human review') : 'not run'}.`;
+
+    await run('git', ['checkout', '-b', branch], repoPath);
+    await run('git', ['add', '-A'], repoPath);
+    await run('git', ['commit', '-m', commitMessage], repoPath);
+
+    // Authenticated remote for push (GitHub or GitLab).
+    if (token) {
+      await run('git', ['remote', 'set-url', 'origin', authedUrl(repoUrl, token)], repoPath);
+    }
+    const pushRes = await run('git', ['push', '-u', 'origin', branch], repoPath);
+    if (pushRes.code !== 0) {
+      throw new Error(`git push failed (exit ${pushRes.code}): ${pushRes.stderr.slice(-500)}`);
+    }
+
+    const diffStatRes = await run('git', ['diff', '--stat', 'HEAD~1'], repoPath);
+    const changedRes = await run('git', ['diff', '--name-only', 'HEAD~1'], repoPath);
+    const changedFiles = changedRes.stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+
+    console.log(`✅ Pushed ${changedFiles.length} file(s) on ${branch}.`);
+
+    return {
+      success: true,
+      branch,
+      repoPath,
+      tested,
+      testsPassed,
+      attempts,
+      testCommand: testCommand || undefined,
+      changedFiles,
+      diffStat: diffStatRes.stdout,
+      commitMessage,
+      agentOutput,
+    };
+  },
+};

package/sentry-triage/nodes/notify-fix-node.js

@@ -0,0 +1,79 @@
+/**
+ * notify (fix scenario) — OPTIONAL chat ping after the fix attempt.
+ *
+ * Runs LAST on the fix branch (open_pr → notify → END, and also on the
+ * fix-failed short-circuit). Posts a one-liner:
+ *   success → "🛠 Auto-fixed Sentry <shortId>: <title> → PR <url>"
+ *   failure → "⚠️ Couldn't auto-fix Sentry <shortId> — needs a human" + Sentry link
+ *
+ * Declares NO `skills` (uses `optionalSkills:['chat_notify']` for marketplace
+ * display only) and calls the chat handler DIRECTLY via lib/notify.js — so this
+ * post is graceful: no chat target / unconnected integration → { sent:false },
+ * NEVER throws (the PR, if any, is already open). Mirrors github-code-review's
+ * notify-node. Reuses the SLACK_CHANNEL / LARK_RECEIVE_ID ENV-tab config the
+ * TRIAGE dispatcher already uses, so one config drives both scenarios.
+ */
+
+import { z } from 'zod';
+import { postChatNotification } from '../lib/notify.js';
+
+const NotifyOutputSchema = z.object({
+  notify_fix: z.object({
+    sent: z.boolean(),
+    target: z.string().optional(),
+    skipped: z.string().optional(),
+    detail: z.string().optional(),
+  }),
+});
+
+function buildMessage(state) {
+  const issue = state?.fetch_issue?.issue || {};
+  const fix = state?.fix || {};
+  const pr = state?.open_pr || {};
+  const id = issue.shortId || issue.id || '(unknown)';
+  const title = issue.title || '';
+  const sentryLink = issue.permalink ? `\n${issue.permalink}` : '';
+
+  if (fix.success && pr.success && pr.pr_url) {
+    const testNote = fix.tested
+      ? (fix.testsPassed ? ' (tests passing)' : ' (⚠️ tests still failing — review carefully)')
+      : '';
+    return `🛠 Auto-fixed Sentry ${id}: ${title} → PR ${pr.pr_url}${testNote}${sentryLink}`;
+  }
+  if (fix.success && fix.branch && !pr.success) {
+    // Branch pushed but PR couldn't be opened — still worth a heads-up.
+    return `🛠 Pushed a fix branch for Sentry ${id}: ${title} (\`${fix.branch}\`), but couldn't open the PR${pr.skippedReason ? `: ${pr.skippedReason}` : ''}.${sentryLink}`;
+  }
+  return `⚠️ Couldn't auto-fix Sentry ${id} — needs a human${title ? `: ${title}` : ''}.${sentryLink}`;
+}
+
+export const notifyFixNode = {
+  name: 'notify',
+  // Marketplace metadata only (Slack OR Lark, optional). The node calls the chat
+  // handler directly, declaring NO `skills`, so it never gates deploy.
+  optionalSkills: ['chat_notify'],
+  outputSchema: NotifyOutputSchema,
+  timeout: 30 * 1000,
+  execute: async (context) => {
+    const state = (context?.state && typeof context.state.getAll === 'function')
+      ? context.state.getAll()
+      : context;
+
+    const slackChannel = process.env.SLACK_CHANNEL && String(process.env.SLACK_CHANNEL).trim();
+    const larkReceiveId = process.env.LARK_RECEIVE_ID && String(process.env.LARK_RECEIVE_ID).trim();
+
+    if (!slackChannel && !larkReceiveId) {
+      return { notify_fix: { sent: false, skipped: 'no chat target configured (SLACK_CHANNEL / LARK_RECEIVE_ID)' } };
+    }
+
+    const text = buildMessage(state);
+    const res = await postChatNotification({ slackChannel, larkReceiveId, text });
+    return {
+      notify_fix: {
+        sent: !!res.sent,
+        ...(res.target ? { target: res.target } : {}),
+        ...(res.detail ? { detail: res.detail } : {}),
+      },
+    };
+  },
+};