shakers-cli 0.0.0-stage → 0.14.1

package/src/agent-evaluation.js

@@ -0,0 +1,177 @@
+'use strict';
+
+const { scrubSecrets } = require('./agent-synthesis');
+const { requestBackend } = require('./backend-request');
+const { reporterFor, REASON } = require('./model-call-record');
+
+// Agent definition-quality evaluation client (ADR-016, agent evaluation).
+
+// HOW LONG TO WAIT FOR THE AGENT EVALUATION, and why it keeps growing.
+const DEFAULT_TIMEOUT_MS = 150000;
+const PROMPT_VERSION = 'agent-eval-v1';
+
+// Cap each agent definition to a prefix before sending.
+const MAX_DEFINITION_CHARS = 2000;
+
+// Builds the frozen-contract body from the deterministic org chart (structure) + the per-agent definition text, scrubbing each definition.
+function buildAgentEvaluationRequest(structuralAgents, definitionsByName, locale = null, consentGranted = false) {
+  const defMap = new Map(
+    (definitionsByName || []).map((d) => [d.name, d.definition != null ? d.definition : d.description]),
+  );
+  return {
+    agents: (structuralAgents || []).map((a) => ({
+      name: a.name,
+      // Scrub first, THEN cap to the prefix — so a secret straddling the cut is
+      // already redacted and can't leak a half-matched fragment.
+      definition: scrubSecrets(defMap.get(a.name) || '').slice(0, MAX_DEFINITION_CHARS),
+      tools: Array.isArray(a.tools) ? a.tools : [],
+      model: a.model || null,
+      parent: a.parent || null,
+    })),
+    promptVersion: PROMPT_VERSION,
+    // ADR-026: detected report language for the rationale + description prose.
+    ...(locale === 'es' || locale === 'en' ? { locale } : {}),
+    ...(consentGranted === true ? { traceContentConsent: true } : {}),
+  };
+}
+
+function isValidEvaluationResponse(parsed) {
+  return !!parsed && typeof parsed === 'object' && Array.isArray(parsed.evaluations);
+}
+
+// The three classification methods the server may report; anything else is
+// coerced to 'unclassified' (never trust an unexpected value).
+const CLASSIFICATION_METHODS = new Set(['deterministic', 'llm', 'unclassified']);
+const UNCLASSIFIED = Object.freeze({
+  catalogId: null,
+  category: null,
+  role: null,
+  level: null,
+  method: 'unclassified',
+});
+
+function normalizeClassification(c) {
+  if (!c || typeof c !== 'object') return { ...UNCLASSIFIED };
+  const catalogId = typeof c.catalogId === 'string' && c.catalogId ? c.catalogId : null;
+  if (!catalogId) return { ...UNCLASSIFIED };
+  const method = CLASSIFICATION_METHODS.has(c.method) ? c.method : 'unclassified';
+  return {
+    catalogId,
+    category: typeof c.category === 'string' && c.category ? c.category : null,
+    role: typeof c.role === 'string' && c.role ? c.role : null,
+    level: typeof c.level === 'string' && c.level ? c.level : null,
+    // A real id but method 'unclassified' would be contradictory — treat an id
+    // that arrived without a usable method as LLM-inferred (the conservative read).
+    method: method === 'unclassified' ? 'llm' : method,
+  };
+}
+
+// Bounds the improvements to a clean string[] (max 3, trimmed, non-empty).
+function normalizeImprovements(list) {
+  return (Array.isArray(list) ? list : [])
+    .filter((s) => typeof s === 'string' && s.trim())
+    .map((s) => s.trim())
+    .slice(0, 3);
+}
+
+// WHICH AGENTS THE CALL LEFT OUT (`omittedAgentNames`, server contract 2026-08-03).
+function normalizeOmittedAgentNames(parsed, requestBody, evaluations) {
+  const requested = new Set(
+    (requestBody && Array.isArray(requestBody.agents) ? requestBody.agents : [])
+      .map((a) => (a && typeof a.name === 'string' ? a.name : null))
+      .filter(Boolean),
+  );
+  const answered = new Set((evaluations || []).map((e) => e.name));
+
+  const declared = (parsed && Array.isArray(parsed.omittedAgentNames) ? parsed.omittedAgentNames : [])
+    .filter((n) => typeof n === 'string' && n.trim())
+    .map((n) => n.trim())
+    .filter((n) => requested.has(n));
+
+  const derived = [...requested].filter((n) => !answered.has(n));
+
+  // Deduped, and in the order the agents were REQUESTED so the list reads the same
+  // way the report lists them (never in the order a server happened to emit).
+  const union = new Set([...declared, ...derived]);
+  return [...requested].filter((n) => union.has(n));
+}
+
+// Normalizes each evaluation.
+function normalizeEvaluations(list) {
+  return (Array.isArray(list) ? list : [])
+    .filter((e) => e && typeof e.name === 'string')
+    .map((e) => ({
+      name: e.name,
+      rationale: typeof e.rationale === 'string' ? e.rationale : '',
+      // ADR-026: target-language one-line description; null when the server
+      // omitted it — the caller falls back to the verbatim phrase.
+      description: typeof e.description === 'string' && e.description ? e.description : null,
+      // v4 (agent classification): closest catalog agent + how it was matched.
+      classification: normalizeClassification(e.classification),
+      // v4: 2-3 concrete improvement tips (target language).
+      improvements: normalizeImprovements(e.improvements),
+    }));
+}
+
+// Requests the agent-evaluation endpoint.
+async function requestAgentEvaluation(requestBody, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS, onOutcome = null } = {}) {
+  const outcome = reporterFor(onOutcome, { timeoutMs });
+  if (!endpoint) {
+    outcome.skip(REASON.NO_ENDPOINT);
+    return null;
+  }
+
+  const promptVersion = (requestBody && requestBody.promptVersion) || PROMPT_VERSION;
+  const locale = requestBody && (requestBody.locale === 'es' || requestBody.locale === 'en')
+    ? requestBody.locale
+    : null;
+  const traceContentConsent = requestBody && requestBody.traceContentConsent === true;
+  const safeBody = {
+    promptVersion,
+    agents: Array.isArray(requestBody && requestBody.agents)
+      ? requestBody.agents.map((a) => ({ ...a, definition: scrubSecrets(a.definition) }))
+      : [],
+    ...(locale ? { locale } : {}),
+    ...(traceContentConsent ? { traceContentConsent: true } : {}),
+  };
+
+  let res;
+  try {
+    res = await requestBackend({ endpoint, body: safeBody, timeoutMs, trace: outcome.hops });
+  } catch (e) {
+    outcome.failFromError(e);
+    return null; // network error or timeout on every hop: never breaks the local report
+  }
+
+  if (res.status < 200 || res.status >= 300) {
+    outcome.fail(REASON.HTTP, { status: res.status, backend: res.backend });
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(res.raw);
+  } catch {
+    outcome.fail(REASON.MALFORMED_JSON, { status: res.status, backend: res.backend });
+    return null; // malformed (non-JSON) body
+  }
+
+  if (!isValidEvaluationResponse(parsed)) {
+    outcome.fail(REASON.UNEXPECTED_SHAPE, { status: res.status, backend: res.backend });
+    return null;
+  }
+
+  const evaluations = normalizeEvaluations(parsed.evaluations);
+  const omittedAgentNames = normalizeOmittedAgentNames(parsed, safeBody, evaluations);
+  // A PARTIAL ANSWER IS NOT A FAILURE, and it is not a plain success either.
+  outcome.succeed({ status: res.status, backend: res.backend, omitted: omittedAgentNames });
+  return { evaluations, promptVersion, omittedAgentNames };
+}
+
+module.exports = {
+  normalizeOmittedAgentNames,
+  PROMPT_VERSION,
+  MAX_DEFINITION_CHARS,
+  buildAgentEvaluationRequest,
+  requestAgentEvaluation,
+};

package/src/agent-org-chart.js

@@ -0,0 +1,355 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getHomeDir } = require('./env-paths');
+
+// Deterministic (no-LLM) parser of the talent's AI agent org chart (talents-ai-score, ADR-009).
+
+// Safety caps mirror scanner.js's FOOTPRINT_MAX_* (avoid pathological scans,
+// never a product requirement).
+const AGENTS_MAX_FILES = 500;
+const AGENTS_MAX_DEPTH = 6;
+
+// Only these frontmatter keys are ever captured.
+const WHITELISTED_KEYS = new Set(['name', 'tools', 'model', 'parent']);
+
+function listAgentMarkdownFiles(dir, depth = 0, budget = { count: 0 }) {
+  const results = [];
+  if (depth > AGENTS_MAX_DEPTH || budget.count >= AGENTS_MAX_FILES) return results;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results; // no .claude/agents directory: not an error, just nothing to parse
+  }
+  for (const entry of entries) {
+    if (budget.count >= AGENTS_MAX_FILES) break;
+    if (entry.isSymbolicLink()) continue; // never follow symlinks (mirrors scanner.js)
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...listAgentMarkdownFiles(full, depth + 1, budget));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      budget.count += 1;
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+function stripQuotes(value) {
+  const v = String(value).trim();
+  if (v.length >= 2) {
+    const first = v[0];
+    const last = v[v.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return v.slice(1, -1);
+    }
+  }
+  return v;
+}
+
+// Minimal, dependency-free frontmatter reader (zero-dependency invariant, same as the rest of this repo).
+function parseFrontmatter(content, { includeDescription = false } = {}) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+  const lines = match[1].split(/\r?\n/);
+  const data = {};
+  const captureKeys = includeDescription
+    ? new Set([...WHITELISTED_KEYS, 'description'])
+    : WHITELISTED_KEYS;
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!kv) {
+      i += 1;
+      continue;
+    }
+    const key = kv[1];
+    const rawValue = kv[2].trim();
+    i += 1;
+
+    // Block scalar (`|`, `>`, `|-`, `>-`, `|+`, `>+`): this is how `description` shows up in practice.
+    if (/^[|>][-+]?$/.test(rawValue)) {
+      const blockLines = [];
+      while (i < lines.length && (lines[i].trim() === '' || /^\s+/.test(lines[i]))) {
+        blockLines.push(lines[i].trim() === '' ? '' : lines[i].replace(/^\s+/, ''));
+        i += 1;
+      }
+      if (includeDescription && key === 'description') {
+        while (blockLines.length && blockLines[blockLines.length - 1] === '') blockLines.pop();
+        data[key] = blockLines.join('\n');
+      }
+      continue;
+    }
+
+    // YAML block list continuation ("key:" on its own line, followed by
+    // "- item" lines).
+    if (rawValue === '') {
+      const items = [];
+      while (i < lines.length && /^\s*-\s+/.test(lines[i])) {
+        items.push(stripQuotes(lines[i].replace(/^\s*-\s+/, '')));
+        i += 1;
+      }
+      if (items.length && captureKeys.has(key)) data[key] = items;
+      continue;
+    }
+
+    if (!captureKeys.has(key)) continue; // never captured (e.g. an inline description, unless explicitly requested)
+
+    // Inline YAML list: `tools: [Read, Write]`
+    if (/^\[.*\]$/.test(rawValue)) {
+      data[key] = rawValue
+        .slice(1, -1)
+        .split(',')
+        .map((s) => stripQuotes(s))
+        .filter(Boolean);
+      continue;
+    }
+
+    // Comma-separated scalar (the format Claude Code's own docs use):
+    // `tools: Read, Write, Bash`
+    if (key === 'tools' && rawValue.includes(',')) {
+      data[key] = rawValue
+        .split(',')
+        .map((s) => stripQuotes(s))
+        .filter(Boolean);
+      continue;
+    }
+
+    data[key] = stripQuotes(rawValue);
+  }
+
+  return data;
+}
+
+// Parses one `.claude/agents/*.md` file into { name, tools, model, parent }.
+function deriveAiProduct(filePath) {
+  const p = String(filePath || '').replace(/\\/g, '/');
+  if (p.includes('/.claude/agents/') || p.includes('/.claude/agents')) return 'claude-code';
+  return null;
+}
+
+function buildAgentFromFrontmatter(fm, filePath) {
+  const fallbackName = path.basename(filePath, path.extname(filePath));
+  const name = typeof fm.name === 'string' && fm.name.trim() ? fm.name.trim() : fallbackName;
+
+  const tools = Array.isArray(fm.tools) ? fm.tools : typeof fm.tools === 'string' ? [fm.tools] : [];
+
+  return {
+    name,
+    tools,
+    // AI product derived from the source path (see deriveAiProduct) — shown on
+    // the card in place of the LLM `model`.
+    aiProduct: deriveAiProduct(filePath),
+    model: typeof fm.model === 'string' && fm.model ? fm.model : null,
+    // Hierarchy (ADR-009): first honour an explicit `parent` frontmatter key when a project declares one.
+    parent: typeof fm.parent === 'string' && fm.parent ? fm.parent : null,
+  };
+}
+
+// `parseAgentFile` USED TO BE HERE (removed by issue 093's sweep): read one `.md` and build an agent from its frontmatter.
+
+// Markdown body (everything after the closing ` ` of the frontmatter).
+function bodyAfterFrontmatter(content) {
+  const m = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+  return m ? content.slice(m[0].length) : '';
+}
+
+const HIERARCHY_DIRECTS = /\b(defines?|sets?|directs?|approves?|coordinat\w+|orchestrat\w+|owns?)\b/i;
+const HIERARCHY_EXECUTES = /\byou\s+(execute|produce|implement|carry\s+out)\b|\byou\s+don'?t\s+strateg|passes?\s+through\s+you|execution\s+agent/i;
+const HIERARCHY_NEGATION = /\b(do\s+not|don'?t\s+touch|not\s+touch|never|nunca|no\s+toques)\b/i;
+
+function deriveParentFromText(selfName, text, knownNames) {
+  if (!text) return null;
+  const units = text.split(/\r?\n|(?<=[.!?])\s+/);
+  for (const unit of units) {
+    if (HIERARCHY_NEGATION.test(unit)) continue;
+    if (!HIERARCHY_DIRECTS.test(unit) || !HIERARCHY_EXECUTES.test(unit)) continue;
+    const matches = [];
+    for (const other of knownNames) {
+      if (other === selfName) continue;
+      const re = new RegExp('\\b' + other.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b');
+      if (re.test(unit)) matches.push(other);
+    }
+    if (matches.length === 1) return matches[0]; // exactly one -> unambiguous
+  }
+  return null;
+}
+
+// Both `.claude/agents/` locations in scope order (project first, so it
+// wins on a name collision when the results are merged/deduped below).
+function agentDirs(root) {
+  return [path.join(root, '.claude', 'agents'), path.join(getHomeDir(), '.claude', 'agents')];
+}
+
+// Per-repo AI-usage scoping: `.claude/agents/` across EVERY selected project root, PLUS home appended ONCE at the end.
+function agentDirsForRoots(roots) {
+  const dirs = [];
+  for (const root of roots) dirs.push(path.join(root, '.claude', 'agents'));
+  dirs.push(path.join(getHomeDir(), '.claude', 'agents'));
+  return dirs;
+}
+
+// Deterministic (no-LLM) agent org chart over a fixed list of `.claude/agents/` directories (in precedence order — first occurrence of a name wins).
+function parseAgentOrgChartFromDirs(dirs) {
+  const seen = new Set();
+  const agents = [];
+  // TRANSIENT prose (description + body) per agent, kept LOCAL to this function purely to derive parent edges below.
+  const textByName = new Map();
+
+  for (const dir of dirs) {
+    for (const file of listAgentMarkdownFiles(dir)) {
+      let content;
+      try {
+        content = fs.readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      const fm = parseFrontmatter(content);
+      if (!fm) continue; // no frontmatter block: not a valid agent definition
+      const agent = buildAgentFromFrontmatter(fm, file);
+      if (seen.has(agent.name)) continue; // project wins on a name collision (dir order)
+      seen.add(agent.name);
+      agents.push(agent);
+      const fmWithDesc = parseFrontmatter(content, { includeDescription: true });
+      const desc = fmWithDesc && typeof fmWithDesc.description === 'string' ? fmWithDesc.description : '';
+      textByName.set(agent.name, `${desc}\n${bodyAfterFrontmatter(content)}`);
+    }
+  }
+
+  // Derive orchestrator->subagent edges from prose for agents that declare no explicit `parent` (the common case).
+  const knownNames = agents.map((a) => a.name);
+  for (const agent of agents) {
+    if (agent.parent) continue;
+    const derived = deriveParentFromText(agent.name, textByName.get(agent.name), knownNames);
+    if (derived && derived !== agent.name) agent.parent = derived;
+  }
+
+  // Defensive: break a direct 2-cycle from mutual cues (A<->B).
+  const byName = new Map(agents.map((a) => [a.name, a]));
+  for (const agent of agents) {
+    if (!agent.parent) continue;
+    const p = byName.get(agent.parent);
+    if (p && p.parent === agent.name) p.parent = null;
+  }
+
+  return agents;
+}
+
+// Deterministic (no-LLM) agent org chart, scoped to `.claude/agents/` in BOTH the project root and the home directory (ADR-014, project ∪ home).
+function parseAgentOrgChart(root) {
+  return parseAgentOrgChartFromDirs(agentDirs(root));
+}
+
+// Per-repo AI-usage scoping: the org chart across ALL selected project roots (∪ home, once), deduped by name.
+function parseAgentOrgChartForRoots(roots) {
+  return parseAgentOrgChartFromDirs(agentDirsForRoots(Array.isArray(roots) ? roots : [roots]));
+}
+
+// talents-ai-score, ADR-010: returns `[{ name, description }]` — the ONLY function in this module that ever returns description/prompt content.
+function parseAgentDescriptionsFromDirs(dirs) {
+  const seen = new Set();
+  const result = [];
+  for (const dir of dirs) {
+    for (const file of listAgentMarkdownFiles(dir)) {
+      let content;
+      try {
+        content = fs.readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      const fm = parseFrontmatter(content, { includeDescription: true });
+      if (!fm) continue;
+      const fallbackName = path.basename(file, path.extname(file));
+      const name = typeof fm.name === 'string' && fm.name.trim() ? fm.name.trim() : fallbackName;
+      if (!seen.has(name)) {
+        seen.add(name);
+        result.push({ name, description: typeof fm.description === 'string' ? fm.description : '' });
+      }
+    }
+  }
+  return result;
+}
+
+function parseAgentDescriptions(root) {
+  return parseAgentDescriptionsFromDirs(agentDirs(root));
+}
+
+// Per-repo AI-usage scoping: card-description fallbacks across ALL selected
+// project roots (∪ home, once), same dedup/precedence as parseAgentOrgChartForRoots.
+function parseAgentDescriptionsForRoots(roots) {
+  return parseAgentDescriptionsFromDirs(agentDirsForRoots(Array.isArray(roots) ? roots : [roots]));
+}
+
+function parseAgentDefinitionsFromDirs(dirs) {
+  const seen = new Set();
+  const result = [];
+  for (const dir of dirs) {
+    for (const file of listAgentMarkdownFiles(dir)) {
+      let content;
+      try {
+        content = fs.readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      const fm = parseFrontmatter(content, { includeDescription: true });
+      if (!fm) continue;
+      const fallbackName = path.basename(file, path.extname(file));
+      const name = typeof fm.name === 'string' && fm.name.trim() ? fm.name.trim() : fallbackName;
+      if (seen.has(name)) continue;
+      seen.add(name);
+      const description = typeof fm.description === 'string' ? fm.description : '';
+      const body = bodyAfterFrontmatter(content);
+      const definition = [description, body].map((s) => (s || '').trim()).filter(Boolean).join('\n\n');
+      result.push({ name, definition });
+    }
+  }
+  return result;
+}
+
+function parseAgentDefinitions(root) {
+  return parseAgentDefinitionsFromDirs(agentDirs(root));
+}
+
+// Per-repo AI-usage scoping: full agent definitions (for the quality-evaluation
+// call) across ALL selected project roots (∪ home, once), same dedup/precedence.
+function parseAgentDefinitionsForRoots(roots) {
+  return parseAgentDefinitionsFromDirs(agentDirsForRoots(Array.isArray(roots) ? roots : [roots]));
+}
+
+function agentSourceFilesByName(root) {
+  const byName = new Map();
+  const dirs = agentDirs(root);
+  dirs.forEach((dir, dirIndex) => {
+    for (const file of listAgentMarkdownFiles(dir)) {
+      let content;
+      try {
+        content = fs.readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      const fm = parseFrontmatter(content);
+      if (!fm) continue;
+      const agent = buildAgentFromFrontmatter(fm, file);
+      if (byName.has(agent.name)) continue; // project (dirIndex 0) wins on collision
+      const rel =
+        dirIndex === 0 ? path.relative(root, file).split(path.sep).join('/') : null;
+      byName.set(agent.name, rel);
+    }
+  });
+  return byName;
+}
+
+module.exports = {
+  parseAgentOrgChart,
+  parseAgentOrgChartForRoots,
+  parseFrontmatter,
+  parseAgentDescriptions,
+  parseAgentDescriptionsForRoots,
+  parseAgentDefinitions,
+  parseAgentDefinitionsForRoots,
+  agentSourceFilesByName,
+};

package/src/agent-synthesis.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const { requestBackend } = require('./backend-request');
+const { reporterFor, REASON } = require('./model-call-record');
+
+// Agent synthesis client (talents-ai-score, ADR-010 / ADR-011).
+
+const DEFAULT_TIMEOUT_MS = 8000;
+
+/* ---------- scrub (mandatory mitigation) ---------- */
+
+const JWT_RE = /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b/g;
+const BEARER_RE = /\bBearer\s+\S{10,}/gi;
+const OPENAI_KEY_RE = /\bsk-[A-Za-z0-9]{16,}\b/g;
+const AWS_KEY_RE = /\bAKIA[0-9A-Z]{16}\b/g;
+const GENERIC_LONG_TOKEN_RE = /\b[A-Za-z0-9_-]{32,}\b/g;
+const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+const WINDOWS_PATH_RE = /[A-Za-z]:\\(?:[^\s\\]+\\)*[^\s\\]+/g;
+const UNIX_PATH_RE = /(?:\/[A-Za-z0-9_.-]+){2,}/g;
+
+const KEY_PREFIX_RE = /\b(?:sk|pk|rk|ghp|gho|ghu|ghs|ghr|xox[baprs])[-_][A-Za-z0-9_-]{10,}\b/g; // OpenAI/Stripe/GitHub/Slack-style prefixed tokens
+const GITHUB_PAT_RE = /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g;
+const GOOGLE_API_KEY_RE = /\bAIza[0-9A-Za-z_-]{35}\b/g;
+const SENDGRID_KEY_RE = /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\b/g;
+const BASE64_SECRET_RE = /\b[A-Za-z0-9+/]{40,}={0,2}\b/g; // base64-inclusive high-entropy blob (e.g. an AWS secret access key)
+const JWT_LIKE_RE = /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g; // dot-separated JWT-shaped triplet not starting with `eyJ`
+const PEM_BLOCK_RE = /-----BEGIN[ A-Z]*PRIVATE KEY-----[\s\S]*?-----END[ A-Z]*PRIVATE KEY-----/g;
+const CONN_STRING_RE = /\b([a-zA-Z][a-zA-Z0-9+.-]{1,15}:\/\/)[^\s'"/:@]+:[^\s'"@]+@/g; // scheme://user:pass@ -> scheme://[REDACTED]@
+const GENERIC_KV_RE = /\b(?:password|secret|token|api[_-]?key|bearer)\s*[:=]\s*\S+/gi;
+
+// Heuristic, best-effort redaction — an "invisible safety net" (ADR-011), not a substitute for the talent's own judgment about what they write in agent descriptions.
+function scrubSecrets(text) {
+  if (typeof text !== 'string' || !text) return '';
+  let out = text;
+  out = out.replace(PEM_BLOCK_RE, '[REDACTED]');
+  out = out.replace(CONN_STRING_RE, '$1[REDACTED]@');
+  out = out.replace(JWT_RE, '[REDACTED]');
+  out = out.replace(BEARER_RE, 'Bearer [REDACTED]');
+  out = out.replace(OPENAI_KEY_RE, '[REDACTED]');
+  out = out.replace(AWS_KEY_RE, '[REDACTED]');
+  out = out.replace(KEY_PREFIX_RE, '[REDACTED]');
+  out = out.replace(GITHUB_PAT_RE, '[REDACTED]');
+  out = out.replace(GOOGLE_API_KEY_RE, '[REDACTED]');
+  out = out.replace(SENDGRID_KEY_RE, '[REDACTED]');
+  out = out.replace(JWT_LIKE_RE, '[REDACTED]');
+  out = out.replace(GENERIC_LONG_TOKEN_RE, '[REDACTED]');
+  out = out.replace(BASE64_SECRET_RE, '[REDACTED]');
+  out = out.replace(GENERIC_KV_RE, '[REDACTED]');
+  out = out.replace(EMAIL_RE, '[REDACTED]');
+  out = out.replace(WINDOWS_PATH_RE, '[REDACTED]');
+  out = out.replace(UNIX_PATH_RE, '[REDACTED]');
+  return out;
+}
+
+/* ---------- request builder ---------- */
+
+function buildSynthesisRequest(structuralAgents, descriptionsByName, consentGranted = false) {
+  const descMap = new Map((descriptionsByName || []).map((d) => [d.name, d.description]));
+  return {
+    agents: (structuralAgents || []).map((a) => ({
+      name: a.name,
+      description: scrubSecrets(descMap.get(a.name) || ''),
+      tools: Array.isArray(a.tools) ? a.tools : [],
+      model: a.model || null,
+      parent: a.parent || null,
+    })),
+    ...(consentGranted === true ? { traceContentConsent: true } : {}),
+  };
+}
+
+/* ---------- network (via the shared PRIMARY -> FALLBACK chain) ---------- */
+
+// Validates the minimal expected shape: `{agents: [...], edges: [...]}` with `agents` an array (edges defaults to [] if absent/invalid — some diagrams may legitimately have none).
+function isValidSynthesisResponse(parsed) {
+  return !!parsed && typeof parsed === 'object' && Array.isArray(parsed.agents);
+}
+
+// Requests the agent-synthesis endpoint.
+async function requestAgentSynthesis(requestBody, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS, onOutcome = null } = {}) {
+  // Issue 109: the four `return null`s below are four DIFFERENT situations that used to be one.
+  const outcome = reporterFor(onOutcome, { timeoutMs });
+  if (!endpoint) {
+    outcome.skip(REASON.NO_ENDPOINT);
+    return null;
+  }
+
+  const safeBody = {
+    ...requestBody,
+    agents: Array.isArray(requestBody && requestBody.agents)
+      ? requestBody.agents.map((a) => ({ ...a, description: scrubSecrets(a.description) }))
+      : [],
+  };
+  if (safeBody.traceContentConsent !== true) delete safeBody.traceContentConsent;
+
+  let res;
+  try {
+    res = await requestBackend({ endpoint, body: safeBody, timeoutMs, trace: outcome.hops });
+  } catch (e) {
+    outcome.failFromError(e);
+    return null; // network error or timeout on every hop: never breaks the local report
+  }
+
+  if (res.status < 200 || res.status >= 300) {
+    outcome.fail(REASON.HTTP, { status: res.status, backend: res.backend });
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(res.raw);
+  } catch {
+    outcome.fail(REASON.MALFORMED_JSON, { status: res.status, backend: res.backend });
+    return null; // malformed (non-JSON) response body
+  }
+
+  if (!isValidSynthesisResponse(parsed)) {
+    outcome.fail(REASON.UNEXPECTED_SHAPE, { status: res.status, backend: res.backend });
+    return null;
+  }
+
+  outcome.succeed({ status: res.status, backend: res.backend });
+  return {
+    agents: parsed.agents,
+    edges: Array.isArray(parsed.edges) ? parsed.edges : [],
+  };
+}
+
+module.exports = {
+  scrubSecrets,
+  buildSynthesisRequest,
+  requestAgentSynthesis,
+};