bus-agent 2.3.0

package/.env.coco

@@ -0,0 +1,11 @@
+# CoCo Bus Agent Configuration
+# Generated by CoCo Config Wizard
+
+# Your agent name on the bus
+COCO_AGENT=agent
+
+# Path to the CoCo bus directory
+COCO_BUS_DIR=E:\_system\.openclaw\workspace\repos\mcp-coco\.bus
+
+# CoCo CLI path (for coco-cli.js)
+COCO_CLI=E:\_system\.openclaw\workspace\repos\mcp-coco\coco-cli.js

package/AGENTS.md

@@ -0,0 +1,37 @@
+# MCP CoCo — AGENTS.md
+
+## Identity
+
+MCP CoCo is a bridge agent that connects OpenClaw and Hermes Agent. It lives in the workspace at `mcp-coco/`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `index.js` | Entry point — stdio server or daemon |
+| `lib/mcp.js` | MCP protocol handler + tool definitions |
+| `lib/hermes.js` | Hermes Agent CLI integration |
+| `lib/daemon.js` | Background process + health management |
+| `bin/cli.js` | CLI entry point (`bus-agent` command) |
+| `scripts/install.ps1` | Windows Scheduled Task installer |
+| `README.md` | User-facing docs |
+
+## Tools Provided
+
+- **`ask_hermes`** — Talk to Hermes. Supports multi-turn via `session_key`.
+- **`hermes_send`** — Send messages through Hermes to chat platforms.
+- **`hermes_channels`** — List available Hermes channels.
+- **`coco_health`** — Check bridge + Hermes health.
+
+## Operational Notes
+
+- Daemon mode writes PID to `.coco-daemon.pid`
+- Hermes session keys stored in `.sessions/` directory
+- Logs go to `coco-daemon.log` in daemon mode
+- Daemon auto-starts Hermes MCP backend (`hermes mcp serve --accept-hooks`)
+
+## Related
+
+- [MCP CoCo README](./README.md)
+- [MCP Protocol Spec](https://modelcontextprotocol.io)
+- [Hermes Agent](https://github.com/NousResearch/hermes-agent)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClewCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,370 @@
+# MCP CoCo
+
+**Universal Agent Communication Hub** — Connect any AI agent to any other.
+
+[![GitHub](https://img.shields.io/badge/GitHub-ClewCode%2Fmcp--coco-blue)](https://github.com/ClewCode/mcp-coco)
+
+MCP CoCo is a **message bus** for AI agents. It supports both the [MCP Protocol](https://modelcontextprotocol.io) (Model Context Protocol) and direct file-based access. Agents such as OpenClaw, Hermes, Claude Desktop, Cursor, OpenCode, and Claude Code CLI can all connect and communicate through a shared bus.
+
+```
+          ┌─────────────────────────────┐
+OpenClaw  │                             │  Hermes Agent
+     ────▶│    MCP CoCo (Agent Bus)     │◀────
+Claude    │                             │  Cursor
+     ────▶│  40+ tools / CLI / SDKs     │◀────
+OpenCode  │                             │  Claude Code CLI
+     ────▶│  Scheduler / Orchestrator   │◀────
+          └─────────────────────────────┘
+```
+
+---
+
+## Features
+
+### Agent Profiles & Discovery
+
+- **Rich Profiles** — Each agent carries metadata: model info (provider, name, context window), capabilities, tags, operational status, version, connection endpoints.
+- **Auto-Discovery** — When a new agent registers, the bus broadcasts a `joined` event to all connected agents. The new agent receives a welcome message via DM.
+- **Search & Filter** — Query agents by name, capability, model, tag, or status. Supports text search across descriptions and capabilities.
+- **Stale Detection** — Agents that miss heartbeats for 5 minutes are automatically marked offline.
+
+### Messaging
+
+- **Direct Messages** — Send private messages between any two agents.
+- **Broadcast** — Send a message to every agent on the bus.
+- **Channels** — Group chat rooms for multi-agent conversations.
+- **Long-Poll** — `message_wait` blocks until a new message arrives (configurable timeout, up to 60s).
+- **Filtered Inbox** — Retrieve messages from specific senders or after a given cursor.
+
+### CLI (coco-cli.js)
+
+```
+node coco-cli.js agents [--online] [--capability X] [--tag Y] [--model Z] [--status S]
+node coco-cli.js profile [agent]
+node coco-cli.js profile edit --status busy --description "..."
+node coco-cli.js search <query>
+node coco-cli.js status
+node coco-cli.js subscribe <channel>
+node coco-cli.js channel list|create <name>|join|send|history
+node coco-cli.js inbox [agent] [--from X] [--unread]
+node coco-cli.js events [since]
+node coco-cli.js watch [agent]
+node coco-cli.js doctor [--quick] [--fix]
+node coco-cli.js tunnel server|client|sync|ssh [options]
+node coco-cli.js backup [--list|--restore|--diff|--cleanup]
+```
+
+### Scheduler
+
+- **Cron Expressions** — Schedule recurring messages using standard cron syntax: `0 9 * * 1-5` sends to a channel or agent every weekday at 09:00.
+- **One-Shot Scheduling** — Specify an ISO timestamp (`at`) for single-delivery messages. The job is automatically disabled after firing.
+- **Timezone Support** — Each job can specify its own IANA timezone (e.g., `Asia/Bangkok`).
+
+### Auto-Reply Rules
+
+- **Pattern Matching** — Define rules that automatically forward, reply, or broadcast when a message matches criteria (by sender, text content, regex, or metadata fields).
+- **Message Transformation** — Use templates with `{message}`, `{from}`, `{channel}` variables.
+- **Loop Protection** — Each rule has a configurable `max_loops` limit to prevent infinite chains.
+
+### Agent Orchestrator
+
+- **Multi-Step Workflows** — Define a pipeline of agents connected in sequence. Output from step N becomes input to step N+1 via variable substitution.
+- **Variable Chaining** — `{input}` → agent A stores result as `{review_result}` → agent B receives `{review_result}`.
+- **Per-Step Timeout** — Individual timeout per agent step; failed steps are reported without blocking the caller indefinitely.
+
+### Webhook Gateway
+
+| Endpoint | Purpose |
+|----------|---------|
+| `POST /webhook/github/:channel` | GitHub push, pull request, issue, comment events |
+| `POST /webhook/github-actions/:channel` | GitHub Actions CI workflow status |
+| `POST /webhook/gitlab/:channel` | GitLab push, merge request events |
+| `POST /webhook/slack/:channel` | Slack messages |
+| `POST /webhook/telegram/:channel` | Telegram bot updates |
+| `POST /hook/:channel` | Generic JSON webhook |
+| `POST /api/send` | Direct API: `{"to": "agent", "message": "..."}` |
+| `GET /health` | Health check |
+| `GET /api/channels` | List registered channels |
+| `GET /api/agents` | List agents on the bus |
+
+### External Bridges
+
+A bridge module (`bridge.js`) provides a template for two-way communication between the bus and external platforms. Supports Slack, Discord, and custom generic bridges via HTTP listener. Channel mapping externalizes bus channels to platform-specific channels.
+
+### Client SDKs
+
+- **Python** — `clients/coco_client.py` provides `CoCoClient` with methods for registration, messaging, and channel operations.
+- **TypeScript** — `clients/coco-client.ts` provides the same interface for Node.js environments.
+
+### Config Wizard
+
+```
+node setup.js              # Interactive wizard
+node setup.js --quick      # Quick setup with defaults
+node setup.js list         # Display config examples
+```
+
+Generates `.mcp.json` configuration files for OpenCode, Claude Code, and Cursor, along with environment files (`.env.coco`) and shell aliases (`coco-aliases.sh`).
+
+### OpenClaw Native Integration
+
+The `coco-tool.js` wrapper provides direct file-based access to the bus without requiring an MCP transport layer:
+
+```bash
+node coco-tool.js agent_register '{"name":"agent","capabilities":["chat","code"]}'
+node coco-tool.js agent_search '{"query":"code"}'
+node coco-tool.js message_send '{"from":"agent","to":"hermes","message":"Hello"}'
+node coco-tool.js workflow_run '{"workflow_id":"review-and-deploy","input":"..."}'
+```
+
+### Bus Doctor
+
+Diagnostics and health checking for the CoCo bus. Verifies bus directory integrity, agent registry validity, orphaned agents, stale PID files, message inbox sizes, channel consistency, schedule/rule/workflow validity, and event log integrity.
+
+```bash
+node doctor.js                    # Full diagnostic report
+node doctor.js --quick            # Summary only
+node doctor.js --fix              # Auto-fix minor issues (missing dirs, stale PIDs, corrupted files)
+node doctor.js --report           # Save report to .bus/diagnostic-report.json
+node doctor.js --watch            # Watch mode (check every 30s)
+
+# Via CLI
+node coco-cli.js doctor --fix
+```
+
+18 checks are performed:
+- Bus directory existence & permissions
+- Required subdirectories (messages, channels, events)
+- Agent registry — profiles, missing fields, stale agents (>24h)
+- Orphaned agents (registered but never active, >7 days)
+- Message inbox sizes & file integrity
+- Channel metadata & log file integrity
+- Schedule file validity
+- Auto-reply rule validity
+- Workflow definition validity
+- Disk usage
+- Stale PID files
+- Event log integrity
+
+### CoCo Tunnel
+
+Cross-machine bus proxy. Expose a local CoCo bus to a remote machine (or vice versa) via HTTP REST, with optional authentication and sync.
+
+```bash
+# Server mode (receiving end)
+node tunnel.js server --port 9090 --secret mytoken
+
+# Client mode (sending end — pushes local agents & messages)
+node tunnel.js client --host 192.168.1.100 --port 9090 --secret mytoken
+
+# Bidirectional sync (merge agents both ways)
+node tunnel.js sync --remote http://192.168.1.100:9090 --interval 5000
+
+# SSH tunnel helper — prints port-forwarding instructions
+node tunnel.js ssh --remote user@server.example.com
+
+# Via CLI
+node coco-cli.js tunnel server --port 9090 --secret mytoken
+```
+
+**Endpoints (server):**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Server status + agent count |
+| GET | `/bus/agents` | List bus agents |
+| GET | `/bus/file/:path` | Read a bus file |
+| POST | `/bus/send` | Send message to bus |
+| POST | `/bus/write` | Write a bus file |
+| POST | `/bus/register` | Register an agent remotely |
+
+### Backup & Restore
+
+Gzip-compressed backup of the entire `.bus/` directory with checksum verification. Supports restore, diff, auto-backup, and cleanup.
+
+```bash
+node backup.js                         # Create timestamped backup in .backups/
+node backup.js --out mybackup.coco     # Custom output path
+node backup.js --list                  # List available backups
+node backup.js --info <file>           # Show backup metadata & contents
+node backup.js --restore <file>        # Restore bus from backup (auto-creates pre-restore backup)
+node backup.js --diff <file>           # Compare backup with current bus state
+node backup.js --cleanup 30            # Remove backups older than 30 days
+node backup.js --auto                  # Backup only if changes detected
+node backup.js --watch 60              # Auto-backup every 60 minutes
+
+# Via CLI
+node coco-cli.js backup --list
+```
+
+---
+
+## Quick Start
+
+```bash
+# Via npm (recommended)
+npm install -g bus-agent
+npx bus-agent
+
+# Or from source:
+git clone https://github.com/ClewCode/mcp-coco.git
+cd mcp-coco
+
+# MCP mode (for any MCP client)
+node index.js
+
+# CLI mode (for scripts / terminal agents)
+node coco-cli.js status
+node coco-cli.js agents
+node coco-cli.js send hermes "Hello"
+
+# Webhook gateway (optional)
+node webhook-gateway.js 8080
+```
+
+### For MCP Agents
+
+Add the following to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "coco": {
+      "command": "node",
+      "args": ["/path/to/mcp-coco/index.js"]
+    }
+  }
+}
+```
+
+Or use `node setup.js` to generate configuration automatically.
+
+### Environment Variable
+
+```bash
+# Set your agent identity
+export COCO_AGENT=opencode
+# Windows (PowerShell)
+$env:COCO_AGENT = "opencode"
+```
+
+---
+
+## Architecture
+
+```
+                    ┌───────────────────────┐
+                    │   HTTP :8080          │
+                    │  Webhook Gateway      │
+                    └──────┬────────────────┘
+                           │
+┌──────────┐     ┌────────┴────────────────────────┐     ┌──────────┐
+│ OpenClaw │────▶│   MCP CoCo (Agent Bus)          │◀────│  Hermes  │
+│  (skill) │     │                                  │     │  Agent   │
+├──────────┤     │  .bus/agents.json               │     ├──────────┤
+│  Claude  │────▶│  .bus/messages/                 │◀────│  Cursor  │
+│  Code    │     │  .bus/channels/                  │     │          │
+├──────────┤     │  .bus/events/                    │     ├──────────┤
+│ OpenCode │────▶│  .bus/schedule.json              │◀────│  CLI     │
+│  (clew)  │     └────────┬─────────────────────────┘     │  agents  │
+└──────────┘              │                                └──────────┘
+                           │\
+                           │
+          ┌────────────────┴────────────────────┐\
+          │  Utility Layer                      │\
+          │  doctor.js — Diagnostics & Auto-Fix │\
+          │  tunnel.js — Cross-machine Proxy    │\
+          │  backup.js — Backup, Restore & Diff │\
+          └─────────────────────────────────────┘
+```
+
+All bus state is stored as plain JSON files on disk. No database or external service required.
+
+---
+
+## Data Layout
+
+```
+.bus/
+  agents.json              # Agent registry with profiles
+  messages/
+    <agent_name>/          # Per-agent inbox (JSON message files)
+    <agent_name>_outbox/   # Sent messages archive
+  channels/
+    <id>.json              # Channel metadata
+    <id>/log/              # Channel message history
+  events/
+    YYYY-MM-DD.jsonl       # System events log (JSONL format)
+  schedule.json            # Scheduled jobs
+  auto-reply-rules.json    # Auto-reply rules
+  workflows.json            # Workflow definitions
+  memory/
+    <agent>/               # Per-agent memories
+      memories.jsonl       # Append-only memory log (JSONL)
+      index.json           # TF-IDF inverted index
+      vectors.json         # Vector embeddings (when provider configured)
+      config.json          # Embedding provider config
+```
+
+---
+
+## Tools Reference
+
+The MCP server exposes 43 tools across 9 categories:
+
+| Category | Count | Tools |
+|----------|-------|-------|
+| Agent Registry | 7 | `agent_register`, `agent_update_profile`, `agent_get_profile`, `agent_list`, `agent_search`, `agent_heartbeat`, `agent_set_status` |
+| Messages | 5 | `message_send`, `message_broadcast`, `message_fetch`, `message_wait`, `message_delete` |
+| Channels | 5 | `channel_create`, `channel_join`, `channel_leave`, `channel_send`, `channel_history` |
+| System Events | 2 | `system_get_events`, `system_wait_for_event` |
+| Scheduler | 3 | `scheduler_add`, `scheduler_remove`, `scheduler_list` |
+| Auto-Reply | 3 | `auto_reply_add`, `auto_reply_remove`, `auto_reply_list` |
+| Workflows | 4 | `workflow_create`, `workflow_run`, `workflow_remove`, `workflow_list` |
+| Memory | 10 | `memory_store`, `memory_search`, `memory_recall`, `memory_list`, `memory_forget`, `memory_stats`, `memory_archive`, `memory_clear`, `memory_configure`, `memory_rebuild` |
+| Utilities | 4 | `coco_health`, `ask_hermes`, `hermes_send`, `hermes_channels` |
+
+## Memory Layer
+
+Agent memory system with dual-mode search:
+
+- **Vector search (ANN)** — Cosine similarity via Ollama (nomic-embed-text, 768-dim), OpenAI, or custom endpoint
+- **TF-IDF keyword search** — Built-in scoring with recency boost, zero external deps
+
+**Storage:** Append-only JSONL per agent in `.bus/memory/{agent}/`
+
+| Feature | Description |
+|---------|-------------|
+| Namespaces | Categorize memories (preferences, system, archive, etc.) |
+| TTL | Auto-expire memories after a set duration |
+| Archive | Move old inbox messages into memory store |
+| Rebuild | Regenerate all vector embeddings from stored content |
+| Pluggable | Switch between keyword, Ollama, OpenAI, or custom |
+
+```bash
+coco memory store andul "Jonus likes clean architecture" --key architecture-pref --namespace preferences
+coco memory search andul "architecture layers" --limit 5
+coco memory configure --provider ollama --endpoint http://localhost:11434 --model nomic-embed-text
+coco memory rebuild andul
+coco memory archive andul --max-age-days 7
+```
+
+## Utility Tools
+
+Three standalone (also integrated into `coco-cli.js`) tools augment the bus:
+
+| Tool | File | Purpose |
+|------|------|---------|
+| Doctor | `doctor.js` / `lib/doctor.js` | Diagnostics, health checks, auto-fix |
+| Tunnel | `tunnel.js` / `lib/tunnel.js` | Cross-machine bus proxy & sync |
+| Backup | `backup.js` / `lib/backup.js` | Compressed backup, restore, diff |
+
+Full tool schemas are available via MCP `tools/list` or by running `node coco-cli.js help`.
+
+---
+
+## Related
+
+- [MCP Protocol](https://modelcontextprotocol.io) — Model Context Protocol specification
+- [Hermes Agent](https://github.com/ClewCode/hermes-agent) — MCP agent for OpenClaw
+- [Clew Code](https://github.com/jonusdx/clew-code) — Multi-provider AI coding agent