agent-comm-hub 0.8.1 → 0.9.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.
package/README.md CHANGED
@@ -139,14 +139,14 @@ is manual (below).
139
139
 
140
140
  | Agent | Config file | Template | Skill location |
141
141
  |---|---|---|---|
142
- | MiniMax Code (mcode) | `~/.minimax/mcp.json` (+ `~/.minimax/mcp/mcp.json`) | [`agents/minimax-code/`](agents/minimax-code/) | `~/.minimax/skills/agent-comm-hub/SKILL.md` |
143
- | opencode | `~/.config/opencode/opencode.json` | [`agents/opencode/opencode.json`](agents/opencode/opencode.json) | `~/.config/opencode/skills/agent-comm-hub/SKILL.md` |
144
- | Kimi Code | `~/.kimi-code/mcp.json` | [`agents/kimi-code/mcp-entry.json`](agents/kimi-code/mcp-entry.json) | `~/.kimi-code/skills/agent-comm-hub/SKILL.md` |
145
- | Gemini CLI | `~/.gemini/settings.json` | [`agents/gemini-cli/settings.json`](agents/gemini-cli/settings.json) | `~/.gemini/skills/agent-comm-hub/SKILL.md` |
146
- | Codex | `~/.codex/config.toml` | [`agents/codex/config.toml`](agents/codex/config.toml) | `~/.codex/skills/agent-comm-hub/SKILL.md` |
147
- | zcode | `~/.zcode/cli/config.json` (`mcp.servers`) | [`agents/zcode/config.json`](agents/zcode/config.json) | `~/.zcode/skills/agent-comm-hub/SKILL.md` |
148
- | Claude Code | project `.mcp.json` (manual; `~/.claude.json` is never touched) | [`agents/claude-code/.mcp.json`](agents/claude-code/.mcp.json) | `~/.claude/skills/agent-comm-hub/SKILL.md` |
149
- | DeepSeek Harness (DSH) | `~/.dsh/profiles/*/cordis.patch.yml` (auto by `setup`) | [`agents/dsh/cordis.patch.yml`](agents/dsh/cordis.patch.yml) | `$DSH_HOME/skills/agent-comm-hub/SKILL.md` |
142
+ | MiniMax Code (mcode) | `~/.minimax/mcp.json` (+ `~/.minimax/mcp/mcp.json`) | [`agents/minimax-code/`](agents/minimax-code/) | `~/.minimax/skills/agent-hub/SKILL.md` |
143
+ | opencode | `~/.config/opencode/opencode.json` | [`agents/opencode/opencode.json`](agents/opencode/opencode.json) | `~/.config/opencode/skills/agent-hub/SKILL.md` |
144
+ | Kimi Code | `~/.kimi-code/mcp.json` | [`agents/kimi-code/mcp-entry.json`](agents/kimi-code/mcp-entry.json) | `~/.kimi-code/skills/agent-hub/SKILL.md` |
145
+ | Gemini CLI | `~/.gemini/settings.json` | [`agents/gemini-cli/settings.json`](agents/gemini-cli/settings.json) | `~/.gemini/skills/agent-hub/SKILL.md` |
146
+ | Codex | `~/.codex/config.toml` | [`agents/codex/config.toml`](agents/codex/config.toml) | `~/.codex/skills/agent-hub/SKILL.md` |
147
+ | zcode | `~/.zcode/cli/config.json` (`mcp.servers`) | [`agents/zcode/config.json`](agents/zcode/config.json) | `~/.zcode/skills/agent-hub/SKILL.md` |
148
+ | Claude Code | project `.mcp.json` (manual; `~/.claude.json` is never touched) | [`agents/claude-code/.mcp.json`](agents/claude-code/.mcp.json) | `~/.claude/skills/agent-hub/SKILL.md` |
149
+ | DeepSeek Harness (DSH) | `~/.dsh/profiles/*/cordis.patch.yml` (auto by `setup`) | [`agents/dsh/cordis.patch.yml`](agents/dsh/cordis.patch.yml) | `$DSH_HOME/skills/agent-hub/SKILL.md` |
150
150
 
151
151
  > Streamable-http support varies by agent version; the templates use the fields each agent documents. If a client lacks HTTP MCP, wrap the endpoint with a stdio shim.
152
152
 
@@ -179,7 +179,7 @@ Copy `agents/claude-code/.mcp.json` into your project root (or merge `mcpServers
179
179
  }
180
180
  ```
181
181
 
182
- Copy `agents/SKILL.md` to `~/.claude/skills/agent-comm-hub/SKILL.md`, restart Claude, and have it `bridge_register("claude-code:myproject")`.
182
+ Copy `agents/SKILL.md` to `~/.claude/skills/agent-hub/SKILL.md`, restart Claude, and have it `bridge_register("claude-code:myproject")`.
183
183
 
184
184
  ### opencode
185
185
 
@@ -315,7 +315,8 @@ history attribution move atomically — queued messages and acks stay
315
315
  continuous. Renaming yourself is open to everyone; renaming/kicking
316
316
  **another** peer (`bridge_unregister { peer }`) or reading another peer's
317
317
  history (`bridge_history { peer }` / `peer: "all"`) requires the **manager**
318
- role (`--manager-peers`, default `agent-hub-cli` — the desktop GUI identity).
318
+ role (`--manager-peers`, default `agent-hub-cli,hub-admin` — the desktop GUI
319
+ and the web console identities).
319
320
  This is a convention on top of the loopback trust model, not authentication.
320
321
 
321
322
  Rosters persist: `--state-file` (default `~/.agent-comm-hub/roster.json`,
@@ -351,7 +352,7 @@ agent-comm-hub service install|uninstall [options] one-shot auto-start
351
352
  (default herdr, resolved via PATH)
352
353
  --herdr-timeout-ms <n> Default cap for one herdr call in ms (default 30000)
353
354
  --manager-peers <ids> Comma-separated roster managers, or "all"
354
- (default agent-hub-cli — the desktop GUI identity)
355
+ (default agent-hub-cli,hub-admin — desktop GUI + web console)
355
356
  --state-file <path> Roster persistence file
356
357
  (default ~/.agent-comm-hub/roster.json; "off" = memory only)
357
358
  --url <u> / --server-name <n> / --remove / --dry-run (setup/service/status)
@@ -429,7 +430,8 @@ const hub = startHub({ port: 18764 }, console) // returns { hub, registry, serve
429
430
  ```bash
430
431
  pnpm install
431
432
  pnpm typecheck # tsc --noEmit (strict)
432
- pnpm test # test suite (263 checks: 138 smoke + 36 setup + 11 ops + 35 herdr + 23 discover + 20 e2e)
433
+ pnpm test # test suite (291 checks: 165 smoke + 37 setup + 11 ops + 35 herdr + 23 discover + 20 e2e)
434
+ npm run build:admin # admin/ workspace (npm) → single-file assets/admin.html
433
435
  pnpm run build # esbuild → lib/{cli,index,setup}.js (zero deps)
434
436
  pnpm pack # build + npm pack (publishing artifact)
435
437
  ```
@@ -479,4 +481,4 @@ Tests cover registration, duplicate rejection, chat routing, sender-filtered wai
479
481
 
480
482
  ## License
481
483
 
482
- MIT — see [LICENSE](LICENSE). Contributions welcome: keep the 64-check suite green (`pnpm test`) and zero runtime dependencies. Architecture: [ARCHITECTURE.md](ARCHITECTURE.md).
484
+ MIT — see [LICENSE](LICENSE). Contributions welcome: keep the 291-check suite green (`pnpm test`) and zero runtime dependencies. Architecture: [ARCHITECTURE.md](ARCHITECTURE.md).
package/README.zh.md CHANGED
@@ -124,14 +124,14 @@ curl -X POST http://127.0.0.1:18764/mcp \
124
124
 
125
125
  | Agent | 配置文件 | 模板 | Skill 位置 |
126
126
  |---|---|---|---|
127
- | MiniMax Code (mcode) | `~/.minimax/mcp.json`(+ `~/.minimax/mcp/mcp.json`) | [`agents/minimax-code/`](agents/minimax-code/) | `~/.minimax/skills/agent-comm-hub/SKILL.md` |
128
- | opencode | `~/.config/opencode/opencode.json` | [`agents/opencode/opencode.json`](agents/opencode/opencode.json) | `~/.config/opencode/skills/agent-comm-hub/SKILL.md` |
129
- | Kimi Code | `~/.kimi-code/mcp.json` | [`agents/kimi-code/mcp-entry.json`](agents/kimi-code/mcp-entry.json) | `~/.kimi-code/skills/agent-comm-hub/SKILL.md` |
130
- | Gemini CLI | `~/.gemini/settings.json` | [`agents/gemini-cli/settings.json`](agents/gemini-cli/settings.json) | `~/.gemini/skills/agent-comm-hub/SKILL.md` |
131
- | Codex | `~/.codex/config.toml` | [`agents/codex/config.toml`](agents/codex/config.toml) | `~/.codex/skills/agent-comm-hub/SKILL.md` |
132
- | zcode | `~/.zcode/cli/config.json`(`mcp.servers`) | [`agents/zcode/config.json`](agents/zcode/config.json) | `~/.zcode/skills/agent-comm-hub/SKILL.md` |
133
- | Claude Code | 项目根 `.mcp.json`(手动;**绝不碰 `~/.claude.json`**——含凭据) | [`agents/claude-code/.mcp.json`](agents/claude-code/.mcp.json) | `~/.claude/skills/agent-comm-hub/SKILL.md` |
134
- | DeepSeek Harness (DSH) | profile `cordis.patch.yml`(手动) | [`agents/dsh/cordis.patch.yml`](agents/dsh/cordis.patch.yml) | `$DSH_HOME/skills/agent-comm-hub/SKILL.md` |
127
+ | MiniMax Code (mcode) | `~/.minimax/mcp.json`(+ `~/.minimax/mcp/mcp.json`) | [`agents/minimax-code/`](agents/minimax-code/) | `~/.minimax/skills/agent-hub/SKILL.md` |
128
+ | opencode | `~/.config/opencode/opencode.json` | [`agents/opencode/opencode.json`](agents/opencode/opencode.json) | `~/.config/opencode/skills/agent-hub/SKILL.md` |
129
+ | Kimi Code | `~/.kimi-code/mcp.json` | [`agents/kimi-code/mcp-entry.json`](agents/kimi-code/mcp-entry.json) | `~/.kimi-code/skills/agent-hub/SKILL.md` |
130
+ | Gemini CLI | `~/.gemini/settings.json` | [`agents/gemini-cli/settings.json`](agents/gemini-cli/settings.json) | `~/.gemini/skills/agent-hub/SKILL.md` |
131
+ | Codex | `~/.codex/config.toml` | [`agents/codex/config.toml`](agents/codex/config.toml) | `~/.codex/skills/agent-hub/SKILL.md` |
132
+ | zcode | `~/.zcode/cli/config.json`(`mcp.servers`) | [`agents/zcode/config.json`](agents/zcode/config.json) | `~/.zcode/skills/agent-hub/SKILL.md` |
133
+ | Claude Code | 项目根 `.mcp.json`(手动;**绝不碰 `~/.claude.json`**——含凭据) | [`agents/claude-code/.mcp.json`](agents/claude-code/.mcp.json) | `~/.claude/skills/agent-hub/SKILL.md` |
134
+ | DeepSeek Harness (DSH) | profile `cordis.patch.yml`(手动) | [`agents/dsh/cordis.patch.yml`](agents/dsh/cordis.patch.yml) | `$DSH_HOME/skills/agent-hub/SKILL.md` |
135
135
 
136
136
  > 各 agent 对 streamable-http 的支持随版本演进;不支持的客户端可加 stdio 包装。
137
137
 
@@ -206,7 +206,7 @@ agent-comm-hub service uninstall
206
206
 
207
207
  ### 花名册管理(别名、踢人)
208
208
 
209
- 每个 peer 带一份**档案**:连接时上报的客户端名/版本,外加可选的**显示别名**(`bridge_rename`)。别名纯展示——只出现在 `bridge_peers` / `bridge_status` 和桌面端花名册里;路由、信箱、历史、ack 始终使用 peer id,因此改名不会丢消息、不迁移状态。管理端还能对已注册 peer 做**真改名**(`bridge_rename { peer, peerId }`):信箱、等待器、session 绑定与历史归属原子迁移,排队消息与 ack 路由保持连续。给自己改别名人人可以;改**别人**的别名、踢人(`bridge_unregister { peer }`)、读别人的历史(`bridge_history { peer }` / `peer: "all"`)需要**管理端**身份(`--manager-peers`,默认 `agent-hub-cli`,即桌面 GUI 的身份)。这是叠加在本机信任模型上的约定,不是鉴权。
209
+ 每个 peer 带一份**档案**:连接时上报的客户端名/版本,外加可选的**显示别名**(`bridge_rename`)。别名纯展示——只出现在 `bridge_peers` / `bridge_status` 和桌面端花名册里;路由、信箱、历史、ack 始终使用 peer id,因此改名不会丢消息、不迁移状态。管理端还能对已注册 peer 做**真改名**(`bridge_rename { peer, peerId }`):信箱、等待器、session 绑定与历史归属原子迁移,排队消息与 ack 路由保持连续。给自己改别名人人可以;改**别人**的别名、踢人(`bridge_unregister { peer }`)、读别人的历史(`bridge_history { peer }` / `peer: "all"`)需要**管理端**身份(`--manager-peers`,默认 `agent-hub-cli,hub-admin`,即桌面 GUI 与网页管理台的身份)。这是叠加在本机信任模型上的约定,不是鉴权。
210
210
 
211
211
  花名册可落盘:`--state-file`(默认 `~/.agent-comm-hub/roster.json`,`off` 关闭),别名与客户端信息在 hub 重启后保留。
212
212
 
@@ -276,7 +276,8 @@ const hub = startHub({ port: 18764 }, console) // 返回 { hub, registry, server
276
276
  ```bash
277
277
  pnpm install
278
278
  pnpm typecheck # tsc --noEmit(strict)
279
- pnpm test # 测试套件(240 项:135 冒烟 + 36 安装器 + 11 运维 + 35 herdr + 23 发现)
279
+ pnpm test # 测试套件(291 项:165 冒烟 + 37 安装器 + 11 运维 + 35 herdr + 23 发现 + 20 e2e)
280
+ npm run build:admin # admin/ 工作区(用 npm)→ 单文件 assets/admin.html
280
281
  pnpm run build # esbuild → lib/{cli,index,setup}.js(零依赖)
281
282
  pnpm pack # 构建 + npm pack(发布产物)
282
283
  ```
package/agents/README.md CHANGED
@@ -23,14 +23,14 @@ Codex(TOML 追加)/ zcode(`mcp.servers`)。Claude Code 和 DSH 需手动
23
23
 
24
24
  | Agent | 配置文件 | 片段 | Skill 位置 |
25
25
  |---|---|---|---|
26
- | MiniMax Code (mcode) | `~/.minimax/mcp.json` + `~/.minimax/mcp/mcp.json` | `minimax-code/mcp-entry.json` | `~/.minimax/skills/agent-comm-hub/SKILL.md`(或跑 `minimax-code/install-mcode.ps1`) |
27
- | opencode | `~/.config/opencode/opencode.json` | `opencode/opencode.json` | `~/.config/opencode/skills/agent-comm-hub/SKILL.md` |
28
- | Kimi Code | `~/.kimi-code/mcp.json` | `kimi-code/mcp-entry.json`(`transport: "http"`,url 自动推断为 http) | `~/.kimi-code/skills/agent-comm-hub/SKILL.md` |
29
- | Gemini CLI | `~/.gemini/settings.json` | `gemini-cli/settings.json` | `~/.gemini/skills/agent-comm-hub/SKILL.md` |
30
- | Codex | `~/.codex/config.toml` | `codex/config.toml` | `~/.codex/skills/agent-comm-hub/SKILL.md` |
31
- | zcode | `~/.zcode/cli/config.json` | `zcode/config.json` | `~/.zcode/skills/agent-comm-hub/SKILL.md` |
32
- | Claude Code | 项目根 `.mcp.json`(手动复制;**不碰 `~/.claude.json`**——含凭据且无法安全往返) | `claude-code/.mcp.json` | `~/.claude/skills/agent-comm-hub/SKILL.md` |
33
- | DeepSeek Harness (DSH) | profile `cordis.patch.yml`(手动合并) | `dsh/cordis.patch.yml`(`@deepseek-ai/dsh-mcp-client`,**serverName: `agent-comm-hub`**,工具名为 `mcp__agent-comm-hub__bridge_*`;刻意不用 `agent-hub`,避免与 MCP 管理器动态挂载同名冲突) | `$DSH_HOME/skills/agent-comm-hub/SKILL.md` |
26
+ | MiniMax Code (mcode) | `~/.minimax/mcp.json` + `~/.minimax/mcp/mcp.json` | `minimax-code/mcp-entry.json` | `~/.minimax/skills/agent-hub/SKILL.md`(或跑 `minimax-code/install-mcode.ps1`) |
27
+ | opencode | `~/.config/opencode/opencode.json` | `opencode/opencode.json` | `~/.config/opencode/skills/agent-hub/SKILL.md` |
28
+ | Kimi Code | `~/.kimi-code/mcp.json` | `kimi-code/mcp-entry.json`(`transport: "http"`,url 自动推断为 http) | `~/.kimi-code/skills/agent-hub/SKILL.md` |
29
+ | Gemini CLI | `~/.gemini/settings.json` | `gemini-cli/settings.json` | `~/.gemini/skills/agent-hub/SKILL.md` |
30
+ | Codex | `~/.codex/config.toml` | `codex/config.toml` | `~/.codex/skills/agent-hub/SKILL.md` |
31
+ | zcode | `~/.zcode/cli/config.json` | `zcode/config.json` | `~/.zcode/skills/agent-hub/SKILL.md` |
32
+ | Claude Code | 项目根 `.mcp.json`(手动复制;**不碰 `~/.claude.json`**——含凭据且无法安全往返) | `claude-code/.mcp.json` | `~/.claude/skills/agent-hub/SKILL.md` |
33
+ | DeepSeek Harness (DSH) | profile `cordis.patch.yml`(手动合并) | `dsh/cordis.patch.yml`(`@deepseek-ai/dsh-mcp-client`,**serverName: `agent-comm-hub`**,工具名为 `mcp__agent-comm-hub__bridge_*`;刻意不用 `agent-hub`,避免与 MCP 管理器动态挂载同名冲突) | `$DSH_HOME/skills/agent-hub/SKILL.md` |
34
34
 
35
35
  > 各 agent 对 streamable-http MCP 的支持随版本演进,模板里的字段以官方文档为准;
36
36
  > 不支持的版本可退化为 stdio 包装(见下)。
package/agents/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: agent-comm-hub
3
- description:
3
+ description: >-
4
4
  Real-time two-way communication with other AI agents connected to the local
5
5
  agent-comm-hub. Use when the user mentions another agent, the hub, group
6
6
  chat, sending messages or tasks to another agent, waiting for another
@@ -23,23 +23,28 @@ Optional: call `bridge_register(peerId)` to claim a readable id
23
23
 
24
24
  ## Tools
25
25
 
26
- - `bridge_chat(to, message)` — send a chat message to a peer; `to: "all"`
27
- broadcasts.
28
- - `bridge_task(to, prompt, context?, deliverable?)` delegate a structured
29
- task.
30
- - `bridge_ack(ref, status, note?)` acknowledge a task
31
- (`accepted`/`rejected`/`done`/`failed`), auto-routed back to the original
32
- sender.
33
- - `bridge_task_status(ref)` one task's ledger state + full ack timeline.
26
+ - `bridge_chat(to, message, threadId?, ref?)` — send a chat to a peer, group
27
+ id, or `"all"` (broadcast). `threadId` groups a multi-turn dialog; `ref`
28
+ marks a reply-to and is capped at 5 hops per chain (see Notes).
29
+ - `bridge_task(to, prompt, context?, deliverable?, timeoutMs?, threadId?)` —
30
+ delegate a structured task. `timeoutMs` is a soft SLA: the hub marks the
31
+ task `timeout` if no terminal ack arrives in time.
32
+ - `bridge_ack(ref, status, note?, progress?)` — acknowledge a task.
33
+ Statuses: `accepted` | `working` | `rejected` | `done` | `failed`.
34
+ `working` + `progress` (0–100) report intermediate state. Terminal
35
+ statuses lock the task (later acks are recorded on the timeline but do
36
+ not reopen it). The ack is auto-routed to the original sender of `ref`.
37
+ - `bridge_task_status(ref)` — one task's ledger state, per-assignee state,
38
+ and full ack timeline.
34
39
  - `bridge_tasks(role?, status?, limit?)` — list tasks you sent or received.
35
- - `bridge_wait(from?, ref?, timeoutMs?)` — long-poll for the next message
36
- (default 30 s; `ref` waits specifically for that task's ack; loop it to
37
- hold a real-time conversation).
40
+ - `bridge_wait(from?, ref?, threadId?, timeoutMs?)` — long-poll for the next
41
+ message (default 30 s; `ref` waits for that task's ack; `threadId` narrows
42
+ to one dialog). Loop it to hold a real-time conversation.
38
43
  - `bridge_poll(from?)` — non-blocking drain of every queued message.
39
44
  - `bridge_status()` / `bridge_peers()` — hub health and who is online.
40
- - `bridge_history(peer?, limit?)` — recent messages (newest first). `peer`
41
- defaults to you; pass another peer's id to read their conversation, or
42
- `"all"` for the unfiltered tail across every peer.
45
+ - `bridge_history(peer?, limit?, channel?)` — recent messages (newest first).
46
+ - `bridge_group_create/send/list/delete` + `add_member`/`remove_member`
47
+ named channels for a subset of peers.
43
48
 
44
49
  ## When to use
45
50
 
@@ -52,9 +57,11 @@ Optional: call `bridge_register(peerId)` to claim a readable id
52
57
  3. Receiving: try `bridge_poll()` first; if empty, loop `bridge_wait()` until
53
58
  a message arrives or you give up.
54
59
  4. On receiving a `task` (content is `{prompt, context?, deliverable?}`):
55
- acknowledge with `bridge_ack(ref, "accepted")` when you take it on, then
56
- `bridge_ack(ref, "done"[, note])` when finished; use `"rejected"` to
57
- decline and `"failed"` when it could not be completed (always with a note).
60
+ - `bridge_ack(ref, "accepted")` when you take it on
61
+ - `bridge_ack(ref, "working", note?, progress?)` for long-running work
62
+ - `bridge_ack(ref, "done"[, note])` when finished
63
+ - `bridge_ack(ref, "rejected")` to decline (with a reason)
64
+ - `bridge_ack(ref, "failed")` when it could not be completed (with a note)
58
65
  5. Unsure whether the peer is online: check `bridge_peers()` first.
59
66
 
60
67
  ## Common workflows (plain language)
@@ -64,29 +71,45 @@ Follow the scenario directly (tool names stay as-is):
64
71
  **1. Someone delegates a task to you (e.g. codex plans -> you build)**
65
72
  - On receiving a task: acknowledge first — `bridge_ack(ref, "accepted")`,
66
73
  say "got it, starting".
74
+ - For work that takes a while: `bridge_ack(ref, "working", note, progress)`
75
+ so the delegator can see it is moving.
67
76
  - When done: send the result and a delivery note back to the delegator
68
77
  (`bridge_chat` / `bridge_task`), then `bridge_ack(ref, "done", note)` so it
69
78
  can review.
70
79
  - If you can't do it: `bridge_ack(ref, "rejected")` with the reason.
71
80
 
72
81
  **2. You delegate to someone else (wait vs don't-wait)**
73
- - Wait for delivery: after `bridge_task`, loop `bridge_wait()` until the
74
- result arrives, then take it over.
82
+ - Wait for delivery: after `bridge_task`, loop `bridge_wait({ref})` until the
83
+ terminal ack arrives, then take the result over.
75
84
  - Don't wait: send it and move on; the peer sends the result back when done —
76
85
  collect it later with `bridge_poll()` / `bridge_wait()` /
77
86
  `bridge_history()` (messages queue while you are away).
87
+ - Need a deadline: pass `timeoutMs` on `bridge_task`; the ledger will show
88
+ `timeout` if the assignee never finishes.
78
89
 
79
90
  **3. Multi-agent real-time discussion**
80
91
  - After you've said your piece, stay in the conversation: loop
81
92
  `bridge_wait()` to keep listening — nothing arrived this round, wait the
82
93
  next — until a conclusion is reached or the user says "done".
83
94
  - A timeout (`{type:"timeout"}`) is not a failure; keep waiting.
95
+ - Optional: put the dialog on one `threadId` so `bridge_wait({threadId})`
96
+ only sees that conversation.
84
97
 
85
98
  ## Notes
86
99
 
87
- - Messages travel on loopback only (127.0.0.1:18764); never put credentials
88
- in bridge messages.
100
+ - Messages travel on loopback only (127.0.0.1:18764) in local mode; never put
101
+ credentials in bridge messages.
89
102
  - A timeout is not a failure: `bridge_wait` returning `{type:"timeout"}` just
90
103
  means nothing arrived — try again.
91
104
  - Cadence: use 10–30 s short polls when the peer is active; check
92
105
  `bridge_peers()` when unsure.
106
+ - Task terminal states (`done`/`failed`/`rejected`/`timeout`) cannot be
107
+ reopened; start a new task instead of re-acking.
108
+ - **Reply chains are capped at 5 hops.** Every message carrying `ref` sits one
109
+ hop deeper than the message it points at, and the hub rejects the 6th with
110
+ `hop limit exceeded`. You only run into it when you keep replying
111
+ (`ref`) or re-delegating along one chain instead of starting a new message —
112
+ two agents answering each other's replies forever is exactly what the cap
113
+ exists to stop. When it happens, stop extending that chain: send a fresh
114
+ message with no `ref` (a new `threadId` keeps it readable as one dialog) and
115
+ restate the context in it, or continue with `bridge_task` for new work.
@@ -117,25 +117,21 @@ Write-Step '- mcode'
117
117
  foreach ($f in @((Join-Path $userHome '.minimax\mcp.json'), (Join-Path $userHome '.minimax\mcp\mcp.json'))) {
118
118
  Merge-JsonServer 'mcode' $f 'mcpServers' $mcodeEntry
119
119
  }
120
- Sync-Skill 'mcode' (Join-Path $userHome '.minimax\skills\agent-comm-hub')
121
120
 
122
121
  # ---------- opencode: mcp.<name> in ~/.config/opencode/opencode.json
123
122
  $opencodeEntry = [ordered]@{ type = 'remote'; url = $Url; enabled = $true }
124
123
  Write-Step '- opencode'
125
124
  Merge-JsonServer 'opencode' (Join-Path $userHome '.config\opencode\opencode.json') 'mcp' $opencodeEntry
126
- Sync-Skill 'opencode' (Join-Path $userHome '.config\opencode\skills\agent-comm-hub')
127
125
 
128
126
  # ---------- Kimi Code: mcpServers at root of ~/.kimi-code/mcp.json
129
127
  $kimiEntry = [ordered]@{ transport = 'http'; url = $Url; startupTimeoutMs = 30000; toolTimeoutMs = 120000 }
130
128
  Write-Step '- kimi-code'
131
129
  Merge-JsonServer 'kimi-code' (Join-Path $userHome '.kimi-code\mcp.json') 'mcpServers' $kimiEntry
132
- Sync-Skill 'kimi-code' (Join-Path $userHome '.kimi-code\skills\agent-comm-hub')
133
130
 
134
131
  # ---------- Gemini CLI: mcpServers in ~/.gemini/settings.json
135
132
  $geminiEntry = [ordered]@{ type = 'http'; url = $Url }
136
133
  Write-Step '- gemini-cli'
137
134
  Merge-JsonServer 'gemini-cli' (Join-Path $userHome '.gemini\settings.json') 'mcpServers' $geminiEntry
138
- Sync-Skill 'gemini-cli' (Join-Path $userHome '.gemini\skills\agent-comm-hub')
139
135
 
140
136
  # ---------- Codex: append [mcp_servers.<name>] to ~/.codex/config.toml (incremental append only)
141
137
  $codexFile = Join-Path $userHome '.codex\config.toml'
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: agent-comm-hub
3
- description:
3
+ description: >-
4
4
  Real-time two-way communication with other AI agents connected to the local
5
5
  agent-comm-hub. Use when the user mentions another agent, the hub, group
6
6
  chat, sending messages or tasks to another agent, waiting for another