@sleep2agi/commhub-server 0.5.0 → 0.5.2-preview.0

package/README.md

@@ -1,161 +1,157 @@
 # @sleep2agi/commhub-server
 
-AI Agent 通信中枢 — MCP Server + SSE Push + REST API。
+CommHub: MCP Streamable HTTP + SSE push + REST API for an AI agent network. Single-process Bun server, SQLite-backed, zero config.
 
-## 快速启动
+**v0.5.0 stable.** The supported path is to install the `anet` CLI (`@sleep2agi/agent-network` 2.0.0) and run `anet hub start`, which wires up port, default account, and config for you.
+
+## Quick start (verified)
 
 ```bash
-# 需要 Bun
+# Recommended — through the anet CLI
+npm install -g @sleep2agi/agent-network
+anet hub start
+#   • http://127.0.0.1:9200 (also bound to LAN)
+#   • SQLite at ~/.commhub/commhub.db
+#   • Default admin account auto-created: admin / anethub
+#   • Reset hint printed in the launch banner
+
+# Or directly via bunx (Bun required)
 bunx @sleep2agi/commhub-server
 
-# 或指定端口 + auth
+# With custom port / auth token
 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 工具 (18 个)
-
-### 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 (33 端点)
-
-| 端点 | 方法 | 说明 |
-|------|------|------|
-| `/health` | GET | 健康检查 (无需 auth) |
-| `/mcp` | POST | MCP Streamable HTTP |
-| **认证** | | |
-| `/api/auth/register` | POST | 注册 → utok_ + ntok_ |
-| `/api/auth/login` | POST | 登录 → utok_ |
-| `/api/auth/me` | GET | 当前用户信息 |
-| `/api/auth/me` | PUT | 修改资料 |
-| `/api/auth/password` | POST | 修改密码 |
-| `/api/auth/tokens` | GET | Token 列表 |
-| `/api/auth/tokens` | POST | 创建 Token |
-| `/api/auth/tokens/:id` | DELETE | 撤销 Token |
-| `/api/auth/node-token` | POST | 创建节点网络 Token (ntok_) |
-| **网络** | | |
-| `/api/networks` | GET | 我的网络列表（成员网络） |
-| `/api/networks` | POST | 创建网络 |
-| `/api/networks/:id` | GET | 网络详情 + 统计 |
-| `/api/networks/:id` | PUT | 重命名网络 |
-| `/api/networks/:id` | DELETE | 删除网络 |
-| `/api/networks/:id/members` | GET | 成员列表 |
-| `/api/networks/:id/members` | POST | 添加成员 |
-| `/api/networks/:id/members/:uid` | PUT | 修改成员角色 |
-| `/api/networks/:id/members/:uid` | DELETE | 移除成员 |
-| `/api/networks/:id/invite` | POST | 生成邀请码 |
-| `/api/networks/join` | POST | 用邀请码加入 |
-| **数据** | | |
-| `/api/status` | GET | 所有 session |
-| `/api/tasks` | GET | 任务列表 |
-| `/api/nodes` | GET | 节点信息 |
-| `/api/stats` | GET | 统计汇总 |
-| `/api/messages` | GET | 消息列表 |
-| `/api/completions` | GET | 完成记录 |
-| `/api/task_events` | GET | 任务审计日志 |
-| `/api/audit-log` | GET | 操作审计日志 |
-| `/api/users` | GET | 用户列表 (admin) |
-| `/api/license` | GET | License 状态 |
-| `/api/license/activate` | POST | 激活授权码 |
-
-## 数据表 (13 表)
-
-自动创建，SQLite
-
-| 表 | 说明 |
-|---|------|
-| `sessions` | 运行时 session (21 列, 含 node_id/session_id/channels) |
-| `inbox` | 消息队列 (13 列, 含 in_reply_to/scope) |
-| `tasks` | 任务生命周期 (17 列, 完整状态机) |
-| `nodes` | 持久化节点身份 (11 列, 独立于 session) |
-| `completions` | 完成记录 (7 列) |
-| `task_events` | 审计日志 (7 列, 每次状态变化记录) |
-| `users` | 用户 (username/password_hash/role/plan) |
-| `networks` | 网络 (name/owner/visibility/max_members) |
-| `api_tokens` | API Token (utok_/ntok_/atok_ + scope + network) |
-| `audit_log` | 操作审计 (user/action/target/ip) |
-| `licenses` | License (type/expires/limits) |
-| `network_members` | 网络成员 (user ↔ network + role) |
-| `network_invites` | 邀请码 (code/role/max_uses/expires) |
-
-任务状态机:
+Once running:
+
+| Surface | URL |
+|---|---|
+| Health | `GET /health` |
+| MCP (Streamable HTTP) | `POST /mcp` |
+| SSE per-agent push | `GET /events/:alias` |
+| REST | `/api/*` |
+
+## Pairs with
+
+| Package | Version |
+|---|---|
+| [`@sleep2agi/agent-network`](https://www.npmjs.com/package/@sleep2agi/agent-network) | 2.0.0 |
+| [`@sleep2agi/agent-network-dashboard`](https://www.npmjs.com/package/@sleep2agi/agent-network-dashboard) | 0.1.0 |
+| [`@sleep2agi/agent-node`](https://www.npmjs.com/package/@sleep2agi/agent-node) | 2.1.1 |
+
+## MCP tools (18)
+
+### Agent-side
+| Tool | Description |
+|---|---|
+| `report_status` | Heartbeat + status (idle / working / blocked / error / offline) |
+| `report_completion` | Final completion payload |
+| `get_inbox` | Pull pending tasks |
+| `ack_inbox` | Acknowledge receipt |
+
+### Hub-side (used by Dashboard, Claude Code, peer agents)
+| Tool | Description |
+|---|---|
+| `send_task` | Dispatch a task (supports `ttl_seconds`) |
+| `send_message` | Send a chat message (no task lifecycle) |
+| `send_reply` | Reply to a task (`replied` / `failed` / `cancelled`, plus `in_reply_to`) |
+| `send_ack` | Acknowledge without inbox |
+| `retry_task` | Retry failed / expired / cancelled tasks |
+| `cancel_task` | Cancel a pending task |
+| `reassign_task` | Move a task to a different agent |
+| `get_task` | Fetch task details (used by peer-coordination polling) |
+| `get_all_status` | Global presence panel |
+| `get_session_status` | Per-session detail |
+| `broadcast` | Group send |
+| `list_tasks` | Task list, filterable by `network_id` |
+| `get_completions` | Completion history |
+
+## REST API
+
+The server exposes ~33 endpoints across health, auth, networks, and observability surfaces. The endpoints in use today by the verified flow are:
+
+| Method | Endpoint | Notes |
+|---|---|---|
+| GET | `/health` | No auth |
+| POST | `/mcp` | MCP entry |
+| POST | `/api/auth/register` | Bootstrap admin |
+| POST | `/api/auth/login` | Returns user token |
+| GET | `/api/auth/me` | Current user |
+| PUT | `/api/auth/me` | Edit profile |
+| POST | `/api/auth/password` | Change password |
+| GET / POST / DELETE | `/api/auth/tokens[…]` | Manage API tokens |
+| GET | `/api/status` | Sessions snapshot |
+| GET | `/api/tasks` | Task list (Dashboard) |
+| GET | `/api/messages` | Message list (Dashboard) |
+| GET | `/api/nodes` | Node directory |
+| GET | `/api/stats` | Aggregate stats |
+| GET | `/api/audit-log` | Audit trail |
+
+Network-management endpoints (`/api/networks…`) and `/api/license[…]` are present but are **not** part of the v2.0.0 verified flow — see *Not verified* below.
+
+Auth: `Authorization: Bearer <token>` header, or `?token=<token>` query.
+
+## SQLite schema (13 tables)
+
+Auto-created on first run.
+
+| Table | Purpose |
+|---|---|
+| `sessions` | Live agent sessions |
+| `inbox` | Pending messages and tasks |
+| `tasks` | Task state machine |
+| `nodes` | Persistent node identity |
+| `completions` | Final completion records |
+| `task_events` | Per-state audit |
+| `users` | Accounts |
+| `networks` | Workspaces |
+| `api_tokens` | `utok_` / `ntok_` / `atok_` tokens |
+| `audit_log` | Operation audit |
+| `licenses` | License placeholder |
+| `network_members` | Workspace membership |
+| `network_invites` | Invite codes |
+
+Task state machine:
+
 ```
 created → delivered → acked → running → replied
                                       → failed → retry → delivered
                                       → cancelled
-delivered → expired (5min patrol)
-delivered/acked/running → reassign → delivered (新agent)
+delivered → expired (5min watchdog)
+delivered/acked/running → reassign → delivered (new agent)
 ```
 
-## 数据库 (SQLite + PostgreSQL)
+## PostgreSQL (experimental)
 
-默认使用 SQLite（零配置），设置 `DATABASE_URL` 即切换到 PostgreSQL：
+Set `DATABASE_URL` to switch to PostgreSQL — the SQL layer auto-translates SQLite-isms (datetime, parameter placeholders) so application code is unchanged. Requires `bun add pg`. **Not in the v2.0.0 verified path.**
 
 ```bash
-# SQLite (默认，零配置)
-bunx @sleep2agi/commhub-server
-
-# PostgreSQL
-DATABASE_URL=postgres://user:pass@localhost:5432/commhub bunx @sleep2agi/commhub-server
+DATABASE_URL=postgres://user:pass@host:5432/commhub bunx @sleep2agi/commhub-server
 ```
 
-PostgreSQL 模式需要 `pg` 包：`bun add pg`
-
-所有 SQL 自动翻译（datetime→NOW, 参数占位符→$N 等），代码零修改。
-
-## 环境变量
+## Environment
 
-| 变量 | 默认 | 说明 |
-|------|------|------|
-| `PORT` | 9200 | 监听端口 |
-| `HOST` | 0.0.0.0 | 监听地址 |
-| `COMMHUB_AUTH_TOKEN` | (无) | Bearer token 鉴权 |
-| `COMMHUB_DB` | ~/.commhub/commhub.db | SQLite 数据库路径 |
-| `DATABASE_URL` | (无) | PostgreSQL 连接串 (设置后使用 PG) |
+| Variable | Default | Notes |
+|---|---|---|
+| `PORT` | `9200` | listen port |
+| `HOST` | `0.0.0.0` | listen address |
+| `COMMHUB_AUTH_TOKEN` | (none) | Bearer token gate (legacy) |
+| `COMMHUB_DB` | `~/.commhub/commhub.db` | SQLite path |
+| `DATABASE_URL` | (none) | switches to PostgreSQL when set (unverified) |
 
-## 鉴权
+## Auth modes
 
-两种认证方式:
-1. **V3 用户系统** (推荐): `POST /api/auth/register` → 获取 `atok_xxx` token
-2. **全局 token** (传统): `COMMHUB_AUTH_TOKEN` 环境变量
+1. **V3 user system (default)** — `POST /api/auth/register` and `/api/auth/login` issue `utok_…` tokens; nodes get `ntok_…`.
+2. **Legacy global token** — set `COMMHUB_AUTH_TOKEN` and pass it as Bearer / query.
 
-Header: `Authorization: Bearer <token>` 或 Query: `?token=<token>`
+`/health` is always public.
 
-## V3 功能
+## Not verified
 
-- **用户系统**: 注册/登录/Token 认证
-- **多网络**: 每个用户可创建多个独立网络
-- **网络隔离**: 不同网络的数据完全隔离
-- **试用授权**: 14 天免费试用, 到期需授权码
-- **审计日志**: 所有操作记录
-- **限流**: 注册 30/min, 登录 10/min (per IP)
-- `/health` 不需要 auth
+- `/api/networks*` (multi-network create / invite / member management) — code present, not E2E regressed.
+- `/api/license*` — placeholder for a future paid tier.
+- PostgreSQL backend — translation layer exists, no E2E run.
+- Telegram / WeChat / Feishu channel endpoints — out of scope for v2.0.0 verification.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.5.0",
+  "version": "0.5.2-preview.0",
   "description": "CommHub Server \u2014 AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 18 MCP tools.",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -18,6 +18,24 @@ const SERVER_VERSION = (() => {
   } catch { return "?"; }
 })();
 
+// In-memory log ring buffer — last N lines streamed via /api/server-logs.
+// Wraps console.log/info/warn/error so EVERY existing log call lands here
+// without source changes. Dashboard tails this buffer for "hub server log
+// view" feature.
+const LOG_RING_CAP = Number(process.env.COMMHUB_LOG_RING || 500);
+type LogEntry = { ts: string; level: "log" | "info" | "warn" | "error"; line: string };
+const logRing: LogEntry[] = [];
+const _origConsole = { log: console.log.bind(console), info: console.info.bind(console), warn: console.warn.bind(console), error: console.error.bind(console) };
+function pushLog(level: LogEntry["level"], args: any[]) {
+  const line = args.map(a => typeof a === "string" ? a : (() => { try { return JSON.stringify(a); } catch { return String(a); } })()).join(" ");
+  logRing.push({ ts: new Date().toISOString(), level, line: line.slice(0, 4000) });
+  if (logRing.length > LOG_RING_CAP) logRing.splice(0, logRing.length - LOG_RING_CAP);
+}
+console.log = (...args: any[]) => { pushLog("log", args); _origConsole.log(...args); };
+console.info = (...args: any[]) => { pushLog("info", args); _origConsole.info(...args); };
+console.warn = (...args: any[]) => { pushLog("warn", args); _origConsole.warn(...args); };
+console.error = (...args: any[]) => { pushLog("error", args); _origConsole.error(...args); };
+
 // ── Rate limiter (in-memory, per IP) ──
 const rateLimits = new Map<string, { count: number; resetAt: number }>();
 function checkRateLimit(ip: string, maxPerMinute = 60): boolean {
@@ -838,6 +856,23 @@ Bun.serve({
       }));
     }
 
+    // ── REST: server log tail (in-memory ring buffer, last LOG_RING_CAP lines) ──
+    // Admin-only because logs may include user names + task content.
+    if (url.pathname === "/api/server-logs") {
+      const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");
+      if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
+      const resolved = resolveToken(token);
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (resolved.user.role !== "admin") return withCors(req, Response.json({ ok: false, error: "admin only" }, { status: 403 }));
+      const limit = Math.min(Number(url.searchParams.get("limit")) || 200, LOG_RING_CAP);
+      const since = url.searchParams.get("since"); // ISO timestamp; only return logs newer
+      let entries = logRing.slice(-limit);
+      if (since) entries = entries.filter(e => e.ts > since);
+      // Newest first
+      entries = entries.slice().reverse();
+      return withCors(req, Response.json({ ok: true, logs: entries, capacity: LOG_RING_CAP }));
+    }
+
     // ── REST: audit log (V3) ──
     if (url.pathname === "/api/audit-log") {
       const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");