@sleep2agi/commhub-server 0.5.0-preview.6 → 0.5.0-preview.8

package/README.md

@@ -0,0 +1,99 @@
+# @sleep2agi/commhub-server
+
+AI Agent 通信中枢 — MCP Server + SSE Push + REST API。
+
+## 快速启动
+
+```bash
+# 需要 Bun
+bunx @sleep2agi/commhub-server
+
+# 或指定端口 + auth
+PORT=9200 COMMHUB_AUTH_TOKEN=your-secret bunx @sleep2agi/commhub-server
+```
+
+启动后:
+- MCP: `http://0.0.0.0:9200/mcp` (Claude Code / Codex 连接)
+- SSE: `http://0.0.0.0:9200/events/:alias` (Agent 实时推送)
+- REST: `http://0.0.0.0:9200/api/*` (Dashboard / 监控)
+- Health: `http://0.0.0.0:9200/health`
+
+## MCP 工具 (17 个)
+
+### Agent 端 (从 Agent 调用)
+| 工具 | 说明 |
+|------|------|
+| `report_status` | 心跳 + 状态更新 (idle/working/blocked/error/offline) |
+| `report_completion` | 任务完成汇报 |
+| `get_inbox` | 拉取待办任务 |
+| `ack_inbox` | 确认收到任务 |
+
+### Hub 端 (从指挥室 / Dashboard 调用)
+| 工具 | 说明 |
+|------|------|
+| `send_task` | 下发任务 (+ 可选 ttl_seconds) |
+| `send_message` | 发消息 (不触发 Agent 处理) |
+| `send_reply` | 回复任务 (replied/failed/cancelled + in_reply_to) |
+| `send_ack` | 确认任务 (不入 inbox) |
+| `retry_task` | 重试失败/过期/取消的任务 |
+| `cancel_task` | 取消待处理任务 |
+| `reassign_task` | 转移任务到另一个 Agent |
+| `get_task` | 查询任务详情 |
+| `get_all_status` | 全局状态面板 |
+| `get_session_status` | 单 session 详情 |
+| `broadcast` | 群发消息 |
+
+## REST API
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/health` | GET | 健康检查 (无需 auth) |
+| `/api/status` | GET | 所有 session |
+| `/api/tasks` | GET | 任务列表 (支持 status/from_name/to_name/task_id/limit 过滤) |
+| `/api/nodes` | GET | 节点持久化信息 |
+| `/api/task_events` | GET | 任务审计日志 |
+| `/api/messages` | GET | 消息列表 |
+| `/api/completions` | GET | 完成记录 |
+| `/mcp` | POST | MCP Streamable HTTP |
+
+## 数据库 (6 表)
+
+SQLite WAL 模式, 自动创建在 `~/.commhub/commhub.db`
+
+| 表 | 说明 |
+|---|------|
+| `sessions` | 运行时 session (21 列, 含 node_id/session_id/channels) |
+| `inbox` | 消息队列 (13 列, 含 in_reply_to/scope) |
+| `tasks` | 任务生命周期 (17 列, 完整状态机) |
+| `nodes` | 持久化节点身份 (11 列, 独立于 session) |
+| `completions` | 完成记录 (7 列) |
+| `task_events` | 审计日志 (7 列, 每次状态变化记录) |
+
+任务状态机:
+```
+created → delivered → acked → running → replied
+                                      → failed → retry → delivered
+                                      → cancelled
+delivered → expired (5min patrol)
+delivered/acked/running → reassign → delivered (新agent)
+```
+
+## 环境变量
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `PORT` | 9200 | 监听端口 |
+| `HOST` | 0.0.0.0 | 监听地址 |
+| `COMMHUB_AUTH_TOKEN` | (无) | Bearer token 鉴权 |
+| `COMMHUB_DB` | ~/.commhub/commhub.db | 数据库路径 |
+
+## 鉴权
+
+设置 `COMMHUB_AUTH_TOKEN` 后, 所有端点需要 Bearer token:
+- Header: `Authorization: Bearer <token>`
+- 或 Query: `?token=<token>`
+- `/health` 不需要 auth
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.5.0-preview.6",
+  "version": "0.5.0-preview.8",
   "description": "CommHub MCP Server — AI Agent communication hub with SSE push, MCP protocol, and REST API",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -286,6 +286,24 @@ Bun.serve({
       return withCors(req, Response.json({ ok: true, messages: rows }));
     }
 
+    // ── REST: stats summary ──
+    if (url.pathname === "/api/stats") {
+      const taskStats = db.query<any, []>("SELECT status, COUNT(*) as count FROM tasks GROUP BY status").all();
+      const sessionStats = db.query<any, []>("SELECT status, COUNT(*) as count FROM sessions GROUP BY status").all();
+      const totalTasks = db.query<{ cnt: number }, []>("SELECT COUNT(*) as cnt FROM tasks").get();
+      const totalNodes = db.query<{ cnt: number }, []>("SELECT COUNT(*) as cnt FROM nodes").get();
+      const recentTasks = db.query<any, []>(
+        "SELECT task_id, from_name, to_name, status, created_at FROM tasks ORDER BY created_at DESC LIMIT 5"
+      ).all();
+      return withCors(req, Response.json({
+        ok: true,
+        tasks: { total: totalTasks?.cnt || 0, by_status: taskStats },
+        sessions: { by_status: sessionStats },
+        nodes: { total: totalNodes?.cnt || 0 },
+        recent_tasks: recentTasks,
+      }));
+    }
+
     // ── REST: task events (V2 Sprint 2) ──
     if (url.pathname === "/api/task_events") {
       const taskId = url.searchParams.get("task_id");
@@ -330,7 +348,8 @@ Bun.serve({
       params.push(limit);
 
       const rows = db.query(sql).all(...params);
-      return withCors(req, Response.json({ ok: true, tasks: rows, count: rows.length }));
+      const stats = db.query<any, []>("SELECT status, COUNT(*) as count FROM tasks GROUP BY status").all();
+      return withCors(req, Response.json({ ok: true, tasks: rows, count: rows.length, stats }));
     }
 
     // ── REST: recent completions ──

package/src/tools.ts

@@ -565,6 +565,67 @@ export function registerTools(server: McpServer, clientIP?: string) {
     }
   );
 
+  // ── V2: list_tasks (查询任务列表) ──
+  server.tool(
+    "list_tasks",
+    "List tasks with filters. Agents can query their own pending/running tasks.",
+    {
+      alias: z.string().max(200).optional().describe("Filter by to_name (target agent)"),
+      status: z.string().max(50).optional().describe("Filter by status"),
+      from_name: z.string().max(200).optional().describe("Filter by sender"),
+      limit: z.number().min(1).max(100).optional().default(20),
+    },
+    async ({ alias, status, from_name, limit }) => {
+      let sql = "SELECT task_id, from_name, to_name, priority, status, content, result, created_at, completed_at FROM tasks WHERE 1=1";
+      const params: any[] = [];
+      if (alias) { sql += ` AND to_name = ?${params.length + 1}`; params.push(alias); }
+      if (status) { sql += ` AND status = ?${params.length + 1}`; params.push(status); }
+      if (from_name) { sql += ` AND from_name = ?${params.length + 1}`; params.push(from_name); }
+      sql += ` ORDER BY created_at DESC LIMIT ?${params.length + 1}`;
+      params.push(limit);
+      const tasks = db.query(sql).all(...params);
+
+      // Stats
+      const stats = db.query<any, []>(
+        "SELECT status, COUNT(*) as count FROM tasks GROUP BY status"
+      ).all();
+
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({ ok: true, tasks, count: tasks.length, stats }),
+        }],
+      };
+    }
+  );
+
+  // ── V2: cancel_task (取消任务) ──
+  server.tool(
+    "cancel_task",
+    "Cancel a pending task. Works on delivered/acked/running tasks.",
+    {
+      task_id: z.string().min(1).max(200).describe("Task ID to cancel"),
+      reason: z.string().max(1000).optional().describe("Cancellation reason"),
+      from_session: z.string().max(200).optional().default("hub"),
+    },
+    async ({ task_id, reason, from_session }) => {
+      console.log(`[${ts()}] ${from_session} → cancel_task → ${task_id.slice(0, 8)}`);
+      const result = db.run(
+        `UPDATE tasks SET status = 'cancelled', result = ?1, completed_at = datetime('now')
+         WHERE task_id = ?2 AND status IN ('created', 'delivered', 'acked', 'running')`,
+        [reason || "cancelled by " + from_session, task_id]
+      );
+      // Also ack the inbox entry to prevent agent from picking it up
+      if (result.changes > 0) {
+        db.run("UPDATE inbox SET acked = 1 WHERE id = ?1 AND acked = 0", [task_id]);
+        logTaskEvent(task_id, null, "cancelled", from_session, reason || undefined);
+      }
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ ok: result.changes > 0, task_id, cancelled: result.changes > 0 }) }],
+      };
+    }
+  );
+
   // ── V2: reassign_task (转移任务到另一个 agent) ──
   server.tool(
     "reassign_task",
@@ -584,6 +645,8 @@ export function registerTools(server: McpServer, clientIP?: string) {
       const oldAlias = task.to_name;
       try {
         db.run("BEGIN IMMEDIATE");
+        // Ack old inbox to prevent original agent from picking it up
+        db.run("UPDATE inbox SET acked = 1 WHERE id = ?1 AND acked = 0", [task_id]);
         db.run("UPDATE tasks SET to_name = ?1, status = 'delivered', started_at = NULL, delivered_at = datetime('now') WHERE task_id = ?2", [new_alias, task_id]);
         const newInboxId = uuidv4();
         db.run("INSERT INTO inbox (id, session_name, type, priority, content, from_session, requires_response) VALUES (?1, ?2, 'task', ?3, ?4, ?5, 'reply')",