@dommaker/harness 0.13.0 → 0.13.2

package/src/context/__tests__/session-manager.test.ts

@@ -0,0 +1,300 @@
+/**
+ * SessionManager 测试
+ */
+
+import { SessionManager } from '../session-manager';
+import * as fs from 'fs';
+
+jest.mock('fs', () => ({
+  mkdirSync: jest.fn(),
+  appendFileSync: jest.fn(),
+  existsSync: jest.fn().mockReturnValue(false),
+  readFileSync: jest.fn().mockReturnValue(''),
+  readdirSync: jest.fn().mockReturnValue([]),
+  writeFileSync: jest.fn(),
+  statSync: jest.fn().mockReturnValue({
+    birthtime: new Date(),
+    mtime: new Date(),
+  }),
+}));
+
+const mockFs = fs as jest.Mocked<typeof fs>;
+
+describe('SessionManager', () => {
+  let manager: SessionManager;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    manager = new SessionManager('/test');
+  });
+
+  describe('createSession', () => {
+    it('应该创建会话', () => {
+      const handle = manager.createSession('session-1');
+      expect(handle.id).toBe('session-1');
+      expect(handle.events).toEqual([]);
+      expect(handle.createdAt).toBeDefined();
+    });
+
+    it('应该创建会话目录', () => {
+      manager.createSession('session-1');
+      expect(mockFs.mkdirSync).toHaveBeenCalled();
+    });
+  });
+
+  describe('appendToSession', () => {
+    it('应该追加事件', () => {
+      manager.createSession('session-1');
+      manager.appendToSession('session-1', {
+        type: 'user_message',
+        id: 'evt-1',
+        content: 'hello',
+        timestamp: new Date().toISOString(),
+      });
+
+      const handle = manager.getSession('session-1');
+      expect(handle!.events.length).toBe(1);
+      expect(handle!.events[0].content).toBe('hello');
+    });
+
+    it('应该持久化事件到 JSONL', () => {
+      manager.createSession('session-1');
+      manager.appendToSession('session-1', {
+        type: 'user_message',
+        id: 'evt-1',
+        content: 'hello',
+        timestamp: new Date().toISOString(),
+      });
+
+      expect(mockFs.appendFileSync).toHaveBeenCalled();
+    });
+
+    it('应该抛出当会话不存在', () => {
+      expect(() => {
+        manager.appendToSession('nonexistent', {
+          type: 'user_message',
+          id: 'evt-1',
+          content: 'hello',
+          timestamp: new Date().toISOString(),
+        });
+      }).toThrow('不存在');
+    });
+  });
+
+  describe('getWindowView', () => {
+    it('应该生成窗口视图', () => {
+      manager.createSession('session-1');
+      manager.appendToSession('session-1', {
+        type: 'system',
+        id: 'sys-1',
+        content: 'You are helpful.',
+        timestamp: 't1',
+      });
+      manager.appendToSession('session-1', {
+        type: 'user_message',
+        id: 'msg-1',
+        content: 'Hello',
+        timestamp: 't2',
+      });
+
+      const output = manager.getWindowView('session-1', {
+        total: 8000,
+        systemPrompt: 1000,
+        toolDefinitions: 500,
+        knowledge: 600,
+        notes: 300,
+        history: 5600,
+      });
+
+      expect(output.prompt).toContain('You are helpful.');
+      expect(output.prompt).toContain('Hello');
+      expect(output.snapshot).toBeDefined();
+    });
+
+    it('应该抛出当会话不存在', () => {
+      expect(() => {
+        manager.getWindowView('nonexistent', {
+          total: 8000,
+          systemPrompt: 1000,
+          toolDefinitions: 500,
+          knowledge: 600,
+          notes: 300,
+          history: 5600,
+        });
+      }).toThrow('不存在');
+    });
+  });
+
+  describe('checkpointSession', () => {
+    it('应该生成 checkpoint', () => {
+      manager.createSession('session-1');
+      manager.appendToSession('session-1', {
+        type: 'user_message',
+        id: 'msg-1',
+        content: 'hello',
+        timestamp: 't1',
+      });
+
+      const checkpoint = manager.checkpointSession('session-1');
+      expect(checkpoint.id).toContain('cp-');
+      expect(checkpoint.sessionId).toBe('session-1');
+      expect(checkpoint.eventCount).toBe(1);
+      expect(checkpoint.summary).toContain('1');
+    });
+
+    it('应该持久化 checkpoint', () => {
+      manager.createSession('session-1');
+      manager.checkpointSession('session-1');
+      expect(mockFs.writeFileSync).toHaveBeenCalled();
+    });
+
+    it('应该抛出当会话不存在', () => {
+      expect(() => {
+        manager.checkpointSession('nonexistent');
+      }).toThrow('不存在');
+    });
+  });
+
+  describe('restoreSession', () => {
+    it('应该从 checkpoint 恢复会话', () => {
+      (mockFs.existsSync as jest.Mock).mockImplementation((p: string) => {
+        if (p.includes('checkpoints')) return true;
+        if (p.includes('events.jsonl')) return true;
+        return false;
+      });
+      (mockFs.readdirSync as jest.Mock).mockReturnValue(['session-1']);
+      (mockFs.readFileSync as jest.Mock).mockImplementation((p: string) => {
+        if (p.includes('checkpoint')) {
+          return JSON.stringify({
+            id: 'cp-123',
+            sessionId: 'session-1',
+            timestamp: 't1',
+            eventCount: 2,
+            summary: 'test',
+          });
+        }
+        if (p.includes('events.jsonl')) {
+          return JSON.stringify({ type: 'user_message', id: '1', content: 'a', timestamp: 't1' }) + '\n' +
+                 JSON.stringify({ type: 'assistant_message', id: '2', content: 'b', timestamp: 't2' });
+        }
+        return '';
+      });
+
+      const handle = manager.restoreSession('cp-123');
+      expect(handle.id).toBe('session-1');
+      expect(handle.events.length).toBe(2);
+    });
+
+    it('应该抛出当 checkpoint 不存在', () => {
+      (mockFs.existsSync as jest.Mock).mockReturnValue(false);
+      (mockFs.readdirSync as jest.Mock).mockReturnValue([]);
+
+      expect(() => {
+        manager.restoreSession('nonexistent');
+      }).toThrow('不存在');
+    });
+  });
+
+  describe('getSessionInfo', () => {
+    it('应该抛出当会话不存在', () => {
+      expect(() => {
+        manager.getSessionInfo('nonexistent');
+      }).toThrow('不存在');
+    });
+
+    it('应该返回已存在的会话信息', () => {
+      manager.createSession('info-test');
+      const info = manager.getSessionInfo('info-test');
+      expect(info.id).toBe('info-test');
+    });
+  });
+
+  describe('getSession', () => {
+    it('应该返回会话', () => {
+      manager.createSession('session-1');
+      const handle = manager.getSession('session-1');
+      expect(handle).toBeDefined();
+      expect(handle!.id).toBe('session-1');
+    });
+
+    it('应该返回 undefined 当会话不存在', () => {
+      const handle = manager.getSession('nonexistent');
+      expect(handle).toBeUndefined();
+    });
+  });
+
+  describe('getTracker', () => {
+    it('应该返回 tracker', () => {
+      const tracker = manager.getTracker();
+      expect(tracker).toBeDefined();
+    });
+  });
+
+  describe('loadSession (disk loading via getSession)', () => {
+    it('loads session from disk when events.jsonl exists', () => {
+      (mockFs.existsSync as jest.Mock).mockImplementation((p: any) => {
+        if (typeof p === 'string' && p.includes('events.jsonl')) return true;
+        return false;
+      });
+      (mockFs.readFileSync as jest.Mock).mockImplementation((p: any) => {
+        if (typeof p === 'string' && p.includes('events.jsonl')) {
+          return JSON.stringify({ type: 'user_message', id: '1', content: 'hello', timestamp: 't1' }) + '\n';
+        }
+        return '';
+      });
+
+      const handle = manager.getSession('disk-loaded');
+      expect(handle).toBeDefined();
+      expect(handle!.events).toHaveLength(1);
+      expect(handle!.events[0].content).toBe('hello');
+    });
+  });
+
+  describe('getWindowView with all event types', () => {
+    it('handles all event types through eventsToSources', () => {
+      manager.createSession('session-event-types');
+      manager.appendToSession('session-event-types', {
+        type: 'system',
+        id: 'sys-1',
+        content: 'System prompt',
+        timestamp: 't1',
+      });
+      manager.appendToSession('session-event-types', {
+        type: 'assistant_message',
+        id: 'asst-1',
+        content: 'I will help',
+        timestamp: 't2',
+      });
+      manager.appendToSession('session-event-types', {
+        type: 'tool_call',
+        id: 'tool-1',
+        content: 'run test',
+        timestamp: 't3',
+      });
+      manager.appendToSession('session-event-types', {
+        type: 'tool_result',
+        id: 'tool-2',
+        content: 'test output',
+        timestamp: 't4',
+      });
+      manager.appendToSession('session-event-types', {
+        type: 'checkpoint',
+        id: 'cp-1',
+        content: 'session summary',
+        timestamp: 't5',
+      });
+
+      const output = manager.getWindowView('session-event-types', {
+        total: 8000,
+        systemPrompt: 1000,
+        toolDefinitions: 500,
+        knowledge: 600,
+        notes: 300,
+        history: 5600,
+      });
+
+      expect(output).toBeDefined();
+      expect(output.prompt).toBeDefined();
+    });
+  });
+});

package/src/context/__tests__/token-budget.test.ts

@@ -0,0 +1,338 @@
+/**
+ * TokenBudget 和 TokenEstimator 测试
+ */
+
+import { TokenBudget, TokenEstimator, AdaptiveTokenBudget } from '../token-budget';
+
+describe('TokenEstimator', () => {
+  describe('estimateText()', () => {
+    it('should return 0 for empty text', () => {
+      expect(TokenEstimator.estimateText('')).toBe(0);
+    });
+
+    it('should estimate English text', () => {
+      const text = 'Hello world'; // 11 chars / 4 ≈ 3 tokens
+      const estimate = TokenEstimator.estimateText(text);
+      expect(estimate).toBeGreaterThan(0);
+      expect(estimate).toBeLessThanOrEqual(5);
+    });
+
+    it('should estimate Chinese text', () => {
+      const text = '你好世界'; // 4 chars / 1.5 ≈ 3 tokens
+      const estimate = TokenEstimator.estimateText(text);
+      expect(estimate).toBeGreaterThan(0);
+      expect(estimate).toBeLessThanOrEqual(5);
+    });
+
+    it('should handle mixed text', () => {
+      const text = 'Hello 世界'; // Mixed
+      const estimate = TokenEstimator.estimateText(text);
+      expect(estimate).toBeGreaterThan(0);
+    });
+
+    it('should use ceil for rounding', () => {
+      const text = 'ab'; // 2 chars / 4 = 0.5 → ceil = 1
+      const estimate = TokenEstimator.estimateText(text);
+      expect(estimate).toBe(1);
+    });
+  });
+
+  describe('estimateObject()', () => {
+    it('should estimate object tokens', () => {
+      const obj = { name: 'test', value: 123 };
+      const estimate = TokenEstimator.estimateObject(obj);
+      expect(estimate).toBeGreaterThan(0);
+    });
+
+    it('should estimate nested object', () => {
+      const obj = { nested: { level1: { level2: 'deep' } } };
+      const estimate = TokenEstimator.estimateObject(obj);
+      expect(estimate).toBeGreaterThan(0);
+    });
+
+    it('should return 0 for circular reference', () => {
+      const obj: any = { name: 'test' };
+      obj.self = obj; // Circular reference
+      const estimate = TokenEstimator.estimateObject(obj);
+      expect(estimate).toBe(0);
+    });
+  });
+
+  describe('estimateArray()', () => {
+    it('should estimate array tokens', () => {
+      const arr = ['a', 'b', 'c'];
+      const estimate = TokenEstimator.estimateArray(arr);
+      expect(estimate).toBeGreaterThan(0);
+    });
+
+    it('should use custom item estimator', () => {
+      const items = [{ text: 'hello' }, { text: 'world' }];
+      const estimate = TokenEstimator.estimateArray(items, (item) =>
+        TokenEstimator.estimateText(item.text)
+      );
+      expect(estimate).toBeGreaterThan(0);
+    });
+
+    it('should handle empty array', () => {
+      const estimate = TokenEstimator.estimateArray([]);
+      expect(estimate).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe('createFieldEstimator()', () => {
+    it('should create field-based estimator', () => {
+      const estimator = TokenEstimator.createFieldEstimator<{ name: string; desc: string }>({
+        name: (v) => TokenEstimator.estimateText(v),
+        desc: (v) => TokenEstimator.estimateText(v),
+      });
+
+      const item = { name: 'test', desc: 'description' };
+      const estimate = estimator(item);
+      expect(estimate).toBeGreaterThan(0);
+    });
+  });
+});
+
+describe('TokenBudget', () => {
+  describe('constructor', () => {
+    it('should create budget with given amount', () => {
+      const budget = new TokenBudget(1000);
+      expect(budget.total).toBe(1000);
+      expect(budget.used).toBe(0);
+      expect(budget.remaining).toBe(1000);
+    });
+  });
+
+  describe('reserve()', () => {
+    it('should reserve tokens', () => {
+      const budget = new TokenBudget(1000);
+      const success = budget.reserve(200);
+      expect(success).toBe(true);
+      expect(budget.remaining).toBe(800);
+    });
+
+    it('should fail when not enough remaining', () => {
+      const budget = new TokenBudget(100);
+      const success = budget.reserve(200);
+      expect(success).toBe(false);
+      expect(budget.remaining).toBe(100);
+    });
+
+    it('should allow multiple reserves', () => {
+      const budget = new TokenBudget(1000);
+      budget.reserve(200);
+      budget.reserve(300);
+      expect(budget.remaining).toBe(500);
+    });
+  });
+
+  describe('release()', () => {
+    it('should release reserved tokens', () => {
+      const budget = new TokenBudget(1000);
+      budget.reserve(200);
+      budget.release(100);
+      expect(budget.remaining).toBe(900);
+    });
+
+    it('should not go below zero', () => {
+      const budget = new TokenBudget(1000);
+      budget.reserve(50);
+      budget.release(100); // More than reserved
+      expect(budget.remaining).toBe(1000);
+    });
+  });
+
+  describe('consume()', () => {
+    it('should consume tokens', () => {
+      const budget = new TokenBudget(1000);
+      const success = budget.consume(100);
+      expect(success).toBe(true);
+      expect(budget.used).toBe(100);
+      expect(budget.remaining).toBe(900);
+    });
+
+    it('should fail when not enough remaining', () => {
+      const budget = new TokenBudget(100);
+      const success = budget.consume(200);
+      expect(success).toBe(false);
+      expect(budget.used).toBe(0);
+    });
+  });
+
+  describe('reset()', () => {
+    it('should reset used tokens', () => {
+      const budget = new TokenBudget(1000);
+      budget.consume(500);
+      budget.reset();
+      expect(budget.used).toBe(0);
+      expect(budget.remaining).toBe(1000);
+    });
+
+    it('should update total with new budget', () => {
+      const budget = new TokenBudget(1000);
+      budget.consume(500);
+      budget.reset(2000);
+      expect(budget.total).toBe(2000);
+      expect(budget.used).toBe(0);
+    });
+  });
+
+  describe('usageRatio', () => {
+    it('should return usage ratio', () => {
+      const budget = new TokenBudget(1000);
+      budget.consume(500);
+      expect(budget.usageRatio).toBe(0.5);
+    });
+
+    it('should return 0 when not used', () => {
+      const budget = new TokenBudget(1000);
+      expect(budget.usageRatio).toBe(0);
+    });
+  });
+
+  describe('status', () => {
+    it('should return healthy when ratio < 0.5', () => {
+      const budget = new TokenBudget(1000);
+      budget.consume(400);
+      expect(budget.status).toBe('healthy');
+    });
+
+    it('should return warning when 0.5 <= ratio < 0.8', () => {
+      const budget = new TokenBudget(1000);
+      budget.consume(600);
+      expect(budget.status).toBe('warning');
+    });
+
+    it('should return critical when ratio >= 0.8', () => {
+      const budget = new TokenBudget(1000);
+      budget.consume(900);
+      expect(budget.status).toBe('critical');
+    });
+  });
+
+  describe('getReport()', () => {
+    it('should return budget report', () => {
+      const budget = new TokenBudget(1000);
+      budget.consume(300);
+      budget.reserve(200);
+
+      const report = budget.getReport();
+
+      expect(report.total).toBe(1000);
+      expect(report.used).toBe(300);
+      expect(report.reserved).toBe(200);
+      expect(report.remaining).toBe(500);
+      expect(report.usageRatio).toBe(0.3);
+      expect(report.status).toBe('healthy');
+    });
+  });
+
+  describe('forceConsume()', () => {
+    it('should consume even beyond budget', () => {
+      const budget = new TokenBudget(100);
+      budget.forceConsume(200);
+      expect(budget.used).toBe(200);
+      expect(budget.remaining).toBe(-100);
+    });
+  });
+
+  describe('addBudget()', () => {
+    it('should increase total budget', () => {
+      const budget = new TokenBudget(1000);
+      budget.addBudget(500);
+      expect(budget.total).toBe(1500);
+    });
+  });
+
+  describe('canAfford()', () => {
+    it('should return true when affordable', () => {
+      const budget = new TokenBudget(1000);
+      expect(budget.canAfford(500)).toBe(true);
+    });
+
+    it('should return false when not affordable', () => {
+      const budget = new TokenBudget(100);
+      expect(budget.canAfford(200)).toBe(false);
+    });
+  });
+});
+
+describe('AdaptiveTokenBudget', () => {
+  describe('recordActualUsage()', () => {
+    it('should record usage history', () => {
+      const budget = new AdaptiveTokenBudget(1000);
+      budget.recordActualUsage(500);
+      budget.recordActualUsage(600);
+      expect(budget.getAverageUsage()).toBe(550);
+    });
+
+    it('should trim history when exceeding max size', () => {
+      const budget = new AdaptiveTokenBudget(1000);
+      for (let i = 0; i < 15; i++) {
+        budget.recordActualUsage(100 + i);
+      }
+      expect(budget.getAverageUsage()).toBeGreaterThan(0);
+    });
+  });
+
+  describe('getAverageUsage()', () => {
+    it('should return 0 when no history', () => {
+      const budget = new AdaptiveTokenBudget(1000);
+      expect(budget.getAverageUsage()).toBe(0);
+    });
+  });
+
+  describe('predictNeed()', () => {
+    it('should return total when no history', () => {
+      const budget = new AdaptiveTokenBudget(1000);
+      expect(budget.predictNeed()).toBe(1000);
+    });
+
+    it('should predict based on history', () => {
+      const budget = new AdaptiveTokenBudget(1000);
+      budget.recordActualUsage(400);
+      budget.recordActualUsage(500);
+      budget.recordActualUsage(600);
+      const predicted = budget.predictNeed(0.9);
+      expect(predicted).toBeGreaterThan(0);
+    });
+  });
+
+  describe('suggestBudgetAdjustment()', () => {
+    it('should suggest increase when ratio > 0.9', () => {
+      const budget = new AdaptiveTokenBudget(1000);
+      for (let i = 0; i < 5; i++) {
+        budget.recordActualUsage(950);
+      }
+      const suggestion = budget.suggestBudgetAdjustment();
+      expect(suggestion.action).toBe('increase');
+      expect(suggestion.suggestedBudget).toBeGreaterThan(1000);
+    });
+
+    it('should suggest decrease when ratio < 0.5 and history >= 5', () => {
+      const budget = new AdaptiveTokenBudget(1000);
+      for (let i = 0; i < 5; i++) {
+        budget.recordActualUsage(100);
+      }
+      const suggestion = budget.suggestBudgetAdjustment();
+      expect(suggestion.action).toBe('decrease');
+    });
+
+    it('should maintain when ratio is moderate', () => {
+      const budget = new AdaptiveTokenBudget(1000);
+      for (let i = 0; i < 5; i++) {
+        budget.recordActualUsage(600);
+      }
+      const suggestion = budget.suggestBudgetAdjustment();
+      expect(suggestion.action).toBe('maintain');
+    });
+
+    it('should maintain when history < 5 even if low usage', () => {
+      const budget = new AdaptiveTokenBudget(1000);
+      budget.recordActualUsage(100);
+      budget.recordActualUsage(100);
+      const suggestion = budget.suggestBudgetAdjustment();
+      expect(suggestion.action).toBe('maintain');
+    });
+  });
+});