devassist-agent 1.0.0

package/src/modules/runtime/index.js

@@ -0,0 +1,64 @@
+/**
+ * Runtime module index — exports all Layer 2 base code modules.
+ *
+ * This file is used both:
+ * 1. Internally by devassist for testing
+ * 2. As the entry point for installed base code in projects
+ */
+
+const { ToolRegistry, registry, MODULE_TYPES, TOOL_INTERFACE } = require('./tool-registry');
+const { ChannelAgent, ActionRouter, PROTOCOL_VERSION, STATE, PRIORITY } = require('./channel-agent');
+const { compose, requestLogger, authGuard, rateLimiter, schemaValidator, errorHandler, corsHandler } = require('./channel-middleware');
+const { InfrastructureGuard, Probe, HttpProbe, DatabaseProbe, MemoryProbe, DiskProbe, ProcessProbe, HEALTH_STATE } = require('./infrastructure-guard');
+const { NotificationCenter, center, Channel, LogChannel, EmailChannel, WebhookChannel, DingTalkChannel, LEVELS } = require('./notification-center');
+const { SchemaGatekeeper, gatekeeper, LAYERS, SEVERITY } = require('./schema-gatekeeper');
+
+module.exports = {
+  // ToolRegistry
+  ToolRegistry,
+  registry,
+  MODULE_TYPES,
+  TOOL_INTERFACE,
+
+  // ChannelAgent
+  ChannelAgent,
+  ActionRouter,
+  PROTOCOL_VERSION,
+  CHANNEL_STATE: STATE,
+  PRIORITY,
+
+  // ChannelMiddleware
+  compose,
+  requestLogger,
+  authGuard,
+  rateLimiter,
+  schemaValidator,
+  errorHandler,
+  corsHandler,
+
+  // InfrastructureGuard
+  InfrastructureGuard,
+  Probe,
+  HttpProbe,
+  DatabaseProbe,
+  MemoryProbe,
+  DiskProbe,
+  ProcessProbe,
+  HEALTH_STATE,
+
+  // NotificationCenter
+  NotificationCenter,
+  center,
+  Channel,
+  LogChannel,
+  EmailChannel,
+  WebhookChannel,
+  DingTalkChannel,
+  NOTIF_LEVELS: LEVELS,
+
+  // SchemaGatekeeper
+  SchemaGatekeeper,
+  gatekeeper,
+  GATEKEEPER_LAYERS: LAYERS,
+  SEVERITY,
+};

package/src/modules/runtime/infrastructure-guard.js

@@ -0,0 +1,582 @@
+/**
+ * InfrastructureGuard - Runtime health monitoring (5 probes)
+ *
+ * Design from 通知与健康检查基础设施_完整报告.md:
+ *   - 5 probes: HTTP, Database, Memory, Disk, Process
+ *   - Adaptive frequency based on stability (EMA learning)
+ *   - FSM: HEALTHY -> DEGRADED -> UNHEALTHY -> RECOVERING -> HEALTHY
+ *   - Alerting via EventBus -> NotificationCenter
+ *
+ * This is the runtime "always-on" guard that catches production issues
+ * (failure #1 port conflicts, #4 memory leaks, #10 process crashes, etc.)
+ */
+
+const { bus } = require('../../core/event-bus');
+const { Logger } = require('../../core/logger');
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+
+const log = new Logger('InfrastructureGuard');
+
+const HEALTH_STATE = {
+  HEALTHY:    'healthy',
+  DEGRADED:   'degraded',
+  UNHEALTHY:  'unhealthy',
+  RECOVERING: 'recovering',
+  UNKNOWN:    'unknown',
+};
+
+const TRANSITIONS = {
+  [HEALTH_STATE.HEALTHY]:    [HEALTH_STATE.DEGRADED, HEALTH_STATE.UNHEALTHY],
+  [HEALTH_STATE.DEGRADED]:   [HEALTH_STATE.HEALTHY, HEALTH_STATE.UNHEALTHY],
+  [HEALTH_STATE.UNHEALTHY]:  [HEALTH_STATE.RECOVERING, HEALTH_STATE.DEGRADED],
+  [HEALTH_STATE.RECOVERING]: [HEALTH_STATE.HEALTHY, HEALTH_STATE.UNHEALTHY],
+  [HEALTH_STATE.UNKNOWN]:    [HEALTH_STATE.HEALTHY, HEALTH_STATE.UNHEALTHY],
+};
+
+// ============ Probes ============
+
+/**
+ * Base Probe class.
+ */
+class Probe {
+  constructor(name, opts = {}) {
+    this.name = name;
+    this.interval = opts.interval || 30000;
+    this.timeout = opts.timeout || 5000;
+    this.enabled = opts.enabled !== false;
+    this._timer = null;
+    this._lastResult = null;
+    this._consecutiveFailures = 0;
+    this._consecutiveSuccesses = 0;
+  }
+
+  /**
+   * Run the probe check. Override in subclass.
+   * @returns {Promise<{ healthy: boolean, details: object, latency: number }>}
+   */
+  async check() {
+    throw new Error('Probe.check() must be overridden');
+  }
+
+  /**
+   * Start periodic checking.
+   */
+  start(onResult) {
+    if (this._timer) return;
+    this.enabled = true;
+
+    const run = async () => {
+      const result = await this._safeCheck();
+      this._lastResult = result;
+
+      if (result.healthy) {
+        this._consecutiveSuccesses++;
+        this._consecutiveFailures = 0;
+      } else {
+        this._consecutiveFailures++;
+        this._consecutiveSuccesses = 0;
+      }
+
+      if (typeof onResult === 'function') {
+        onResult(this, result);
+      }
+
+      // Adaptive interval: check more frequently when unhealthy
+      const nextInterval = result.healthy ? this.interval : Math.max(this.interval / 3, 5000);
+      this._timer = setTimeout(run, nextInterval);
+      this._timer.unref?.();
+    };
+
+    run();
+  }
+
+  stop() {
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+    this.enabled = false;
+  }
+
+  async _safeCheck() {
+    const start = Date.now();
+    try {
+      const timeoutPromise = new Promise((_, reject) =>
+        setTimeout(() => reject(new Error('Probe timeout')), this.timeout)
+      );
+      const result = await Promise.race([this.check(), timeoutPromise]);
+      return { ...result, latency: Date.now() - start };
+    } catch (err) {
+      return {
+        healthy: false,
+        details: { error: err.message },
+        latency: Date.now() - start,
+      };
+    }
+  }
+
+  get lastResult() {
+    return this._lastResult;
+  }
+
+  get consecutiveFailures() {
+    return this._consecutiveFailures;
+  }
+
+  get consecutiveSuccesses() {
+    return this._consecutiveSuccesses;
+  }
+}
+
+/**
+ * HTTP Probe — checks if an HTTP endpoint responds with 2xx.
+ */
+class HttpProbe extends Probe {
+  constructor(opts = {}) {
+    super('http', opts);
+    this.url = opts.url || 'http://localhost:8080/health';
+    this.expectedStatus = opts.expectedStatus || 200;
+  }
+
+  async check() {
+    const res = await fetch(this.url, {
+      method: 'GET',
+      signal: AbortSignal.timeout ? AbortSignal.timeout(this.timeout) : undefined,
+    });
+    return {
+      healthy: res.status === this.expectedStatus,
+      details: {
+        url: this.url,
+        status: res.status,
+        statusText: res.statusText,
+      },
+    };
+  }
+}
+
+/**
+ * Database Probe — checks if a database query succeeds.
+ */
+class DatabaseProbe extends Probe {
+  constructor(opts = {}) {
+    super('database', opts);
+    this.queryFn = opts.queryFn || (async () => true);
+  }
+
+  async check() {
+    const result = await this.queryFn();
+    return {
+      healthy: result === true || (result && result.healthy !== false),
+      details: typeof result === 'object' ? result : { connected: result },
+    };
+  }
+}
+
+/**
+ * Memory Probe — checks process memory usage.
+ */
+class MemoryProbe extends Probe {
+  constructor(opts = {}) {
+    super('memory', opts);
+    this.maxHeapMB = opts.maxHeapMB || 512;     // 512MB default
+    this.maxRssMB = opts.maxRssMB || 1024;      // 1GB default
+    this.warnHeapMB = opts.warnHeapMB || 384;   // 75% of max
+  }
+
+  async check() {
+    const mem = process.memoryUsage();
+    const heapMB = Math.round(mem.heapUsed / 1024 / 1024);
+    const rssMB = Math.round(mem.rss / 1024 / 1024);
+    const systemFreeMB = Math.round(os.freemem() / 1024 / 1024);
+    const systemTotalMB = Math.round(os.totalmem() / 1024 / 1024);
+
+    let healthy = true;
+    let warning = null;
+
+    if (heapMB > this.maxHeapMB) {
+      healthy = false;
+      warning = `Heap usage ${heapMB}MB exceeds limit ${this.maxHeapMB}MB`;
+    } else if (heapMB > this.warnHeapMB) {
+      warning = `Heap usage ${heapMB}MB approaching limit ${this.maxHeapMB}MB`;
+    }
+
+    if (rssMB > this.maxRssMB) {
+      healthy = false;
+      warning = `RSS ${rssMB}MB exceeds limit ${this.maxRssMB}MB`;
+    }
+
+    return {
+      healthy,
+      details: {
+        heapUsedMB: heapMB,
+        heapLimitMB: this.maxHeapMB,
+        rssMB,
+        systemFreeMB,
+        systemTotalMB,
+        warning,
+      },
+    };
+  }
+}
+
+/**
+ * Disk Probe — checks available disk space on a path.
+ */
+class DiskProbe extends Probe {
+  constructor(opts = {}) {
+    super('disk', opts);
+    this.path = opts.path || process.cwd();
+    this.minFreeMB = opts.minFreeMB || 500; // 500MB minimum
+  }
+
+  async check() {
+    try {
+      const stats = fs.statSync(this.path);
+      // Use fs.statfs if available (Node 18.15+)
+      if (fs.statfs) {
+        const fsStats = fs.statfsSync(this.path);
+        const freeMB = Math.round(fsStats.bavail * fsStats.bsize / 1024 / 1024);
+        const totalMB = Math.round(fsStats.blocks * fsStats.bsize / 1024 / 1024);
+        return {
+          healthy: freeMB >= this.minFreeMB,
+          details: {
+            path: this.path,
+            freeMB,
+            totalMB,
+            minFreeMB: this.minFreeMB,
+            usagePercent: Math.round((1 - freeMB / totalMB) * 100),
+          },
+        };
+      }
+      // Fallback: just check the path exists
+      return {
+        healthy: true,
+        details: { path: this.path, note: 'statfs not available, existence check only' },
+      };
+    } catch (err) {
+      return {
+        healthy: false,
+        details: { path: this.path, error: err.message },
+      };
+    }
+  }
+}
+
+/**
+ * Process Probe — checks if child processes are alive.
+ */
+class ProcessProbe extends Probe {
+  constructor(opts = {}) {
+    super('process', opts);
+    this.checks = opts.checks || []; // [{ name, pid | checkFn }]
+  }
+
+  async check() {
+    const results = [];
+    let allHealthy = true;
+
+    for (const check of this.checks) {
+      try {
+        if (check.pid) {
+          // Check if process with given PID is alive
+          process.kill(check.pid, 0); // signal 0 = check existence
+          results.push({ name: check.name, pid: check.pid, alive: true });
+        } else if (typeof check.checkFn === 'function') {
+          const alive = await check.checkFn();
+          results.push({ name: check.name, alive });
+          if (!alive) allHealthy = false;
+        }
+      } catch (err) {
+        results.push({ name: check.name, pid: check.pid, alive: false, error: err.message });
+        allHealthy = false;
+      }
+    }
+
+    return {
+      healthy: allHealthy,
+      details: { processes: results },
+    };
+  }
+}
+
+// ============ InfrastructureGuard ============
+
+class InfrastructureGuard {
+  constructor(opts = {}) {
+    this._probes = new Map();
+    this._state = HEALTH_STATE.UNKNOWN;
+    this._listeners = [];
+    this._history = [];
+    this._maxHistory = 100;
+    this._checkInterval = opts.checkInterval || 30000;
+
+    // Learning engine — adaptive probe frequency
+    this._learning = {
+      totalChecks: 0,
+      totalFailures: 0,
+      stability: 1.0,
+      lastHealthyAt: Date.now(),
+
+      record(success) {
+        this.totalChecks++;
+        if (!success) this.totalFailures++;
+        if (success) this.lastHealthyAt = Date.now();
+        const total = Math.max(this.totalChecks, 1);
+        this.stability = 1 - (this.totalFailures / total);
+      },
+
+      getAdaptiveInterval() {
+        if (this.stability > 0.95) return 45000;  // Very stable → 45s
+        if (this.stability > 0.85) return 30000;  // Stable → 30s
+        if (this.stability > 0.6) return 20000;   // Fair → 20s
+        return 10000;                               // Unstable → 10s
+      },
+
+      getReport() {
+        return {
+          totalChecks: this.totalChecks,
+          totalFailures: this.totalFailures,
+          stability: Math.round(this.stability * 100) / 100,
+          adaptiveIntervalMs: this.getAdaptiveInterval(),
+          lastHealthyAt: this.lastHealthyAt,
+        };
+      },
+    };
+  }
+
+  /**
+   * Register a probe.
+   */
+  registerProbe(probe) {
+    if (!(probe instanceof Probe)) {
+      throw new Error('Must be a Probe instance');
+    }
+    this._probes.set(probe.name, probe);
+    log.info(`探针已注册：${probe.name}（间隔：${probe.interval}ms）`);
+  }
+
+  /**
+   * Add an HTTP probe.
+   */
+  addHttpProbe(opts) {
+    this.registerProbe(new HttpProbe(opts));
+    return this;
+  }
+
+  /**
+   * Add a database probe.
+   */
+  addDatabaseProbe(opts) {
+    this.registerProbe(new DatabaseProbe(opts));
+    return this;
+  }
+
+  /**
+   * Add a memory probe.
+   */
+  addMemoryProbe(opts) {
+    this.registerProbe(new MemoryProbe(opts));
+    return this;
+  }
+
+  /**
+   * Add a disk probe.
+   */
+  addDiskProbe(opts) {
+    this.registerProbe(new DiskProbe(opts));
+    return this;
+  }
+
+  /**
+   * Add a process probe.
+   */
+  addProcessProbe(opts) {
+    this.registerProbe(new ProcessProbe(opts));
+    return this;
+  }
+
+  /**
+   * Start all probes.
+   */
+  start() {
+    for (const probe of this._probes.values()) {
+      probe.start((p, result) => this._onProbeResult(p, result));
+    }
+    this._transition(HEALTH_STATE.HEALTHY);
+    log.info(`InfrastructureGuard 已启动，共 ${this._probes.size} 个探针`);
+    bus.emit('guard:started', { probes: Array.from(this._probes.keys()) });
+  }
+
+  /**
+   * Stop all probes.
+   */
+  stop() {
+    for (const probe of this._probes.values()) {
+      probe.stop();
+    }
+    log.info('InfrastructureGuard 已停止');
+    bus.emit('guard:stopped', {});
+  }
+
+  /**
+   * Run a single health check across all probes.
+   */
+  async checkNow() {
+    const results = {};
+    let allHealthy = true;
+    let anyDegraded = false;
+
+    for (const [name, probe] of this._probes) {
+      const result = await probe._safeCheck();
+      probe._lastResult = result;
+      results[name] = result;
+      if (!result.healthy) {
+        allHealthy = false;
+        if (probe.consecutiveFailures < 3) {
+          anyDegraded = true;
+        }
+      }
+    }
+
+    const newState = allHealthy ? HEALTH_STATE.HEALTHY
+      : anyDegraded ? HEALTH_STATE.DEGRADED
+      : HEALTH_STATE.UNHEALTHY;
+
+    if (newState !== this._state) {
+      this._transition(newState);
+    }
+
+    this._learning.record(allHealthy);
+
+    return {
+      state: this._state,
+      healthy: allHealthy,
+      probes: results,
+      learning: this._learning.getReport(),
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Get current health status.
+   */
+  getStatus() {
+    const probes = {};
+    for (const [name, probe] of this._probes) {
+      probes[name] = {
+        enabled: probe.enabled,
+        lastResult: probe.lastResult,
+        consecutiveFailures: probe.consecutiveFailures,
+        consecutiveSuccesses: probe.consecutiveSuccesses,
+      };
+    }
+    return {
+      state: this._state,
+      probes,
+      learning: this._learning.getReport(),
+      uptime: process.uptime(),
+    };
+  }
+
+  /**
+   * Handle individual probe results.
+   */
+  _onProbeResult(probe, result) {
+    this._learning.record(result.healthy);
+
+    // Record in history
+    this._history.push({
+      probe: probe.name,
+      healthy: result.healthy,
+      latency: result.latency,
+      details: result.details,
+      ts: Date.now(),
+    });
+    if (this._history.length > this._maxHistory) {
+      this._history.shift();
+    }
+
+    // Emit event
+    bus.emit('guard:probe', {
+      probe: probe.name,
+      healthy: result.healthy,
+      latency: result.latency,
+      details: result.details,
+      consecutiveFailures: probe.consecutiveFailures,
+    });
+
+    // State transition logic
+    if (!result.healthy && probe.consecutiveFailures >= 3) {
+      if (this._state === HEALTH_STATE.HEALTHY) {
+        this._transition(HEALTH_STATE.DEGRADED);
+      } else if (this._state === HEALTH_STATE.DEGRADED && probe.consecutiveFailures >= 5) {
+        this._transition(HEALTH_STATE.UNHEALTHY);
+      }
+    } else if (result.healthy && probe.consecutiveSuccesses >= 3) {
+      if (this._state === HEALTH_STATE.UNHEALTHY) {
+        this._transition(HEALTH_STATE.RECOVERING);
+      } else if (this._state === HEALTH_STATE.RECOVERING || this._state === HEALTH_STATE.DEGRADED) {
+        // Check if all probes are now healthy
+        const allHealthy = Array.from(this._probes.values())
+          .every(p => !p.lastResult || p.lastResult.healthy);
+        if (allHealthy) {
+          this._transition(HEALTH_STATE.HEALTHY);
+        }
+      }
+    }
+
+    // Emit alert if unhealthy
+    if (!result.healthy && probe.consecutiveFailures === 1) {
+      bus.emit('guard:alert', {
+        probe: probe.name,
+        severity: probe.consecutiveFailures >= 5 ? 'critical' : 'warning',
+        message: `Probe '${probe.name}' is unhealthy: ${JSON.stringify(result.details)}`,
+        details: result.details,
+      });
+    }
+  }
+
+  _transition(newState) {
+    if (this._state === newState) return;
+    if (!TRANSITIONS[this._state]?.includes(newState)) return;
+
+    const old = this._state;
+    this._state = newState;
+    log.info(`健康状态转换：${old} -> ${newState}`);
+
+    this._listeners.forEach(fn => {
+      try { fn(newState, old); } catch (_) {}
+    });
+
+    bus.emit('guard:state_change', { from: old, to: newState });
+  }
+
+  onStateChange(fn) {
+    this._listeners.push(fn);
+    return () => {
+      this._listeners = this._listeners.filter(f => f !== fn);
+    };
+  }
+
+  getHistory(limit) {
+    if (limit) return this._history.slice(-limit);
+    return this._history.slice();
+  }
+
+  get state() {
+    return this._state;
+  }
+}
+
+module.exports = {
+  InfrastructureGuard,
+  Probe,
+  HttpProbe,
+  DatabaseProbe,
+  MemoryProbe,
+  DiskProbe,
+  ProcessProbe,
+  HEALTH_STATE,
+};