agent-comm-hub 0.1.6

package/agents/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: agent-comm-hub
+description:
+  Real-time two-way communication with other AI agents connected to the local
+  agent-comm-hub. Use when the user mentions another agent, the hub, group
+  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.
+---
+
+# agent-comm-hub usage
+
+A local hub (`agent-comm-hub` on 127.0.0.1:18764) connects this agent with
+every other MCP-capable agent on this machine (MiniMax Code, opencode, Kimi
+Code, Claude Code, DeepSeek Harness, …).
+
+**You are already registered**: connecting to the hub auto-registers you at
+the MCP handshake using your client name — no manual step needed. Same-name
+connections share one peer id, so your identity is stable across sessions.
+Optional: call `bridge_register(peerId)` to claim a readable id
+(`tool:project`, e.g. `claude-code:myproject`; errors when taken).
+
+## Tools
+
+- `bridge_chat(to, message)` — send a chat message to a peer; `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`), auto-routed back to the original
+  sender.
+- `bridge_wait(from?, timeoutMs?)` — long-poll for the next message (default
+  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).
+
+## When to use
+
+1. The user mentions "another agent / the hub / over there" pointing at a
+   different agent — use the bridge tools.
+2. **Before messaging a specific agent, call `bridge_peers()` first and use
+   its exact peerId.** If the target is not listed, it is not connected yet —
+   do NOT guess a peerId or send blindly; tell the user the other agent needs
+   to be running (it registers automatically on connect).
+3. Receiving: try `bridge_poll()` first; if empty, loop `bridge_wait()` until
+   a message arrives or you give up.
+4. On receiving a `task` (content is `{prompt, context?, deliverable?}`):
+   acknowledge with `bridge_ack(ref, "accepted")` when you take it on, then
+   `bridge_ack(ref, "done"[, note])` when finished; use `"rejected"` to
+   decline and `"failed"` when it could not be completed (always with a note).
+5. Unsure whether the peer is online: check `bridge_peers()` first.
+
+## Notes
+
+- Messages travel on loopback only (127.0.0.1:18764); never put credentials
+  in bridge messages.
+- A timeout is not a failure: `bridge_wait` returning `{type:"timeout"}` just
+  means nothing arrived — try again.
+- Cadence: use 10–30 s short polls when the peer is active; check
+  `bridge_peers()` when unsure.

package/agents/claude-code/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agent-hub": {
+      "type": "http",
+      "url": "http://127.0.0.1:18764/mcp"
+    }
+  }
+}

package/agents/codex/config.toml

@@ -0,0 +1,3 @@
+[mcp_servers.agent-hub]
+type = "streamable-http"
+url = "http://127.0.0.1:18764/mcp"

package/agents/dsh/cordis.patch.yml

@@ -0,0 +1,7 @@
+- insert:
+    - id: agent-comm-hub
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: agent-hub
+        transport: streamable-http
+        url: http://127.0.0.1:18764/mcp

package/agents/gemini-cli/settings.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agent-hub": {
+      "type": "http",
+      "url": "http://127.0.0.1:18764/mcp"
+    }
+  }
+}

package/agents/install-all.ps1

@@ -0,0 +1,177 @@
+<#
+.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.
+
+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)
+
+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
+
+.EXAMPLE
+powershell -ExecutionPolicy Bypass -File install-all.ps1
+powershell -ExecutionPolicy Bypass -File install-all.ps1 -Remove
+#>
+param(
+  [string]$Url = 'http://127.0.0.1:18764/mcp',
+  [string]$ServerName = 'agent-hub',
+  [switch]$Remove
+)
+
+$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 }
+    $servers = $doc.$sectionName
+    if ($null -eq $servers) {
+      # Incremental: create only the missing section, keep the rest untouched.
+      $servers = [ordered]@{}
+      $doc | Add-Member -NotePropertyName $sectionName -NotePropertyValue $servers -Force
+    }
+    $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)"
+  }
+}
+
+if ($Remove) { Write-Step 'uninstalling from all agents...' } else { Write-Step "syncing '$ServerName' -> $Url to all agents..." }
+
+# ---------- 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
+}
+Sync-Skill 'mcode' (Join-Path $userHome '.minimax\skills\agent-comm-hub')
+
+# ---------- 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
+Sync-Skill 'opencode' (Join-Path $userHome '.config\opencode\skills\agent-comm-hub')
+
+# ---------- 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
+Sync-Skill 'kimi-code' (Join-Path $userHome '.kimi-code\skills\agent-comm-hub')
+
+# ---------- 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
+Sync-Skill 'gemini-cli' (Join-Path $userHome '.gemini\skills\agent-comm-hub')
+
+# ---------- 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)"
+}
+
+# ---------- 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 ".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.'

package/agents/kimi-code/mcp-entry.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "agent-hub": {
+      "transport": "http",
+      "url": "http://127.0.0.1:18764/mcp",
+      "startupTimeoutMs": 30000,
+      "toolTimeoutMs": 120000
+    }
+  }
+}

package/agents/minimax-code/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: agent-comm-hub
+description:
+  Real-time two-way communication with other AI agents connected to the local
+  agent-comm-hub. Use when the user mentions another agent, the hub, group
+  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.
+---
+
+# agent-comm-hub usage
+
+A local hub (`agent-comm-hub` on 127.0.0.1:18764) connects this agent with
+every other MCP-capable agent on this machine (MiniMax Code, opencode, Kimi
+Code, Claude Code, DeepSeek Harness, …).
+
+**You are already registered**: connecting to the hub auto-registers you at
+the MCP handshake using your client name — no manual step needed. Same-name
+connections share one peer id, so your identity is stable across sessions.
+Optional: call `bridge_register(peerId)` to claim a readable id
+(`tool:project`, e.g. `claude-code:myproject`; errors when taken).
+
+## Tools
+
+- `bridge_chat(to, message)` — send a chat message to a peer; `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`), auto-routed back to the original
+  sender.
+- `bridge_wait(from?, timeoutMs?)` — long-poll for the next message (default
+  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).
+
+## When to use
+
+1. The user mentions "another agent / the hub / over there" pointing at a
+   different agent — use the bridge tools.
+2. **Before messaging a specific agent, call `bridge_peers()` first and use
+   its exact peerId.** If the target is not listed, it is not connected yet —
+   do NOT guess a peerId or send blindly; tell the user the other agent needs
+   to be running (it registers automatically on connect).
+3. Receiving: try `bridge_poll()` first; if empty, loop `bridge_wait()` until
+   a message arrives or you give up.
+4. On receiving a `task` (content is `{prompt, context?, deliverable?}`):
+   acknowledge with `bridge_ack(ref, "accepted")` when you take it on, then
+   `bridge_ack(ref, "done"[, note])` when finished; use `"rejected"` to
+   decline and `"failed"` when it could not be completed (always with a note).
+5. Unsure whether the peer is online: check `bridge_peers()` first.
+
+## Notes
+
+- Messages travel on loopback only (127.0.0.1:18764); never put credentials
+  in bridge messages.
+- A timeout is not a failure: `bridge_wait` returning `{type:"timeout"}` just
+  means nothing arrived — try again.
+- Cadence: use 10–30 s short polls when the peer is active; check
+  `bridge_peers()` when unsure.

package/agents/minimax-code/install-mcode.ps1

@@ -0,0 +1,121 @@
+<#
+.SYNOPSIS
+Install the agent-comm-hub client into MiniMax Code (mcode): register the hub
+MCP endpoint and install the hub skill. Run as the same user that runs mcode.
+
+.DESCRIPTION
+Writes the agent-hub MCP server into BOTH config files:
+  - ~/.minimax/mcp.json          — read by the mcode CLI runtime (connections)
+  - ~/.minimax/mcp/mcp.json      — the MiniMax Code desktop app config
+Both are backed up before touching. Files are written as UTF-8 WITHOUT BOM
+(Node's JSON.parse rejects a BOM). Idempotent. Use -Remove to uninstall.
+
+The hub must be running first: `npx agent-comm-hub` (default port 18764).
+
+.PARAMETER Url
+Hub MCP endpoint URL. Default http://127.0.0.1:18764/mcp.
+
+.PARAMETER ServerName
+Key of the mcp.json entries. Default agent-hub.
+
+.PARAMETER Remove
+Uninstall: remove the entries and the skill directory.
+
+.EXAMPLE
+powershell -ExecutionPolicy Bypass -File install-mcode.ps1
+#>
+param(
+  [string]$Url = 'http://127.0.0.1:18764/mcp',
+  [string]$ServerName = 'agent-hub',
+  [switch]$Remove
+)
+
+$ErrorActionPreference = 'Stop'
+$userHome = $env:USERPROFILE
+$minimaxDir = Join-Path $userHome '.minimax'
+$mcpTargets = @(
+  (Join-Path $minimaxDir 'mcp.json'),
+  (Join-Path $minimaxDir 'mcp\mcp.json')
+)
+$skillDir = Join-Path $minimaxDir 'skills\agent-comm-hub'
+$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+
+function Write-Step($text) { Write-Host "[agent-comm-hub] $text" -ForegroundColor Cyan }
+
+function Read-JsonFile($path) {
+  if (-not (Test-Path $path)) { return $null }
+  try { return [System.IO.File]::ReadAllText($path, [System.Text.Encoding]::UTF8) | ConvertFrom-Json }
+  catch { return $null }
+}
+
+function Write-JsonFile($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 20), $utf8NoBom)
+}
+
+if (-not (Test-Path $minimaxDir)) {
+  throw "mcode config home not found: $minimaxDir — is mcode installed?"
+}
+
+$entry = [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. Call bridge_register(peerId) first, then bridge_chat / bridge_task / bridge_ack / bridge_wait / bridge_poll / bridge_status / bridge_peers / bridge_history.'
+}
+
+foreach ($mcpFile in $mcpTargets) {
+  $mcp = Read-JsonFile $mcpFile
+  if ($null -eq $mcp -or $null -eq $mcp.mcpServers) {
+    $mcp = [pscustomobject]@{ mcpServers = [ordered]@{} }
+  }
+  if ($Remove) {
+    if ($mcp.mcpServers.PSObject.Properties.Name -contains $ServerName) {
+      $mcp.mcpServers.PSObject.Properties.Remove($ServerName)
+      $stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
+      Copy-Item $mcpFile "$mcpFile.bak-$stamp" -Force -ErrorAction SilentlyContinue
+      Write-JsonFile $mcpFile $mcp
+      Write-Step "removed '$ServerName' from $mcpFile (backup: $(Split-Path $mcpFile -Leaf).bak-$stamp)"
+    } else {
+      Write-Step "'$ServerName' not present in $mcpFile — nothing to remove"
+    }
+  } else {
+    $changed = $true
+    if ($mcp.mcpServers.PSObject.Properties.Name -contains $ServerName) {
+      $existing = $mcp.mcpServers.$ServerName
+      $changed = ($existing.url -ne $Url) -or (-not $existing.enabled) -or ($existing.description -ne $entry.description)
+    }
+    if ($changed) {
+      $stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
+      Copy-Item $mcpFile "$mcpFile.bak-$stamp" -Force -ErrorAction SilentlyContinue
+      $mcp.mcpServers | Add-Member -NotePropertyName $ServerName -NotePropertyValue $entry -Force
+      Write-JsonFile $mcpFile $mcp
+      Write-Step "registered '$ServerName' -> $Url in $mcpFile (backup: $(Split-Path $mcpFile -Leaf).bak-$stamp)"
+    } else {
+      Write-Step "'$ServerName' already registered and enabled in $mcpFile — unchanged"
+    }
+  }
+}
+
+$skillSrc = Join-Path $PSScriptRoot 'SKILL.md'
+if ($Remove) {
+  if (Test-Path $skillDir) {
+    Remove-Item $skillDir -Recurse -Force
+    Write-Step "removed skill $skillDir"
+  } else {
+    Write-Step "skill $skillDir not present — nothing to remove"
+  }
+} elseif (Test-Path $skillSrc) {
+  New-Item -ItemType Directory -Path $skillDir -Force | Out-Null
+  Copy-Item $skillSrc (Join-Path $skillDir 'SKILL.md') -Force
+  Write-Step "installed skill -> $skillDir\SKILL.md"
+}
+
+if (-not $Remove) {
+  Write-Step 'done. Restart your mcode session, then verify with:'
+  Write-Step '  mcode exec "你有哪些 bridge 工具？先 bridge_register 注册一下"'
+  Write-Step 'Make sure the hub is running: npx agent-comm-hub'
+}

package/agents/minimax-code/mcp-entry.json

@@ -0,0 +1,10 @@
+{
+  "agent-hub": {
+    "url": "http://127.0.0.1:18764/mcp",
+    "type": "streamable-http",
+    "enabled": true,
+    "configured": true,
+    "timeout": 120000,
+    "description": "agent-comm-hub: talk to every other agent connected to the hub. Call bridge_register(peerId) first, then bridge_chat / bridge_task / bridge_ack / bridge_wait / bridge_poll / bridge_status / bridge_peers / bridge_history."
+  }
+}

package/agents/opencode/opencode.json

@@ -0,0 +1,9 @@
+{
+  "mcp": {
+    "agent-hub": {
+      "type": "remote",
+      "url": "http://127.0.0.1:18764/mcp",
+      "enabled": true
+    }
+  }
+}