@sleep2agi/commhub-server 0.4.2

package/bin/commhub.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry point for @sleep2agi/commhub-server
+ *
+ * Usage:
+ *   npx @sleep2agi/commhub-server
+ *   npx @sleep2agi/commhub-server --port 9200
+ *   npx @sleep2agi/commhub-server --port 9200 --token my-secret
+ *   npx @sleep2agi/commhub-server --db ~/.commhub/commhub.db
+ */
+
+const args = process.argv.slice(2);
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--port" || args[i] === "-p") process.env.PORT = args[++i];
+  if (args[i] === "--token" || args[i] === "-t") process.env.COMMHUB_AUTH_TOKEN = args[++i];
+  if (args[i] === "--db") process.env.COMMHUB_DB = args[++i];
+  if (args[i] === "--cors") process.env.COMMHUB_CORS_ORIGINS = args[++i];
+  if (args[i] === "--help" || args[i] === "-h") {
+    console.log(`
+CommHub MCP Server — AI Agent 通信中枢
+
+Usage:
+  commhub-server [options]
+
+Options:
+  --port, -p <port>       Port to listen on (default: 9200, env: PORT)
+  --token, -t <token>     Auth token (env: COMMHUB_AUTH_TOKEN)
+  --db <path>             SQLite database path (default: ~/.commhub/commhub.db, env: COMMHUB_DB)
+  --cors <origins>        CORS origins, comma-separated (env: COMMHUB_CORS_ORIGINS)
+  --help, -h              Show this help
+
+Environment Variables:
+  PORT                    Server port (default: 9200)
+  COMMHUB_AUTH_TOKEN      Bearer token for authentication
+  COMMHUB_DB              SQLite database file path
+  COMMHUB_CORS_ORIGINS    Allowed CORS origins (comma-separated)
+
+Examples:
+  commhub-server --port 9200
+  commhub-server --port 9200 --token my-secret-token
+  PORT=9200 COMMHUB_AUTH_TOKEN=secret commhub-server
+`);
+    process.exit(0);
+  }
+}
+
+// Load the server
+import("../src/index.js");

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@sleep2agi/commhub-server",
+  "version": "0.4.2",
+  "description": "CommHub MCP Server — AI Agent communication hub with SSE push, MCP protocol, and REST API",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "commhub-server": "bin/commhub.ts"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --watch run src/index.ts"
+  },
+  "keywords": [
+    "commhub",
+    "mcp",
+    "agent",
+    "ai",
+    "sse",
+    "claude",
+    "orchestration",
+    "communication",
+    "hub"
+  ],
+  "author": "sleep2agi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sleep2agi/agent-comm-hub",
+    "directory": "server"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  }
+}

package/src/db.ts

@@ -0,0 +1,64 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+
+const DB_PATH = process.env.COMMHUB_DB || `${process.env.HOME}/.commhub/commhub.db`;
+mkdirSync(dirname(DB_PATH), { recursive: true });
+
+console.log(`[commhub] database: ${DB_PATH}`);
+export const db = new Database(DB_PATH);
+db.exec("PRAGMA journal_mode=WAL");
+db.exec("PRAGMA busy_timeout=5000");
+
+// Schema
+db.exec(`
+  CREATE TABLE IF NOT EXISTS sessions (
+    resume_id     TEXT PRIMARY KEY,
+    alias         TEXT UNIQUE,
+    tmux_name     TEXT,
+    server        TEXT DEFAULT 'unknown',
+    ip            TEXT,
+    hostname      TEXT,
+    agent         TEXT,
+    project_dir   TEXT,
+    version       TEXT,
+    status        TEXT DEFAULT 'offline',
+    task          TEXT,
+    output        TEXT,
+    progress      INTEGER DEFAULT 0,
+    score         REAL,
+    registered_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at    TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS inbox (
+    id            TEXT PRIMARY KEY,
+    session_name  TEXT NOT NULL,
+    type          TEXT DEFAULT 'task',
+    priority      TEXT DEFAULT 'normal',
+    content       TEXT NOT NULL,
+    context       TEXT,
+    from_session  TEXT DEFAULT 'hub',
+    acked         INTEGER DEFAULT 0,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_inbox_pending
+    ON inbox(session_name, acked) WHERE acked = 0;
+
+  CREATE TABLE IF NOT EXISTS completions (
+    id               TEXT PRIMARY KEY,
+    session_name     TEXT NOT NULL,
+    task             TEXT NOT NULL,
+    result           TEXT NOT NULL,
+    artifacts        TEXT,
+    score            REAL,
+    duration_minutes REAL,
+    completed_at     TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+`);
+
+// Helpers
+export function uuidv4(): string {
+  return crypto.randomUUID();
+}

package/src/index.ts

@@ -0,0 +1,379 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { z } from "zod/v4";
+import { registerTools } from "./tools.js";
+import { db } from "./db.js";
+import { createSSEStream, pushEvent, pushBroadcast, getSSEStats } from "./push.js";
+
+const PORT = Number(process.env.PORT) || 9200;
+const AUTH_TOKEN = process.env.COMMHUB_AUTH_TOKEN;
+
+// ── Factory: 每个请求创建新的 McpServer（stateless 模式）──
+function createServer(clientIP?: string): McpServer {
+  const server = new McpServer({
+    name: "commhub",
+    version: "0.4.1",
+  });
+  registerTools(server, clientIP);
+  return server;
+}
+
+// ── Auth helper ─────────────────────────────────────
+function requireAuth(req: Request): Response | null {
+  if (!AUTH_TOKEN) return null; // no token = open mode (dev)
+  const header = req.headers.get("Authorization");
+  if (header === `Bearer ${AUTH_TOKEN}`) return null;
+  // Also check query param for MCP clients that can't set headers
+  const url = new URL(req.url);
+  if (url.searchParams.get("token") === AUTH_TOKEN) return null;
+  return Response.json({ error: "unauthorized" }, { status: 401 });
+}
+
+// ── REST input schema ───────────────────────────────
+const TaskSchema = z.object({
+  alias: z.string().min(1).max(200),
+  task: z.string().min(1).max(10000),
+  priority: z.enum(["high", "normal", "low"]).default("normal"),
+});
+
+const BroadcastSchema = z.object({
+  message: z.string().min(1).max(10000),
+  filter_server: z.string().max(200).optional(),
+  filter_status: z.string().max(50).optional(),
+});
+
+// ── HTTP Server (Bun native) ────────────────────────
+const CORS_ORIGINS = process.env.COMMHUB_CORS_ORIGINS
+  ? process.env.COMMHUB_CORS_ORIGINS.split(",").map((s) => s.trim())
+  : ["http://localhost:3000", "http://localhost:3001"];
+
+function corsHeaders(req: Request): Record<string, string> {
+  const origin = req.headers.get("Origin") || "";
+  const allowed = CORS_ORIGINS.includes(origin) ? origin : "";
+  return {
+    "Access-Control-Allow-Origin": allowed,
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization",
+    "Access-Control-Max-Age": "86400",
+  };
+}
+
+function withCors(req: Request, res: Response): Response {
+  const headers = corsHeaders(req);
+  for (const [k, v] of Object.entries(headers)) {
+    res.headers.set(k, v);
+  }
+  return res;
+}
+
+// ── WebSocket tmux sessions ────────────────────────
+const wsTmuxIntervals = new Map<object, ReturnType<typeof setInterval>>();
+
+
+Bun.serve({
+  port: PORT,
+  idleTimeout: 255, // max value: keep SSE connections alive (seconds)
+
+  async fetch(req, server) {
+    const url = new URL(req.url, `http://localhost:${PORT}`);
+
+    // ── CORS preflight ──
+    if (req.method === "OPTIONS") {
+      return new Response(null, { status: 204, headers: corsHeaders(req) });
+    }
+
+    // ── WebSocket: tmux terminal ──
+    const wsMatch = url.pathname.match(/^\/ws\/tmux\/([a-zA-Z0-9_-]+)$/);
+    if (wsMatch && server.upgrade(req, { data: { tmuxName: wsMatch[1] } })) {
+      return; // upgraded
+    }
+
+    // ── MCP Streamable HTTP endpoint ──
+    // MCP protocol handles its own auth — skip token check here
+    if (url.pathname === "/mcp") {
+      const fwd = req.headers.get("x-forwarded-for");
+      const clientIP = fwd ? fwd.split(",")[0].trim() : (req.headers.get("x-real-ip") ?? "unknown");
+      const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+      });
+      const server = createServer(clientIP);
+      await server.connect(transport);
+      const response = await transport.handleRequest(req);
+      // Disconnect after response to prevent McpServer leak
+      setImmediate(() => server.close().catch(() => {}));
+      return response;
+    }
+
+    // ── SSE push: Agent 实时接收任务推送 ──
+    // GET /events/知识哥 → 保持长连接，send_task 时秒推
+    const eventsMatch = url.pathname.match(/^\/events\/(.+)$/);
+    if (eventsMatch && req.method === "GET") {
+      const authErr = requireAuth(req);
+      if (authErr) return authErr;
+      const sessionName = decodeURIComponent(eventsMatch[1]);
+      return createSSEStream(sessionName);
+    }
+
+    // ── REST: health (public, no auth) ──
+    if (url.pathname === "/health") {
+      const count = db.query<{ cnt: number }, []>("SELECT COUNT(*) as cnt FROM sessions").get();
+      const sse = getSSEStats();
+      return withCors(req, Response.json({
+        ok: true,
+        version: "0.4.1",
+        transport: "streamable-http",
+        sessions: count?.cnt ?? 0,
+        sse_connections: sse.total,
+        sse_sessions: sse.sessions,
+        auth: AUTH_TOKEN ? "enabled" : "disabled",
+        uptime: process.uptime(),
+      }));
+    }
+
+    // ── All REST /api endpoints require auth (if token configured) ──
+    const authErr = requireAuth(req);
+    if (authErr) return withCors(req, authErr);
+
+    // ── REST: all sessions status ──
+    if (url.pathname === "/api/status") {
+      const cutoff = new Date(Date.now() - 10 * 60 * 1000).toISOString().replace("T", " ").slice(0, 19);
+      db.run("UPDATE sessions SET status = 'offline' WHERE updated_at < ?1 AND status != 'offline'", [cutoff]);
+      const sessions = db.query("SELECT * FROM sessions ORDER BY updated_at DESC").all();
+      return withCors(req, Response.json({ ok: true, sessions }));
+    }
+
+    // ── REST: send task ──
+    if (url.pathname === "/api/task" && req.method === "POST") {
+      let raw: unknown;
+      try {
+        raw = await req.json();
+      } catch {
+        return withCors(req, Response.json({ error: "invalid JSON" }, { status: 400 }));
+      }
+      const parsed = TaskSchema.safeParse(raw);
+      if (!parsed.success) {
+        return withCors(req, Response.json({ error: "invalid input", details: parsed.error.format() }, { status: 400 }));
+      }
+      const body = parsed.data;
+      const id = crypto.randomUUID();
+      db.run(
+        `INSERT INTO inbox (id, session_name, type, priority, content, from_session)
+         VALUES (?1, ?2, 'task', ?3, ?4, 'api')`,
+        [id, body.alias, body.priority, body.task]
+      );
+      // SSE push: 秒达
+      const pending = db.query<{ cnt: number }, [string]>(
+        "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0"
+      ).get(body.alias);
+      pushEvent(body.alias, { type: "new_task", inbox_count: pending?.cnt ?? 1, priority: body.priority });
+      return withCors(req, Response.json({ ok: true, message_id: id }));
+    }
+
+    // ── REST: broadcast ──
+    if (url.pathname === "/api/broadcast" && req.method === "POST") {
+      let raw: unknown;
+      try {
+        raw = await req.json();
+      } catch {
+        return withCors(req, Response.json({ error: "invalid JSON" }, { status: 400 }));
+      }
+      const parsed = BroadcastSchema.safeParse(raw);
+      if (!parsed.success) {
+        return withCors(req, Response.json({ error: "invalid input", details: parsed.error.format() }, { status: 400 }));
+      }
+      const body = parsed.data;
+      let sql = "SELECT alias FROM sessions WHERE alias IS NOT NULL";
+      const params: any[] = [];
+      if (body.filter_server) { sql += " AND server = ?"; params.push(body.filter_server); }
+      if (body.filter_status) { sql += " AND status = ?"; params.push(body.filter_status); }
+      const targets = db.query<{ alias: string }, any[]>(sql).all(...params);
+      const ids: string[] = [];
+      for (const t of targets) {
+        const id = crypto.randomUUID();
+        db.run(
+          `INSERT INTO inbox (id, session_name, type, priority, content, from_session)
+           VALUES (?1, ?2, 'broadcast', 'normal', ?3, 'api')`,
+          [id, t.alias, body.message]
+        );
+        ids.push(id);
+      }
+      pushBroadcast(targets.map(t => t.alias), { type: "broadcast", inbox_count: 1, message: body.message.slice(0, 200) });
+      return withCors(req, Response.json({ ok: true, recipients: targets.length, message_ids: ids }));
+    }
+
+    // ── REST: tmux capture-pane ──
+    const tmuxCapture = url.pathname.match(/^\/api\/tmux\/([a-zA-Z0-9_-]+)$/);
+    if (tmuxCapture && req.method === "GET") {
+      const name = tmuxCapture[1];
+      const lines = Number(url.searchParams.get("lines")) || 30;
+      try {
+        const proc = Bun.spawn(["tmux", "capture-pane", "-t", name, "-p"], {
+          stdout: "pipe", stderr: "pipe",
+        });
+        const text = await new Response(proc.stdout).text();
+        const err = await new Response(proc.stderr).text();
+        const code = await proc.exited;
+        if (code !== 0) {
+          return withCors(req, Response.json({ ok: false, error: err.trim() || `exit ${code}` }, { status: 400 }));
+        }
+        const trimmed = text.split("\n").slice(-lines).join("\n");
+        return withCors(req, Response.json({ ok: true, tmux_name: name, lines: lines, output: trimmed }));
+      } catch (e) {
+        return withCors(req, Response.json({ ok: false, error: (e as Error).message }, { status: 500 }));
+      }
+    }
+
+    // ── REST: tmux send-keys ──
+    const tmuxSend = url.pathname.match(/^\/api\/tmux\/([a-zA-Z0-9_-]+)\/send$/);
+    if (tmuxSend && req.method === "POST") {
+      const name = tmuxSend[1];
+      let body: { text?: string; enter?: boolean };
+      try { body = await req.json(); } catch {
+        return withCors(req, Response.json({ error: "invalid JSON" }, { status: 400 }));
+      }
+      if (!body.text || typeof body.text !== "string") {
+        return withCors(req, Response.json({ error: "text is required" }, { status: 400 }));
+      }
+      const args = ["tmux", "send-keys", "-t", name, body.text];
+      if (body.enter !== false) args.push("Enter");
+      try {
+        const proc = Bun.spawn(args, { stdout: "pipe", stderr: "pipe" });
+        const err = await new Response(proc.stderr).text();
+        const code = await proc.exited;
+        if (code !== 0) {
+          return withCors(req, Response.json({ ok: false, error: err.trim() || `exit ${code}` }, { status: 400 }));
+        }
+        return withCors(req, Response.json({ ok: true, sent: body.text }));
+      } catch (e) {
+        return withCors(req, Response.json({ ok: false, error: (e as Error).message }, { status: 500 }));
+      }
+    }
+
+    // ── REST: recent completions ──
+    if (url.pathname === "/api/completions") {
+      const since = url.searchParams.get("since") ?? new Date(Date.now() - 86400000).toISOString();
+      const rows = db.query("SELECT * FROM completions WHERE completed_at >= ?1 ORDER BY completed_at DESC LIMIT 100").all(since);
+      return withCors(req, Response.json({ ok: true, completions: rows }));
+    }
+
+    return withCors(req, new Response(
+      `CommHub MCP Server v0.4.1 (Streamable HTTP + SSE Push)
+
+Endpoints:
+  POST /mcp               - MCP Streamable HTTP (for Claude Code / Codex)
+  GET  /events/:session   - SSE realtime push (Agent subscribes here)
+  GET  /health            - Health check
+  GET  /api/status        - All sessions ${AUTH_TOKEN ? "(auth required)" : ""}
+  POST /api/task          - Send task via REST ${AUTH_TOKEN ? "(auth required)" : ""}
+  GET  /api/completions   - Recent completions ${AUTH_TOKEN ? "(auth required)" : ""}
+  GET  /api/tmux/:name    - Capture tmux pane output ${AUTH_TOKEN ? "(auth required)" : ""}
+  POST /api/tmux/:name/send - Send keys to tmux ${AUTH_TOKEN ? "(auth required)" : ""}
+
+Auth: ${AUTH_TOKEN ? "Bearer token enabled (set COMMHUB_AUTH_TOKEN)" : "disabled (set COMMHUB_AUTH_TOKEN to enable)"}
+`,
+      { status: 200, headers: { "Content-Type": "text/plain" } }
+    ));
+  },
+
+  // ── WebSocket handler for tmux terminal streaming ──
+  websocket: {
+    open(ws) {
+      const { tmuxName } = ws.data as { tmuxName: string };
+      console.log(`[ws] tmux terminal opened: ${tmuxName}`);
+      let lastOutput = "";
+
+      // Poll capture-pane every 200ms and send diffs
+      const interval = setInterval(async () => {
+        try {
+          const proc = Bun.spawn(["tmux", "capture-pane", "-t", tmuxName, "-p", "-e"], {
+            stdout: "pipe", stderr: "pipe",
+          });
+          const output = await new Response(proc.stdout).text();
+          const code = await proc.exited;
+          if (code !== 0) return;
+
+          if (output !== lastOutput) {
+            lastOutput = output;
+            ws.send(JSON.stringify({ type: "output", data: output }));
+          }
+        } catch { /* session gone */ }
+      }, 200);
+
+      wsTmuxIntervals.set(ws, interval);
+
+      // Send initial capture immediately
+      (async () => {
+        try {
+          const proc = Bun.spawn(["tmux", "capture-pane", "-t", tmuxName, "-p", "-e"], {
+            stdout: "pipe", stderr: "pipe",
+          });
+          const output = await new Response(proc.stdout).text();
+          const code = await proc.exited;
+          if (code === 0) {
+            lastOutput = output;
+            ws.send(JSON.stringify({ type: "output", data: output }));
+          } else {
+            const err = await new Response(proc.stderr).text();
+            ws.send(JSON.stringify({ type: "error", data: err.trim() || "tmux session not found" }));
+          }
+        } catch (e) {
+          ws.send(JSON.stringify({ type: "error", data: (e as Error).message }));
+        }
+      })();
+    },
+
+    async message(ws, message) {
+      const { tmuxName } = ws.data as { tmuxName: string };
+      try {
+        const msg = JSON.parse(typeof message === "string" ? message : new TextDecoder().decode(message));
+
+        if (msg.type === "input" && typeof msg.data === "string") {
+          // Send individual characters/sequences via send-keys
+          const proc = Bun.spawn(["tmux", "send-keys", "-t", tmuxName, "-l", msg.data], {
+            stdout: "pipe", stderr: "pipe",
+          });
+          await proc.exited;
+        } else if (msg.type === "key" && typeof msg.data === "string") {
+          // Send special key names (Enter, C-c, etc.)
+          const proc = Bun.spawn(["tmux", "send-keys", "-t", tmuxName, msg.data], {
+            stdout: "pipe", stderr: "pipe",
+          });
+          await proc.exited;
+        } else if (msg.type === "resize" && msg.cols && msg.rows) {
+          // Resize tmux pane
+          Bun.spawn(["tmux", "resize-window", "-t", tmuxName, "-x", String(msg.cols), "-y", String(msg.rows)], {
+            stdout: "pipe", stderr: "pipe",
+          });
+        }
+      } catch { /* ignore malformed messages */ }
+    },
+
+    close(ws) {
+      const { tmuxName } = ws.data as { tmuxName: string };
+      console.log(`[ws] tmux terminal closed: ${tmuxName}`);
+      const interval = wsTmuxIntervals.get(ws);
+      if (interval) { clearInterval(interval); wsTmuxIntervals.delete(ws); }
+    },
+  },
+});
+
+// ── Graceful shutdown ───────────────────────────────
+function shutdown() {
+  console.log("[commhub] shutting down...");
+  db.close();
+  process.exit(0);
+}
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+
+console.log(`
+╔══════════════════════════════════════════════════╗
+║   CommHub MCP Server v0.4.1                     ║
+║   Transport: Streamable HTTP (Bun native)         ║
+║   Auth: ${AUTH_TOKEN ? "ENABLED (Bearer token)" : "DISABLED (set COMMHUB_AUTH_TOKEN)"}${"".padEnd(AUTH_TOKEN ? 5 : 0)}║
+║                                                   ║
+║   MCP:    http://0.0.0.0:${PORT}/mcp                 ║
+║   REST:   http://0.0.0.0:${PORT}/api                 ║
+║   Health: http://0.0.0.0:${PORT}/health               ║
+╚══════════════════════════════════════════════════╝
+`);

package/src/push.ts

@@ -0,0 +1,109 @@
+// ── SSE Push: 实时推送事件给 Agent ──────────────────
+// Agent 连 GET /events/:session → 保持 SSE 长连接
+// send_task 写 inbox 后 → pushEvent() → 秒达
+
+type SSEClient = {
+  controller: ReadableStreamDefaultController;
+  encoder: TextEncoder;
+};
+
+// 一个 session 可能有多个 SSE 连接（重连时短暂并存）
+const clients = new Map<string, SSEClient[]>();
+
+function ts(): string {
+  return new Date().toTimeString().slice(0, 8);
+}
+
+/** 创建 SSE Response 并注册到 clients map */
+export function createSSEStream(sessionName: string): Response {
+  const encoder = new TextEncoder();
+  let ctrl: ReadableStreamDefaultController;
+
+  const stream = new ReadableStream({
+    start(controller) {
+      ctrl = controller;
+      const client: SSEClient = { controller, encoder };
+
+      if (!clients.has(sessionName)) {
+        clients.set(sessionName, []);
+      }
+      clients.get(sessionName)!.push(client);
+      console.log(`[${ts()}] SSE ← ${sessionName} connected (${clients.get(sessionName)!.length} clients)`);
+
+      // 发送初始心跳
+      controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: "connected", session: sessionName })}\n\n`));
+
+      // Periodic keepalive every 30s to prevent proxy/LB idle timeout
+      const keepalive = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(`: keepalive\n\n`));
+        } catch {
+          clearInterval(keepalive);
+        }
+      }, 30_000);
+      (client as any)._keepalive = keepalive;
+    },
+    cancel() {
+      // 断线清理
+      const arr = clients.get(sessionName);
+      if (arr) {
+        const idx = arr.findIndex(c => c.controller === ctrl);
+        if (idx !== -1) {
+          clearInterval((arr[idx] as any)._keepalive);
+          arr.splice(idx, 1);
+        }
+        if (arr.length === 0) clients.delete(sessionName);
+        console.log(`[${ts()}] SSE ✕ ${sessionName} disconnected (${arr.length} remaining)`);
+      }
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      "Connection": "keep-alive",
+    },
+  });
+}
+
+/** 推送事件给指定 session 的所有 SSE 连接 */
+export function pushEvent(sessionName: string, event: Record<string, unknown>): void {
+  const arr = clients.get(sessionName);
+  if (!arr || arr.length === 0) return;
+
+  const data = `data: ${JSON.stringify(event)}\n\n`;
+  const dead: number[] = [];
+
+  for (let i = 0; i < arr.length; i++) {
+    try {
+      arr[i].controller.enqueue(arr[i].encoder.encode(data));
+    } catch {
+      dead.push(i);
+    }
+  }
+
+  // 清理死连接
+  for (let i = dead.length - 1; i >= 0; i--) {
+    arr.splice(dead[i], 1);
+  }
+  if (arr.length === 0) clients.delete(sessionName);
+}
+
+/** 广播给多个 session */
+export function pushBroadcast(sessionNames: string[], event: Record<string, unknown>): void {
+  for (const name of sessionNames) {
+    pushEvent(name, event);
+  }
+}
+
+/** 获取当前 SSE 连接统计 */
+export function getSSEStats(): { total: number; sessions: Record<string, number> } {
+  let total = 0;
+  const sessions: Record<string, number> = {};
+  for (const [name, arr] of clients) {
+    sessions[name] = arr.length;
+    total += arr.length;
+  }
+  return { total, sessions };
+}

package/src/tools.ts

@@ -0,0 +1,378 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod/v4";
+import { db, uuidv4 } from "./db.js";
+import { pushEvent, pushBroadcast } from "./push.js";
+
+function ts(): string {
+  return new Date().toTimeString().slice(0, 8);
+}
+
+export function registerTools(server: McpServer, clientIP?: string) {
+  // ═══════════════════════════════════════════
+  //  Child Agent Tools (4)
+  // ═══════════════════════════════════════════
+
+  server.tool(
+    "report_status",
+    "Report agent status. Returns inbox_count so you know if there are pending tasks.",
+    {
+      resume_id: z.string().min(1).max(200).describe("Claude Code session UUID (unique per session)"),
+      alias: z.string().min(1).max(200).describe("Human-readable session name for dispatching (e.g. 指挥室/知识哥)"),
+      status: z.enum(["working", "idle", "blocked", "error", "waiting_input"]),
+      task: z.string().max(10000).optional().describe("Current task description"),
+      output: z.string().max(50000).optional().describe("Recent output (max 4000 chars stored)"),
+      score: z.number().min(0).max(10).optional().describe("Self-score 1-10"),
+      progress: z.number().min(0).max(100).optional().describe("Progress 0-100"),
+      server: z.string().max(200).optional().describe("Server identifier"),
+      hostname: z.string().max(200).optional().describe("Agent hostname"),
+      agent: z.string().max(100).optional().describe("Agent type (claude-code / codex / opencode)"),
+      project_dir: z.string().max(1000).optional().describe("Agent working directory"),
+      version: z.string().max(100).optional().describe("Agent version"),
+      tmux_name: z.string().max(200).optional().describe("tmux session name"),
+    },
+    async ({ resume_id, alias, status, task, output, score, progress, server: srv, hostname: hn, agent: ag, project_dir: pd, version: ver, tmux_name: tmux }) => {
+      console.log(`[${ts()}] ${alias} (${resume_id.slice(0, 8)}) → report_status: ${status}${task ? " | " + task.slice(0, 60) : ""}`);
+      const trimmedOutput = output?.slice(0, 4000);
+
+      // Wrap DELETE + UPSERT in transaction to prevent race conditions
+      db.run("BEGIN IMMEDIATE");
+      db.run("DELETE FROM sessions WHERE alias = ?1 AND resume_id != ?2", [alias, resume_id]);
+      db.run(
+        `INSERT INTO sessions (resume_id, alias, tmux_name, server, ip, hostname, agent, project_dir, version, status, task, output, progress, score, updated_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, datetime('now'))
+         ON CONFLICT(resume_id) DO UPDATE SET
+           alias = COALESCE(?2, sessions.alias),
+           tmux_name = COALESCE(?3, sessions.tmux_name),
+           server = COALESCE(?4, sessions.server),
+           ip = COALESCE(?5, sessions.ip),
+           hostname = COALESCE(?6, sessions.hostname),
+           agent = COALESCE(?7, sessions.agent),
+           project_dir = COALESCE(?8, sessions.project_dir),
+           version = COALESCE(?9, sessions.version),
+           status = ?10,
+           task = COALESCE(?11, sessions.task),
+           output = COALESCE(?12, sessions.output),
+           progress = COALESCE(?13, sessions.progress),
+           score = COALESCE(?14, sessions.score),
+           updated_at = datetime('now')`,
+        [resume_id, alias, tmux ?? null, srv ?? null, clientIP ?? null, hn ?? null, ag ?? null, pd ?? null, ver ?? null, status, task ?? null, trimmedOutput ?? null, progress ?? null, score ?? null]
+      );
+
+      db.run("COMMIT");
+
+      // inbox uses alias for routing
+      const row = db.query<{ cnt: number }, [string]>(
+        "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0"
+      ).get(alias);
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({
+              ok: true,
+              resume_id,
+              alias,
+              inbox_count: row?.cnt ?? 0,
+            }),
+          },
+        ],
+      };
+    }
+  );
+
+  server.tool(
+    "report_completion",
+    "Report task completion with results and optional artifacts.",
+    {
+      alias: z.string().min(1).max(200).describe("Session alias"),
+      task: z.string().min(1).max(10000).describe("Completed task description"),
+      result: z.string().min(1).max(50000).describe("Result summary"),
+      artifacts: z.array(z.string().max(2000)).max(50).optional().describe("Output URLs or file paths"),
+      score: z.number().min(0).max(10).optional(),
+      duration_minutes: z.number().min(0).optional(),
+    },
+    async ({ alias, task, result, artifacts, score, duration_minutes }) => {
+      console.log(`[${ts()}] ${alias} → report_completion: ${task.slice(0, 60)}`);
+      const id = uuidv4();
+      db.run(
+        `INSERT INTO completions (id, session_name, task, result, artifacts, score, duration_minutes)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)`,
+        [id, alias, task, result, artifacts ? JSON.stringify(artifacts) : null, score ?? null, duration_minutes ?? null]
+      );
+
+      db.run(
+        `UPDATE sessions SET status = 'idle', task = NULL, progress = 0, updated_at = datetime('now')
+         WHERE alias = ?1`,
+        [alias]
+      );
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ ok: true, completion_id: id }) }],
+      };
+    }
+  );
+
+  server.tool(
+    "get_inbox",
+    "Get pending commands for your session.",
+    {
+      alias: z.string().min(1).max(200).describe("Session alias"),
+      limit: z.number().min(1).max(100).optional().default(10),
+    },
+    async ({ alias, limit }) => {
+      const rows0 = db.query<{ cnt: number }, [string]>(
+        "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0"
+      ).get(alias);
+      console.log(`[${ts()}] ${alias} → get_inbox: ${rows0?.cnt ?? 0} pending messages`);
+      const rows = db.query<any, [string, number]>(
+        `SELECT id, type, priority, content, context, from_session, created_at
+         FROM inbox WHERE session_name = ?1 AND acked = 0
+         ORDER BY CASE priority WHEN 'high' THEN 0 WHEN 'normal' THEN 1 ELSE 2 END, created_at
+         LIMIT ?2`
+      ).all(alias, limit);
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ ok: true, messages: rows }) }],
+      };
+    }
+  );
+
+  server.tool(
+    "ack_inbox",
+    "Acknowledge receipt of a command.",
+    {
+      alias: z.string().min(1).max(200).describe("Session alias"),
+      message_id: z.string().min(1).max(200),
+      response: z.string().max(10000).optional(),
+    },
+    async ({ alias, message_id, response }) => {
+      console.log(`[${ts()}] ${alias} → ack_inbox: ${message_id.slice(0, 8)}`);
+      const result = db.run("UPDATE inbox SET acked = 1 WHERE id = ?1 AND session_name = ?2", [message_id, alias]);
+      if (result.changes === 0) {
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "message not found or not yours" }) }],
+        };
+      }
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ ok: true }) }],
+      };
+    }
+  );
+
+  // ═══════════════════════════════════════════
+  //  Hub Tools (5)
+  // ═══════════════════════════════════════════
+
+  server.tool(
+    "get_all_status",
+    "Get status of all sessions. Hub uses this for the patrol loop.",
+    {
+      filter_status: z.string().max(50).optional(),
+      filter_server: z.string().max(200).optional(),
+    },
+    async ({ filter_status, filter_server }) => {
+      console.log(`[${ts()}] hub → get_all_status${filter_status ? ": filter=" + filter_status : ""}${filter_server ? " server=" + filter_server : ""}`);
+
+      const sessions = db.transaction(() => {
+        const cutoff = new Date(Date.now() - 10 * 60 * 1000).toISOString().replace("T", " ").slice(0, 19);
+        db.run("UPDATE sessions SET status = 'offline' WHERE updated_at < ?1 AND status != 'offline'", [cutoff]);
+
+        let sql = "SELECT * FROM sessions WHERE 1=1";
+        const params: any[] = [];
+        if (filter_status) { sql += " AND status = ?"; params.push(filter_status); }
+        if (filter_server) { sql += " AND server = ?"; params.push(filter_server); }
+        sql += " ORDER BY updated_at DESC";
+        return db.query(sql).all(...params);
+      })();
+
+      const summary = db.query<any, []>(
+        "SELECT status, COUNT(*) as count FROM sessions GROUP BY status"
+      ).all();
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({ ok: true, sessions, summary }),
+          },
+        ],
+      };
+    }
+  );
+
+  server.tool(
+    "get_session_status",
+    "Get detailed status of a specific session by alias.",
+    { alias: z.string().min(1).max(200).describe("Session alias") },
+    async ({ alias }) => {
+      console.log(`[${ts()}] hub → get_session_status: ${alias}`);
+      const session = db.query("SELECT * FROM sessions WHERE alias = ?1").get(alias);
+      const pending = db.query<{ cnt: number }, [string]>(
+        "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0"
+      ).get(alias);
+      const recent = db.query(
+        "SELECT * FROM completions WHERE session_name = ?1 ORDER BY completed_at DESC LIMIT 5"
+      ).all(alias);
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({ ok: true, session, inbox_pending: pending?.cnt ?? 0, recent_completions: recent }),
+          },
+        ],
+      };
+    }
+  );
+
+  server.tool(
+    "send_task",
+    "Dispatch a task to a session's inbox (by alias).",
+    {
+      alias: z.string().min(1).max(200).describe("Target session alias"),
+      task: z.string().min(1).max(10000).describe("Task content"),
+      priority: z.enum(["high", "normal", "low"]).optional().default("normal"),
+      context: z.string().max(10000).optional(),
+      from_session: z.string().max(200).optional().default("hub"),
+    },
+    async ({ alias, task, priority, context, from_session }) => {
+      console.log(`[${ts()}] ${from_session} → send_task → ${alias}: ${task.slice(0, 60)}${priority === "high" ? " [HIGH]" : ""}`);
+      const id = uuidv4();
+      // inbox.session_name stores alias
+      db.run(
+        `INSERT INTO inbox (id, session_name, type, priority, content, context, from_session)
+         VALUES (?1, ?2, 'task', ?3, ?4, ?5, ?6)`,
+        [id, alias, priority, task, context ?? null, from_session]
+      );
+
+      const session = db.query<any, [string]>("SELECT status FROM sessions WHERE alias = ?1").get(alias);
+
+      // SSE push by alias
+      const pending = db.query<{ cnt: number }, [string]>(
+        "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0"
+      ).get(alias);
+      pushEvent(alias, { type: "new_task", inbox_count: pending?.cnt ?? 1, priority, from: from_session });
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({
+              ok: true,
+              message_id: id,
+              session_status: session?.status ?? "unknown",
+            }),
+          },
+        ],
+      };
+    }
+  );
+
+  server.tool(
+    "send_message",
+    "Send a message to a session (no task lifecycle, just chat). Use for replies, status updates, or casual communication.",
+    {
+      alias: z.string().min(1).max(200).describe("Target session alias"),
+      message: z.string().min(1).max(10000).describe("Message content"),
+      from_session: z.string().max(200).optional().default("hub"),
+    },
+    async ({ alias, message, from_session }) => {
+      console.log(`[${ts()}] ${from_session} → send_message → ${alias}: ${message.slice(0, 60)}`);
+      const id = uuidv4();
+      db.run(
+        `INSERT INTO inbox (id, session_name, type, priority, content, from_session)
+         VALUES (?1, ?2, 'message', 'normal', ?3, ?4)`,
+        [id, alias, message, from_session]
+      );
+
+      const session = db.query<any, [string]>("SELECT status FROM sessions WHERE alias = ?1").get(alias);
+
+      pushEvent(alias, { type: "new_message", message, from: from_session, message_id: id });
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({
+              ok: true,
+              message_id: id,
+              session_status: session?.status ?? "unknown",
+            }),
+          },
+        ],
+      };
+    }
+  );
+
+  server.tool(
+    "broadcast",
+    "Send a message to multiple sessions.",
+    {
+      message: z.string().min(1).max(10000),
+      filter_server: z.string().max(200).optional(),
+      filter_status: z.string().max(50).optional(),
+    },
+    async ({ message, filter_server, filter_status }) => {
+      console.log(`[${ts()}] hub → broadcast: ${message.slice(0, 60)}${filter_server ? " [server=" + filter_server + "]" : ""}`);
+      let sql = "SELECT alias FROM sessions WHERE alias IS NOT NULL";
+      const params: any[] = [];
+      if (filter_server) { sql += " AND server = ?"; params.push(filter_server); }
+      if (filter_status) { sql += " AND status = ?"; params.push(filter_status); }
+
+      const targets = db.query<{ alias: string }, any[]>(sql).all(...params);
+      const ids: string[] = [];
+
+      for (const t of targets) {
+        const id = uuidv4();
+        db.run(
+          `INSERT INTO inbox (id, session_name, type, priority, content, from_session)
+           VALUES (?1, ?2, 'broadcast', 'normal', ?3, 'hub')`,
+          [id, t.alias, message]
+        );
+        ids.push(id);
+      }
+
+      pushBroadcast(targets.map(t => t.alias), { type: "broadcast", inbox_count: 1, message: message.slice(0, 200) });
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({ ok: true, recipients: targets.length, message_ids: ids }),
+          },
+        ],
+      };
+    }
+  );
+
+  server.tool(
+    "get_completions",
+    "Get recent task completions.",
+    {
+      since: z.string().optional().describe("ISO 8601 datetime, default last 24h"),
+      alias: z.string().max(200).optional().describe("Filter by session alias"),
+      limit: z.number().min(1).max(500).optional().default(50),
+    },
+    async ({ since, alias, limit }) => {
+      console.log(`[${ts()}] hub → get_completions${alias ? ": " + alias : ""}`);
+      const cutoff = since ?? new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+      let sql = "SELECT * FROM completions WHERE completed_at >= ?1";
+      const params: any[] = [cutoff];
+
+      if (alias) {
+        sql += " AND session_name = ?2";
+        params.push(alias);
+      }
+
+      const paramIdx = params.length + 1;
+      sql += ` ORDER BY completed_at DESC LIMIT ?${paramIdx}`;
+      params.push(limit);
+
+      const rows = db.query(sql).all(...params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ ok: true, completions: rows }) }],
+      };
+    }
+  );
+}