@toyako/hive 1.0.0

package/src/runtime/v2/audit/AuditTrail.ts

@@ -0,0 +1,393 @@
+/**
+ * Audit Trail — Phase 4
+ * 
+ * 结构化审计持久化
+ * 
+ * 将状态机的所有流转轨迹持久化为不可篡改的流水账：
+ * - Events 历史
+ * - Budget 消耗曲线
+ * - Evaluator 判定节点日志
+ * - 人工审批记录
+ * 
+ * 用于合规审计
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { RuntimeState } from "../state-machine/RuntimeStateMachine";
+import { Verdict } from "../RuntimeCore";
+import { PersistenceEngine } from "../persistence/PersistenceEngine";
+
+// 审计事件类型
+export enum AuditEventType {
+  // 状态流转
+  STATE_TRANSITION = "state_transition",
+  
+  // 执行事件
+  EXECUTION_START = "execution_start",
+  EXECUTION_END = "execution_end",
+  EXECUTION_ERROR = "execution_error",
+  
+  // 验证事件
+  EVALUATION_START = "evaluation_start",
+  EVALUATION_RESULT = "evaluation_result",
+  
+  // 预算事件
+  BUDGET_CONSUMPTION = "budget_consumption",
+  BUDGET_EXCEEDED = "budget_exceeded",
+  
+  // 恢复事件
+  RECOVERY_ATTEMPT = "recovery_attempt",
+  RECOVERY_SUCCESS = "recovery_success",
+  RECOVERY_ESCALATION = "recovery_escalation",
+  
+  // 检查点事件
+  CHECKPOINT_CREATED = "checkpoint_created",
+  CHECKPOINT_APPROVED = "checkpoint_approved",
+  CHECKPOINT_REJECTED = "checkpoint_rejected",
+  
+  // 隔离事件
+  SANDBOX_CREATED = "sandbox_created",
+  SANDBOX_ROLLBACK = "sandbox_rollback",
+  SANDBOX_DESTROYED = "sandbox_destroyed",
+  
+  // 策略事件
+  POLICY_CHECK = "policy_check",
+  POLICY_REJECTED = "policy_rejected",
+  
+  // 人工操作
+  HUMAN_DECISION = "human_decision",
+  
+  // 系统事件
+  SYSTEM_START = "system_start",
+  SYSTEM_SHUTDOWN = "system_shutdown",
+  SYSTEM_ERROR = "system_error"
+}
+
+// 审计事件
+export interface AuditEvent {
+  id: string;
+  type: AuditEventType;
+  taskId: string;
+  timestamp: number;
+  
+  // 状态信息
+  fromState?: RuntimeState;
+  toState?: RuntimeState;
+  
+  // 执行信息
+  agentId?: string;
+  duration?: number;
+  
+  // 验证信息
+  verdict?: Verdict;
+  score?: number;
+  checks?: Array<{ name: string; passed: boolean; message?: string }>;
+  
+  // 预算信息
+  tokensUsed?: number;
+  costIncurred?: number;
+  
+  // 错误信息
+  error?: string;
+  stackTrace?: string;
+  
+  // 人工操作
+  operator?: string;
+  reason?: string;
+  
+  // 元数据
+  metadata?: Record<string, any>;
+  
+  // 不可篡改签名
+  signature?: string;
+}
+
+// 审计查询条件
+export interface AuditQuery {
+  taskId?: string;
+  type?: AuditEventType;
+  startTime?: number;
+  endTime?: number;
+  limit?: number;
+  offset?: number;
+}
+
+// 审计统计
+export interface AuditStats {
+  totalEvents: number;
+  eventsByType: Map<AuditEventType, number>;
+  tasksTracked: number;
+  timeRange: { start: number; end: number };
+}
+
+export class AuditTrail {
+  private persistence: PersistenceEngine;
+  private basePath: string;
+  private events: AuditEvent[] = [];
+  private flushInterval: NodeJS.Timeout | null = null;
+
+  constructor(persistence: PersistenceEngine, basePath: string = ".agent-hive/audit") {
+    this.persistence = persistence;
+    this.basePath = basePath;
+    this.ensureDirectory(basePath);
+  }
+
+  /**
+   * 启动审计追踪
+   */
+  start(): void {
+    console.log("[AuditTrail] Started");
+    
+    // 定期刷新到磁盘
+    this.flushInterval = setInterval(() => {
+      this.flush();
+    }, 10000); // 10秒
+  }
+
+  /**
+   * 停止审计追踪
+   */
+  stop(): void {
+    if (this.flushInterval) {
+      clearInterval(this.flushInterval);
+      this.flushInterval = null;
+    }
+    
+    this.flush();
+    console.log("[AuditTrail] Stopped");
+  }
+
+  /**
+   * 记录审计事件
+   */
+  record(event: Omit<AuditEvent, "id" | "timestamp" | "signature">): AuditEvent {
+    const fullEvent: AuditEvent = {
+      ...event,
+      id: this.generateEventId(),
+      timestamp: Date.now(),
+      signature: this.calculateSignature(event)
+    };
+
+    this.events.push(fullEvent);
+    
+    // 如果事件数量超过阈值，刷新到磁盘
+    if (this.events.length > 1000) {
+      this.flush();
+    }
+
+    return fullEvent;
+  }
+
+  /**
+   * 记录状态流转
+   */
+  recordStateTransition(
+    taskId: string,
+    fromState: RuntimeState,
+    toState: RuntimeState,
+    reason?: string,
+    metadata?: Record<string, any>
+  ): AuditEvent {
+    return this.record({
+      type: AuditEventType.STATE_TRANSITION,
+      taskId,
+      fromState,
+      toState,
+      reason,
+      metadata
+    });
+  }
+
+  /**
+   * 记录执行事件
+   */
+  recordExecution(
+    taskId: string,
+    agentId: string,
+    success: boolean,
+    duration: number,
+    error?: string,
+    metadata?: Record<string, any>
+  ): AuditEvent {
+    return this.record({
+      type: success ? AuditEventType.EXECUTION_END : AuditEventType.EXECUTION_ERROR,
+      taskId,
+      agentId,
+      duration,
+      error,
+      metadata
+    });
+  }
+
+  /**
+   * 记录验证事件
+   */
+  recordEvaluation(
+    taskId: string,
+    verdict: Verdict,
+    score: number,
+    checks: Array<{ name: string; passed: boolean; message?: string }>,
+    metadata?: Record<string, any>
+  ): AuditEvent {
+    return this.record({
+      type: AuditEventType.EVALUATION_RESULT,
+      taskId,
+      verdict,
+      score,
+      checks,
+      metadata
+    });
+  }
+
+  /**
+   * 记录预算消耗
+   */
+  recordBudgetConsumption(
+    taskId: string,
+    tokensUsed: number,
+    costIncurred: number,
+    metadata?: Record<string, any>
+  ): AuditEvent {
+    return this.record({
+      type: AuditEventType.BUDGET_CONSUMPTION,
+      taskId,
+      tokensUsed,
+      costIncurred,
+      metadata
+    });
+  }
+
+  /**
+   * 记录人工决策
+   */
+  recordHumanDecision(
+    taskId: string,
+    operator: string,
+    decision: "approve" | "reject",
+    reason?: string,
+    metadata?: Record<string, any>
+  ): AuditEvent {
+    return this.record({
+      type: AuditEventType.HUMAN_DECISION,
+      taskId,
+      operator,
+      reason,
+      metadata: { ...metadata, decision }
+    });
+  }
+
+  /**
+   * 查询审计事件
+   */
+  query(query: AuditQuery): AuditEvent[] {
+    let results = [...this.events];
+
+    if (query.taskId) {
+      results = results.filter(e => e.taskId === query.taskId);
+    }
+
+    if (query.type) {
+      results = results.filter(e => e.type === query.type);
+    }
+
+    if (query.startTime) {
+      results = results.filter(e => e.timestamp >= query.startTime!);
+    }
+
+    if (query.endTime) {
+      results = results.filter(e => e.timestamp <= query.endTime!);
+    }
+
+    // 按时间排序
+    results.sort((a, b) => a.timestamp - b.timestamp);
+
+    // 分页
+    if (query.offset) {
+      results = results.slice(query.offset);
+    }
+    if (query.limit) {
+      results = results.slice(0, query.limit);
+    }
+
+    return results;
+  }
+
+  /**
+   * 获取任务的完整审计轨迹
+   */
+  getTaskTrail(taskId: string): AuditEvent[] {
+    return this.query({ taskId });
+  }
+
+  /**
+   * 获取审计统计
+   */
+  getStats(): AuditStats {
+    const eventsByType = new Map<AuditEventType, number>();
+    const tasks = new Set<string>();
+    let minTimestamp = Infinity;
+    let maxTimestamp = 0;
+
+    for (const event of this.events) {
+      // 按类型统计
+      const count = eventsByType.get(event.type) || 0;
+      eventsByType.set(event.type, count + 1);
+
+      // 任务统计
+      tasks.add(event.taskId);
+
+      // 时间范围
+      if (event.timestamp < minTimestamp) minTimestamp = event.timestamp;
+      if (event.timestamp > maxTimestamp) maxTimestamp = event.timestamp;
+    }
+
+    return {
+      totalEvents: this.events.length,
+      eventsByType,
+      tasksTracked: tasks.size,
+      timeRange: { start: minTimestamp, end: maxTimestamp }
+    };
+  }
+
+  /**
+   * 刷新到磁盘
+   */
+  private flush(): void {
+    if (this.events.length === 0) return;
+
+    const filePath = path.join(this.basePath, `audit-${Date.now()}.json`);
+    
+    try {
+      fs.writeFileSync(filePath, JSON.stringify(this.events, null, 2));
+      this.events = [];
+    } catch (error) {
+      console.error("[AuditTrail] Failed to flush:", error);
+    }
+  }
+
+  /**
+   * 生成事件 ID
+   */
+  private generateEventId(): string {
+    return `audit-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * 计算签名（简单实现，生产环境应使用加密签名）
+   */
+  private calculateSignature(event: any): string {
+    const crypto = require("crypto");
+    const content = JSON.stringify(event);
+    return crypto.createHash("sha256").update(content).digest("hex").substr(0, 16);
+  }
+
+  /**
+   * 确保目录存在
+   */
+  private ensureDirectory(dir: string): void {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+}

package/src/runtime/v2/budget/BudgetGuard.ts

@@ -0,0 +1,304 @@
+/**
+ * Budget Guard — Phase 1
+ * 
+ * 铁律：冷酷无情（Hard Abort）
+ * 
+ * 一旦检测到 Token 消耗、重试次数或费用超过限制，
+ * 必须触发最高优先级的系统级硬中断。
+ * 
+ * 绝对不允许给 Agent 留有：
+ * - "自我纠错"的运行空间
+ * - "善后编写日志"的运行空间
+ * - "自我辩解"的运行空间
+ * 
+ * 直接切断执行流，状态强转为 BUDGET_LIMIT。
+ */
+
+import { EventBus, RuntimeEventType, globalEventBus } from "../observation/EventBus";
+import { PersistenceEngine } from "../persistence/PersistenceEngine";
+
+// 预算配置
+export interface BudgetLimits {
+  maxTokensPerTask?: number;
+  maxTokensDaily?: number;
+  maxCostPerTask?: number;   // USD
+  maxCostDaily?: number;     // USD
+  maxRetriesPerTask?: number;
+  maxRuntimePerTask?: number; // ms
+  maxRuntimeDaily?: number;   // ms
+}
+
+// 预算消耗记录
+export interface BudgetConsumption {
+  tokensUsed: number;
+  costIncurred: number;  // USD
+  retryCount: number;
+  runtimeElapsed: number; // ms
+  timestamp: number;
+}
+
+// 预算状态
+export interface BudgetState {
+  taskConsumptions: Map<string, BudgetConsumption>;
+  dailyTokens: number;
+  dailyCost: number;
+  dailyRuntime: number;
+  dailyResetAt: number;
+}
+
+export class BudgetGuard {
+  private limits: BudgetLimits;
+  private state: BudgetState;
+  private eventBus: EventBus;
+  private persistence: PersistenceEngine | null = null;
+  private hardAbortCallbacks: Array<(taskId: string, reason: string) => void> = [];
+
+  constructor(limits: BudgetLimits, eventBus: EventBus = globalEventBus) {
+    this.limits = limits;
+    this.eventBus = eventBus;
+    this.state = {
+      taskConsumptions: new Map(),
+      dailyTokens: 0,
+      dailyCost: 0,
+      dailyRuntime: 0,
+      dailyResetAt: this.getNextDayReset()
+    };
+  }
+
+  /**
+   * 设置持久化引擎
+   */
+  setPersistence(persistence: PersistenceEngine): void {
+    this.persistence = persistence;
+  }
+
+  /**
+   * 注册硬中断回调
+   * 
+   * 当预算超限时，直接调用这些回调切断执行流
+   */
+  onHardAbort(callback: (taskId: string, reason: string) => void): void {
+    this.hardAbortCallbacks.push(callback);
+  }
+
+  /**
+   * 检查任务是否可以开始执行
+   * 
+   * 在任务开始前检查，如果超限则立即阻断
+   */
+  canStartTask(taskId: string): { allowed: boolean; reason?: string } {
+    this.checkDailyReset();
+
+    // 检查每日 Token 限制
+    if (this.limits.maxTokensDaily && this.state.dailyTokens >= this.limits.maxTokensDaily) {
+      return { allowed: false, reason: `Daily token limit exceeded: ${this.state.dailyTokens}/${this.limits.maxTokensDaily}` };
+    }
+
+    // 检查每日费用限制
+    if (this.limits.maxCostDaily && this.state.dailyCost >= this.limits.maxCostDaily) {
+      return { allowed: false, reason: `Daily cost limit exceeded: $${this.state.dailyCost.toFixed(4)}/$${this.limits.maxCostDaily}` };
+    }
+
+    // 检查每日运行时间限制
+    if (this.limits.maxRuntimeDaily && this.state.dailyRuntime >= this.limits.maxRuntimeDaily) {
+      return { allowed: false, reason: `Daily runtime limit exceeded: ${this.state.dailyRuntime}ms/${this.limits.maxRuntimeDaily}ms` };
+    }
+
+    return { allowed: true };
+  }
+
+  /**
+   * 记录任务消耗
+   * 
+   * 每次调用都会检查是否超限
+   * 如果超限，立即触发硬中断
+   */
+  recordConsumption(taskId: string, consumption: Partial<BudgetConsumption>): void {
+    this.checkDailyReset();
+
+    // 获取或创建任务消耗记录
+    let taskConsumption = this.state.taskConsumptions.get(taskId);
+    if (!taskConsumption) {
+      taskConsumption = { tokensUsed: 0, costIncurred: 0, retryCount: 0, runtimeElapsed: 0, timestamp: Date.now() };
+      this.state.taskConsumptions.set(taskId, taskConsumption);
+    }
+
+    // 更新消耗
+    if (consumption.tokensUsed) {
+      taskConsumption.tokensUsed += consumption.tokensUsed;
+      this.state.dailyTokens += consumption.tokensUsed;
+    }
+    if (consumption.costIncurred) {
+      taskConsumption.costIncurred += consumption.costIncurred;
+      this.state.dailyCost += consumption.costIncurred;
+    }
+    if (consumption.retryCount) {
+      taskConsumption.retryCount += consumption.retryCount;
+    }
+    if (consumption.runtimeElapsed) {
+      taskConsumption.runtimeElapsed += consumption.runtimeElapsed;
+      this.state.dailyRuntime += consumption.runtimeElapsed;
+    }
+
+    // 🚨 立即检查是否超限 - 冷酷无情
+    this.enforceBudgetLimits(taskId);
+  }
+
+  /**
+   * 记录重试
+   */
+  recordRetry(taskId: string): void {
+    this.recordConsumption(taskId, { retryCount: 1 });
+  }
+
+  /**
+   * 🚨 强制执行预算限制 - 冷酷无情
+   * 
+   * 一旦超限，立即触发硬中断，不允许任何善后操作
+   */
+  private enforceBudgetLimits(taskId: string): void {
+    const taskConsumption = this.state.taskConsumptions.get(taskId);
+    if (!taskConsumption) return;
+
+    // 检查任务级 Token 限制
+    if (this.limits.maxTokensPerTask && taskConsumption.tokensUsed > this.limits.maxTokensPerTask) {
+      this.triggerHardAbort(taskId, `Task token limit exceeded: ${taskConsumption.tokensUsed}/${this.limits.maxTokensPerTask}`);
+      return;
+    }
+
+    // 检查任务级费用限制
+    if (this.limits.maxCostPerTask && taskConsumption.costIncurred > this.limits.maxCostPerTask) {
+      this.triggerHardAbort(taskId, `Task cost limit exceeded: $${taskConsumption.costIncurred.toFixed(4)}/$${this.limits.maxCostPerTask}`);
+      return;
+    }
+
+    // 检查任务级重试限制
+    if (this.limits.maxRetriesPerTask && taskConsumption.retryCount > this.limits.maxRetriesPerTask) {
+      this.triggerHardAbort(taskId, `Task retry limit exceeded: ${taskConsumption.retryCount}/${this.limits.maxRetriesPerTask}`);
+      return;
+    }
+
+    // 检查任务级运行时间限制
+    if (this.limits.maxRuntimePerTask && taskConsumption.runtimeElapsed > this.limits.maxRuntimePerTask) {
+      this.triggerHardAbort(taskId, `Task runtime limit exceeded: ${taskConsumption.runtimeElapsed}ms/${this.limits.maxRuntimePerTask}ms`);
+      return;
+    }
+
+    // 检查每日 Token 限制
+    if (this.limits.maxTokensDaily && this.state.dailyTokens > this.limits.maxTokensDaily) {
+      this.triggerHardAbort(taskId, `Daily token limit exceeded: ${this.state.dailyTokens}/${this.limits.maxTokensDaily}`);
+      return;
+    }
+
+    // 检查每日费用限制
+    if (this.limits.maxCostDaily && this.state.dailyCost > this.limits.maxCostDaily) {
+      this.triggerHardAbort(taskId, `Daily cost limit exceeded: $${this.state.dailyCost.toFixed(4)}/$${this.limits.maxCostDaily}`);
+      return;
+    }
+
+    // 检查每日运行时间限制
+    if (this.limits.maxRuntimeDaily && this.state.dailyRuntime > this.limits.maxRuntimeDaily) {
+      this.triggerHardAbort(taskId, `Daily runtime limit exceeded: ${this.state.dailyRuntime}ms/${this.limits.maxRuntimeDaily}ms`);
+      return;
+    }
+  }
+
+  /**
+   * 🚨 触发硬中断 - 冷酷无情
+   * 
+   * 直接切断执行流，状态强转为 BUDGET_LIMIT
+   * 不允许任何善后操作
+   */
+  private triggerHardAbort(taskId: string, reason: string): void {
+    console.error(`[BudgetGuard] 🚨 HARD ABORT: ${taskId} - ${reason}`);
+
+    // 持久化预算状态
+    if (this.persistence) {
+      this.persistence.saveBudget({
+        limits: this.limits,
+        state: {
+          dailyTokens: this.state.dailyTokens,
+          dailyCost: this.state.dailyCost,
+          dailyRuntime: this.state.dailyRuntime,
+          abortedTask: taskId,
+          abortReason: reason,
+          timestamp: Date.now()
+        }
+      });
+    }
+
+    // 触发事件
+    this.eventBus.emit({
+      type: RuntimeEventType.BUDGET_EXCEEDED,
+      taskId,
+      timestamp: Date.now(),
+      error: reason
+    });
+
+    // 触发所有硬中断回调 - 直接切断执行流
+    for (const callback of this.hardAbortCallbacks) {
+      try {
+        callback(taskId, reason);
+      } catch (e) {
+        // 即使回调失败，也不阻止硬中断
+      }
+    }
+  }
+
+  /**
+   * 获取任务消耗
+   */
+  getTaskConsumption(taskId: string): BudgetConsumption | undefined {
+    return this.state.taskConsumptions.get(taskId);
+  }
+
+  /**
+   * 获取每日状态
+   */
+  getDailyState(): { tokens: number; cost: number; runtime: number; resetAt: number } {
+    this.checkDailyReset();
+    return {
+      tokens: this.state.dailyTokens,
+      cost: this.state.dailyCost,
+      runtime: this.state.dailyRuntime,
+      resetAt: this.state.dailyResetAt
+    };
+  }
+
+  /**
+   * 获取限制
+   */
+  getLimits(): BudgetLimits {
+    return { ...this.limits };
+  }
+
+  /**
+   * 更新限制
+   */
+  updateLimits(limits: Partial<BudgetLimits>): void {
+    Object.assign(this.limits, limits);
+  }
+
+  /**
+   * 检查并重置每日计数器
+   */
+  private checkDailyReset(): void {
+    const now = Date.now();
+    if (now >= this.state.dailyResetAt) {
+      this.state.dailyTokens = 0;
+      this.state.dailyCost = 0;
+      this.state.dailyRuntime = 0;
+      this.state.dailyResetAt = this.getNextDayReset();
+    }
+  }
+
+  /**
+   * 获取明天重置时间
+   */
+  private getNextDayReset(): number {
+    const tomorrow = new Date();
+    tomorrow.setDate(tomorrow.getDate() + 1);
+    tomorrow.setHours(0, 0, 0, 0);
+    return tomorrow.getTime();
+  }
+}