bus-agent 2.3.0

package/SKILL.md

@@ -0,0 +1,314 @@
+# MCP CoCo — Universal Agent Communication Hub
+
+## Overview
+
+MCP CoCo is an **Agent Communication Hub** — an MCP server that lets **any MCP-compatible agent** talk to any other.
+
+```
+OpenClaw (Andul) ──┐
+                    ├──▶ MCP CoCo (Agent Bus) ◀──▶ Claude Desktop
+Hermes Agent ──────┘                               Cursor
+                        │                          Any MCP agent
+                        ├─ message_send(to, msg)
+                        ├─ message_wait(timeout)
+                        ├─ channel_send(channel, msg)
+                        └─ agent_list()
+```
+
+## Location
+
+```
+E:\_system\.openclaw\workspace\repos\mcp-coco\
+GitHub: https://github.com/ClewCode/mcp-coco
+```
+
+## Running
+
+```bash
+# Stdio mode (via mcporter)
+mcporter add coco --stdio "node E:\_system\.openclaw\workspace\repos\mcp-coco\index.js"
+
+# Daemon mode
+node E:\_system\.openclaw\workspace\repos\mcp-coco\index.js --daemon
+
+# Health check
+node E:\_system\.openclaw\workspace\repos\mcp-coco\index.js --health
+```
+
+## Tools (43 total)
+
+### Hermes Bridge (legacy)
+
+| Tool | Description |
+|------|-------------|
+| `ask_hermes(prompt, session_key?)` | Talk to Hermes Agent (multi-turn) |
+| `hermes_send(target, message)` | Send via Hermes to chat platform |
+| `hermes_channels(platform?)` | List Hermes channels |
+| `coco_health()` | Health check (CLI + gateway) |
+
+### Agent Bus (new)
+
+| Tool | Description |
+|------|-------------|
+| `agent_register(name, description?, metadata?)` | Register your agent on the bus |
+| `agent_list(online_only?)` | List all registered agents |
+| `agent_heartbeat(name)` | Ping to show online status |
+| `message_send(from, to, message, metadata?)` | Send DM to another agent |
+| `message_broadcast(from, message)` | Send to ALL agents |
+| `message_fetch(agent_name, limit?)` | Read your inbox |
+| `message_wait(agent_name, timeout_ms?)` | Long-poll for new messages (up to 60s) |
+| `channel_create(channel_id, topic?, created_by?)` | Create a shared channel |
+| `channel_join(channel_id, agent_name)` | Join a channel |
+| `channel_send(channel_id, from, message)` | Send to channel (all members) |
+| `channel_history(channel_id, limit?)` | Read channel log |
+
+### Memory Tools
+
+Agent memory with TF-IDF keyword search (built-in) and optional vector search via Ollama/OpenAI.
+
+| Tool | Description |
+|------|-------------|
+| `memory_store` | Store a memory. Auto-embeds if provider configured. |
+| `memory_search` | Search — vector ANN with TF-IDF fallback |
+| `memory_recall` | Recall by ID or key |
+| `memory_list` | List with namespace filter, pagination |
+| `memory_forget` | Delete by ID |
+| `memory_stats` | Count, namespaces, vectors, size |
+| `memory_archive` | Move old inbox messages into memory |
+| `memory_clear` | Clear all or by namespace |
+| `memory_configure` | Set provider (keyword/ollama/openai/custom) |
+| `memory_rebuild` | Regenerate vector embeddings |
+
+**Dual-mode search:** Vector (cosine similarity) → TF-IDF fallback. Stored in `.bus/memory/{agent}/` as JSONL + vectors.json.
+
+```bash
+coco memory store andul "content" --key k --namespace preferences
+coco memory search andul "query" --limit 5
+coco memory configure --provider ollama --endpoint http://localhost:11434
+coco memory rebuild andul
+```
+
+## Communication Patterns
+
+### 1. Register → Send → Fetch (async)
+
+```bash
+# Agent A registers
+mcporter call coco.agent_register name="alice"
+
+# Agent A sends to B
+mcporter call coco.message_send from="alice" to="bob" message="Hello!"
+
+# Agent B fetches later
+mcporter call coco.message_fetch agent_name="bob"
+```
+
+### 2. Register → Wait (long-poll, real-time)
+
+```bash
+# Agent B waits for messages (blocks up to 30s)
+mcporter call coco.message_wait agent_name="bob" timeout_ms=60000
+
+# Agent A sends → B gets the message immediately
+mcporter call coco.message_send from="alice" to="bob" message="Ping!"
+```
+
+### 3. Channel (multi-agent chat)
+
+```bash
+# Create
+mcporter call coco.channel_create channel_id="dev" topic="Dev chat"
+
+# Join
+mcporter call coco.channel_join channel_id="dev" agent_name="alice"
+
+# Chat (sent to all members)
+mcporter call coco.channel_send channel_id="dev" from="alice" message="Hey team!"
+```
+
+## Webhook Gateway (port 8080)
+
+HTTP server that receives external webhooks (GitHub, GitLab, Slack, generic) and posts them to bus channels.
+
+```bash
+node webhook-gateway.js 8080
+```
+
+**Endpoints:**
+- `POST /webhook/github/:channel` — GitHub push/PR events
+- `POST /webhook/gitlab/:channel` — GitLab events
+- `POST /webhook/slack/:channel` — Slack messages
+- `POST /hook/:channel` — Any JSON `{"text":"..."}` payload
+- `GET /health` — Health check
+
+**Example (GitHub → dev channel):**
+```bash
+curl -X POST http://localhost:8080/webhook/github/dev \
+  -H "Content-Type: application/json" \
+  -d '{"ref":"refs/heads/main","repository":{"name":"mcp-coco"},"pusher":{"name":"jonus"},"commits":[{"message":"feat: new feature"}]}'
+```
+
+## Hermes Auto-Forwarder
+
+Any DM sent to agent `hermes` on the bus is automatically forwarded to Hermes CLI (`ask_hermes`) and the reply is posted back to the sender's inbox. No manual `ask_hermes` call needed.
+
+```
+andul ──DM──▶ hermes → Hermes CLI → reply DM back to andul
+```
+
+Run:
+```bash
+node hermes-forwarder.js
+```
+
+## Scheduled Tasks (Windows)
+
+All CoCo services can run as Windows Scheduled Tasks (auto-start on boot, auto-restart on crash):
+
+| Task | Purpose | Port |
+|------|---------|------|
+| `MCP_CoCo_Daemon` | CoCo MCP server (agent bus) | stdio |
+| `MCP_CoCo_Webhook` | Webhook Gateway | :8080 |
+| `MCP_CoCo_HermesFwd` | Hermes Auto-Forwarder | — |
+
+Install:
+```powershell
+powershell -File scripts\install.ps1
+```
+
+## CLI Access for OpenCode & Terminal Agents
+
+CLI agents (OpenCode, Claude Code, shell scripts) can access the message bus **directly** — no MCP server needed. Just read/write JSON files in `.bus/`.
+
+```bash
+# Set your agent name (optional, defaults to $USER)
+export COCO_AGENT=opencode
+
+# List agents
+node coco-cli.js agents
+
+# Check inbox
+node coco-cli.js inbox
+
+# Send a message
+node coco-cli.js send andul "Hello from OpenCode!"
+
+# Reply to a specific message
+node coco-cli.js reply <message-id> "Thanks!"
+
+# Watch for new messages (poll every 2s)
+node coco-cli.js watch
+
+# Or use the shorter wrapper
+node coco.js agents
+node coco.js inbox
+node coco.js send andul "Hey!"
+```
+
+## One-liner for OpenCode
+
+Set this in your shell profile:
+```bash
+# ~/.bashrc or ~/.zshrc or $PROFILE (PowerShell)
+export COCO_AGENT=opencode
+alias coco='node E:\_system\.openclaw\workspace\repos\mcp-coco\coco.js'
+```
+
+Then just:
+```bash
+coco agents
+coco inbox
+coco send andul "Hello world!"
+```
+
+When you run `coco send`, it auto-registers your agent on the bus. Other agents (Andul, Hermes) will see you online and can message you back.
+
+## Windows Notes
+
+- Uses `cmd.exe /c` wrapper for prompt_toolkit TTY crash fix
+- All commands wrapped with `2>&1` (session_id on stderr)
+- Timeout: 180s per hermes call, 60s max for message_wait
+- Bus data stored in `.bus/` directory (agents, messages, channels)
+- ANSI output stripped automatically
+
+## Integration with Hermes
+
+MCP CoCo auto-registers itself as `coco` agent. Hermes can connect via:
+```bash
+mcporter add hermes --stdio "hermes mcp serve --accept-hooks"
+```
+
+Then OpenClaw and Hermes can DM through CoCo's message bus — no need for direct subprocess calls.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `"sent": true` but no message received | Recipient hasn't registered yet — register first, then fetch |
+| `message_wait` times out | No messages in 30s — increase `timeout_ms` or send a ping |
+| Agent not showing in list | Call `agent_register` first |
+| Channel not found on join | Check `channel_id` is exact (case-sensitive) |
+| `Error: Exit code 2` | Hermes stderr quirk — retry, usually transient |
+
+## Bus Data
+
+```
+.bus/
+├── agents.json        # Agent registry
+├── messages/
+│   ├── <agent>/       # Per-agent inbox
+│   └── <agent>_outbox/ # Sender outbox
+├── channels/
+│   ├── <id>.json      # Channel metadata
+│   └── <id>/log/      # Channel messages
+└── memory/
+    └── <agent>/       # Per-agent memories (JSONL + vectors.json + config.json)
+```
+
+All data is JSON. Back up `.bus/` to preserve conversations.
+
+## Utility Tools
+
+### Bus Doctor
+
+Diagnostics and health checks for the CoCo bus:
+
+```bash
+node doctor.js [--quick] [--fix] [--report] [--watch]
+# or via CLI
+node coco-cli.js doctor [--quick] [--fix]
+```
+
+Performs 18 checks: bus directory, permissions, agent registry (profiles, stale agents), orphaned agents, message integrity, channels, scheduler validity, auto-reply rules, workflows, disk usage, stale PIDs, event logs. With `--fix`, auto-creates missing directories, removes stale PID files, deletes corrupted messages.
+
+### CoCo Tunnel
+
+Cross-machine bus proxy. Expose your local bus to remote agents:
+
+```bash
+node tunnel.js server --port 9090 --secret ***
+node tunnel.js client --host <ip> --port 9090 --secret ***
+node tunnel.js sync --remote http://<ip>:9090
+node tunnel.js ssh --remote user@host
+# or via CLI
+node coco-cli.js tunnel server --port 9090 --secret ***
+```
+
+Server exposes HTTP endpoints: `/health`, `/bus/agents`, `/bus/send`, `/bus/register`. Client pushes local agents and recent messages at configurable interval. Sync mode merges agent registries bidirectionally.
+
+### Backup & Restore
+
+Gzip-compressed backup of the entire `.bus/` directory:
+
+```bash
+node backup.js                         # Create backup
+node backup.js --list                  # List backups
+node backup.js --restore <file>        # Restore (auto pre-backup first)
+node backup.js --diff <file>           # Compare with current state
+node backup.js --cleanup 30            # Remove old backups
+node backup.js --watch 60              # Auto-backup every 60 min
+# or via CLI
+node coco-cli.js backup --list
+```
+
+Backups stored in `.backups/` directory. Each backup includes checksum verification. Diff shows added/removed/modified files.

package/backup.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * CoCo Backup & Restore — Bus State Management CLI Wrapper
+ *
+ * Thin wrapper around lib/backup.js
+ * Usage: see --help
+ */
+const path = require('path');
+const { createBackup, restoreBackup, listBackups, backupInfo, diffBackup, cleanupBackups, autoBackup, watchMode } = require('./lib/backup');
+
+const BUS_DIR = path.join(__dirname, '.bus');
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+function help() {
+  console.log(`\n╔═══════════════════════════════════════════════╗\n║     CoCo — Backup & Restore                      ║\n╚═══════════════════════════════════════════════╝\n`);
+  console.log('Usage:');
+  console.log('  node backup.js                         Create backup (timestamped name)');
+  console.log('  node backup.js --out <file>            Create backup with custom path');
+  console.log('  node backup.js --list                  List available backups');
+  console.log('  node backup.js --info <file>           Show backup metadata');
+  console.log('  node backup.js --restore <file>        Restore bus from backup');
+  console.log('  node backup.js --diff <file>           Compare backup with current state');
+  console.log('  node backup.js --cleanup [days]        Remove backups older than N days');
+  console.log('  node backup.js --auto                  Backup only if changes detected');
+  console.log('  node backup.js --watch <minutes>       Auto-backup every N minutes\n');
+  console.log('Examples:');
+  console.log('  node backup.js');
+  console.log('  node backup.js --restore .backups/coco-bus-2026-06-24.coco');
+  console.log('  node backup.js --diff .backups/coco-bus-2026-06-24.coco');
+  console.log('  node backup.js --cleanup 30');
+  console.log('  node backup.js --watch 60\n');
+}
+
+function main() {
+  if (!cmd) { createBackup(BUS_DIR); return; }
+  if (cmd === '--help') { help(); return; }
+
+  try {
+    switch (cmd) {
+      case '--list': listBackups(BUS_DIR); break;
+      case '--info': backupInfo(path.resolve(args[1])); break;
+      case '--restore': restoreBackup(path.resolve(args[1]), BUS_DIR); break;
+      case '--diff': diffBackup(path.resolve(args[1]), BUS_DIR); break;
+      case '--cleanup': cleanupBackups(BUS_DIR, parseInt(args[1], 10) || 30); break;
+      case '--out': createBackup(BUS_DIR, path.resolve(args[1])); break;
+      case '--auto': autoBackup(BUS_DIR); break;
+      case '--watch': watchMode(BUS_DIR, parseInt(args[1], 10) || 30); break;
+      default: createBackup(BUS_DIR);
+    }
+  } catch (err) {
+    console.error('Error:', err.message);
+    process.exit(1);
+  }
+}
+
+main();

package/bin/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * MCP Bus CLI — command-line entry point
+ *
+ * Usage:
+ *   bus-agent                    # stdio MCP server
+ *   bus-agent --daemon           # start background daemon
+ *   bus-agent --health           # one-shot health check
+ *   bus-agent --help             # show help
+ */
+const path = require('path');
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+MCP Bus — MCP Bridge: OpenClaw ↔ Hermes Agent
+
+Usage:
+  bus-agent                    Run as stdio MCP server (for mcporter)
+  bus-agent --daemon           Start background daemon
+  bus-agent --health           Quick health check (exit 0 = ok)
+  bus-agent --help             Show this help
+
+Examples:
+  # Run as stdio server (connect via mcporter):
+  mcporter add coco --stdio "node path/to/index.js"
+
+  # Start as background daemon:
+  bus-agent --daemon
+
+  # Call from OpenClaw:
+  mcporter call coco.ask_hermes prompt="Hello Hermes"
+
+  # Check health:
+  bus-agent --health
+`);
+  process.exit(0);
+}
+
+require(path.join(__dirname, '..', 'index.js'));