claude-mycelium 2.0.0 → 2.1.0

package/src/coordination/inhibitors.ts

@@ -0,0 +1,345 @@
+/**
+ * Inhibitor Signal System for Claude-Mycelium
+ * Records pattern-specific warnings from failures with exponential decay
+ * Storage: .agent-meta/_inhibitors.ndjson (append-only)
+ * Reference: ADR-002, second-spec §1
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import * as path from 'path';
+import { appendFile, readFile, fileExists, writeFile } from '../utils/file-utils.js';
+import { logInfo, logError } from '../utils/logger.js';
+import type { Inhibitor, Mode, TraceEvent } from '../types/index.js';
+
+// Compute file path at runtime to respect TEST_META_DIR
+function getInhibitorsFile(): string {
+  const META_DIR = process.env.TEST_META_DIR || '.agent-meta';
+  return path.join(META_DIR, '_inhibitors.ndjson');
+}
+
+const INHIBITOR_RELEVANCE_THRESHOLD = 0.2;
+const INHIBITOR_GC_THRESHOLD = 0.05;
+const DEFAULT_HALF_LIFE_DAYS = 30;
+
+/**
+ * Emit an inhibitor signal after a failure
+ * Appends to NDJSON file for durability
+ */
+export async function emitInhibitor(params: {
+  trigger: {
+    file?: string;
+    pattern?: string;
+    mode?: Mode;
+  };
+  signal: string;
+  origin: {
+    agent_id: string;
+    trace_id: string;
+    energy_wasted: number;
+    failure_type: 'ci_failed' | 'regression' | 'reverted' | 'loop_detected';
+  };
+  strength: number;
+  half_life_days: number;
+}): Promise<Inhibitor> {
+  const inhibitor: Inhibitor = {
+    id: uuidv4(),
+    timestamp: new Date().toISOString(),
+    trigger: params.trigger,
+    signal: params.signal,
+    origin: params.origin,
+    strength: params.strength,
+    half_life_days: params.half_life_days,
+  };
+
+  try {
+    // Append to NDJSON file
+    const line = JSON.stringify(inhibitor) + '\n';
+    appendFile(getInhibitorsFile(), line);
+
+    logInfo('Inhibitor emitted', {
+      id: inhibitor.id,
+      file: inhibitor.trigger.file,
+      mode: inhibitor.trigger.mode,
+      pattern: inhibitor.trigger.pattern,
+      failure_type: inhibitor.origin.failure_type,
+      energy_wasted: `$${inhibitor.origin.energy_wasted.toFixed(4)}`,
+    });
+
+    return inhibitor;
+  } catch (error) {
+    logError('Failed to emit inhibitor', error as Error, { inhibitor });
+    throw error;
+  }
+}
+
+/**
+ * Query relevant inhibitors for a file + mode combination
+ * Returns inhibitors sorted by current strength (strongest first)
+ * Filters out inhibitors below relevance threshold
+ */
+export async function queryInhibitors(
+  file: string,
+  mode: Mode
+): Promise<Array<Inhibitor & { currentStrength: number }>> {
+  try {
+    const all = await readInhibitors();
+
+    return all
+      .map(i => ({ ...i, currentStrength: calculateCurrentStrength(i) }))
+      .filter(i => {
+        // Must be strong enough to be relevant
+        if (i.currentStrength < INHIBITOR_RELEVANCE_THRESHOLD) return false;
+
+        // Check trigger match
+        const matchesFile = !i.trigger.file || i.trigger.file === file;
+        const matchesMode = !i.trigger.mode || i.trigger.mode === mode;
+
+        return matchesFile && matchesMode;
+      })
+      .sort((a, b) => b.currentStrength - a.currentStrength);
+  } catch (error) {
+    logError('Failed to query inhibitors', error as Error, { file, mode });
+    return [];
+  }
+}
+
+/**
+ * Calculate current strength with exponential decay
+ * Formula: strength * 0.5^(days / half_life)
+ *
+ * Examples (30-day half-life):
+ * - Day 0: 1.0
+ * - Day 30: 0.5
+ * - Day 60: 0.25
+ * - Day 90: 0.125
+ */
+export function calculateCurrentStrength(inhibitor: Inhibitor): number {
+  const ageMs = Date.now() - Date.parse(inhibitor.timestamp);
+  const ageDays = ageMs / (1000 * 60 * 60 * 24);
+  const halfLives = ageDays / inhibitor.half_life_days;
+
+  return inhibitor.strength * Math.pow(0.5, halfLives);
+}
+
+/**
+ * Read all inhibitors from NDJSON file
+ */
+export async function readInhibitors(): Promise<Inhibitor[]> {
+  try {
+    if (!fileExists(getInhibitorsFile())) {
+      return [];
+    }
+
+    const content = readFile(getInhibitorsFile());
+    const lines = content.trim().split('\n').filter(line => line.length > 0);
+
+    const inhibitors: Inhibitor[] = [];
+    for (const line of lines) {
+      try {
+        const inhibitor = JSON.parse(line) as Inhibitor;
+        inhibitors.push(inhibitor);
+      } catch (error) {
+        logError('Failed to parse inhibitor line', error as Error, {
+          line: line.substring(0, 100),
+        });
+        // Skip corrupted lines
+      }
+    }
+
+    return inhibitors;
+  } catch (error) {
+    logError('Failed to read inhibitors', error as Error);
+    return [];
+  }
+}
+
+/**
+ * Extract failure pattern from CI output
+ * Heuristic pattern matching for common failure types
+ */
+export function extractFailurePattern(ciOutput: string): string | undefined {
+  if (ciOutput.includes('TypeError')) return 'changes causing TypeError';
+  if (ciOutput.includes('Cannot find module')) return 'breaking imports';
+  if (ciOutput.includes('is not assignable')) return 'type mismatches';
+  if (ciOutput.includes('ENOENT')) return 'missing file references';
+  if (ciOutput.includes('ReferenceError')) return 'undefined variable references';
+  if (ciOutput.includes('SyntaxError')) return 'syntax errors';
+  return undefined;
+}
+
+/**
+ * Summarize CI failure for human-readable signal
+ */
+export function summarizeCIFailure(ciOutput: string): string {
+  const lines = ciOutput.split('\n').filter(line => line.trim().length > 0);
+
+  // Find the first error line
+  for (const line of lines) {
+    if (
+      line.includes('Error:') ||
+      line.includes('error TS') ||
+      line.includes('✖') ||
+      line.includes('FAIL')
+    ) {
+      return line.trim().substring(0, 150); // First 150 chars
+    }
+  }
+
+  return lines[0]?.substring(0, 150) || 'CI failure (no details available)';
+}
+
+/**
+ * Check if inhibitor should be emitted after an agent run
+ * Cases: CI failed, regression, or loop detected
+ */
+export async function maybeEmitInhibitor(
+  trace: TraceEvent,
+  ciOutput?: string
+): Promise<Inhibitor | null> {
+  try {
+    // Case 1: CI failed
+    if (!trace.ci_passed && ciOutput) {
+      return await emitInhibitor({
+        trigger: {
+          file: trace.file_path,
+          mode: trace.mode,
+          pattern: extractFailurePattern(ciOutput),
+        },
+        signal: `CI failed: ${summarizeCIFailure(ciOutput)}`,
+        origin: {
+          agent_id: trace.agent_id || 'unknown',
+          trace_id: trace.id,
+          energy_wasted: trace.cost?.estimated_usd || 0,
+          failure_type: 'ci_failed',
+        },
+        strength: 1.0,
+        half_life_days: DEFAULT_HALF_LIFE_DAYS,
+      });
+    }
+
+    // Case 2: Regression (gradient increased instead of decreased)
+    if (trace.gradient_delta < -0.02) {
+      // Made things worse
+      return await emitInhibitor({
+        trigger: {
+          file: trace.file_path,
+          mode: trace.mode,
+        },
+        signal: `${trace.mode} made ${trace.file_path} worse. Gradient increased by ${Math.abs(trace.gradient_delta).toFixed(2)}.`,
+        origin: {
+          agent_id: trace.agent_id || 'unknown',
+          trace_id: trace.id,
+          energy_wasted: trace.cost?.estimated_usd || 0,
+          failure_type: 'regression',
+        },
+        strength: 1.0,
+        half_life_days: DEFAULT_HALF_LIFE_DAYS,
+      });
+    }
+
+    // Case 3: Loop detection is handled separately via checkForLoop()
+
+    return null;
+  } catch (error) {
+    logError('Failed to check for inhibitor emission', error as Error, { trace });
+    return null;
+  }
+}
+
+/**
+ * Check for loop pattern (same file + mode, 3+ attempts, no progress)
+ * Must be called after trace is recorded
+ */
+export async function checkForLoop(
+  file: string,
+  mode: Mode,
+  getRecentTraces: (file: string, mode: Mode, limit: number) => Promise<TraceEvent[]>
+): Promise<Inhibitor | null> {
+  try {
+    const recentTraces = await getRecentTraces(file, mode, 5);
+
+    // Need at least 3 attempts
+    if (recentTraces.length < 3) {
+      return null;
+    }
+
+    // Check if all recent attempts had poor efficiency (<0.02)
+    const isLoop = recentTraces.every(t => {
+      const efficiency = t.efficiency || 0;
+      return efficiency < 0.02;
+    });
+
+    if (!isLoop) {
+      return null;
+    }
+
+    // Calculate total waste
+    const totalWasted = recentTraces.reduce(
+      (sum, t) => sum + (t.cost?.estimated_usd || 0),
+      0
+    );
+
+    return await emitInhibitor({
+      trigger: {
+        file,
+        mode,
+      },
+      signal: `${mode} is stuck on ${file}. ${recentTraces.length} attempts with no improvement. Total wasted: $${totalWasted.toFixed(2)}.`,
+      origin: {
+        agent_id: recentTraces[0]?.agent_id || 'unknown',
+        trace_id: recentTraces[0]?.id || 'unknown',
+        energy_wasted: totalWasted,
+        failure_type: 'loop_detected',
+      },
+      strength: 1.0,
+      half_life_days: 60, // Longer half-life for loops
+    });
+  } catch (error) {
+    logError('Failed to check for loop', error as Error, { file, mode });
+    return null;
+  }
+}
+
+/**
+ * Garbage collect decayed inhibitors (strength < 0.05)
+ * Rewrites the NDJSON file with only relevant inhibitors
+ */
+export async function gcInhibitors(): Promise<{ removed: number; kept: number }> {
+  try {
+    const all = await readInhibitors();
+    const active = all.filter(i => calculateCurrentStrength(i) >= INHIBITOR_GC_THRESHOLD);
+
+    // Rewrite file with only active inhibitors
+    if (active.length < all.length) {
+      const lines = active.map(i => JSON.stringify(i) + '\n').join('');
+      writeFile(getInhibitorsFile(), lines);
+
+      logInfo('Inhibitor GC complete', {
+        removed: all.length - active.length,
+        kept: active.length,
+      });
+    }
+
+    return {
+      removed: all.length - active.length,
+      kept: active.length,
+    };
+  } catch (error) {
+    logError('Failed to GC inhibitors', error as Error);
+    return { removed: 0, kept: 0 };
+  }
+}
+
+/**
+ * Format inhibitor for display in agent prompts
+ */
+export function formatInhibitorForPrompt(
+  inhibitor: Inhibitor & { currentStrength: number }
+): string {
+  const strengthPercent = Math.round(inhibitor.currentStrength * 100);
+  const patternText = inhibitor.trigger.pattern || 'this approach';
+
+  return `⚠️ **[Strength: ${strengthPercent}%]** ${patternText}
+   ${inhibitor.signal}
+   _Origin: ${inhibitor.origin.failure_type} by ${inhibitor.origin.agent_id}, wasted $${inhibitor.origin.energy_wasted.toFixed(4)}_`;
+}

package/src/coordination/process-manager.ts

@@ -0,0 +1,199 @@
+/**
+ * Process management for spawning and managing agent workers
+ * Each agent runs as an independent Node.js process via child_process.fork()
+ *
+ * Reference: ADR-004 lines 15-28
+ */
+
+import { fork, ChildProcess } from 'child_process';
+import * as path from 'path';
+
+export interface SpawnOptions {
+  agentId: string;
+  maxIterations?: number;
+  timeout?: number;
+}
+
+export interface AgentProcess {
+  child: ChildProcess;
+  agentId: string;
+  startedAt: Date;
+  timeout: NodeJS.Timeout | null;
+}
+
+const activeAgents = new Map<string, AgentProcess>();
+
+/**
+ * Spawn an agent worker process
+ *
+ * @param options - Agent spawn options
+ * @returns ChildProcess handle
+ */
+export function spawnAgent(options: SpawnOptions): ChildProcess {
+  const {
+    agentId,
+    maxIterations = 10,
+    timeout = 300_000, // 5 minutes default
+  } = options;
+
+  // Path to the compiled worker file
+  const workerPath = path.join(__dirname, '../agent/worker.js');
+
+  const child = fork(workerPath, [], {
+    env: {
+      ...process.env,
+      AGENT_ID: agentId,
+      MAX_ITERATIONS: String(maxIterations),
+    },
+    stdio: ['pipe', 'pipe', 'pipe', 'ipc'],
+  });
+
+  // Set up timeout
+  const timer = setTimeout(() => {
+    console.warn(`[process-manager] Agent ${agentId} timed out after ${timeout}ms`);
+    child.kill('SIGTERM');
+  }, timeout);
+
+  // Clean up on exit
+  child.on('exit', (code, signal) => {
+    clearTimeout(timer);
+    activeAgents.delete(agentId);
+    console.log(`[process-manager] Agent ${agentId} exited with code ${code}, signal ${signal}`);
+  });
+
+  // Handle IPC messages
+  child.on('message', (message: any) => {
+    console.log(`[process-manager] Message from ${agentId}:`, message);
+  });
+
+  // Handle errors
+  child.on('error', (error) => {
+    console.error(`[process-manager] Error from agent ${agentId}:`, error);
+  });
+
+  // Track the agent
+  activeAgents.set(agentId, {
+    child,
+    agentId,
+    startedAt: new Date(),
+    timeout: timer,
+  });
+
+  return child;
+}
+
+/**
+ * Kill an agent process
+ *
+ * @param agentId - Agent to kill
+ * @returns true if agent was killed, false if not found
+ */
+export function killAgent(agentId: string): boolean {
+  const agent = activeAgents.get(agentId);
+  if (!agent) {
+    return false;
+  }
+
+  if (agent.timeout) {
+    clearTimeout(agent.timeout);
+  }
+
+  agent.child.kill('SIGTERM');
+  activeAgents.delete(agentId);
+  return true;
+}
+
+/**
+ * List all active agent processes
+ *
+ * @returns Array of active agent IDs with metadata
+ */
+export function listAgents(): Array<{
+  agentId: string;
+  pid: number;
+  startedAt: Date;
+  uptime: number;
+}> {
+  const agents: Array<{
+    agentId: string;
+    pid: number;
+    startedAt: Date;
+    uptime: number;
+  }> = [];
+
+  for (const [agentId, agent] of activeAgents) {
+    if (agent.child.pid) {
+      agents.push({
+        agentId,
+        pid: agent.child.pid,
+        startedAt: agent.startedAt,
+        uptime: Date.now() - agent.startedAt.getTime(),
+      });
+    }
+  }
+
+  return agents;
+}
+
+/**
+ * Check if an agent is running
+ *
+ * @param agentId - Agent to check
+ * @returns true if agent is running
+ */
+export function isAgentRunning(agentId: string): boolean {
+  return activeAgents.has(agentId);
+}
+
+/**
+ * Get agent process info
+ *
+ * @param agentId - Agent to get info for
+ * @returns Agent info or null if not found
+ */
+export function getAgentInfo(agentId: string): {
+  agentId: string;
+  pid: number;
+  startedAt: Date;
+  uptime: number;
+} | null {
+  const agent = activeAgents.get(agentId);
+  if (!agent || !agent.child.pid) {
+    return null;
+  }
+
+  return {
+    agentId,
+    pid: agent.child.pid,
+    startedAt: agent.startedAt,
+    uptime: Date.now() - agent.startedAt.getTime(),
+  };
+}
+
+/**
+ * Kill all active agents
+ */
+export function killAllAgents(): void {
+  for (const [agentId, agent] of activeAgents) {
+    if (agent.timeout) {
+      clearTimeout(agent.timeout);
+    }
+    agent.child.kill('SIGTERM');
+  }
+  activeAgents.clear();
+}
+
+/**
+ * Wait for all agents to complete
+ *
+ * @returns Promise that resolves when all agents have exited
+ */
+export async function waitForAllAgents(): Promise<void> {
+  const promises = Array.from(activeAgents.values()).map((agent) =>
+    new Promise<void>((resolve) => {
+      agent.child.once('exit', () => resolve());
+    })
+  );
+
+  await Promise.all(promises);
+}

package/src/core/agent-executor.ts

@@ -17,10 +17,9 @@ import { readFile, writeFile } from 'fs/promises';
 import { v4 as uuid } from 'uuid';
 import { calculateGradient } from './gradient.js';
 import { buildPrompt } from '../prompts/index.js';
-import { callLLM, type LLMResponse } from '../llm/anthropic-client.js';
+import { callLLM, calculateCost, type LLMResponse } from '../llm/anthropic-client.js';
 import { applyChanges } from './change-applier.js';
 import { recordTrace } from '../trace/trace-event.js';
-import { calculateCost } from '../cost/cost-tracker.js';
 import type { Mode, TraceEvent, ChangeSet, CostRecord } from '../types/index.js';
 import { logInfo, logDebug, logWarn, logError } from '../utils/logger.js';
 import { ciProvider } from '../utils/ci-provider.js';
@@ -104,7 +103,23 @@ export async function executeAgent(
       logInfo('Dry run - changes not applied', { file });
     } else {
       // Real run - apply changes and verify
-      changeSet = await applyChanges(file, originalContent, parsedChanges.newContent);
+      const result = await applyChanges([
+        {
+          file,
+          newContent: parsedChanges.newContent,
+          reason: `Applied ${mode} changes`,
+        },
+      ]);
+
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to apply changes');
+      }
+
+      changeSet = {
+        additions: countLines(parsedChanges.newContent) - countLines(originalContent),
+        deletions: 0,
+        files_touched: [file],
+      };
 
       // Step 7: Run CI checks
       logDebug('Step 7: Running CI checks');
@@ -185,7 +200,8 @@ export async function executeAgent(
     };
   } catch (error) {
     // Error handling - record failed trace
-    logError('Agent execution failed', error, { file, mode, agentId });
+    const errorObj = error instanceof Error ? error : new Error(String(error));
+    logError('Agent execution failed', errorObj, { file, mode, agentId });
 
     const errorTrace: TraceEvent = {
       id: traceId,

package/src/core/signals/churn.ts

@@ -12,12 +12,12 @@
  * Cache TTL: 5 minutes (300 seconds)
  */
 
-import { exec } from 'child_process';
+import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { resolve, dirname } from 'path';
 import { logDebug, logWarn } from '../../utils/logger.js';
 
-const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
 
 export interface ChurnResult {
   commits: number;
@@ -110,7 +110,8 @@ async function findGitRootForFile(filePath: string): Promise<string> {
   const fileDir = dirname(resolve(filePath));
 
   try {
-    const { stdout } = await execAsync('git rev-parse --show-toplevel', {
+    // SECURITY: Use execFile to prevent command injection
+    const { stdout } = await execFileAsync('git', ['rev-parse', '--show-toplevel'], {
       cwd: fileDir,
       maxBuffer: 1024,
     });
@@ -128,8 +129,10 @@ async function buildChurnCache(gitRoot: string): Promise<ChurnCache> {
   try {
     // Get all commits with changed files
     // Use "30 days ago" which git understands better than ISO dates
-    const { stdout } = await execAsync(
-      `git log --since="${CHURN_LOOKBACK_DAYS} days ago" --name-only --pretty=format:"" --all`,
+    // SECURITY: Use execFile with array args to prevent command injection
+    const { stdout } = await execFileAsync(
+      'git',
+      ['log', `--since=${CHURN_LOOKBACK_DAYS} days ago`, '--name-only', '--pretty=format:', '--all'],
       {
         cwd: gitRoot,
         maxBuffer: 10 * 1024 * 1024, // 10MB buffer for large repos

package/src/core/signals/debt.ts

@@ -11,12 +11,12 @@
  * Graceful fallback if ESLint missing or fails (returns 0)
  */
 
-import { exec } from 'child_process';
+import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { getLineCount } from '../../utils/file-utils.js';
 import { logDebug, logWarn } from '../../utils/logger.js';
 
-const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
 
 export interface DebtResult {
   errors: number;
@@ -44,7 +44,8 @@ export async function calculateDebt(filePath: string): Promise<DebtResult> {
 
     // Run ESLint with JSON formatter
     // Note: ESLint exits with code 1 if there are linting errors, so we catch and parse stdout
-    const { stdout } = await execAsync(`npx eslint "${filePath}" --format json`, {
+    // SECURITY: Use execFile with array args to prevent command injection
+    const { stdout } = await execFileAsync('npx', ['eslint', filePath, '--format', 'json'], {
       maxBuffer: 1024 * 1024,
     }).catch((error) => {
       // ESLint returns exit code 1 when there are lint errors, but stdout still has JSON

package/src/cost/cost-tracker.ts

@@ -6,6 +6,8 @@ import {
   appendFile,
   ensureDir,
 } from '../utils/file-utils';
+/* eslint-disable @typescript-eslint/no-unused-vars */
+// @ts-ignore
 import { logDebug, logWarn, createLogger } from '../utils/logger';
 
 const logger = createLogger({ module: 'cost-tracker' });

package/src/gc/index.ts

@@ -0,0 +1,17 @@
+/**
+ * GC Module - Garbage Collection System
+ *
+ * Per Phase 7 specification §8, §14
+ * - Trace compaction (keep last 10 samples + 7 days)
+ * - Inhibitor cleanup (remove weak signals)
+ * - Automatic GC every 100 spawns
+ *
+ * Usage:
+ * ```typescript
+ * import { runGC } from './gc/index.js';
+ * const report = await runGC();
+ * ```
+ */
+
+export * from './trace-compactor.js';
+export * from './runner.js';