@toyako/hive 1.0.0

package/src/api/HiveAPI.ts

@@ -0,0 +1,148 @@
+import { Broker } from "../broker/Broker";
+import {
+  AgentProfile,
+  GraphEdge,
+  Task,
+  MessageEnvelope,
+  RevisionRecord,
+} from "../types";
+
+/**
+ * HiveAPI
+ *
+ * Thin programming interface over the Broker, designed for use by
+ * Web UIs, scripts, and external integrations. All methods are
+ * synchronous reads (except constructor) — no side effects.
+ */
+export class HiveAPI {
+  private broker: Broker;
+
+  constructor(broker: Broker) {
+    this.broker = broker;
+  }
+
+  // ─── Agent queries ──────────────────────────────────
+
+  /** List all agent profiles in the graph. */
+  getAgents(): AgentProfile[] {
+    return this.broker.graph.allAgents();
+  }
+
+  /** Get a single agent profile by id. */
+  getAgent(id: string): AgentProfile | undefined {
+    return this.broker.graph.getAgent(id);
+  }
+
+  // ─── Graph queries ──────────────────────────────────
+
+  /** Get the full graph data (agents + edges). */
+  getGraph(): { agents: AgentProfile[]; edges: GraphEdge[] } {
+    return {
+      agents: this.broker.graph.allAgents(),
+      edges: this.broker.graph.allEdges(),
+    };
+  }
+
+  /** Render an ASCII art topology view of the graph. */
+  getTopology(): string {
+    const agents = this.broker.graph.allAgents();
+    const edges = this.broker.graph.allEdges();
+
+    if (agents.length === 0) return "(empty graph)";
+
+    const lines: string[] = ["Agent Hive Topology:", ""];
+
+    // Build adjacency for display
+    const byRelation: Record<string, GraphEdge[]> = {};
+    for (const e of edges) {
+      const key = `${e.from} → ${e.to}`;
+      if (!byRelation[key]) byRelation[key] = [];
+      byRelation[key].push(e);
+    }
+
+    // Agent list
+    lines.push("  Agents:");
+    for (const a of agents) {
+      lines.push(`    [${a.status}] ${a.id} (${a.role})`);
+    }
+    lines.push("");
+
+    // Edge list with ASCII art
+    lines.push("  Edges:");
+    for (const e of edges) {
+      const arrow = e.relation === "reviews" ? "──(reviews)──▶" :
+                    e.relation === "escalates" ? "──(escalates)─▶" :
+                    e.relation === "delegates" ? "──(delegates)─▶" :
+                    `──(${e.relation})──▶`;
+      lines.push(`    ${e.from} ${arrow} ${e.to}  [w=${e.weight}]`);
+    }
+
+    return lines.join("\n");
+  }
+
+  // ─── Task queries ───────────────────────────────────
+
+  /** List all tasks in the queue. */
+  getTasks(): Task[] {
+    return this.broker.queue.all();
+  }
+
+  /** Get a single task by id. */
+  getTask(taskId: string): Task | undefined {
+    return this.broker.queue.get(taskId) || undefined;
+  }
+
+  /** Get revision history for a task. */
+  getTaskHistory(taskId: string): RevisionRecord[] {
+    return this.broker.history.get(taskId);
+  }
+
+  // ─── Message queries ────────────────────────────────
+
+  /** Get the v2.0 message envelope log for a task. */
+  getMessageLog(taskId: string): MessageEnvelope[] {
+    return this.broker.bus.envelopeHistory(taskId);
+  }
+
+  // ─── Health / Monitoring ────────────────────────────
+
+  /** Get a health summary of all agents, circuit breakers, and active conversations. */
+  getHealth(): {
+    agents: { id: string; healthy: boolean; status: string }[];
+    circuitBreakers: { id: string; state: string }[];
+    activeConversations: number;
+  } {
+    // Agents from registry
+    const entries = this.broker.registry.all();
+    const agents = entries.map((e) => ({
+      id: e.name,
+      healthy: e.healthy,
+      status: e.installed ? (e.healthy ? "healthy" : "unhealthy") : "not-installed",
+    }));
+
+    // Graph agents not in registry
+    const graphAgents = this.broker.graph.allAgents();
+    for (const ga of graphAgents) {
+      if (!agents.find((a) => a.id === ga.id)) {
+        agents.push({
+          id: ga.id,
+          healthy: ga.status !== "offline",
+          status: ga.status,
+        });
+      }
+    }
+
+    // Circuit breakers
+    const safetyStatus = this.broker.getSafetyStatus();
+    const cbStates = safetyStatus.circuitBreaker;
+    const circuitBreakers = Array.isArray(cbStates) ? cbStates.map((cb: any) => ({
+      id: cb.agentId,
+      state: cb.state,
+    })) : [];
+
+    // Active conversations
+    const activeConversations = this.broker.getConversations().active().length;
+
+    return { agents, circuitBreakers, activeConversations };
+  }
+}

package/src/benchmark/BenchmarkDataset.ts

@@ -0,0 +1,80 @@
+import * as fs from "fs";
+import * as path from "path";
+
+const BENCHMARK_FILE = path.resolve(process.cwd(), ".agent-hive/benchmark/runtime-benchmark.json");
+
+export interface RuntimeBenchmark {
+  runtimeId: string;
+  coding: number;
+  review: number;
+  planning: number;
+  reasoning: number;
+  latency: number;
+  successRate: number;
+  updatedAt: number;
+}
+
+export class BenchmarkDataset {
+  private data: Map<string, RuntimeBenchmark> = new Map();
+
+  constructor() {
+    fs.mkdirSync(path.dirname(BENCHMARK_FILE), { recursive: true });
+    this.loadPersisted();
+  }
+
+  set(benchmark: RuntimeBenchmark): void {
+    benchmark.updatedAt = Date.now();
+    this.data.set(benchmark.runtimeId, benchmark);
+    this.persist();
+  }
+
+  get(runtimeId: string): RuntimeBenchmark | undefined {
+    return this.data.get(runtimeId);
+  }
+
+  all(): RuntimeBenchmark[] {
+    return Array.from(this.data.values());
+  }
+
+  /**
+   * Get benchmark score for a specific category.
+   */
+  getCategoryScore(runtimeId: string, category: string): number {
+    const b = this.data.get(runtimeId);
+    if (!b) return 0;
+    switch (category) {
+      case "coding": return b.coding;
+      case "review": return b.review;
+      case "planning": return b.planning;
+      case "reasoning": return b.reasoning;
+      default: return 0;
+    }
+  }
+
+  /**
+   * Get overall benchmark score (weighted average).
+   */
+  getOverallScore(runtimeId: string): number {
+    const b = this.data.get(runtimeId);
+    if (!b) return 0;
+    return (b.coding * 0.3 + b.review * 0.25 + b.planning * 0.25 + b.reasoning * 0.2);
+  }
+
+  private persist(): void {
+    const data: Record<string, RuntimeBenchmark> = {};
+    for (const [k, v] of this.data) data[k] = v;
+    fs.writeFileSync(BENCHMARK_FILE, JSON.stringify(data, null, 2));
+  }
+
+  private loadPersisted(): void {
+    if (!fs.existsSync(BENCHMARK_FILE)) return;
+    try {
+      const data = JSON.parse(fs.readFileSync(BENCHMARK_FILE, "utf-8"));
+      for (const [k, v] of Object.entries(data)) {
+        this.data.set(k, v as RuntimeBenchmark);
+      }
+    } catch (e) {
+      console.warn("[BenchmarkDataset] Failed to load persisted data:", e instanceof Error ? e.message : e);
+    }
+  }
+}

package/src/benchmark/BenchmarkPlan.ts

@@ -0,0 +1,451 @@
+/**
+ * Execution Runtime Freeze + Benchmark Execution Plan v1.0
+ * 
+ * 冻结架构 + 建立系统性能基线 + 验证真实运行稳定性
+ * 
+ * 系统从工程完成 → 变成可验证产品
+ */
+
+// ═══════════════════════════════════════════════════════════════
+// Phase 1: Freeze Architecture（架构冻结）
+// ═══════════════════════════════════════════════════════════════
+
+export interface FreezeConfig {
+  frozen: boolean;
+  archVersion: string;
+  timestamp: number;
+  allowedChanges: string[];
+  prohibitedChanges: string[];
+}
+
+export class ArchitectureFreeze {
+  private config: FreezeConfig;
+
+  constructor() {
+    this.config = {
+      frozen: false,
+      archVersion: "v1.0-stable",
+      timestamp: Date.now(),
+      allowedChanges: [
+        "bug fix (non-behavioral)",
+        "performance optimization (no logic change)",
+        "observability enhancement"
+      ],
+      prohibitedChanges: [
+        "scheduler algorithm",
+        "worker execution model",
+        "event/state schema",
+        "control plane logic"
+      ]
+    };
+  }
+
+  /**
+   * 冻结架构
+   */
+  freeze(): void {
+    this.config.frozen = true;
+    this.config.timestamp = Date.now();
+  }
+
+  /**
+   * 检查是否冻结
+   */
+  isFrozen(): boolean {
+    return this.config.frozen;
+  }
+
+  /**
+   * 获取配置
+   */
+  getConfig(): FreezeConfig {
+    return { ...this.config };
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Phase 2: Benchmark Suite（基准测试套件）
+// ═══════════════════════════════════════════════════════════════
+
+// Benchmark Level
+export type BenchmarkLevel = "A" | "B" | "C" | "D";
+
+// Benchmark Result
+export interface BenchmarkResult {
+  level: BenchmarkLevel;
+  name: string;
+  workload: number;
+  metrics: {
+    successRate: number;
+    latencyP50: number;
+    latencyP95: number;
+    latencyP99: number;
+    throughput: number;
+    recoveryRate: number;
+  };
+  passed: boolean;
+  timestamp: number;
+}
+
+export class BenchmarkSuite {
+  private results: BenchmarkResult[] = [];
+
+  /**
+   * Level A: Functional Benchmark（正确性）
+   */
+  async runFunctionalBenchmark(workload: number, executor: (tasks: number) => Promise<{
+    success: number;
+    failed: number;
+    latency: number[];
+  }>): Promise<BenchmarkResult> {
+    const result = await executor(workload);
+    const successRate = result.success / workload;
+    const latency = result.latency.sort((a, b) => a - b);
+
+    const benchmarkResult: BenchmarkResult = {
+      level: "A",
+      name: "Functional Benchmark",
+      workload,
+      metrics: {
+        successRate,
+        latencyP50: latency[Math.floor(latency.length * 0.5)] || 0,
+        latencyP95: latency[Math.floor(latency.length * 0.95)] || 0,
+        latencyP99: latency[Math.floor(latency.length * 0.99)] || 0,
+        throughput: workload / (Date.now() / 1000),
+        recoveryRate: 0
+      },
+      passed: successRate >= 0.95,
+      timestamp: Date.now()
+    };
+
+    this.results.push(benchmarkResult);
+    return benchmarkResult;
+  }
+
+  /**
+   * Level B: Performance Benchmark（性能）
+   */
+  async runPerformanceBenchmark(workload: number, executor: (tasks: number) => Promise<{
+    success: number;
+    failed: number;
+    latency: number[];
+    duration: number;
+  }>): Promise<BenchmarkResult> {
+    const result = await executor(workload);
+    const successRate = result.success / workload;
+    const latency = result.latency.sort((a, b) => a - b);
+    const throughput = workload / (result.duration / 1000);
+
+    const benchmarkResult: BenchmarkResult = {
+      level: "B",
+      name: "Performance Benchmark",
+      workload,
+      metrics: {
+        successRate,
+        latencyP50: latency[Math.floor(latency.length * 0.5)] || 0,
+        latencyP95: latency[Math.floor(latency.length * 0.95)] || 0,
+        latencyP99: latency[Math.floor(latency.length * 0.99)] || 0,
+        throughput,
+        recoveryRate: 0
+      },
+      passed: latency[Math.floor(latency.length * 0.95)] < 2000,
+      timestamp: Date.now()
+    };
+
+    this.results.push(benchmarkResult);
+    return benchmarkResult;
+  }
+
+  /**
+   * Level C: Reliability Benchmark（稳定性）
+   */
+  async runReliabilityBenchmark(workload: number, faultRate: number, executor: (tasks: number, faultRate: number) => Promise<{
+    success: number;
+    failed: number;
+    recovered: number;
+    latency: number[];
+  }>): Promise<BenchmarkResult> {
+    const result = await executor(workload, faultRate);
+    const successRate = result.success / workload;
+    const recoveryRate = result.recovered / result.failed;
+    const latency = result.latency.sort((a, b) => a - b);
+
+    const benchmarkResult: BenchmarkResult = {
+      level: "C",
+      name: "Reliability Benchmark",
+      workload,
+      metrics: {
+        successRate,
+        latencyP50: latency[Math.floor(latency.length * 0.5)] || 0,
+        latencyP95: latency[Math.floor(latency.length * 0.95)] || 0,
+        latencyP99: latency[Math.floor(latency.length * 0.99)] || 0,
+        throughput: 0,
+        recoveryRate
+      },
+      passed: recoveryRate >= 0.9,
+      timestamp: Date.now()
+    };
+
+    this.results.push(benchmarkResult);
+    return benchmarkResult;
+  }
+
+  /**
+   * 获取所有结果
+   */
+  getResults(): BenchmarkResult[] {
+    return [...this.results];
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Phase 3: Load Profiles（负载模型）
+// ═══════════════════════════════════════════════════════════════
+
+export type LoadProfile = "steady" | "burst" | "dag_explosion" | "retry_storm";
+
+export interface LoadConfig {
+  profile: LoadProfile;
+  tasksPerMinute: number;
+  burstSize?: number;
+  faultRate?: number;
+  duration: number;
+}
+
+export class LoadGenerator {
+  /**
+   * 生成负载配置
+   */
+  static createConfig(profile: LoadProfile): LoadConfig {
+    switch (profile) {
+      case "steady":
+        return { profile, tasksPerMinute: 100, duration: 60000 };
+      case "burst":
+        return { profile, tasksPerMinute: 6000, burstSize: 1000, duration: 10000 };
+      case "dag_explosion":
+        return { profile, tasksPerMinute: 200, duration: 30000 };
+      case "retry_storm":
+        return { profile, tasksPerMinute: 100, faultRate: 0.3, duration: 60000 };
+    }
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Phase 4: Metrics Definition（指标定义）
+// ═══════════════════════════════════════════════════════════════
+
+export interface SystemMetrics {
+  executionSuccessRate: number;
+  systemLatencyP95: number;
+  schedulerEfficiency: number;
+  recoveryRate: number;
+  eventConsistency: boolean;
+}
+
+export class MetricsCollector {
+  private metrics: SystemMetrics[] = [];
+
+  /**
+   * 收集指标
+   */
+  collect(metrics: SystemMetrics): void {
+    this.metrics.push({
+      ...metrics,
+    });
+  }
+
+  /**
+   * 获取最新指标
+   */
+  getLatest(): SystemMetrics | undefined {
+    return this.metrics[this.metrics.length - 1];
+  }
+
+  /**
+   * 检查 SLA
+   */
+  checkSLA(): {
+    passed: boolean;
+    violations: string[];
+  } {
+    const latest = this.getLatest();
+    if (!latest) {
+      return { passed: false, violations: ["No metrics collected"] };
+    }
+
+    const violations: string[] = [];
+
+    if (latest.executionSuccessRate < 0.95) {
+      violations.push(`Execution success rate: ${(latest.executionSuccessRate * 100).toFixed(1)}% < 95%`);
+    }
+
+    if (latest.systemLatencyP95 > 2000) {
+      violations.push(`System latency P95: ${latest.systemLatencyP95}ms > 2000ms`);
+    }
+
+    if (latest.recoveryRate < 0.9) {
+      violations.push(`Recovery rate: ${(latest.recoveryRate * 100).toFixed(1)}% < 90%`);
+    }
+
+    return {
+      passed: violations.length === 0,
+      violations
+    };
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Phase 5: Production Readiness Report（生产就绪报告）
+// ═══════════════════════════════════════════════════════════════
+
+export interface BenchmarkReport {
+  runId: string;
+  timestamp: number;
+  archVersion: string;
+  functional: {
+    successRate: number;
+  };
+  performance: {
+    p50Latency: number;
+    p95Latency: number;
+    throughput: number;
+  };
+  reliability: {
+    recoveryRate: number;
+    failureRate: number;
+  };
+  stability: {
+    memoryDrift: "low" | "medium" | "high";
+    queueGrowth: "stable" | "growing" | "shrinking";
+  };
+  readinessScore: number;
+}
+
+export class ProductionReadinessReport {
+  /**
+   * 生成报告
+   */
+  generate(
+    archVersion: string,
+    benchmarkResults: BenchmarkResult[],
+    metrics: SystemMetrics
+  ): BenchmarkReport {
+    // 计算功能指标
+    const functionalResults = benchmarkResults.filter(r => r.level === "A");
+    const avgSuccessRate = functionalResults.length > 0
+      ? functionalResults.reduce((sum, r) => sum + r.metrics.successRate, 0) / functionalResults.length
+      : 0;
+
+    // 计算性能指标
+    const performanceResults = benchmarkResults.filter(r => r.level === "B");
+    const avgP50 = performanceResults.length > 0
+      ? performanceResults.reduce((sum, r) => sum + r.metrics.latencyP50, 0) / performanceResults.length
+      : 0;
+    const avgP95 = performanceResults.length > 0
+      ? performanceResults.reduce((sum, r) => sum + r.metrics.latencyP95, 0) / performanceResults.length
+      : 0;
+    const avgThroughput = performanceResults.length > 0
+      ? performanceResults.reduce((sum, r) => sum + r.metrics.throughput, 0) / performanceResults.length
+      : 0;
+
+    // 计算可靠性指标
+    const reliabilityResults = benchmarkResults.filter(r => r.level === "C");
+    const avgRecoveryRate = reliabilityResults.length > 0
+      ? reliabilityResults.reduce((sum, r) => sum + r.metrics.recoveryRate, 0) / reliabilityResults.length
+      : 0;
+
+    // 计算就绪分数
+    const readinessScore = this.calculateReadinessScore({
+      successRate: avgSuccessRate,
+      latencyP95: avgP95,
+      recoveryRate: avgRecoveryRate
+    });
+
+    return {
+      runId: `run-${Date.now().toString(36)}`,
+      timestamp: Date.now(),
+      archVersion,
+      functional: {
+        successRate: avgSuccessRate
+      },
+      performance: {
+        p50Latency: avgP50,
+        p95Latency: avgP95,
+        throughput: avgThroughput
+      },
+      reliability: {
+        recoveryRate: avgRecoveryRate,
+        failureRate: 1 - avgSuccessRate
+      },
+      stability: {
+        memoryDrift: "low",
+        queueGrowth: "stable"
+      },
+      readinessScore
+    };
+  }
+
+  /**
+   * 计算就绪分数
+   */
+  private calculateReadinessScore(params: {
+    successRate: number;
+    latencyP95: number;
+    recoveryRate: number;
+  }): number {
+    let score = 0;
+
+    // 成功率 (40分)
+    score += Math.min(40, params.successRate * 40);
+
+    // 延迟 (30分)
+    if (params.latencyP95 < 1000) {
+      score += 30;
+    } else if (params.latencyP95 < 2000) {
+      score += 20;
+    } else if (params.latencyP95 < 5000) {
+      score += 10;
+    }
+
+    // 恢复率 (30分)
+    score += Math.min(30, params.recoveryRate * 30);
+
+    return Math.round(score);
+  }
+
+  /**
+   * 格式化报告
+   */
+  format(report: BenchmarkReport): string {
+    const lines: string[] = [];
+    lines.push("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    lines.push("Production Readiness Report");
+    lines.push("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    lines.push("");
+    lines.push(`Run ID: ${report.runId}`);
+    lines.push(`Architecture: ${report.archVersion}`);
+    lines.push(`Timestamp: ${new Date(report.timestamp).toISOString()}`);
+    lines.push("");
+    lines.push("Functional:");
+    lines.push(`  Success Rate: ${(report.functional.successRate * 100).toFixed(1)}%`);
+    lines.push("");
+    lines.push("Performance:");
+    lines.push(`  P50 Latency: ${report.performance.p50Latency.toFixed(0)}ms`);
+    lines.push(`  P95 Latency: ${report.performance.p95Latency.toFixed(0)}ms`);
+    lines.push(`  Throughput: ${report.performance.throughput.toFixed(1)} tasks/sec`);
+    lines.push("");
+    lines.push("Reliability:");
+    lines.push(`  Recovery Rate: ${(report.reliability.recoveryRate * 100).toFixed(1)}%`);
+    lines.push(`  Failure Rate: ${(report.reliability.failureRate * 100).toFixed(1)}%`);
+    lines.push("");
+    lines.push("Stability:");
+    lines.push(`  Memory Drift: ${report.stability.memoryDrift}`);
+    lines.push(`  Queue Growth: ${report.stability.queueGrowth}`);
+    lines.push("");
+    lines.push(`Readiness Score: ${report.readinessScore}/100`);
+    lines.push("");
+    lines.push("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+
+    return lines.join("\n");
+  }
+}