shakers-cli-beta 0.8.0-beta.0

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,
+};

package/src/agent-usage.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getHomeDir } = require('./env-paths');
+
+// Local Claude Code agent-usage signal (ADR-016, agent evaluation feature).
+
+const MAX_FILES = 500; // cap total session files scanned (bounded work)
+const MAX_BYTES_PER_FILE = 8 * 1024 * 1024; // read at most an 8MB head per file
+const AGENT_TOOL_NAMES = new Set(['Agent', 'Task']);
+
+function historyRoot(env = process.env) {
+  return path.join(getHomeDir(env), '.claude', 'projects');
+}
+
+function listSessionFiles(root) {
+  const out = [];
+  let dirs;
+  try {
+    dirs = fs.readdirSync(root);
+  } catch {
+    return out; // no history dir on this machine — graceful
+  }
+  for (const d of dirs) {
+    const dirPath = path.join(root, d);
+    let files;
+    try {
+      files = fs.readdirSync(dirPath);
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (f.endsWith('.jsonl')) {
+        out.push(path.join(dirPath, f));
+        if (out.length >= MAX_FILES) return out;
+      }
+    }
+  }
+  return out;
+}
+
+// Parse ONE jsonl line, tallying any Agent/Task tool_use subagent_type into `counts`.
+function countInvocation(line, counts) {
+  if (!line || !line.includes('subagent_type')) return;
+  let o;
+  try {
+    o = JSON.parse(line);
+  } catch {
+    return; // truncated / malformed line — skip, never throw
+  }
+  const msg = o && o.message;
+  const content = msg && Array.isArray(msg.content) ? msg.content : null;
+  if (!content) return;
+  for (const c of content) {
+    if (c && c.type === 'tool_use' && AGENT_TOOL_NAMES.has(c.name)) {
+      const t = c.input && typeof c.input.subagent_type === 'string' ? c.input.subagent_type.trim() : '';
+      if (t) counts[t] = (counts[t] || 0) + 1;
+    }
+  }
+}
+
+// Read a bounded head of a session file and tally invocations.
+function scanFile(file, counts) {
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+  } catch {
+    return;
+  }
+  try {
+    const { size } = fs.fstatSync(fd);
+    const readLen = Math.min(size, MAX_BYTES_PER_FILE);
+    const buf = Buffer.allocUnsafe(readLen);
+    fs.readSync(fd, buf, 0, readLen, 0);
+    const lines = buf.toString('utf8').split('\n');
+    const complete = size > MAX_BYTES_PER_FILE ? lines.slice(0, -1) : lines;
+    for (const ln of complete) countInvocation(ln, counts);
+  } catch {
+    /* unreadable mid-stream — skip this file */
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* already closed */
+    }
+  }
+}
+
+// Scan the whole local history.
+function collectClaudeAgentUsage(env = process.env) {
+  const files = listSessionFiles(historyRoot(env));
+  if (!files.length) {
+    return { available: false, byAgent: {}, totalInvocations: 0, sessionsScanned: 0 };
+  }
+  const counts = {};
+  for (const f of files) scanFile(f, counts);
+  const totalInvocations = Object.values(counts).reduce((a, b) => a + b, 0);
+  return { available: true, byAgent: counts, totalInvocations, sessionsScanned: files.length };
+}
+
+// Annotate the DETECTED local agents with their usage count (exact match of the agent `name` against the recorded `subagent_type`).
+function collectAgentUsage(agents, env = process.env) {
+  const usage = collectClaudeAgentUsage(env);
+  const byAgent = {};
+  for (const a of agents || []) {
+    if (!a || !a.name) continue;
+    byAgent[a.name] = usage.available ? usage.byAgent[a.name] || 0 : null;
+  }
+  return {
+    available: usage.available,
+    byAgent,
+    totalInvocations: usage.totalInvocations,
+    sessionsScanned: usage.sessionsScanned,
+  };
+}
+
+module.exports = { collectClaudeAgentUsage, collectAgentUsage, historyRoot };