claude-mycelium 2.0.0 → 2.1.0

package/src/quarantine/explorer.ts

@@ -0,0 +1,234 @@
+/**
+ * Explorer Mode Spawning for Claude-Mycelium
+ * Adaptive probability based on system efficiency and centrality
+ * Reference: initial-spec §7, second-spec §10
+ */
+
+import { logInfo, logDebug, logError } from '../utils/logger.js';
+import type { Gradient, TraceEvent } from '../types/index.js';
+import {
+  getQuarantinedFiles,
+  canExplorerAttempt,
+  recordExplorerAttempt,
+  isQuarantined,
+} from './manager.js';
+
+export interface ExplorerConfig {
+  baseProbability: number;
+  maxProbability: number;
+  efficiencyThreshold: number;
+  lookbackRuns: number;
+}
+
+const DEFAULT_CONFIG: ExplorerConfig = {
+  baseProbability: 0.05, // 5% base chance
+  maxProbability: 0.25, // 25% max chance
+  efficiencyThreshold: 0.3, // Below this, increase probability
+  lookbackRuns: 20,
+};
+
+/**
+ * Determine if explorer should spawn based on system-wide efficiency
+ * Probability increases as efficiency drops
+ *
+ * Formula from spec:
+ * - efficiency >= 0.3 → 5% chance
+ * - efficiency = 0.15 → 15% chance
+ * - efficiency = 0.0 → 25% chance
+ */
+export async function shouldSpawnExplorer(
+  getRecentTraces: (limit: number) => Promise<TraceEvent[]>,
+  config: ExplorerConfig = DEFAULT_CONFIG
+): Promise<boolean> {
+  try {
+    const recentTraces = await getRecentTraces(config.lookbackRuns);
+
+    if (recentTraces.length < 10) {
+      // Not enough data
+      return false;
+    }
+
+    // Calculate system-wide efficiency
+    const efficiencies = recentTraces.map(t => t.efficiency || 0);
+    const avgEfficiency = efficiencies.reduce((a, b) => a + b, 0) / efficiencies.length;
+
+    // Probability increases as efficiency drops
+    const efficiencyFactor = Math.max(
+      0,
+      config.efficiencyThreshold - avgEfficiency
+    ) / config.efficiencyThreshold;
+
+    const probability =
+      config.baseProbability +
+      (config.maxProbability - config.baseProbability) * efficiencyFactor;
+
+    const shouldSpawn = Math.random() < probability;
+
+    if (shouldSpawn) {
+      logInfo('Explorer spawn triggered', {
+        avgEfficiency: avgEfficiency.toFixed(3),
+        probability: (probability * 100).toFixed(1) + '%',
+      });
+    } else {
+      logDebug('Explorer spawn skipped', {
+        avgEfficiency: avgEfficiency.toFixed(3),
+        probability: (probability * 100).toFixed(1) + '%',
+      });
+    }
+
+    return shouldSpawn;
+  } catch (error) {
+    logError('Failed to check explorer spawn', error as Error);
+    return false;
+  }
+}
+
+/**
+ * Select target for explorer mode
+ * Priority:
+ * 1. Quarantined files with explorer attempts remaining
+ * 2. Highest gradient non-quarantined file
+ */
+export async function selectExplorerTarget(
+  gradients: Gradient[],
+  isFileLocked: (file: string) => Promise<boolean>
+): Promise<string | null> {
+  try {
+    // First, try quarantined files that still have explorer attempts
+    const quarantined = await getQuarantinedFiles();
+
+    for (const entry of quarantined) {
+      if (await canExplorerAttempt(entry.file)) {
+        const locked = await isFileLocked(entry.file);
+        if (!locked) {
+          logInfo('Explorer targeting quarantined file', {
+            file: entry.file,
+            attempts: entry.explorer_attempts,
+            max: entry.max_explorer_attempts,
+          });
+
+          // Record the attempt
+          await recordExplorerAttempt(entry.file);
+
+          return entry.file;
+        }
+      }
+    }
+
+    // Otherwise, pick highest gradient non-quarantined file
+    const sorted = [...gradients].sort((a, b) => b.score - a.score);
+
+    for (const g of sorted) {
+      const quarantinedCheck = await isQuarantined(g.file);
+      const lockedCheck = await isFileLocked(g.file);
+
+      if (!quarantinedCheck && !lockedCheck) {
+        logInfo('Explorer targeting high-gradient file', {
+          file: g.file,
+          gradient: g.score.toFixed(3),
+        });
+        return g.file;
+      }
+    }
+
+    return null;
+  } catch (error) {
+    logError('Failed to select explorer target', error as Error);
+    return null;
+  }
+}
+
+/**
+ * Calculate explorer spawn probability for a specific file
+ * Based on centrality: 0.1 × (1 + centrality)
+ *
+ * Examples from spec:
+ * - centrality 0.0 → 10% chance
+ * - centrality 0.5 → 15% chance
+ * - centrality 1.0 → 20% chance
+ */
+export function calculateExplorerProbability(centrality: number): number {
+  return 0.1 * (1 + centrality);
+}
+
+/**
+ * Check if explorer should be spawned for a specific file
+ * Uses centrality-based probability
+ */
+export function shouldSpawnExplorerForFile(centrality: number): boolean {
+  const probability = calculateExplorerProbability(centrality);
+  return Math.random() < probability;
+}
+
+/**
+ * Execute explorer mode with different system prompt
+ * Explorer has:
+ * - Higher temperature (more creative)
+ * - Different instruction set (exploratory)
+ * - Less constrained by patterns
+ */
+export interface ExplorerPromptConfig {
+  temperature: number; // Higher than normal (e.g., 0.8 vs 0.3)
+  systemPromptAddition: string;
+}
+
+export const EXPLORER_PROMPT_CONFIG: ExplorerPromptConfig = {
+  temperature: 0.8, // More creative than normal modes
+  systemPromptAddition: `
+## Explorer Mode
+
+You are in EXPLORER mode. This file has resisted conventional approaches.
+
+Your goal is to try creative, unconventional solutions that other modes might not consider:
+- Radical refactoring
+- Complete rewrites of problematic sections
+- Alternative algorithms or patterns
+- Breaking changes if necessary
+
+Don't be constrained by existing patterns. Think outside the box.
+
+Success criteria:
+- Meaningful gradient improvement (efficiency > 0.2)
+- CI passes
+- Code quality maintained or improved
+
+Be bold but careful.
+`,
+};
+
+/**
+ * Get explorer mode configuration
+ */
+export function getExplorerConfig(): ExplorerPromptConfig {
+  return { ...EXPLORER_PROMPT_CONFIG };
+}
+
+/**
+ * Format explorer instructions for prompt
+ */
+export function formatExplorerInstructions(
+  file: string,
+  isQuarantined: boolean,
+  explorerAttempts: number
+): string {
+  if (isQuarantined) {
+    return `
+## 🔬 Explorer Mode: Quarantined File
+
+File: ${file}
+Status: QUARANTINED (${explorerAttempts} explorer attempts made)
+
+This file has failed ${explorerAttempts > 0 ? 'multiple' : 'many'} conventional improvement attempts.
+Try creative, unconventional approaches. Don't be afraid to make bold changes.
+`;
+  }
+
+  return `
+## 🔬 Explorer Mode: Creative Exploration
+
+File: ${file}
+Status: Selected for exploratory improvement
+
+Try innovative approaches that might not be obvious. Think creatively.
+`;
+}

package/src/quarantine/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Quarantine System for Claude-Mycelium
+ * Exports quarantine manager and explorer mode
+ */
+
+export * from './manager.js';
+export * from './explorer.js';

package/src/quarantine/manager.ts

@@ -0,0 +1,336 @@
+/**
+ * Quarantine Manager for Claude-Mycelium
+ * Full withdrawal mechanism when files resist all approaches
+ * Storage: .agent-meta/_quarantine.json
+ * Reference: initial-spec §6, second-spec §9
+ */
+
+import * as path from 'path';
+import { readJsonFile, writeJsonFile, fileExists } from '../utils/file-utils.js';
+import { logInfo, logWarn, logError } from '../utils/logger.js';
+import type { TraceEvent } from '../types/index.js';
+
+// Compute file path at runtime to respect TEST_META_DIR
+function getQuarantineFile(): string {
+  const META_DIR = process.env.TEST_META_DIR || '.agent-meta';
+  return path.join(META_DIR, '_quarantine.json');
+}
+
+export interface QuarantineEntry {
+  file: string;
+  quarantined_at: string;
+  reason: string;
+  attempts_before_quarantine: number;
+  explorer_attempts: number;
+  max_explorer_attempts: number;
+}
+
+export interface QuarantineState {
+  updated_at: string;
+  entries: QuarantineEntry[];
+}
+
+export interface QuarantineConfig {
+  minSamplesBeforeQuarantine: number;
+  efficiencyThreshold: number;
+  maxExplorerAttempts: number;
+}
+
+const DEFAULT_CONFIG: QuarantineConfig = {
+  minSamplesBeforeQuarantine: 10, // Spec requirement
+  efficiencyThreshold: 0.02, // All samples must be below this
+  maxExplorerAttempts: 3, // Spec requirement
+};
+
+/**
+ * Check if a file should be quarantined
+ * Trigger: 10+ samples, all with efficiency < 0.02
+ */
+export async function shouldQuarantine(
+  file: string,
+  getTracesForFile: (file: string) => Promise<TraceEvent[]>,
+  config: QuarantineConfig = DEFAULT_CONFIG
+): Promise<boolean> {
+  try {
+    const traces = await getTracesForFile(file);
+
+    // Need minimum samples
+    if (traces.length < config.minSamplesBeforeQuarantine) {
+      return false;
+    }
+
+    // Take last 10 samples
+    const recent = traces.slice(-config.minSamplesBeforeQuarantine);
+
+    // All must have poor efficiency
+    const allPoor = recent.every(t => {
+      const efficiency = t.efficiency || 0;
+      return efficiency < config.efficiencyThreshold;
+    });
+
+    return allPoor;
+  } catch (error) {
+    logError('Failed to check quarantine condition', error as Error, { file });
+    return false;
+  }
+}
+
+/**
+ * Add a file to quarantine
+ */
+export async function addToQuarantine(entry: QuarantineEntry): Promise<void> {
+  try {
+    const state = await readQuarantineState();
+
+    // Check if already quarantined
+    const existing = state.entries.find(e => e.file === entry.file);
+    if (existing) {
+      logWarn('File already quarantined', { file: entry.file });
+      return;
+    }
+
+    // Add entry
+    state.entries.push(entry);
+    state.updated_at = new Date().toISOString();
+
+    await writeQuarantineState(state);
+
+    logWarn('File quarantined', {
+      file: entry.file,
+      reason: entry.reason,
+      attempts: entry.attempts_before_quarantine,
+    });
+  } catch (error) {
+    logError('Failed to add to quarantine', error as Error, { entry });
+    throw error;
+  }
+}
+
+/**
+ * Check if a file is quarantined
+ */
+export async function isQuarantined(file: string): Promise<boolean> {
+  try {
+    const state = await readQuarantineState();
+    return state.entries.some(e => e.file === file);
+  } catch (error) {
+    logError('Failed to check quarantine status', error as Error, { file });
+    return false;
+  }
+}
+
+/**
+ * Get quarantine entry for a file
+ */
+export async function getQuarantineEntry(file: string): Promise<QuarantineEntry | null> {
+  try {
+    const state = await readQuarantineState();
+    return state.entries.find(e => e.file === file) ?? null;
+  } catch (error) {
+    logError('Failed to get quarantine entry', error as Error, { file });
+    return null;
+  }
+}
+
+/**
+ * Check if explorer can attempt quarantined file
+ */
+export async function canExplorerAttempt(file: string): Promise<boolean> {
+  try {
+    const entry = await getQuarantineEntry(file);
+    if (!entry) return true; // Not quarantined
+
+    return entry.explorer_attempts < entry.max_explorer_attempts;
+  } catch (error) {
+    logError('Failed to check explorer attempts', error as Error, { file });
+    return false;
+  }
+}
+
+/**
+ * Record an explorer attempt on quarantined file
+ */
+export async function recordExplorerAttempt(file: string): Promise<void> {
+  try {
+    const state = await readQuarantineState();
+    const entry = state.entries.find(e => e.file === file);
+
+    if (entry) {
+      entry.explorer_attempts++;
+      state.updated_at = new Date().toISOString();
+      await writeQuarantineState(state);
+
+      logInfo('Explorer attempt recorded', {
+        file,
+        attempts: entry.explorer_attempts,
+        remaining: entry.max_explorer_attempts - entry.explorer_attempts,
+      });
+    }
+  } catch (error) {
+    logError('Failed to record explorer attempt', error as Error, { file });
+  }
+}
+
+/**
+ * Check if quarantine should be released after explorer success
+ * Only explorer mode with efficiency >= 0.2 can release
+ */
+export async function checkQuarantineRelease(
+  file: string,
+  trace: TraceEvent
+): Promise<boolean> {
+  try {
+    if (!(await isQuarantined(file))) return false;
+
+    // Only explorer can release
+    if (trace.mode !== 'explorer') return false;
+
+    // Must have good efficiency
+    const efficiency = trace.efficiency || 0;
+    if (efficiency < 0.2) return false;
+
+    await removeFromQuarantine(file);
+    logInfo('Quarantine released', {
+      file,
+      explorer_efficiency: efficiency.toFixed(3),
+    });
+
+    return true;
+  } catch (error) {
+    logError('Failed to check quarantine release', error as Error, { file });
+    return false;
+  }
+}
+
+/**
+ * Remove a file from quarantine
+ */
+export async function removeFromQuarantine(file: string): Promise<void> {
+  try {
+    const state = await readQuarantineState();
+    const before = state.entries.length;
+
+    state.entries = state.entries.filter(e => e.file !== file);
+    state.updated_at = new Date().toISOString();
+
+    await writeQuarantineState(state);
+
+    if (state.entries.length < before) {
+      logInfo('File removed from quarantine', { file });
+    }
+  } catch (error) {
+    logError('Failed to remove from quarantine', error as Error, { file });
+    throw error;
+  }
+}
+
+/**
+ * Get all quarantined files
+ */
+export async function getQuarantinedFiles(): Promise<QuarantineEntry[]> {
+  try {
+    const state = await readQuarantineState();
+    return state.entries;
+  } catch (error) {
+    logError('Failed to get quarantined files', error as Error);
+    return [];
+  }
+}
+
+/**
+ * Check and potentially quarantine a file after agent run
+ */
+export async function checkAndQuarantine(
+  file: string,
+  getTracesForFile: (file: string) => Promise<TraceEvent[]>,
+  config?: QuarantineConfig
+): Promise<boolean> {
+  try {
+    // Already quarantined?
+    if (await isQuarantined(file)) {
+      return true;
+    }
+
+    // Should quarantine now?
+    if (await shouldQuarantine(file, getTracesForFile, config)) {
+      const traces = await getTracesForFile(file);
+      const recentEfficiency = traces.slice(-5).map(t => t.efficiency || 0);
+      const avgEfficiency =
+        recentEfficiency.reduce((a, b) => a + b, 0) / recentEfficiency.length;
+
+      await addToQuarantine({
+        file,
+        quarantined_at: new Date().toISOString(),
+        reason: `No progress after ${traces.length} attempts. Avg efficiency: ${avgEfficiency.toFixed(3)}`,
+        attempts_before_quarantine: traces.length,
+        explorer_attempts: 0,
+        max_explorer_attempts: config?.maxExplorerAttempts ?? DEFAULT_CONFIG.maxExplorerAttempts,
+      });
+
+      return true;
+    }
+
+    return false;
+  } catch (error) {
+    logError('Failed to check and quarantine', error as Error, { file });
+    return false;
+  }
+}
+
+/**
+ * Read quarantine state from file
+ */
+async function readQuarantineState(): Promise<QuarantineState> {
+  try {
+    if (!fileExists(getQuarantineFile())) {
+      return {
+        updated_at: new Date().toISOString(),
+        entries: [],
+      };
+    }
+
+    return readJsonFile<QuarantineState>(getQuarantineFile());
+  } catch (error) {
+    logError('Failed to read quarantine state', error as Error);
+    return {
+      updated_at: new Date().toISOString(),
+      entries: [],
+    };
+  }
+}
+
+/**
+ * Write quarantine state to file
+ */
+async function writeQuarantineState(state: QuarantineState): Promise<void> {
+  try {
+    writeJsonFile(getQuarantineFile(), state, 2);
+  } catch (error) {
+    logError('Failed to write quarantine state', error as Error);
+    throw error;
+  }
+}
+
+/**
+ * Get quarantine statistics
+ */
+export async function getQuarantineStats(): Promise<{
+  total: number;
+  withExplorerAttempts: number;
+  exhausted: number;
+}> {
+  try {
+    const state = await readQuarantineState();
+
+    return {
+      total: state.entries.length,
+      withExplorerAttempts: state.entries.filter(e => e.explorer_attempts > 0).length,
+      exhausted: state.entries.filter(
+        e => e.explorer_attempts >= e.max_explorer_attempts
+      ).length,
+    };
+  } catch (error) {
+    logError('Failed to get quarantine stats', error as Error);
+    return { total: 0, withExplorerAttempts: 0, exhausted: 0 };
+  }
+}