@sleep2agi/commhub-server 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +127 -131
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,161 +1,157 @@
1
1
  # @sleep2agi/commhub-server
2
2
 
3
- AI Agent 通信中枢 — MCP Server + SSE Push + REST API。
3
+ CommHub: MCP Streamable HTTP + SSE push + REST API for an AI agent network. Single-process Bun server, SQLite-backed, zero config.
4
4
 
5
- ## 快速启动
5
+ **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.
6
+
7
+ ## Quick start (verified)
6
8
 
7
9
  ```bash
8
- # 需要 Bun
10
+ # Recommended — through the anet CLI
11
+ npm install -g @sleep2agi/agent-network
12
+ anet hub start
13
+ # • http://127.0.0.1:9200 (also bound to LAN)
14
+ # • SQLite at ~/.commhub/commhub.db
15
+ # • Default admin account auto-created: admin / anethub
16
+ # • Reset hint printed in the launch banner
17
+
18
+ # Or directly via bunx (Bun required)
9
19
  bunx @sleep2agi/commhub-server
10
20
 
11
- # 或指定端口 + auth
21
+ # With custom port / auth token
12
22
  PORT=9200 COMMHUB_AUTH_TOKEN=your-secret bunx @sleep2agi/commhub-server
13
23
  ```
14
24
 
15
- 启动后:
16
- - MCP: `http://0.0.0.0:9200/mcp` (Claude Code / Codex 连接)
17
- - SSE: `http://0.0.0.0:9200/events/:alias` (Agent 实时推送)
18
- - REST: `http://0.0.0.0:9200/api/*` (Dashboard / 监控)
19
- - Health: `http://0.0.0.0:9200/health`
20
-
21
- ## MCP 工具 (18 个)
22
-
23
- ### Agent 端 (从 Agent 调用)
24
- | 工具 | 说明 |
25
- |------|------|
26
- | `report_status` | 心跳 + 状态更新 (idle/working/blocked/error/offline) |
27
- | `report_completion` | 任务完成汇报 |
28
- | `get_inbox` | 拉取待办任务 |
29
- | `ack_inbox` | 确认收到任务 |
30
-
31
- ### Hub 端 (从指挥室 / Dashboard 调用)
32
- | 工具 | 说明 |
33
- |------|------|
34
- | `send_task` | 下发任务 (+ 可选 ttl_seconds) |
35
- | `send_message` | 发消息 (不触发 Agent 处理) |
36
- | `send_reply` | 回复任务 (replied/failed/cancelled + in_reply_to) |
37
- | `send_ack` | 确认任务 (不入 inbox) |
38
- | `retry_task` | 重试失败/过期/取消的任务 |
39
- | `cancel_task` | 取消待处理任务 |
40
- | `reassign_task` | 转移任务到另一个 Agent |
41
- | `get_task` | 查询任务详情 |
42
- | `get_all_status` | 全局状态面板 |
43
- | `get_session_status` | 单 session 详情 |
44
- | `broadcast` | 群发消息 |
45
-
46
- ## REST API (33 端点)
47
-
48
- | 端点 | 方法 | 说明 |
49
- |------|------|------|
50
- | `/health` | GET | 健康检查 (无需 auth) |
51
- | `/mcp` | POST | MCP Streamable HTTP |
52
- | **认证** | | |
53
- | `/api/auth/register` | POST | 注册 → utok_ + ntok_ |
54
- | `/api/auth/login` | POST | 登录 → utok_ |
55
- | `/api/auth/me` | GET | 当前用户信息 |
56
- | `/api/auth/me` | PUT | 修改资料 |
57
- | `/api/auth/password` | POST | 修改密码 |
58
- | `/api/auth/tokens` | GET | Token 列表 |
59
- | `/api/auth/tokens` | POST | 创建 Token |
60
- | `/api/auth/tokens/:id` | DELETE | 撤销 Token |
61
- | `/api/auth/node-token` | POST | 创建节点网络 Token (ntok_) |
62
- | **网络** | | |
63
- | `/api/networks` | GET | 我的网络列表（成员网络） |
64
- | `/api/networks` | POST | 创建网络 |
65
- | `/api/networks/:id` | GET | 网络详情 + 统计 |
66
- | `/api/networks/:id` | PUT | 重命名网络 |
67
- | `/api/networks/:id` | DELETE | 删除网络 |
68
- | `/api/networks/:id/members` | GET | 成员列表 |
69
- | `/api/networks/:id/members` | POST | 添加成员 |
70
- | `/api/networks/:id/members/:uid` | PUT | 修改成员角色 |
71
- | `/api/networks/:id/members/:uid` | DELETE | 移除成员 |
72
- | `/api/networks/:id/invite` | POST | 生成邀请码 |
73
- | `/api/networks/join` | POST | 用邀请码加入 |
74
- | **数据** | | |
75
- | `/api/status` | GET | 所有 session |
76
- | `/api/tasks` | GET | 任务列表 |
77
- | `/api/nodes` | GET | 节点信息 |
78
- | `/api/stats` | GET | 统计汇总 |
79
- | `/api/messages` | GET | 消息列表 |
80
- | `/api/completions` | GET | 完成记录 |
81
- | `/api/task_events` | GET | 任务审计日志 |
82
- | `/api/audit-log` | GET | 操作审计日志 |
83
- | `/api/users` | GET | 用户列表 (admin) |
84
- | `/api/license` | GET | License 状态 |
85
- | `/api/license/activate` | POST | 激活授权码 |
86
-
87
- ## 数据表 (13 表)
88
-
89
- 自动创建，SQLite
90
-
91
- | 表 | 说明 |
92
- |---|------|
93
- | `sessions` | 运行时 session (21 列, 含 node_id/session_id/channels) |
94
- | `inbox` | 消息队列 (13 列, 含 in_reply_to/scope) |
95
- | `tasks` | 任务生命周期 (17 列, 完整状态机) |
96
- | `nodes` | 持久化节点身份 (11 列, 独立于 session) |
97
- | `completions` | 完成记录 (7 列) |
98
- | `task_events` | 审计日志 (7 列, 每次状态变化记录) |
99
- | `users` | 用户 (username/password_hash/role/plan) |
100
- | `networks` | 网络 (name/owner/visibility/max_members) |
101
- | `api_tokens` | API Token (utok_/ntok_/atok_ + scope + network) |
102
- | `audit_log` | 操作审计 (user/action/target/ip) |
103
- | `licenses` | License (type/expires/limits) |
104
- | `network_members` | 网络成员 (user ↔ network + role) |
105
- | `network_invites` | 邀请码 (code/role/max_uses/expires) |
106
-
107
- 任务状态机:
25
+ Once running:
26
+
27
+ | Surface | URL |
28
+ |---|---|
29
+ | Health | `GET /health` |
30
+ | MCP (Streamable HTTP) | `POST /mcp` |
31
+ | SSE per-agent push | `GET /events/:alias` |
32
+ | REST | `/api/*` |
33
+
34
+ ## Pairs with
35
+
36
+ | Package | Version |
37
+ |---|---|
38
+ | [`@sleep2agi/agent-network`](https://www.npmjs.com/package/@sleep2agi/agent-network) | 2.0.0 |
39
+ | [`@sleep2agi/agent-network-dashboard`](https://www.npmjs.com/package/@sleep2agi/agent-network-dashboard) | 0.1.0 |
40
+ | [`@sleep2agi/agent-node`](https://www.npmjs.com/package/@sleep2agi/agent-node) | 2.1.1 |
41
+
42
+ ## MCP tools (18)
43
+
44
+ ### Agent-side
45
+ | Tool | Description |
46
+ |---|---|
47
+ | `report_status` | Heartbeat + status (idle / working / blocked / error / offline) |
48
+ | `report_completion` | Final completion payload |
49
+ | `get_inbox` | Pull pending tasks |
50
+ | `ack_inbox` | Acknowledge receipt |
51
+
52
+ ### Hub-side (used by Dashboard, Claude Code, peer agents)
53
+ | Tool | Description |
54
+ |---|---|
55
+ | `send_task` | Dispatch a task (supports `ttl_seconds`) |
56
+ | `send_message` | Send a chat message (no task lifecycle) |
57
+ | `send_reply` | Reply to a task (`replied` / `failed` / `cancelled`, plus `in_reply_to`) |
58
+ | `send_ack` | Acknowledge without inbox |
59
+ | `retry_task` | Retry failed / expired / cancelled tasks |
60
+ | `cancel_task` | Cancel a pending task |
61
+ | `reassign_task` | Move a task to a different agent |
62
+ | `get_task` | Fetch task details (used by peer-coordination polling) |
63
+ | `get_all_status` | Global presence panel |
64
+ | `get_session_status` | Per-session detail |
65
+ | `broadcast` | Group send |
66
+ | `list_tasks` | Task list, filterable by `network_id` |
67
+ | `get_completions` | Completion history |
68
+
69
+ ## REST API
70
+
71
+ The server exposes ~33 endpoints across health, auth, networks, and observability surfaces. The endpoints in use today by the verified flow are:
72
+
73
+ | Method | Endpoint | Notes |
74
+ |---|---|---|
75
+ | GET | `/health` | No auth |
76
+ | POST | `/mcp` | MCP entry |
77
+ | POST | `/api/auth/register` | Bootstrap admin |
78
+ | POST | `/api/auth/login` | Returns user token |
79
+ | GET | `/api/auth/me` | Current user |
80
+ | PUT | `/api/auth/me` | Edit profile |
81
+ | POST | `/api/auth/password` | Change password |
82
+ | GET / POST / DELETE | `/api/auth/tokens[…]` | Manage API tokens |
83
+ | GET | `/api/status` | Sessions snapshot |
84
+ | GET | `/api/tasks` | Task list (Dashboard) |
85
+ | GET | `/api/messages` | Message list (Dashboard) |
86
+ | GET | `/api/nodes` | Node directory |
87
+ | GET | `/api/stats` | Aggregate stats |
88
+ | GET | `/api/audit-log` | Audit trail |
89
+
90
+ 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.
91
+
92
+ Auth: `Authorization: Bearer <token>` header, or `?token=<token>` query.
93
+
94
+ ## SQLite schema (13 tables)
95
+
96
+ Auto-created on first run.
97
+
98
+ | Table | Purpose |
99
+ |---|---|
100
+ | `sessions` | Live agent sessions |
101
+ | `inbox` | Pending messages and tasks |
102
+ | `tasks` | Task state machine |
103
+ | `nodes` | Persistent node identity |
104
+ | `completions` | Final completion records |
105
+ | `task_events` | Per-state audit |
106
+ | `users` | Accounts |
107
+ | `networks` | Workspaces |
108
+ | `api_tokens` | `utok_` / `ntok_` / `atok_` tokens |
109
+ | `audit_log` | Operation audit |
110
+ | `licenses` | License placeholder |
111
+ | `network_members` | Workspace membership |
112
+ | `network_invites` | Invite codes |
113
+
114
+ Task state machine:
115
+
108
116
  ```
109
117
  created → delivered → acked → running → replied
110
118
  → failed → retry → delivered
111
119
  → cancelled
112
- delivered → expired (5min patrol)
113
- delivered/acked/running → reassign → delivered (新agent)
120
+ delivered → expired (5min watchdog)
121
+ delivered/acked/running → reassign → delivered (new agent)
114
122
  ```
115
123
 
116
- ## 数据库 (SQLite + PostgreSQL)
124
+ ## PostgreSQL (experimental)
117
125
 
118
- 默认使用 SQLite（零配置），设置 `DATABASE_URL` 即切换到 PostgreSQL：
126
+ 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.**
119
127
 
120
128
  ```bash
121
- # SQLite (默认，零配置)
122
- bunx @sleep2agi/commhub-server
123
-
124
- # PostgreSQL
125
- DATABASE_URL=postgres://user:pass@localhost:5432/commhub bunx @sleep2agi/commhub-server
129
+ DATABASE_URL=postgres://user:pass@host:5432/commhub bunx @sleep2agi/commhub-server
126
130
  ```
127
131
 
128
- PostgreSQL 模式需要 `pg` 包：`bun add pg`
129
-
130
- 所有 SQL 自动翻译（datetime→NOW, 参数占位符→$N 等），代码零修改。
131
-
132
- ## 环境变量
132
+ ## Environment
133
133
 
134
- | 变量 | 默认 | 说明 |
135
- |------|------|------|
136
- | `PORT` | 9200 | 监听端口 |
137
- | `HOST` | 0.0.0.0 | 监听地址 |
138
- | `COMMHUB_AUTH_TOKEN` | (无) | Bearer token 鉴权 |
139
- | `COMMHUB_DB` | ~/.commhub/commhub.db | SQLite 数据库路径 |
140
- | `DATABASE_URL` | (无) | PostgreSQL 连接串 (设置后使用 PG) |
134
+ | Variable | Default | Notes |
135
+ |---|---|---|
136
+ | `PORT` | `9200` | listen port |
137
+ | `HOST` | `0.0.0.0` | listen address |
138
+ | `COMMHUB_AUTH_TOKEN` | (none) | Bearer token gate (legacy) |
139
+ | `COMMHUB_DB` | `~/.commhub/commhub.db` | SQLite path |
140
+ | `DATABASE_URL` | (none) | switches to PostgreSQL when set (unverified) |
141
141
 
142
- ## 鉴权
142
+ ## Auth modes
143
143
 
144
- 两种认证方式:
145
- 1. **V3 用户系统** (推荐): `POST /api/auth/register` → 获取 `atok_xxx` token
146
- 2. **全局 token** (传统): `COMMHUB_AUTH_TOKEN` 环境变量
144
+ 1. **V3 user system (default)** — `POST /api/auth/register` and `/api/auth/login` issue `utok_…` tokens; nodes get `ntok_…`.
145
+ 2. **Legacy global token** — set `COMMHUB_AUTH_TOKEN` and pass it as Bearer / query.
147
146
 
148
- Header: `Authorization: Bearer <token>` 或 Query: `?token=<token>`
147
+ `/health` is always public.
149
148
 
150
- ## V3 功能
149
+ ## Not verified
151
150
 
152
- - **用户系统**: 注册/登录/Token 认证
153
- - **多网络**: 每个用户可创建多个独立网络
154
- - **网络隔离**: 不同网络的数据完全隔离
155
- - **试用授权**: 14 天免费试用, 到期需授权码
156
- - **审计日志**: 所有操作记录
157
- - **限流**: 注册 30/min, 登录 10/min (per IP)
158
- - `/health` 不需要 auth
151
+ - `/api/networks*` (multi-network create / invite / member management) — code present, not E2E regressed.
152
+ - `/api/license*` — placeholder for a future paid tier.
153
+ - PostgreSQL backend — translation layer exists, no E2E run.
154
+ - Telegram / WeChat / Feishu channel endpoints — out of scope for v2.0.0 verification.
159
155
 
160
156
  ## License
161
157
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sleep2agi/commhub-server",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "CommHub Server \u2014 AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 18 MCP tools.",
5
5
  "type": "module",
6
6
  "main": "src/index.ts",