opencode-agent-hub 1.3.1__tar.gz → 1.3.3__tar.gz

opencode_agent_hub-1.3.3/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: opencode-agent-hub
+Version: 1.3.3
+Summary: Multi-agent coordination daemon and tools for OpenCode
+Project-URL: Homepage, https://github.com/xnoto/opencode-agent-hub
+Project-URL: Repository, https://github.com/xnoto/opencode-agent-hub
+Project-URL: Issues, https://github.com/xnoto/opencode-agent-hub/issues
+Author: xnoto
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,coordination,daemon,mcp,opencode
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Requires-Dist: requests>=2.28.0
+Requires-Dist: watchdog>=3.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: types-requests>=2.28.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# opencode-agent-hub
+
+Multi-agent coordination for [OpenCode](https://github.com/anomalyco/opencode). Lets multiple AI agents in separate OpenCode sessions talk to each other.
+
+> **Warning**: This enables autonomous agent-to-agent communication which triggers LLM API calls. Use at your own risk. Consider enabling [rate limiting](#rate-limiting) to control costs.
+
+## Demo
+
+https://github.com/user-attachments/assets/b591f1d2-01d7-4408-bf60-67eb7a8fbf0c
+
+## How It Works
+
+- The **daemon** starts an OpenCode hub server (`opencode serve --port 4096`) and discovers sessions by polling OpenCode's shared SQLite database
+- A **coordinator** session facilitates introductions between new agents, then steps back
+- Agents communicate by writing JSON files to `~/.agent-hub/messages/` via the [agent-hub-mcp](https://github.com/gilbarbara/agent-hub-mcp) tools
+- The daemon watches for new message files, looks up the target agent's session, and injects the message via `prompt_async` — agents don't poll, they get woken up
+
+## Known Limitations
+
+- **Injected messages not visible in TUI** — agent-to-agent messages work but users can't see them in the conversation. Upstream issue: [opencode#8564](https://github.com/sst/opencode/issues/8564). Use `agent-hub-watch` to monitor.
+- **TUI spinner after response** — the TUI may briefly show "thinking" after an agent finishes responding to an injection. Visual only, no extra token consumption.
+- **Orientation may trigger security heuristics** — some models (particularly Claude) may flag orientation messages as prompt injections. The agent still has MCP tools and can collaborate, just without orientation context.
+
+## Prerequisites
+
+[agent-hub-mcp](https://github.com/gilbarbara/agent-hub-mcp) must be configured in OpenCode. The daemon will refuse to start without it.
+
+Find your OpenCode config location with `opencode debug paths`, then add to `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "agent-hub": {
+      "type": "local",
+      "command": ["npx", "-y", "agent-hub-mcp@latest"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Verify with `opencode mcp list` (should show `agent-hub connected`).
+
+## Quickstart
+
+```bash
+git clone https://github.com/xnoto/opencode-agent-hub
+cd opencode-agent-hub
+
+# Terminal 1: start the daemon
+uv run agent-hub-daemon
+
+# Terminal 2: monitor activity
+uv run agent-hub-watch
+```
+
+## Installation
+
+### Homebrew (macOS)
+
+```bash
+brew install xnoto/opencode-agent-hub/opencode-agent-hub
+```
+
+### Linux Packages
+
+**Debian / Ubuntu:**
+
+```bash
+curl -fsSL https://xnoto.github.io/opencode-agent-hub/KEY.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/xnoto.gpg
+echo "deb [signed-by=/etc/apt/keyrings/xnoto.gpg] https://xnoto.github.io/opencode-agent-hub/apt ./" | sudo tee /etc/apt/sources.list.d/xnoto.list
+sudo apt update && sudo apt install opencode-agent-hub
+```
+
+**Fedora / RHEL:**
+
+```bash
+sudo curl -o /etc/yum.repos.d/xnoto.repo https://xnoto.github.io/opencode-agent-hub/xnoto.repo
+sudo dnf install opencode-agent-hub
+```
+
+**Arch Linux (AUR):**
+
+```bash
+yay -S opencode-agent-hub
+```
+
+See [GitHub Releases](https://github.com/xnoto/opencode-agent-hub/releases) for direct .deb/.rpm downloads.
+
+### uv / pipx (PyPI)
+
+```bash
+uv tool install opencode-agent-hub
+# or
+pipx install opencode-agent-hub
+```
+
+### From source
+
+```bash
+git clone https://github.com/xnoto/opencode-agent-hub
+cd opencode-agent-hub
+uv sync
+```
+
+## Running as a Service
+
+### macOS (Homebrew)
+
+```bash
+brew services start opencode-agent-hub
+tail -f ~/Library/Logs/agent-hub-daemon.log
+brew services stop opencode-agent-hub
+```
+
+### Linux (systemd)
+
+```bash
+agent-hub-daemon --install-service     # install + start
+journalctl --user -u agent-hub-daemon -f
+systemctl --user stop agent-hub-daemon
+agent-hub-daemon --uninstall-service   # remove
+```
+
+If installed via RPM/DEB, a system-wide service file is included — enable with `systemctl --user enable --now agent-hub-daemon`.
+
+## Configuration
+
+Config file: `~/.config/agent-hub-daemon/config.json` (all fields optional). Environment variables override config file values.
+
+```json
+{
+  "opencode_port": 4096,
+  "log_level": "INFO",
+  "rate_limit": {
+    "enabled": false,
+    "max_messages": 10,
+    "window_seconds": 300,
+    "cooldown_seconds": 0
+  },
+  "coordinator": {
+    "enabled": true,
+    "directory": "~/.agent-hub/coordinator",
+    "agents_md": ""
+  },
+  "gc": { "message_ttl_seconds": 3600, "agent_stale_seconds": 3600, "interval_seconds": 60 },
+  "session": { "poll_seconds": 5, "cache_ttl": 10 },
+  "injection": { "workers": 4, "retries": 3, "timeout": 5 },
+  "metrics_interval": 30
+}
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENCODE_PORT` | `4096` | Hub server port |
+| `AGENT_HUB_DAEMON_LOG_LEVEL` | `INFO` | Log level |
+| `AGENT_HUB_MESSAGE_TTL` | `3600` | Message TTL (seconds) |
+| `AGENT_HUB_AGENT_STALE` | `3600` | Agent stale threshold (seconds) |
+| `AGENT_HUB_GC_INTERVAL` | `60` | GC interval (seconds) |
+| `AGENT_HUB_SESSION_POLL` | `5` | Session poll interval (seconds) |
+| `AGENT_HUB_SESSION_CACHE_TTL` | `10` | Session cache TTL (seconds) |
+| `AGENT_HUB_INJECTION_WORKERS` | `4` | Injection worker threads |
+| `AGENT_HUB_INJECTION_RETRIES` | `3` | Injection retry attempts |
+| `AGENT_HUB_INJECTION_TIMEOUT` | `5` | Injection timeout (seconds) |
+| `AGENT_HUB_METRICS_INTERVAL` | `30` | Metrics write interval (seconds) |
+
+### Rate Limiting
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AGENT_HUB_RATE_LIMIT` | `false` | Enable rate limiting |
+| `AGENT_HUB_RATE_LIMIT_MAX` | `10` | Max messages per agent per window |
+| `AGENT_HUB_RATE_LIMIT_WINDOW` | `300` | Window size (seconds) |
+| `AGENT_HUB_RATE_LIMIT_COOLDOWN` | `0` | Min seconds between messages |
+
+### Coordinator
+
+The coordinator is a dedicated OpenCode session that introduces agents to each other. It starts non-blocking and uses the same message pipeline as any other agent.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AGENT_HUB_COORDINATOR` | `true` | Enable coordinator |
+| `AGENT_HUB_COORDINATOR_DIR` | `~/.agent-hub/coordinator` | Coordinator working directory |
+| `AGENT_HUB_COORDINATOR_PRESERVE_LOCAL_AGENTS_MD` | `false` | Keep existing AGENTS.md on restart |
+| `AGENT_HUB_COORDINATOR_READY_TIMEOUT` | `20` | Bootstrap ready timeout (seconds) |
+| `AGENT_HUB_COORDINATOR_STRICT_READY` | `false` | Require exact `READY` acknowledgment |
+| `AGENT_HUB_COORDINATOR_BOOTSTRAP_REQUIRED` | `false` | Fail startup if bootstrap times out |
+| `AGENT_HUB_COORDINATOR_AGENTS_MD` | (auto-detect) | Custom AGENTS.md path |
+
+The coordinator model is set in `~/.agent-hub/coordinator/opencode.json` (default: `opencode/minimax-m2.5-free`).
+
+Custom coordinator instructions are searched in order:
+1. `AGENT_HUB_COORDINATOR_AGENTS_MD` env var
+2. `~/.config/agent-hub-daemon/AGENTS.md` (or `COORDINATOR.md`)
+3. Package template (`contrib/coordinator/AGENTS.md`)
+4. `/usr/local/share/opencode-agent-hub/coordinator/AGENTS.md`
+5. Auto-generated minimal default
+
+## Message Format
+
+Messages are JSON files in `~/.agent-hub/messages/`:
+
+```json
+{
+  "from": "agent-id",
+  "to": "target-agent-id",
+  "type": "task|question|context|completion|error",
+  "content": "Message content",
+  "priority": "normal|urgent|high|low",
+  "threadId": "auto-generated-or-provided",
+  "timestamp": 1234567890000
+}
+```
+
+## Directory Structure
+
+```
+~/.agent-hub/
+├── agents/                 # Registered agent files
+├── messages/               # Pending messages
+│   └── archive/            # Processed messages
+├── threads/                # Conversation threads
+├── metrics.prom            # Prometheus metrics
+├── oriented_sessions.json  # Orientation cache
+└── session_agents.json     # Session-to-agent mapping
+
+~/.config/agent-hub-daemon/
+└── config.json             # Optional config
+```
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run ruff check .
+uv run ruff format .
+uv run mypy src/
+uv run pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for integration testing and architecture details.
+
+## Acknowledgments
+
+- **[OpenCode](https://github.com/anomalyco/opencode)** by [anomalyco](https://github.com/anomalyco)
+- **[agent-hub-mcp](https://github.com/gilbarbara/agent-hub-mcp)** by [@gilbarbara](https://github.com/gilbarbara)
+
+## License
+
+MIT - See [LICENSE](LICENSE) for details.

opencode_agent_hub-1.3.3/README.md

@@ -0,0 +1,252 @@
+# opencode-agent-hub
+
+Multi-agent coordination for [OpenCode](https://github.com/anomalyco/opencode). Lets multiple AI agents in separate OpenCode sessions talk to each other.
+
+> **Warning**: This enables autonomous agent-to-agent communication which triggers LLM API calls. Use at your own risk. Consider enabling [rate limiting](#rate-limiting) to control costs.
+
+## Demo
+
+https://github.com/user-attachments/assets/b591f1d2-01d7-4408-bf60-67eb7a8fbf0c
+
+## How It Works
+
+- The **daemon** starts an OpenCode hub server (`opencode serve --port 4096`) and discovers sessions by polling OpenCode's shared SQLite database
+- A **coordinator** session facilitates introductions between new agents, then steps back
+- Agents communicate by writing JSON files to `~/.agent-hub/messages/` via the [agent-hub-mcp](https://github.com/gilbarbara/agent-hub-mcp) tools
+- The daemon watches for new message files, looks up the target agent's session, and injects the message via `prompt_async` — agents don't poll, they get woken up
+
+## Known Limitations
+
+- **Injected messages not visible in TUI** — agent-to-agent messages work but users can't see them in the conversation. Upstream issue: [opencode#8564](https://github.com/sst/opencode/issues/8564). Use `agent-hub-watch` to monitor.
+- **TUI spinner after response** — the TUI may briefly show "thinking" after an agent finishes responding to an injection. Visual only, no extra token consumption.
+- **Orientation may trigger security heuristics** — some models (particularly Claude) may flag orientation messages as prompt injections. The agent still has MCP tools and can collaborate, just without orientation context.
+
+## Prerequisites
+
+[agent-hub-mcp](https://github.com/gilbarbara/agent-hub-mcp) must be configured in OpenCode. The daemon will refuse to start without it.
+
+Find your OpenCode config location with `opencode debug paths`, then add to `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "agent-hub": {
+      "type": "local",
+      "command": ["npx", "-y", "agent-hub-mcp@latest"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Verify with `opencode mcp list` (should show `agent-hub connected`).
+
+## Quickstart
+
+```bash
+git clone https://github.com/xnoto/opencode-agent-hub
+cd opencode-agent-hub
+
+# Terminal 1: start the daemon
+uv run agent-hub-daemon
+
+# Terminal 2: monitor activity
+uv run agent-hub-watch
+```
+
+## Installation
+
+### Homebrew (macOS)
+
+```bash
+brew install xnoto/opencode-agent-hub/opencode-agent-hub
+```
+
+### Linux Packages
+
+**Debian / Ubuntu:**
+
+```bash
+curl -fsSL https://xnoto.github.io/opencode-agent-hub/KEY.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/xnoto.gpg
+echo "deb [signed-by=/etc/apt/keyrings/xnoto.gpg] https://xnoto.github.io/opencode-agent-hub/apt ./" | sudo tee /etc/apt/sources.list.d/xnoto.list
+sudo apt update && sudo apt install opencode-agent-hub
+```
+
+**Fedora / RHEL:**
+
+```bash
+sudo curl -o /etc/yum.repos.d/xnoto.repo https://xnoto.github.io/opencode-agent-hub/xnoto.repo
+sudo dnf install opencode-agent-hub
+```
+
+**Arch Linux (AUR):**
+
+```bash
+yay -S opencode-agent-hub
+```
+
+See [GitHub Releases](https://github.com/xnoto/opencode-agent-hub/releases) for direct .deb/.rpm downloads.
+
+### uv / pipx (PyPI)
+
+```bash
+uv tool install opencode-agent-hub
+# or
+pipx install opencode-agent-hub
+```
+
+### From source
+
+```bash
+git clone https://github.com/xnoto/opencode-agent-hub
+cd opencode-agent-hub
+uv sync
+```
+
+## Running as a Service
+
+### macOS (Homebrew)
+
+```bash
+brew services start opencode-agent-hub
+tail -f ~/Library/Logs/agent-hub-daemon.log
+brew services stop opencode-agent-hub
+```
+
+### Linux (systemd)
+
+```bash
+agent-hub-daemon --install-service     # install + start
+journalctl --user -u agent-hub-daemon -f
+systemctl --user stop agent-hub-daemon
+agent-hub-daemon --uninstall-service   # remove
+```
+
+If installed via RPM/DEB, a system-wide service file is included — enable with `systemctl --user enable --now agent-hub-daemon`.
+
+## Configuration
+
+Config file: `~/.config/agent-hub-daemon/config.json` (all fields optional). Environment variables override config file values.
+
+```json
+{
+  "opencode_port": 4096,
+  "log_level": "INFO",
+  "rate_limit": {
+    "enabled": false,
+    "max_messages": 10,
+    "window_seconds": 300,
+    "cooldown_seconds": 0
+  },
+  "coordinator": {
+    "enabled": true,
+    "directory": "~/.agent-hub/coordinator",
+    "agents_md": ""
+  },
+  "gc": { "message_ttl_seconds": 3600, "agent_stale_seconds": 3600, "interval_seconds": 60 },
+  "session": { "poll_seconds": 5, "cache_ttl": 10 },
+  "injection": { "workers": 4, "retries": 3, "timeout": 5 },
+  "metrics_interval": 30
+}
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENCODE_PORT` | `4096` | Hub server port |
+| `AGENT_HUB_DAEMON_LOG_LEVEL` | `INFO` | Log level |
+| `AGENT_HUB_MESSAGE_TTL` | `3600` | Message TTL (seconds) |
+| `AGENT_HUB_AGENT_STALE` | `3600` | Agent stale threshold (seconds) |
+| `AGENT_HUB_GC_INTERVAL` | `60` | GC interval (seconds) |
+| `AGENT_HUB_SESSION_POLL` | `5` | Session poll interval (seconds) |
+| `AGENT_HUB_SESSION_CACHE_TTL` | `10` | Session cache TTL (seconds) |
+| `AGENT_HUB_INJECTION_WORKERS` | `4` | Injection worker threads |
+| `AGENT_HUB_INJECTION_RETRIES` | `3` | Injection retry attempts |
+| `AGENT_HUB_INJECTION_TIMEOUT` | `5` | Injection timeout (seconds) |
+| `AGENT_HUB_METRICS_INTERVAL` | `30` | Metrics write interval (seconds) |
+
+### Rate Limiting
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AGENT_HUB_RATE_LIMIT` | `false` | Enable rate limiting |
+| `AGENT_HUB_RATE_LIMIT_MAX` | `10` | Max messages per agent per window |
+| `AGENT_HUB_RATE_LIMIT_WINDOW` | `300` | Window size (seconds) |
+| `AGENT_HUB_RATE_LIMIT_COOLDOWN` | `0` | Min seconds between messages |
+
+### Coordinator
+
+The coordinator is a dedicated OpenCode session that introduces agents to each other. It starts non-blocking and uses the same message pipeline as any other agent.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AGENT_HUB_COORDINATOR` | `true` | Enable coordinator |
+| `AGENT_HUB_COORDINATOR_DIR` | `~/.agent-hub/coordinator` | Coordinator working directory |
+| `AGENT_HUB_COORDINATOR_PRESERVE_LOCAL_AGENTS_MD` | `false` | Keep existing AGENTS.md on restart |
+| `AGENT_HUB_COORDINATOR_READY_TIMEOUT` | `20` | Bootstrap ready timeout (seconds) |
+| `AGENT_HUB_COORDINATOR_STRICT_READY` | `false` | Require exact `READY` acknowledgment |
+| `AGENT_HUB_COORDINATOR_BOOTSTRAP_REQUIRED` | `false` | Fail startup if bootstrap times out |
+| `AGENT_HUB_COORDINATOR_AGENTS_MD` | (auto-detect) | Custom AGENTS.md path |
+
+The coordinator model is set in `~/.agent-hub/coordinator/opencode.json` (default: `opencode/minimax-m2.5-free`).
+
+Custom coordinator instructions are searched in order:
+1. `AGENT_HUB_COORDINATOR_AGENTS_MD` env var
+2. `~/.config/agent-hub-daemon/AGENTS.md` (or `COORDINATOR.md`)
+3. Package template (`contrib/coordinator/AGENTS.md`)
+4. `/usr/local/share/opencode-agent-hub/coordinator/AGENTS.md`
+5. Auto-generated minimal default
+
+## Message Format
+
+Messages are JSON files in `~/.agent-hub/messages/`:
+
+```json
+{
+  "from": "agent-id",
+  "to": "target-agent-id",
+  "type": "task|question|context|completion|error",
+  "content": "Message content",
+  "priority": "normal|urgent|high|low",
+  "threadId": "auto-generated-or-provided",
+  "timestamp": 1234567890000
+}
+```
+
+## Directory Structure
+
+```
+~/.agent-hub/
+├── agents/                 # Registered agent files
+├── messages/               # Pending messages
+│   └── archive/            # Processed messages
+├── threads/                # Conversation threads
+├── metrics.prom            # Prometheus metrics
+├── oriented_sessions.json  # Orientation cache
+└── session_agents.json     # Session-to-agent mapping
+
+~/.config/agent-hub-daemon/
+└── config.json             # Optional config
+```
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run ruff check .
+uv run ruff format .
+uv run mypy src/
+uv run pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for integration testing and architecture details.
+
+## Acknowledgments
+
+- **[OpenCode](https://github.com/anomalyco/opencode)** by [anomalyco](https://github.com/anomalyco)
+- **[agent-hub-mcp](https://github.com/gilbarbara/agent-hub-mcp)** by [@gilbarbara](https://github.com/gilbarbara)
+
+## License
+
+MIT - See [LICENSE](LICENSE) for details.

{opencode_agent_hub-1.3.1 → opencode_agent_hub-1.3.3}/contrib/coordinator/AGENTS.md

@@ -6,6 +6,12 @@ You are the **coordinator** for a multi-agent system. Your job is to facilitate
 
 Your value is making agents aware of each other. Once they're talking directly, **stay out of it**.
 
+## Session Mode
+
+- This session is non-interactive.
+- Never ask the human user anything.
+- Never use the `question` tool.
+
 ## Your Responsibilities
 
 1. **Capture tasks** - When notified of a new agent, ask what they're working on (ONE message)

{opencode_agent_hub-1.3.1 → opencode_agent_hub-1.3.3}/contrib/coordinator/opencode.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://opencode.ai/config.json",
+  "model": "opencode/minimax-m2.5-free",
   "permission": [
     {"permission": "agent-hub_*", "pattern": "*", "action": "allow"},
     {"permission": "question", "pattern": "agent-hub*", "action": "allow"},

{opencode_agent_hub-1.3.1 → opencode_agent_hub-1.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "opencode-agent-hub"
-version = "1.3.1"
+version = "1.3.3"
 description = "Multi-agent coordination daemon and tools for OpenCode"
 readme = "README.md"
 license = "MIT"

{opencode_agent_hub-1.3.1 → opencode_agent_hub-1.3.3}/src/opencode_agent_hub/__init__.py

@@ -8,4 +8,4 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("opencode-agent-hub")
 except PackageNotFoundError:  # pragma: no cover - fallback for dev
-    __version__ = "1.3.1"
+    __version__ = "1.3.3"