@toyako/hive 1.0.0

package/src/runtime/v2.1/validation/ValidationEngine.ts

@@ -0,0 +1,308 @@
+/**
+ * Validation Engine — v2.1
+ * 
+ * Shadow Validation 核心引擎
+ * 
+ * 职责：
+ * - 验证 Shadow 与 Runtime 的一致性
+ * - 收集验证指标
+ * - 生成验证报告
+ */
+
+import { ControlPlane, DualExecutionResult, ControlPlaneFlags } from "../ControlPlane";
+import { ExecutionContract } from "../contract/ShadowContractLayer";
+import { TraceEvent, DivergenceReport } from "../observability/ShadowObservabilityLayer";
+
+// 验证指标
+export interface ValidationMetrics {
+  // 执行统计
+  totalExecutions: number;
+  shadowExecutions: number;
+  
+  // 差异率
+  divergenceRate: number;
+  divergentRuns: number;
+  
+  // Contract 稳定性
+  contractStability: number;
+  contractHashMatches: number;
+  
+  // Replay 一致性
+  replayConsistency: number;
+  successfulReplays: number;
+  failedReplays: number;
+  
+  // 性能开销
+  shadowLatency: number;
+  avgShadowLatency: number;
+  
+  // 时间范围
+  startTime: number;
+  lastUpdateTime: number;
+}
+
+// 验证报告
+export interface ValidationReport {
+  timestamp: number;
+  metrics: ValidationMetrics;
+  cutoverReady: boolean;
+  cutoverConditions: Array<{ condition: string; met: boolean; current: string; required: string }>;
+  rollbackRisk: boolean;
+  recommendations: string[];
+}
+
+// 验证配置
+export interface ValidationConfig {
+  cutoverThresholds: {
+    contractStability: number;      // 100%
+    replayConsistency: number;      // > 99.9%
+    divergenceRate: number;         // < 1%
+    shadowLatency: number;          // < 5%
+    minExecutions: number;          // >= 1000
+  };
+  rollbackThresholds: {
+    replayConsistency: number;      // < 99%
+    divergenceRate: number;         // > 5%
+  };
+  persistMetrics: boolean;
+}
+
+export class ValidationEngine {
+  private controlPlane: ControlPlane;
+  private config: ValidationConfig;
+  private metrics: ValidationMetrics;
+  private executionHistory: Array<{
+    executionId: string;
+    contractHash: string;
+    timestamp: number;
+    diverged: boolean;
+  }> = [];
+
+  constructor(
+    controlPlane: ControlPlane,
+    config: Partial<ValidationConfig> = {}
+  ) {
+    this.controlPlane = controlPlane;
+    this.config = {
+      cutoverThresholds: {
+        contractStability: 1.0,      // 100%
+        replayConsistency: 0.999,    // > 99.9%
+        divergenceRate: 0.01,        // < 1%
+        shadowLatency: 0.05,         // < 5%
+        minExecutions: 1000           // >= 1000
+      },
+      rollbackThresholds: {
+        replayConsistency: 0.99,     // < 99%
+        divergenceRate: 0.05          // > 5%
+      },
+      persistMetrics: true,
+      ...config
+    };
+
+    this.metrics = this.initializeMetrics();
+  }
+
+  /**
+   * 验证执行
+   */
+  async validateExecution(
+    intent: string,
+    candidates: any[],
+    context: any = {}
+  ): Promise<{
+    result: DualExecutionResult;
+    validation: {
+      diverged: boolean;
+      contractHash: string;
+      metrics: ValidationMetrics;
+    };
+  }> {
+    const startTime = Date.now();
+
+    // 执行双轨模式
+    const result = await this.controlPlane.processIntent(intent, candidates, context);
+
+    // 检查是否分歧
+    const diverged = result.divergence_report.length > 0;
+
+    // 获取 Contract Hash
+    const contractHash = result.v2_1_shadow.contract?.deterministicHash || "";
+
+    // 更新指标
+    this.updateMetrics(diverged, contractHash, Date.now() - startTime);
+
+    // 记录执行历史
+    this.executionHistory.push({
+      executionId: result.v2_0_result?.taskId || "unknown",
+      contractHash,
+      timestamp: Date.now(),
+      diverged
+    });
+
+    return {
+      result,
+      validation: {
+        diverged,
+        contractHash,
+        metrics: { ...this.metrics }
+      }
+    };
+  }
+
+  /**
+   * 生成验证报告
+   */
+  generateReport(): ValidationReport {
+    const cutoverConditions = this.checkCutoverConditions();
+    const cutoverReady = cutoverConditions.every(c => c.met);
+    const rollbackRisk = this.checkRollbackRisk();
+
+    return {
+      timestamp: Date.now(),
+      metrics: { ...this.metrics },
+      cutoverReady,
+      cutoverConditions,
+      rollbackRisk,
+      recommendations: this.generateRecommendations(cutoverReady, rollbackRisk)
+    };
+  }
+
+  /**
+   * 获取指标
+   */
+  getMetrics(): ValidationMetrics {
+    return { ...this.metrics };
+  }
+
+  /**
+   * 重置指标
+   */
+  resetMetrics(): void {
+    this.metrics = this.initializeMetrics();
+    this.executionHistory = [];
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // 私有方法
+  // ═══════════════════════════════════════════════════════════════
+
+  private initializeMetrics(): ValidationMetrics {
+    return {
+      totalExecutions: 0,
+      shadowExecutions: 0,
+      divergenceRate: 0,
+      divergentRuns: 0,
+      contractStability: 1.0,
+      contractHashMatches: 0,
+      replayConsistency: 1.0,
+      successfulReplays: 0,
+      failedReplays: 0,
+      shadowLatency: 0,
+      avgShadowLatency: 0,
+      startTime: Date.now(),
+      lastUpdateTime: Date.now()
+    };
+  }
+
+  private updateMetrics(diverged: boolean, contractHash: string, latency: number): void {
+    this.metrics.totalExecutions++;
+    this.metrics.shadowExecutions++;
+    this.metrics.lastUpdateTime = Date.now();
+
+    if (diverged) {
+      this.metrics.divergentRuns++;
+    }
+
+    // 计算差异率
+    this.metrics.divergenceRate = this.metrics.divergentRuns / this.metrics.totalExecutions;
+
+    // 检查 Contract 稳定性
+    const hashMatches = this.executionHistory.filter(
+      h => h.contractHash === contractHash
+    ).length;
+    this.metrics.contractHashMatches = hashMatches;
+    this.metrics.contractStability = hashMatches / this.metrics.totalExecutions;
+
+    // 更新延迟
+    this.metrics.shadowLatency = latency;
+    this.metrics.avgShadowLatency = (
+      (this.metrics.avgShadowLatency * (this.metrics.totalExecutions - 1) + latency) /
+      this.metrics.totalExecutions
+    );
+  }
+
+  private checkCutoverConditions(): Array<{
+    condition: string;
+    met: boolean;
+    current: string;
+    required: string;
+  }> {
+    const { cutoverThresholds } = this.config;
+
+    return [
+      {
+        condition: "Contract Stability",
+        met: this.metrics.contractStability >= cutoverThresholds.contractStability,
+        current: `${(this.metrics.contractStability * 100).toFixed(1)}%`,
+        required: `${(cutoverThresholds.contractStability * 100).toFixed(0)}%`
+      },
+      {
+        condition: "Replay Consistency",
+        met: this.metrics.replayConsistency >= cutoverThresholds.replayConsistency,
+        current: `${(this.metrics.replayConsistency * 100).toFixed(1)}%`,
+        required: `> ${(cutoverThresholds.replayConsistency * 100).toFixed(1)}%`
+      },
+      {
+        condition: "Divergence Rate",
+        met: this.metrics.divergenceRate <= cutoverThresholds.divergenceRate,
+        current: `${(this.metrics.divergenceRate * 100).toFixed(2)}%`,
+        required: `< ${(cutoverThresholds.divergenceRate * 100).toFixed(0)}%`
+      },
+      {
+        condition: "Shadow Latency",
+        met: this.metrics.avgShadowLatency <= cutoverThresholds.shadowLatency * 1000,
+        current: `${this.metrics.avgShadowLatency.toFixed(0)}ms`,
+        required: `< ${(cutoverThresholds.shadowLatency * 1000).toFixed(0)}ms`
+      },
+      {
+        condition: "Min Executions",
+        met: this.metrics.totalExecutions >= cutoverThresholds.minExecutions,
+        current: `${this.metrics.totalExecutions}`,
+        required: `>= ${cutoverThresholds.minExecutions}`
+      }
+    ];
+  }
+
+  private checkRollbackRisk(): boolean {
+    const { rollbackThresholds } = this.config;
+
+    return (
+      this.metrics.replayConsistency < rollbackThresholds.replayConsistency ||
+      this.metrics.divergenceRate > rollbackThresholds.divergenceRate
+    );
+  }
+
+  private generateRecommendations(cutoverReady: boolean, rollbackRisk: boolean): string[] {
+    const recommendations: string[] = [];
+
+    if (rollbackRisk) {
+      recommendations.push("⚠️ Rollback risk detected. Consider disabling cutover.");
+    }
+
+    if (!cutoverReady) {
+      if (this.metrics.totalExecutions < this.config.cutoverThresholds.minExecutions) {
+        recommendations.push(`Continue validation: ${this.metrics.totalExecutions}/${this.config.cutoverThresholds.minExecutions} executions`);
+      }
+
+      if (this.metrics.divergenceRate > this.config.cutoverThresholds.divergenceRate) {
+        recommendations.push(`Reduce divergence rate: ${(this.metrics.divergenceRate * 100).toFixed(2)}% > ${(this.config.cutoverThresholds.divergenceRate * 100).toFixed(0)}%`);
+      }
+    }
+
+    if (cutoverReady) {
+      recommendations.push("✅ All cutover conditions met. Ready for production migration.");
+    }
+
+    return recommendations;
+  }
+}

package/src/runtime-core/agents/hermes.ts

@@ -0,0 +1,20 @@
+/**
+ * Hermes Agent — Planner Agent
+ * 
+ * 职责：
+ * - 分解任务
+ * - 生成 execution plan
+ * - input → plan steps
+ */
+
+import { Agent } from "./registry";
+
+export class HermesAgent implements Agent {
+  name = "hermes";
+  type = "planner" as const;
+
+  async execute(input: { input: string; context: any[] }): Promise<string> {
+    // 简化实现：分析任务并返回计划
+    return `Plan for: ${input.input}\nSteps: 1. Analyze 2. Implement 3. Test`;
+  }
+}

package/src/runtime-core/agents/registry.ts

@@ -0,0 +1,35 @@
+/**
+ * Agent Registry — Agent 注册表
+ */
+
+// Agent 接口
+export interface Agent {
+  name: string;
+  type: "planner" | "executor" | "tool";
+  execute(input: { input: string; context: any[] }): Promise<string>;
+}
+
+export class AgentRegistry {
+  private agents: Map<string, Agent> = new Map();
+
+  /**
+   * 注册 Agent
+   */
+  register(agent: Agent): void {
+    this.agents.set(agent.name, agent);
+  }
+
+  /**
+   * 获取 Agent
+   */
+  get(name: string): Agent | undefined {
+    return this.agents.get(name);
+  }
+
+  /**
+   * 列出所有 Agent
+   */
+  list(): Agent[] {
+    return Array.from(this.agents.values());
+  }
+}

package/src/runtime-core/agents/worker.ts

@@ -0,0 +1,20 @@
+/**
+ * Worker Agent — Executor Agent
+ * 
+ * 职责：
+ * - 执行 step
+ * - 使用 tools
+ * - 返回结果
+ */
+
+import { Agent } from "./registry";
+
+export class WorkerAgent implements Agent {
+  name = "worker";
+  type = "executor" as const;
+
+  async execute(input: { input: string; context: any[] }): Promise<string> {
+    // 简化实现：执行任务
+    return `Executed: ${input.input}\nResult: Success`;
+  }
+}

package/src/runtime-core/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Runtime Core v1 — 核心执行引擎
+ * 
+ * Agent Hive Runtime v1 = A CLI-based multi-agent execution orchestrator
+ */
+
+import { Orchestrator, Task } from "./orchestrator";
+import { AgentRegistry } from "./agents/registry";
+import { HermesAgent } from "./agents/hermes";
+import { WorkerAgent } from "./agents/worker";
+import { ToolRegistry } from "./tools/registry";
+import { FSTool } from "./tools/fs";
+
+export class RuntimeCore {
+  private orchestrator: Orchestrator;
+  private agentRegistry: AgentRegistry;
+  private toolRegistry: ToolRegistry;
+
+  constructor() {
+    this.agentRegistry = new AgentRegistry();
+    this.toolRegistry = new ToolRegistry();
+
+    // 注册 Agents
+    this.agentRegistry.register(new HermesAgent());
+    this.agentRegistry.register(new WorkerAgent());
+
+    // 注册 Tools
+    this.toolRegistry.register(new FSTool());
+
+    // 创建 Orchestrator
+    this.orchestrator = new Orchestrator(this.agentRegistry, this.toolRegistry);
+  }
+
+  /**
+   * 执行任务
+   */
+  async run(task: string): Promise<any> {
+    const taskObj: Task = {
+      id: `task_${Date.now()}`,
+      input: task,
+      timestamp: Date.now()
+    };
+
+    return this.orchestrator.execute(taskObj);
+  }
+
+  /**
+   * 列出所有 Agents
+   */
+  listAgents(): string[] {
+    return this.agentRegistry.list().map(a => a.name);
+  }
+
+  /**
+   * 列出所有 Tools
+   */
+  listTools(): string[] {
+    return this.toolRegistry.list().map(t => t.name);
+  }
+}

package/src/runtime-core/orchestrator.ts

@@ -0,0 +1,123 @@
+/**
+ * Orchestrator — 核心调度器
+ * 
+ * 职责：
+ * - 接收 task
+ * - 选择 agent
+ * - 生成 execution plan
+ * - 调度执行
+ */
+
+import { Agent, AgentRegistry } from "./agents/registry";
+import { ToolRegistry } from "./tools/registry";
+
+// Task
+export interface Task {
+  id: string;
+  input: string;
+  timestamp: number;
+}
+
+// Plan Step
+export interface PlanStep {
+  agent: string;
+  input: string;
+  tool?: string;
+}
+
+// Plan
+export interface Plan {
+  steps: PlanStep[];
+}
+
+// Result
+export interface Result {
+  output: string;
+  logs: string[];
+  artifacts: string[];
+}
+
+export class Orchestrator {
+  private agentRegistry: AgentRegistry;
+  private toolRegistry: ToolRegistry;
+
+  constructor(agentRegistry: AgentRegistry, toolRegistry: ToolRegistry) {
+    this.agentRegistry = agentRegistry;
+    this.toolRegistry = toolRegistry;
+  }
+
+  /**
+   * 执行任务
+   */
+  async execute(task: Task): Promise<Result> {
+    const logs: string[] = [];
+    const artifacts: string[] = [];
+
+    // 1. 解析意图
+    logs.push(`Parsing intent: ${task.input}`);
+    const intent = this.parseIntent(task.input);
+
+    // 2. 创建执行计划
+    logs.push(`Creating execution plan...`);
+    const plan = this.createPlan(intent);
+
+    // 3. 执行计划
+    const results: any[] = [];
+    
+    for (const step of plan.steps) {
+      logs.push(`Executing step: ${step.agent} - ${step.input}`);
+
+      // 选择 agent
+      const agent = this.agentRegistry.get(step.agent);
+      if (!agent) {
+        throw new Error(`Agent not found: ${step.agent}`);
+      }
+
+      // 执行 agent
+      const output = await agent.execute({
+        input: step.input,
+        context: results
+      });
+
+      // 如果需要工具
+      if (step.tool) {
+        logs.push(`Using tool: ${step.tool}`);
+        const tool = this.toolRegistry.get(step.tool);
+        if (tool) {
+          const toolResult = await tool.run(output);
+          results.push(toolResult);
+          artifacts.push(toolResult);
+        }
+      } else {
+        results.push(output);
+      }
+    }
+
+    return {
+      output: results.at(-1) || "",
+      logs,
+      artifacts
+    };
+  }
+
+  /**
+   * 解析意图
+   */
+  private parseIntent(input: string): string {
+    // 简化实现
+    return input;
+  }
+
+  /**
+   * 创建执行计划
+   */
+  private createPlan(intent: string): Plan {
+    // 简化实现：根据意图创建计划
+    return {
+      steps: [
+        { agent: "hermes", input: `Analyze: ${intent}` },
+        { agent: "worker", input: `Execute: ${intent}` }
+      ]
+    };
+  }
+}

package/src/runtime-core/tools/fs.ts

@@ -0,0 +1,24 @@
+/**
+ * File System Tool
+ */
+
+import { Tool } from "./registry";
+import * as fs from "fs";
+
+export class FSTool implements Tool {
+  name = "fs";
+
+  async run(input: any): Promise<any> {
+    const { action, path, content } = input;
+
+    switch (action) {
+      case "read":
+        return fs.readFileSync(path, "utf-8");
+      case "write":
+        fs.writeFileSync(path, content);
+        return { success: true };
+      default:
+        throw new Error(`Unknown action: ${action}`);
+    }
+  }
+}

package/src/runtime-core/tools/registry.ts

@@ -0,0 +1,34 @@
+/**
+ * Tool Registry — Tool 注册表
+ */
+
+// Tool 接口
+export interface Tool {
+  name: string;
+  run(input: any): Promise<any>;
+}
+
+export class ToolRegistry {
+  private tools: Map<string, Tool> = new Map();
+
+  /**
+   * 注册 Tool
+   */
+  register(tool: Tool): void {
+    this.tools.set(tool.name, tool);
+  }
+
+  /**
+   * 获取 Tool
+   */
+  get(name: string): Tool | undefined {
+    return this.tools.get(name);
+  }
+
+  /**
+   * 列出所有 Tools
+   */
+  list(): Tool[] {
+    return Array.from(this.tools.values());
+  }
+}

package/src/runtime-v2/agents/PlannerAgent.ts

@@ -0,0 +1,34 @@
+/**
+ * Planner Agent (Hermes) — v2
+ * 
+ * 职责：
+ * - task decomposition
+ * - DAG generation
+ * - agent assignment
+ */
+
+import { ExecutionGraph, GraphNode, GraphEdge } from "../graph/GraphRuntimeEngine";
+
+export class PlannerAgent {
+  /**
+   * 将任务转换为 DAG
+   */
+  async plan(task: string): Promise<ExecutionGraph> {
+    // 简化实现：根据任务生成 DAG
+    const nodes: GraphNode[] = [
+      { id: "A", agent: "hermes", task: `Analyze: ${task}`, status: "pending" },
+      { id: "B", agent: "worker", task: `Implement: ${task}`, status: "pending" },
+      { id: "C", agent: "worker", task: `Test: ${task}`, status: "pending" },
+      { id: "D", agent: "reviewer", task: `Review: ${task}`, status: "pending" }
+    ];
+
+    const edges: GraphEdge[] = [
+      { from: "A", to: "B" },
+      { from: "A", to: "C" },
+      { from: "B", to: "D" },
+      { from: "C", to: "D" }
+    ];
+
+    return { nodes, edges };
+  }
+}