@dommaker/harness 0.13.0 → 0.13.2

package/src/context/session-manager.ts

@@ -0,0 +1,343 @@
+/**
+ * Session Manager
+ *
+ * 解耦 Session（持久事件日志）/ Harness（窗口视图）/ Sandbox（执行环境）
+ * Session 事件存储：.harness/sessions/{id}/events.jsonl
+ * Checkpoint 存储：.harness/sessions/{id}/checkpoints/
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { TokenPipeline } from './token-pipeline';
+import { ContextTracker } from '../monitoring/context-tracker';
+import type {
+  SessionEvent,
+  SessionHandle,
+  SessionCheckpoint,
+  TokenBudgetAllocation,
+  PipelineOutput,
+  ContextSource,
+} from './types';
+
+export class SessionManager {
+  private basePath: string;
+  private sessions: Map<string, SessionHandle> = new Map();
+  private pipeline: TokenPipeline;
+  private tracker: ContextTracker;
+
+  constructor(basePath?: string) {
+    this.basePath = basePath || process.cwd();
+    this.pipeline = new TokenPipeline();
+    this.tracker = new ContextTracker(this.basePath);
+  }
+
+  /**
+   * 创建会话
+   */
+  createSession(id: string): SessionHandle {
+    const handle: SessionHandle = {
+      id,
+      events: [],
+      createdAt: new Date().toISOString(),
+      lastActiveAt: new Date().toISOString(),
+    };
+
+    this.sessions.set(id, handle);
+
+    // 创建会话目录
+    const sessionDir = this.getSessionDir(id);
+    try {
+      fs.mkdirSync(sessionDir, { recursive: true });
+    } catch {
+      // 目录创建失败，静默处理
+    }
+
+    return handle;
+  }
+
+  /**
+   * 从磁盘加载已持久化的会话（S2）
+   *
+   * 跨实例恢复：当新的 SessionManager 实例创建时，内存中 sessions Map 为空，
+   * 但磁盘上可能有之前持久化的事件。此方法从 events.jsonl 重建 SessionHandle。
+   *
+   * @returns 加载成功返回 SessionHandle，磁盘无数据返回 undefined
+   */
+  loadSession(id: string): SessionHandle | undefined {
+    // 先检查内存
+    const cached = this.sessions.get(id);
+    if (cached) return cached;
+
+    // 从磁盘恢复
+    const eventsPath = path.join(this.getSessionDir(id), 'events.jsonl');
+    try {
+      if (!fs.existsSync(eventsPath)) return undefined;
+
+      const content = fs.readFileSync(eventsPath, 'utf-8');
+      const lines = content.trim().split('\n').filter(Boolean);
+      if (lines.length === 0) return undefined;
+
+      const events: SessionEvent[] = [];
+      for (const line of lines) {
+        try {
+          events.push(JSON.parse(line) as SessionEvent);
+        } catch {
+          // 跳过损坏行
+        }
+      }
+
+      const stat = fs.statSync(eventsPath);
+      const handle: SessionHandle = {
+        id,
+        events,
+        createdAt: stat.birthtime.toISOString(),
+        lastActiveAt: stat.mtime.toISOString(),
+      };
+
+      this.sessions.set(id, handle);
+      return handle;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * 获取会话（自动从磁盘加载，S2）
+   *
+   * 先查内存缓存，未命中则从磁盘恢复。
+   */
+  getSession(id: string): SessionHandle | undefined {
+    return this.sessions.get(id) ?? this.loadSession(id);
+  }
+
+  /**
+   * 获取会话摘要信息（S2）
+   *
+   * 跨实例安全的查询接口。返回轻量级摘要，不加载完整事件列表。
+   */
+  getSessionInfo(id: string): SessionHandle {
+    const handle = this.getSession(id);
+    if (!handle) {
+      throw new Error(`会话 ${id} 不存在`);
+    }
+    return handle;
+  }
+
+  /**
+   * 追加事件到会话（自动从磁盘加载，S2）
+   */
+  appendToSession(id: string, event: SessionEvent): void {
+    const handle = this.getSession(id);
+    if (!handle) {
+      throw new Error(`会话 ${id} 不存在`);
+    }
+
+    handle.events.push(event);
+    handle.lastActiveAt = new Date().toISOString();
+
+    // 持久化到 JSONL
+    this.appendEvent(id, event);
+  }
+
+  /**
+   * 获取当前轮窗口视图（自动从磁盘加载，S2）
+   *
+   * 将 session 事件转换为 ContextSource，通过 TokenPipeline 生成 prompt
+   */
+  getWindowView(id: string, budget: TokenBudgetAllocation): PipelineOutput {
+    const handle = this.getSession(id);
+    if (!handle) {
+      throw new Error(`会话 ${id} 不存在`);
+    }
+
+    // 将事件转换为 ContextSource
+    const sources = this.eventsToSources(handle.events);
+
+    // 通过 pipeline 生成窗口视图
+    const output = this.pipeline.run({ sources, budget });
+
+    // 记录快照
+    this.tracker.record(output.snapshot);
+
+    return output;
+  }
+
+  /**
+   * 生成 checkpoint（自动从磁盘加载，S2）
+   */
+  checkpointSession(id: string): SessionCheckpoint {
+    const handle = this.getSession(id);
+    if (!handle) {
+      throw new Error(`会话 ${id} 不存在`);
+    }
+
+    const checkpoint: SessionCheckpoint = {
+      id: `cp-${Date.now()}`,
+      sessionId: id,
+      timestamp: new Date().toISOString(),
+      eventCount: handle.events.length,
+      summary: this.generateCheckpointSummary(handle.events),
+    };
+
+    // 持久化 checkpoint
+    this.saveCheckpoint(id, checkpoint);
+
+    return checkpoint;
+  }
+
+  /**
+   * 从 checkpoint 恢复会话
+   */
+  restoreSession(checkpointId: string): SessionHandle {
+    // 搜索所有会话的 checkpoints
+    const sessionsDir = path.join(this.basePath, '.harness', 'sessions');
+
+    try {
+      const sessionIds = fs.readdirSync(sessionsDir);
+
+      for (const sessionId of sessionIds) {
+        const checkpointPath = path.join(sessionsDir, sessionId, 'checkpoints', `${checkpointId}.json`);
+
+        if (fs.existsSync(checkpointPath)) {
+          const checkpointData = JSON.parse(fs.readFileSync(checkpointPath, 'utf-8')) as SessionCheckpoint;
+
+          // 恢复会话
+          const handle = this.createSession(sessionId);
+
+          // 从 events.jsonl 恢复事件
+          const eventsPath = path.join(sessionsDir, sessionId, 'events.jsonl');
+          if (fs.existsSync(eventsPath)) {
+            const content = fs.readFileSync(eventsPath, 'utf-8');
+            const lines = content.trim().split('\n').filter(Boolean);
+
+            // 只恢复 checkpoint 之前的事件
+            const events = lines
+              .slice(0, checkpointData.eventCount)
+              .map(line => {
+                try {
+                  return JSON.parse(line) as SessionEvent;
+                } catch {
+                  return null;
+                }
+              })
+              .filter((e): e is SessionEvent => e !== null);
+
+            handle.events = events;
+          }
+
+          return handle;
+        }
+      }
+    } catch {
+      // 恢复失败
+    }
+
+    throw new Error(`Checkpoint ${checkpointId} 不存在`);
+  }
+
+  /**
+   * 获取 tracker
+   */
+  getTracker(): ContextTracker {
+    return this.tracker;
+  }
+
+  /**
+   * 将事件转换为 ContextSource
+   */
+  private eventsToSources(events: SessionEvent[]): ContextSource[] {
+    return events.map(event => {
+      let priority: number;
+      let type: ContextSource['type'];
+
+      switch (event.type) {
+        case 'system':
+          priority = 1;
+          type = 'system_prompt';
+          break;
+        case 'user_message':
+          priority = 6;
+          type = 'user_message';
+          break;
+        case 'assistant_message':
+          priority = 5;
+          type = 'session_event';
+          break;
+        case 'tool_call':
+        case 'tool_result':
+          priority = 5;
+          type = 'tool_output';
+          break;
+        case 'checkpoint':
+          priority = 4;
+          type = 'session_event';
+          break;
+        default:
+          priority = 5;
+          type = 'session_event';
+      }
+
+      return {
+        type,
+        id: event.id,
+        content: event.content,
+        priority,
+        metadata: event.metadata,
+      };
+    });
+  }
+
+  /**
+   * 生成 checkpoint 摘要
+   */
+  private generateCheckpointSummary(events: SessionEvent[]): string {
+    const userMessages = events.filter(e => e.type === 'user_message');
+    const toolCalls = events.filter(e => e.type === 'tool_call');
+
+    const parts: string[] = [];
+    parts.push(`事件总数: ${events.length}`);
+    parts.push(`用户消息: ${userMessages.length}`);
+    parts.push(`工具调用: ${toolCalls.length}`);
+
+    if (userMessages.length > 0) {
+      parts.push(`最近目标: ${userMessages[userMessages.length - 1].content.slice(0, 200)}`);
+    }
+
+    return parts.join('\n');
+  }
+
+  /**
+   * 持久化事件到 JSONL
+   */
+  private appendEvent(sessionId: string, event: SessionEvent): void {
+    try {
+      const eventsPath = path.join(this.getSessionDir(sessionId), 'events.jsonl');
+      const line = JSON.stringify(event) + '\n';
+      fs.appendFileSync(eventsPath, line, 'utf-8');
+    } catch {
+      // 持久化失败，静默处理
+    }
+  }
+
+  /**
+   * 保存 checkpoint
+   */
+  private saveCheckpoint(sessionId: string, checkpoint: SessionCheckpoint): void {
+    try {
+      const checkpointDir = path.join(this.getSessionDir(sessionId), 'checkpoints');
+      fs.mkdirSync(checkpointDir, { recursive: true });
+
+      const checkpointPath = path.join(checkpointDir, `${checkpoint.id}.json`);
+      fs.writeFileSync(checkpointPath, JSON.stringify(checkpoint, null, 2), 'utf-8');
+    } catch {
+      // 保存失败，静默处理
+    }
+  }
+
+  /**
+   * 获取会话目录
+   */
+  private getSessionDir(sessionId: string): string {
+    return path.join(this.basePath, '.harness', 'sessions', sessionId);
+  }
+}

package/src/context/token-budget.ts

@@ -0,0 +1,295 @@
+/**
+ * @spec HZ-002
+ * @implements HZ-002-C2
+ * @acceptance AC-001-2
+ * 
+ * Token Budget Manager
+ * 
+ * Token 预算管理和估算工具
+ */
+
+/**
+ * Token 估算器
+ * 
+ * 提供常用的 Token 估算方法
+ */
+export class TokenEstimator {
+  /**
+   * 估算文本的 Token 数（简化版）
+   * 
+   * 基于字符数估算，假设 1 token ≈ 4 字符（英文）
+   * 中文按 1 token ≈ 1.5 字符计算
+   * 
+   * 注意：这是快速估算，不是精确值
+   * 精确值需要使用 tokenizer（如 tiktoken）
+   */
+  static estimateText(text: string): number {
+    if (!text) return 0;
+    
+    // 检测是否包含中文
+    const hasChinese = /[\u4e00-\u9fa5]/.test(text);
+    
+    if (hasChinese) {
+      // 中文：1 token ≈ 1.5 字符
+      return Math.ceil(text.length / 1.5);
+    } else {
+      // 英文：1 token ≈ 4 字符
+      return Math.ceil(text.length / 4);
+    }
+  }
+
+  /**
+   * 估算对象的 Token 数
+   * 
+   * 将对象转为 JSON 字符串后估算
+   */
+  static estimateObject(obj: any): number {
+    try {
+      const json = JSON.stringify(obj);
+      return this.estimateText(json);
+    } catch {
+      return 0;
+    }
+  }
+
+  /**
+   * 估算数组的 Token 数
+   */
+  static estimateArray<T>(
+    items: T[],
+    itemEstimator?: (item: T) => number
+  ): number {
+    if (itemEstimator) {
+      return items.reduce((sum, item) => sum + itemEstimator(item), 0);
+    }
+    return this.estimateObject(items);
+  }
+
+  /**
+   * 创建自定义估算器
+   */
+  static createFieldEstimator<T>(
+    fieldMap: Record<string, (value: any) => number>
+  ): (item: T) => number {
+    return (item: T) => {
+      let total = 0;
+      for (const [field, estimator] of Object.entries(fieldMap)) {
+        const value = (item as any)[field];
+        total += estimator(value);
+      }
+      return total;
+    };
+  }
+}
+
+/**
+ * Token 预算分配器
+ * 
+ * 管理 Token 预算的分配和使用
+ */
+export class TokenBudget {
+  private totalBudget: number;
+  private usedTokens: number = 0;
+  private reservedTokens: number = 0;
+
+  constructor(budget: number) {
+    this.totalBudget = budget;
+  }
+
+  /**
+   * 获取剩余预算
+   */
+  get remaining(): number {
+    return this.totalBudget - this.usedTokens - this.reservedTokens;
+  }
+
+  /**
+   * 获取已使用预算
+   */
+  get used(): number {
+    return this.usedTokens;
+  }
+
+  /**
+   * 获取总预算
+   */
+  get total(): number {
+    return this.totalBudget;
+  }
+
+  /**
+   * 预留预算
+   * 
+   * @returns 是否预留成功
+   */
+  reserve(amount: number): boolean {
+    if (amount > this.remaining) {
+      return false;
+    }
+    this.reservedTokens += amount;
+    return true;
+  }
+
+  /**
+   * 释放预留的预算
+   */
+  release(amount: number): void {
+    this.reservedTokens = Math.max(0, this.reservedTokens - amount);
+  }
+
+  /**
+   * 使用预算
+   * 
+   * @returns 是否使用成功
+   */
+  consume(amount: number): boolean {
+    if (amount > this.remaining) {
+      return false;
+    }
+    this.usedTokens += amount;
+    return true;
+  }
+
+  /**
+   * 强制使用（可能超预算）
+   */
+  forceConsume(amount: number): void {
+    this.usedTokens += amount;
+  }
+
+  /**
+   * 增加预算
+   */
+  addBudget(amount: number): void {
+    this.totalBudget += amount;
+  }
+
+  /**
+   * 检查是否有足够预算
+   */
+  canAfford(amount: number): boolean {
+    return amount <= this.remaining;
+  }
+
+  /**
+   * 获取预算使用比例
+   */
+  get usageRatio(): number {
+    return this.usedTokens / this.totalBudget;
+  }
+
+  /**
+   * 获取预算状态
+   */
+  get status(): 'healthy' | 'warning' | 'critical' {
+    const ratio = this.usageRatio;
+    if (ratio < 0.5) return 'healthy';
+    if (ratio < 0.8) return 'warning';
+    return 'critical';
+  }
+
+  /**
+   * 重置预算
+   */
+  reset(newBudget?: number): void {
+    this.usedTokens = 0;
+    this.reservedTokens = 0;
+    if (newBudget !== undefined) {
+      this.totalBudget = newBudget;
+    }
+  }
+
+  /**
+   * 获取预算报告
+   */
+  getReport(): {
+    total: number;
+    used: number;
+    reserved: number;
+    remaining: number;
+    usageRatio: number;
+    status: 'healthy' | 'warning' | 'critical';
+  } {
+    return {
+      total: this.totalBudget,
+      used: this.usedTokens,
+      reserved: this.reservedTokens,
+      remaining: this.remaining,
+      usageRatio: this.usageRatio,
+      status: this.status
+    };
+  }
+}
+
+/**
+ * 自适应预算管理器
+ * 
+ * 根据历史使用情况动态调整预算
+ */
+export class AdaptiveTokenBudget extends TokenBudget {
+  private history: number[] = [];
+  private maxHistorySize: number = 10;
+
+  /**
+   * 记录实际使用情况
+   */
+  recordActualUsage(actualTokens: number): void {
+    this.history.push(actualTokens);
+    if (this.history.length > this.maxHistorySize) {
+      this.history.shift();
+    }
+  }
+
+  /**
+   * 获取平均使用量
+   */
+  getAverageUsage(): number {
+    if (this.history.length === 0) return 0;
+    return this.history.reduce((a, b) => a + b, 0) / this.history.length;
+  }
+
+  /**
+   * 预测未来需求
+   */
+  predictNeed(confidence: number = 0.9): number {
+    if (this.history.length === 0) return this.total;
+    
+    const avg = this.getAverageUsage();
+    const max = Math.max(...this.history);
+    
+    // 简单预测：平均值 + 一定比例的最大值
+    return Math.ceil(avg + (max - avg) * confidence);
+  }
+
+  /**
+   * 建议预算调整
+   */
+  suggestBudgetAdjustment(): {
+    action: 'increase' | 'decrease' | 'maintain';
+    suggestedBudget: number;
+    reason: string;
+  } {
+    const avg = this.getAverageUsage();
+    const ratio = avg / this.total;
+
+    if (ratio > 0.9) {
+      return {
+        action: 'increase',
+        suggestedBudget: Math.ceil(avg * 1.2),
+        reason: '平均使用量接近预算上限，建议增加 20%'
+      };
+    } else if (ratio < 0.5 && this.history.length >= 5) {
+      return {
+        action: 'decrease',
+        suggestedBudget: Math.ceil(avg * 1.2),
+        reason: '平均使用量远低于预算，可减少预算'
+      };
+    }
+
+    return {
+      action: 'maintain',
+      suggestedBudget: this.total,
+      reason: '预算使用合理'
+    };
+  }
+}