feat: agent compression, inspection logic, governance hooks (#491, #485, #482) (#688)

Implements three roadmap features: - Agent description compression (#491): New `agent-compress` module with catalog/summary/full compression modes and lazy-loading. Reduces ~26k token agent descriptions to ~2-3k catalog entries for context efficiency. - Inspection logic (#485): New `inspection` module that detects recurring failure patterns in skill_runs. Groups by skill + normalized failure reason, generates structured reports with suggested remediation actions. Configurable threshold (default: 3 failures). - Governance event capture hook (#482): PreToolUse/PostToolUse hook that detects secrets, policy violations, approval-required commands, and elevated privilege usage. Gated behind ECC_GOVERNANCE_CAPTURE=1 flag. Writes to governance_events table via JSON-line stderr output. 59 new tests (16 + 16 + 27), all passing.
2026-03-30 13:43:26 +08:00 · 2026-03-20 01:38:13 -07:00
parent 28de7cc420
commit 0b0b66c02f
7 changed files with 1563 additions and 0 deletions
--- a/scripts/lib/agent-compress.js
+++ b/scripts/lib/agent-compress.js
@@ -0,0 +1,230 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Parse YAML frontmatter from a markdown string.
+ * Returns { frontmatter: {}, body: string }.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const frontmatter = {};
+  for (const line of match[1].split('\n')) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+
+    const key = line.slice(0, colonIdx).trim();
+    let value = line.slice(colonIdx + 1).trim();
+
+    // Handle JSON arrays (e.g. tools: ["Read", "Grep"])
+    if (value.startsWith('[') && value.endsWith(']')) {
+      try {
+        value = JSON.parse(value);
+      } catch {
+        // keep as string
+      }
+    }
+
+    // Strip surrounding quotes
+    if (typeof value === 'string' && value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1);
+    }
+
+    frontmatter[key] = value;
+  }
+
+  return { frontmatter, body: match[2] };
+}
+
+/**
+ * Extract the first meaningful paragraph from agent body as a summary.
+ * Skips headings and blank lines, returns up to maxSentences sentences.
+ */
+function extractSummary(body, maxSentences = 1) {
+  const lines = body.split('\n');
+  const paragraphs = [];
+  let current = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed === '') {
+      if (current.length > 0) {
+        paragraphs.push(current.join(' '));
+        current = [];
+      }
+      continue;
+    }
+
+    // Skip headings
+    if (trimmed.startsWith('#')) {
+      if (current.length > 0) {
+        paragraphs.push(current.join(' '));
+        current = [];
+      }
+      continue;
+    }
+
+    // Skip list items, code blocks, etc.
+    if (trimmed.startsWith('```') || trimmed.startsWith('- **') || trimmed.startsWith('|')) {
+      continue;
+    }
+
+    current.push(trimmed);
+  }
+  if (current.length > 0) {
+    paragraphs.push(current.join(' '));
+  }
+
+  // Find first non-empty paragraph
+  const firstParagraph = paragraphs.find(p => p.length > 0);
+  if (!firstParagraph) {
+    return '';
+  }
+
+  // Extract up to maxSentences sentences
+  const sentences = firstParagraph.match(/[^.!?]+[.!?]+/g) || [firstParagraph];
+  return sentences.slice(0, maxSentences).join(' ').trim();
+}
+
+/**
+ * Load and parse a single agent file.
+ * Returns the full agent object with frontmatter and body.
+ */
+function loadAgent(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = parseFrontmatter(content);
+  const fileName = path.basename(filePath, '.md');
+
+  return {
+    fileName,
+    name: frontmatter.name || fileName,
+    description: frontmatter.description || '',
+    tools: Array.isArray(frontmatter.tools) ? frontmatter.tools : [],
+    model: frontmatter.model || 'sonnet',
+    body,
+    byteSize: Buffer.byteLength(content, 'utf8'),
+  };
+}
+
+/**
+ * Load all agents from a directory.
+ */
+function loadAgents(agentsDir) {
+  if (!fs.existsSync(agentsDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(agentsDir)
+    .filter(f => f.endsWith('.md'))
+    .sort()
+    .map(f => loadAgent(path.join(agentsDir, f)));
+}
+
+/**
+ * Compress an agent to its catalog entry (metadata only).
+ * This is the minimal representation needed for agent selection.
+ */
+function compressToCatalog(agent) {
+  return {
+    name: agent.name,
+    description: agent.description,
+    tools: agent.tools,
+    model: agent.model,
+  };
+}
+
+/**
+ * Compress an agent to a summary entry (metadata + first paragraph).
+ * More context than catalog, less than full body.
+ */
+function compressToSummary(agent) {
+  return {
+    name: agent.name,
+    description: agent.description,
+    tools: agent.tools,
+    model: agent.model,
+    summary: extractSummary(agent.body),
+  };
+}
+
+/**
+ * Build a full compressed catalog from a directory of agents.
+ *
+ * Modes:
+ *  - 'catalog': name, description, tools, model only (~2-3k tokens for 27 agents)
+ *  - 'summary': catalog + first paragraph summary (~4-5k tokens)
+ *  - 'full':    no compression, full body included
+ *
+ * Returns { agents: [], stats: { totalAgents, originalBytes, compressedTokenEstimate } }
+ */
+function buildAgentCatalog(agentsDir, options = {}) {
+  const mode = options.mode || 'catalog';
+  const filter = options.filter || null;
+
+  let agents = loadAgents(agentsDir);
+
+  if (typeof filter === 'function') {
+    agents = agents.filter(filter);
+  }
+
+  const originalBytes = agents.reduce((sum, a) => sum + a.byteSize, 0);
+
+  let compressed;
+  if (mode === 'catalog') {
+    compressed = agents.map(compressToCatalog);
+  } else if (mode === 'summary') {
+    compressed = agents.map(compressToSummary);
+  } else {
+    compressed = agents.map(a => ({
+      name: a.name,
+      description: a.description,
+      tools: a.tools,
+      model: a.model,
+      body: a.body,
+    }));
+  }
+
+  const compressedJson = JSON.stringify(compressed);
+  // Rough token estimate: ~4 chars per token for English text
+  const compressedTokenEstimate = Math.ceil(compressedJson.length / 4);
+
+  return {
+    agents: compressed,
+    stats: {
+      totalAgents: agents.length,
+      originalBytes,
+      compressedBytes: Buffer.byteLength(compressedJson, 'utf8'),
+      compressedTokenEstimate,
+      mode,
+    },
+  };
+}
+
+/**
+ * Lazy-load a single agent's full content by name from a directory.
+ * Returns null if not found.
+ */
+function lazyLoadAgent(agentsDir, agentName) {
+  const filePath = path.join(agentsDir, `${agentName}.md`);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  return loadAgent(filePath);
+}
+
+module.exports = {
+  buildAgentCatalog,
+  compressToCatalog,
+  compressToSummary,
+  extractSummary,
+  lazyLoadAgent,
+  loadAgent,
+  loadAgents,
+  parseFrontmatter,
+};
--- a/scripts/lib/inspection.js
+++ b/scripts/lib/inspection.js
@@ -0,0 +1,212 @@
+'use strict';
+
+const DEFAULT_FAILURE_THRESHOLD = 3;
+const DEFAULT_WINDOW_SIZE = 50;
+
+const FAILURE_OUTCOMES = new Set(['failure', 'failed', 'error']);
+
+/**
+ * Normalize a failure reason string for grouping.
+ * Strips timestamps, UUIDs, file paths, and numeric suffixes.
+ */
+function normalizeFailureReason(reason) {
+  if (!reason || typeof reason !== 'string') {
+    return 'unknown';
+  }
+
+  return reason
+    .trim()
+    .toLowerCase()
+    // Strip ISO timestamps (note: already lowercased, so t/z not T/Z)
+    .replace(/\d{4}-\d{2}-\d{2}[t ]\d{2}:\d{2}:\d{2}[.\dz]*/g, '<timestamp>')
+    // Strip UUIDs (already lowercased)
+    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, '<uuid>')
+    // Strip file paths
+    .replace(/\/[\w./-]+/g, '<path>')
+    // Collapse whitespace
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Group skill runs by skill ID and normalized failure reason.
+ *
+ * @param {Array} skillRuns - Array of skill run objects
+ * @returns {Map<string, { skillId: string, normalizedReason: string, runs: Array }>}
+ */
+function groupFailures(skillRuns) {
+  const groups = new Map();
+
+  for (const run of skillRuns) {
+    const outcome = String(run.outcome || '').toLowerCase();
+    if (!FAILURE_OUTCOMES.has(outcome)) {
+      continue;
+    }
+
+    const normalizedReason = normalizeFailureReason(run.failureReason);
+    const key = `${run.skillId}::${normalizedReason}`;
+
+    if (!groups.has(key)) {
+      groups.set(key, {
+        skillId: run.skillId,
+        normalizedReason,
+        runs: [],
+      });
+    }
+
+    groups.get(key).runs.push(run);
+  }
+
+  return groups;
+}
+
+/**
+ * Detect recurring failure patterns from skill runs.
+ *
+ * @param {Array} skillRuns - Array of skill run objects (newest first)
+ * @param {Object} [options]
+ * @param {number} [options.threshold=3] - Minimum failure count to trigger pattern detection
+ * @returns {Array<Object>} Array of detected patterns sorted by count descending
+ */
+function detectPatterns(skillRuns, options = {}) {
+  const threshold = options.threshold ?? DEFAULT_FAILURE_THRESHOLD;
+  const groups = groupFailures(skillRuns);
+  const patterns = [];
+
+  for (const [, group] of groups) {
+    if (group.runs.length < threshold) {
+      continue;
+    }
+
+    const sortedRuns = [...group.runs].sort(
+      (a, b) => (b.createdAt || '').localeCompare(a.createdAt || '')
+    );
+
+    const firstSeen = sortedRuns[sortedRuns.length - 1].createdAt || null;
+    const lastSeen = sortedRuns[0].createdAt || null;
+    const sessionIds = [...new Set(sortedRuns.map(r => r.sessionId).filter(Boolean))];
+    const versions = [...new Set(sortedRuns.map(r => r.skillVersion).filter(Boolean))];
+
+    // Collect unique raw failure reasons for this normalized group
+    const rawReasons = [...new Set(sortedRuns.map(r => r.failureReason).filter(Boolean))];
+
+    patterns.push({
+      skillId: group.skillId,
+      normalizedReason: group.normalizedReason,
+      count: group.runs.length,
+      firstSeen,
+      lastSeen,
+      sessionIds,
+      versions,
+      rawReasons,
+      runIds: sortedRuns.map(r => r.id),
+    });
+  }
+
+  // Sort by count descending, then by lastSeen descending
+  return patterns.sort((a, b) => {
+    if (b.count !== a.count) return b.count - a.count;
+    return (b.lastSeen || '').localeCompare(a.lastSeen || '');
+  });
+}
+
+/**
+ * Generate an inspection report from detected patterns.
+ *
+ * @param {Array} patterns - Output from detectPatterns()
+ * @param {Object} [options]
+ * @param {string} [options.generatedAt] - ISO timestamp for the report
+ * @returns {Object} Inspection report
+ */
+function generateReport(patterns, options = {}) {
+  const generatedAt = options.generatedAt || new Date().toISOString();
+
+  if (patterns.length === 0) {
+    return {
+      generatedAt,
+      status: 'clean',
+      patternCount: 0,
+      patterns: [],
+      summary: 'No recurring failure patterns detected.',
+    };
+  }
+
+  const totalFailures = patterns.reduce((sum, p) => sum + p.count, 0);
+  const affectedSkills = [...new Set(patterns.map(p => p.skillId))];
+
+  return {
+    generatedAt,
+    status: 'attention_needed',
+    patternCount: patterns.length,
+    totalFailures,
+    affectedSkills,
+    patterns: patterns.map(p => ({
+      skillId: p.skillId,
+      normalizedReason: p.normalizedReason,
+      count: p.count,
+      firstSeen: p.firstSeen,
+      lastSeen: p.lastSeen,
+      sessionIds: p.sessionIds,
+      versions: p.versions,
+      rawReasons: p.rawReasons.slice(0, 5),
+      suggestedAction: suggestAction(p),
+    })),
+    summary: `Found ${patterns.length} recurring failure pattern(s) across ${affectedSkills.length} skill(s) (${totalFailures} total failures).`,
+  };
+}
+
+/**
+ * Suggest a remediation action based on pattern characteristics.
+ */
+function suggestAction(pattern) {
+  const reason = pattern.normalizedReason;
+
+  if (reason.includes('timeout')) {
+    return 'Increase timeout or optimize skill execution time.';
+  }
+  if (reason.includes('permission') || reason.includes('denied') || reason.includes('auth')) {
+    return 'Check tool permissions and authentication configuration.';
+  }
+  if (reason.includes('not found') || reason.includes('missing')) {
+    return 'Verify required files/dependencies exist before skill execution.';
+  }
+  if (reason.includes('parse') || reason.includes('syntax') || reason.includes('json')) {
+    return 'Review input/output format expectations and add validation.';
+  }
+  if (pattern.versions.length > 1) {
+    return 'Failure spans multiple versions. Consider rollback to last stable version.';
+  }
+
+  return 'Investigate root cause and consider adding error handling.';
+}
+
+/**
+ * Run full inspection pipeline: query skill runs, detect patterns, generate report.
+ *
+ * @param {Object} store - State store instance with listRecentSessions, getSessionDetail
+ * @param {Object} [options]
+ * @param {number} [options.threshold] - Minimum failure count
+ * @param {number} [options.windowSize] - Number of recent skill runs to analyze
+ * @returns {Object} Inspection report
+ */
+function inspect(store, options = {}) {
+  const windowSize = options.windowSize ?? DEFAULT_WINDOW_SIZE;
+  const threshold = options.threshold ?? DEFAULT_FAILURE_THRESHOLD;
+
+  const status = store.getStatus({ recentSkillRunLimit: windowSize });
+  const skillRuns = status.skillRuns.recent || [];
+
+  const patterns = detectPatterns(skillRuns, { threshold });
+  return generateReport(patterns, { generatedAt: status.generatedAt });
+}
+
+module.exports = {
+  DEFAULT_FAILURE_THRESHOLD,
+  DEFAULT_WINDOW_SIZE,
+  detectPatterns,
+  generateReport,
+  groupFailures,
+  inspect,
+  normalizeFailureReason,
+  suggestAction,
+};