merge: resolve conflict with main (keep fence markers + _find_shell)
This commit is contained in:
0xbyt4
commit
f967471758
36 changed files with 5037 additions and 293 deletions
63
README.md
63
README.md
|
|
@ -32,7 +32,7 @@ Built by [Nous Research](https://nousresearch.com). Under the hood, the same arc
|
|||
|
||||
## Quick Install
|
||||
|
||||
**Linux/macOS:**
|
||||
**Linux / macOS / WSL:**
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
|
||||
```
|
||||
|
|
@ -42,18 +42,25 @@ curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scri
|
|||
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
|
||||
```
|
||||
|
||||
**Windows (CMD):**
|
||||
```cmd
|
||||
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.cmd -o install.cmd && install.cmd && del install.cmd
|
||||
```
|
||||
|
||||
> **Windows note:** [Git for Windows](https://git-scm.com/download/win) is required. Hermes uses Git Bash internally for shell commands.
|
||||
|
||||
The installer will:
|
||||
- Install [uv](https://docs.astral.sh/uv/) (fast Python package manager) if not present
|
||||
- Install Python 3.11 via uv if not already available (no sudo needed)
|
||||
- Clone to `~/.hermes/hermes-agent` (with submodules: mini-swe-agent, tinker-atropos)
|
||||
- Create a virtual environment with Python 3.11
|
||||
- Install all dependencies and submodule packages
|
||||
- Symlink `hermes` into `~/.local/bin` so it works globally (no venv activation needed)
|
||||
- Set up the `hermes` command globally (no venv activation needed)
|
||||
- Run the interactive setup wizard
|
||||
|
||||
After installation, reload your shell and run:
|
||||
```bash
|
||||
source ~/.bashrc # or: source ~/.zshrc
|
||||
source ~/.bashrc # or: source ~/.zshrc (Windows: restart your terminal)
|
||||
hermes setup # Configure API keys (if you skipped during install)
|
||||
hermes # Start chatting!
|
||||
```
|
||||
|
|
@ -271,22 +278,30 @@ SLACK_ALLOWED_USERS=U01234ABCDE # Comma-separated Slack user IDs
|
|||
|
||||
### WhatsApp Setup
|
||||
|
||||
WhatsApp doesn't have a simple bot API like Telegram or Discord. Hermes includes a built-in bridge using [Baileys](https://github.com/WhiskeySockets/Baileys) that connects via WhatsApp Web. The agent links to your WhatsApp account and responds to incoming messages.
|
||||
WhatsApp doesn't have a simple bot API like Telegram or Discord. Hermes includes a built-in bridge using [Baileys](https://github.com/WhiskeySockets/Baileys) that connects via WhatsApp Web.
|
||||
|
||||
1. **Run the setup command:**
|
||||
**Two modes are supported:**
|
||||
|
||||
| Mode | How it works | Best for |
|
||||
|------|-------------|----------|
|
||||
| **Separate bot number** (recommended) | Dedicate a phone number to the bot. People message that number directly. | Clean UX, multiple users |
|
||||
| **Personal self-chat** | Use your own WhatsApp. You message yourself to talk to the agent. | Quick setup, single user |
|
||||
|
||||
**Setup:**
|
||||
|
||||
```bash
|
||||
hermes whatsapp
|
||||
```
|
||||
|
||||
This will:
|
||||
- Enable WhatsApp in your config
|
||||
- Ask for your phone number (for the allowlist)
|
||||
- Install bridge dependencies (Node.js required)
|
||||
- Display a QR code — scan it with your phone (WhatsApp → Settings → Linked Devices → Link a Device)
|
||||
- Exit automatically once paired
|
||||
The wizard will:
|
||||
1. Ask which mode you want
|
||||
2. For **bot mode**: guide you through getting a second number (WhatsApp Business app on a dual-SIM, Google Voice, or cheap prepaid SIM)
|
||||
3. Configure the allowlist
|
||||
4. Install bridge dependencies (Node.js required)
|
||||
5. Display a QR code — scan from WhatsApp (or WhatsApp Business) → Settings → Linked Devices → Link a Device
|
||||
6. Exit once paired
|
||||
|
||||
2. **Start the gateway:**
|
||||
**Start the gateway:**
|
||||
|
||||
```bash
|
||||
hermes gateway # Foreground
|
||||
|
|
@ -295,7 +310,7 @@ hermes gateway install # Or install as a system service (Linux)
|
|||
|
||||
The gateway starts the WhatsApp bridge automatically using the saved session.
|
||||
|
||||
> **Note:** WhatsApp Web sessions can disconnect if WhatsApp updates their protocol. The gateway reconnects automatically. If you see persistent failures, re-pair with `hermes whatsapp`. Agent responses are prefixed with "⚕ Hermes Agent" so you can distinguish them from your own messages in self-chat.
|
||||
> **Note:** WhatsApp Web sessions can disconnect if WhatsApp updates their protocol. The gateway reconnects automatically. If you see persistent failures, re-pair with `hermes whatsapp`. Agent responses are prefixed with "⚕ Hermes Agent" for easy identification.
|
||||
|
||||
See [docs/messaging.md](docs/messaging.md) for advanced WhatsApp configuration.
|
||||
|
||||
|
|
@ -488,6 +503,23 @@ hermes tools
|
|||
|
||||
**Available toolsets:** `web`, `terminal`, `file`, `browser`, `vision`, `image_gen`, `moa`, `skills`, `tts`, `todo`, `memory`, `session_search`, `cronjob`, `code_execution`, `delegation`, `clarify`, and more.
|
||||
|
||||
### 🔌 MCP (Model Context Protocol)
|
||||
|
||||
Connect to any MCP-compatible server to extend Hermes with external tools. Just add servers to your config:
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
time:
|
||||
command: uvx
|
||||
args: ["mcp-server-time"]
|
||||
notion:
|
||||
url: https://mcp.notion.com/mcp
|
||||
```
|
||||
|
||||
Supports stdio and HTTP transports, auto-reconnection, and env var filtering. See [docs/mcp.md](docs/mcp.md) for details.
|
||||
|
||||
Install MCP support: `pip install hermes-agent[mcp]`
|
||||
|
||||
### 🖥️ Terminal & Process Management
|
||||
|
||||
The terminal tool can execute commands in different environments, with full background process management via the `process` tool:
|
||||
|
|
@ -1212,8 +1244,8 @@ brew install git
|
|||
brew install ripgrep node
|
||||
```
|
||||
|
||||
**Windows (WSL recommended):**
|
||||
Use the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) and follow the Ubuntu instructions above. Alternatively, use the PowerShell quick-install script at the top of this README.
|
||||
**Windows (native):**
|
||||
Hermes runs natively on Windows using [Git for Windows](https://git-scm.com/download/win) (which provides Git Bash for shell commands). Install Git for Windows first, then use the PowerShell or CMD quick-install command at the top of this README. WSL also works — follow the Ubuntu instructions above.
|
||||
|
||||
</details>
|
||||
|
||||
|
|
@ -1635,6 +1667,7 @@ All variables go in `~/.hermes/.env`. Run `hermes config set VAR value` to set t
|
|||
| `SLACK_ALLOWED_USERS` | Comma-separated Slack user IDs |
|
||||
| `SLACK_HOME_CHANNEL` | Default Slack channel for cron delivery |
|
||||
| `WHATSAPP_ENABLED` | Enable WhatsApp bridge (`true`/`false`) |
|
||||
| `WHATSAPP_MODE` | `bot` (separate number, recommended) or `self-chat` (message yourself) |
|
||||
| `WHATSAPP_ALLOWED_USERS` | Comma-separated phone numbers (with country code) |
|
||||
| `MESSAGING_CWD` | Working directory for terminal in messaging (default: ~) |
|
||||
| `GATEWAY_ALLOW_ALL_USERS` | Allow all users without allowlist (`true`/`false`, default: `false`) |
|
||||
|
|
|
|||
38
TODO.md
38
TODO.md
|
|
@ -63,33 +63,27 @@ Full Python plugin interface that goes beyond the current hook system.
|
|||
- `hermes plugin list|install|uninstall|create` CLI commands
|
||||
- Plugin discovery and validation on startup
|
||||
|
||||
### Phase 3: MCP support (industry standard)
|
||||
- MCP client that can connect to external MCP servers (stdio, SSE, HTTP)
|
||||
- This is the big one -- Codex, Cline, and OpenCode all support MCP
|
||||
- Allows Hermes to use any MCP-compatible tool server (hundreds exist)
|
||||
- Config: `mcp_servers` list in config.yaml with connection details
|
||||
- Each MCP server's tools get registered as a new toolset
|
||||
### Phase 3: MCP support (industry standard) ✅ DONE
|
||||
- ✅ MCP client that connects to external MCP servers (stdio + HTTP/StreamableHTTP)
|
||||
- ✅ Config: `mcp_servers` in config.yaml with connection details
|
||||
- ✅ Each MCP server's tools auto-registered as a dynamic toolset
|
||||
- Future: Resources, Prompts, Progress notifications, `hermes mcp` CLI command
|
||||
|
||||
---
|
||||
|
||||
## 6. MCP (Model Context Protocol) Support 🔗
|
||||
## 6. MCP (Model Context Protocol) Support 🔗 ✅ DONE
|
||||
|
||||
**Status:** Not started
|
||||
**Priority:** High -- this is becoming an industry standard
|
||||
**Status:** Implemented (PR #301)
|
||||
**Priority:** Complete
|
||||
|
||||
MCP is the protocol that Codex, Cline, and OpenCode all support for connecting to external tool servers. Supporting MCP would instantly give Hermes access to hundreds of community tool servers.
|
||||
Native MCP client support with stdio and HTTP/StreamableHTTP transports, auto-discovery, reconnection with exponential backoff, env var filtering, and credential stripping. See `docs/mcp.md` for full documentation.
|
||||
|
||||
**What other agents do:**
|
||||
- **Codex**: Full MCP integration with skill dependencies
|
||||
- **Cline**: `use_mcp_tool` / `access_mcp_resource` / `load_mcp_documentation` tools
|
||||
- **OpenCode**: MCP client support (stdio, SSE, StreamableHTTP transports), OAuth auth
|
||||
|
||||
**Our approach:**
|
||||
- Implement an MCP client that can connect to external MCP servers
|
||||
- Config: list of MCP servers in `~/.hermes/config.yaml` with transport type and connection details
|
||||
- Each MCP server's tools auto-registered as a dynamic toolset
|
||||
- Start with stdio transport (most common), then add SSE and HTTP
|
||||
- Could also be part of the Plugin system (#5, Phase 3) since MCP is essentially a plugin protocol
|
||||
**Still TODO:**
|
||||
- `hermes mcp` CLI subcommand (list/test/status)
|
||||
- `hermes tools` UI integration for MCP toolsets
|
||||
- MCP Resources and Prompts support
|
||||
- OAuth authentication for remote servers
|
||||
- Progress notifications for long-running tools
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -121,7 +115,7 @@ Automatic filesystem snapshots after each agent loop iteration so the user can r
|
|||
|
||||
### Tier 1: Next Up
|
||||
|
||||
1. MCP Support -- #6
|
||||
1. ~~MCP Support -- #6~~ ✅ Done (PR #301)
|
||||
|
||||
### Tier 2: Quality of Life
|
||||
|
||||
|
|
|
|||
|
|
@ -442,6 +442,41 @@ toolsets:
|
|||
# toolsets:
|
||||
# - safe
|
||||
|
||||
# =============================================================================
|
||||
# MCP (Model Context Protocol) Servers
|
||||
# =============================================================================
|
||||
# Connect to external MCP servers to add tools from the MCP ecosystem.
|
||||
# Each server's tools are automatically discovered and registered.
|
||||
# See docs/mcp.md for full documentation.
|
||||
#
|
||||
# Stdio servers (spawn a subprocess):
|
||||
# command: the executable to run
|
||||
# args: command-line arguments
|
||||
# env: environment variables (only these + safe defaults passed to subprocess)
|
||||
#
|
||||
# HTTP servers (connect to a URL):
|
||||
# url: the MCP server endpoint
|
||||
# headers: HTTP headers (e.g., for authentication)
|
||||
#
|
||||
# Optional per-server settings:
|
||||
# timeout: tool call timeout in seconds (default: 120)
|
||||
# connect_timeout: initial connection timeout (default: 60)
|
||||
#
|
||||
# mcp_servers:
|
||||
# time:
|
||||
# command: uvx
|
||||
# args: ["mcp-server-time"]
|
||||
# filesystem:
|
||||
# command: npx
|
||||
# args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
|
||||
# notion:
|
||||
# url: https://mcp.notion.com/mcp
|
||||
# github:
|
||||
# command: npx
|
||||
# args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
# env:
|
||||
# GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
|
||||
|
||||
# =============================================================================
|
||||
# Voice Transcription (Speech-to-Text)
|
||||
# =============================================================================
|
||||
|
|
|
|||
137
cli.py
137
cli.py
|
|
@ -386,6 +386,11 @@ def _run_cleanup():
|
|||
_cleanup_all_browsers()
|
||||
except Exception:
|
||||
pass
|
||||
try:
|
||||
from tools.mcp_tool import shutdown_mcp_servers
|
||||
shutdown_mcp_servers()
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
# ============================================================================
|
||||
# ASCII Art & Branding
|
||||
|
|
@ -685,6 +690,7 @@ COMMANDS = {
|
|||
"/cron": "Manage scheduled tasks (list, add, remove)",
|
||||
"/skills": "Search, install, inspect, or manage skills from online registries",
|
||||
"/platforms": "Show gateway/messaging platform status",
|
||||
"/reload-mcp": "Reload MCP servers from config.yaml",
|
||||
"/quit": "Exit the CLI (also: /exit, /q)",
|
||||
}
|
||||
|
||||
|
|
@ -847,7 +853,7 @@ class HermesCLI:
|
|||
or os.getenv("OPENAI_BASE_URL")
|
||||
or os.getenv("OPENROUTER_BASE_URL", CLI_CONFIG["model"]["base_url"])
|
||||
)
|
||||
self.api_key = api_key or os.getenv("OPENAI_API_KEY") or os.getenv("OPENROUTER_API_KEY")
|
||||
self.api_key = api_key or os.getenv("OPENROUTER_API_KEY") or os.getenv("OPENAI_API_KEY")
|
||||
self._nous_key_expires_at: Optional[str] = None
|
||||
self._nous_key_source: Optional[str] = None
|
||||
# Max turns priority: CLI arg > config file > env var > default
|
||||
|
|
@ -916,6 +922,15 @@ class HermesCLI:
|
|||
|
||||
# History file for persistent input recall across sessions
|
||||
self._history_file = Path.home() / ".hermes_history"
|
||||
self._last_invalidate: float = 0.0 # throttle UI repaints
|
||||
|
||||
def _invalidate(self, min_interval: float = 0.25) -> None:
|
||||
"""Throttled UI repaint — prevents terminal blinking on slow/SSH connections."""
|
||||
import time as _time
|
||||
now = _time.monotonic()
|
||||
if hasattr(self, "_app") and self._app and (now - self._last_invalidate) >= min_interval:
|
||||
self._last_invalidate = now
|
||||
self._app.invalidate()
|
||||
|
||||
def _ensure_runtime_credentials(self) -> bool:
|
||||
"""
|
||||
|
|
@ -1756,6 +1771,8 @@ class HermesCLI:
|
|||
self._manual_compress()
|
||||
elif cmd_lower == "/usage":
|
||||
self._show_usage()
|
||||
elif cmd_lower == "/reload-mcp":
|
||||
self._reload_mcp()
|
||||
else:
|
||||
# Check for skill slash commands (/gif-search, /axolotl, etc.)
|
||||
base_cmd = cmd_lower.split()[0]
|
||||
|
|
@ -1877,6 +1894,91 @@ class HermesCLI:
|
|||
for quiet_logger in ('tools', 'minisweagent', 'run_agent', 'trajectory_compressor', 'cron', 'hermes_cli'):
|
||||
logging.getLogger(quiet_logger).setLevel(logging.ERROR)
|
||||
|
||||
def _reload_mcp(self):
|
||||
"""Reload MCP servers: disconnect all, re-read config.yaml, reconnect.
|
||||
|
||||
After reconnecting, refreshes the agent's tool list so the model
|
||||
sees the updated tools on the next turn.
|
||||
"""
|
||||
try:
|
||||
from tools.mcp_tool import shutdown_mcp_servers, discover_mcp_tools, _load_mcp_config, _servers, _lock
|
||||
|
||||
# Capture old server names
|
||||
with _lock:
|
||||
old_servers = set(_servers.keys())
|
||||
|
||||
print("🔄 Reloading MCP servers...")
|
||||
|
||||
# Shutdown existing connections
|
||||
shutdown_mcp_servers()
|
||||
|
||||
# Reconnect (reads config.yaml fresh)
|
||||
new_tools = discover_mcp_tools()
|
||||
|
||||
# Compute what changed
|
||||
with _lock:
|
||||
connected_servers = set(_servers.keys())
|
||||
|
||||
added = connected_servers - old_servers
|
||||
removed = old_servers - connected_servers
|
||||
reconnected = connected_servers & old_servers
|
||||
|
||||
if reconnected:
|
||||
print(f" ♻️ Reconnected: {', '.join(sorted(reconnected))}")
|
||||
if added:
|
||||
print(f" ➕ Added: {', '.join(sorted(added))}")
|
||||
if removed:
|
||||
print(f" ➖ Removed: {', '.join(sorted(removed))}")
|
||||
if not connected_servers:
|
||||
print(" No MCP servers connected.")
|
||||
else:
|
||||
print(f" 🔧 {len(new_tools)} tool(s) available from {len(connected_servers)} server(s)")
|
||||
|
||||
# Refresh the agent's tool list so the model can call new tools
|
||||
if self.agent is not None:
|
||||
from model_tools import get_tool_definitions
|
||||
self.agent.tools = get_tool_definitions(
|
||||
enabled_toolsets=self.agent.enabled_toolsets
|
||||
if hasattr(self.agent, "enabled_toolsets") else None,
|
||||
quiet_mode=True,
|
||||
)
|
||||
self.agent.valid_tool_names = {
|
||||
tool["function"]["name"] for tool in self.agent.tools
|
||||
} if self.agent.tools else set()
|
||||
|
||||
# Inject a message at the END of conversation history so the
|
||||
# model knows tools changed. Appended after all existing
|
||||
# messages to preserve prompt-cache for the prefix.
|
||||
change_parts = []
|
||||
if added:
|
||||
change_parts.append(f"Added servers: {', '.join(sorted(added))}")
|
||||
if removed:
|
||||
change_parts.append(f"Removed servers: {', '.join(sorted(removed))}")
|
||||
if reconnected:
|
||||
change_parts.append(f"Reconnected servers: {', '.join(sorted(reconnected))}")
|
||||
tool_summary = f"{len(new_tools)} MCP tool(s) now available" if new_tools else "No MCP tools available"
|
||||
change_detail = ". ".join(change_parts) + ". " if change_parts else ""
|
||||
self.conversation_history.append({
|
||||
"role": "user",
|
||||
"content": f"[SYSTEM: MCP servers have been reloaded. {change_detail}{tool_summary}. The tool list for this conversation has been updated accordingly.]",
|
||||
})
|
||||
|
||||
# Persist session immediately so the session log reflects the
|
||||
# updated tools list (self.agent.tools was refreshed above).
|
||||
if self.agent is not None:
|
||||
try:
|
||||
self.agent._persist_session(
|
||||
self.conversation_history,
|
||||
self.conversation_history,
|
||||
)
|
||||
except Exception:
|
||||
pass # Best-effort
|
||||
|
||||
print(f" ✅ Agent updated — {len(self.agent.tools if self.agent else [])} tool(s) available")
|
||||
|
||||
except Exception as e:
|
||||
print(f" ❌ MCP reload failed: {e}")
|
||||
|
||||
def _clarify_callback(self, question, choices):
|
||||
"""
|
||||
Platform callback for the clarify tool. Called from the agent thread.
|
||||
|
|
@ -1903,8 +2005,7 @@ class HermesCLI:
|
|||
self._clarify_freetext = is_open_ended
|
||||
|
||||
# Trigger prompt_toolkit repaint from this (non-main) thread
|
||||
if hasattr(self, '_app') and self._app:
|
||||
self._app.invalidate()
|
||||
self._invalidate()
|
||||
|
||||
# Poll in 1-second ticks so the countdown refreshes in the UI.
|
||||
# Each tick triggers an invalidate() to repaint the hint line.
|
||||
|
|
@ -1918,15 +2019,13 @@ class HermesCLI:
|
|||
if remaining <= 0:
|
||||
break
|
||||
# Repaint so the countdown updates
|
||||
if hasattr(self, '_app') and self._app:
|
||||
self._app.invalidate()
|
||||
self._invalidate()
|
||||
|
||||
# Timed out — tear down the UI and let the agent decide
|
||||
self._clarify_state = None
|
||||
self._clarify_freetext = False
|
||||
self._clarify_deadline = 0
|
||||
if hasattr(self, '_app') and self._app:
|
||||
self._app.invalidate()
|
||||
self._invalidate()
|
||||
_cprint(f"\n{_DIM}(clarify timed out after {timeout}s — agent will decide){_RST}")
|
||||
return (
|
||||
"The user did not provide a response within the time limit. "
|
||||
|
|
@ -1951,16 +2050,14 @@ class HermesCLI:
|
|||
}
|
||||
self._sudo_deadline = _time.monotonic() + timeout
|
||||
|
||||
if hasattr(self, '_app') and self._app:
|
||||
self._app.invalidate()
|
||||
self._invalidate()
|
||||
|
||||
while True:
|
||||
try:
|
||||
result = response_queue.get(timeout=1)
|
||||
self._sudo_state = None
|
||||
self._sudo_deadline = 0
|
||||
if hasattr(self, '_app') and self._app:
|
||||
self._app.invalidate()
|
||||
self._invalidate()
|
||||
if result:
|
||||
_cprint(f"\n{_DIM} ✓ Password received (cached for session){_RST}")
|
||||
else:
|
||||
|
|
@ -1970,13 +2067,11 @@ class HermesCLI:
|
|||
remaining = self._sudo_deadline - _time.monotonic()
|
||||
if remaining <= 0:
|
||||
break
|
||||
if hasattr(self, '_app') and self._app:
|
||||
self._app.invalidate()
|
||||
self._invalidate()
|
||||
|
||||
self._sudo_state = None
|
||||
self._sudo_deadline = 0
|
||||
if hasattr(self, '_app') and self._app:
|
||||
self._app.invalidate()
|
||||
self._invalidate()
|
||||
_cprint(f"\n{_DIM} ⏱ Timeout — continuing without sudo{_RST}")
|
||||
return ""
|
||||
|
||||
|
|
@ -2002,28 +2097,24 @@ class HermesCLI:
|
|||
}
|
||||
self._approval_deadline = _time.monotonic() + timeout
|
||||
|
||||
if hasattr(self, '_app') and self._app:
|
||||
self._app.invalidate()
|
||||
self._invalidate()
|
||||
|
||||
while True:
|
||||
try:
|
||||
result = response_queue.get(timeout=1)
|
||||
self._approval_state = None
|
||||
self._approval_deadline = 0
|
||||
if hasattr(self, '_app') and self._app:
|
||||
self._app.invalidate()
|
||||
self._invalidate()
|
||||
return result
|
||||
except queue.Empty:
|
||||
remaining = self._approval_deadline - _time.monotonic()
|
||||
if remaining <= 0:
|
||||
break
|
||||
if hasattr(self, '_app') and self._app:
|
||||
self._app.invalidate()
|
||||
self._invalidate()
|
||||
|
||||
self._approval_state = None
|
||||
self._approval_deadline = 0
|
||||
if hasattr(self, '_app') and self._app:
|
||||
self._app.invalidate()
|
||||
self._invalidate()
|
||||
_cprint(f"\n{_DIM} ⏱ Timeout — denying command{_RST}")
|
||||
return "deny"
|
||||
|
||||
|
|
|
|||
527
docs/mcp.md
Normal file
527
docs/mcp.md
Normal file
|
|
@ -0,0 +1,527 @@
|
|||
# MCP (Model Context Protocol) Support
|
||||
|
||||
MCP lets Hermes Agent connect to external tool servers — giving the agent access to databases, APIs, filesystems, and more without any code changes.
|
||||
|
||||
## Overview
|
||||
|
||||
The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard for connecting AI agents to external tools and data sources. MCP servers expose tools over a lightweight RPC protocol, and Hermes Agent can connect to any compliant server automatically.
|
||||
|
||||
What this means for you:
|
||||
|
||||
- **Thousands of ready-made tools** — browse the [MCP server directory](https://github.com/modelcontextprotocol/servers) for servers covering GitHub, Slack, databases, file systems, web scraping, and more.
|
||||
- **No code changes needed** — add a few lines to `~/.hermes/config.yaml` and the tools appear alongside built-in ones.
|
||||
- **Mix and match** — run multiple MCP servers simultaneously, combining stdio-based and HTTP-based servers.
|
||||
- **Secure by default** — environment variables are filtered and credentials are stripped from error messages returned to the LLM.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install MCP support as an optional dependency:
|
||||
|
||||
```bash
|
||||
pip install hermes-agent[mcp]
|
||||
```
|
||||
|
||||
Depending on which MCP servers you want to use, you may need additional runtimes:
|
||||
|
||||
| Server Type | Runtime Needed | Example |
|
||||
|-------------|---------------|---------|
|
||||
| HTTP/remote | Nothing extra | `url: "https://mcp.example.com"` |
|
||||
| npm-based (npx) | Node.js 18+ | `command: "npx"` |
|
||||
| Python-based | uv (recommended) | `command: "uvx"` |
|
||||
|
||||
Most popular MCP servers are distributed as npm packages and launched via `npx`. Python-based servers typically use `uvx` (from the [uv](https://docs.astral.sh/uv/) package manager).
|
||||
|
||||
## Configuration
|
||||
|
||||
MCP servers are configured in `~/.hermes/config.yaml` under the `mcp_servers` key. Each entry is a named server with its connection details.
|
||||
|
||||
### Stdio Servers (command + args + env)
|
||||
|
||||
Stdio servers run as local subprocesses. Communication happens over stdin/stdout.
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
|
||||
env: {}
|
||||
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxx"
|
||||
```
|
||||
|
||||
| Key | Required | Description |
|
||||
|-----|----------|-------------|
|
||||
| `command` | Yes | Executable to run (e.g., `npx`, `uvx`, `python`) |
|
||||
| `args` | No | List of command-line arguments |
|
||||
| `env` | No | Environment variables to pass to the subprocess |
|
||||
|
||||
**Note:** Only explicitly listed `env` variables plus a safe baseline (PATH, HOME, USER, LANG, SHELL, TMPDIR, XDG_*) are passed to the subprocess. Your shell's API keys, tokens, and secrets are **not** leaked. See [Security](#security) for details.
|
||||
|
||||
### HTTP Servers (url + headers)
|
||||
|
||||
HTTP servers run remotely and are accessed over HTTP/StreamableHTTP.
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
remote_api:
|
||||
url: "https://my-mcp-server.example.com/mcp"
|
||||
headers:
|
||||
Authorization: "Bearer sk-xxxxxxxxxxxx"
|
||||
```
|
||||
|
||||
| Key | Required | Description |
|
||||
|-----|----------|-------------|
|
||||
| `url` | Yes | Full URL of the MCP HTTP endpoint |
|
||||
| `headers` | No | HTTP headers to include (e.g., auth tokens) |
|
||||
|
||||
### Per-Server Timeouts
|
||||
|
||||
Each server can have custom timeouts:
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
slow_database:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-postgres"]
|
||||
env:
|
||||
DATABASE_URL: "postgres://user:pass@localhost/mydb"
|
||||
timeout: 300 # Tool call timeout in seconds (default: 120)
|
||||
connect_timeout: 90 # Initial connection timeout in seconds (default: 60)
|
||||
```
|
||||
|
||||
| Key | Default | Description |
|
||||
|-----|---------|-------------|
|
||||
| `timeout` | 120 | Maximum seconds to wait for a single tool call to complete |
|
||||
| `connect_timeout` | 60 | Maximum seconds to wait for the initial connection and tool discovery |
|
||||
|
||||
### Mixed Configuration Example
|
||||
|
||||
You can combine stdio and HTTP servers freely:
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
# Local filesystem access via stdio
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
|
||||
|
||||
# GitHub API via stdio with auth
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxx"
|
||||
|
||||
# Remote database via HTTP
|
||||
company_db:
|
||||
url: "https://mcp.internal.company.com/db"
|
||||
headers:
|
||||
Authorization: "Bearer sk-xxxxxxxxxxxx"
|
||||
timeout: 180
|
||||
|
||||
# Python-based server via uvx
|
||||
memory:
|
||||
command: "uvx"
|
||||
args: ["mcp-server-memory"]
|
||||
```
|
||||
|
||||
## Config Translation (Claude/Cursor JSON → Hermes YAML)
|
||||
|
||||
Many MCP server docs show configuration in Claude Desktop JSON format. Here's how to translate:
|
||||
|
||||
**Claude Desktop JSON** (`claude_desktop_config.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"filesystem": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
|
||||
"env": {}
|
||||
},
|
||||
"github": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-github"],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Hermes Agent YAML** (`~/.hermes/config.yaml`):
|
||||
|
||||
```yaml
|
||||
mcp_servers: # mcpServers → mcp_servers (snake_case)
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
|
||||
env: {}
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxx"
|
||||
```
|
||||
|
||||
Translation rules:
|
||||
|
||||
1. **Key name**: `mcpServers` → `mcp_servers` (snake_case)
|
||||
2. **Format**: JSON → YAML (remove braces/brackets, use indentation)
|
||||
3. **Arrays**: `["a", "b"]` stays the same in YAML flow style, or use block style with `- a`
|
||||
4. **Everything else**: Keys (`command`, `args`, `env`) are identical
|
||||
|
||||
## How It Works
|
||||
|
||||
### Startup & Discovery
|
||||
|
||||
When Hermes Agent starts, the tool discovery system calls `discover_mcp_tools()`:
|
||||
|
||||
1. **Config loading** — Reads `mcp_servers` from `~/.hermes/config.yaml`
|
||||
2. **Background loop** — Spins up a dedicated asyncio event loop in a daemon thread for MCP connections
|
||||
3. **Connection** — Connects to each configured server (stdio subprocess or HTTP)
|
||||
4. **Session init** — Initializes the MCP client session (protocol handshake)
|
||||
5. **Tool discovery** — Calls `list_tools()` on each server to get available tools
|
||||
6. **Registration** — Registers each MCP tool into the Hermes tool registry with a prefixed name
|
||||
|
||||
### Tool Registration
|
||||
|
||||
Each discovered MCP tool is registered with a prefixed name following this pattern:
|
||||
|
||||
```
|
||||
mcp_{server_name}_{tool_name}
|
||||
```
|
||||
|
||||
Hyphens and dots in both server and tool names are replaced with underscores for API compatibility. For example:
|
||||
|
||||
| Server Name | MCP Tool Name | Registered As |
|
||||
|-------------|--------------|---------------|
|
||||
| `filesystem` | `read_file` | `mcp_filesystem_read_file` |
|
||||
| `github` | `create-issue` | `mcp_github_create_issue` |
|
||||
| `my-api` | `query.data` | `mcp_my_api_query_data` |
|
||||
|
||||
Tools appear alongside built-in tools — the agent sees them in its tool list and can call them like any other tool.
|
||||
|
||||
### Tool Calling
|
||||
|
||||
When the agent calls an MCP tool:
|
||||
|
||||
1. The handler is invoked by the tool registry (sync interface)
|
||||
2. The handler schedules the actual MCP `call_tool()` RPC on the background event loop
|
||||
3. The call blocks (with timeout) until the MCP server responds
|
||||
4. Response content blocks are collected and returned as JSON
|
||||
5. Errors are sanitized to strip credentials before returning to the LLM
|
||||
|
||||
### Shutdown
|
||||
|
||||
On agent exit, `shutdown_mcp_servers()` is called:
|
||||
|
||||
1. All server tasks are signalled to exit via their shutdown events
|
||||
2. Each server's `async with` context manager exits, cleaning up transports
|
||||
3. The background event loop is stopped and its thread is joined
|
||||
4. All server state is cleared
|
||||
|
||||
## Security
|
||||
|
||||
### Environment Variable Filtering
|
||||
|
||||
When launching stdio MCP servers, Hermes does **not** pass your full shell environment to the subprocess. The `_build_safe_env()` function constructs a minimal environment:
|
||||
|
||||
**Always passed through** (from your current environment):
|
||||
- `PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `TERM`, `SHELL`, `TMPDIR`
|
||||
- Any variable starting with `XDG_`
|
||||
|
||||
**Explicitly added**: Any variables you list in the server's `env` config.
|
||||
|
||||
**Everything else is excluded** — your `OPENAI_API_KEY`, `AWS_SECRET_ACCESS_KEY`, database passwords, and other secrets are never leaked to MCP server subprocesses unless you explicitly add them.
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
# Only this token is passed — nothing else from your shell
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxx"
|
||||
```
|
||||
|
||||
### Credential Stripping in Errors
|
||||
|
||||
If an MCP tool call fails, the error message is sanitized by `_sanitize_error()` before being returned to the LLM. The following patterns are replaced with `[REDACTED]`:
|
||||
|
||||
- GitHub PATs (`ghp_...`)
|
||||
- OpenAI-style keys (`sk-...`)
|
||||
- Bearer tokens (`Bearer ...`)
|
||||
- Query parameters (`token=...`, `key=...`, `API_KEY=...`, `password=...`, `secret=...`)
|
||||
|
||||
This prevents accidental credential exposure through error messages in the conversation.
|
||||
|
||||
## Transport Types
|
||||
|
||||
### Stdio Transport
|
||||
|
||||
The default transport for locally-installed MCP servers. The server runs as a subprocess and communicates over stdin/stdout.
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
my_server:
|
||||
command: "npx" # or "uvx", "python", any executable
|
||||
args: ["-y", "package"]
|
||||
env:
|
||||
MY_VAR: "value"
|
||||
```
|
||||
|
||||
**Pros:** Simple setup, no network needed, works offline.
|
||||
**Cons:** Server must be installed locally, one process per server.
|
||||
|
||||
### HTTP / StreamableHTTP Transport
|
||||
|
||||
For remote MCP servers accessible over HTTP. Uses the StreamableHTTP protocol from the MCP SDK.
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
my_remote:
|
||||
url: "https://mcp.example.com/endpoint"
|
||||
headers:
|
||||
Authorization: "Bearer token"
|
||||
```
|
||||
|
||||
**Pros:** No local installation needed, shared servers, cloud-hosted.
|
||||
**Cons:** Requires network, slightly higher latency, needs `mcp` package with HTTP support.
|
||||
|
||||
**Note:** If HTTP transport is not available in your installed `mcp` package version, Hermes will log a clear error and skip that server.
|
||||
|
||||
## Reconnection
|
||||
|
||||
If an MCP server connection drops after initial setup (e.g., process crash, network hiccup), Hermes automatically attempts to reconnect with exponential backoff:
|
||||
|
||||
| Attempt | Delay Before Retry |
|
||||
|---------|--------------------|
|
||||
| 1 | 1 second |
|
||||
| 2 | 2 seconds |
|
||||
| 3 | 4 seconds |
|
||||
| 4 | 8 seconds |
|
||||
| 5 | 16 seconds |
|
||||
|
||||
- Maximum of **5 retry attempts** before giving up
|
||||
- Backoff is capped at **60 seconds** (relevant if the formula exceeds this)
|
||||
- Reconnection only triggers for **established connections** that drop — initial connection failures are reported immediately without retries
|
||||
- If shutdown is requested during reconnection, the retry loop exits cleanly
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Errors
|
||||
|
||||
**"mcp package not installed"**
|
||||
|
||||
```
|
||||
MCP SDK not available -- skipping MCP tool discovery
|
||||
```
|
||||
|
||||
Solution: Install the MCP optional dependency:
|
||||
|
||||
```bash
|
||||
pip install hermes-agent[mcp]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**"command not found" or server fails to start**
|
||||
|
||||
The MCP server command (`npx`, `uvx`, etc.) is not on PATH.
|
||||
|
||||
Solution: Install the required runtime:
|
||||
|
||||
```bash
|
||||
# For npm-based servers
|
||||
npm install -g npx # or ensure Node.js 18+ is installed
|
||||
|
||||
# For Python-based servers
|
||||
pip install uv # then use "uvx" as the command
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**"MCP server 'X' has no 'command' in config"**
|
||||
|
||||
Your stdio server config is missing the `command` key.
|
||||
|
||||
Solution: Check your `~/.hermes/config.yaml` indentation and ensure `command` is present:
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
my_server:
|
||||
command: "npx" # <-- required for stdio servers
|
||||
args: ["-y", "package-name"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Server connects but tools fail with authentication errors**
|
||||
|
||||
Your API key or token is missing or invalid.
|
||||
|
||||
Solution: Ensure the key is in the server's `env` block (not your shell env):
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_your_actual_token" # <-- check this
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**"MCP server 'X' is not connected"**
|
||||
|
||||
The server disconnected and reconnection failed (or was never established).
|
||||
|
||||
Solution:
|
||||
1. Check the Hermes logs for connection errors (`hermes --verbose`)
|
||||
2. Verify the server works standalone (e.g., run the `npx` command manually)
|
||||
3. Increase `connect_timeout` if the server is slow to start
|
||||
|
||||
---
|
||||
|
||||
**Connection timeout during discovery**
|
||||
|
||||
```
|
||||
Failed to connect to MCP server 'X': TimeoutError
|
||||
```
|
||||
|
||||
Solution: Increase the `connect_timeout` for slow-starting servers:
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
slow_server:
|
||||
command: "npx"
|
||||
args: ["-y", "heavy-server-package"]
|
||||
connect_timeout: 120 # default is 60
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**HTTP transport not available**
|
||||
|
||||
```
|
||||
mcp.client.streamable_http is not available
|
||||
```
|
||||
|
||||
Solution: Upgrade the `mcp` package to a version that includes HTTP support:
|
||||
|
||||
```bash
|
||||
pip install --upgrade mcp
|
||||
```
|
||||
|
||||
## Popular MCP Servers
|
||||
|
||||
Here are some popular free MCP servers you can use immediately:
|
||||
|
||||
| Server | Package | Description |
|
||||
|--------|---------|-------------|
|
||||
| Filesystem | `@modelcontextprotocol/server-filesystem` | Read/write/search local files |
|
||||
| GitHub | `@modelcontextprotocol/server-github` | Issues, PRs, repos, code search |
|
||||
| Git | `@modelcontextprotocol/server-git` | Git operations on local repos |
|
||||
| Fetch | `@modelcontextprotocol/server-fetch` | HTTP fetching and web content extraction |
|
||||
| Memory | `@modelcontextprotocol/server-memory` | Persistent key-value memory |
|
||||
| SQLite | `@modelcontextprotocol/server-sqlite` | Query SQLite databases |
|
||||
| PostgreSQL | `@modelcontextprotocol/server-postgres` | Query PostgreSQL databases |
|
||||
| Brave Search | `@modelcontextprotocol/server-brave-search` | Web search via Brave API |
|
||||
| Puppeteer | `@modelcontextprotocol/server-puppeteer` | Browser automation |
|
||||
| Sequential Thinking | `@modelcontextprotocol/server-sequential-thinking` | Step-by-step reasoning |
|
||||
|
||||
### Example Configs for Popular Servers
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
# Filesystem — no API key needed
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
|
||||
|
||||
# Git — no API key needed
|
||||
git:
|
||||
command: "uvx"
|
||||
args: ["mcp-server-git", "--repository", "/home/user/my-repo"]
|
||||
|
||||
# GitHub — requires a personal access token
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxx"
|
||||
|
||||
# Fetch — no API key needed
|
||||
fetch:
|
||||
command: "uvx"
|
||||
args: ["mcp-server-fetch"]
|
||||
|
||||
# SQLite — no API key needed
|
||||
sqlite:
|
||||
command: "uvx"
|
||||
args: ["mcp-server-sqlite", "--db-path", "/home/user/data.db"]
|
||||
|
||||
# Brave Search — requires API key (free tier available)
|
||||
brave_search:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-brave-search"]
|
||||
env:
|
||||
BRAVE_API_KEY: "BSA_xxxxxxxxxxxx"
|
||||
```
|
||||
|
||||
## Advanced
|
||||
|
||||
### Multiple Servers
|
||||
|
||||
You can run as many MCP servers as you want simultaneously. Each server gets its own subprocess (stdio) or HTTP connection, and all tools are registered into a single unified namespace.
|
||||
|
||||
Servers are connected sequentially during startup. If one server fails to connect, the others still work — failed servers are logged as warnings and skipped.
|
||||
|
||||
### Tool Naming Convention
|
||||
|
||||
All MCP tools follow the naming pattern:
|
||||
|
||||
```
|
||||
mcp_{server_name}_{tool_name}
|
||||
```
|
||||
|
||||
Both the server name and tool name are sanitized: hyphens (`-`) and dots (`.`) are replaced with underscores (`_`). This ensures compatibility with LLM function-calling APIs that restrict tool name characters.
|
||||
|
||||
If you configure a server named `my-api` that exposes a tool called `query.users`, the agent will see it as `mcp_my_api_query_users`.
|
||||
|
||||
### Configurable Timeouts
|
||||
|
||||
Fine-tune timeouts per server based on expected response times:
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
fast_cache:
|
||||
command: "npx"
|
||||
args: ["-y", "mcp-server-redis"]
|
||||
timeout: 30 # Fast lookups — short timeout
|
||||
connect_timeout: 15
|
||||
|
||||
slow_analysis:
|
||||
url: "https://analysis.example.com/mcp"
|
||||
timeout: 600 # Long-running analysis — generous timeout
|
||||
connect_timeout: 120
|
||||
```
|
||||
|
||||
### Idempotent Discovery
|
||||
|
||||
`discover_mcp_tools()` is idempotent — calling it multiple times only connects to servers that aren't already running. Already-connected servers keep their existing connections and tool registrations.
|
||||
|
||||
### Custom Toolsets
|
||||
|
||||
Each MCP server's tools are automatically grouped into a toolset named `mcp-{server_name}`. These toolsets are also injected into all `hermes-*` platform toolsets, so MCP tools are available in CLI, Telegram, Discord, and other platforms.
|
||||
|
||||
### Thread Safety
|
||||
|
||||
The MCP subsystem is fully thread-safe. A dedicated background event loop runs in a daemon thread, and all server state is protected by a lock. This works correctly even with Python 3.13+ free-threading builds.
|
||||
|
|
@ -141,7 +141,12 @@ pip install discord.py>=2.0
|
|||
|
||||
### WhatsApp
|
||||
|
||||
WhatsApp uses a built-in bridge powered by [Baileys](https://github.com/WhiskeySockets/Baileys) that connects via WhatsApp Web. The agent links to your WhatsApp account and responds to incoming messages.
|
||||
WhatsApp uses a built-in bridge powered by [Baileys](https://github.com/WhiskeySockets/Baileys) that connects via WhatsApp Web.
|
||||
|
||||
**Two modes:**
|
||||
|
||||
- **`bot` mode (recommended):** Use a dedicated phone number for the bot. Other people message that number directly. All `fromMe` messages are treated as bot echo-backs and ignored.
|
||||
- **`self-chat` mode:** Use your own WhatsApp account. You talk to the agent by messaging yourself (WhatsApp → "Message Yourself").
|
||||
|
||||
**Setup:**
|
||||
|
||||
|
|
@ -149,12 +154,7 @@ WhatsApp uses a built-in bridge powered by [Baileys](https://github.com/WhiskeyS
|
|||
hermes whatsapp
|
||||
```
|
||||
|
||||
This will:
|
||||
- Enable WhatsApp in your `.env`
|
||||
- Ask for your phone number (for the allowlist)
|
||||
- Install bridge dependencies (Node.js required)
|
||||
- Display a QR code — scan it with your phone (WhatsApp → Settings → Linked Devices → Link a Device)
|
||||
- Exit automatically once paired
|
||||
The wizard walks you through mode selection, allowlist configuration, dependency installation, and QR code pairing. For bot mode, you'll need a second phone number with WhatsApp installed on some device (dual-SIM with WhatsApp Business app is the easiest approach).
|
||||
|
||||
Then start the gateway:
|
||||
|
||||
|
|
@ -162,16 +162,23 @@ Then start the gateway:
|
|||
hermes gateway
|
||||
```
|
||||
|
||||
The gateway starts the WhatsApp bridge automatically using the saved session credentials in `~/.hermes/whatsapp/session/`.
|
||||
|
||||
**Environment variables:**
|
||||
|
||||
```bash
|
||||
WHATSAPP_ENABLED=true
|
||||
WHATSAPP_ALLOWED_USERS=15551234567 # Comma-separated phone numbers with country code
|
||||
WHATSAPP_MODE=bot # "bot" (separate number) or "self-chat" (message yourself)
|
||||
WHATSAPP_ALLOWED_USERS=15551234567 # Comma-separated phone numbers with country code
|
||||
```
|
||||
|
||||
Agent responses are prefixed with "⚕ **Hermes Agent**" so you can distinguish them from your own messages when messaging yourself.
|
||||
**Getting a second number for bot mode:**
|
||||
|
||||
| Option | Cost | Notes |
|
||||
|--------|------|-------|
|
||||
| WhatsApp Business app + dual-SIM | Free (if you have dual-SIM) | Install alongside personal WhatsApp, no second phone needed |
|
||||
| Google Voice | Free (US only) | voice.google.com, verify WhatsApp via the Google Voice app |
|
||||
| Prepaid SIM | $3-10/month | Any carrier; verify once, phone can go in a drawer on WiFi |
|
||||
|
||||
Agent responses are prefixed with "⚕ **Hermes Agent**" for easy identification.
|
||||
|
||||
> **Re-pairing:** If WhatsApp Web sessions disconnect (protocol updates, phone reset), re-pair with `hermes whatsapp`.
|
||||
|
||||
|
|
|
|||
|
|
@ -55,6 +55,7 @@ async def web_search(query: str) -> dict:
|
|||
| **Clarify** | `clarify_tool.py` | `clarify` (interactive multiple-choice / open-ended questions, CLI-only) |
|
||||
| **Code Execution** | `code_execution_tool.py` | `execute_code` (run Python scripts that call tools via RPC sandbox) |
|
||||
| **Delegation** | `delegate_tool.py` | `delegate_task` (spawn subagents with isolated context, single + parallel batch) |
|
||||
| **MCP (External)** | `tools/mcp_tool.py` | Auto-discovered from configured MCP servers |
|
||||
|
||||
## Tool Registration
|
||||
|
||||
|
|
@ -414,3 +415,20 @@ The Skills Hub enables searching, installing, and managing skills from online re
|
|||
|
||||
**CLI:** `hermes skills search|install|inspect|list|audit|uninstall|publish|snapshot|tap`
|
||||
**Slash:** `/skills search|install|inspect|list|audit|uninstall|publish|snapshot|tap`
|
||||
|
||||
## MCP Tools
|
||||
|
||||
MCP (Model Context Protocol) tools are **dynamically registered** from external MCP servers configured in `cli-config.yaml`. Unlike built-in tools which are defined in Python source files, MCP tools are discovered at startup by connecting to each configured server and querying its available tools.
|
||||
|
||||
Each MCP tool is automatically wrapped with an OpenAI-compatible schema and registered in the tool registry under the `mcp` toolset. Tool names are prefixed with the server name (e.g., `time__get_current_time`) to avoid collisions.
|
||||
|
||||
**Key characteristics:**
|
||||
- Tools are discovered and registered at agent startup — no code changes needed
|
||||
- Supports both stdio (subprocess) and HTTP (streamable HTTP) transports
|
||||
- Auto-reconnects on connection failures with exponential backoff
|
||||
- Environment variables passed to stdio servers are filtered for security
|
||||
- Each server can have independent timeout settings
|
||||
|
||||
**Configuration:** Add servers to `mcp_servers` in `cli-config.yaml`. See [docs/mcp.md](mcp.md) for full documentation.
|
||||
|
||||
**Installation:** MCP support requires the optional `mcp` extra: `pip install hermes-agent[mcp]`
|
||||
|
|
|
|||
|
|
@ -29,7 +29,17 @@ except ImportError:
|
|||
Bot = Any
|
||||
Message = Any
|
||||
Application = Any
|
||||
ContextTypes = Any
|
||||
CommandHandler = Any
|
||||
TelegramMessageHandler = Any
|
||||
filters = None
|
||||
ParseMode = None
|
||||
ChatType = None
|
||||
|
||||
# Mock ContextTypes so type annotations using ContextTypes.DEFAULT_TYPE
|
||||
# don't crash during class definition when the library isn't installed.
|
||||
class _MockContextTypes:
|
||||
DEFAULT_TYPE = Any
|
||||
ContextTypes = _MockContextTypes
|
||||
|
||||
import sys
|
||||
from pathlib import Path as _Path
|
||||
|
|
|
|||
|
|
@ -19,7 +19,10 @@ import asyncio
|
|||
import json
|
||||
import logging
|
||||
import os
|
||||
import platform
|
||||
import subprocess
|
||||
|
||||
_IS_WINDOWS = platform.system() == "Windows"
|
||||
from pathlib import Path
|
||||
from typing import Dict, List, Optional, Any
|
||||
|
||||
|
|
@ -157,16 +160,18 @@ class WhatsAppAdapter(BasePlatformAdapter):
|
|||
pass
|
||||
|
||||
# Start the bridge process in its own process group
|
||||
whatsapp_mode = os.getenv("WHATSAPP_MODE", "self-chat")
|
||||
self._bridge_process = subprocess.Popen(
|
||||
[
|
||||
"node",
|
||||
str(bridge_path),
|
||||
"--port", str(self._bridge_port),
|
||||
"--session", str(self._session_path),
|
||||
"--mode", whatsapp_mode,
|
||||
],
|
||||
stdout=subprocess.DEVNULL,
|
||||
stderr=subprocess.DEVNULL,
|
||||
preexec_fn=os.setsid,
|
||||
preexec_fn=None if _IS_WINDOWS else os.setsid,
|
||||
)
|
||||
|
||||
# Wait for bridge to be ready via HTTP health check
|
||||
|
|
@ -211,13 +216,19 @@ class WhatsAppAdapter(BasePlatformAdapter):
|
|||
# Kill the entire process group so child node processes die too
|
||||
import signal
|
||||
try:
|
||||
os.killpg(os.getpgid(self._bridge_process.pid), signal.SIGTERM)
|
||||
if _IS_WINDOWS:
|
||||
self._bridge_process.terminate()
|
||||
else:
|
||||
os.killpg(os.getpgid(self._bridge_process.pid), signal.SIGTERM)
|
||||
except (ProcessLookupError, PermissionError):
|
||||
self._bridge_process.terminate()
|
||||
await asyncio.sleep(1)
|
||||
if self._bridge_process.poll() is None:
|
||||
try:
|
||||
os.killpg(os.getpgid(self._bridge_process.pid), signal.SIGKILL)
|
||||
if _IS_WINDOWS:
|
||||
self._bridge_process.kill()
|
||||
else:
|
||||
os.killpg(os.getpgid(self._bridge_process.pid), signal.SIGKILL)
|
||||
except (ProcessLookupError, PermissionError):
|
||||
self._bridge_process.kill()
|
||||
except Exception as e:
|
||||
|
|
|
|||
|
|
@ -645,7 +645,7 @@ class GatewayRunner:
|
|||
# Emit command:* hook for any recognized slash command
|
||||
_known_commands = {"new", "reset", "help", "status", "stop", "model",
|
||||
"personality", "retry", "undo", "sethome", "set-home",
|
||||
"compress", "usage"}
|
||||
"compress", "usage", "reload-mcp"}
|
||||
if command and command in _known_commands:
|
||||
await self.hooks.emit(f"command:{command}", {
|
||||
"platform": source.platform.value if source.platform else "",
|
||||
|
|
@ -686,6 +686,9 @@ class GatewayRunner:
|
|||
|
||||
if command == "usage":
|
||||
return await self._handle_usage_command(event)
|
||||
|
||||
if command == "reload-mcp":
|
||||
return await self._handle_reload_mcp_command(event)
|
||||
|
||||
# Skill slash commands: /skill-name loads the skill and sends to agent
|
||||
if command:
|
||||
|
|
@ -1086,6 +1089,7 @@ class GatewayRunner:
|
|||
"`/sethome` — Set this chat as the home channel",
|
||||
"`/compress` — Compress conversation context",
|
||||
"`/usage` — Show token usage for this session",
|
||||
"`/reload-mcp` — Reload MCP servers from config",
|
||||
"`/help` — Show this message",
|
||||
]
|
||||
try:
|
||||
|
|
@ -1379,6 +1383,76 @@ class GatewayRunner:
|
|||
)
|
||||
return "No usage data available for this session."
|
||||
|
||||
async def _handle_reload_mcp_command(self, event: MessageEvent) -> str:
|
||||
"""Handle /reload-mcp command -- disconnect and reconnect all MCP servers."""
|
||||
loop = asyncio.get_event_loop()
|
||||
try:
|
||||
from tools.mcp_tool import shutdown_mcp_servers, discover_mcp_tools, _load_mcp_config, _servers, _lock
|
||||
|
||||
# Capture old server names before shutdown
|
||||
with _lock:
|
||||
old_servers = set(_servers.keys())
|
||||
|
||||
# Read new config before shutting down, so we know what will be added/removed
|
||||
new_config = _load_mcp_config()
|
||||
new_server_names = set(new_config.keys())
|
||||
|
||||
# Shutdown existing connections
|
||||
await loop.run_in_executor(None, shutdown_mcp_servers)
|
||||
|
||||
# Reconnect by discovering tools (reads config.yaml fresh)
|
||||
new_tools = await loop.run_in_executor(None, discover_mcp_tools)
|
||||
|
||||
# Compute what changed
|
||||
with _lock:
|
||||
connected_servers = set(_servers.keys())
|
||||
|
||||
added = connected_servers - old_servers
|
||||
removed = old_servers - connected_servers
|
||||
reconnected = connected_servers & old_servers
|
||||
|
||||
lines = ["🔄 **MCP Servers Reloaded**\n"]
|
||||
if reconnected:
|
||||
lines.append(f"♻️ Reconnected: {', '.join(sorted(reconnected))}")
|
||||
if added:
|
||||
lines.append(f"➕ Added: {', '.join(sorted(added))}")
|
||||
if removed:
|
||||
lines.append(f"➖ Removed: {', '.join(sorted(removed))}")
|
||||
if not connected_servers:
|
||||
lines.append("No MCP servers connected.")
|
||||
else:
|
||||
lines.append(f"\n🔧 {len(new_tools)} tool(s) available from {len(connected_servers)} server(s)")
|
||||
|
||||
# Inject a message at the END of the session history so the
|
||||
# model knows tools changed on its next turn. Appended after
|
||||
# all existing messages to preserve prompt-cache for the prefix.
|
||||
change_parts = []
|
||||
if added:
|
||||
change_parts.append(f"Added servers: {', '.join(sorted(added))}")
|
||||
if removed:
|
||||
change_parts.append(f"Removed servers: {', '.join(sorted(removed))}")
|
||||
if reconnected:
|
||||
change_parts.append(f"Reconnected servers: {', '.join(sorted(reconnected))}")
|
||||
tool_summary = f"{len(new_tools)} MCP tool(s) now available" if new_tools else "No MCP tools available"
|
||||
change_detail = ". ".join(change_parts) + ". " if change_parts else ""
|
||||
reload_msg = {
|
||||
"role": "user",
|
||||
"content": f"[SYSTEM: MCP servers have been reloaded. {change_detail}{tool_summary}. The tool list for this conversation has been updated accordingly.]",
|
||||
}
|
||||
try:
|
||||
session_entry = self.session_store.get_or_create_session(event.source)
|
||||
self.session_store.append_to_transcript(
|
||||
session_entry.session_id, reload_msg
|
||||
)
|
||||
except Exception:
|
||||
pass # Best-effort; don't fail the reload over a transcript write
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
except Exception as e:
|
||||
logger.warning("MCP reload failed: %s", e)
|
||||
return f"❌ MCP reload failed: {e}"
|
||||
|
||||
def _set_session_env(self, context: SessionContext) -> None:
|
||||
"""Set environment variables for the current session."""
|
||||
os.environ["HERMES_SESSION_PLATFORM"] = context.source.platform.value
|
||||
|
|
@ -2217,7 +2291,14 @@ async def start_gateway(config: Optional[GatewayConfig] = None) -> bool:
|
|||
# Stop cron ticker cleanly
|
||||
cron_stop.set()
|
||||
cron_thread.join(timeout=5)
|
||||
|
||||
|
||||
# Close MCP server connections
|
||||
try:
|
||||
from tools.mcp_tool import shutdown_mcp_servers
|
||||
shutdown_mcp_servers()
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return True
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -196,6 +196,28 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
|
|||
if remaining_toolsets > 0:
|
||||
right_lines.append(f"[dim #B8860B](and {remaining_toolsets} more toolsets...)[/]")
|
||||
|
||||
# MCP Servers section (only if configured)
|
||||
try:
|
||||
from tools.mcp_tool import get_mcp_status
|
||||
mcp_status = get_mcp_status()
|
||||
except Exception:
|
||||
mcp_status = []
|
||||
|
||||
if mcp_status:
|
||||
right_lines.append("")
|
||||
right_lines.append("[bold #FFBF00]MCP Servers[/]")
|
||||
for srv in mcp_status:
|
||||
if srv["connected"]:
|
||||
right_lines.append(
|
||||
f"[dim #B8860B]{srv['name']}[/] [#FFF8DC]({srv['transport']})[/] "
|
||||
f"[dim #B8860B]—[/] [#FFF8DC]{srv['tools']} tool(s)[/]"
|
||||
)
|
||||
else:
|
||||
right_lines.append(
|
||||
f"[red]{srv['name']}[/] [dim]({srv['transport']})[/] "
|
||||
f"[red]— failed[/]"
|
||||
)
|
||||
|
||||
right_lines.append("")
|
||||
right_lines.append("[bold #FFBF00]Available Skills[/]")
|
||||
skills_by_category = get_available_skills()
|
||||
|
|
@ -216,7 +238,12 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
|
|||
right_lines.append("[dim #B8860B]No skills installed[/]")
|
||||
|
||||
right_lines.append("")
|
||||
right_lines.append(f"[dim #B8860B]{len(tools)} tools · {total_skills} skills · /help for commands[/]")
|
||||
mcp_connected = sum(1 for s in mcp_status if s["connected"]) if mcp_status else 0
|
||||
summary_parts = [f"{len(tools)} tools", f"{total_skills} skills"]
|
||||
if mcp_connected:
|
||||
summary_parts.append(f"{mcp_connected} MCP servers")
|
||||
summary_parts.append("/help for commands")
|
||||
right_lines.append(f"[dim #B8860B]{' · '.join(summary_parts)}[/]")
|
||||
|
||||
right_content = "\n".join(right_lines)
|
||||
layout_table.add_row(left_content, right_content)
|
||||
|
|
|
|||
|
|
@ -13,11 +13,14 @@ This module provides:
|
|||
"""
|
||||
|
||||
import os
|
||||
import platform
|
||||
import sys
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
from typing import Dict, Any, Optional, List, Tuple
|
||||
|
||||
_IS_WINDOWS = platform.system() == "Windows"
|
||||
|
||||
import yaml
|
||||
|
||||
from hermes_cli.colors import Colors, color
|
||||
|
|
@ -618,7 +621,10 @@ def load_env() -> Dict[str, str]:
|
|||
env_vars = {}
|
||||
|
||||
if env_path.exists():
|
||||
with open(env_path) as f:
|
||||
# On Windows, open() defaults to the system locale (cp1252) which can
|
||||
# fail on UTF-8 .env files. Use explicit UTF-8 only on Windows.
|
||||
open_kw = {"encoding": "utf-8", "errors": "replace"} if _IS_WINDOWS else {}
|
||||
with open(env_path, **open_kw) as f:
|
||||
for line in f:
|
||||
line = line.strip()
|
||||
if line and not line.startswith('#') and '=' in line:
|
||||
|
|
@ -633,10 +639,14 @@ def save_env_value(key: str, value: str):
|
|||
ensure_hermes_home()
|
||||
env_path = get_env_path()
|
||||
|
||||
# Load existing
|
||||
# On Windows, open() defaults to the system locale (cp1252) which can
|
||||
# cause OSError errno 22 on UTF-8 .env files.
|
||||
read_kw = {"encoding": "utf-8", "errors": "replace"} if _IS_WINDOWS else {}
|
||||
write_kw = {"encoding": "utf-8"} if _IS_WINDOWS else {}
|
||||
|
||||
lines = []
|
||||
if env_path.exists():
|
||||
with open(env_path) as f:
|
||||
with open(env_path, **read_kw) as f:
|
||||
lines = f.readlines()
|
||||
|
||||
# Find and update or append
|
||||
|
|
@ -653,7 +663,7 @@ def save_env_value(key: str, value: str):
|
|||
lines[-1] += "\n"
|
||||
lines.append(f"{key}={value}\n")
|
||||
|
||||
with open(env_path, 'w') as f:
|
||||
with open(env_path, 'w', **write_kw) as f:
|
||||
f.writelines(lines)
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -21,39 +21,59 @@ PROJECT_ROOT = Path(__file__).parent.parent.resolve()
|
|||
def find_gateway_pids() -> list:
|
||||
"""Find PIDs of running gateway processes."""
|
||||
pids = []
|
||||
patterns = [
|
||||
"hermes_cli.main gateway",
|
||||
"hermes gateway",
|
||||
"gateway/run.py",
|
||||
]
|
||||
|
||||
try:
|
||||
# Look for gateway processes with multiple patterns
|
||||
patterns = [
|
||||
"hermes_cli.main gateway",
|
||||
"hermes gateway",
|
||||
"gateway/run.py",
|
||||
]
|
||||
|
||||
result = subprocess.run(
|
||||
["ps", "aux"],
|
||||
capture_output=True,
|
||||
text=True
|
||||
)
|
||||
|
||||
for line in result.stdout.split('\n'):
|
||||
# Skip grep and current process
|
||||
if 'grep' in line or str(os.getpid()) in line:
|
||||
continue
|
||||
|
||||
for pattern in patterns:
|
||||
if pattern in line:
|
||||
parts = line.split()
|
||||
if len(parts) > 1:
|
||||
if is_windows():
|
||||
# Windows: use wmic to search command lines
|
||||
result = subprocess.run(
|
||||
["wmic", "process", "get", "ProcessId,CommandLine", "/FORMAT:LIST"],
|
||||
capture_output=True, text=True
|
||||
)
|
||||
# Parse WMIC LIST output: blocks of "CommandLine=...\nProcessId=...\n"
|
||||
current_cmd = ""
|
||||
for line in result.stdout.split('\n'):
|
||||
line = line.strip()
|
||||
if line.startswith("CommandLine="):
|
||||
current_cmd = line[len("CommandLine="):]
|
||||
elif line.startswith("ProcessId="):
|
||||
pid_str = line[len("ProcessId="):]
|
||||
if any(p in current_cmd for p in patterns):
|
||||
try:
|
||||
pid = int(parts[1])
|
||||
if pid not in pids:
|
||||
pid = int(pid_str)
|
||||
if pid != os.getpid() and pid not in pids:
|
||||
pids.append(pid)
|
||||
except ValueError:
|
||||
continue
|
||||
break
|
||||
pass
|
||||
current_cmd = ""
|
||||
else:
|
||||
result = subprocess.run(
|
||||
["ps", "aux"],
|
||||
capture_output=True,
|
||||
text=True
|
||||
)
|
||||
for line in result.stdout.split('\n'):
|
||||
# Skip grep and current process
|
||||
if 'grep' in line or str(os.getpid()) in line:
|
||||
continue
|
||||
for pattern in patterns:
|
||||
if pattern in line:
|
||||
parts = line.split()
|
||||
if len(parts) > 1:
|
||||
try:
|
||||
pid = int(parts[1])
|
||||
if pid not in pids:
|
||||
pids.append(pid)
|
||||
except ValueError:
|
||||
continue
|
||||
break
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
|
||||
return pids
|
||||
|
||||
|
||||
|
|
@ -64,7 +84,7 @@ def kill_gateway_processes(force: bool = False) -> int:
|
|||
|
||||
for pid in pids:
|
||||
try:
|
||||
if force:
|
||||
if force and not is_windows():
|
||||
os.kill(pid, signal.SIGKILL)
|
||||
else:
|
||||
os.kill(pid, signal.SIGTERM)
|
||||
|
|
@ -102,7 +122,10 @@ def get_launchd_plist_path() -> Path:
|
|||
return Path.home() / "Library" / "LaunchAgents" / "ai.hermes.gateway.plist"
|
||||
|
||||
def get_python_path() -> str:
|
||||
venv_python = PROJECT_ROOT / "venv" / "bin" / "python"
|
||||
if is_windows():
|
||||
venv_python = PROJECT_ROOT / "venv" / "Scripts" / "python.exe"
|
||||
else:
|
||||
venv_python = PROJECT_ROOT / "venv" / "bin" / "python"
|
||||
if venv_python.exists():
|
||||
return str(venv_python)
|
||||
return sys.executable
|
||||
|
|
|
|||
|
|
@ -168,7 +168,7 @@ def cmd_gateway(args):
|
|||
|
||||
|
||||
def cmd_whatsapp(args):
|
||||
"""Set up WhatsApp: enable, configure allowed users, install bridge, pair via QR."""
|
||||
"""Set up WhatsApp: choose mode, configure, install bridge, pair via QR."""
|
||||
import os
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
|
|
@ -177,12 +177,55 @@ def cmd_whatsapp(args):
|
|||
print()
|
||||
print("⚕ WhatsApp Setup")
|
||||
print("=" * 50)
|
||||
print()
|
||||
print("This will link your WhatsApp account to Hermes Agent.")
|
||||
print("The agent will respond to messages sent to your WhatsApp number.")
|
||||
print()
|
||||
|
||||
# Step 1: Enable WhatsApp
|
||||
# ── Step 1: Choose mode ──────────────────────────────────────────────
|
||||
current_mode = get_env_value("WHATSAPP_MODE") or ""
|
||||
if not current_mode:
|
||||
print()
|
||||
print("How will you use WhatsApp with Hermes?")
|
||||
print()
|
||||
print(" 1. Separate bot number (recommended)")
|
||||
print(" People message the bot's number directly — cleanest experience.")
|
||||
print(" Requires a second phone number with WhatsApp installed on a device.")
|
||||
print()
|
||||
print(" 2. Personal number (self-chat)")
|
||||
print(" You message yourself to talk to the agent.")
|
||||
print(" Quick to set up, but the UX is less intuitive.")
|
||||
print()
|
||||
try:
|
||||
choice = input(" Choose [1/2]: ").strip()
|
||||
except (EOFError, KeyboardInterrupt):
|
||||
print("\nSetup cancelled.")
|
||||
return
|
||||
|
||||
if choice == "1":
|
||||
save_env_value("WHATSAPP_MODE", "bot")
|
||||
wa_mode = "bot"
|
||||
print(" ✓ Mode: separate bot number")
|
||||
print()
|
||||
print(" ┌─────────────────────────────────────────────────┐")
|
||||
print(" │ Getting a second number for the bot: │")
|
||||
print(" │ │")
|
||||
print(" │ Easiest: Install WhatsApp Business (free app) │")
|
||||
print(" │ on your phone with a second number: │")
|
||||
print(" │ • Dual-SIM: use your 2nd SIM slot │")
|
||||
print(" │ • Google Voice: free US number (voice.google) │")
|
||||
print(" │ • Prepaid SIM: $3-10, verify once │")
|
||||
print(" │ │")
|
||||
print(" │ WhatsApp Business runs alongside your personal │")
|
||||
print(" │ WhatsApp — no second phone needed. │")
|
||||
print(" └─────────────────────────────────────────────────┘")
|
||||
else:
|
||||
save_env_value("WHATSAPP_MODE", "self-chat")
|
||||
wa_mode = "self-chat"
|
||||
print(" ✓ Mode: personal number (self-chat)")
|
||||
else:
|
||||
wa_mode = current_mode
|
||||
mode_label = "separate bot number" if wa_mode == "bot" else "personal number (self-chat)"
|
||||
print(f"\n✓ Mode: {mode_label}")
|
||||
|
||||
# ── Step 2: Enable WhatsApp ──────────────────────────────────────────
|
||||
print()
|
||||
current = get_env_value("WHATSAPP_ENABLED")
|
||||
if current and current.lower() == "true":
|
||||
print("✓ WhatsApp is already enabled")
|
||||
|
|
@ -190,26 +233,36 @@ def cmd_whatsapp(args):
|
|||
save_env_value("WHATSAPP_ENABLED", "true")
|
||||
print("✓ WhatsApp enabled")
|
||||
|
||||
# Step 2: Allowed users
|
||||
# ── Step 3: Allowed users ────────────────────────────────────────────
|
||||
current_users = get_env_value("WHATSAPP_ALLOWED_USERS") or ""
|
||||
if current_users:
|
||||
print(f"✓ Allowed users: {current_users}")
|
||||
response = input("\n Update allowed users? [y/N] ").strip()
|
||||
try:
|
||||
response = input("\n Update allowed users? [y/N] ").strip()
|
||||
except (EOFError, KeyboardInterrupt):
|
||||
response = "n"
|
||||
if response.lower() in ("y", "yes"):
|
||||
phone = input(" Phone number(s) (e.g. 15551234567, comma-separated): ").strip()
|
||||
if wa_mode == "bot":
|
||||
phone = input(" Phone numbers that can message the bot (comma-separated): ").strip()
|
||||
else:
|
||||
phone = input(" Your phone number (e.g. 15551234567): ").strip()
|
||||
if phone:
|
||||
save_env_value("WHATSAPP_ALLOWED_USERS", phone.replace(" ", ""))
|
||||
print(f" ✓ Updated to: {phone}")
|
||||
else:
|
||||
print()
|
||||
phone = input(" Your phone number (e.g. 15551234567): ").strip()
|
||||
if wa_mode == "bot":
|
||||
print(" Who should be allowed to message the bot?")
|
||||
phone = input(" Phone numbers (comma-separated, or * for anyone): ").strip()
|
||||
else:
|
||||
phone = input(" Your phone number (e.g. 15551234567): ").strip()
|
||||
if phone:
|
||||
save_env_value("WHATSAPP_ALLOWED_USERS", phone.replace(" ", ""))
|
||||
print(f" ✓ Allowed users set: {phone}")
|
||||
else:
|
||||
print(" ⚠ No allowlist — the agent will respond to ALL incoming messages")
|
||||
|
||||
# Step 3: Install bridge deps
|
||||
# ── Step 4: Install bridge dependencies ──────────────────────────────
|
||||
project_root = Path(__file__).resolve().parents[1]
|
||||
bridge_dir = project_root / "scripts" / "whatsapp-bridge"
|
||||
bridge_script = bridge_dir / "bridge.js"
|
||||
|
|
@ -234,13 +287,16 @@ def cmd_whatsapp(args):
|
|||
else:
|
||||
print("✓ Bridge dependencies already installed")
|
||||
|
||||
# Step 4: Check for existing session
|
||||
# ── Step 5: Check for existing session ───────────────────────────────
|
||||
session_dir = Path.home() / ".hermes" / "whatsapp" / "session"
|
||||
session_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
if (session_dir / "creds.json").exists():
|
||||
print("✓ Existing WhatsApp session found")
|
||||
response = input("\n Re-pair? This will clear the existing session. [y/N] ").strip()
|
||||
try:
|
||||
response = input("\n Re-pair? This will clear the existing session. [y/N] ").strip()
|
||||
except (EOFError, KeyboardInterrupt):
|
||||
response = "n"
|
||||
if response.lower() in ("y", "yes"):
|
||||
import shutil
|
||||
shutil.rmtree(session_dir, ignore_errors=True)
|
||||
|
|
@ -251,11 +307,16 @@ def cmd_whatsapp(args):
|
|||
print(" Start the gateway with: hermes gateway")
|
||||
return
|
||||
|
||||
# Step 5: Run bridge in pair-only mode (no HTTP server, exits after QR scan)
|
||||
# ── Step 6: QR code pairing ──────────────────────────────────────────
|
||||
print()
|
||||
print("─" * 50)
|
||||
print("📱 Scan the QR code with your phone:")
|
||||
print(" WhatsApp → Settings → Linked Devices → Link a Device")
|
||||
if wa_mode == "bot":
|
||||
print("📱 Open WhatsApp (or WhatsApp Business) on the")
|
||||
print(" phone with the BOT's number, then scan:")
|
||||
else:
|
||||
print("📱 Open WhatsApp on your phone, then scan:")
|
||||
print()
|
||||
print(" Settings → Linked Devices → Link a Device")
|
||||
print("─" * 50)
|
||||
print()
|
||||
|
||||
|
|
@ -267,12 +328,28 @@ def cmd_whatsapp(args):
|
|||
except KeyboardInterrupt:
|
||||
pass
|
||||
|
||||
# ── Step 7: Post-pairing ─────────────────────────────────────────────
|
||||
print()
|
||||
if (session_dir / "creds.json").exists():
|
||||
print("✓ WhatsApp paired successfully!")
|
||||
print()
|
||||
print("Start the gateway with: hermes gateway")
|
||||
print("Or install as a service: hermes gateway install")
|
||||
if wa_mode == "bot":
|
||||
print(" Next steps:")
|
||||
print(" 1. Start the gateway: hermes gateway")
|
||||
print(" 2. Send a message to the bot's WhatsApp number")
|
||||
print(" 3. The agent will reply automatically")
|
||||
print()
|
||||
print(" Tip: Agent responses are prefixed with '⚕ Hermes Agent'")
|
||||
else:
|
||||
print(" Next steps:")
|
||||
print(" 1. Start the gateway: hermes gateway")
|
||||
print(" 2. Open WhatsApp → Message Yourself")
|
||||
print(" 3. Type a message — the agent will reply")
|
||||
print()
|
||||
print(" Tip: Agent responses are prefixed with '⚕ Hermes Agent'")
|
||||
print(" so you can tell them apart from your own messages.")
|
||||
print()
|
||||
print(" Or install as a service: hermes gateway install")
|
||||
else:
|
||||
print("⚠ Pairing may not have completed. Run 'hermes whatsapp' to try again.")
|
||||
|
||||
|
|
@ -697,6 +774,96 @@ def cmd_uninstall(args):
|
|||
run_uninstall(args)
|
||||
|
||||
|
||||
def _update_via_zip(args):
|
||||
"""Update Hermes Agent by downloading a ZIP archive.
|
||||
|
||||
Used on Windows when git file I/O is broken (antivirus, NTFS filter
|
||||
drivers causing 'Invalid argument' errors on file creation).
|
||||
"""
|
||||
import shutil
|
||||
import tempfile
|
||||
import zipfile
|
||||
from urllib.request import urlretrieve
|
||||
|
||||
branch = "main"
|
||||
zip_url = f"https://github.com/NousResearch/hermes-agent/archive/refs/heads/{branch}.zip"
|
||||
|
||||
print("→ Downloading latest version...")
|
||||
try:
|
||||
tmp_dir = tempfile.mkdtemp(prefix="hermes-update-")
|
||||
zip_path = os.path.join(tmp_dir, f"hermes-agent-{branch}.zip")
|
||||
urlretrieve(zip_url, zip_path)
|
||||
|
||||
print("→ Extracting...")
|
||||
with zipfile.ZipFile(zip_path, 'r') as zf:
|
||||
zf.extractall(tmp_dir)
|
||||
|
||||
# GitHub ZIPs extract to hermes-agent-<branch>/
|
||||
extracted = os.path.join(tmp_dir, f"hermes-agent-{branch}")
|
||||
if not os.path.isdir(extracted):
|
||||
# Try to find it
|
||||
for d in os.listdir(tmp_dir):
|
||||
candidate = os.path.join(tmp_dir, d)
|
||||
if os.path.isdir(candidate) and d != "__MACOSX":
|
||||
extracted = candidate
|
||||
break
|
||||
|
||||
# Copy updated files over existing installation, preserving venv/node_modules/.git
|
||||
preserve = {'venv', 'node_modules', '.git', '__pycache__', '.env'}
|
||||
update_count = 0
|
||||
for item in os.listdir(extracted):
|
||||
if item in preserve:
|
||||
continue
|
||||
src = os.path.join(extracted, item)
|
||||
dst = os.path.join(str(PROJECT_ROOT), item)
|
||||
if os.path.isdir(src):
|
||||
if os.path.exists(dst):
|
||||
shutil.rmtree(dst)
|
||||
shutil.copytree(src, dst)
|
||||
else:
|
||||
shutil.copy2(src, dst)
|
||||
update_count += 1
|
||||
|
||||
print(f"✓ Updated {update_count} items from ZIP")
|
||||
|
||||
# Cleanup
|
||||
shutil.rmtree(tmp_dir, ignore_errors=True)
|
||||
|
||||
except Exception as e:
|
||||
print(f"✗ ZIP update failed: {e}")
|
||||
sys.exit(1)
|
||||
|
||||
# Reinstall Python dependencies
|
||||
print("→ Updating Python dependencies...")
|
||||
import subprocess
|
||||
uv_bin = shutil.which("uv")
|
||||
if uv_bin:
|
||||
subprocess.run(
|
||||
[uv_bin, "pip", "install", "-e", ".", "--quiet"],
|
||||
cwd=PROJECT_ROOT, check=True,
|
||||
env={**os.environ, "VIRTUAL_ENV": str(PROJECT_ROOT / "venv")}
|
||||
)
|
||||
else:
|
||||
venv_pip = PROJECT_ROOT / "venv" / ("Scripts" if sys.platform == "win32" else "bin") / "pip"
|
||||
if venv_pip.exists():
|
||||
subprocess.run([str(venv_pip), "install", "-e", ".", "--quiet"], cwd=PROJECT_ROOT, check=True)
|
||||
|
||||
# Sync skills
|
||||
try:
|
||||
from tools.skills_sync import sync_skills
|
||||
print("→ Checking for new bundled skills...")
|
||||
result = sync_skills(quiet=True)
|
||||
if result["copied"]:
|
||||
print(f" + {len(result['copied'])} new skill(s): {', '.join(result['copied'])}")
|
||||
else:
|
||||
print(" ✓ Skills are up to date")
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
print()
|
||||
print("✓ Update complete!")
|
||||
|
||||
|
||||
def cmd_update(args):
|
||||
"""Update Hermes Agent to the latest version."""
|
||||
import subprocess
|
||||
|
|
@ -705,21 +872,44 @@ def cmd_update(args):
|
|||
print("⚕ Updating Hermes Agent...")
|
||||
print()
|
||||
|
||||
# Check if we're in a git repo
|
||||
# Try git-based update first, fall back to ZIP download on Windows
|
||||
# when git file I/O is broken (antivirus, NTFS filter drivers, etc.)
|
||||
use_zip_update = False
|
||||
git_dir = PROJECT_ROOT / '.git'
|
||||
if not git_dir.exists():
|
||||
print("✗ Not a git repository. Please reinstall:")
|
||||
print(" curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash")
|
||||
sys.exit(1)
|
||||
|
||||
if not git_dir.exists():
|
||||
if sys.platform == "win32":
|
||||
use_zip_update = True
|
||||
else:
|
||||
print("✗ Not a git repository. Please reinstall:")
|
||||
print(" curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash")
|
||||
sys.exit(1)
|
||||
|
||||
# On Windows, git can fail with "unable to write loose object file: Invalid argument"
|
||||
# due to filesystem atomicity issues. Set the recommended workaround.
|
||||
if sys.platform == "win32" and git_dir.exists():
|
||||
subprocess.run(
|
||||
["git", "-c", "windows.appendAtomically=false", "config", "windows.appendAtomically", "false"],
|
||||
cwd=PROJECT_ROOT, check=False, capture_output=True
|
||||
)
|
||||
|
||||
if use_zip_update:
|
||||
# ZIP-based update for Windows when git is broken
|
||||
_update_via_zip(args)
|
||||
return
|
||||
|
||||
# Fetch and pull
|
||||
try:
|
||||
print("→ Fetching updates...")
|
||||
subprocess.run(["git", "fetch", "origin"], cwd=PROJECT_ROOT, check=True)
|
||||
git_cmd = ["git"]
|
||||
if sys.platform == "win32":
|
||||
git_cmd = ["git", "-c", "windows.appendAtomically=false"]
|
||||
|
||||
subprocess.run(git_cmd + ["fetch", "origin"], cwd=PROJECT_ROOT, check=True)
|
||||
|
||||
# Get current branch
|
||||
result = subprocess.run(
|
||||
["git", "rev-parse", "--abbrev-ref", "HEAD"],
|
||||
git_cmd + ["rev-parse", "--abbrev-ref", "HEAD"],
|
||||
cwd=PROJECT_ROOT,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
|
|
@ -729,7 +919,7 @@ def cmd_update(args):
|
|||
|
||||
# Check if there are updates
|
||||
result = subprocess.run(
|
||||
["git", "rev-list", f"HEAD..origin/{branch}", "--count"],
|
||||
git_cmd + ["rev-list", f"HEAD..origin/{branch}", "--count"],
|
||||
cwd=PROJECT_ROOT,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
|
|
@ -743,7 +933,7 @@ def cmd_update(args):
|
|||
|
||||
print(f"→ Found {commit_count} new commit(s)")
|
||||
print("→ Pulling updates...")
|
||||
subprocess.run(["git", "pull", "origin", branch], cwd=PROJECT_ROOT, check=True)
|
||||
subprocess.run(git_cmd + ["pull", "origin", branch], cwd=PROJECT_ROOT, check=True)
|
||||
|
||||
# Reinstall Python dependencies (prefer uv for speed, fall back to pip)
|
||||
print("→ Updating Python dependencies...")
|
||||
|
|
@ -755,7 +945,7 @@ def cmd_update(args):
|
|||
env={**os.environ, "VIRTUAL_ENV": str(PROJECT_ROOT / "venv")}
|
||||
)
|
||||
else:
|
||||
venv_pip = PROJECT_ROOT / "venv" / "bin" / "pip"
|
||||
venv_pip = PROJECT_ROOT / "venv" / ("Scripts" if sys.platform == "win32" else "bin") / "pip"
|
||||
if venv_pip.exists():
|
||||
subprocess.run([str(venv_pip), "install", "-e", ".", "--quiet"], cwd=PROJECT_ROOT, check=True)
|
||||
else:
|
||||
|
|
@ -851,8 +1041,14 @@ def cmd_update(args):
|
|||
print(" hermes model # Select provider and model")
|
||||
|
||||
except subprocess.CalledProcessError as e:
|
||||
print(f"✗ Update failed: {e}")
|
||||
sys.exit(1)
|
||||
if sys.platform == "win32":
|
||||
print(f"⚠ Git update failed: {e}")
|
||||
print("→ Falling back to ZIP download...")
|
||||
print()
|
||||
_update_via_zip(args)
|
||||
else:
|
||||
print(f"✗ Update failed: {e}")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
def main():
|
||||
|
|
|
|||
|
|
@ -74,8 +74,8 @@ def _resolve_openrouter_runtime(
|
|||
|
||||
api_key = (
|
||||
explicit_api_key
|
||||
or os.getenv("OPENAI_API_KEY")
|
||||
or os.getenv("OPENROUTER_API_KEY")
|
||||
or os.getenv("OPENAI_API_KEY")
|
||||
or ""
|
||||
)
|
||||
|
||||
|
|
|
|||
|
|
@ -390,11 +390,17 @@ def run_setup_wizard(args):
|
|||
config = load_config()
|
||||
hermes_home = get_hermes_home()
|
||||
|
||||
# Check if this is an existing installation with config (any provider or config file)
|
||||
# Check if this is an existing installation with a provider configured.
|
||||
# Just having config.yaml is NOT enough — the installer creates it from
|
||||
# a template, so it always exists after install. We need an actual
|
||||
# inference provider to consider it "existing" (otherwise quick mode
|
||||
# would skip provider selection, leaving hermes non-functional).
|
||||
from hermes_cli.auth import get_active_provider
|
||||
active_provider = get_active_provider()
|
||||
is_existing = (
|
||||
get_env_value("OPENROUTER_API_KEY") is not None
|
||||
or get_env_value("OPENAI_BASE_URL") is not None
|
||||
or get_config_path().exists()
|
||||
or active_provider is not None
|
||||
)
|
||||
|
||||
# Import migration helpers
|
||||
|
|
@ -1382,21 +1388,13 @@ def run_setup_wizard(args):
|
|||
existing_whatsapp = get_env_value('WHATSAPP_ENABLED')
|
||||
if not existing_whatsapp and prompt_yes_no("Set up WhatsApp?", False):
|
||||
print_info("WhatsApp connects via a built-in bridge (Baileys).")
|
||||
print_info("Requires Node.js (already installed if you have browser tools).")
|
||||
print_info("On first gateway start, you'll scan a QR code with your phone.")
|
||||
print_info("Requires Node.js. Run 'hermes whatsapp' for guided setup.")
|
||||
print()
|
||||
if prompt_yes_no("Enable WhatsApp?", True):
|
||||
if prompt_yes_no("Enable WhatsApp now?", True):
|
||||
save_env_value("WHATSAPP_ENABLED", "true")
|
||||
print_success("WhatsApp enabled")
|
||||
|
||||
allowed_users = prompt(" Your phone number (e.g. 15551234567, comma-separated for multiple)")
|
||||
if allowed_users:
|
||||
save_env_value("WHATSAPP_ALLOWED_USERS", allowed_users.replace(" ", ""))
|
||||
print_success("WhatsApp allowlist configured")
|
||||
else:
|
||||
print_info("⚠️ No allowlist set — anyone who messages your WhatsApp will get a response!")
|
||||
|
||||
print_info("Start the gateway with 'hermes gateway' and scan the QR code.")
|
||||
print_info("Run 'hermes whatsapp' to choose your mode (separate bot number")
|
||||
print_info("or personal self-chat) and pair via QR code.")
|
||||
|
||||
# Gateway reminder
|
||||
any_messaging = (
|
||||
|
|
|
|||
|
|
@ -69,14 +69,38 @@
|
|||
</p>
|
||||
|
||||
<div class="hero-install">
|
||||
<div class="install-box">
|
||||
<code id="install-command">curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash</code>
|
||||
<button class="copy-btn" onclick="copyInstall()" title="Copy to clipboard">
|
||||
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
|
||||
<span class="copy-text">Copy</span>
|
||||
</button>
|
||||
<div class="install-widget">
|
||||
<div class="install-widget-header">
|
||||
<div class="install-dots">
|
||||
<span class="dot dot-red"></span>
|
||||
<span class="dot dot-yellow"></span>
|
||||
<span class="dot dot-green"></span>
|
||||
</div>
|
||||
<div class="install-tabs">
|
||||
<button class="install-tab active" data-platform="linux" onclick="switchPlatform('linux')">
|
||||
<svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" style="opacity:0.7"><path d="M12.504 0c-.155 0-.315.008-.48.021-4.226.333-3.105 4.807-3.17 6.298-.076 1.092-.3 1.953-1.05 3.02-.885 1.051-2.127 2.75-2.716 4.521-.278.832-.41 1.684-.287 2.489a.424.424 0 00-.11.135c-.26.268-.45.6-.663.839-.199.199-.485.267-.797.4-.313.136-.658.269-.864.68-.09.189-.136.394-.132.602 0 .199.027.4.055.536.058.399.116.728.04.97-.249.68-.28 1.145-.106 1.484.174.334.535.47.94.601.81.2 1.91.135 2.774.6.926.466 1.866.67 2.616.47.526-.116.97-.464 1.208-.946.587-.003 1.23-.269 2.26-.334.699-.058 1.574.267 2.577.2.025.134.063.198.114.333l.003.003c.391.778 1.113 1.368 1.884 1.43.39.03.8-.066 1.109-.199.69-.3 1.286-1.006 1.652-1.963.086-.235.188-.479.152-.88-.064-.406-.358-.597-.548-.899-.19-.301-.2-.335-.2-.68 0-.348.076-.664.152-.901.1-.256.233-.478.21-.783l-.003-.003c-.091-.472-.279-.861-.607-1.144-.327-.283-.762-.409-1.032-.433-.18-.04-.33-.063-.44-.143-.12-.09-.21-.29-.19-.543 .029-.272.089-.549.178-.822.188-.57.456-1.128.748-1.633.02-.044.04-.09.06-.133a.205.205 0 00.015-.04c.413-.916.64-1.866.64-2.699 0-1.039-.258-1.904-.608-2.572-.11-.188-.208-.368-.32-.527a.604.604 0 00-.038-.06c-.725-1.05-1.735-1.572-2.74-1.795a6.986 6.986 0 00-1.18-.133h-.005c-.163 0-.32.01-.478.025z"/></svg>
|
||||
Linux / macOS
|
||||
</button>
|
||||
<button class="install-tab" data-platform="powershell" onclick="switchPlatform('powershell')">
|
||||
<svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" style="opacity:0.7"><path d="M0 3.449L9.75 2.1v9.451H0m10.949-9.602L24 0v11.4H10.949M0 12.6h9.75v9.451L0 20.699M10.949 12.6H24V24l-12.9-1.801"/></svg>
|
||||
PowerShell
|
||||
</button>
|
||||
<button class="install-tab" data-platform="cmd" onclick="switchPlatform('cmd')">
|
||||
<svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" style="opacity:0.7"><path d="M0 3.449L9.75 2.1v9.451H0m10.949-9.602L24 0v11.4H10.949M0 12.6h9.75v9.451L0 20.699M10.949 12.6H24V24l-12.9-1.801"/></svg>
|
||||
CMD
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
<div class="install-widget-body">
|
||||
<span class="install-prompt" id="install-prompt">$</span>
|
||||
<code id="install-command">curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash</code>
|
||||
<button class="copy-btn" onclick="copyInstall()" title="Copy to clipboard">
|
||||
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
|
||||
<span class="copy-text">Copy</span>
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
<p class="install-note">Works on Linux & macOS · No Python prerequisite · Installs everything automatically</p>
|
||||
<p class="install-note" id="install-note">Works on Linux, macOS & WSL · No prerequisites · Installs everything automatically</p>
|
||||
</div>
|
||||
|
||||
<div class="hero-links">
|
||||
|
|
@ -330,12 +354,16 @@
|
|||
<h4>Install</h4>
|
||||
<div class="code-block">
|
||||
<div class="code-header">
|
||||
<span>bash</span>
|
||||
<button class="copy-btn" onclick="copyText(this)" data-text="curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash">Copy</button>
|
||||
<div class="code-tabs">
|
||||
<button class="code-tab active" data-platform="linux" onclick="switchStepPlatform('linux')">Linux / macOS</button>
|
||||
<button class="code-tab" data-platform="powershell" onclick="switchStepPlatform('powershell')">PowerShell</button>
|
||||
<button class="code-tab" data-platform="cmd" onclick="switchStepPlatform('cmd')">CMD</button>
|
||||
</div>
|
||||
<button class="copy-btn" id="step1-copy" onclick="copyText(this)" data-text="curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash">Copy</button>
|
||||
</div>
|
||||
<pre><code>curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash</code></pre>
|
||||
<pre><code id="step1-command">curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash</code></pre>
|
||||
</div>
|
||||
<p class="step-note">Installs uv, Python 3.11, clones the repo, sets up everything. No sudo needed.</p>
|
||||
<p class="step-note" id="step1-note">Installs uv, Python 3.11, clones the repo, sets up everything. No sudo needed.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
|
@ -394,14 +422,7 @@ hermes gateway install</code></pre>
|
|||
</div>
|
||||
|
||||
<div class="install-windows">
|
||||
<p>Windows? Use WSL or PowerShell:</p>
|
||||
<div class="code-block code-block-sm">
|
||||
<div class="code-header">
|
||||
<span>powershell</span>
|
||||
<button class="copy-btn" onclick="copyText(this)" data-text="irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex">Copy</button>
|
||||
</div>
|
||||
<pre><code>irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex</code></pre>
|
||||
</div>
|
||||
<p>🪟 Windows requires <a href="https://git-scm.com/download/win" target="_blank" rel="noopener">Git for Windows</a> — Hermes uses Git Bash internally for shell commands.</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
|
|
|||
|
|
@ -2,11 +2,79 @@
|
|||
// Hermes Agent Landing Page — Interactions
|
||||
// =========================================================================
|
||||
|
||||
// --- Platform install commands ---
|
||||
const PLATFORMS = {
|
||||
linux: {
|
||||
command: 'curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash',
|
||||
prompt: '$',
|
||||
note: 'Works on Linux, macOS & WSL · No prerequisites · Installs everything automatically',
|
||||
stepNote: 'Installs uv, Python 3.11, clones the repo, sets up everything. No sudo needed.',
|
||||
},
|
||||
powershell: {
|
||||
command: 'irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex',
|
||||
prompt: 'PS>',
|
||||
note: 'Windows PowerShell · Requires Git for Windows · Installs everything automatically',
|
||||
stepNote: 'Requires Git for Windows. Installs uv, Python 3.11, sets up everything.',
|
||||
},
|
||||
cmd: {
|
||||
command: 'curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.cmd -o install.cmd && install.cmd && del install.cmd',
|
||||
prompt: '>',
|
||||
note: 'Windows CMD · Requires Git for Windows · Installs everything automatically',
|
||||
stepNote: 'Requires Git for Windows. Downloads and runs the installer, then cleans up.',
|
||||
},
|
||||
};
|
||||
|
||||
function detectPlatform() {
|
||||
const ua = navigator.userAgent.toLowerCase();
|
||||
if (ua.includes('win')) return 'powershell';
|
||||
return 'linux';
|
||||
}
|
||||
|
||||
function switchPlatform(platform) {
|
||||
const cfg = PLATFORMS[platform];
|
||||
if (!cfg) return;
|
||||
|
||||
// Update hero install widget
|
||||
const commandEl = document.getElementById('install-command');
|
||||
const promptEl = document.getElementById('install-prompt');
|
||||
const noteEl = document.getElementById('install-note');
|
||||
|
||||
if (commandEl) commandEl.textContent = cfg.command;
|
||||
if (promptEl) promptEl.textContent = cfg.prompt;
|
||||
if (noteEl) noteEl.textContent = cfg.note;
|
||||
|
||||
// Update active tab in hero
|
||||
document.querySelectorAll('.install-tab').forEach(tab => {
|
||||
tab.classList.toggle('active', tab.dataset.platform === platform);
|
||||
});
|
||||
|
||||
// Sync the step section tabs too
|
||||
switchStepPlatform(platform);
|
||||
}
|
||||
|
||||
function switchStepPlatform(platform) {
|
||||
const cfg = PLATFORMS[platform];
|
||||
if (!cfg) return;
|
||||
|
||||
const commandEl = document.getElementById('step1-command');
|
||||
const copyBtn = document.getElementById('step1-copy');
|
||||
const noteEl = document.getElementById('step1-note');
|
||||
|
||||
if (commandEl) commandEl.textContent = cfg.command;
|
||||
if (copyBtn) copyBtn.setAttribute('data-text', cfg.command);
|
||||
if (noteEl) noteEl.textContent = cfg.stepNote;
|
||||
|
||||
// Update active tab in step section
|
||||
document.querySelectorAll('.code-tab').forEach(tab => {
|
||||
tab.classList.toggle('active', tab.dataset.platform === platform);
|
||||
});
|
||||
}
|
||||
|
||||
// --- Copy to clipboard ---
|
||||
function copyInstall() {
|
||||
const text = document.getElementById('install-command').textContent;
|
||||
navigator.clipboard.writeText(text).then(() => {
|
||||
const btn = document.querySelector('.hero-install .copy-btn');
|
||||
const btn = document.querySelector('.install-widget-body .copy-btn');
|
||||
const original = btn.querySelector('.copy-text').textContent;
|
||||
btn.querySelector('.copy-text').textContent = 'Copied!';
|
||||
btn.style.color = 'var(--gold)';
|
||||
|
|
@ -243,6 +311,10 @@ class TerminalDemo {
|
|||
|
||||
// --- Initialize ---
|
||||
document.addEventListener('DOMContentLoaded', () => {
|
||||
// Auto-detect platform and set the right install command
|
||||
const detectedPlatform = detectPlatform();
|
||||
switchPlatform(detectedPlatform);
|
||||
|
||||
initScrollAnimations();
|
||||
|
||||
// Terminal demo - start when visible
|
||||
|
|
|
|||
|
|
@ -245,33 +245,132 @@ strong {
|
|||
margin-bottom: 32px;
|
||||
}
|
||||
|
||||
.install-box {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0;
|
||||
/* --- Install Widget (hero tabbed installer) --- */
|
||||
.install-widget {
|
||||
max-width: 740px;
|
||||
margin: 0 auto;
|
||||
background: var(--bg-card);
|
||||
border: 1px solid var(--border);
|
||||
border-radius: var(--radius);
|
||||
overflow: hidden;
|
||||
transition: border-color 0.3s;
|
||||
}
|
||||
|
||||
.install-widget:hover {
|
||||
border-color: var(--border-hover);
|
||||
}
|
||||
|
||||
.install-widget-header {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 16px;
|
||||
padding: 10px 16px;
|
||||
background: rgba(255, 255, 255, 0.02);
|
||||
border-bottom: 1px solid var(--border);
|
||||
}
|
||||
|
||||
.install-dots {
|
||||
display: flex;
|
||||
gap: 6px;
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
.install-dots .dot {
|
||||
width: 10px;
|
||||
height: 10px;
|
||||
border-radius: 50%;
|
||||
}
|
||||
|
||||
.install-tabs {
|
||||
display: flex;
|
||||
gap: 4px;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.install-tab {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 6px;
|
||||
padding: 5px 14px;
|
||||
border: none;
|
||||
border-radius: 6px;
|
||||
font-family: var(--font-sans);
|
||||
font-size: 12px;
|
||||
font-weight: 500;
|
||||
cursor: pointer;
|
||||
transition: all 0.2s;
|
||||
background: transparent;
|
||||
color: var(--text-muted);
|
||||
}
|
||||
|
||||
.install-tab:hover {
|
||||
color: var(--text-dim);
|
||||
background: rgba(255, 255, 255, 0.04);
|
||||
}
|
||||
|
||||
.install-tab.active {
|
||||
background: rgba(255, 215, 0, 0.12);
|
||||
color: var(--gold);
|
||||
}
|
||||
|
||||
.install-tab svg {
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
.install-widget-body {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 10px;
|
||||
padding: 14px 16px;
|
||||
max-width: 680px;
|
||||
margin: 0 auto;
|
||||
font-family: var(--font-mono);
|
||||
font-size: 13px;
|
||||
color: var(--text);
|
||||
overflow-x: auto;
|
||||
transition: border-color 0.3s;
|
||||
}
|
||||
|
||||
.install-box:hover {
|
||||
border-color: var(--border-hover);
|
||||
.install-prompt {
|
||||
color: var(--gold);
|
||||
font-weight: 600;
|
||||
flex-shrink: 0;
|
||||
opacity: 0.7;
|
||||
}
|
||||
|
||||
.install-box code {
|
||||
.install-widget-body code {
|
||||
flex: 1;
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
text-align: left;
|
||||
transition: opacity 0.15s;
|
||||
}
|
||||
|
||||
/* --- Code block tabs (install step section) --- */
|
||||
.code-tabs {
|
||||
display: flex;
|
||||
gap: 2px;
|
||||
}
|
||||
|
||||
.code-tab {
|
||||
padding: 3px 10px;
|
||||
border: none;
|
||||
border-radius: 4px;
|
||||
font-family: var(--font-mono);
|
||||
font-size: 11px;
|
||||
font-weight: 500;
|
||||
cursor: pointer;
|
||||
transition: all 0.2s;
|
||||
background: transparent;
|
||||
color: var(--text-muted);
|
||||
}
|
||||
|
||||
.code-tab:hover {
|
||||
color: var(--text-dim);
|
||||
background: rgba(255, 255, 255, 0.04);
|
||||
}
|
||||
|
||||
.code-tab.active {
|
||||
background: rgba(255, 215, 0, 0.1);
|
||||
color: var(--gold);
|
||||
}
|
||||
|
||||
.copy-btn {
|
||||
|
|
@ -948,17 +1047,35 @@ strong {
|
|||
margin: 0 auto 28px;
|
||||
}
|
||||
|
||||
.install-box {
|
||||
.install-widget-body {
|
||||
font-size: 10px;
|
||||
padding: 10px 12px;
|
||||
}
|
||||
|
||||
.install-box code {
|
||||
.install-widget-body code {
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.install-widget-header {
|
||||
padding: 8px 12px;
|
||||
gap: 10px;
|
||||
}
|
||||
|
||||
.install-tabs {
|
||||
gap: 2px;
|
||||
}
|
||||
|
||||
.install-tab {
|
||||
padding: 4px 10px;
|
||||
font-size: 11px;
|
||||
}
|
||||
|
||||
.install-tab svg {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.copy-btn {
|
||||
padding: 3px 6px;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -105,6 +105,13 @@ def _discover_tools():
|
|||
|
||||
_discover_tools()
|
||||
|
||||
# MCP tool discovery (external MCP servers from config)
|
||||
try:
|
||||
from tools.mcp_tool import discover_mcp_tools
|
||||
discover_mcp_tools()
|
||||
except Exception as e:
|
||||
logger.debug("MCP tool discovery failed: %s", e)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Backward-compat constants (built once after discovery)
|
||||
|
|
|
|||
|
|
@ -47,6 +47,7 @@ cli = ["simple-term-menu"]
|
|||
tts-premium = ["elevenlabs"]
|
||||
pty = ["ptyprocess>=0.7.0"]
|
||||
honcho = ["honcho-ai>=2.0.1"]
|
||||
mcp = ["mcp>=1.2.0"]
|
||||
all = [
|
||||
"hermes-agent[modal]",
|
||||
"hermes-agent[messaging]",
|
||||
|
|
@ -57,6 +58,7 @@ all = [
|
|||
"hermes-agent[slack]",
|
||||
"hermes-agent[pty]",
|
||||
"hermes-agent[honcho]",
|
||||
"hermes-agent[mcp]",
|
||||
]
|
||||
|
||||
[project.scripts]
|
||||
|
|
|
|||
28
scripts/install.cmd
Normal file
28
scripts/install.cmd
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
@echo off
|
||||
REM ============================================================================
|
||||
REM Hermes Agent Installer for Windows (CMD wrapper)
|
||||
REM ============================================================================
|
||||
REM This batch file launches the PowerShell installer for users running CMD.
|
||||
REM
|
||||
REM Usage:
|
||||
REM curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.cmd -o install.cmd && install.cmd && del install.cmd
|
||||
REM
|
||||
REM Or if you're already in PowerShell, use the direct command instead:
|
||||
REM irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
|
||||
REM ============================================================================
|
||||
|
||||
echo.
|
||||
echo Hermes Agent Installer
|
||||
echo Launching PowerShell installer...
|
||||
echo.
|
||||
|
||||
powershell -ExecutionPolicy ByPass -NoProfile -Command "irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex"
|
||||
|
||||
if %ERRORLEVEL% NEQ 0 (
|
||||
echo.
|
||||
echo Installation failed. Please try running PowerShell directly:
|
||||
echo powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex"
|
||||
echo.
|
||||
pause
|
||||
exit /b 1
|
||||
)
|
||||
|
|
@ -16,8 +16,8 @@ param(
|
|||
[switch]$NoVenv,
|
||||
[switch]$SkipSetup,
|
||||
[string]$Branch = "main",
|
||||
[string]$HermesHome = "$env:USERPROFILE\.hermes",
|
||||
[string]$InstallDir = "$env:USERPROFILE\.hermes\hermes-agent"
|
||||
[string]$HermesHome = "$env:LOCALAPPDATA\hermes",
|
||||
[string]$InstallDir = "$env:LOCALAPPDATA\hermes\hermes-agent"
|
||||
)
|
||||
|
||||
$ErrorActionPreference = "Stop"
|
||||
|
|
@ -145,17 +145,49 @@ function Test-Python {
|
|||
# Python not found — use uv to install it (no admin needed!)
|
||||
Write-Info "Python $PythonVersion not found, installing via uv..."
|
||||
try {
|
||||
& $UvCmd python install $PythonVersion 2>&1 | Out-Null
|
||||
$pythonPath = & $UvCmd python find $PythonVersion 2>$null
|
||||
if ($pythonPath) {
|
||||
$ver = & $pythonPath --version 2>$null
|
||||
Write-Success "Python installed: $ver"
|
||||
$uvOutput = & $UvCmd python install $PythonVersion 2>&1
|
||||
if ($LASTEXITCODE -eq 0) {
|
||||
$pythonPath = & $UvCmd python find $PythonVersion 2>$null
|
||||
if ($pythonPath) {
|
||||
$ver = & $pythonPath --version 2>$null
|
||||
Write-Success "Python installed: $ver"
|
||||
return $true
|
||||
}
|
||||
} else {
|
||||
Write-Warn "uv python install output:"
|
||||
Write-Host $uvOutput -ForegroundColor DarkGray
|
||||
}
|
||||
} catch {
|
||||
Write-Warn "uv python install error: $_"
|
||||
}
|
||||
|
||||
# Fallback: check if ANY Python 3.10+ is already available on the system
|
||||
Write-Info "Trying to find any existing Python 3.10+..."
|
||||
foreach ($fallbackVer in @("3.12", "3.13", "3.10")) {
|
||||
try {
|
||||
$pythonPath = & $UvCmd python find $fallbackVer 2>$null
|
||||
if ($pythonPath) {
|
||||
$ver = & $pythonPath --version 2>$null
|
||||
Write-Success "Found fallback: $ver"
|
||||
$script:PythonVersion = $fallbackVer
|
||||
return $true
|
||||
}
|
||||
} catch { }
|
||||
}
|
||||
|
||||
# Fallback: try system python
|
||||
if (Get-Command python -ErrorAction SilentlyContinue) {
|
||||
$sysVer = python --version 2>$null
|
||||
if ($sysVer -match "3\.(1[0-9]|[1-9][0-9])") {
|
||||
Write-Success "Using system Python: $sysVer"
|
||||
return $true
|
||||
}
|
||||
} catch { }
|
||||
}
|
||||
|
||||
Write-Err "Failed to install Python $PythonVersion"
|
||||
Write-Info "Install Python $PythonVersion manually, then re-run this script"
|
||||
Write-Info "Install Python 3.11 manually, then re-run this script:"
|
||||
Write-Info " https://www.python.org/downloads/"
|
||||
Write-Info " Or: winget install Python.Python.3.11"
|
||||
return $false
|
||||
}
|
||||
|
||||
|
|
@ -384,48 +416,103 @@ function Install-Repository {
|
|||
if (Test-Path "$InstallDir\.git") {
|
||||
Write-Info "Existing installation found, updating..."
|
||||
Push-Location $InstallDir
|
||||
git fetch origin
|
||||
git checkout $Branch
|
||||
git pull origin $Branch
|
||||
git -c windows.appendAtomically=false fetch origin
|
||||
git -c windows.appendAtomically=false checkout $Branch
|
||||
git -c windows.appendAtomically=false pull origin $Branch
|
||||
Pop-Location
|
||||
} else {
|
||||
Write-Err "Directory exists but is not a git repository: $InstallDir"
|
||||
Write-Info "Remove it or choose a different directory with -InstallDir"
|
||||
exit 1
|
||||
throw "Directory exists but is not a git repository: $InstallDir"
|
||||
}
|
||||
} else {
|
||||
# Try SSH first (for private repo access), fall back to HTTPS.
|
||||
# GIT_SSH_COMMAND with BatchMode=yes prevents SSH from hanging
|
||||
# when no key is configured (fails immediately instead of prompting).
|
||||
$cloneSuccess = $false
|
||||
|
||||
# Fix Windows git "copy-fd: write returned: Invalid argument" error.
|
||||
# Git for Windows can fail on atomic file operations (hook templates,
|
||||
# config lock files) due to antivirus, OneDrive, or NTFS filter drivers.
|
||||
# The -c flag injects config before any file I/O occurs.
|
||||
Write-Info "Configuring git for Windows compatibility..."
|
||||
$env:GIT_CONFIG_COUNT = "1"
|
||||
$env:GIT_CONFIG_KEY_0 = "windows.appendAtomically"
|
||||
$env:GIT_CONFIG_VALUE_0 = "false"
|
||||
git config --global windows.appendAtomically false 2>$null
|
||||
|
||||
# Try SSH first, then HTTPS, with -c flag for atomic write fix
|
||||
Write-Info "Trying SSH clone..."
|
||||
$env:GIT_SSH_COMMAND = "ssh -o BatchMode=yes -o ConnectTimeout=5"
|
||||
$sshResult = git clone --branch $Branch --recurse-submodules $RepoUrlSsh $InstallDir 2>&1
|
||||
$sshExitCode = $LASTEXITCODE
|
||||
try {
|
||||
git -c windows.appendAtomically=false clone --branch $Branch --recurse-submodules $RepoUrlSsh $InstallDir
|
||||
if ($LASTEXITCODE -eq 0) { $cloneSuccess = $true }
|
||||
} catch { }
|
||||
$env:GIT_SSH_COMMAND = $null
|
||||
|
||||
if ($sshExitCode -eq 0) {
|
||||
Write-Success "Cloned via SSH"
|
||||
} else {
|
||||
# Clean up partial SSH clone before retrying
|
||||
if (-not $cloneSuccess) {
|
||||
if (Test-Path $InstallDir) { Remove-Item -Recurse -Force $InstallDir -ErrorAction SilentlyContinue }
|
||||
Write-Info "SSH failed, trying HTTPS..."
|
||||
$httpsResult = git clone --branch $Branch --recurse-submodules $RepoUrlHttps $InstallDir 2>&1
|
||||
|
||||
if ($LASTEXITCODE -eq 0) {
|
||||
Write-Success "Cloned via HTTPS"
|
||||
} else {
|
||||
Write-Err "Failed to clone repository"
|
||||
exit 1
|
||||
try {
|
||||
git -c windows.appendAtomically=false clone --branch $Branch --recurse-submodules $RepoUrlHttps $InstallDir
|
||||
if ($LASTEXITCODE -eq 0) { $cloneSuccess = $true }
|
||||
} catch { }
|
||||
}
|
||||
|
||||
# Fallback: download ZIP archive (bypasses git file I/O issues entirely)
|
||||
if (-not $cloneSuccess) {
|
||||
if (Test-Path $InstallDir) { Remove-Item -Recurse -Force $InstallDir -ErrorAction SilentlyContinue }
|
||||
Write-Warn "Git clone failed — downloading ZIP archive instead..."
|
||||
try {
|
||||
$zipUrl = "https://github.com/NousResearch/hermes-agent/archive/refs/heads/$Branch.zip"
|
||||
$zipPath = "$env:TEMP\hermes-agent-$Branch.zip"
|
||||
$extractPath = "$env:TEMP\hermes-agent-extract"
|
||||
|
||||
Invoke-WebRequest -Uri $zipUrl -OutFile $zipPath -UseBasicParsing
|
||||
if (Test-Path $extractPath) { Remove-Item -Recurse -Force $extractPath }
|
||||
Expand-Archive -Path $zipPath -DestinationPath $extractPath -Force
|
||||
|
||||
# GitHub ZIPs extract to repo-branch/ subdirectory
|
||||
$extractedDir = Get-ChildItem $extractPath -Directory | Select-Object -First 1
|
||||
if ($extractedDir) {
|
||||
New-Item -ItemType Directory -Force -Path (Split-Path $InstallDir) -ErrorAction SilentlyContinue | Out-Null
|
||||
Move-Item $extractedDir.FullName $InstallDir -Force
|
||||
Write-Success "Downloaded and extracted"
|
||||
|
||||
# Initialize git repo so updates work later
|
||||
Push-Location $InstallDir
|
||||
git -c windows.appendAtomically=false init 2>$null
|
||||
git -c windows.appendAtomically=false config windows.appendAtomically false 2>$null
|
||||
git remote add origin $RepoUrlHttps 2>$null
|
||||
Pop-Location
|
||||
Write-Success "Git repo initialized for future updates"
|
||||
|
||||
$cloneSuccess = $true
|
||||
}
|
||||
|
||||
# Cleanup temp files
|
||||
Remove-Item -Force $zipPath -ErrorAction SilentlyContinue
|
||||
Remove-Item -Recurse -Force $extractPath -ErrorAction SilentlyContinue
|
||||
} catch {
|
||||
Write-Err "ZIP download also failed: $_"
|
||||
}
|
||||
}
|
||||
|
||||
if (-not $cloneSuccess) {
|
||||
throw "Failed to download repository (tried git clone SSH, HTTPS, and ZIP)"
|
||||
}
|
||||
}
|
||||
|
||||
# Set per-repo config (harmless if it fails)
|
||||
Push-Location $InstallDir
|
||||
git -c windows.appendAtomically=false config windows.appendAtomically false 2>$null
|
||||
|
||||
# Ensure submodules are initialized and updated
|
||||
Write-Info "Initializing submodules (mini-swe-agent, tinker-atropos)..."
|
||||
Push-Location $InstallDir
|
||||
git submodule update --init --recursive
|
||||
git -c windows.appendAtomically=false submodule update --init --recursive 2>$null
|
||||
if ($LASTEXITCODE -ne 0) {
|
||||
Write-Warn "Submodule init failed (terminal/RL tools may need manual setup)"
|
||||
} else {
|
||||
Write-Success "Submodules ready"
|
||||
}
|
||||
Pop-Location
|
||||
Write-Success "Submodules ready"
|
||||
|
||||
Write-Success "Repository ready"
|
||||
}
|
||||
|
|
@ -526,6 +613,16 @@ function Set-PathVariable {
|
|||
Write-Info "PATH already configured"
|
||||
}
|
||||
|
||||
# Set HERMES_HOME so the Python code finds config/data in the right place.
|
||||
# Only needed on Windows where we install to %LOCALAPPDATA%\hermes instead
|
||||
# of the Unix default ~/.hermes
|
||||
$currentHermesHome = [Environment]::GetEnvironmentVariable("HERMES_HOME", "User")
|
||||
if (-not $currentHermesHome -or $currentHermesHome -ne $HermesHome) {
|
||||
[Environment]::SetEnvironmentVariable("HERMES_HOME", $HermesHome, "User")
|
||||
Write-Success "Set HERMES_HOME=$HermesHome"
|
||||
}
|
||||
$env:HERMES_HOME = $HermesHome
|
||||
|
||||
# Update current session
|
||||
$env:Path = "$hermesBin;$env:Path"
|
||||
|
||||
|
|
@ -744,7 +841,7 @@ function Write-Completion {
|
|||
Write-Host ""
|
||||
|
||||
# Show file locations
|
||||
Write-Host "📁 Your files (all in ~/.hermes/):" -ForegroundColor Cyan
|
||||
Write-Host "📁 Your files:" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
Write-Host " Config: " -NoNewline -ForegroundColor Yellow
|
||||
Write-Host "$HermesHome\config.yaml"
|
||||
|
|
@ -800,9 +897,9 @@ function Write-Completion {
|
|||
function Main {
|
||||
Write-Banner
|
||||
|
||||
if (-not (Install-Uv)) { exit 1 }
|
||||
if (-not (Test-Python)) { exit 1 }
|
||||
if (-not (Test-Git)) { exit 1 }
|
||||
if (-not (Install-Uv)) { throw "uv installation failed — cannot continue" }
|
||||
if (-not (Test-Python)) { throw "Python $PythonVersion not available — cannot continue" }
|
||||
if (-not (Test-Git)) { throw "Git not found — install from https://git-scm.com/download/win" }
|
||||
Test-Node # Auto-installs if missing
|
||||
Install-SystemPackages # ripgrep + ffmpeg in one step
|
||||
|
||||
|
|
@ -818,4 +915,17 @@ function Main {
|
|||
Write-Completion
|
||||
}
|
||||
|
||||
Main
|
||||
# Wrap in try/catch so errors don't kill the terminal when run via:
|
||||
# irm https://...install.ps1 | iex
|
||||
# (exit/throw inside iex kills the entire PowerShell session)
|
||||
try {
|
||||
Main
|
||||
} catch {
|
||||
Write-Host ""
|
||||
Write-Err "Installation failed: $_"
|
||||
Write-Host ""
|
||||
Write-Info "If the error is unclear, try downloading and running the script directly:"
|
||||
Write-Host " Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1' -OutFile install.ps1" -ForegroundColor Yellow
|
||||
Write-Host " .\install.ps1" -ForegroundColor Yellow
|
||||
Write-Host ""
|
||||
}
|
||||
|
|
|
|||
|
|
@ -34,6 +34,7 @@ function getArg(name, defaultVal) {
|
|||
const PORT = parseInt(getArg('port', '3000'), 10);
|
||||
const SESSION_DIR = getArg('session', path.join(process.env.HOME || '~', '.hermes', 'whatsapp', 'session'));
|
||||
const PAIR_ONLY = args.includes('--pair-only');
|
||||
const WHATSAPP_MODE = getArg('mode', process.env.WHATSAPP_MODE || 'self-chat'); // "bot" or "self-chat"
|
||||
const ALLOWED_USERS = (process.env.WHATSAPP_ALLOWED_USERS || '').split(',').map(s => s.trim()).filter(Boolean);
|
||||
|
||||
mkdirSync(SESSION_DIR, { recursive: true });
|
||||
|
|
@ -110,11 +111,16 @@ async function startSocket() {
|
|||
const isGroup = chatId.endsWith('@g.us');
|
||||
const senderNumber = senderId.replace(/@.*/, '');
|
||||
|
||||
// Skip own messages UNLESS it's a self-chat ("Message Yourself")
|
||||
// Handle fromMe messages based on mode
|
||||
if (msg.key.fromMe) {
|
||||
// Always skip in groups and status
|
||||
if (isGroup || chatId.includes('status')) continue;
|
||||
// In DMs: only allow self-chat (remoteJid matches our own number)
|
||||
|
||||
if (WHATSAPP_MODE === 'bot') {
|
||||
// Bot mode: separate number. ALL fromMe are echo-backs of our own replies — skip.
|
||||
continue;
|
||||
}
|
||||
|
||||
// Self-chat mode: only allow messages in the user's own self-chat
|
||||
const myNumber = (sock.user?.id || '').replace(/:.*@/, '@').replace(/@.*/, '');
|
||||
const chatNumber = chatId.replace(/@.*/, '');
|
||||
const isSelfChat = myNumber && chatNumber === myNumber;
|
||||
|
|
@ -270,7 +276,7 @@ if (PAIR_ONLY) {
|
|||
startSocket();
|
||||
} else {
|
||||
app.listen(PORT, () => {
|
||||
console.log(`🌉 WhatsApp bridge listening on port ${PORT}`);
|
||||
console.log(`🌉 WhatsApp bridge listening on port ${PORT} (mode: ${WHATSAPP_MODE})`);
|
||||
console.log(`📁 Session stored in: ${SESSION_DIR}`);
|
||||
if (ALLOWED_USERS.length > 0) {
|
||||
console.log(`🔒 Allowed users: ${ALLOWED_USERS.join(', ')}`);
|
||||
|
|
|
|||
|
|
@ -1,3 +1,3 @@
|
|||
---
|
||||
description: Skills for working with MCP (Model Context Protocol) servers, tools, and integrations.
|
||||
description: Skills for working with MCP (Model Context Protocol) servers, tools, and integrations. Includes the built-in native MCP client (configure servers in config.yaml for automatic tool discovery) and the mcporter CLI bridge for ad-hoc server interaction.
|
||||
---
|
||||
|
|
|
|||
330
skills/mcp/native-mcp/SKILL.md
Normal file
330
skills/mcp/native-mcp/SKILL.md
Normal file
|
|
@ -0,0 +1,330 @@
|
|||
---
|
||||
name: native-mcp
|
||||
description: Built-in MCP (Model Context Protocol) client that connects to external MCP servers, discovers their tools, and registers them as native Hermes Agent tools. Supports stdio and HTTP transports with automatic reconnection, security filtering, and zero-config tool injection.
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [MCP, Tools, Integrations]
|
||||
related_skills: [mcporter]
|
||||
---
|
||||
|
||||
# Native MCP Client
|
||||
|
||||
Hermes Agent has a built-in MCP client that connects to MCP servers at startup, discovers their tools, and makes them available as first-class tools the agent can call directly. No bridge CLI needed -- tools from MCP servers appear alongside built-in tools like `terminal`, `read_file`, etc.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this whenever you want to:
|
||||
- Connect to MCP servers and use their tools from within Hermes Agent
|
||||
- Add external capabilities (filesystem access, GitHub, databases, APIs) via MCP
|
||||
- Run local stdio-based MCP servers (npx, uvx, or any command)
|
||||
- Connect to remote HTTP/StreamableHTTP MCP servers
|
||||
- Have MCP tools auto-discovered and available in every conversation
|
||||
|
||||
For ad-hoc, one-off MCP tool calls from the terminal without configuring anything, see the `mcporter` skill instead.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **mcp Python package** -- optional dependency; install with `pip install mcp`. If not installed, MCP support is silently disabled.
|
||||
- **Node.js** -- required for `npx`-based MCP servers (most community servers)
|
||||
- **uv** -- required for `uvx`-based MCP servers (Python-based servers)
|
||||
|
||||
Install the MCP SDK:
|
||||
|
||||
```bash
|
||||
pip install mcp
|
||||
# or, if using uv:
|
||||
uv pip install mcp
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
Add MCP servers to `~/.hermes/config.yaml` under the `mcp_servers` key:
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
time:
|
||||
command: "uvx"
|
||||
args: ["mcp-server-time"]
|
||||
```
|
||||
|
||||
Restart Hermes Agent. On startup it will:
|
||||
1. Connect to the server
|
||||
2. Discover available tools
|
||||
3. Register them with the prefix `mcp_time_*`
|
||||
4. Inject them into all platform toolsets
|
||||
|
||||
You can then use the tools naturally -- just ask the agent to get the current time.
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
Each entry under `mcp_servers` is a server name mapped to its config. There are two transport types: **stdio** (command-based) and **HTTP** (url-based).
|
||||
|
||||
### Stdio Transport (command + args)
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
server_name:
|
||||
command: "npx" # (required) executable to run
|
||||
args: ["-y", "pkg-name"] # (optional) command arguments, default: []
|
||||
env: # (optional) environment variables for the subprocess
|
||||
SOME_API_KEY: "value"
|
||||
timeout: 120 # (optional) per-tool-call timeout in seconds, default: 120
|
||||
connect_timeout: 60 # (optional) initial connection timeout in seconds, default: 60
|
||||
```
|
||||
|
||||
### HTTP Transport (url)
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
server_name:
|
||||
url: "https://my-server.example.com/mcp" # (required) server URL
|
||||
headers: # (optional) HTTP headers
|
||||
Authorization: "Bearer sk-..."
|
||||
timeout: 180 # (optional) per-tool-call timeout in seconds, default: 120
|
||||
connect_timeout: 60 # (optional) initial connection timeout in seconds, default: 60
|
||||
```
|
||||
|
||||
### All Config Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|-------------------|--------|---------|---------------------------------------------------|
|
||||
| `command` | string | -- | Executable to run (stdio transport, required) |
|
||||
| `args` | list | `[]` | Arguments passed to the command |
|
||||
| `env` | dict | `{}` | Extra environment variables for the subprocess |
|
||||
| `url` | string | -- | Server URL (HTTP transport, required) |
|
||||
| `headers` | dict | `{}` | HTTP headers sent with every request |
|
||||
| `timeout` | int | `120` | Per-tool-call timeout in seconds |
|
||||
| `connect_timeout` | int | `60` | Timeout for initial connection and discovery |
|
||||
|
||||
Note: A server config must have either `command` (stdio) or `url` (HTTP), not both.
|
||||
|
||||
## How It Works
|
||||
|
||||
### Startup Discovery
|
||||
|
||||
When Hermes Agent starts, `discover_mcp_tools()` is called during tool initialization:
|
||||
|
||||
1. Reads `mcp_servers` from `~/.hermes/config.yaml`
|
||||
2. For each server, spawns a connection in a dedicated background event loop
|
||||
3. Initializes the MCP session and calls `list_tools()` to discover available tools
|
||||
4. Registers each tool in the Hermes tool registry
|
||||
|
||||
### Tool Naming Convention
|
||||
|
||||
MCP tools are registered with the naming pattern:
|
||||
|
||||
```
|
||||
mcp_{server_name}_{tool_name}
|
||||
```
|
||||
|
||||
Hyphens and dots in names are replaced with underscores for LLM API compatibility.
|
||||
|
||||
Examples:
|
||||
- Server `filesystem`, tool `read_file` → `mcp_filesystem_read_file`
|
||||
- Server `github`, tool `list-issues` → `mcp_github_list_issues`
|
||||
- Server `my-api`, tool `fetch.data` → `mcp_my_api_fetch_data`
|
||||
|
||||
### Auto-Injection
|
||||
|
||||
After discovery, MCP tools are automatically injected into all `hermes-*` platform toolsets (CLI, Discord, Telegram, etc.). This means MCP tools are available in every conversation without any additional configuration.
|
||||
|
||||
### Connection Lifecycle
|
||||
|
||||
- Each server runs as a long-lived asyncio Task in a background daemon thread
|
||||
- Connections persist for the lifetime of the agent process
|
||||
- If a connection drops, automatic reconnection with exponential backoff kicks in (up to 5 retries, max 60s backoff)
|
||||
- On agent shutdown, all connections are gracefully closed
|
||||
|
||||
### Idempotency
|
||||
|
||||
`discover_mcp_tools()` is idempotent -- calling it multiple times only connects to servers that aren't already connected. Failed servers are retried on subsequent calls.
|
||||
|
||||
## Transport Types
|
||||
|
||||
### Stdio Transport
|
||||
|
||||
The most common transport. Hermes launches the MCP server as a subprocess and communicates over stdin/stdout.
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
|
||||
```
|
||||
|
||||
The subprocess inherits a **filtered** environment (see Security section below) plus any variables you specify in `env`.
|
||||
|
||||
### HTTP / StreamableHTTP Transport
|
||||
|
||||
For remote or shared MCP servers. Requires the `mcp` package to include HTTP client support (`mcp.client.streamable_http`).
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
remote_api:
|
||||
url: "https://mcp.example.com/mcp"
|
||||
headers:
|
||||
Authorization: "Bearer sk-..."
|
||||
```
|
||||
|
||||
If HTTP support is not available in your installed `mcp` version, the server will fail with an ImportError and other servers will continue normally.
|
||||
|
||||
## Security
|
||||
|
||||
### Environment Variable Filtering
|
||||
|
||||
For stdio servers, Hermes does NOT pass your full shell environment to MCP subprocesses. Only safe baseline variables are inherited:
|
||||
|
||||
- `PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `TERM`, `SHELL`, `TMPDIR`
|
||||
- Any `XDG_*` variables
|
||||
|
||||
All other environment variables (API keys, tokens, secrets) are excluded unless you explicitly add them via the `env` config key. This prevents accidental credential leakage to untrusted MCP servers.
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
# Only this token is passed to the subprocess
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
|
||||
```
|
||||
|
||||
### Credential Stripping in Error Messages
|
||||
|
||||
If an MCP tool call fails, any credential-like patterns in the error message are automatically redacted before being shown to the LLM. This covers:
|
||||
|
||||
- GitHub PATs (`ghp_...`)
|
||||
- OpenAI-style keys (`sk-...`)
|
||||
- Bearer tokens
|
||||
- Generic `token=`, `key=`, `API_KEY=`, `password=`, `secret=` patterns
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "MCP SDK not available -- skipping MCP tool discovery"
|
||||
|
||||
The `mcp` Python package is not installed. Install it:
|
||||
|
||||
```bash
|
||||
pip install mcp
|
||||
```
|
||||
|
||||
### "No MCP servers configured"
|
||||
|
||||
No `mcp_servers` key in `~/.hermes/config.yaml`, or it's empty. Add at least one server.
|
||||
|
||||
### "Failed to connect to MCP server 'X'"
|
||||
|
||||
Common causes:
|
||||
- **Command not found**: The `command` binary isn't on PATH. Ensure `npx`, `uvx`, or the relevant command is installed.
|
||||
- **Package not found**: For npx servers, the npm package may not exist or may need `-y` in args to auto-install.
|
||||
- **Timeout**: The server took too long to start. Increase `connect_timeout`.
|
||||
- **Port conflict**: For HTTP servers, the URL may be unreachable.
|
||||
|
||||
### "MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available"
|
||||
|
||||
Your `mcp` package version doesn't include HTTP client support. Upgrade:
|
||||
|
||||
```bash
|
||||
pip install --upgrade mcp
|
||||
```
|
||||
|
||||
### Tools not appearing
|
||||
|
||||
- Check that the server is listed under `mcp_servers` (not `mcp` or `servers`)
|
||||
- Ensure the YAML indentation is correct
|
||||
- Look at Hermes Agent startup logs for connection messages
|
||||
- Tool names are prefixed with `mcp_{server}_{tool}` -- look for that pattern
|
||||
|
||||
### Connection keeps dropping
|
||||
|
||||
The client retries up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s, capped at 60s). If the server is fundamentally unreachable, it gives up after 5 attempts. Check the server process and network connectivity.
|
||||
|
||||
## Examples
|
||||
|
||||
### Time Server (uvx)
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
time:
|
||||
command: "uvx"
|
||||
args: ["mcp-server-time"]
|
||||
```
|
||||
|
||||
Registers tools like `mcp_time_get_current_time`.
|
||||
|
||||
### Filesystem Server (npx)
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
|
||||
timeout: 30
|
||||
```
|
||||
|
||||
Registers tools like `mcp_filesystem_read_file`, `mcp_filesystem_write_file`, `mcp_filesystem_list_directory`.
|
||||
|
||||
### GitHub Server with Authentication
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
|
||||
timeout: 60
|
||||
```
|
||||
|
||||
Registers tools like `mcp_github_list_issues`, `mcp_github_create_pull_request`, etc.
|
||||
|
||||
### Remote HTTP Server
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
company_api:
|
||||
url: "https://mcp.mycompany.com/v1/mcp"
|
||||
headers:
|
||||
Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
|
||||
X-Team-Id: "engineering"
|
||||
timeout: 180
|
||||
connect_timeout: 30
|
||||
```
|
||||
|
||||
### Multiple Servers
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
time:
|
||||
command: "uvx"
|
||||
args: ["mcp-server-time"]
|
||||
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
|
||||
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
|
||||
|
||||
company_api:
|
||||
url: "https://mcp.internal.company.com/mcp"
|
||||
headers:
|
||||
Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
|
||||
timeout: 300
|
||||
```
|
||||
|
||||
All tools from all servers are registered and available simultaneously. Each server's tools are prefixed with its name to avoid collisions.
|
||||
|
||||
## Notes
|
||||
|
||||
- MCP tools are called synchronously from the agent's perspective but run asynchronously on a dedicated background event loop
|
||||
- Tool results are returned as JSON with either `{"result": "..."}` or `{"error": "..."}`
|
||||
- The native MCP client is independent of `mcporter` -- you can use both simultaneously
|
||||
- Server connections are persistent and shared across all conversations in the same agent process
|
||||
- Adding or removing servers requires restarting the agent (no hot-reload currently)
|
||||
|
|
@ -89,6 +89,38 @@ def test_resolve_runtime_provider_auto_uses_custom_config_base_url(monkeypatch):
|
|||
assert resolved["base_url"] == "https://custom.example/v1"
|
||||
|
||||
|
||||
def test_openrouter_key_takes_priority_over_openai_key(monkeypatch):
|
||||
"""OPENROUTER_API_KEY should be used over OPENAI_API_KEY when both are set.
|
||||
|
||||
Regression test for #289: users with OPENAI_API_KEY in .bashrc had it
|
||||
sent to OpenRouter instead of their OPENROUTER_API_KEY.
|
||||
"""
|
||||
monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "openrouter")
|
||||
monkeypatch.setattr(rp, "_get_model_config", lambda: {})
|
||||
monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
|
||||
monkeypatch.delenv("OPENROUTER_BASE_URL", raising=False)
|
||||
monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-should-lose")
|
||||
monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-should-win")
|
||||
|
||||
resolved = rp.resolve_runtime_provider(requested="openrouter")
|
||||
|
||||
assert resolved["api_key"] == "sk-or-should-win"
|
||||
|
||||
|
||||
def test_openai_key_used_when_no_openrouter_key(monkeypatch):
|
||||
"""OPENAI_API_KEY is used as fallback when OPENROUTER_API_KEY is not set."""
|
||||
monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "openrouter")
|
||||
monkeypatch.setattr(rp, "_get_model_config", lambda: {})
|
||||
monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
|
||||
monkeypatch.delenv("OPENROUTER_BASE_URL", raising=False)
|
||||
monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-fallback")
|
||||
monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
|
||||
|
||||
resolved = rp.resolve_runtime_provider(requested="openrouter")
|
||||
|
||||
assert resolved["api_key"] == "sk-openai-fallback"
|
||||
|
||||
|
||||
def test_resolve_requested_provider_precedence(monkeypatch):
|
||||
monkeypatch.setenv("HERMES_INFERENCE_PROVIDER", "nous")
|
||||
monkeypatch.setattr(rp, "_get_model_config", lambda: {"provider": "openai-codex"})
|
||||
|
|
|
|||
1491
tests/tools/test_mcp_tool.py
Normal file
1491
tests/tools/test_mcp_tool.py
Normal file
File diff suppressed because it is too large
Load diff
126
tests/tools/test_skills_hub_clawhub.py
Normal file
126
tests/tools/test_skills_hub_clawhub.py
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
#!/usr/bin/env python3
|
||||
|
||||
import unittest
|
||||
from unittest.mock import patch
|
||||
|
||||
from tools.skills_hub import ClawHubSource
|
||||
|
||||
|
||||
class _MockResponse:
|
||||
def __init__(self, status_code=200, json_data=None, text=""):
|
||||
self.status_code = status_code
|
||||
self._json_data = json_data
|
||||
self.text = text
|
||||
|
||||
def json(self):
|
||||
return self._json_data
|
||||
|
||||
|
||||
class TestClawHubSource(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.src = ClawHubSource()
|
||||
|
||||
@patch("tools.skills_hub._write_index_cache")
|
||||
@patch("tools.skills_hub._read_index_cache", return_value=None)
|
||||
@patch("tools.skills_hub.httpx.get")
|
||||
def test_search_uses_new_endpoint_and_parses_items(self, mock_get, _mock_read_cache, _mock_write_cache):
|
||||
mock_get.return_value = _MockResponse(
|
||||
status_code=200,
|
||||
json_data={
|
||||
"items": [
|
||||
{
|
||||
"slug": "caldav-calendar",
|
||||
"displayName": "CalDAV Calendar",
|
||||
"summary": "Calendar integration",
|
||||
"tags": ["calendar", "productivity"],
|
||||
}
|
||||
]
|
||||
},
|
||||
)
|
||||
|
||||
results = self.src.search("caldav", limit=5)
|
||||
|
||||
self.assertEqual(len(results), 1)
|
||||
self.assertEqual(results[0].identifier, "caldav-calendar")
|
||||
self.assertEqual(results[0].name, "CalDAV Calendar")
|
||||
self.assertEqual(results[0].description, "Calendar integration")
|
||||
|
||||
mock_get.assert_called_once()
|
||||
args, kwargs = mock_get.call_args
|
||||
self.assertTrue(args[0].endswith("/skills"))
|
||||
self.assertEqual(kwargs["params"], {"search": "caldav", "limit": 5})
|
||||
|
||||
@patch("tools.skills_hub.httpx.get")
|
||||
def test_inspect_maps_display_name_and_summary(self, mock_get):
|
||||
mock_get.return_value = _MockResponse(
|
||||
status_code=200,
|
||||
json_data={
|
||||
"slug": "caldav-calendar",
|
||||
"displayName": "CalDAV Calendar",
|
||||
"summary": "Calendar integration",
|
||||
"tags": ["calendar"],
|
||||
},
|
||||
)
|
||||
|
||||
meta = self.src.inspect("caldav-calendar")
|
||||
|
||||
self.assertIsNotNone(meta)
|
||||
self.assertEqual(meta.name, "CalDAV Calendar")
|
||||
self.assertEqual(meta.description, "Calendar integration")
|
||||
self.assertEqual(meta.identifier, "caldav-calendar")
|
||||
|
||||
@patch("tools.skills_hub.httpx.get")
|
||||
def test_fetch_resolves_latest_version_and_downloads_raw_files(self, mock_get):
|
||||
def side_effect(url, *args, **kwargs):
|
||||
if url.endswith("/skills/caldav-calendar"):
|
||||
return _MockResponse(
|
||||
status_code=200,
|
||||
json_data={
|
||||
"slug": "caldav-calendar",
|
||||
"latestVersion": {"version": "1.0.1"},
|
||||
},
|
||||
)
|
||||
if url.endswith("/skills/caldav-calendar/versions/1.0.1"):
|
||||
return _MockResponse(
|
||||
status_code=200,
|
||||
json_data={
|
||||
"files": [
|
||||
{"path": "SKILL.md", "rawUrl": "https://files.example/skill-md"},
|
||||
{"path": "README.md", "content": "hello"},
|
||||
]
|
||||
},
|
||||
)
|
||||
if url == "https://files.example/skill-md":
|
||||
return _MockResponse(status_code=200, text="# Skill")
|
||||
return _MockResponse(status_code=404, json_data={})
|
||||
|
||||
mock_get.side_effect = side_effect
|
||||
|
||||
bundle = self.src.fetch("caldav-calendar")
|
||||
|
||||
self.assertIsNotNone(bundle)
|
||||
self.assertEqual(bundle.name, "caldav-calendar")
|
||||
self.assertIn("SKILL.md", bundle.files)
|
||||
self.assertEqual(bundle.files["SKILL.md"], "# Skill")
|
||||
self.assertEqual(bundle.files["README.md"], "hello")
|
||||
|
||||
@patch("tools.skills_hub.httpx.get")
|
||||
def test_fetch_falls_back_to_versions_list(self, mock_get):
|
||||
def side_effect(url, *args, **kwargs):
|
||||
if url.endswith("/skills/caldav-calendar"):
|
||||
return _MockResponse(status_code=200, json_data={"slug": "caldav-calendar"})
|
||||
if url.endswith("/skills/caldav-calendar/versions"):
|
||||
return _MockResponse(status_code=200, json_data=[{"version": "2.0.0"}])
|
||||
if url.endswith("/skills/caldav-calendar/versions/2.0.0"):
|
||||
return _MockResponse(status_code=200, json_data={"files": {"SKILL.md": "# Skill"}})
|
||||
return _MockResponse(status_code=404, json_data={})
|
||||
|
||||
mock_get.side_effect = side_effect
|
||||
|
||||
bundle = self.src.fetch("caldav-calendar")
|
||||
self.assertIsNotNone(bundle)
|
||||
self.assertEqual(bundle.files["SKILL.md"], "# Skill")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
80
tests/tools/test_windows_compat.py
Normal file
80
tests/tools/test_windows_compat.py
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
"""Tests for Windows compatibility of process management code.
|
||||
|
||||
Verifies that os.setsid and os.killpg are never called unconditionally,
|
||||
and that each module uses a platform guard before invoking POSIX-only functions.
|
||||
"""
|
||||
|
||||
import ast
|
||||
import pytest
|
||||
from pathlib import Path
|
||||
|
||||
# Files that must have Windows-safe process management
|
||||
GUARDED_FILES = [
|
||||
"tools/environments/local.py",
|
||||
"tools/process_registry.py",
|
||||
"tools/code_execution_tool.py",
|
||||
"gateway/platforms/whatsapp.py",
|
||||
]
|
||||
|
||||
PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
|
||||
|
||||
|
||||
def _get_preexec_fn_values(filepath: Path) -> list:
|
||||
"""Find all preexec_fn= keyword arguments in Popen calls."""
|
||||
source = filepath.read_text(encoding="utf-8")
|
||||
tree = ast.parse(source, filename=str(filepath))
|
||||
values = []
|
||||
for node in ast.walk(tree):
|
||||
if isinstance(node, ast.keyword) and node.arg == "preexec_fn":
|
||||
values.append(ast.dump(node.value))
|
||||
return values
|
||||
|
||||
|
||||
class TestNoUnconditionalSetsid:
|
||||
"""preexec_fn must never be a bare os.setsid reference."""
|
||||
|
||||
@pytest.mark.parametrize("relpath", GUARDED_FILES)
|
||||
def test_preexec_fn_is_guarded(self, relpath):
|
||||
filepath = PROJECT_ROOT / relpath
|
||||
if not filepath.exists():
|
||||
pytest.skip(f"{relpath} not found")
|
||||
values = _get_preexec_fn_values(filepath)
|
||||
for val in values:
|
||||
# A bare os.setsid would be: Attribute(value=Name(id='os'), attr='setsid')
|
||||
assert "attr='setsid'" not in val or "IfExp" in val or "None" in val, (
|
||||
f"{relpath} has unconditional preexec_fn=os.setsid"
|
||||
)
|
||||
|
||||
|
||||
class TestIsWindowsConstant:
|
||||
"""Each guarded file must define _IS_WINDOWS."""
|
||||
|
||||
@pytest.mark.parametrize("relpath", GUARDED_FILES)
|
||||
def test_has_is_windows(self, relpath):
|
||||
filepath = PROJECT_ROOT / relpath
|
||||
if not filepath.exists():
|
||||
pytest.skip(f"{relpath} not found")
|
||||
source = filepath.read_text(encoding="utf-8")
|
||||
assert "_IS_WINDOWS" in source, (
|
||||
f"{relpath} missing _IS_WINDOWS platform guard"
|
||||
)
|
||||
|
||||
|
||||
class TestKillpgGuarded:
|
||||
"""os.killpg must always be behind a platform check."""
|
||||
|
||||
@pytest.mark.parametrize("relpath", GUARDED_FILES)
|
||||
def test_no_unguarded_killpg(self, relpath):
|
||||
filepath = PROJECT_ROOT / relpath
|
||||
if not filepath.exists():
|
||||
pytest.skip(f"{relpath} not found")
|
||||
source = filepath.read_text(encoding="utf-8")
|
||||
lines = source.splitlines()
|
||||
for i, line in enumerate(lines):
|
||||
stripped = line.strip()
|
||||
if "os.killpg" in stripped or "os.getpgid" in stripped:
|
||||
# Check that there's an _IS_WINDOWS guard in the surrounding context
|
||||
context = "\n".join(lines[max(0, i - 15):i + 1])
|
||||
assert "_IS_WINDOWS" in context or "else:" in context, (
|
||||
f"{relpath}:{i + 1} has unguarded os.killpg/os.getpgid call"
|
||||
)
|
||||
|
|
@ -20,6 +20,7 @@ Platform: Linux / macOS only (Unix domain sockets). Disabled on Windows.
|
|||
import json
|
||||
import logging
|
||||
import os
|
||||
import platform
|
||||
import signal
|
||||
import socket
|
||||
import subprocess
|
||||
|
|
@ -28,6 +29,8 @@ import tempfile
|
|||
import threading
|
||||
import time
|
||||
import uuid
|
||||
|
||||
_IS_WINDOWS = platform.system() == "Windows"
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
||||
# Availability gate: UDS requires a POSIX OS
|
||||
|
|
@ -405,7 +408,7 @@ def execute_code(
|
|||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.PIPE,
|
||||
stdin=subprocess.DEVNULL,
|
||||
preexec_fn=os.setsid,
|
||||
preexec_fn=None if _IS_WINDOWS else os.setsid,
|
||||
)
|
||||
|
||||
# --- Poll loop: watch for exit, timeout, and interrupt ---
|
||||
|
|
@ -514,7 +517,10 @@ def execute_code(
|
|||
def _kill_process_group(proc, escalate: bool = False):
|
||||
"""Kill the child and its entire process group."""
|
||||
try:
|
||||
os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
|
||||
if _IS_WINDOWS:
|
||||
proc.terminate()
|
||||
else:
|
||||
os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
|
||||
except (ProcessLookupError, PermissionError):
|
||||
try:
|
||||
proc.kill()
|
||||
|
|
@ -527,7 +533,10 @@ def _kill_process_group(proc, escalate: bool = False):
|
|||
proc.wait(timeout=5)
|
||||
except subprocess.TimeoutExpired:
|
||||
try:
|
||||
os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
|
||||
if _IS_WINDOWS:
|
||||
proc.kill()
|
||||
else:
|
||||
os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
|
||||
except (ProcessLookupError, PermissionError):
|
||||
try:
|
||||
proc.kill()
|
||||
|
|
|
|||
|
|
@ -1,18 +1,58 @@
|
|||
"""Local execution environment with interrupt support and non-blocking I/O."""
|
||||
|
||||
import os
|
||||
import platform
|
||||
import shutil
|
||||
import signal
|
||||
import subprocess
|
||||
import threading
|
||||
import time
|
||||
|
||||
_IS_WINDOWS = platform.system() == "Windows"
|
||||
|
||||
from tools.environments.base import BaseEnvironment
|
||||
|
||||
# Unique marker to isolate real command output from shell init/exit noise.
|
||||
# printf (no trailing newline) keeps the boundaries clean for splitting.
|
||||
_OUTPUT_FENCE = "__HERMES_FENCE_a9f7b3__"
|
||||
|
||||
|
||||
def _find_shell() -> str:
|
||||
"""Find the best shell for command execution.
|
||||
|
||||
On Unix: uses $SHELL, falls back to bash.
|
||||
On Windows: uses Git Bash (bundled with Git for Windows).
|
||||
Raises RuntimeError if no suitable shell is found on Windows.
|
||||
"""
|
||||
if not _IS_WINDOWS:
|
||||
return os.environ.get("SHELL") or shutil.which("bash") or "/bin/bash"
|
||||
|
||||
# Windows: look for Git Bash (installed with Git for Windows).
|
||||
# Allow override via env var (same pattern as Claude Code).
|
||||
custom = os.environ.get("HERMES_GIT_BASH_PATH")
|
||||
if custom and os.path.isfile(custom):
|
||||
return custom
|
||||
|
||||
# shutil.which finds bash.exe if Git\bin is on PATH
|
||||
found = shutil.which("bash")
|
||||
if found:
|
||||
return found
|
||||
|
||||
# Check common Git for Windows install locations
|
||||
for candidate in (
|
||||
os.path.join(os.environ.get("ProgramFiles", r"C:\Program Files"), "Git", "bin", "bash.exe"),
|
||||
os.path.join(os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)"), "Git", "bin", "bash.exe"),
|
||||
os.path.join(os.environ.get("LOCALAPPDATA", ""), "Programs", "Git", "bin", "bash.exe"),
|
||||
):
|
||||
if candidate and os.path.isfile(candidate):
|
||||
return candidate
|
||||
|
||||
raise RuntimeError(
|
||||
"Git Bash not found. Hermes Agent requires Git for Windows on Windows.\n"
|
||||
"Install it from: https://git-scm.com/download/win\n"
|
||||
"Or set HERMES_GIT_BASH_PATH to your bash.exe location."
|
||||
)
|
||||
|
||||
# Noise lines emitted by interactive shells when stdin is not a terminal.
|
||||
# Used as a fallback when output fence markers are missing.
|
||||
_SHELL_NOISE_SUBSTRINGS = (
|
||||
|
|
@ -119,7 +159,7 @@ class LocalEnvironment(BaseEnvironment):
|
|||
# tools like nvm, pyenv, and cargo install their init scripts.
|
||||
# -l alone isn't enough: .profile sources .bashrc, but the guard
|
||||
# returns early because the shell isn't interactive.
|
||||
user_shell = os.environ.get("SHELL") or shutil.which("bash") or "/bin/bash"
|
||||
user_shell = _find_shell()
|
||||
# Wrap with output fences so we can later extract the real
|
||||
# command output and discard shell init/exit noise.
|
||||
fenced_cmd = (
|
||||
|
|
@ -139,7 +179,7 @@ class LocalEnvironment(BaseEnvironment):
|
|||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.STDOUT,
|
||||
stdin=subprocess.PIPE if stdin_data is not None else subprocess.DEVNULL,
|
||||
preexec_fn=os.setsid,
|
||||
preexec_fn=None if _IS_WINDOWS else os.setsid,
|
||||
)
|
||||
|
||||
if stdin_data is not None:
|
||||
|
|
@ -172,12 +212,15 @@ class LocalEnvironment(BaseEnvironment):
|
|||
while proc.poll() is None:
|
||||
if _interrupt_event.is_set():
|
||||
try:
|
||||
pgid = os.getpgid(proc.pid)
|
||||
os.killpg(pgid, signal.SIGTERM)
|
||||
try:
|
||||
proc.wait(timeout=1.0)
|
||||
except subprocess.TimeoutExpired:
|
||||
os.killpg(pgid, signal.SIGKILL)
|
||||
if _IS_WINDOWS:
|
||||
proc.terminate()
|
||||
else:
|
||||
pgid = os.getpgid(proc.pid)
|
||||
os.killpg(pgid, signal.SIGTERM)
|
||||
try:
|
||||
proc.wait(timeout=1.0)
|
||||
except subprocess.TimeoutExpired:
|
||||
os.killpg(pgid, signal.SIGKILL)
|
||||
except (ProcessLookupError, PermissionError):
|
||||
proc.kill()
|
||||
reader.join(timeout=2)
|
||||
|
|
@ -187,7 +230,10 @@ class LocalEnvironment(BaseEnvironment):
|
|||
}
|
||||
if time.monotonic() > deadline:
|
||||
try:
|
||||
os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
|
||||
if _IS_WINDOWS:
|
||||
proc.terminate()
|
||||
else:
|
||||
os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
|
||||
except (ProcessLookupError, PermissionError):
|
||||
proc.kill()
|
||||
reader.join(timeout=2)
|
||||
|
|
|
|||
1047
tools/mcp_tool.py
Normal file
1047
tools/mcp_tool.py
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -32,6 +32,7 @@ Usage:
|
|||
import json
|
||||
import logging
|
||||
import os
|
||||
import platform
|
||||
import shlex
|
||||
import shutil
|
||||
import signal
|
||||
|
|
@ -39,6 +40,9 @@ import subprocess
|
|||
import threading
|
||||
import time
|
||||
import uuid
|
||||
|
||||
_IS_WINDOWS = platform.system() == "Windows"
|
||||
from tools.environments.local import _find_shell
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
|
@ -145,7 +149,7 @@ class ProcessRegistry:
|
|||
# Try PTY mode for interactive CLI tools
|
||||
try:
|
||||
import ptyprocess
|
||||
user_shell = os.environ.get("SHELL") or shutil.which("bash") or "/bin/bash"
|
||||
user_shell = _find_shell()
|
||||
pty_env = os.environ | (env_vars or {})
|
||||
pty_env["PYTHONUNBUFFERED"] = "1"
|
||||
pty_proc = ptyprocess.PtyProcess.spawn(
|
||||
|
|
@ -183,7 +187,7 @@ class ProcessRegistry:
|
|||
# Standard Popen path (non-PTY or PTY fallback)
|
||||
# Use the user's login shell for consistency with LocalEnvironment --
|
||||
# ensures rc files are sourced and user tools are available.
|
||||
user_shell = os.environ.get("SHELL") or shutil.which("bash") or "/bin/bash"
|
||||
user_shell = _find_shell()
|
||||
# Force unbuffered output for Python scripts so progress is visible
|
||||
# during background execution (libraries like tqdm/datasets buffer when
|
||||
# stdout is a pipe, hiding output from process(action="poll")).
|
||||
|
|
@ -199,7 +203,7 @@ class ProcessRegistry:
|
|||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.STDOUT,
|
||||
stdin=subprocess.PIPE,
|
||||
preexec_fn=os.setsid,
|
||||
preexec_fn=None if _IS_WINDOWS else os.setsid,
|
||||
)
|
||||
|
||||
session.process = proc
|
||||
|
|
@ -551,7 +555,10 @@ class ProcessRegistry:
|
|||
elif session.process:
|
||||
# Local process -- kill the process group
|
||||
try:
|
||||
os.killpg(os.getpgid(session.process.pid), signal.SIGTERM)
|
||||
if _IS_WINDOWS:
|
||||
session.process.terminate()
|
||||
else:
|
||||
os.killpg(os.getpgid(session.process.pid), signal.SIGTERM)
|
||||
except (ProcessLookupError, PermissionError):
|
||||
session.process.kill()
|
||||
elif session.env_ref and session.pid:
|
||||
|
|
|
|||
|
|
@ -520,8 +520,8 @@ class ClawHubSource(SkillSource):
|
|||
|
||||
try:
|
||||
resp = httpx.get(
|
||||
f"{self.BASE_URL}/skills/search",
|
||||
params={"q": query, "limit": limit},
|
||||
f"{self.BASE_URL}/skills",
|
||||
params={"search": query, "limit": limit},
|
||||
timeout=15,
|
||||
)
|
||||
if resp.status_code != 200:
|
||||
|
|
@ -530,82 +530,154 @@ class ClawHubSource(SkillSource):
|
|||
except (httpx.HTTPError, json.JSONDecodeError):
|
||||
return []
|
||||
|
||||
skills_data = data.get("skills", data) if isinstance(data, dict) else data
|
||||
skills_data = data.get("items", data) if isinstance(data, dict) else data
|
||||
if not isinstance(skills_data, list):
|
||||
return []
|
||||
|
||||
results = []
|
||||
for item in skills_data[:limit]:
|
||||
name = item.get("name", item.get("slug", ""))
|
||||
if not name:
|
||||
slug = item.get("slug")
|
||||
if not slug:
|
||||
continue
|
||||
meta = SkillMeta(
|
||||
name=name,
|
||||
description=item.get("description", ""),
|
||||
display_name = item.get("displayName") or item.get("name") or slug
|
||||
summary = item.get("summary") or item.get("description") or ""
|
||||
tags = item.get("tags", [])
|
||||
if not isinstance(tags, list):
|
||||
tags = []
|
||||
results.append(SkillMeta(
|
||||
name=display_name,
|
||||
description=summary,
|
||||
source="clawhub",
|
||||
identifier=item.get("slug", name),
|
||||
identifier=slug,
|
||||
trust_level="community",
|
||||
tags=item.get("tags", []),
|
||||
)
|
||||
results.append(meta)
|
||||
tags=[str(t) for t in tags],
|
||||
))
|
||||
|
||||
_write_index_cache(cache_key, [_skill_meta_to_dict(s) for s in results])
|
||||
return results
|
||||
|
||||
def fetch(self, identifier: str) -> Optional[SkillBundle]:
|
||||
try:
|
||||
resp = httpx.get(
|
||||
f"{self.BASE_URL}/skills/{identifier}/versions/latest/files",
|
||||
timeout=30,
|
||||
)
|
||||
if resp.status_code != 200:
|
||||
return None
|
||||
data = resp.json()
|
||||
except (httpx.HTTPError, json.JSONDecodeError):
|
||||
slug = identifier.split("/")[-1]
|
||||
|
||||
skill_data = self._get_json(f"{self.BASE_URL}/skills/{slug}")
|
||||
if not isinstance(skill_data, dict):
|
||||
return None
|
||||
|
||||
files: Dict[str, str] = {}
|
||||
file_list = data.get("files", data) if isinstance(data, dict) else data
|
||||
if isinstance(file_list, list):
|
||||
for f in file_list:
|
||||
fname = f.get("name", f.get("path", ""))
|
||||
content = f.get("content", "")
|
||||
if fname and content:
|
||||
files[fname] = content
|
||||
elif isinstance(file_list, dict):
|
||||
files = {k: v for k, v in file_list.items() if isinstance(v, str)}
|
||||
latest_version = self._resolve_latest_version(slug, skill_data)
|
||||
if not latest_version:
|
||||
logger.warning("ClawHub fetch failed for %s: could not resolve latest version", slug)
|
||||
return None
|
||||
|
||||
version_data = self._get_json(f"{self.BASE_URL}/skills/{slug}/versions/{latest_version}")
|
||||
if not isinstance(version_data, dict):
|
||||
return None
|
||||
|
||||
files = self._extract_files(version_data)
|
||||
if "SKILL.md" not in files:
|
||||
logger.warning(
|
||||
"ClawHub fetch for %s resolved version %s but no inline/raw file content was available",
|
||||
slug,
|
||||
latest_version,
|
||||
)
|
||||
return None
|
||||
|
||||
return SkillBundle(
|
||||
name=identifier.split("/")[-1] if "/" in identifier else identifier,
|
||||
name=slug,
|
||||
files=files,
|
||||
source="clawhub",
|
||||
identifier=identifier,
|
||||
identifier=slug,
|
||||
trust_level="community",
|
||||
)
|
||||
|
||||
def inspect(self, identifier: str) -> Optional[SkillMeta]:
|
||||
slug = identifier.split("/")[-1]
|
||||
data = self._get_json(f"{self.BASE_URL}/skills/{slug}")
|
||||
if not isinstance(data, dict):
|
||||
return None
|
||||
|
||||
tags = data.get("tags", [])
|
||||
if not isinstance(tags, list):
|
||||
tags = []
|
||||
|
||||
return SkillMeta(
|
||||
name=data.get("displayName") or data.get("name") or data.get("slug") or slug,
|
||||
description=data.get("summary") or data.get("description") or "",
|
||||
source="clawhub",
|
||||
identifier=data.get("slug") or slug,
|
||||
trust_level="community",
|
||||
tags=[str(t) for t in tags],
|
||||
)
|
||||
|
||||
def _get_json(self, url: str, timeout: int = 20) -> Optional[Any]:
|
||||
try:
|
||||
resp = httpx.get(
|
||||
f"{self.BASE_URL}/skills/{identifier}",
|
||||
timeout=15,
|
||||
)
|
||||
resp = httpx.get(url, timeout=timeout)
|
||||
if resp.status_code != 200:
|
||||
return None
|
||||
data = resp.json()
|
||||
return resp.json()
|
||||
except (httpx.HTTPError, json.JSONDecodeError):
|
||||
return None
|
||||
|
||||
return SkillMeta(
|
||||
name=data.get("name", identifier),
|
||||
description=data.get("description", ""),
|
||||
source="clawhub",
|
||||
identifier=identifier,
|
||||
trust_level="community",
|
||||
tags=data.get("tags", []),
|
||||
)
|
||||
def _resolve_latest_version(self, slug: str, skill_data: Dict[str, Any]) -> Optional[str]:
|
||||
latest = skill_data.get("latestVersion")
|
||||
if isinstance(latest, dict):
|
||||
version = latest.get("version")
|
||||
if isinstance(version, str) and version:
|
||||
return version
|
||||
|
||||
tags = skill_data.get("tags")
|
||||
if isinstance(tags, dict):
|
||||
latest_tag = tags.get("latest")
|
||||
if isinstance(latest_tag, str) and latest_tag:
|
||||
return latest_tag
|
||||
|
||||
versions_data = self._get_json(f"{self.BASE_URL}/skills/{slug}/versions")
|
||||
if isinstance(versions_data, list) and versions_data:
|
||||
first = versions_data[0]
|
||||
if isinstance(first, dict):
|
||||
version = first.get("version")
|
||||
if isinstance(version, str) and version:
|
||||
return version
|
||||
return None
|
||||
|
||||
def _extract_files(self, version_data: Dict[str, Any]) -> Dict[str, str]:
|
||||
files: Dict[str, str] = {}
|
||||
file_list = version_data.get("files")
|
||||
|
||||
if isinstance(file_list, dict):
|
||||
return {k: v for k, v in file_list.items() if isinstance(v, str)}
|
||||
|
||||
if not isinstance(file_list, list):
|
||||
return files
|
||||
|
||||
for file_meta in file_list:
|
||||
if not isinstance(file_meta, dict):
|
||||
continue
|
||||
|
||||
fname = file_meta.get("path") or file_meta.get("name")
|
||||
if not fname or not isinstance(fname, str):
|
||||
continue
|
||||
|
||||
inline_content = file_meta.get("content")
|
||||
if isinstance(inline_content, str):
|
||||
files[fname] = inline_content
|
||||
continue
|
||||
|
||||
raw_url = file_meta.get("rawUrl") or file_meta.get("downloadUrl") or file_meta.get("url")
|
||||
if isinstance(raw_url, str) and raw_url.startswith("http"):
|
||||
content = self._fetch_text(raw_url)
|
||||
if content is not None:
|
||||
files[fname] = content
|
||||
|
||||
return files
|
||||
|
||||
def _fetch_text(self, url: str) -> Optional[str]:
|
||||
try:
|
||||
resp = httpx.get(url, timeout=20)
|
||||
if resp.status_code == 200:
|
||||
return resp.text
|
||||
except httpx.HTTPError:
|
||||
return None
|
||||
return None
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
|
|
|
|||
82
uv.lock
generated
82
uv.lock
generated
|
|
@ -1015,6 +1015,7 @@ all = [
|
|||
{ name = "discord-py" },
|
||||
{ name = "elevenlabs" },
|
||||
{ name = "honcho-ai" },
|
||||
{ name = "mcp" },
|
||||
{ name = "ptyprocess" },
|
||||
{ name = "pytest" },
|
||||
{ name = "pytest-asyncio" },
|
||||
|
|
@ -1037,6 +1038,9 @@ dev = [
|
|||
honcho = [
|
||||
{ name = "honcho-ai" },
|
||||
]
|
||||
mcp = [
|
||||
{ name = "mcp" },
|
||||
]
|
||||
messaging = [
|
||||
{ name = "aiohttp" },
|
||||
{ name = "discord-py" },
|
||||
|
|
@ -1072,6 +1076,7 @@ requires-dist = [
|
|||
{ name = "hermes-agent", extras = ["cron"], marker = "extra == 'all'" },
|
||||
{ name = "hermes-agent", extras = ["dev"], marker = "extra == 'all'" },
|
||||
{ name = "hermes-agent", extras = ["honcho"], marker = "extra == 'all'" },
|
||||
{ name = "hermes-agent", extras = ["mcp"], marker = "extra == 'all'" },
|
||||
{ name = "hermes-agent", extras = ["messaging"], marker = "extra == 'all'" },
|
||||
{ name = "hermes-agent", extras = ["modal"], marker = "extra == 'all'" },
|
||||
{ name = "hermes-agent", extras = ["pty"], marker = "extra == 'all'" },
|
||||
|
|
@ -1081,6 +1086,7 @@ requires-dist = [
|
|||
{ name = "httpx" },
|
||||
{ name = "jinja2" },
|
||||
{ name = "litellm", specifier = ">=1.75.5" },
|
||||
{ name = "mcp", marker = "extra == 'mcp'", specifier = ">=1.2.0" },
|
||||
{ name = "openai" },
|
||||
{ name = "platformdirs" },
|
||||
{ name = "prompt-toolkit" },
|
||||
|
|
@ -1103,7 +1109,7 @@ requires-dist = [
|
|||
{ name = "tenacity" },
|
||||
{ name = "typer" },
|
||||
]
|
||||
provides-extras = ["modal", "dev", "messaging", "cron", "slack", "cli", "tts-premium", "pty", "honcho", "all"]
|
||||
provides-extras = ["modal", "dev", "messaging", "cron", "slack", "cli", "tts-premium", "pty", "honcho", "mcp", "all"]
|
||||
|
||||
[[package]]
|
||||
name = "hf-xet"
|
||||
|
|
@ -1522,6 +1528,31 @@ wheels = [
|
|||
{ url = "https://files.pythonhosted.org/packages/70/bc/6f1c2f612465f5fa89b95bead1f44dcb607670fd42891d8fdcd5d039f4f4/markupsafe-3.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:32001d6a8fc98c8cb5c947787c5d08b0a50663d139f1305bac5885d98d9b40fa", size = 14146, upload-time = "2025-09-27T18:37:28.327Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "mcp"
|
||||
version = "1.26.0"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
dependencies = [
|
||||
{ name = "anyio" },
|
||||
{ name = "httpx" },
|
||||
{ name = "httpx-sse" },
|
||||
{ name = "jsonschema" },
|
||||
{ name = "pydantic" },
|
||||
{ name = "pydantic-settings" },
|
||||
{ name = "pyjwt", extra = ["crypto"] },
|
||||
{ name = "python-multipart" },
|
||||
{ name = "pywin32", marker = "sys_platform == 'win32'" },
|
||||
{ name = "sse-starlette" },
|
||||
{ name = "starlette" },
|
||||
{ name = "typing-extensions" },
|
||||
{ name = "typing-inspection" },
|
||||
{ name = "uvicorn", marker = "sys_platform != 'emscripten'" },
|
||||
]
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/fc/6d/62e76bbb8144d6ed86e202b5edd8a4cb631e7c8130f3f4893c3f90262b10/mcp-1.26.0.tar.gz", hash = "sha256:db6e2ef491eecc1a0d93711a76f28dec2e05999f93afd48795da1c1137142c66", size = 608005, upload-time = "2026-01-24T19:40:32.468Z" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/fd/d9/eaa1f80170d2b7c5ba23f3b59f766f3a0bb41155fbc32a69adfa1adaaef9/mcp-1.26.0-py3-none-any.whl", hash = "sha256:904a21c33c25aa98ddbeb47273033c435e595bbacfdb177f4bd87f6dceebe1ca", size = 233615, upload-time = "2026-01-24T19:40:30.652Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "mdurl"
|
||||
version = "0.1.2"
|
||||
|
|
@ -2114,6 +2145,20 @@ wheels = [
|
|||
{ url = "https://files.pythonhosted.org/packages/36/c7/cfc8e811f061c841d7990b0201912c3556bfeb99cdcb7ed24adc8d6f8704/pydantic_core-2.41.5-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:56121965f7a4dc965bff783d70b907ddf3d57f6eba29b6d2e5dabfaf07799c51", size = 2145302, upload-time = "2025-11-04T13:43:46.64Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pydantic-settings"
|
||||
version = "2.13.1"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
dependencies = [
|
||||
{ name = "pydantic" },
|
||||
{ name = "python-dotenv" },
|
||||
{ name = "typing-inspection" },
|
||||
]
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/52/6d/fffca34caecc4a3f97bda81b2098da5e8ab7efc9a66e819074a11955d87e/pydantic_settings-2.13.1.tar.gz", hash = "sha256:b4c11847b15237fb0171e1462bf540e294affb9b86db4d9aa5c01730bdbe4025", size = 223826, upload-time = "2026-02-19T13:45:08.055Z" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/00/4b/ccc026168948fec4f7555b9164c724cf4125eac006e176541483d2c959be/pydantic_settings-2.13.1-py3-none-any.whl", hash = "sha256:d56fd801823dbeae7f0975e1f8c8e25c258eb75d278ea7abb5d9cebb01b56237", size = 58929, upload-time = "2026-02-19T13:45:06.034Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pygments"
|
||||
version = "2.19.2"
|
||||
|
|
@ -2221,6 +2266,28 @@ wheels = [
|
|||
{ url = "https://files.pythonhosted.org/packages/81/c4/34e93fe5f5429d7570ec1fa436f1986fb1f00c3e0f43a589fe2bbcd22c3f/pytz-2025.2-py2.py3-none-any.whl", hash = "sha256:5ddf76296dd8c44c26eb8f4b6f35488f3ccbf6fbbd7adee0b7262d43f0ec2f00", size = 509225, upload-time = "2025-03-25T02:24:58.468Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pywin32"
|
||||
version = "311"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/7b/40/44efbb0dfbd33aca6a6483191dae0716070ed99e2ecb0c53683f400a0b4f/pywin32-311-cp310-cp310-win32.whl", hash = "sha256:d03ff496d2a0cd4a5893504789d4a15399133fe82517455e78bad62efbb7f0a3", size = 8760432, upload-time = "2025-07-14T20:13:05.9Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/5e/bf/360243b1e953bd254a82f12653974be395ba880e7ec23e3731d9f73921cc/pywin32-311-cp310-cp310-win_amd64.whl", hash = "sha256:797c2772017851984b97180b0bebe4b620bb86328e8a884bb626156295a63b3b", size = 9590103, upload-time = "2025-07-14T20:13:07.698Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/57/38/d290720e6f138086fb3d5ffe0b6caa019a791dd57866940c82e4eeaf2012/pywin32-311-cp310-cp310-win_arm64.whl", hash = "sha256:0502d1facf1fed4839a9a51ccbcc63d952cf318f78ffc00a7e78528ac27d7a2b", size = 8778557, upload-time = "2025-07-14T20:13:11.11Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/7c/af/449a6a91e5d6db51420875c54f6aff7c97a86a3b13a0b4f1a5c13b988de3/pywin32-311-cp311-cp311-win32.whl", hash = "sha256:184eb5e436dea364dcd3d2316d577d625c0351bf237c4e9a5fabbcfa5a58b151", size = 8697031, upload-time = "2025-07-14T20:13:13.266Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/51/8f/9bb81dd5bb77d22243d33c8397f09377056d5c687aa6d4042bea7fbf8364/pywin32-311-cp311-cp311-win_amd64.whl", hash = "sha256:3ce80b34b22b17ccbd937a6e78e7225d80c52f5ab9940fe0506a1a16f3dab503", size = 9508308, upload-time = "2025-07-14T20:13:15.147Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/44/7b/9c2ab54f74a138c491aba1b1cd0795ba61f144c711daea84a88b63dc0f6c/pywin32-311-cp311-cp311-win_arm64.whl", hash = "sha256:a733f1388e1a842abb67ffa8e7aad0e70ac519e09b0f6a784e65a136ec7cefd2", size = 8703930, upload-time = "2025-07-14T20:13:16.945Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/e7/ab/01ea1943d4eba0f850c3c61e78e8dd59757ff815ff3ccd0a84de5f541f42/pywin32-311-cp312-cp312-win32.whl", hash = "sha256:750ec6e621af2b948540032557b10a2d43b0cee2ae9758c54154d711cc852d31", size = 8706543, upload-time = "2025-07-14T20:13:20.765Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/d1/a8/a0e8d07d4d051ec7502cd58b291ec98dcc0c3fff027caad0470b72cfcc2f/pywin32-311-cp312-cp312-win_amd64.whl", hash = "sha256:b8c095edad5c211ff31c05223658e71bf7116daa0ecf3ad85f3201ea3190d067", size = 9495040, upload-time = "2025-07-14T20:13:22.543Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/ba/3a/2ae996277b4b50f17d61f0603efd8253cb2d79cc7ae159468007b586396d/pywin32-311-cp312-cp312-win_arm64.whl", hash = "sha256:e286f46a9a39c4a18b319c28f59b61de793654af2f395c102b4f819e584b5852", size = 8710102, upload-time = "2025-07-14T20:13:24.682Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/a5/be/3fd5de0979fcb3994bfee0d65ed8ca9506a8a1260651b86174f6a86f52b3/pywin32-311-cp313-cp313-win32.whl", hash = "sha256:f95ba5a847cba10dd8c4d8fefa9f2a6cf283b8b88ed6178fa8a6c1ab16054d0d", size = 8705700, upload-time = "2025-07-14T20:13:26.471Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/e3/28/e0a1909523c6890208295a29e05c2adb2126364e289826c0a8bc7297bd5c/pywin32-311-cp313-cp313-win_amd64.whl", hash = "sha256:718a38f7e5b058e76aee1c56ddd06908116d35147e133427e59a3983f703a20d", size = 9494700, upload-time = "2025-07-14T20:13:28.243Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/04/bf/90339ac0f55726dce7d794e6d79a18a91265bdf3aa70b6b9ca52f35e022a/pywin32-311-cp313-cp313-win_arm64.whl", hash = "sha256:7b4075d959648406202d92a2310cb990fea19b535c7f4a78d3f5e10b926eeb8a", size = 8709318, upload-time = "2025-07-14T20:13:30.348Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/c9/31/097f2e132c4f16d99a22bfb777e0fd88bd8e1c634304e102f313af69ace5/pywin32-311-cp314-cp314-win32.whl", hash = "sha256:b7a2c10b93f8986666d0c803ee19b5990885872a7de910fc460f9b0c2fbf92ee", size = 8840714, upload-time = "2025-07-14T20:13:32.449Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/90/4b/07c77d8ba0e01349358082713400435347df8426208171ce297da32c313d/pywin32-311-cp314-cp314-win_amd64.whl", hash = "sha256:3aca44c046bd2ed8c90de9cb8427f581c479e594e99b5c0bb19b29c10fd6cb87", size = 9656800, upload-time = "2025-07-14T20:13:34.312Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/c0/d2/21af5c535501a7233e734b8af901574572da66fcc254cb35d0609c9080dd/pywin32-311-cp314-cp314-win_arm64.whl", hash = "sha256:a508e2d9025764a8270f93111a970e1d0fbfc33f4153b388bb649b7eec4f9b42", size = 8932540, upload-time = "2025-07-14T20:13:36.379Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pyyaml"
|
||||
version = "6.0.3"
|
||||
|
|
@ -2639,6 +2706,19 @@ wheels = [
|
|||
{ url = "https://files.pythonhosted.org/packages/e9/44/75a9c9421471a6c4805dbf2356f7c181a29c1879239abab1ea2cc8f38b40/sniffio-1.3.1-py3-none-any.whl", hash = "sha256:2f6da418d1f1e0fddd844478f41680e794e6051915791a034ff65e5f100525a2", size = 10235, upload-time = "2024-02-25T23:20:01.196Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "sse-starlette"
|
||||
version = "3.3.2"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
dependencies = [
|
||||
{ name = "anyio" },
|
||||
{ name = "starlette" },
|
||||
]
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/5a/9f/c3695c2d2d4ef70072c3a06992850498b01c6bc9be531950813716b426fa/sse_starlette-3.3.2.tar.gz", hash = "sha256:678fca55a1945c734d8472a6cad186a55ab02840b4f6786f5ee8770970579dcd", size = 32326, upload-time = "2026-02-28T11:24:34.36Z" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/61/28/8cb142d3fe80c4a2d8af54ca0b003f47ce0ba920974e7990fa6e016402d1/sse_starlette-3.3.2-py3-none-any.whl", hash = "sha256:5c3ea3dad425c601236726af2f27689b74494643f57017cafcb6f8c9acfbb862", size = 14270, upload-time = "2026-02-28T11:24:32.984Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "starlette"
|
||||
version = "0.52.1"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue