claude-mycelium 2.0.0

package/src/prompts/index.ts

@@ -0,0 +1,128 @@
+/**
+ * Prompt Templates
+ * Per initial-spec §4.1
+ *
+ * Mode-specific prompts for guiding agents.
+ * Each prompt provides context and instructions for a specific improvement mode.
+ */
+
+import { readFile } from 'fs/promises';
+import type { Mode, GradientScore } from '../types/index.js';
+import type { PromptContext } from './types.js';
+
+export { generatePrompt as generateErrorReducerPrompt } from './error-reducer.js';
+export { generatePrompt as generateComplexityReducerPrompt } from './complexity-reducer.js';
+export { generatePrompt as generateDebtPayerPrompt } from './debt-payer.js';
+export { generatePrompt as generateStabilizerPrompt } from './stabilizer.js';
+
+export type { PromptContext } from './types.js';
+
+/**
+ * Build complete prompt for agent (system + user)
+ * Used by agent-executor
+ */
+export async function buildPrompt(
+  file: string,
+  mode: Mode,
+  gradient: GradientScore
+): Promise<{ system: string; user: string }> {
+  // Read file content
+  const content = await readFile(file, 'utf-8');
+
+  // Build context
+  const context: PromptContext = {
+    file,
+    content,
+    gradient,
+    mode,
+  };
+
+  // Generate mode-specific prompt
+  let userPrompt: string;
+  switch (mode) {
+    case 'error_reducer': {
+      const { generatePrompt } = await import('./error-reducer.js');
+      userPrompt = generatePrompt(context);
+      break;
+    }
+    case 'complexity_reducer': {
+      const { generatePrompt } = await import('./complexity-reducer.js');
+      userPrompt = generatePrompt(context);
+      break;
+    }
+    case 'debt_payer': {
+      const { generatePrompt } = await import('./debt-payer.js');
+      userPrompt = generatePrompt(context);
+      break;
+    }
+    case 'stabilizer': {
+      const { generatePrompt } = await import('./stabilizer.js');
+      userPrompt = generatePrompt(context);
+      break;
+    }
+    case 'explorer': {
+      // Explorer mode - use generic improvement prompt
+      userPrompt = buildExplorerPrompt(context);
+      break;
+    }
+    default:
+      throw new Error(`Unknown mode: ${mode}`);
+  }
+
+  // System prompt is common across all modes
+  const systemPrompt = `You are a code improvement agent. Your task is to analyze and improve code files.
+
+CRITICAL OUTPUT FORMAT:
+1. Brief analysis (2-3 sentences)
+2. Complete modified file in code fence:
+
+\`\`\`typescript
+// complete modified code here
+\`\`\`
+
+RULES:
+- Output COMPLETE file, not just changes
+- Make MINIMAL changes for your mode's focus
+- PRESERVE all existing functionality
+- Do NOT add comments explaining changes
+- Do NOT introduce new dependencies`;
+
+  return {
+    system: systemPrompt,
+    user: userPrompt,
+  };
+}
+
+/**
+ * Build explorer mode prompt
+ */
+function buildExplorerPrompt(context: PromptContext): string {
+  const { file, content, gradient } = context;
+
+  return `# Task
+You are exploring \`${file}\` to find novel improvement opportunities.
+
+## File Context
+**Gradient**: ${gradient.score.toFixed(3)}
+**Dominant issue**: ${gradient.dominantSignal.name} = ${gradient.dominantSignal.value.toFixed(3)}
+
+## Explorer Mode Instructions
+This file has resisted conventional improvements. You have permission to:
+- Challenge fundamental assumptions
+- Suggest structural changes (within limits)
+- Try unconventional approaches
+
+**Constraints**:
+- Maximum 50 lines changed
+- Cannot change public API signatures
+- Cannot remove validation logic
+- Changes will be flagged for human review
+
+## Current File Content
+\`\`\`typescript
+${content}
+\`\`\`
+
+## Your Task
+Explore creative improvements to this file while respecting the constraints.`;
+}

package/src/prompts/stabilizer.ts

@@ -0,0 +1,59 @@
+/**
+ * Stabilizer Prompt
+ * Focus: Reduce churn with tests and documentation
+ */
+
+import { getModeInstructions } from '../core/mode-selector.js';
+import type { PromptContext } from './types.js';
+
+export function generatePrompt(context: PromptContext): string {
+  const { file, content, gradient, rank, totalFiles } = context;
+  const { dominantSignal, signals, score } = gradient;
+
+  const rankInfo = rank && totalFiles
+    ? `(ranked #${rank} of ${totalFiles})`
+    : '';
+
+  return `# Task
+You are improving \`${file}\` in mode \`stabilizer\`.
+
+## File Context
+**Current gradient**: ${score.toFixed(3)} ${rankInfo}
+**Dominant issue**: ${dominantSignal.name} = ${dominantSignal.value.toFixed(3)}
+
+${getModeInstructions('stabilizer')}
+
+## Current File Content
+\`\`\`typescript
+${content}
+\`\`\`
+
+## Your Task
+Improve stability to reduce future changes:
+
+1. Identify stability issues:
+   - Missing tests
+   - Unclear behavior that requires frequent changes
+   - Weak interfaces that allow misuse
+   - Magic numbers without constants
+   - Poor encapsulation
+
+2. Make stability improvements:
+   - Add unit tests for untested code
+   - Document unclear behavior
+   - Improve interfaces to prevent misuse
+   - Extract constants from magic numbers
+   - Improve encapsulation
+
+3. Avoid major changes:
+   - Do NOT refactor internals (use complexity_reducer for that)
+   - Do NOT change public APIs without good reason
+   - Do NOT remove existing tests
+
+**Important**:
+- Make minimal, focused changes
+- Preserve existing functionality
+- Add tests if removing code
+- Keep the same file structure
+- Explain what you changed and why`;
+}

package/src/prompts/types.ts

@@ -0,0 +1,15 @@
+/**
+ * Prompt Template Types
+ */
+
+import type { Mode } from '../types/index.js';
+import type { GradientScore } from '../core/gradient.js';
+
+export interface PromptContext {
+  file: string;
+  content: string;
+  gradient: GradientScore;
+  mode: Mode;
+  rank?: number;
+  totalFiles?: number;
+}

package/src/trace/README.md

@@ -0,0 +1,178 @@
+# Trace Event System
+
+The trace event system records all agent actions for learning and analysis. Every agent intervention produces a trace event that captures what happened, how much it cost, and whether it improved the codebase.
+
+## Storage
+
+Traces are stored in `.agent-meta/traces.jsonl` using JSON Lines format (one trace per line). This format enables:
+- Fast append-only writes (important for concurrent agents)
+- Easy streaming/parsing (no need to load entire file)
+- Simple archival (just move lines to archive files)
+
+## Schema
+
+```typescript
+interface TraceEvent {
+  id: string;                    // UUID
+  timestamp: string;             // ISO 8601
+  agent_id: string;              // Agent that performed the action
+  file_path: string;             // File that was modified
+  mode: Mode;                    // Agent mode used
+  gradient_before: number;       // File gradient before intervention
+  gradient_after: number;        // File gradient after intervention
+  gradient_delta: number;        // Improvement (before - after)
+  changes_made: string[];        // List of changes
+  tokens_used: number;           // Total tokens consumed
+  cost_usd: number;              // Estimated cost in USD
+  duration_ms: number;           // Duration in milliseconds
+  success: boolean;              // Whether intervention succeeded
+  error?: string;                // Error message if failed
+}
+```
+
+## Usage
+
+### Recording Traces
+
+```typescript
+import { recordTrace, createTraceEvent } from './trace/trace-event.js';
+
+const trace = createTraceEvent({
+  agent_id: 'agent-123',
+  file_path: 'src/auth.ts',
+  mode: 'error_reducer',
+  gradient_before: 0.8,
+  gradient_after: 0.6,
+  changes_made: ['fix null check', 'add error handling'],
+  tokens_used: 1000,
+  cost_usd: 0.05,
+  duration_ms: 30000,
+  success: true,
+});
+
+await recordTrace(trace);
+```
+
+### Reading Traces
+
+```typescript
+import { readTraces } from './trace/trace-event.js';
+
+// Get all traces (newest first)
+const all = await readTraces();
+
+// Filter by file
+const authTraces = await readTraces({ file: 'src/auth.ts' });
+
+// Filter by mode
+const errorReducers = await readTraces({ mode: 'error_reducer' });
+
+// Filter by date
+const recent = await readTraces({
+  since: new Date('2025-01-01'),
+  limit: 10
+});
+```
+
+### Calculating Efficiency
+
+Efficiency measures gradient improvement per dollar spent:
+
+```typescript
+import { getRecentEfficiency } from './trace/trace-event.js';
+
+// Get efficiency for last 5 traces
+const efficiency = await getRecentEfficiency('src/auth.ts', 5);
+
+if (efficiency !== null && efficiency < 0.15) {
+  console.log('Poor efficiency - consider quarantining this file');
+}
+```
+
+### Statistics
+
+```typescript
+import { getTraceStats } from './trace/trace-event.js';
+
+const traces = await readTraces({ file: 'src/auth.ts' });
+const stats = getTraceStats(traces);
+
+console.log(`Total cost: $${stats.totalCost.toFixed(2)}`);
+console.log(`Average improvement: ${stats.avgDelta.toFixed(3)}`);
+console.log(`Success rate: ${(stats.successRate * 100).toFixed(1)}%`);
+```
+
+### Cost Calculation
+
+```typescript
+import { calculateCost } from './trace/trace-event.js';
+
+// Calculate cost from token usage
+const cost = calculateCost(
+  1_000_000,  // tokens in
+  500_000,    // tokens out
+  'claude-sonnet-4'
+);
+// Returns: $10.50
+```
+
+## Cleanup
+
+The system automatically cleans up old traces to keep file size manageable:
+- Keeps last 1000 traces in main file
+- Archives older traces to dated files in `.agent-meta/traces-archive/`
+- Runs cleanup every 100 traces
+
+## Concurrent Access
+
+The trace system is designed for concurrent access by multiple agents:
+- Append-only writes (no locks needed)
+- Each trace is a single line (atomic writes)
+- Read operations tolerate partially written lines (skip corrupted)
+
+## Metrics
+
+Key metrics calculated from traces:
+
+1. **Efficiency**: `gradient_delta / cost_usd`
+   - Higher is better
+   - Below 0.15 indicates poor performance
+
+2. **Success Rate**: Percentage of traces with `success: true`
+   - Should be > 90%
+
+3. **Cost per Improvement**: `total_cost / total_delta`
+   - Lower is better
+   - Used for budget optimization
+
+## Example Trace
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "timestamp": "2025-01-30T18:30:00.000Z",
+  "agent_id": "agent-abc123",
+  "file_path": "src/auth.ts",
+  "mode": "error_reducer",
+  "gradient_before": 0.72,
+  "gradient_after": 0.58,
+  "gradient_delta": 0.14,
+  "changes_made": [
+    "fix null check in validateToken()",
+    "add error handling for expired tokens"
+  ],
+  "tokens_used": 1523,
+  "cost_usd": 0.0456,
+  "duration_ms": 32451,
+  "success": true
+}
+```
+
+## Integration
+
+Traces feed into several system components:
+
+- **Quarantine System**: Uses efficiency to detect files resisting improvement
+- **Explorer Mode**: Triggered by low system-wide efficiency
+- **Cost Tracking**: Aggregates costs by mode, file, and time period
+- **Learning**: Trains on successful patterns for future routing

package/src/trace/index.ts

@@ -0,0 +1,88 @@
+/**
+ * Trace Module - Event Tracking System
+ *
+ * Per Phase 2 specification, this tracks:
+ * - Agent execution traces with timing
+ * - File changes (additions, deletions, modifications)
+ * - Gradient measurements (before/after)
+ * - Cost metrics (tokens, USD)
+ * - CI pass/fail status
+ *
+ * Traces are stored as JSON Lines format for efficient querying.
+ *
+ * Usage:
+ * ```typescript
+ * import { recordTraceEvent } from './trace/index.js';
+ * await recordTraceEvent({ ... });
+ * ```
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { logDebug } from '../utils/logger.js';
+import type { TraceEvent, ChangeSet } from '../types/index.js';
+
+/**
+ * Create a trace event for an agent execution
+ */
+export function createTraceEvent(data: {
+  filePath: string;
+  mode: string;
+  gradientBefore: number;
+  gradientAfter: number;
+  metabolicCost: number;
+  efficiency: number;
+  ciPassed: boolean;
+  changes: ChangeSet;
+  costRecord: {
+    tokens_in: number;
+    tokens_out: number;
+    model: string;
+    estimated_usd: number;
+  };
+  notes?: string[];
+  taskId?: string;
+  agentId?: string;
+}): TraceEvent {
+  const now = new Date().toISOString();
+
+  return {
+    id: uuidv4(),
+    timestamp: now,
+    file_path: data.filePath,
+    mode: data.mode as any,
+    gradient_before: data.gradientBefore,
+    gradient_after: data.gradientAfter,
+    gradient_delta: data.gradientAfter - data.gradientBefore,
+    metabolic_cost: data.metabolicCost,
+    efficiency: data.efficiency,
+    ci_passed: data.ciPassed,
+    changes: data.changes,
+    notes: data.notes || [],
+    task_id: data.taskId,
+    agent_id: data.agentId,
+    cost: data.costRecord,
+  };
+}
+
+/**
+ * Record a trace event to the trace log
+ * In Phase 2, we store this in memory; in Phase 3+ it goes to persistent storage
+ */
+export async function recordTraceEvent(event: TraceEvent): Promise<void> {
+  logDebug('Trace event recorded', {
+    event_id: event.id,
+    file: event.file_path,
+    mode: event.mode,
+    gradient_delta: event.gradient_delta.toFixed(3),
+    cost_usd: event.cost.estimated_usd.toFixed(4),
+  });
+
+  // In Phase 2, trace events are collected in memory
+  // In Phase 3+, they will be written to persistent storage (JSON Lines format)
+  // For now, this is a no-op that validates the event structure
+}
+
+/**
+ * Export trace event type and utilities for Phase 2 integration
+ */
+export type { TraceEvent, ChangeSet } from '../types/index.js';