@dommaker/harness 0.13.0 → 0.13.2

package/src/__tests__/traces.test.ts

@@ -0,0 +1,347 @@
+/**
+ * Execution Trace 测试
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { TraceCollector } from '../monitoring/traces';
+import { TraceAnalyzer } from '../monitoring/trace-analyzer';
+import type { ExecutionTrace } from '../types/trace';
+
+describe('TraceCollector', () => {
+  let tempDir: string;
+  let collector: TraceCollector;
+
+  beforeEach(() => {
+    tempDir = path.join(os.tmpdir(), `harness-traces-${Date.now()}`);
+    fs.mkdirSync(tempDir, { recursive: true });
+    collector = new TraceCollector({
+      traceFile: path.join(tempDir, 'execution.log'),
+      enabled: true,
+    });
+  });
+
+  afterEach(() => {
+    // 清理临时目录
+    if (fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true });
+    }
+  });
+
+  test('should record a trace', () => {
+    collector.record({
+      constraintId: 'no_fix_without_root_cause',
+      level: 'iron_law',
+      timestamp: Date.now(),
+      result: 'fail',
+      operation: 'code_implementation',
+      severity: 'error',
+    });
+
+    const traces = collector.read();
+    expect(traces.length).toBe(1);
+    expect(traces[0].constraintId).toBe('no_fix_without_root_cause');
+    expect(traces[0].result).toBe('fail');
+  });
+
+  test('should record multiple traces', () => {
+    for (let i = 0; i < 5; i++) {
+      collector.recordPass('test_constraint', 'guideline');
+    }
+
+    const traces = collector.read();
+    expect(traces.length).toBe(5);
+    expect(traces.every(t => t.result === 'pass')).toBe(true);
+  });
+
+  test('should filter traces by constraint ID', () => {
+    collector.recordPass('constraint_a', 'iron_law');
+    collector.recordFail('constraint_b', 'guideline');
+    collector.recordBypass('constraint_a', 'iron_law', 'user reason');
+
+    const traces = collector.read({ constraintId: 'constraint_a' });
+    expect(traces.length).toBe(2);
+    expect(traces.every(t => t.constraintId === 'constraint_a')).toBe(true);
+  });
+
+  test('should filter traces by time range', () => {
+    const now = Date.now();
+    const oneHourAgo = now - 3600 * 1000;
+
+    collector.record({
+      constraintId: 'old_trace',
+      level: 'guideline',
+      timestamp: oneHourAgo - 1000, // 1小时前更早
+      result: 'pass',
+    });
+
+    collector.record({
+      constraintId: 'new_trace',
+      level: 'guideline',
+      timestamp: now,
+      result: 'pass',
+    });
+
+    const traces = collector.read({
+      timeRange: { start: oneHourAgo, end: now + 1000 },
+    });
+
+    expect(traces.length).toBe(1);
+    expect(traces[0].constraintId).toBe('new_trace');
+  });
+
+  test('should read recent traces', () => {
+    // 记录一些 traces
+    for (let i = 0; i < 10; i++) {
+      collector.record({
+        constraintId: `constraint_${i}`,
+        level: 'guideline',
+        timestamp: Date.now() - i * 60 * 1000, // 每分钟一个
+        result: i % 2 === 0 ? 'pass' : 'fail',
+      });
+    }
+
+    // 读取最近 5 分钟
+    const traces = collector.readRecent(5 / 60); // 5 分钟 = 5/60 小时
+    expect(traces.length).toBeLessThanOrEqual(6); // 最多 6 个（包括当前）
+  });
+
+  test('should provide stats', () => {
+    for (let i = 0; i < 10; i++) {
+      collector.recordPass(`constraint_${i}`, 'guideline');
+    }
+
+    const stats = collector.getStats();
+    expect(stats.fileExists).toBe(true);
+    expect(stats.totalLines).toBe(10);
+  });
+
+  test('should filter traces by result', () => {
+    collector.recordFail('constraint_a', 'guideline');
+    collector.recordPass('constraint_b', 'guideline');
+
+    const traces = collector.read({ result: 'fail' });
+    expect(traces).toHaveLength(1);
+    expect(traces[0].constraintId).toBe('constraint_a');
+  });
+
+  test('should filter traces by projectPath', () => {
+    collector.record({
+      constraintId: 'c1', level: 'guideline', timestamp: Date.now(),
+      result: 'pass', projectPath: '/project/a', severity: 'info',
+    });
+    collector.record({
+      constraintId: 'c2', level: 'guideline', timestamp: Date.now(),
+      result: 'pass', projectPath: '/project/b', severity: 'info',
+    });
+
+    const traces = collector.read({ projectPath: '/project/a' });
+    expect(traces).toHaveLength(1);
+    expect(traces[0].constraintId).toBe('c1');
+  });
+
+  test('should filter traces by sessionId', () => {
+    collector.record({
+      constraintId: 'c1', level: 'guideline', timestamp: Date.now(),
+      result: 'pass', sessionId: 'session-1', severity: 'info',
+    });
+    collector.record({
+      constraintId: 'c2', level: 'guideline', timestamp: Date.now(),
+      result: 'pass', sessionId: 'session-2', severity: 'info',
+    });
+
+    const traces = collector.read({ sessionId: 'session-2' });
+    expect(traces).toHaveLength(1);
+    expect(traces[0].constraintId).toBe('c2');
+  });
+
+  test('should clean up old backup files', () => {
+    // Create old backup files
+    const dir = path.dirname(collector['traceFile']);
+    const oldFile = path.join(dir, 'execution-old.log');
+    fs.writeFileSync(oldFile, 'old content', 'utf-8');
+    // Set mtime to 2 years ago
+    const oldDate = new Date(Date.now() - 2 * 365 * 24 * 3600 * 1000);
+    fs.utimesSync(oldFile, oldDate, oldDate);
+
+    // Create recent backup file (not cleaned)
+    const recentFile = path.join(dir, 'execution-recent.log');
+    fs.writeFileSync(recentFile, 'recent content', 'utf-8');
+
+    // Cleanup files older than 365 days
+    const deletedCount = collector.cleanupOldFiles(365);
+    expect(deletedCount).toBe(1);
+  });
+
+  test('should return 0 when backup dir does not exist', () => {
+    const result = collector.cleanupOldFiles(30);
+    // Dir exists (created by constructor), so this won't hit line 259.
+    // Create a collector with a path in non-existent dir to test that branch.
+    const tmpRoot = path.join(os.tmpdir(), `harness-traces-nonexistent-${Date.now()}`);
+    const c = new (require('../monitoring/traces').TraceCollector)({
+      traceFile: path.join(tmpRoot, 'deep', 'traces.log'),
+    });
+    // Delete the directory the collector just created
+    require('fs').rmSync(tmpRoot, { recursive: true, force: true });
+    expect(c.cleanupOldFiles(30)).toBe(0);
+  });
+});
+
+describe('TraceAnalyzer', () => {
+  let tempDir: string;
+  let collector: TraceCollector;
+  let analyzer: TraceAnalyzer;
+
+  beforeEach(() => {
+    tempDir = path.join(os.tmpdir(), `harness-traces-${Date.now()}`);
+    fs.mkdirSync(tempDir, { recursive: true });
+    collector = new TraceCollector({
+      traceFile: path.join(tempDir, 'execution.log'),
+      enabled: true,
+    });
+    analyzer = new TraceAnalyzer(collector, {
+      summaryFile: path.join(tempDir, 'summary.json'),
+    });
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true });
+    }
+  });
+
+  test('should summarize traces', () => {
+    // 记录不同约束的 traces
+    for (let i = 0; i < 10; i++) {
+      collector.record({
+        constraintId: 'constraint_a',
+        level: 'guideline',
+        timestamp: Date.now() - i * 60 * 1000,
+        result: i < 7 ? 'pass' : 'fail',
+      });
+    }
+
+    for (let i = 0; i < 5; i++) {
+      collector.record({
+        constraintId: 'constraint_b',
+        level: 'iron_law',
+        timestamp: Date.now() - i * 60 * 1000,
+        result: i < 3 ? 'pass' : 'bypassed',
+      });
+    }
+
+    const traces = collector.read();
+    const summaries = analyzer.summarize(traces);
+
+    expect(summaries.length).toBe(2);
+
+    const summaryA = summaries.find(s => s.constraintId === 'constraint_a');
+    expect(summaryA).toBeDefined();
+    expect(summaryA!.totalChecks).toBe(10);
+    expect(summaryA!.passRate).toBeCloseTo(0.7, 1);
+    expect(summaryA!.failRate).toBeCloseTo(0.3, 1);
+
+    const summaryB = summaries.find(s => s.constraintId === 'constraint_b');
+    expect(summaryB).toBeDefined();
+    expect(summaryB!.bypassRate).toBeCloseTo(0.4, 1);
+  });
+
+  test('should detect high bypass rate anomaly', () => {
+    // 记录高绕过率的 traces
+    for (let i = 0; i < 10; i++) {
+      collector.record({
+        constraintId: 'problematic_constraint',
+        level: 'guideline',
+        timestamp: Date.now(),
+        result: i < 3 ? 'pass' : 'bypassed', // 70% 绕过率
+      });
+    }
+
+    const traces = collector.read();
+    const summaries = analyzer.summarize(traces);
+    const anomalies = analyzer.detectAnomalies(summaries);
+
+    expect(anomalies.length).toBeGreaterThan(0);
+    expect(anomalies.some(a => a.type === 'high_bypass_rate')).toBe(true);
+  });
+
+  test('should detect rising fail rate anomaly', () => {
+    const now = Date.now();
+
+    // 前半段：低失败率
+    for (let i = 0; i < 20; i++) {
+      collector.record({
+        constraintId: 'rising_fail_constraint',
+        level: 'iron_law',
+        timestamp: now - (40 - i) * 60 * 1000,
+        result: 'pass',
+      });
+    }
+
+    // 后半段：高失败率（趋势上升）
+    for (let i = 0; i < 20; i++) {
+      collector.record({
+        constraintId: 'rising_fail_constraint',
+        level: 'iron_law',
+        timestamp: now - i * 60 * 1000,
+        result: i < 15 ? 'fail' : 'pass', // 75% 失败率
+      });
+    }
+
+    const traces = collector.read();
+    const summaries = analyzer.summarize(traces);
+
+    // 检查趋势
+    const summary = summaries.find(s => s.constraintId === 'rising_fail_constraint');
+    expect(summary?.recentTrend).toBe('falling'); // 通过率下降 = 失败率上升
+  });
+
+  test('should calculate trend correctly', () => {
+    const now = Date.now();
+
+    // 稳定趋势：前后通过率相同
+    for (let i = 0; i < 10; i++) {
+      collector.record({
+        constraintId: 'stable_constraint',
+        level: 'guideline',
+        timestamp: now - i * 60 * 1000,
+        result: 'pass',
+      });
+    }
+
+    const traces = collector.readByConstraint('stable_constraint');
+    const summaries = analyzer.summarize(traces);
+
+    expect(summaries[0].recentTrend).toBe('stable');
+  });
+
+  test('should save and load summary', () => {
+    for (let i = 0; i < 5; i++) {
+      collector.recordPass('test_constraint', 'guideline');
+    }
+
+    const summaries = analyzer.analyzeRecent(1);
+    analyzer.saveSummary(summaries);
+
+    const loaded = analyzer.loadSummary();
+    expect(loaded).toBeDefined();
+    expect(loaded!.length).toBe(1);
+    expect(loaded![0].constraintId).toBe('test_constraint');
+  });
+
+  test('should generate report', () => {
+    for (let i = 0; i < 5; i++) {
+      collector.recordPass('constraint_a', 'guideline');
+      collector.recordFail('constraint_b', 'iron_law');
+    }
+
+    const summaries = analyzer.analyzeRecent(1);
+    const anomalies = analyzer.detectAnomalies(summaries);
+    const report = analyzer.generateReport(summaries, anomalies);
+
+    expect(report).toContain('# Harness Trace Report');
+    expect(report).toContain('constraint_a');
+    expect(report).toContain('constraint_b');
+  });
+});

package/src/agents/CONTEXT.md

@@ -0,0 +1,21 @@
+# agents/
+
+## 职责
+Agent 生命周期管理：Agent 状态机(init → running → paused → completed → failed)。
+
+## 核心导出
+- `types.ts` — Agent 生命周期类型定义
+- `lifecycle.ts` — AgentLifecycle 状态机
+
+## 依赖关系
+- 依赖 `src/types/` 公共类型
+- 被 `src/context/session-manager.ts` 消费
+
+## 约定
+- Agent 状态机 5 状态: init → running → paused → completed → failed
+- 状态转换由事件驱动
+- 生命周期管理不包含业务逻辑
+
+## 注意事项
+- Phase 2 实现的 Agent 状态管理
+- 状态转换可被外部监听(hook)

package/src/agents/__tests__/lifecycle.test.ts

@@ -0,0 +1,248 @@
+import { AgentLifecycle } from '../lifecycle';
+import type { AgentConfig } from '../types';
+
+function makeConfig(overrides: Partial<AgentConfig> = {}): AgentConfig {
+  return {
+    id: 'agent-1',
+    name: 'Test Agent',
+    workingDir: '/tmp',
+    ...overrides,
+  };
+}
+
+describe('AgentLifecycle', () => {
+  describe('register', () => {
+    it('注册 Agent 返回 idle 状态', () => {
+      const lc = new AgentLifecycle();
+      const state = lc.register(makeConfig());
+      expect(state.id).toBe('agent-1');
+      expect(state.status).toBe('idle');
+      expect(state.retryCount).toBe(0);
+    });
+
+    it('注册多个 Agent', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig({ id: 'a1' }));
+      lc.register(makeConfig({ id: 'a2' }));
+      expect(lc.getAllStates()).toHaveLength(2);
+    });
+  });
+
+  describe('start', () => {
+    it('启动已注册的 Agent', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig());
+      const state = lc.start('agent-1');
+      expect(state!.status).toBe('running');
+      expect(state!.startedAt).toBeTruthy();
+    });
+
+    it('启动未注册的 Agent 返回 undefined', () => {
+      const lc = new AgentLifecycle();
+      expect(lc.start('unknown')).toBeUndefined();
+    });
+  });
+
+  describe('complete', () => {
+    it('完成 Agent', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig());
+      lc.start('agent-1');
+      const state = lc.complete('agent-1', { result: 'ok' });
+      expect(state!.status).toBe('completed');
+      expect(state!.completedAt).toBeTruthy();
+      expect(state!.metadata.result).toBe('ok');
+    });
+
+    it('完成未注册的 Agent 返回 undefined', () => {
+      const lc = new AgentLifecycle();
+      expect(lc.complete('unknown')).toBeUndefined();
+    });
+  });
+
+  describe('fail', () => {
+    it('标记 Agent 失败', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig());
+      lc.start('agent-1');
+      const state = lc.fail('agent-1', 'boom');
+      expect(state!.status).toBe('failed');
+      expect(state!.error).toBe('boom');
+    });
+
+    it('失败后应用回退策略重试', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig({ maxRetries: 3 }));
+      lc.addFallbackStrategy({
+        condition: (s) => s.status === 'failed' && s.retryCount < 3,
+        action: 'retry',
+      });
+      lc.start('agent-1');
+      const state = lc.fail('agent-1', 'error');
+      expect(state!.status).toBe('running');
+      expect(state!.retryCount).toBe(1);
+      expect(state!.error).toBeUndefined();
+    });
+
+    it('未注册的 Agent 返回 undefined', () => {
+      const lc = new AgentLifecycle();
+      expect(lc.fail('unknown', 'err')).toBeUndefined();
+    });
+
+    it('未配置 maxRetries 时使用默认值 3', () => {
+      const lc = new AgentLifecycle();
+      // 不设置 maxRetries，触发 ?? 3 回退
+      lc.register(makeConfig());
+      lc.addFallbackStrategy({
+        condition: (s) => s.status === 'failed',
+        action: 'retry',
+      });
+      lc.start('agent-1');
+      const state = lc.fail('agent-1', 'err');
+      expect(state!.status).toBe('running');
+      expect(state!.retryCount).toBe(1);
+    });
+
+    it('达到最大重试次数后不再重试', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig({ maxRetries: 1 }));
+      lc.addFallbackStrategy({
+        condition: (s) => s.status === 'failed' && s.retryCount < 1,
+        action: 'retry',
+      });
+      lc.start('agent-1');
+      lc.fail('agent-1', 'err1'); // retry → running
+      lc.fail('agent-1', 'err2'); // no retry, stays failed
+      const state = lc.getState('agent-1');
+      expect(state!.status).toBe('failed');
+    });
+
+    it('degrade 策略将状态设为 paused', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig());
+      lc.addFallbackStrategy({
+        condition: (s) => s.status === 'failed',
+        action: 'degrade',
+      });
+      lc.start('agent-1');
+      const state = lc.fail('agent-1', 'err');
+      expect(state!.status).toBe('paused');
+      expect(state!.metadata.degraded).toBe(true);
+    });
+
+    it('abort 策略将状态设为 terminated', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig());
+      lc.addFallbackStrategy({
+        condition: (s) => s.status === 'failed',
+        action: 'abort',
+      });
+      lc.start('agent-1');
+      const state = lc.fail('agent-1', 'err');
+      expect(state!.status).toBe('terminated');
+    });
+
+    it('notify 策略不改变状态', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig());
+      lc.addFallbackStrategy({
+        condition: (s) => s.status === 'failed',
+        action: 'notify',
+      });
+      lc.start('agent-1');
+      const state = lc.fail('agent-1', 'err');
+      expect(state!.status).toBe('failed');
+    });
+  });
+
+  describe('terminate', () => {
+    it('终止 Agent', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig());
+      lc.start('agent-1');
+      const state = lc.terminate('agent-1');
+      expect(state!.status).toBe('terminated');
+      expect(state!.completedAt).toBeTruthy();
+    });
+
+    it('终止未注册的 Agent 返回 undefined', () => {
+      const lc = new AgentLifecycle();
+      expect(lc.terminate('unknown')).toBeUndefined();
+    });
+  });
+
+  describe('getState / getByStatus', () => {
+    it('获取指定 Agent 状态', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig());
+      const state = lc.getState('agent-1');
+      expect(state).toBeDefined();
+      expect(state!.id).toBe('agent-1');
+    });
+
+    it('按状态过滤', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig({ id: 'a1' }));
+      lc.register(makeConfig({ id: 'a2' }));
+      lc.start('a1');
+      expect(lc.getByStatus('running')).toHaveLength(1);
+      expect(lc.getByStatus('idle')).toHaveLength(1);
+    });
+  });
+
+  describe('事件', () => {
+    it('start 触发事件', () => {
+      const lc = new AgentLifecycle();
+      const events: any[] = [];
+      lc.onEvent((e) => events.push(e));
+      lc.register(makeConfig());
+      lc.start('agent-1');
+      expect(events).toHaveLength(1);
+      expect(events[0].type).toBe('start');
+    });
+
+    it('complete 触发事件', () => {
+      const lc = new AgentLifecycle();
+      const events: any[] = [];
+      lc.onEvent((e) => events.push(e));
+      lc.register(makeConfig());
+      lc.start('agent-1');
+      lc.complete('agent-1');
+      expect(events.some(e => e.type === 'complete')).toBe(true);
+    });
+
+    it('fail 触发 error 事件', () => {
+      const lc = new AgentLifecycle();
+      const events: any[] = [];
+      lc.onEvent((e) => events.push(e));
+      lc.register(makeConfig());
+      lc.start('agent-1');
+      lc.fail('agent-1', 'err');
+      expect(events.some(e => e.type === 'error')).toBe(true);
+    });
+
+    it('事件处理器异常不影响主流程', () => {
+      const lc = new AgentLifecycle();
+      lc.onEvent(() => { throw new Error('handler error'); });
+      lc.register(makeConfig());
+      expect(() => lc.start('agent-1')).not.toThrow();
+    });
+  });
+
+  describe('remove / clear', () => {
+    it('remove 移除 Agent', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig());
+      expect(lc.remove('agent-1')).toBe(true);
+      expect(lc.getState('agent-1')).toBeUndefined();
+    });
+
+    it('clear 清空所有 Agent', () => {
+      const lc = new AgentLifecycle();
+      lc.register(makeConfig({ id: 'a1' }));
+      lc.register(makeConfig({ id: 'a2' }));
+      lc.clear();
+      expect(lc.getAllStates()).toHaveLength(0);
+    });
+  });
+});

package/src/agents/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './lifecycle';