agent-comm-hub 0.9.0 → 0.10.0

package/README.md

@@ -98,7 +98,7 @@ itself).
 
 ```bash
 agent-comm-hub setup
-# or: agents/install-all.ps1 (PowerShell equivalent)
+# (agents/install-all.ps1 is deprecated — it forwards to this command)
 # 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
@@ -131,7 +131,7 @@ curl -X POST http://127.0.0.1:18764/mcp \
 
 Each agent gets **one MCP server entry** pointing at `http://127.0.0.1:18764/mcp`, plus the shared English skill (`agents/SKILL.md`) that teaches it when and how to use the bridge tools. Templates live in [`agents/`](agents/README.md).
 
-**One-shot incremental sync** (recommended): `agents/install-all.ps1` merges the
+**One-shot incremental sync** (recommended): `agent-comm-hub setup` merges the
 `agent-hub` entry into every installed agent's MCP config (mcode, opencode,
 Kimi Code, Gemini CLI, Codex, zcode, DSH) and installs the skill — it only
 touches the `agent-hub` key, backs up each file, and is idempotent. Claude Code
@@ -252,16 +252,31 @@ with `agent-comm-hub setup --remove` (or only refresh skills via
 
 | Tool | Purpose |
 |---|---|
-| `bridge_register(peerId)` | Claim or rename your identity (auto-registered at connect with the client name; optional for a readable id like `opencode:myproject`) |
-| `bridge_unregister()` | Leave the hub (removes peer, queue, and session binding; stays off until an explicit register) |
-| `bridge_chat(to, message)` | Send a chat message; `to: "all"` broadcasts |
-| `bridge_task(to, prompt, context?, deliverable?)` | Delegate a structured task |
-| `bridge_ack(ref, status, note?)` | Acknowledge a task (`accepted`/`rejected`/`done`/`failed`), routed back to the original sender |
-| `bridge_wait(from?, timeoutMs?)` | Long-poll for the next message (default 30 s) |
-| `bridge_poll(from?)` | Non-blocking drain of queued messages |
+| `bridge_register(peerId, alias?)` | Claim or rename your identity (auto-registered at connect with the client name; optional for a readable id like `opencode:myproject`) |
+| `bridge_rename(alias?, peer?, peerId?)` | Set your own display alias; renaming or true-renaming **another** peer needs manager rights |
+| `bridge_unregister(peer?)` | Leave the hub (removes peer, queue, and session binding; stays off until an explicit register). With `peer`, kicks that peer (manager) |
+| `bridge_chat(to, message, threadId?, priority?, ref?, expiresAt?)` | Send a chat message; `to: "all"` broadcasts. `expiresAt` is an absolute epoch-ms deadline: a message still undelivered after it is dropped and counted, not delivered late. `priority` (0\|1\|2, default 0) orders the recipient's mailbox |
+| `bridge_notice(to, message, level?)` | Send a system-flavoured notice (`info`/`warn`/`error`) — read as a status, not as chat; creates no task |
+| `bridge_task(to, prompt, context?, deliverable?, timeoutMs?, threadId?, ref?, expiresAt?)` | Delegate a structured task (`timeoutMs` is the assignee's SLA once it arrives; `expiresAt` is the delivery deadline) |
+| `bridge_ack(ref, status, note?, progress?)` | Acknowledge a task (`accepted`/`working`/`rejected`/`done`/`failed`), routed back to the original sender |
+| `bridge_wait(from?, ref?, threadId?, timeoutMs?, ack?, maxMessages?)` | Long-poll for the next message (default 30 s). `ack: "manual"` leases it instead of consuming it; `maxMessages > 1` returns `{type:"messages", messages:[…]}` in one call |
+| `bridge_poll(from?, ack?)` | Non-blocking drain of queued messages (`ack: "manual"` leases them) |
+| `bridge_commit(ids)` | Acknowledge leased messages; uncommitted ones come back when the lease expires |
+| `bridge_nack(ids)` | Give leased (or dead-lettered) messages back immediately — use when handling failed |
 | `bridge_status()` | Hub health: peers with connected/queued/waiting state |
-| `bridge_peers()` | Who is online |
-| `bridge_history(peer?, limit?)` | Recent messages (context refresh after reconnect) |
+| `bridge_peers()` | Who is online, how reachable (`online`/`idle`/`parked`) and how much is queued |
+| `bridge_history(peer?, limit?, channel?)` | Recent messages (context refresh after reconnect) |
+| `bridge_tasks(role?, status?, limit?, peer?)` | Task ledger rows you sent or received |
+| `bridge_task_status(ref)` | One task's state, per-assignee rows and the full ack timeline (also carries the A2A aliases `taskId` / `contextId` / `a2aState`) |
+| `bridge_task_cancel(ref, reason?)` | Cancel a task — either side may; routed to the other side and terminal |
+| `bridge_task_input(ref, input)` | Answer an `input-required` interrupt; the task resumes to `working` |
+| `bridge_announce(card)` | Say what you can do (skills, `acceptsTasks`, modes, runner) |
+| `bridge_discover(skill?, tag?, acceptsTasks?, idleOnly?)` | Find a peer to hand work to, with its current load |
+| `bridge_group_create` · `bridge_group_send` · `bridge_group_list` · `bridge_group_delete` · `bridge_group_add_member` · `bridge_group_remove_member` | Named channels for a subset of peers |
+
+That is the full 26 message + group tools; the 11 control tools are below. (37 in total and symmetric on every side — see [ARCHITECTURE.md](ARCHITECTURE.md) §4.)
+
+Two peer ids are reserved and cannot be registered or renamed into: `all` (broadcast) and `hub` (the hub's own drop notices — `bridge_wait { from: "hub" }` subscribes to them).
 
 ### herdr control tools (optional)
 
@@ -294,6 +309,7 @@ socket — physical input, read output:
 | `bridge_pane_send(target, text, enter?)` | Type text into a pane (slash commands execute; Enter submits by default) |
 | `bridge_pane_keys(target, keys)` | Raw key presses to any pane |
 | `bridge_pane_read(target, lines?, source?)` | Read a pane's recent output |
+| `bridge_pane_wait(target, until?, timeoutMs?)` | Wait for a pane to reach a state (idle / working / blocked / done) |
 
 Verified live: a MiniMax Code session was driven end-to-end through the hub —
 prompt injected via `bridge_pane_send`, reply collected via
@@ -317,7 +333,17 @@ continuous. Renaming yourself is open to everyone; renaming/kicking
 history (`bridge_history { peer }` / `peer: "all"`) requires the **manager**
 role (`--manager-peers`, default `agent-hub-cli,hub-admin` — the desktop GUI
 and the web console identities).
-This is a convention on top of the loopback trust model, not authentication.
+
+With no credential configured this is a convention on top of the loopback trust
+model, not authentication — the peer id is simply whoever claimed it first. Set
+`--manager-token <secret>` (or drop the secret in `<state-file dir>/manager.token`)
+to make manager PRIVILEGES require it: rename/kick/full-history/task-board and the
+SSE relay then need `Authorization: Bearer <secret>`, and a credential-less client
+that claims a manager id gets no power. The id itself is not reserved — the
+desktop GUI identifies itself as `agent-hub-cli`, so reserving it would stop the
+GUI from connecting. Note that claiming the id still occupies its identity and
+mailbox even without the credential, and that in remote mode (`--auth-tokens`) the
+token table owns the `Authorization` header, so `--manager-token` is ignored there.
 
 Rosters persist: `--state-file` (default `~/.agent-comm-hub/roster.json`,
 `off` to disable) keeps aliases and client info across hub restarts.
@@ -347,12 +373,42 @@ agent-comm-hub service install|uninstall [options]   one-shot auto-start
 --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)
---peer-idle-timeout-ms <n> Auto-unregister idle peers after this; 0 disables (default 600000)
+--peer-idle-timeout-ms <n> Park (not delete) idle peers after this; 0 disables the GC
+                         entirely (default 600000)
+--parked-ttl-ms <n>      Drop a parked mailbox after this; 0 disables expiry
+                         (default 604800000 = 7 days)
+--rate-per-min <n>       Per-peer mailbox rate limit (messages per minute); 0 (default)
+                         is unlimited. Guards a recipient against a broadcast storm;
+                         excess is counted as `droppedRate` in the roster
+--db <path>              SQLite state file for history/mailboxes/roster/groups/tasks
+                         (default ~/.agent-comm-hub/state.db; "off" = memory + JSON roster)
+--auth-tokens <file>     REMOTE MODE: require `Authorization: Bearer <token>`; the token,
+                         not the client name, decides the peer id. Also refuses a
+                         non-loopback --host unless this is set.
+--allow-join             (remote mode) accept token-less walk-in peers, each on a unique
+                         id; LAN/VPN only — keep it off on the public internet.
+--heartbeat-ms <n>       SSE heartbeat cadence (default 20000)
+--runner <json>          Executor for a peer that is NOT polling: one JSON object
+                         or an array, e.g. {"peer":"codex","kind":"cli",
+                         "command":"codex","args":["exec","{prompt}"]} or
+                         {"peer":"mcode","kind":"herdr"}. Off by default; the
+                         runner's outcome is written back as that peer's ack.
 --herdr-bin <path>       herdr CLI binary for bridge_agent_* control tools
                          (default herdr, resolved via PATH)
 --herdr-timeout-ms <n>   Default cap for one herdr call in ms (default 30000)
 --manager-peers <ids>    Comma-separated roster managers, or "all"
                          (default agent-hub-cli,hub-admin — desktop GUI + web console)
+--manager-token <secret> Require this secret (Authorization: Bearer <secret>) for hub
+                         manager PRIVILEGES (rename/kick/full history/relay); otherwise
+                         <state-file dir>/manager.token is read when present. The peer
+                         id itself is not reserved. Ignored with --auth-tokens.
+--allow-origins <list>   Comma-separated browser origins allowed to call the MCP
+                         endpoint (e.g. https://hub.example.com). Requests without
+                         an Origin header and loopback origins are always allowed;
+                         anything else gets 403 (the MCP spec's DNS-rebinding rule).
+--insecure               Allow --host to bind a non-loopback address with NO token
+                         table. Refused by default: without --auth-tokens the hub
+                         would trust every client that can reach the port.
 --state-file <path>      Roster persistence file
                          (default ~/.agent-comm-hub/roster.json; "off" = memory only)
 --url <u> / --server-name <n> / --remove / --dry-run   (setup/service/status)
@@ -430,7 +486,7 @@ const hub = startHub({ port: 18764 }, console) // returns { hub, registry, serve
 ```bash
 pnpm install
 pnpm typecheck        # tsc --noEmit (strict)
-pnpm test             # test suite (282 checks: 156 smoke + 37 setup + 11 ops + 35 herdr + 23 discover + 20 e2e)
+pnpm test             # test suite (314 checks: 169 smoke + 46 setup + 11 ops + 35 herdr + 33 discover + 20 e2e)
 npm run build:admin   # admin/ workspace (npm) → single-file assets/admin.html
 pnpm run build        # esbuild → lib/{cli,index,setup}.js (zero deps)
 pnpm pack             # build + npm pack (publishing artifact)
@@ -481,4 +537,4 @@ Tests cover registration, duplicate rejection, chat routing, sender-filtered wai
 
 ## License
 
-MIT — see [LICENSE](LICENSE). Contributions welcome: keep the 282-check suite green (`pnpm test`) and zero runtime dependencies. Architecture: [ARCHITECTURE.md](ARCHITECTURE.md).
+MIT — see [LICENSE](LICENSE). Contributions welcome: keep the 314-check suite green (`pnpm test`) and zero runtime dependencies. Architecture: [ARCHITECTURE.md](ARCHITECTURE.md).

package/README.zh.md

@@ -93,7 +93,7 @@ agent-comm-hub status             # hub 是否在跑？谁在线？
 
 ```bash
 agent-comm-hub setup
-# 或 PowerShell 版：agents/install-all.ps1
+# （agents/install-all.ps1 已废弃，它只是转发到这个命令）
 # 卸载：agent-comm-hub setup --remove
 # 查看本机装了什么（只读）：agent-comm-hub discover
 # 只配置某一个：agent-comm-hub setup --agent codex
@@ -276,7 +276,7 @@ const hub = startHub({ port: 18764 }, console) // 返回 { hub, registry, server
 ```bash
 pnpm install
 pnpm typecheck        # tsc --noEmit（strict）
-pnpm test             # 测试套件（282 项：156 冒烟 + 37 安装器 + 11 运维 + 35 herdr + 23 发现 + 20 e2e）
+pnpm test             # 测试套件（314 项：169 冒烟 + 46 安装器 + 11 运维 + 35 herdr + 33 发现 + 20 e2e）
 npm run build:admin   # admin/ 工作区（用 npm）→ 单文件 assets/admin.html
 pnpm run build        # esbuild → lib/{cli,index,setup}.js（零依赖）
 pnpm pack             # 构建 + npm pack（发布产物）

package/agents/SKILL.md

@@ -6,7 +6,8 @@ description: >-
   chat, sending messages or tasks to another agent, waiting for another
   agent's reply, or forwarding results between agents. Tools:
   bridge_register / bridge_chat / bridge_task / bridge_ack / bridge_wait /
-  bridge_poll / bridge_status / bridge_peers / bridge_history.
+  bridge_poll / bridge_status / bridge_peers / bridge_history /
+  bridge_commit / bridge_nack.
 ---
 
 # agent-comm-hub usage
@@ -23,26 +24,59 @@ Optional: call `bridge_register(peerId)` to claim a readable id
 
 ## Tools
 
-- `bridge_chat(to, message, threadId?, ref?)` — send a chat to a peer, group
-  id, or `"all"` (broadcast). `threadId` groups a multi-turn dialog; `ref`
-  marks a reply-to.
-- `bridge_task(to, prompt, context?, deliverable?, timeoutMs?, threadId?)` —
+- `bridge_chat(to, message, threadId?, ref?, expiresAt?)` — send a chat to a peer,
+  group id, or `"all"` (broadcast). `threadId` groups a multi-turn dialog; `ref`
+  marks a reply-to (chain depth is bounded — see Notes). `expiresAt` is an
+  absolute epoch-ms deadline: a message still undelivered when it passes is
+  dropped (counted as `droppedExpired`) instead of arriving late.
+- `bridge_notice(to, message, level?)` — send a system-flavoured line
+  ("your mailbox dropped 3 messages", "hub restarting"). `level` is
+  `info` | `warn` | `error`. Use it instead of `bridge_chat` when the recipient
+  should read it as a status, not as a peer talking; it creates no task.
+- `bridge_task(to, prompt, context?, deliverable?, timeoutMs?, threadId?, ref?, expiresAt?)` —
   delegate a structured task. `timeoutMs` is a soft SLA: the hub marks the
-  task `timeout` if no terminal ack arrives in time.
+  task `timeout` if no terminal ack arrives in time. `ref` names the task this
+  one answers; a task answering a task is a re-delegation, and that chain is
+  capped at 5 hops.
 - `bridge_ack(ref, status, note?, progress?)` — acknowledge a task.
   Statuses: `accepted` | `working` | `rejected` | `done` | `failed`.
   `working` + `progress` (0–100) report intermediate state. Terminal
   statuses lock the task (later acks are recorded on the timeline but do
   not reopen it). The ack is auto-routed to the original sender of `ref`.
 - `bridge_task_status(ref)` — one task's ledger state, per-assignee state,
-  and full ack timeline.
+  and full ack timeline (also carries the A2A aliases `taskId` / `contextId` /
+  `a2aState`).
 - `bridge_tasks(role?, status?, limit?)` — list tasks you sent or received.
-- `bridge_wait(from?, ref?, threadId?, timeoutMs?)` — long-poll for the next
+- `bridge_task_cancel(ref, reason?)` — cancel a task. Either side may: the sender
+  stops work it no longer wants, an assignee reports it will not finish. Routed to
+  the other side; `canceled` is terminal and a later ack cannot reopen it.
+- `bridge_task_input(ref, input)` — answer a task whose assignee acked
+  `input-required`. Only the SENDER calls this; the answer reaches the waiting
+  assignee and the task resumes to `working`.
+- `bridge_announce(card)` — say what you can do: skills, whether you accept tasks,
+  how many at once, input/output modes, and how you are executed when not polling.
+  Only peers that set `acceptsTasks: true` are offered by `bridge_discover`.
+- `bridge_discover(skill?, tag?, acceptsTasks?, idleOnly?)` — find a peer to hand
+  work to. Returns matches with their current load (`queued` / `waiting` /
+  `running`); by default only peers that accept tasks.
+- `bridge_wait(from?, ref?, threadId?, timeoutMs?, ack?, maxMessages?)` — long-poll for the next
   message (default 30 s; `ref` waits for that task's ack; `threadId` narrows
-  to one dialog). Loop it to hold a real-time conversation.
-- `bridge_poll(from?)` — non-blocking drain of every queued message.
+  to one dialog). Loop it to hold a real-time conversation. `ack: "manual"`
+  LEASES the message instead of consuming it.
+- `bridge_poll(from?, ack?)` — non-blocking drain of every queued message.
+- `bridge_commit(ids)` — confirm you have finished with leased messages. Until you
+  do, they are handed out again when the lease expires (with `attempts` growing),
+  so `ack: "manual"` + `bridge_commit` is the at-least-once path: use it when
+  losing a message would be worse than handling one twice. A message that keeps
+  being handed out without a commit is dead-lettered rather than looping forever
+  (`bridge_status` shows `inFlight` / `deadLettered`).
+- `bridge_nack(ids)` — give leased messages back now (handling failed), or revive
+  a dead-lettered one.
 - `bridge_status()` / `bridge_peers()` — hub health and who is online.
-- `bridge_history(peer?, limit?, channel?)` — recent messages (newest first).
+- `bridge_history(peer?, limit?, channel?, since?)` — recent messages (newest
+  first). `since` is a resume cursor: record `bridge_status().lastSeq`, then read
+  only what happened after it, with no repeats. A small `limit` still truncates,
+  so loop until you get an empty page.
 - `bridge_group_create/send/list/delete` + `add_member`/`remove_member` —
   named channels for a subset of peers.
 
@@ -104,4 +138,32 @@ Follow the scenario directly (tool names stay as-is):
 - Cadence: use 10–30 s short polls when the peer is active; check
   `bridge_peers()` when unsure.
 - Task terminal states (`done`/`failed`/`rejected`/`timeout`) cannot be
-  reopened; start a new task instead of re-acking.
+  reopened; start a new task instead of re-acking.
+- **Reply chains are counted, not enforced — nothing is ever refused.**
+  Every message carrying `ref` sits one hop deeper than the message it points at.
+  A plain conversation (chat / ack replies) counts up to **50** hops; a **task
+  re-delegation chain** — a task replying to a task — counts up to **5**. Past
+  either ceiling `hop` simply stops counting: the message and its `ref` are
+  delivered unchanged, so correlation never breaks and `bridge_wait({ ref })`
+  keeps working on arbitrarily long chains. Read `hop` as “how deep this chain
+  is, capped” — reaching the ceiling is a hint that the conversation has become
+  a loop, not an error to recover from.
+- **Nothing is dropped silently any more.** If your mailbox overflows (`maxQueue`)
+  or a message hits its `expiresAt` before you read it, the hub counts it and
+  `bridge_status` / `bridge_peers` show `droppedOverflow` / `droppedExpired` on
+  your row. When you are waiting you may also receive a `notice` whose `from` is
+  the reserved id `hub` — `bridge_wait { from: "hub" }` subscribes to exactly
+  those. `all` and `hub` are reserved: you cannot register or rename into them.
+- **Need at-least-once instead of best-effort?** Take messages with
+  `bridge_wait { ack: "manual" }` (or `bridge_poll { ack: "manual" }`) and call
+  `bridge_commit` once you have really handled them. Uncommitted messages come
+  back when the lease expires, with `attempts` incremented; `bridge_nack` gives
+  one back immediately. After too many hand-outs a message is dead-lettered
+  instead of looping (see `deadLettered` in the roster).
+- **SSE pushes are a client-runtime event channel, not a wake-up.** A hub
+  notification arrives on the stream you subscribed to; it does NOT start a model
+  turn, and an agent that is not polling will not be woken by it. Waking an agent
+  that is not in a `bridge_wait` loop is the job of a *runner* — the hub runs the
+  configured executor for that peer and writes the outcome back as its ack
+  (`--runner`; see the hub README). If you want to be woken, either loop on
+  `bridge_wait` or ask the operator to configure a runner for you.

package/agents/install-all.ps1

@@ -1,23 +1,19 @@
 <#
 .SYNOPSIS
-Sync the agent-comm-hub MCP entry into every installed agent's own config —
-incrementally. Only the "agent-hub" server key is added/updated; all other
-content is preserved byte-for-byte semantically, each file is backed up first,
-and re-running is a no-op. -Remove undoes everything.
+DEPRECATED shim. Use `agent-comm-hub setup` instead.
 
-Covered agents (auto-skipped when not installed):
-  - MiniMax Code (mcode)   ~/.minimax/mcp.json + ~/.minimax/mcp/mcp.json
-  - opencode               ~/.config/opencode/opencode.json
-  - Kimi Code              ~/.kimi-code/mcp.json
-  - Gemini CLI             ~/.gemini/settings.json
-  - Codex                  ~/.codex/config.toml (appends the section if missing)
-  - zcode                  ~/.zcode/cli/config.json (mcp.servers)
+.DESCRIPTION
+This script used to carry its own copy of the agent list and the merge logic.
+That copy drifted: it synced the skill into eight fixed directories with no
+"is this agent installed?" check, so running it on a machine with two agents
+created skill folders for six agents that were not there.
 
-Not covered (manual, documented in agents/README.md):
-  - Claude Code  -> project-level .mcp.json (copy agents/claude-code/.mcp.json)
-                   (~/.claude.json is not touched: it carries credentials and
-                   cannot be round-tripped safely)
-  - DSH          -> merge agents/dsh/cordis.patch.yml into the profile patch
+`agent-comm-hub setup` is registry-driven (`agents/registry.json`), only
+touches agents that are actually installed, backs every file up, and is
+covered by the test suite. It is the supported path.
+
+This file is kept so existing callers keep working: it forwards to that
+command with the same three switches. It no longer contains an agent list.
 
 .EXAMPLE
 powershell -ExecutionPolicy Bypass -File install-all.ps1
@@ -30,154 +26,23 @@ param(
 )
 
 $ErrorActionPreference = 'Stop'
-$userHome = $env:USERPROFILE
-$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
-$skillSrc = Join-Path $PSScriptRoot 'SKILL.md'
-
-function Write-Step($text) { Write-Host "[agent-comm-hub] $text" -ForegroundColor Cyan }
-
-function Read-Json($path) {
-  if (-not (Test-Path $path)) { return $null }
-  try { return [System.IO.File]::ReadAllText($path, [System.Text.Encoding]::UTF8) | ConvertFrom-Json }
-  catch { throw "cannot parse JSON: $path ($($_.Exception.Message))" }
-}
-
-function Write-JsonNoBom($path, $value) {
-  $dir = Split-Path $path
-  if (-not (Test-Path $dir)) { New-Item -ItemType Directory -Path $dir -Force | Out-Null }
-  [System.IO.File]::WriteAllText($path, ($value | ConvertTo-Json -Depth 50), $utf8NoBom)
-}
-
-function Backup($path) {
-  $stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
-  Copy-Item $path "$path.bak-$stamp" -Force -ErrorAction SilentlyContinue
-  return "$(Split-Path $path -Leaf).bak-$stamp"
-}
-
-function Sync-Skill($agentName, $skillDir) {
-  if ($Remove) {
-    if (Test-Path $skillDir) { Remove-Item $skillDir -Recurse -Force; Write-Step "  ${agentName}: removed skill $skillDir" }
-    return
-  }
-  if (-not (Test-Path $skillSrc)) { Write-Step "  ${agentName}: SKILL.md source missing (skipped)"; return }
-  New-Item -ItemType Directory -Path $skillDir -Force | Out-Null
-  Copy-Item $skillSrc (Join-Path $skillDir 'SKILL.md') -Force
-  Write-Step "  ${agentName}: skill -> $skillDir\SKILL.md"
-}
 
-function Merge-JsonServer($label, $file, $sectionName, $entry) {
-  if (-not (Test-Path $file)) { Write-Step "  ${label}: not installed ($file missing, skipped)"; return }
-  try {
-    $doc = Read-Json $file
-    if ($null -eq $doc) { Write-Step "  ${label}: empty config (skipped)"; return }
-    # Resolve (creating when missing) a dotted section path like 'mcp.servers'.
-    $servers = $doc
-    foreach ($part in $sectionName.Split('.')) {
-      if ($null -eq $servers.$part) {
-        $servers | Add-Member -NotePropertyName $part -NotePropertyValue ([ordered]@{}) -Force
-      }
-      $servers = $servers.$part
-    }
-    $changed = $false
-    if ($servers.PSObject.Properties.Name -contains $ServerName) {
-      $existing = $servers.$ServerName
-      $changed = ($existing.url -ne ${Url})
-    } else {
-      $changed = $true
-    }
-    if ($Remove) {
-      if ($servers.PSObject.Properties.Name -contains $ServerName) {
-        $servers.PSObject.Properties.Remove($ServerName)
-        $bak = Backup $file
-        Write-JsonNoBom $file $doc
-        Write-Step "  ${label}: removed '$ServerName' from $file (backup: $bak)"
-      } else {
-        Write-Step "  ${label}: '$ServerName' not present in $file"
-      }
-      return
-    }
-    if (-not $changed) { Write-Step "  ${label}: '$ServerName' already set -> ${Url} ($file unchanged)"; return }
-    $bak = Backup $file
-    $servers | Add-Member -NotePropertyName $ServerName -NotePropertyValue $entry -Force
-    Write-JsonNoBom $file $doc
-    Write-Step "  ${label}: merged '$ServerName' -> ${Url} into $file (backup: $bak)"
-  } catch {
-    Write-Step "  ${label}: SKIPPED — $($_.Exception.Message)"
-  }
-}
+Write-Warning 'install-all.ps1 is deprecated; use `agent-comm-hub setup` (this forwards to it).'
 
-if ($Remove) { Write-Step 'uninstalling from all agents...' } else { Write-Step "syncing '$ServerName' -> $Url to all agents..." }
+# Prefer an installed CLI; fall back to this checkout's built bundle.
+$cli = Get-Command agent-comm-hub -ErrorAction SilentlyContinue
+$setupArgs = @('setup', '--url', $Url, '--server-name', $ServerName)
+if ($Remove) { $setupArgs += '--remove' }
 
-# ---------- MiniMax Code (mcode): mcpServers at root of ~/.minimax/mcp.json + ~/.minimax/mcp/mcp.json
-$mcodeEntry = [ordered]@{
-  url = $Url; type = 'streamable-http'; enabled = $true; configured = $true; timeout = 120000
-  description = 'agent-comm-hub: talk to every other agent connected to the hub (bridge_register auto, bridge_chat/task/ack/wait/poll/status/peers/history).'
-}
-Write-Step '- mcode'
-foreach ($f in @((Join-Path $userHome '.minimax\mcp.json'), (Join-Path $userHome '.minimax\mcp\mcp.json'))) {
-  Merge-JsonServer 'mcode' $f 'mcpServers' $mcodeEntry
+if ($cli) {
+  & $cli.Source @setupArgs
+  exit $LASTEXITCODE
 }
 
-# ---------- opencode: mcp.<name> in ~/.config/opencode/opencode.json
-$opencodeEntry = [ordered]@{ type = 'remote'; url = $Url; enabled = $true }
-Write-Step '- opencode'
-Merge-JsonServer 'opencode' (Join-Path $userHome '.config\opencode\opencode.json') 'mcp' $opencodeEntry
-
-# ---------- Kimi Code: mcpServers at root of ~/.kimi-code/mcp.json
-$kimiEntry = [ordered]@{ transport = 'http'; url = $Url; startupTimeoutMs = 30000; toolTimeoutMs = 120000 }
-Write-Step '- kimi-code'
-Merge-JsonServer 'kimi-code' (Join-Path $userHome '.kimi-code\mcp.json') 'mcpServers' $kimiEntry
-
-# ---------- Gemini CLI: mcpServers in ~/.gemini/settings.json
-$geminiEntry = [ordered]@{ type = 'http'; url = $Url }
-Write-Step '- gemini-cli'
-Merge-JsonServer 'gemini-cli' (Join-Path $userHome '.gemini\settings.json') 'mcpServers' $geminiEntry
-
-# ---------- Codex: append [mcp_servers.<name>] to ~/.codex/config.toml (incremental append only)
-$codexFile = Join-Path $userHome '.codex\config.toml'
-Write-Step '- codex'
-if (Test-Path $codexFile) {
-  $codexText = [System.IO.File]::ReadAllText($codexFile, [System.Text.Encoding]::UTF8)
-  $section = "[mcp_servers.$ServerName]"
-  if ($Remove) {
-    if ($codexText -match "(?m)^\[mcp_servers\.$([regex]::Escape($ServerName))\]") {
-      $bak = Backup $codexFile
-      $clean = [regex]::Replace($codexText, "(?m)^\[mcp_servers\.$([regex]::Escape($ServerName))\][^\r\n]*(\r?\n(?!\[).*)*(\r?\n)?", '')
-      [System.IO.File]::WriteAllText($codexFile, $clean, $utf8NoBom)
-      Write-Step "  codex: removed '$ServerName' section from $codexFile (backup: $bak)"
-    } else {
-      Write-Step "  codex: '$ServerName' section not present in $codexFile"
-    }
-  } elseif ($codexText -match "(?m)^\[mcp_servers\.$([regex]::Escape($ServerName))\]") {
-    Write-Step "  codex: '$ServerName' section already present ($codexFile unchanged)"
-  } else {
-    $bak = Backup $codexFile
-    $block = "`n[mcp_servers.$ServerName]`ntype = `"streamable-http`"`nurl = `"$Url`"`n"
-    [System.IO.File]::WriteAllText($codexFile, $codexText.TrimEnd() + $block, $utf8NoBom)
-    Write-Step "  codex: appended '$ServerName' section to $codexFile (backup: $bak)"
-  }
-} else {
-  Write-Step "  codex: not installed ($codexFile missing, skipped)"
+$local = Join-Path (Split-Path -Parent $PSScriptRoot) 'lib/cli.js'
+if (Test-Path $local) {
+  & node $local @setupArgs
+  exit $LASTEXITCODE
 }
 
-# ---------- zcode: mcp.servers in ~/.zcode/cli/config.json
-$zcodeEntry = [ordered]@{ enabled = $true; type = 'remote'; url = $Url }
-Write-Step '- zcode'
-Merge-JsonServer 'zcode' (Join-Path $userHome '.zcode\cli\config.json') 'mcp.servers' $zcodeEntry
-Sync-Skill 'zcode' (Join-Path $userHome ".zcode\skills\$ServerName")
-
-# ---------- skills: cross-agent standard location + each agent's private dir
-$skillDirs = @(
-  (Join-Path $userHome ".agents\skills\$ServerName"),   # cross-agent standard
-  (Join-Path $userHome ".minimax\skills\$ServerName"),
-  (Join-Path $userHome ".config\opencode\skills\$ServerName"),
-  (Join-Path $userHome ".kimi-code\skills\$ServerName"),
-  (Join-Path $userHome ".gemini\skills\$ServerName"),
-  (Join-Path $userHome ".codex\skills\$ServerName"),
-  (Join-Path $userHome ".zcode\skills\$ServerName"),
-  (Join-Path $userHome ".claude\skills\$ServerName")    # config is manual; skill still useful
-)
-foreach ($dir in $skillDirs) { Sync-Skill 'skill' $dir }
-
-Write-Step 'done. Manual targets (see agents/README.md): Claude Code (project .mcp.json), DSH (cordis.patch.yml).'
-Write-Step 'Restart agent sessions to pick up the new MCP server.'
+throw "agent-comm-hub is not installed and $local does not exist. Install it (`npm i -g agent-comm-hub`) or run `pnpm run build` in a checkout, then use `agent-comm-hub setup`."