devassist-agent 1.0.0

package/src/modules/runtime/channel-agent.js

@@ -0,0 +1,404 @@
+/**
+ * ChannelAgent (Server-side) - Protocol handler and intelligent router
+ *
+ * This is the server-side counterpart to the client-side ChannelAgent in app.js.
+ * It receives protocol messages, verifies HMAC signatures, routes actions to
+ * ToolRegistry, and manages the server-side FSM.
+ *
+ * Protocol format (from client):
+ *   { protocol, seq, action, timestamp, token, payload, signature }
+ *
+ * Protocol response (to client):
+ *   { protocol, code, data, message, seq, timestamp }
+ *
+ * FSM States: UNINITIALIZED -> HANDSHAKING -> ONLINE -> OFFLINE -> ERROR
+ *
+ * Design from 智能体能力分析报告.md:
+ *   - PERCEIVE -> DECIDE -> ACT -> LEARN closed loop
+ *   - Adaptive heartbeat and telemetry frequency
+ *   - Server-client mutual state awareness (互感知)
+ */
+
+const crypto = require('crypto');
+const { bus } = require('../../core/event-bus');
+const { Logger } = require('../../core/logger');
+
+const log = new Logger('ChannelAgent');
+
+const PROTOCOL_VERSION = 'xiaomai-channel/1.0';
+
+const STATE = {
+  UNINITIALIZED: 'uninitialized',
+  HANDSHAKING:   'handshaking',
+  ONLINE:        'online',
+  OFFLINE:       'offline',
+  ERROR:         'error',
+};
+
+const PRIORITY = {
+  CRITICAL: 0,
+  HIGH: 1,
+  NORMAL: 2,
+  LOW: 3,
+};
+
+/**
+ * Action route table — maps action names to tool ids in ToolRegistry.
+ * This is the routing layer between the protocol and the tool system.
+ */
+class ActionRouter {
+  constructor() {
+    this._routes = new Map();
+  }
+
+  /**
+   * Register an action route.
+   * @param {string} action - Action name (e.g. 'chat.send')
+   * @param {object} route - { toolId, priority, middleware: [] }
+   */
+  register(action, route) {
+    if (this._routes.has(action)) {
+      log.warn(`动作路由被覆盖：${action}`);
+    }
+    this._routes.set(action, {
+      toolId: route.toolId,
+      priority: route.priority || PRIORITY.NORMAL,
+      middleware: route.middleware || [],
+      registeredAt: Date.now(),
+    });
+  }
+
+  unregister(action) {
+    this._routes.delete(action);
+  }
+
+  resolve(action) {
+    return this._routes.get(action) || null;
+  }
+
+  list() {
+    return Array.from(this._routes.entries()).map(([action, route]) => ({
+      action,
+      toolId: route.toolId,
+      priority: route.priority,
+    }));
+  }
+}
+
+/**
+ * Server-side ChannelAgent.
+ *
+ * Usage:
+ *   const agent = new ChannelAgent({ registry, secret });
+ *   await agent.init();
+ *
+ *   // In your HTTP handler:
+ *   const result = await agent.handleRequest(req.body, req);
+ */
+class ChannelAgent {
+  constructor(options = {}) {
+    this._registry = options.registry;
+    this._secret = options.secret || null;
+    this._router = new ActionRouter();
+    this._state = STATE.UNINITIALIZED;
+    this._listeners = [];
+    this._telemetryStore = new Map(); // clientId -> telemetry data
+    this._seqCounter = 0;
+    this._maxTelemetryAge = 5 * 60 * 1000; // 5 min
+
+    // Learning engine (server-side) — tracks client behavior patterns
+    this._learning = {
+      totalRequests: 0,
+      totalErrors: 0,
+      avgResponseTime: 0,
+      activeClients: 0,
+      errorRate: 0,
+
+      record(success, elapsedMs) {
+        this.totalRequests++;
+        if (!success) this.totalErrors++;
+        if (this.avgResponseTime === 0) {
+          this.avgResponseTime = elapsedMs;
+        } else {
+          // EMA smoothing
+          this.avgResponseTime = this.avgResponseTime * 0.7 + elapsedMs * 0.3;
+        }
+        this.errorRate = this.totalErrors / this.totalRequests;
+      },
+
+      getReport() {
+        return {
+          totalRequests: this.totalRequests,
+          totalErrors: this.totalErrors,
+          avgResponseTime: Math.round(this.avgResponseTime),
+          errorRate: Math.round(this.errorRate * 1000) / 1000,
+          activeClients: this.activeClients,
+        };
+      },
+    };
+
+    if (!this._registry) {
+      throw new Error('ChannelAgent requires a ToolRegistry instance');
+    }
+  }
+
+  /**
+   * Initialize the agent. Registers built-in actions.
+   */
+  async init() {
+    if (this._state !== STATE.UNINITIALIZED) return;
+    this._transition(STATE.HANDSHAKING);
+
+    // Register built-in actions
+    this._router.register('heartbeat.ping', {
+      toolId: null, // Handled directly, no tool needed
+      priority: PRIORITY.LOW,
+    });
+    this._router.register('channel.state', {
+      toolId: null,
+      priority: PRIORITY.LOW,
+    });
+
+    this._transition(STATE.ONLINE);
+    log.info(`ChannelAgent 已初始化（协议：${PROTOCOL_VERSION}）`);
+    bus.emit('agent:online', { protocol: PROTOCOL_VERSION });
+  }
+
+  /**
+   * Register an action route that maps to a tool.
+   */
+  route(action, toolId, opts = {}) {
+    this._router.register(action, {
+      toolId,
+      priority: opts.priority || PRIORITY.NORMAL,
+      middleware: opts.middleware || [],
+    });
+    log.info(`路由已注册：${action} -> ${toolId}`);
+  }
+
+  /**
+   * Handle an incoming protocol request.
+   *
+   * @param {object} body - The raw request body
+   * @param {object} ctx - Additional context (ip, headers, etc.)
+   * @returns {Promise<object>} Protocol response
+   */
+  async handleRequest(body, ctx = {}) {
+    const startTime = Date.now();
+    this._seqCounter++;
+
+    // --- Parse and validate protocol envelope ---
+    if (!body || typeof body !== 'object') {
+      return this._errorResponse(400, 'Invalid request body', this._seqCounter);
+    }
+
+    // Check if this is a protocol-wrapped request or a plain JSON request
+    const isProtocol = body.protocol === PROTOCOL_VERSION;
+
+    let action, payload, token, seq, timestamp, signature;
+    if (isProtocol) {
+      action = body.action;
+      payload = body.payload || {};
+      token = body.token;
+      seq = body.seq || this._seqCounter;
+      timestamp = body.timestamp;
+      signature = body.signature;
+
+      // --- Verify HMAC signature (if secret is configured) ---
+      if (this._secret && signature !== undefined) {
+        const expectedSig = this._sign(this._buildSignString(body));
+        if (signature !== expectedSig) {
+          log.warn(`动作签名验证失败：${action}`);
+          bus.emit('agent:auth_failed', { action, seq, ip: ctx.ip });
+          return this._protocolResponse(401, null, 'Signature verification failed', seq);
+        }
+      }
+    } else {
+      // Plain JSON (degraded mode) — extract action from URL path or body
+      action = body.action || ctx.action;
+      payload = body;
+      token = ctx.token;
+      seq = this._seqCounter;
+      timestamp = Date.now();
+    }
+
+    if (!action) {
+      return this._errorResponse(400, 'Missing action', seq);
+    }
+
+    // --- Resolve route ---
+    const route = this._router.resolve(action);
+    if (!route) {
+      log.warn(`未知动作：${action}`);
+      return this._protocolResponse(404, null, `Unknown action: ${action}`, seq);
+    }
+
+    // --- Handle built-in actions (no tool needed) ---
+    if (route.toolId === null) {
+      return this._handleBuiltin(action, payload, ctx, seq);
+    }
+
+    // --- Invoke tool ---
+    const toolCtx = {
+      ...ctx,
+      requestId: `${seq}-${Date.now()}`,
+      token,
+      action,
+      priority: route.priority,
+    };
+
+    try {
+      const result = await this._registry.invoke(route.toolId, payload, toolCtx);
+      const elapsed = Date.now() - startTime;
+      this._learning.record(true, elapsed);
+
+      bus.emit('agent:request', {
+        action, success: true, elapsed, seq, toolId: route.toolId,
+      });
+
+      return this._protocolResponse(200, result, null, seq);
+
+    } catch (err) {
+      const elapsed = Date.now() - startTime;
+      this._learning.record(false, elapsed);
+
+      bus.emit('agent:request', {
+        action, success: false, elapsed, seq, error: err.message,
+      });
+
+      log.error(`动作 '${action}' 失败：${err.message}`);
+      return this._protocolResponse(500, null, err.message, seq);
+    }
+  }
+
+  /**
+   * Handle built-in actions (heartbeat, state, telemetry).
+   */
+  _handleBuiltin(action, payload, ctx, seq) {
+    if (action === 'heartbeat.ping') {
+      return this._protocolResponse(200, { alive: true, timestamp: Date.now() }, null, seq);
+    }
+
+    if (action === 'channel.state') {
+      return this._protocolResponse(200, {
+        state: this._state,
+        protocol: PROTOCOL_VERSION,
+        serverTime: Date.now(),
+        learning: this._learning.getReport(),
+        activeClients: this._learning.activeClients,
+      }, null, seq);
+    }
+
+    return this._protocolResponse(404, null, `Unknown builtin action: ${action}`, seq);
+  }
+
+  /**
+   * Store client telemetry data (received via /api/channel/telemetry).
+   */
+  storeTelemetry(clientId, data) {
+    data.receivedAt = Date.now();
+    this._telemetryStore.set(clientId, data);
+    this._learning.activeClients = this._countActiveClients();
+    bus.emit('agent:telemetry', { clientId, data });
+  }
+
+  /**
+   * Get server state for client mutual awareness (互感知).
+   */
+  getServerState() {
+    return {
+      state: this._state,
+      protocol: PROTOCOL_VERSION,
+      learning: this._learning.getReport(),
+      activeClients: this._learning.activeClients,
+      uptime: process.uptime(),
+    };
+  }
+
+  /**
+   * Get learning report.
+   */
+  getLearningReport() {
+    return this._learning.getReport();
+  }
+
+  /**
+   * Get the action router (for external route management).
+   */
+  get router() {
+    return this._router;
+  }
+
+  get state() {
+    return this._state;
+  }
+
+  // --- FSM ---
+  _transition(newState) {
+    if (this._state === newState) return;
+    const old = this._state;
+    this._state = newState;
+    this._listeners.forEach(fn => {
+      try { fn(newState, old); } catch (_) {}
+    });
+    bus.emit('agent:state_change', { from: old, to: newState });
+  }
+
+  onStateChange(fn) {
+    this._listeners.push(fn);
+    return () => {
+      this._listeners = this._listeners.filter(f => f !== fn);
+    };
+  }
+
+  // --- Protocol helpers ---
+  _protocolResponse(code, data, message, seq) {
+    return {
+      protocol: PROTOCOL_VERSION,
+      code,
+      data: data || null,
+      message: message || (code === 200 ? 'OK' : 'Error'),
+      seq,
+      timestamp: Date.now(),
+    };
+  }
+
+  _errorResponse(code, message, seq) {
+    return this._protocolResponse(code, null, message, seq);
+  }
+
+  _buildSignString(body) {
+    return `${body.protocol}${body.seq}${body.timestamp}${body.action}${JSON.stringify(body.payload)}`;
+  }
+
+  _sign(data) {
+    return crypto
+      .createHmac('sha256', this._secret)
+      .update(data)
+      .digest('hex');
+  }
+
+  _countActiveClients() {
+    const now = Date.now();
+    let count = 0;
+    for (const [, data] of this._telemetryStore) {
+      if (data.receivedAt && now - data.receivedAt < this._maxTelemetryAge) {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Graceful shutdown.
+   */
+  destroy() {
+    this._transition(STATE.OFFLINE);
+    this._listeners = [];
+    this._telemetryStore.clear();
+    log.info('ChannelAgent 已销毁');
+    bus.emit('agent:offline', {});
+  }
+}
+
+module.exports = { ChannelAgent, ActionRouter, PROTOCOL_VERSION, STATE, PRIORITY };

package/src/modules/runtime/channel-middleware.js

@@ -0,0 +1,316 @@
+/**
+ * ChannelMiddleware - Request/response middleware chain
+ *
+ * Provides a composable middleware system for processing requests before they
+ * reach the ChannelAgent/tool handlers, and responses before they go back to
+ * the client.
+ *
+ * Built-in middlewares:
+ *   - requestLogger: Logs every request with timing
+ *   - authGuard: Verifies JWT token
+ *   - rateLimiter: Per-IP rate limiting (sliding window)
+ *   - schemaValidator: Validates input against route schema
+ *   - errorHandler: Catches errors and formats protocol response
+ *
+ * Design pattern: Standard Koa-style compose() — each middleware can
+ * short-circuit the chain by not calling next().
+ */
+
+const { bus } = require('../../core/event-bus');
+const { Logger } = require('../../core/logger');
+
+const log = new Logger('ChannelMiddleware');
+
+/**
+ * Compose an array of middleware into a single function.
+ * Standard async middleware composition.
+ *
+ * @param {function[]} middlewares - Array of (ctx, next) => {}
+ * @returns {function} Composed middleware
+ */
+function compose(middlewares) {
+  if (!Array.isArray(middlewares)) {
+    throw new TypeError('Middleware stack must be an array');
+  }
+  for (const fn of middlewares) {
+    if (typeof fn !== 'function') {
+      throw new TypeError('Middleware must be a function');
+    }
+  }
+
+  return function composed(ctx, next) {
+    let index = -1;
+
+    function dispatch(i) {
+      if (i <= index) {
+        return Promise.reject(new Error('next() called multiple times'));
+      }
+      index = i;
+      let fn = middlewares[i];
+      if (i === middlewares.length) fn = next;
+      if (!fn) return Promise.resolve();
+      try {
+        return Promise.resolve(fn(ctx, function nextFn() {
+          return dispatch(i + 1);
+        }));
+      } catch (err) {
+        return Promise.reject(err);
+      }
+    }
+
+    return dispatch(0);
+  };
+}
+
+// ============ Built-in Middlewares ============
+
+/**
+ * Request Logger — logs every request with method, action, and timing.
+ */
+function requestLogger() {
+  return async function (ctx, next) {
+    const start = Date.now();
+    ctx._startTime = start;
+
+    await next();
+
+    const elapsed = Date.now() - start;
+    const action = ctx.action || ctx.body?.action || 'unknown';
+    const code = ctx.response?.code || 200;
+
+    if (code === 200) {
+      log.info(`${ctx.ip || '未知'} ${action} ${code} ${elapsed}ms`);
+    } else {
+      log.warn(`${ctx.ip || '未知'} ${action} ${code} ${elapsed}ms`);
+    }
+
+    bus.emit('middleware:logged', { action, code, elapsed, ip: ctx.ip });
+  };
+}
+
+/**
+ * Auth Guard — verifies JWT token.
+ *
+ * @param {object} opts - { exclude: ['action1', 'action2'] } actions that skip auth
+ */
+function authGuard(opts = {}) {
+  const exclude = new Set(opts.exclude || [
+    'heartbeat.ping',
+    'channel.state',
+    'config.greetings',
+    'auth.send_code',
+    'auth.login',
+  ]);
+
+  return async function (ctx, next) {
+    const action = ctx.action || ctx.body?.action;
+
+    // Skip auth for excluded actions
+    if (exclude.has(action)) {
+      await next();
+      return;
+    }
+
+    const token = ctx.token || ctx.body?.token || ctx.headers?.authorization?.replace('Bearer ', '');
+
+    if (!token) {
+      ctx.response = {
+        protocol: 'xiaomai-channel/1.0',
+        code: 401,
+        data: null,
+        message: 'Authentication required',
+        seq: ctx.body?.seq || 0,
+        timestamp: Date.now(),
+      };
+      return; // Short-circuit
+    }
+
+    // Attach decoded token to context (actual JWT verification left to the app)
+    ctx.token = token;
+    try {
+      const parts = token.split('.');
+      if (parts.length === 3) {
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString());
+        ctx.user = { id: payload.sub, exp: payload.exp };
+        ctx.tokenExpiresAt = payload.exp;
+      }
+    } catch (_) {
+      // Token decode failed — let the tool handler decide
+    }
+
+    await next();
+  };
+}
+
+/**
+ * Rate Limiter — per-IP sliding window rate limiting.
+ *
+ * @param {object} opts - { windowMs, max, keyFn }
+ */
+function rateLimiter(opts = {}) {
+  const windowMs = opts.windowMs || 60 * 1000;  // 1 minute
+  const max = opts.max || 100;                    // 100 requests per window
+  const keyFn = opts.keyFn || ((ctx) => ctx.ip || 'unknown');
+
+  const buckets = new Map();
+
+  // Periodic cleanup
+  setInterval(() => {
+    const now = Date.now();
+    for (const [key, entries] of buckets) {
+      const valid = entries.filter(t => now - t < windowMs);
+      if (valid.length === 0) {
+        buckets.delete(key);
+      } else {
+        buckets.set(key, valid);
+      }
+    }
+  }, windowMs).unref?.();
+
+  return async function (ctx, next) {
+    const key = keyFn(ctx);
+    const now = Date.now();
+
+    if (!buckets.has(key)) {
+      buckets.set(key, []);
+    }
+    const entries = buckets.get(key);
+    const valid = entries.filter(t => now - t < windowMs);
+    entries.length = 0;
+    entries.push(...valid, now);
+
+    if (entries.length > max) {
+      log.warn(`${key} 触发速率限制：${entries.length}/${max}`);
+      ctx.response = {
+        protocol: 'xiaomai-channel/1.0',
+        code: 429,
+        data: null,
+        message: 'Rate limit exceeded. Please try again later.',
+        seq: ctx.body?.seq || 0,
+        timestamp: Date.now(),
+        retryAfter: Math.ceil(windowMs / 1000),
+      };
+      bus.emit('middleware:rate_limited', { key, count: entries.length, max });
+      return;
+    }
+
+    await next();
+  };
+}
+
+/**
+ * Schema Validator — validates input against a provided schema.
+ * Lightweight JSON-schema-like validation.
+ *
+ * @param {object} opts - { getSchema: (action) => schema }
+ */
+function schemaValidator(opts = {}) {
+  const getSchema = opts.getSchema || (() => null);
+
+  return async function (ctx, next) {
+    const action = ctx.action || ctx.body?.action;
+    const schema = getSchema(action);
+
+    if (!schema) {
+      await next();
+      return;
+    }
+
+    const input = ctx.body?.payload || ctx.body || {};
+
+    // Check required fields
+    if (schema.required) {
+      for (const field of schema.required) {
+        if (input[field] === undefined || input[field] === null) {
+          ctx.response = {
+            protocol: 'xiaomai-channel/1.0',
+            code: 400,
+            data: null,
+            message: `Missing required field: ${field}`,
+            seq: ctx.body?.seq || 0,
+            timestamp: Date.now(),
+          };
+          return;
+        }
+      }
+    }
+
+    // Check types
+    if (schema.properties) {
+      for (const [field, type] of Object.entries(schema.properties)) {
+        if (input[field] !== undefined) {
+          const expectedType = typeof type === 'string' ? type : type.type;
+          const actualType = Array.isArray(input[field]) ? 'array' : typeof input[field];
+          if (expectedType && actualType !== expectedType) {
+            ctx.response = {
+              protocol: 'xiaomai-channel/1.0',
+              code: 400,
+              data: null,
+              message: `Field '${field}' must be ${expectedType}, got ${actualType}`,
+              seq: ctx.body?.seq || 0,
+              timestamp: Date.now(),
+            };
+            return;
+          }
+        }
+      }
+    }
+
+    await next();
+  };
+}
+
+/**
+ * Error Handler — catches errors from downstream middleware/tools.
+ * Should be the FIRST middleware in the chain (outermost).
+ */
+function errorHandler() {
+  return async function (ctx, next) {
+    try {
+      await next();
+    } catch (err) {
+      log.error(`未处理的错误：${err.message}`);
+      bus.emit('middleware:error', { error: err.message, stack: err.stack });
+
+      ctx.response = {
+        protocol: 'xiaomai-channel/1.0',
+        code: 500,
+        data: null,
+        message: process.env.NODE_ENV === 'production'
+          ? 'Internal server error'
+          : err.message,
+        seq: ctx.body?.seq || 0,
+        timestamp: Date.now(),
+      };
+    }
+  };
+}
+
+/**
+ * CORS Handler — adds CORS headers to context.
+ */
+function corsHandler(opts = {}) {
+  const origins = opts.origins || ['*'];
+
+  return async function (ctx, next) {
+    const origin = ctx.headers?.origin;
+    if (origins.includes('*') || (origin && origins.includes(origin))) {
+      ctx.corsHeaders = {
+        'Access-Control-Allow-Origin': origins.includes('*') ? '*' : origin,
+        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+      };
+    }
+    await next();
+  };
+}
+
+module.exports = {
+  compose,
+  requestLogger,
+  authGuard,
+  rateLimiter,
+  schemaValidator,
+  errorHandler,
+  corsHandler,
+};