Skip to content

LeoYeAI/agent-master-skills / skills/agent-comm-hub

agent-comm-hub

Flagged

多智能体协同通信基础设施——基于 MCP+SSE 的实时消息、任务调度、记忆共享与进化引擎。支持 WorkBuddy、Hermes、QClaw 及任意 MCP 兼容 Agent 接入。53 个 MCP 工具、4 级权限、零外部依赖 Python SDK。触发词:agent通信、智能体通信、hub通信、多智能体、跨agent通信、任务调度、assign_task、send_message、hermes通信、workbuddy通信、agent hub、通信hub、mcp通信、记忆共享、进化引擎、策略共享、经验分享、共享记忆,共同进化

FileKindSize
.clawhub/origin.jsonconfig146 B
API_REFERENCE.mdmarkdown18.4 KB
HERMES-SETUP.mdmarkdown5.5 KB
README.mdmarkdown8.8 KB
SKILL.mdskill md16.4 KB
_meta.jsonconfig133 B
client-sdk/agent-client.d.tsscript11.6 KB
client-sdk/agent-client.jsscript28.6 KB
client-sdk/agent-client.tsscript29.8 KB
client-sdk/hermes-integration.d.tsscript785 B
client-sdk/hermes-integration.jsscript6.3 KB
client-sdk/hermes-integration.tsscript6.1 KB
client-sdk/hub_client.pyscript50.8 KB
client-sdk/workbuddy-integration.d.tsscript11 B
client-sdk/workbuddy-integration.jsscript4.3 KB
client-sdk/workbuddy-integration.tsscript4.2 KB
deploy/docker-compose.ymlconfig2.0 KB
deploy/grafana/dashboard.jsonconfig16.4 KB
deploy/grafana/provisioning/dashboards/dashboards.ymlconfig258 B
deploy/grafana/provisioning/datasources/prometheus.ymlconfig186 B
deploy/prometheus.ymlconfig408 B
docs/advanced-orchestration-guide.mdmarkdown11.8 KB
docs/evolution-engine-guide.mdmarkdown16.6 KB
docs/hermes-integration-guide.mdmarkdown22.3 KB
package-lock.jsonmanifest139.0 KB
package.jsonmanifest861 B
scripts/hub_task_runner.pyscript6.0 KB
scripts/hub_watcher.pyscript13.9 KB
scripts/install.shscript549 B
scripts/migrate_evolution_db.pyscript6.5 KB
scripts/migrate_from_agent.jsscript2.5 KB
scripts/wb_task_trigger.pyscript2.2 KB
src/db.d.tsscript3.7 KB
src/db.jsscript34.0 KB
src/db.tsscript37.4 KB
src/dedup.d.tsscript2.4 KB
src/dedup.jsscript8.5 KB
src/dedup.tsscript8.7 KB
src/errors.tsscript3.4 KB
src/evolution.d.tsscript6.6 KB
src/evolution.jsscript26.4 KB
src/evolution.tsscript31.0 KB
src/identity.d.tsscript3.4 KB
src/identity.jsscript15.9 KB
src/identity.tsscript17.1 KB
src/logger.d.tsscript1.1 KB
src/logger.jsscript2.8 KB
src/logger.tsscript3.5 KB
src/memory.d.tsscript2.1 KB
src/memory.jsscript13.0 KB
src/memory.tsscript14.3 KB
src/metrics.d.tsscript1.8 KB
src/metrics.jsscript8.4 KB
src/metrics.tsscript9.1 KB
src/orchestrator.d.tsscript6.1 KB
src/orchestrator.jsscript30.4 KB
src/orchestrator.tsscript33.4 KB
src/repo/interfaces.d.tsscript3.6 KB
src/repo/interfaces.jsscript49 B
src/repo/interfaces.tsscript4.2 KB
src/repo/sqlite-impl.d.tsscript225 B
src/repo/sqlite-impl.jsscript7.7 KB
src/repo/sqlite-impl.tsscript8.8 KB
src/repo/types.d.tsscript1021 B
src/repo/types.jsscript116 B
src/repo/types.tsscript1.6 KB
src/security.d.tsscript3.7 KB
src/security.jsscript15.0 KB
src/security.tsscript16.4 KB
src/server.d.tsscript11 B
src/server.jsscript24.7 KB
src/server.tsscript24.7 KB
src/sse.d.tsscript1.6 KB
src/sse.jsscript3.3 KB
src/sse.tsscript3.6 KB
src/stdio.d.tsscript11 B
src/stdio.jsscript1.7 KB
src/stdio.tsscript1.6 KB
src/tokenizer.d.tsscript1.3 KB
src/tokenizer.jsscript3.4 KB
src/tokenizer.tsscript3.2 KB
src/tools.d.tsscript474 B
src/tools.jsscript1.1 KB
src/tools.tsscript1.3 KB
src/tools/consumed.d.tsscript361 B
src/tools/consumed.jsscript5.5 KB
src/tools/consumed.tsscript5.3 KB
src/tools/evolution.d.tsscript660 B
src/tools/evolution.jsscript19.3 KB
src/tools/evolution.tsscript17.6 KB
src/tools/file.d.tsscript348 B
src/tools/file.jsscript7.1 KB
src/tools/file.tsscript6.5 KB
src/tools/identity.d.tsscript438 B
src/tools/identity.jsscript9.8 KB
src/tools/identity.tsscript9.3 KB
src/tools/memory.d.tsscript410 B
src/tools/memory.jsscript11.9 KB
src/tools/memory.tsscript10.8 KB
src/tools/message.d.tsscript467 B
src/tools/message.jsscript17.2 KB
src/tools/message.tsscript15.8 KB
src/tools/orchestrator.d.tsscript746 B
src/tools/orchestrator.jsscript27.8 KB
src/tools/orchestrator.tsscript24.3 KB
src/tools/security.d.tsscript386 B
src/tools/security.jsscript9.0 KB
src/tools/security.tsscript7.8 KB
src/types.tsscript5.9 KB
src/utils.d.tsscript421 B
src/utils.jsscript1.3 KB
src/utils.tsscript3.0 KB
tsconfig.jsonconfig337 B
vitest.config.tsscript1.2 KB

src/server.ts

View on GitHub
/**
 * server.ts — 主入口
 * Express HTTP 服务器 + MCP Server + SSE 推送 + Security 中间件
 *
 * Phase 5b 变更:
 *   - 结构化 JSON 日志(logger.ts)
 *   - 全局错误处理中间件
 *   - 增强健康检查(/health)
 *   - 优雅关闭(SIGTERM/SIGINT)
 *   - Prometheus metrics 端点(/metrics)
 *   - CORS + 安全头中间件
 *   - 请求追踪(traceId)
 */
import express, { type Request, type Response, type NextFunction } from "express";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { registerTools } from "./tools.js";
import { registerClient, removeClient, pushToAgent, onlineAgents, drainAllClients } from "./sse.js";
import { getDbStats, db, scheduleCleanup, stopCleanup } from "./db.js";
import { messageRepo, taskRepo, consumedRepo } from "./repo/sqlite-impl.js";
import {
  authMiddleware,
  optionalAuthMiddleware,
  checkPermission,
  getRequiredPermission,
  createInviteCode,
  auditLog,
  rateLimiter,
  type AuthContext,
} from "./security.js";
import { startHeartbeatMonitor, clearOfflineNotification, stopHeartbeatMonitor } from "./identity.js";
import { startDedupCleanup, stopDedupCleanup } from "./dedup.js";
import { getErrorMessage } from "./types.js";
import { rebuildFtsIndex } from "./memory.js";
import { logger, logError } from "./logger.js";
import { join } from "path";
import {
  getMetricsOutput,
  trackHttpRequest,
  setGauge,
  incrementGauge,
  decrementGauge,
  collectHubMetrics,
} from "./metrics.js";

// ═══════════════════════════════════════════════════════════════
// Phase 6: 配置外部化(零依赖,所有配置有默认值)
// ═══════════════════════════════════════════════════════════════
const config = {
  port:                      parseInt(process.env.PORT ?? "3100", 10),
  logLevel:                  process.env.LOG_LEVEL || "info",
  corsOrigins:               (process.env.CORS_ORIGINS ?? "").split(",").map(s => s.trim()).filter(Boolean),
  dbPath:                    process.env.DB_PATH || "./comm_hub.db",
  sseHeartbeatInterval:      parseInt(process.env.SSE_HEARTBEAT_INTERVAL ?? "10000", 10),
  sseReplayWindow:           parseInt(process.env.SSE_REPLAY_WINDOW ?? "3600", 10) * 1000,
  rateLimitWindow:           parseInt(process.env.RATE_LIMIT_WINDOW ?? "1000", 10),
  rateLimitMax:              parseInt(process.env.RATE_LIMIT_MAX ?? "10", 10),
  heartbeatOnlineThreshold:  parseInt(process.env.HEARTBEAT_ONLINE_THRESHOLD ?? "90000", 10),
  heartbeatNotifyThreshold:  parseInt(process.env.HEARTBEAT_NOTIFY_THRESHOLD ?? "300000", 10),
  heartbeatCheckInterval:    parseInt(process.env.HEARTBEAT_CHECK_INTERVAL ?? "30000", 10),
  dedupTTL:                  parseInt(process.env.DEDUP_TTL ?? "900", 10) * 1000,
  dedupCleanupInterval:      parseInt(process.env.DEDUP_CLEANUP_INTERVAL ?? "60000", 10),
  tokenExpireDays:           parseInt(process.env.TOKEN_EXPIRE_DAYS ?? "90", 10),
  uploadDir:                 process.env.UPLOAD_DIR || join(process.cwd(), "uploads"),
  maxFileSize:               parseInt(process.env.MAX_FILE_SIZE ?? "10485760", 10),  // 10MB
};

const app = express();
app.use(express.json());

// ═══════════════════════════════════════════════════════════════
// Phase 5b: CORS 中间件(零依赖)
// ═══════════════════════════════════════════════════════════════
const CORS_ORIGINS = config.corsOrigins;

app.use((req: Request, res: Response, next: NextFunction) => {
  const origin = req.headers.origin as string | undefined;
  if (origin && CORS_ORIGINS.includes(origin)) {
    res.setHeader("Access-Control-Allow-Origin", origin);
    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, PATCH, OPTIONS");
    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Trace-Id, X-Api-Key");
    res.setHeader("Access-Control-Max-Age", "86400");
  }
  if (req.method === "OPTIONS") {
    return res.sendStatus(204);
  }
  next();
});

// ═══════════════════════════════════════════════════════════════
// Phase 5b: 安全头中间件(零依赖 Helmet 替代)
// ═══════════════════════════════════════════════════════════════
app.use((_req: Request, res: Response, next: NextFunction) => {
  res.setHeader("X-Frame-Options", "DENY");
  res.setHeader("X-Content-Type-Options", "nosniff");
  res.setHeader("X-XSS-Protection", "1; mode=block");
  res.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
  res.setHeader("Content-Security-Policy", "default-src 'self'");
  next();
});

// ═══════════════════════════════════════════════════════════════
// Phase 5b: 请求追踪(traceId)
// ═══════════════════════════════════════════════════════════════
app.use((req: Request, res: Response, next: NextFunction) => {
  const traceId = (req.headers["x-trace-id"] as string) || crypto.randomUUID().slice(0, 8);
  (req as any).traceId = traceId;
  res.setHeader("X-Trace-Id", traceId);
  next();
});

// ═══════════════════════════════════════════════════════════════
// Phase 5b: HTTP 请求日志 + metrics 中间件
// ═══════════════════════════════════════════════════════════════
app.use((req: Request, res: Response, next: NextFunction) => {
  const start = Date.now();
  res.on("finish", () => {
    const duration = Date.now() - start;
    const traceId = (req as any).traceId;
    logger.info("http_request", {
      traceId,
      module: "server",
      method: req.method,
      path: req.path,
      status: res.statusCode,
      duration_ms: duration,
    });
    trackHttpRequest(req.method, req.path, res.statusCode, duration);
  });
  next();
});

// ═══════════════════════════════════════════════════════════════
// SSE 端点:Agent 启动时订阅一次,保持长连接
// GET /events/:agent_id?token=<api_token>
// ═══════════════════════════════════════════════════════════════

// SSE 重连回放窗口(秒),默认 1 小时
const SSE_REPLAY_WINDOW = config.sseReplayWindow;

app.get("/events/:agent_id", optionalAuthMiddleware, (req: Request, res: Response) => {
  const { agent_id } = req.params;
  const authContext: AuthContext | undefined = req.auth?.agent;

  // SSE 必要响应头
  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");
  res.setHeader("Connection", "keep-alive");
  res.setHeader("X-Accel-Buffering", "no");
  res.flushHeaders();

  // 注册连接
  registerClient(agent_id, res);
  incrementGauge("active_sse_connections");

  // 检查 Last-Event-ID(断线重连场景)
  const lastEventId = req.headers["last-event-id"] as string | undefined;
  if (lastEventId) {
    // 解析 lastEventId 为时间戳(毫秒)
    const since = parseInt(lastEventId, 10);
    if (!isNaN(since)) {
      // 检查是否在回放窗口内
      const now = Date.now();
      const windowStart = now - SSE_REPLAY_WINDOW;
      const effectiveSince = Math.max(since, windowStart);

      // 查询并回放该时间戳之后的消息
      const missedMessages = messageRepo.listSince(agent_id, effectiveSince);
      if (missedMessages.length > 0) {
        for (const msg of missedMessages) {
          pushToAgent(agent_id, {
            event: "new_message",
            message: msg,
          });
        }
        logger.info("SSE replay", { module: "sse", agent_id, replay_count: missedMessages.length, since: effectiveSince });
      }
    }
  } else {
    // 首次连接:补发离线期间积压的未读消息
    const pending = messageRepo.pendingFor(agent_id);
    if (pending.length > 0) {
      for (const msg of pending) {
        pushToAgent(agent_id, {
          event: "new_message",
          message: msg,
        });
      }
      messageRepo.markAllDelivered(agent_id);
      logger.info("SSE backfill", { module: "sse", agent_id, pending_count: pending.length });
    }
  }

  // 补发积压的未执行任务
  const pendingTasks = taskRepo.listFor(agent_id, "pending");
  for (const task of pendingTasks) {
    pushToAgent(agent_id, {
      event: "task_assigned",
      task: {
        ...task,
        instruction: "你有一项待执行的任务,请立即处理。",
      },
    });
  }
  if (pendingTasks.length > 0) {
    logger.info("SSE tasks push", { module: "sse", agent_id, pending_tasks: pendingTasks.length });
  }

  // 心跳(10 秒间隔)
  const heartbeat = setInterval(() => {
    try { res.write(": ping\n\n"); } catch (_) { clearInterval(heartbeat); }
  }, config.sseHeartbeatInterval);

  // 断线清理
  req.on("close", () => {
    clearInterval(heartbeat);
    removeClient(agent_id);
    decrementGauge("active_sse_connections");
  });
});

// ═══════════════════════════════════════════════════════════════
// Phase 5b: 增强健康检查端点(免认证)
// ═══════════════════════════════════════════════════════════════
app.get("/health", (_req: Request, res: Response) => {
  const stats = getDbStats();
  const mem = process.memoryUsage();
  let dbSize = 0;
  try {
    const row = db.prepare(`SELECT page_count * page_size as size FROM pragma_page_count(), pragma_page_size()`).get() as any;
    dbSize = row?.size ?? 0;
  } catch {}

  res.json({
    status: "ok",
    version: "2.4.0",
    uptime: process.uptime(),
    timestamp: Date.now(),
    memory: {
      rss: Math.round(mem.rss / 1024 / 1024),
      heap_used: Math.round(mem.heapUsed / 1024 / 1024),
      heap_total: Math.round(mem.heapTotal / 1024 / 1024),
    },
    db: {
      size: dbSize,
      size_mb: Math.round(dbSize / 1024 / 1024 * 100) / 100,
      tables: stats,
    },
    sse: {
      active_connections: onlineAgents().length,
    },
  });
});

// ═══════════════════════════════════════════════════════════════
// Phase 5b: Prometheus Metrics 端点(免认证)
// ═══════════════════════════════════════════════════════════════
app.get("/metrics", (_req: Request, res: Response) => {
  res.setHeader("Content-Type", "text/plain; version=0.0.4; charset=utf-8");
  // Phase 3.1: 拼接 Hub 数据库指标(agents / messages / trust_scores)
  const hubMetrics = collectHubMetrics(db);
  const output = getMetricsOutput() + hubMetrics;
  res.send(output);
});

// ═══════════════════════════════════════════════════════════════
// 管理端点:/admin/invite/generate — 生成邀请码
// ═══════════════════════════════════════════════════════════════
app.post("/admin/invite/generate", authMiddleware, (req: Request, res: Response) => {
  const role = req.auth?.agent?.role;
  if (role !== "admin") {
    res.status(403).json({ error: "Admin access required" });
    return;
  }

  const targetRole = req.body.role === "admin" ? "admin" as const : "member" as const;
  const code = createInviteCode(targetRole);

  auditLog("invite_generated", req.auth?.agent?.agentId ?? null, undefined, `role=${targetRole}`);

  res.json({
    success: true,
    invite_code: code,
    role: targetRole,
    expires_in: "24h",
  });
});

// ═══════════════════════════════════════════════════════════════
// REST API:供自动化脚本通过 curl 轮询任务和消息(需认证)
// ═══════════════════════════════════════════════════════════════

// GET /api/tasks?agent_id=workbuddy&status=pending
app.get("/api/tasks", authMiddleware, (req: Request, res: Response) => {
  const { agent_id, status } = req.query;
  if (!agent_id) {
    res.status(400).json({ error: "agent_id is required" });
    return;
  }
  if (status && !["pending", "in_progress", "completed", "failed"].includes(status as string)) {
    res.status(400).json({ error: `Invalid status: ${status}` });
    return;
  }
  const tasks = status
    ? taskRepo.listFor(agent_id as string, status as string)
    : taskRepo.listFor(agent_id as string, "pending");
  res.json({ tasks, count: tasks.length });
});

// GET /api/messages?agent_id=workbuddy&status=unread
app.get("/api/messages", authMiddleware, (req: Request, res: Response) => {
  const { agent_id, status } = req.query;
  if (!agent_id) {
    res.status(400).json({ error: "agent_id is required" });
    return;
  }
  const validStatuses = ["unread", "delivered", "read", "acknowledged"];
  if (status && !validStatuses.includes(status as string)) {
    res.status(400).json({ error: `Invalid status: ${status}. Valid: ${validStatuses.join(", ")}` });
    return;
  }
  const queryStatus = (status as string) || "unread";
  const messages = messageRepo.listByStatus(agent_id as string, queryStatus);
  res.json({ messages, count: messages.length });
});

// PATCH /api/tasks/:id/status
app.patch("/api/tasks/:id/status", authMiddleware, (req: Request, res: Response) => {
  const { status, result, progress } = req.body;
  if (!["in_progress", "completed", "failed"].includes(status)) {
    res.status(400).json({ error: `Invalid status: ${status}` });
    return;
  }
  const task = taskRepo.getById(req.params.id);
  if (!task) {
    res.status(404).json({ error: "Task not found" });
    return;
  }
  taskRepo.update(req.params.id, status, result || null, progress || 0);

  pushToAgent(task.assigned_by, {
    event: "task_updated",
    update: {
      task_id: task.id,
      status,
      result: result || null,
      progress: progress || 0,
      updated_by: "workbuddy-automation",
      timestamp: Date.now(),
    },
  });

  res.json({ success: true, task_id: task.id, status });
});

// PATCH /api/messages/:id/status
app.patch("/api/messages/:id/status", authMiddleware, (req: Request, res: Response) => {
  const { status } = req.body;
  const validStatuses = ["read", "delivered", "acknowledged"];
  if (!validStatuses.includes(status)) {
    res.status(400).json({ error: `Invalid status: ${status}. Valid: ${validStatuses.join(", ")}` });
    return;
  }
  try {
    messageRepo.updateStatus(req.params.id, status);
    res.json({ success: true, message_id: req.params.id, status });
  } catch (err: unknown) {
    res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
  }
});

// GET /api/consumed?agent_id=hermes&resource=feedback/xxx.json
app.get("/api/consumed", authMiddleware, (req: Request, res: Response) => {
  const { agent_id, resource } = req.query;
  if (!agent_id) {
    res.status(400).json({ error: "agent_id is required" });
    return;
  }
  if (resource) {
    const record = consumedRepo.check(agent_id as string, resource as string);
    res.json({
      consumed: !!record,
      resource,
      record: record || null,
    });
  } else {
    const records = consumedRepo.listByAgent(agent_id as string, 50);
    res.json({ records, count: records.length });
  }
});

// ═══════════════════════════════════════════════════════════════
// MCP 端点:Stateless 模式
// ═══════════════════════════════════════════════════════════════

function createMcpServer(authContext: AuthContext | undefined): McpServer {
  const server = new McpServer({
    name: "agent-comm-hub",
    version: "2.4.0",
  });
  registerTools(server, authContext);
  return server;
}

function extractToolName(req: express.Request): string | null {
  try {
    const body = req.body;
    if (body?.method === "tools/call" && body?.params?.name) {
      return body.params.name as string;
    }
  } catch {}
  return null;
}

// POST /mcp
app.post("/mcp", optionalAuthMiddleware, async (req: Request, res: Response) => {
  const authContext: AuthContext | undefined = req.auth?.agent
    ? { agentId: req.auth.agent.agentId, role: req.auth.agent.role }
    : undefined;

  if (authContext) {
    if (!rateLimiter(authContext.agentId)) {
      res.status(429).json({
        jsonrpc: "2.0",
        error: { code: -32001, message: "Rate limit exceeded (10 req/s)" },
        id: null,
      });
      return;
    }
  }

  const server = createMcpServer(authContext);
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });

  try {
    await server.connect(transport);
    await transport.handleRequest(req as any, res as any, req.body);
    res.on("close", () => {
      transport.close();
      server.close();
    });
  } catch (error) {
    logError("[MCP] handleRequest error", error, { module: "mcp", traceId: (req as any).traceId });
    if (!res.headersSent) {
      res.status(500).json({
        jsonrpc: "2.0",
        error: { code: -32603, message: "Internal server error" },
        id: null,
      });
    }
  }
});

// GET /mcp
app.get("/mcp", optionalAuthMiddleware, async (req: Request, res: Response) => {
  const authContext: AuthContext | undefined = req.auth?.agent
    ? { agentId: req.auth.agent.agentId, role: req.auth.agent.role }
    : undefined;

  const server = createMcpServer(authContext);
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });

  try {
    await server.connect(transport);
    await transport.handleRequest(req as any, res as any, undefined);
    res.on("close", () => {
      transport.close();
      server.close();
    });
  } catch (error) {
    logError("[MCP] GET /mcp error", error, { module: "mcp", traceId: (req as any).traceId });
    if (!res.headersSent) {
      res.status(500).end();
    }
  }
});

// DELETE /mcp
app.delete("/mcp", optionalAuthMiddleware, async (req: Request, res: Response) => {
  const authContext: AuthContext | undefined = req.auth?.agent
    ? { agentId: req.auth.agent.agentId, role: req.auth.agent.role }
    : undefined;

  const server = createMcpServer(authContext);
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });

  try {
    await server.connect(transport);
    await transport.handleRequest(req as any, res as any, req.body);
    res.on("close", () => {
      transport.close();
      server.close();
    });
  } catch (error) {
    logError("[MCP] DELETE /mcp error", error, { module: "mcp", traceId: (req as any).traceId });
    if (!res.headersSent) {
      res.status(500).end();
    }
  }
});

// ═══════════════════════════════════════════════════════════════
// Phase 5b: 404 处理(在 error handler 之前)
// ═══════════════════════════════════════════════════════════════
app.use((req: Request, res: Response) => {
  const traceId = (req as any).traceId;
  res.status(404).json({
    error: true,
    message: "Not Found",
    traceId,
  });
});

// ═══════════════════════════════════════════════════════════════
// Phase 5b: 全局错误处理中间件(放在所有路由之后)
// ═══════════════════════════════════════════════════════════════
app.use((err: Error & { status?: number }, req: Request, res: Response, _next: NextFunction) => {
  const traceId = (req as unknown as Record<string, unknown>).traceId as string | undefined;
  logError("unhandled_error", err, { traceId, path: req.path, method: req.method });

  if (res.headersSent) return;

  res.status(err.status || 500).json({
    error: true,
    message: process.env.NODE_ENV === "development" ? err.message : "Internal Server Error",
    traceId,
  });
});

// ═══════════════════════════════════════════════════════════════
// Phase 5b: 优雅关闭
// ═══════════════════════════════════════════════════════════════

let httpServer: ReturnType<typeof app.listen> | null = null;

async function gracefulShutdown(signal: string): Promise<void> {
  logger.info("shutdown_initiated", { signal, module: "server" });

  // 1. 停止接受新连接
  if (httpServer) {
    httpServer.close(() => {
      logger.info("http_server_closed", { module: "server" });
    });
  }

  // 2. drain SSE 连接
  drainAllClients();
  logger.info("sse_drained", { module: "server" });

  // 3. 停止定时器
  stopHeartbeatMonitor();
  stopDedupCleanup();
  stopCleanup();

  // 4. 关闭数据库
  try {
    db.close();
    logger.info("database_closed", { module: "server" });
  } catch (err) {
    logError("database_close_error", err, { module: "server" });
  }

  logger.info("shutdown_complete", { module: "server" });
  process.exit(0);
}

// ═══════════════════════════════════════════════════════════════
// 未捕获异常兜底
// ═══════════════════════════════════════════════════════════════
process.on("uncaughtException", (err: Error) => {
  logError("uncaught_exception", err, { module: "process" });
  process.exit(1);
});

process.on("unhandledRejection", (reason: unknown) => {
  logError("unhandled_rejection", reason, { module: "process" });
});

// ═══════════════════════════════════════════════════════════════
// 启动
// ═══════════════════════════════════════════════════════════════
httpServer = app.listen(config.port, () => {
  logger.info("server_started", {
    module: "server",
    version: "2.4.0",
    port: config.port,
    phase: "5b",
  });

  // 启动心跳超时监控
  startHeartbeatMonitor((agentId) => {
    logger.info("agent_offline_timeout", { module: "monitor", agent_id: agentId });
  });

  // 启动去重缓存 TTL 清理(15min)
  startDedupCleanup();

  // Phase 6: 启动定时清理(过期 Token / Dedup / Consumed)
  scheduleCleanup(config.dedupTTL);

  // 重建 FTS 索引
  rebuildFtsIndex();
});

// 优雅关闭信号监听
process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
process.on("SIGINT", () => gracefulShutdown("SIGINT"));
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall