agent-comm-hub 0.3.0 → 0.5.0

package/README.md

@@ -84,6 +84,7 @@ Task Scheduler on Windows) — or the built-in one-shot auto-start:
 ```bash
 agent-comm-hub service install    # Windows: HKCU Run + hidden launcher (no admin)
                                   # Linux:   systemd --user unit, enabled
+                                  # macOS:   launchd LaunchAgent
 agent-comm-hub service uninstall  # undo
 agent-comm-hub status             # is the hub up? who is online?
 ```
@@ -98,13 +99,19 @@ itself).
 agent-comm-hub setup
 # or: agents/install-all.ps1 (PowerShell equivalent)
 # undo: agent-comm-hub setup --remove
+# list what is installed (no changes): agent-comm-hub discover
+# configure a single agent:           agent-comm-hub setup --agent codex
 ```
 
-`setup` incrementally merges the `agent-hub` MCP entry into every installed
-agent's own config (mcode, opencode, Kimi Code, Gemini CLI, Codex, zcode, DSH)
-and installs the English skill into `~/.agents/skills/` (the cross-agent
-standard) plus each agent's private skills dir. Only the `agent-hub` key is
-touched, every file is backed up first, and re-running is a no-op. Claude Code
+`setup` **discovers** which agents are installed on this machine (PATH
+commands, config paths, npm global packages — no shell, cross-platform) and
+merges the `agent-hub` MCP entry into each one's config (mcode, opencode, Kimi
+Code, Gemini CLI, Codex, zcode, DSH, claude-desktop on macOS), plus the English
+skill into `~/.agents/skills/` (the cross-agent standard) and each agent's
+private skills dir. Which agents are supported is declared in
+[`agents/registry.json`](agents/registry.json) — adding a new agent is one
+registry record, no code change. Only the `agent-hub` key is touched, every
+file is backed up first, and re-running is a no-op. Claude Code's MCP config
 stays manual (see below).
 
 **Registration is automatic**: once an agent session starts, the MCP handshake
@@ -302,7 +309,7 @@ agent-comm-hub service install|uninstall [options]   one-shot auto-start
 --port <n>               Listen port (default 18764)
 --path <p>               MCP endpoint path (default /mcp)
 --max-queue <n>          Queued messages per peer before dropping oldest (default 200)
---history-limit <n>      Retained history messages (default 100)
+--history-limit <n>      Retained history messages (default 1000)
 --wait-timeout-ms <n>    Long-poll ceiling for bridge_wait (default 60000)
 --default-wait-ms <n>    bridge_wait default budget (default 30000)
 --connected-window-ms <n>  Peer counts as active within this window (default 30000)
@@ -390,6 +397,36 @@ pnpm run build        # esbuild → lib/{cli,index,setup}.js (zero deps)
 pnpm pack             # build + npm pack (publishing artifact)
 ```
 
+## Desktop GUI
+
+A companion desktop GUI is shipped as a separate npm package: **`agent-comm-hub-app`**. It is a standalone Tauri 2 + React app, lives in `app/`, and depends on the MCP HTTP API rather than on this package's source. It does NOT relax the `dependencies: {}` constraint of the main package — workspace isolation is enforced via `app/pnpm-workspace.yaml`.
+
+| English | 简体中文 |
+|---|---|
+| ![agent-comm-hub-app (EN)](assets/ach-en.png) | ![agent-comm-hub-app (CN)](assets/ach-cn.png) |
+
+```bash
+cd app
+pnpm install
+pnpm tauri:dev        # dev with hot reload
+pnpm tauri:build      # produces NSIS / MSI / dmg / AppImage / deb installers
+```
+
+Highlights:
+
+- **Hub lifecycle in one window**: auto-spawn on launch (4-tier PATH fallback), start / stop / restart, live log panel with stderr filter + expandable viewer, and an external-hub reuse mode with health probing
+- **Real-time messaging**: `bridge_wait` long-poll keeps the UI live; optimistic send shows your messages instantly; `/history` merges hub memory with the SQLite archive (survives hub restarts)
+- **Peer conversations** (PRD US-2): click any peer to view its full conversation, not just yours; unread badges per peer
+- **Message details**: raw JSON view, task prompt/context/deliverable, ack state-machine timeline
+- **Slash commands**: `/peers /broadcast /history /clear /help` — from the palette or typed directly
+- **Markdown rendering** with rehype-sanitize, multi-peer cc, drag-drop attachments (≤5 MB), virtual scrolling
+- **Theme system**: dark / light / system-follow, brand-blue palette, persisted
+- **Frameless window**: custom titlebar (drag region, double-click maximize), close dialog with minimize-to-tray / quit / cancel
+- **Hub tools in Settings**: install / version / check update / update the hub CLI, one-click `setup` to detect local agents and install the SKILL + MCP config, auto-start service install
+- **System tray** with brand logo and status tooltip; i18n (zh-CN default, en-US)
+
+See `app/README.md` for the full feature list and architecture.
+
 Tests cover registration, duplicate rejection, chat routing, sender-filtered waits, task+ack routing back to the sender, broadcast, status/peers/history, unregister/re-register, and error paths.
 
 ## Troubleshooting

package/README.zh.md

@@ -82,6 +82,7 @@ agent-comm-hub
 ```bash
 agent-comm-hub service install    # Windows：HKCU Run + 隐藏启动器（无需管理员）
                                   # Linux：systemd --user 单元并启用
+                                  # macOS：launchd LaunchAgent
 agent-comm-hub service uninstall  # 撤销
 agent-comm-hub status             # hub 是否在跑？谁在线？
 ```
@@ -94,12 +95,18 @@ agent-comm-hub status             # hub 是否在跑？谁在线？
 agent-comm-hub setup
 # 或 PowerShell 版：agents/install-all.ps1
 # 卸载：agent-comm-hub setup --remove
+# 查看本机装了什么（只读）：agent-comm-hub discover
+# 只配置某一个：agent-comm-hub setup --agent codex
 ```
 
-`setup` 会把 `agent-hub` 的 MCP 条目**增量合并**进每个已安装 agent 的配置
-（mcode / opencode / kimi-code / gemini / codex / zcode），并把英文 SKILL 装到
-`~/.agents/skills/`（跨 agent 标准位置）+ 各 agent 私有技能目录。只动
-`agent-hub` 这一个键、每个文件先备份、幂等可重跑。Claude Code 与 DSH 手动（见下）。
+`setup` 会**自动发现**本机安装了哪些 agent（PATH 命令 / 配置文件路径 /
+npm 全局包，纯 Node 无 shell、跨平台），并把 `agent-hub` 的 MCP 条目
+**增量合并**进每个已安装 agent 的配置（mcode / opencode / kimi-code /
+gemini / codex / zcode / DSH，macOS 上还有 claude-desktop），英文 SKILL 装到
+`~/.agents/skills/`（跨 agent 标准位置）+ 各 agent 私有技能目录。支持哪些
+agent 由 [`agents/registry.json`](agents/registry.json) 声明——新增 agent
+只需加一条注册表记录，不改代码。只动 `agent-hub` 这一个键、每个文件先备份、
+幂等可重跑。Claude Code 的 MCP 配置手动（见下）。
 
 **注册全自动**：agent 会话一启动，MCP 握手即完成注册（客户端名 = peer id），无需任何手动操作。可选：`bridge_register("工具名:项目名")` 换可读 id。
 
@@ -213,7 +220,7 @@ agent-comm-hub service install|uninstall [options]   一键自启
 --port <n>                端口（默认 18764）
 --path <p>                MCP 路径（默认 /mcp）
 --max-queue <n>           每 peer 队列上限，溢出丢最旧（默认 200）
---history-limit <n>       保留的历史条数（默认 100）
+--history-limit <n>       保留的历史条数（默认 1000）
 --wait-timeout-ms <n>     bridge_wait 长轮询上限（默认 60000）
 --default-wait-ms <n>     bridge_wait 默认预算（默认 30000）
 --connected-window-ms <n> 活跃窗口（默认 30000）
@@ -266,6 +273,36 @@ pnpm run build        # esbuild → lib/{cli,index,setup}.js（零依赖）
 pnpm pack             # 构建 + npm pack（发布产物）
 ```
 
+## 桌面端 GUI
+
+配套桌面端是另一个独立 npm 包 **`agent-comm-hub-app`**,在 `app/` 目录,Tauri 2 + React。它只走 hub 的 MCP / HTTP API,不引入主仓源码,也不会动 `dependencies: {}` 这个零依赖约束 —— 通过 `app/pnpm-workspace.yaml` 做工作区隔离。
+
+| 简体中文 | English |
+|---|---|
+| ![agent-comm-hub-app (CN)](assets/ach-cn.png) | ![agent-comm-hub-app (EN)](assets/ach-en.png) |
+
+```bash
+cd app
+pnpm install
+pnpm tauri:dev        # 开发模式 (HMR)
+pnpm tauri:build      # 三平台安装包 (NSIS / MSI / dmg / AppImage / deb)
+```
+
+主要能力:
+
+- **一站式 Hub 生命周期**:启动自动拉起 hub (4-tier PATH 兜底)、启停/重启、实时日志面板 (stderr 过滤 + 放大查看),外部 hub 复用模式带健康探测
+- **实时消息**:`bridge_wait` 长轮询保持界面实时;发送即乐观显示;`/history` 合并 hub 内存与 SQLite 存档 (重启不丢)
+- **会话视角** (PRD US-2):点击任意 peer 查看它的完整会话;per-peer 未读徽章
+- **消息详情**:原始 JSON、task prompt/context/deliverable、ack 状态机时间线
+- **斜杠命令**:`/peers /broadcast /history /clear /help` —— 面板选择或直接输入
+- **Markdown 渲染** + rehype-sanitize、多会话方 cc、拖拽附件 (≤5 MB)、虚拟滚动
+- **主题系统**:深色 / 浅色 / 跟随系统,品牌蓝主题,持久化
+- **无边框窗口**:自绘标题栏 (拖拽区、双击最大化),关闭弹窗三选一 (最小化到托盘 / 退出 / 取消)
+- **设置页 Hub 工具**:安装 / 版本 / 检查更新 / 更新 hub CLI,一键 `setup` 检测本地 agent 并安装 SKILL + MCP 配置,开机自启服务
+- **系统托盘** (品牌 logo + 状态 tooltip);i18n (简中默认 + 英文)
+
+详见 `app/README.zh.md`。
+
 ## 故障排查
 
 | 症状 | 原因 / 解决 |

package/agents/SKILL.md

@@ -34,7 +34,9 @@ Optional: call `bridge_register(peerId)` to claim a readable id
   30 s; loop it to hold a real-time conversation).
 - `bridge_poll(from?)` — non-blocking drain of every queued message.
 - `bridge_status()` / `bridge_peers()` — hub health and who is online.
-- `bridge_history(peer?, limit?)` — recent messages (newest first).
+- `bridge_history(peer?, limit?)` — recent messages (newest first). `peer`
+  defaults to you; pass another peer's id to read their conversation, or
+  `"all"` for the unfiltered tail across every peer.
 
 ## When to use
 

package/agents/registry.json

@@ -0,0 +1,201 @@
+{
+  "$schema": "docs/agent-registry.schema.json",
+  "agents": [
+    {
+      "id": "mcode",
+      "probe": [],
+      "configs": [
+        {
+          "file": "~/.minimax/mcp.json",
+          "section": "mcpServers",
+          "strategy": "json",
+          "entry": {
+            "url": "{url}",
+            "type": "streamable-http",
+            "enabled": true,
+            "configured": true,
+            "timeout": 120000,
+            "description": "agent-comm-hub: talk to every other agent connected to the hub."
+          }
+        },
+        {
+          "file": "~/.minimax/mcp/mcp.json",
+          "section": "mcpServers",
+          "strategy": "json",
+          "entry": {
+            "url": "{url}",
+            "type": "streamable-http",
+            "enabled": true,
+            "configured": true,
+            "timeout": 120000,
+            "description": "agent-comm-hub: talk to every other agent connected to the hub."
+          }
+        }
+      ],
+      "skill": "~/.minimax/skills",
+      "os": ["win32", "darwin", "linux"]
+    },
+    {
+      "id": "opencode",
+      "probe": ["opencode"],
+      "npm": ["cli"],
+      "configs": [
+        {
+          "file": "~/.config/opencode/opencode.json",
+          "section": "mcp",
+          "strategy": "json",
+          "entry": { "type": "remote", "url": "{url}", "enabled": true }
+        }
+      ],
+      "skill": "~/.config/opencode/skills",
+      "os": ["win32", "darwin", "linux"]
+    },
+    {
+      "id": "kimi-code",
+      "probe": ["kimi"],
+      "configs": [
+        {
+          "file": "~/.kimi-code/mcp.json",
+          "section": "mcpServers",
+          "strategy": "json",
+          "entry": { "transport": "http", "url": "{url}", "startupTimeoutMs": 30000, "toolTimeoutMs": 120000 }
+        }
+      ],
+      "skill": "~/.kimi-code/skills",
+      "os": ["win32", "darwin", "linux"]
+    },
+    {
+      "id": "gemini-cli",
+      "probe": ["gemini"],
+      "configs": [
+        {
+          "file": "~/.gemini/settings.json",
+          "section": "mcpServers",
+          "strategy": "json",
+          "entry": { "type": "http", "url": "{url}" }
+        }
+      ],
+      "skill": "~/.gemini/skills",
+      "os": ["win32", "darwin", "linux"]
+    },
+    {
+      "id": "codex",
+      "probe": ["codex"],
+      "npm": ["codex"],
+      "configs": [
+        {
+          "file": "~/.codex/config.toml",
+          "section": null,
+          "strategy": "toml",
+          "entry": null
+        }
+      ],
+      "skill": "~/.codex/skills",
+      "os": ["win32", "darwin", "linux"]
+    },
+    {
+      "id": "zcode",
+      "probe": [],
+      "configs": [
+        {
+          "file": "~/.zcode/cli/config.json",
+          "section": "mcp.servers",
+          "strategy": "json",
+          "entry": { "type": "remote", "url": "{url}", "enabled": true }
+        }
+      ],
+      "skill": "~/.zcode/skills",
+      "os": ["win32", "darwin", "linux"]
+    },
+    {
+      "id": "dsh",
+      "probe": [],
+      "configs": [
+        {
+          "file": "~/.dsh/profiles/*/cordis.patch.yml",
+          "section": null,
+          "strategy": "dsh",
+          "entry": null
+        }
+      ],
+      "skill": "~/.dsh/skills",
+      "os": ["win32", "darwin", "linux"]
+    },
+    {
+      "id": "claude",
+      "probe": ["claude"],
+      "npm": ["claude-code"],
+      "configs": [],
+      "skill": "~/.claude/skills",
+      "os": ["win32", "darwin", "linux"]
+    },
+    {
+      "id": "qwen-code",
+      "probe": ["qwen"],
+      "npm": ["qwen-code"],
+      "configs": [
+        {
+          "file": "~/.qwen/settings.json",
+          "section": "mcpServers",
+          "strategy": "json",
+          "entry": { "httpUrl": "{url}" }
+        }
+      ],
+      "skill": null,
+      "os": ["win32", "darwin", "linux"]
+    },
+    {
+      "id": "pi",
+      "probe": ["pi"],
+      "npm": ["pi-coding-agent"],
+      "configs": [],
+      "skill": null,
+      "os": ["win32", "darwin", "linux"]
+    },
+    {
+      "id": "cursor",
+      "probe": ["cursor", "cursor-agent"],
+      "npm": ["cursor"],
+      "configs": [
+        {
+          "file": "~/.cursor/mcp.json",
+          "section": "mcpServers",
+          "strategy": "json",
+          "entry": { "url": "{url}" }
+        }
+      ],
+      "skill": null,
+      "os": ["win32", "darwin", "linux"]
+    },
+    {
+      "id": "qoder",
+      "probe": ["qoder"],
+      "npm": ["qoder"],
+      "configs": [],
+      "skill": null,
+      "os": ["win32", "darwin", "linux"]
+    },
+    {
+      "id": "codebuddy",
+      "probe": ["codebuddy"],
+      "npm": ["codebuddy"],
+      "configs": [],
+      "skill": null,
+      "os": ["win32", "darwin", "linux"]
+    },
+    {
+      "id": "claude-desktop",
+      "probe": [],
+      "configs": [
+        {
+          "file": "~/Library/Application Support/Claude/claude_desktop_config.json",
+          "section": "mcpServers",
+          "strategy": "json",
+          "entry": { "url": "{url}", "type": "streamable-http" }
+        }
+      ],
+      "skill": null,
+      "os": ["darwin"]
+    }
+  ]
+}