Install whatsapp bridge deps in container

Switch MCP HTTP transport from the deprecated streamablehttp_client()
(mcp < 1.24.0) to the new streamable_http_client() API that accepts a
pre-built httpx.AsyncClient.

Changes vs the original PR #3391:
- Separate try/except imports so mcp < 1.24.0 doesn't break (graceful
  fallback to deprecated API instead of losing HTTP MCP entirely)
- Wrap httpx.AsyncClient in async-with for proper lifecycle management
  (the new SDK API explicitly skips closing caller-provided clients)
- Match SDK's own create_mcp_http_client defaults: follow_redirects=True,
  Timeout(connect_timeout, read=300.0)
- Keep deprecated code path as fallback for older SDK versions

Co-authored-by: HenkDz <HenkDz@users.noreply.github.com>

.dockerignore

@@ -0,0 +1,13 @@
+# Git
+.git
+.gitignore
+.gitmodules
+
+# Dependencies
+node_modules
+
+# CI/CD
+.github
+
+# Environment files
+.env

.env.example

@@ -74,6 +74,10 @@ HF_TOKEN=
 # TOOL API KEYS
 # =============================================================================
 
+# Exa API Key - AI-native web search and contents
+# Get at: https://exa.ai
+EXA_API_KEY=
+
 # Parallel API Key - AI-native web search and extract
 # Get at: https://parallel.ai
 PARALLEL_API_KEY=

.github/workflows/docker-publish.yml

@@ -0,0 +1,61 @@
+name: Docker Build and Publish
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: docker-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: Dockerfile
+          load: true
+          tags: nousresearch/hermes-agent:test
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Test image starts
+        run: |
+          docker run --rm \
+            -v /tmp/hermes-test:/opt/data \
+            --entrypoint /opt/hermes/docker/entrypoint.sh \
+            nousresearch/hermes-agent:test --help
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Push image
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: Dockerfile
+          push: true
+          tags: |
+            nousresearch/hermes-agent:latest
+            nousresearch/hermes-agent:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

Dockerfile

@@ -0,0 +1,20 @@
+FROM debian:13.4
+
+RUN apt-get update
+RUN apt-get install -y nodejs npm python3 python3-pip ripgrep ffmpeg gcc python3-dev libffi-dev
+
+COPY . /opt/hermes
+WORKDIR /opt/hermes
+
+RUN pip install -e ".[all]" --break-system-packages
+RUN npm install
+RUN npx playwright install --with-deps chromium
+WORKDIR /opt/hermes/scripts/whatsapp-bridge
+RUN npm install
+
+WORKDIR /opt/hermes
+RUN chmod +x /opt/hermes/docker/entrypoint.sh
+
+ENV HERMES_HOME=/opt/data
+VOLUME [ "/opt/data" ]
+ENTRYPOINT [ "/opt/hermes/docker/entrypoint.sh" ]

agent/auxiliary_client.py

@@ -1458,6 +1458,29 @@ def _resolve_task_provider_model(
     return "auto", resolved_model, None, None
 
 
+_DEFAULT_AUX_TIMEOUT = 30.0
+
+
+def _get_task_timeout(task: str, default: float = _DEFAULT_AUX_TIMEOUT) -> float:
+    """Read timeout from auxiliary.{task}.timeout in config, falling back to *default*."""
+    if not task:
+        return default
+    try:
+        from hermes_cli.config import load_config
+        config = load_config()
+    except ImportError:
+        return default
+    aux = config.get("auxiliary", {}) if isinstance(config, dict) else {}
+    task_config = aux.get(task, {}) if isinstance(aux, dict) else {}
+    raw = task_config.get("timeout")
+    if raw is not None:
+        try:
+            return float(raw)
+        except (ValueError, TypeError):
+            pass
+    return default
+
+
 def _build_call_kwargs(
     provider: str,
     model: str,
@@ -1515,7 +1538,7 @@ def call_llm(
     temperature: float = None,
     max_tokens: int = None,
     tools: list = None,
-    timeout: float = 30.0,
+    timeout: float = None,
     extra_body: dict = None,
 ) -> Any:
     """Centralized synchronous LLM call.
@@ -1533,7 +1556,7 @@ def call_llm(
         temperature: Sampling temperature (None = provider default).
         max_tokens: Max output tokens (handles max_tokens vs max_completion_tokens).
         tools: Tool definitions (for function calling).
-        timeout: Request timeout in seconds.
+        timeout: Request timeout in seconds (None = read from auxiliary.{task}.timeout config).
         extra_body: Additional request body fields.
 
     Returns:
@@ -1598,10 +1621,12 @@ def call_llm(
                 f"No LLM provider configured for task={task} provider={resolved_provider}. "
                 f"Run: hermes setup")
 
+    effective_timeout = timeout if timeout is not None else _get_task_timeout(task)
+
     kwargs = _build_call_kwargs(
         resolved_provider, final_model, messages,
         temperature=temperature, max_tokens=max_tokens,
-        tools=tools, timeout=timeout, extra_body=extra_body,
+        tools=tools, timeout=effective_timeout, extra_body=extra_body,
         base_url=resolved_base_url)
 
     # Handle max_tokens vs max_completion_tokens retry
@@ -1683,7 +1708,7 @@ async def async_call_llm(
     temperature: float = None,
     max_tokens: int = None,
     tools: list = None,
-    timeout: float = 30.0,
+    timeout: float = None,
     extra_body: dict = None,
 ) -> Any:
     """Centralized asynchronous LLM call.
@@ -1744,10 +1769,12 @@ async def async_call_llm(
                 f"No LLM provider configured for task={task} provider={resolved_provider}. "
                 f"Run: hermes setup")
 
+    effective_timeout = timeout if timeout is not None else _get_task_timeout(task)
+
     kwargs = _build_call_kwargs(
         resolved_provider, final_model, messages,
         temperature=temperature, max_tokens=max_tokens,
-        tools=tools, timeout=timeout, extra_body=extra_body,
+        tools=tools, timeout=effective_timeout, extra_body=extra_body,
         base_url=resolved_base_url)
 
     try:

agent/context_compressor.py

@@ -141,7 +141,7 @@ class ContextCompressor:
             "last_prompt_tokens": self.last_prompt_tokens,
             "threshold_tokens": self.threshold_tokens,
             "context_length": self.context_length,
-            "usage_percent": (self.last_prompt_tokens / self.context_length * 100) if self.context_length else 0,
+            "usage_percent": min(100, (self.last_prompt_tokens / self.context_length * 100)) if self.context_length else 0,
             "compression_count": self.compression_count,
         }
 
@@ -347,7 +347,7 @@ Write only the summary body. Do not include any preamble or prefix."""
                 "messages": [{"role": "user", "content": prompt}],
                 "temperature": 0.3,
                 "max_tokens": summary_budget * 2,
-                "timeout": 45.0,
+                # timeout resolved from auxiliary.compression.timeout config by call_llm
             }
             if self.summary_model:
                 call_kwargs["model"] = self.summary_model

agent/display.py

@@ -284,11 +284,11 @@ class KawaiiSpinner:
         The CLI already drives a TUI widget (_spinner_text) for spinner display,
         so KawaiiSpinner's \\r-based animation is redundant under StdoutProxy.
         """
-        out = self._out
-        # StdoutProxy has a 'raw' attribute (bool) that plain file objects lack.
-        if hasattr(out, 'raw') and type(out).__name__ == 'StdoutProxy':
-            return True
-        return False
+        try:
+            from prompt_toolkit.patch_stdout import StdoutProxy
+            return isinstance(self._out, StdoutProxy)
+        except ImportError:
+            return False
 
     def _animate(self):
         # When stdout is not a real terminal (e.g. Docker, systemd, pipe),

agent/title_generator.py

@@ -19,7 +19,7 @@ _TITLE_PROMPT = (
 )
 
 
-def generate_title(user_message: str, assistant_response: str, timeout: float = 15.0) -> Optional[str]:
+def generate_title(user_message: str, assistant_response: str, timeout: float = 30.0) -> Optional[str]:
     """Generate a session title from the first exchange.
 
     Uses the auxiliary LLM client (cheapest/fastest available model).

cli-config.yaml.example

@@ -7,6 +7,7 @@
 # =============================================================================
 model:
   # Default model to use (can be overridden with --model flag)
+  # Both "default" and "model" work as the key name here.
   default: "anthropic/claude-opus-4.6"
   
   # Inference provider selection:

cli.py

@@ -1078,7 +1078,7 @@ class HermesCLI:
         # authoritative.  This avoids conflicts in multi-agent setups where
         # env vars would stomp each other.
         _model_config = CLI_CONFIG.get("model", {})
-        _config_model = _model_config.get("default", "") if isinstance(_model_config, dict) else (_model_config or "")
+        _config_model = (_model_config.get("default") or _model_config.get("model") or "") if isinstance(_model_config, dict) else (_model_config or "")
         _FALLBACK_MODEL = "anthropic/claude-opus-4.6"
         self.model = model or _config_model or _FALLBACK_MODEL
         # Auto-detect model from local server if still on fallback
@@ -4034,6 +4034,17 @@ class HermesCLI:
                     provider_data_collection=self._provider_data_collection,
                     fallback_model=self._fallback_model,
                 )
+                # Silence raw spinner; route thinking through TUI widget when no foreground agent is active.
+                bg_agent._print_fn = lambda *_a, **_kw: None
+
+                def _bg_thinking(text: str) -> None:
+                    # Concurrent bg tasks may race on _spinner_text; acceptable for best-effort UI.
+                    if not self._agent_running:
+                        self._spinner_text = text
+                        if self._app:
+                            self._app.invalidate()
+
+                bg_agent.thinking_callback = _bg_thinking
 
                 result = bg_agent.run_conversation(
                     user_message=prompt,
@@ -4096,6 +4107,9 @@ class HermesCLI:
                 _cprint(f"  ❌ Background task #{task_num} failed: {e}")
             finally:
                 self._background_tasks.pop(task_id, None)
+                # Clear spinner only if no foreground agent owns it
+                if not self._agent_running:
+                    self._spinner_text = ""
                 if self._app:
                     self._invalidate(min_interval=0)
 
@@ -4506,7 +4520,7 @@ class HermesCLI:
         compressor = agent.context_compressor
         last_prompt = compressor.last_prompt_tokens
         ctx_len = compressor.context_length
-        pct = (last_prompt / ctx_len * 100) if ctx_len else 0
+        pct = min(100, (last_prompt / ctx_len * 100)) if ctx_len else 0
         compressions = compressor.compression_count
 
         msg_count = len(self.conversation_history)
@@ -5534,6 +5548,13 @@ class HermesCLI:
             except Exception as e:
                 logging.debug("@ context reference expansion failed: %s", e)
 
+        # Sanitize surrogate characters that can arrive via clipboard paste from
+        # rich-text editors (Google Docs, Word, etc.).  Lone surrogates are invalid
+        # UTF-8 and crash JSON serialization in the OpenAI SDK.
+        if isinstance(message, str):
+            from run_agent import _sanitize_surrogates
+            message = _sanitize_surrogates(message)
+
         # Add user message to history
         self.conversation_history.append({"role": "user", "content": message})
 
@@ -5891,10 +5912,22 @@ class HermesCLI:
             else:
                 duration_str = f"{seconds}s"
             
+            # Look up session title for resume-by-name hint
+            session_title = None
+            if self._session_db:
+                try:
+                    session_title = self._session_db.get_session_title(self.session_id)
+                except Exception:
+                    pass
+
             print("Resume this session with:")
             print(f"  hermes --resume {self.session_id}")
+            if session_title:
+                print(f"  hermes -c \"{session_title}\"")
             print()
             print(f"Session:        {self.session_id}")
+            if session_title:
+                print(f"Title:          {session_title}")
             print(f"Duration:       {duration_str}")
             print(f"Messages:       {msg_count} ({user_msgs} user, {tool_calls} tool calls)")
         else:
@@ -6070,7 +6103,7 @@ class HermesCLI:
             from honcho_integration.client import HonchoClientConfig
             from agent.display import honcho_session_line, write_tty
             hcfg = HonchoClientConfig.from_global_config()
-            if hcfg.enabled and hcfg.api_key and hcfg.explicitly_configured:
+            if hcfg.enabled and (hcfg.api_key or hcfg.base_url) and hcfg.explicitly_configured:
                 sname = hcfg.resolve_session_name(session_id=self.session_id)
                 if sname:
                     write_tty(honcho_session_line(hcfg.workspace_id, sname) + "\n")
@@ -6644,6 +6677,7 @@ class HermesCLI:
         # Paste collapsing: detect large pastes and save to temp file
         _paste_counter = [0]
         _prev_text_len = [0]
+        _prev_newline_count = [0]
         _paste_just_collapsed = [False]
 
         def _on_text_changed(buf):
@@ -6652,18 +6686,27 @@ class HermesCLI:
             When bracketed paste is available, handle_paste collapses
             large pastes directly.  This handler is a fallback for
             terminals without bracketed paste support.
+
+            Two heuristics (either triggers collapse):
+            1. Many characters added at once (chars_added > 1) — works
+               when the terminal delivers the paste in one event-loop tick.
+            2. Newline count jumped by 4+ in a single text-change event —
+               catches terminals that feed characters individually but
+               still batch newlines.  Alt+Enter only adds 1 newline per
+               event so it never triggers this.
             """
             text = buf.text
             chars_added = len(text) - _prev_text_len[0]
             _prev_text_len[0] = len(text)
             if _paste_just_collapsed[0]:
                 _paste_just_collapsed[0] = False
+                _prev_newline_count[0] = text.count('\n')
                 return
             line_count = text.count('\n')
-            # Heuristic: a real paste adds many characters at once (not just a
-            # single newline from Alt+Enter) AND the result has 5+ lines.
-            # Fallback for terminals without bracketed paste support.
-            if line_count >= 5 and chars_added > 1 and not text.startswith('/'):
+            newlines_added = line_count - _prev_newline_count[0]
+            _prev_newline_count[0] = line_count
+            is_paste = chars_added > 1 or newlines_added >= 4
+            if line_count >= 5 and is_paste and not text.startswith('/'):
                 _paste_counter[0] += 1
                 # Save to temp file
                 paste_dir = _hermes_home / "pastes"
@@ -6671,6 +6714,7 @@ class HermesCLI:
                 paste_file = paste_dir / f"paste_{_paste_counter[0]}_{datetime.now().strftime('%H%M%S')}.txt"
                 paste_file.write_text(text, encoding="utf-8")
                 # Replace buffer with compact reference
+                _paste_just_collapsed[0] = True
                 buf.text = f"[Pasted text #{_paste_counter[0]}: {line_count + 1} lines \u2192 {paste_file}]"
                 buf.cursor_position = len(buf.text)
 

docker/SOUL.md

@@ -0,0 +1,15 @@
+# Hermes Agent Persona
+
+<!--
+This file defines the agent's personality and tone.
+The agent will embody whatever you write here.
+Edit this to customize how Hermes communicates with you.
+
+Examples:
+  - "You are a warm, playful assistant who uses kaomoji occasionally."
+  - "You are a concise technical expert. No fluff, just facts."
+  - "You speak like a friendly coworker who happens to know everything."
+
+This file is loaded fresh each message -- no restart needed.
+Delete the contents (or this file) to use the default personality.
+-->

docker/entrypoint.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Docker entrypoint: bootstrap config files into the mounted volume, then run hermes.
+set -e
+
+HERMES_HOME="/opt/data"
+INSTALL_DIR="/opt/hermes"
+
+# Create directory structure
+mkdir -p "$HERMES_HOME"/{cron,sessions,logs,pairing,hooks,image_cache,audio_cache,memories,skills,whatsapp/session}
+
+# .env
+if [ ! -f "$HERMES_HOME/.env" ]; then
+    cp "$INSTALL_DIR/.env.example" "$HERMES_HOME/.env"
+fi
+
+# config.yaml
+if [ ! -f "$HERMES_HOME/config.yaml" ]; then
+    cp "$INSTALL_DIR/cli-config.yaml.example" "$HERMES_HOME/config.yaml"
+fi
+
+# SOUL.md
+if [ ! -f "$HERMES_HOME/SOUL.md" ]; then
+    cp "$INSTALL_DIR/docker/SOUL.md" "$HERMES_HOME/SOUL.md"
+fi
+
+# Sync bundled skills (manifest-based so user edits are preserved)
+if [ -d "$INSTALL_DIR/skills" ]; then
+    python3 "$INSTALL_DIR/tools/skills_sync.py"
+fi
+
+exec hermes "$@"

docs/docker.md

@@ -0,0 +1,56 @@
+# Hermes Agent — Docker
+
+Want to run Hermes Agent, but without installing packages on your host? This'll sort you out.
+
+This will let you run the agent in a container, with the most relevant modes outlined below.
+
+The container stores all user data (config, API keys, sessions, skills, memories) in a single directory mounted from the host at `/opt/data`. The image itself is stateless and can be upgraded by pulling a new version without losing any configuration.
+
+## Quick start
+
+If this is your first time running Hermes Agent, create a data directory on the host and start the container interactively to run the setup wizard:
+
+```sh
+mkdir -p ~/.hermes
+docker run -it --rm \
+  -v ~/.hermes:/opt/data \
+  nousresearch/hermes-agent
+```
+
+This drops you into the setup wizard, which will prompt you for your API keys and write them to `~/.hermes/.env`. You only need to do this once. It is highly recommended to set up a chat system for the gateway to work with at this point.
+
+## Running in gateway mode
+
+Once configured, run the container in the background as a persistent gateway (Telegram, Discord, Slack, WhatsApp, etc.):
+
+```sh
+docker run -d \
+  --name hermes \
+  --restart unless-stopped \
+  -v ~/.hermes:/opt/data \
+  nousresearch/hermes-agent gateway run
+```
+
+## Running interactively (CLI chat)
+
+To open an interactive chat session against a running data directory:
+
+```sh
+docker run -it --rm \
+  -v ~/.hermes:/opt/data \
+  nousresearch/hermes-agent
+```
+
+## Upgrading
+
+Pull the latest image and recreate the container. Your data directory is untouched.
+
+```sh
+docker pull nousresearch/hermes-agent:latest
+docker rm -f hermes
+docker run -d \
+  --name hermes \
+  --restart unless-stopped \
+  -v ~/.hermes:/opt/data \
+  nousresearch/hermes-agent
+```

gateway/pairing.py

@@ -25,7 +25,7 @@ import time
 from pathlib import Path
 from typing import Optional
 
-from hermes_cli.config import get_hermes_home
+from hermes_constants import get_hermes_dir
 
 
 # Unambiguous alphabet -- excludes 0/O, 1/I to prevent confusion
@@ -41,7 +41,7 @@ LOCKOUT_SECONDS = 3600              # Lockout duration after too many failures
 MAX_PENDING_PER_PLATFORM = 3        # Max pending codes per platform
 MAX_FAILED_ATTEMPTS = 5             # Failed approvals before lockout
 
-PAIRING_DIR = get_hermes_home() / "pairing"
+PAIRING_DIR = get_hermes_dir("platforms/pairing", "pairing")
 
 
 def _secure_write(path: Path, data: str) -> None:

gateway/platforms/base.py

@@ -27,6 +27,7 @@ sys.path.insert(0, str(_Path(__file__).resolve().parents[2]))
 from gateway.config import Platform, PlatformConfig
 from gateway.session import SessionSource, build_session_key
 from hermes_cli.config import get_hermes_home
+from hermes_constants import get_hermes_dir
 
 
 GATEWAY_SECRET_CAPTURE_UNSUPPORTED_MESSAGE = (
@@ -44,8 +45,8 @@ GATEWAY_SECRET_CAPTURE_UNSUPPORTED_MESSAGE = (
 # (e.g. Telegram file URLs expire after ~1 hour).
 # ---------------------------------------------------------------------------
 
-# Default location: {HERMES_HOME}/image_cache/
-IMAGE_CACHE_DIR = get_hermes_home() / "image_cache"
+# Default location: {HERMES_HOME}/cache/images/ (legacy: image_cache/)
+IMAGE_CACHE_DIR = get_hermes_dir("cache/images", "image_cache")
 
 
 def get_image_cache_dir() -> Path:
@@ -147,7 +148,7 @@ def cleanup_image_cache(max_age_hours: int = 24) -> int:
 # here so the STT tool (OpenAI Whisper) can transcribe them from local files.
 # ---------------------------------------------------------------------------
 
-AUDIO_CACHE_DIR = get_hermes_home() / "audio_cache"
+AUDIO_CACHE_DIR = get_hermes_dir("cache/audio", "audio_cache")
 
 
 def get_audio_cache_dir() -> Path:
@@ -174,29 +175,51 @@ def cache_audio_from_bytes(data: bytes, ext: str = ".ogg") -> str:
     return str(filepath)
 
 
-async def cache_audio_from_url(url: str, ext: str = ".ogg") -> str:
+async def cache_audio_from_url(url: str, ext: str = ".ogg", retries: int = 2) -> str:
     """
     Download an audio file from a URL and save it to the local cache.
 
+    Retries on transient failures (timeouts, 429, 5xx) with exponential
+    backoff so a single slow CDN response doesn't lose the media.
+
     Args:
         url: The HTTP/HTTPS URL to download from.
         ext: File extension including the dot (e.g. ".ogg", ".mp3").
+        retries: Number of retry attempts on transient failures.
 
     Returns:
         Absolute path to the cached audio file as a string.
     """
+    import asyncio
     import httpx
+    import logging as _logging
+    _log = _logging.getLogger(__name__)
 
+    last_exc = None
     async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
-        response = await client.get(
-            url,
-            headers={
-                "User-Agent": "Mozilla/5.0 (compatible; HermesAgent/1.0)",
-                "Accept": "audio/*,*/*;q=0.8",
-            },
-        )
-        response.raise_for_status()
-        return cache_audio_from_bytes(response.content, ext)
+        for attempt in range(retries + 1):
+            try:
+                response = await client.get(
+                    url,
+                    headers={
+                        "User-Agent": "Mozilla/5.0 (compatible; HermesAgent/1.0)",
+                        "Accept": "audio/*,*/*;q=0.8",
+                    },
+                )
+                response.raise_for_status()
+                return cache_audio_from_bytes(response.content, ext)
+            except (httpx.TimeoutException, httpx.HTTPStatusError) as exc:
+                last_exc = exc
+                if isinstance(exc, httpx.HTTPStatusError) and exc.response.status_code < 429:
+                    raise
+                if attempt < retries:
+                    wait = 1.5 * (attempt + 1)
+                    _log.debug("Audio cache retry %d/%d for %s (%.1fs): %s",
+                               attempt + 1, retries, url[:80], wait, exc)
+                    await asyncio.sleep(wait)
+                    continue
+                raise
+    raise last_exc
 
 
 # ---------------------------------------------------------------------------
@@ -206,7 +229,7 @@ async def cache_audio_from_url(url: str, ext: str = ".ogg") -> str:
 # here so the agent can reference them by local file path.
 # ---------------------------------------------------------------------------
 
-DOCUMENT_CACHE_DIR = get_hermes_home() / "document_cache"
+DOCUMENT_CACHE_DIR = get_hermes_dir("cache/documents", "document_cache")
 
 SUPPORTED_DOCUMENT_TYPES = {
     ".pdf": "application/pdf",

gateway/platforms/discord.py

@@ -550,6 +550,22 @@ class DiscordAdapter(BasePlatformAdapter):
                             return
                     # "all" falls through to handle_message
                 
+                # If the message @mentions other users but NOT the bot, the
+                # sender is talking to someone else — stay silent.  Only
+                # applies in server channels; in DMs the user is always
+                # talking to the bot (mentions are just references).
+                # Controlled by DISCORD_IGNORE_NO_MENTION (default: true).
+                _ignore_no_mention = os.getenv(
+                    "DISCORD_IGNORE_NO_MENTION", "true"
+                ).lower() in ("true", "1", "yes")
+                if _ignore_no_mention and message.mentions and not isinstance(message.channel, discord.DMChannel):
+                    _bot_mentioned = (
+                        self._client.user is not None
+                        and self._client.user in message.mentions
+                    )
+                    if not _bot_mentioned:
+                        return  # Talking to someone else, don't interrupt
+
                 await self._handle_message(message)
 
             @self._client.event

gateway/platforms/email.py

@@ -43,6 +43,20 @@ from gateway.platforms.base import (
 from gateway.config import Platform, PlatformConfig
 
 logger = logging.getLogger(__name__)
+# Automated sender patterns — emails from these are silently ignored
+_NOREPLY_PATTERNS = (
+    "noreply", "no-reply", "no_reply", "donotreply", "do-not-reply",
+    "mailer-daemon", "postmaster", "bounce", "notifications@",
+    "automated@", "auto-confirm", "auto-reply", "automailer",
+)
+
+# RFC headers that indicate bulk/automated mail
+_AUTOMATED_HEADERS = {
+    "Auto-Submitted": lambda v: v.lower() != "no",
+    "Precedence": lambda v: v.lower() in ("bulk", "list", "junk"),
+    "X-Auto-Response-Suppress": lambda v: bool(v),
+    "List-Unsubscribe": lambda v: bool(v),
+}
 
 # Gmail-safe max length per email body
 MAX_MESSAGE_LENGTH = 50_000
@@ -50,7 +64,17 @@ MAX_MESSAGE_LENGTH = 50_000
 # Supported image extensions for inline detection
 _IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".gif", ".webp"}
 
-
+def _is_automated_sender(address: str, headers: dict) -> bool:
+    """Return True if this email is from an automated/noreply source."""
+    addr = address.lower()
+    if any(pattern in addr for pattern in _NOREPLY_PATTERNS):
+        return True
+    for header, check in _AUTOMATED_HEADERS.items():
+        value = headers.get(header, "")
+        if value and check(value):
+            return True
+    return False
+    
 def check_email_requirements() -> bool:
     """Check if email platform dependencies are available."""
     addr = os.getenv("EMAIL_ADDRESS")
@@ -346,6 +370,11 @@ class EmailAdapter(BasePlatformAdapter):
                 subject = _decode_header_value(msg.get("Subject", "(no subject)"))
                 message_id = msg.get("Message-ID", "")
                 in_reply_to = msg.get("In-Reply-To", "")
+                # Skip automated/noreply senders before any processing
+                msg_headers = dict(msg.items())
+                if _is_automated_sender(sender_addr, msg_headers):
+                    logger.debug("[Email] Skipping automated sender: %s", sender_addr)
+                    continue
                 body = _extract_text_body(msg)
                 attachments = _extract_attachments(msg, skip_attachments=self._skip_attachments)
 
@@ -374,6 +403,11 @@ class EmailAdapter(BasePlatformAdapter):
         if sender_addr == self._address.lower():
             return
 
+        # Never reply to automated senders
+        if _is_automated_sender(sender_addr, {}):
+            logger.debug("[Email] Dropping automated sender at dispatch: %s", sender_addr)
+            return
+
         subject = msg_data["subject"]
         body = msg_data["body"].strip()
         attachments = msg_data["attachments"]

gateway/platforms/matrix.py

@@ -41,8 +41,8 @@ MAX_MESSAGE_LENGTH = 4000
 
 # Store directory for E2EE keys and sync state.
 # Uses get_hermes_home() so each profile gets its own Matrix store.
-from hermes_constants import get_hermes_home as _get_hermes_home
-_STORE_DIR = _get_hermes_home() / "matrix" / "store"
+from hermes_constants import get_hermes_dir as _get_hermes_dir
+_STORE_DIR = _get_hermes_dir("platforms/matrix/store", "matrix/store")
 
 # Grace period: ignore messages older than this many seconds before startup.
 _STARTUP_GRACE_SECONDS = 5

gateway/platforms/webhook.py

@@ -27,6 +27,7 @@ import hashlib
 import hmac
 import json
 import logging
+import os
 import re
 import subprocess
 import time
@@ -53,6 +54,7 @@ logger = logging.getLogger(__name__)
 DEFAULT_HOST = "0.0.0.0"
 DEFAULT_PORT = 8644
 _INSECURE_NO_AUTH = "INSECURE_NO_AUTH"
+_DYNAMIC_ROUTES_FILENAME = "webhook_subscriptions.json"
 
 
 def check_webhook_requirements() -> bool:
@@ -68,7 +70,10 @@ class WebhookAdapter(BasePlatformAdapter):
         self._host: str = config.extra.get("host", DEFAULT_HOST)
         self._port: int = int(config.extra.get("port", DEFAULT_PORT))
         self._global_secret: str = config.extra.get("secret", "")
-        self._routes: Dict[str, dict] = config.extra.get("routes", {})
+        self._static_routes: Dict[str, dict] = config.extra.get("routes", {})
+        self._dynamic_routes: Dict[str, dict] = {}
+        self._dynamic_routes_mtime: float = 0.0
+        self._routes: Dict[str, dict] = dict(self._static_routes)
         self._runner = None
 
         # Delivery info keyed by session chat_id — consumed by send()
@@ -96,6 +101,9 @@ class WebhookAdapter(BasePlatformAdapter):
     # ------------------------------------------------------------------
 
     async def connect(self) -> bool:
+        # Load agent-created subscriptions before validating
+        self._reload_dynamic_routes()
+
         # Validate routes at startup — secret is required per route
         for name, route in self._routes.items():
             secret = route.get("secret", self._global_secret)
@@ -182,8 +190,46 @@ class WebhookAdapter(BasePlatformAdapter):
         """GET /health — simple health check."""
         return web.json_response({"status": "ok", "platform": "webhook"})
 
+    def _reload_dynamic_routes(self) -> None:
+        """Reload agent-created subscriptions from disk if the file changed."""
+        from pathlib import Path as _Path
+        hermes_home = _Path(
+            os.getenv("HERMES_HOME", str(_Path.home() / ".hermes"))
+        ).expanduser()
+        subs_path = hermes_home / _DYNAMIC_ROUTES_FILENAME
+        if not subs_path.exists():
+            if self._dynamic_routes:
+                self._dynamic_routes = {}
+                self._routes = dict(self._static_routes)
+                logger.debug("[webhook] Dynamic subscriptions file removed, cleared dynamic routes")
+            return
+        try:
+            mtime = subs_path.stat().st_mtime
+            if mtime <= self._dynamic_routes_mtime:
+                return  # No change
+            data = json.loads(subs_path.read_text(encoding="utf-8"))
+            if not isinstance(data, dict):
+                return
+            # Merge: static routes take precedence over dynamic ones
+            self._dynamic_routes = {
+                k: v for k, v in data.items()
+                if k not in self._static_routes
+            }
+            self._routes = {**self._dynamic_routes, **self._static_routes}
+            self._dynamic_routes_mtime = mtime
+            logger.info(
+                "[webhook] Reloaded %d dynamic route(s): %s",
+                len(self._dynamic_routes),
+                ", ".join(self._dynamic_routes.keys()) or "(none)",
+            )
+        except Exception as e:
+            logger.warning("[webhook] Failed to reload dynamic routes: %s", e)
+
     async def _handle_webhook(self, request: "web.Request") -> "web.Response":
         """POST /webhooks/{route_name} — receive and process a webhook event."""
+        # Hot-reload dynamic subscriptions on each request (mtime-gated, cheap)
+        self._reload_dynamic_routes()
+
         route_name = request.match_info.get("route_name", "")
         route_config = self._routes.get(route_name)
 

gateway/platforms/whatsapp.py

@@ -26,6 +26,7 @@ from pathlib import Path
 from typing import Dict, Optional, Any
 
 from hermes_cli.config import get_hermes_home
+from hermes_constants import get_hermes_dir
 
 logger = logging.getLogger(__name__)
 
@@ -134,7 +135,7 @@ class WhatsAppAdapter(BasePlatformAdapter):
         )
         self._session_path: Path = Path(config.extra.get(
             "session_path",
-            get_hermes_home() / "whatsapp" / "session"
+            get_hermes_dir("platforms/whatsapp/session", "whatsapp/session")
         ))
         self._reply_prefix: Optional[str] = config.extra.get("reply_prefix")
         self._message_queue: asyncio.Queue = asyncio.Queue()

gateway/run.py

@@ -288,7 +288,7 @@ def _resolve_gateway_model(config: dict | None = None) -> str:
     if isinstance(model_cfg, str):
         model = model_cfg
     elif isinstance(model_cfg, dict):
-        model = model_cfg.get("default", model)
+        model = model_cfg.get("default") or model_cfg.get("model") or model
     return model
 
 
@@ -432,7 +432,7 @@ class GatewayRunner:
             from honcho_integration.session import HonchoSessionManager
 
             hcfg = HonchoClientConfig.from_global_config()
-            if not hcfg.enabled or not hcfg.api_key:
+            if not hcfg.enabled or not (hcfg.api_key or hcfg.base_url):
                 return None, hcfg
 
             client = get_honcho_client(hcfg)
@@ -2093,7 +2093,7 @@ class GatewayRunner:
                     if isinstance(_model_cfg, str):
                         _hyg_model = _model_cfg
                     elif isinstance(_model_cfg, dict):
-                        _hyg_model = _model_cfg.get("default", _hyg_model)
+                        _hyg_model = _model_cfg.get("default") or _model_cfg.get("model") or _hyg_model
                         # Read explicit context_length override from model config
                         # (same as run_agent.py lines 995-1005)
                         _raw_ctx = _model_cfg.get("context_length")
@@ -4190,7 +4190,7 @@ class GatewayRunner:
             ]
             ctx = agent.context_compressor
             if ctx.last_prompt_tokens:
-                pct = ctx.last_prompt_tokens / ctx.context_length * 100 if ctx.context_length else 0
+                pct = min(100, ctx.last_prompt_tokens / ctx.context_length * 100) if ctx.context_length else 0
                 lines.append(f"Context: {ctx.last_prompt_tokens:,} / {ctx.context_length:,} ({pct:.0f}%)")
             if ctx.compression_count:
                 lines.append(f"Compressions: {ctx.compression_count}")

hermes_cli/config.py

@@ -227,42 +227,49 @@ DEFAULT_CONFIG = {
             "model": "",
             "base_url": "",
             "api_key": "",
+            "timeout": 30,         # seconds — increase for slow local models
         },
         "compression": {
             "provider": "auto",
             "model": "",
             "base_url": "",
             "api_key": "",
+            "timeout": 120,        # seconds — compression summarises large contexts; increase for local models
         },
         "session_search": {
             "provider": "auto",
             "model": "",
             "base_url": "",
             "api_key": "",
+            "timeout": 30,
         },
         "skills_hub": {
             "provider": "auto",
             "model": "",
             "base_url": "",
             "api_key": "",
+            "timeout": 30,
         },
         "approval": {
             "provider": "auto",
             "model": "",           # fast/cheap model recommended (e.g. gemini-flash, haiku)
             "base_url": "",
             "api_key": "",
+            "timeout": 30,
         },
         "mcp": {
             "provider": "auto",
             "model": "",
             "base_url": "",
             "api_key": "",
+            "timeout": 30,
         },
         "flush_memories": {
             "provider": "auto",
             "model": "",
             "base_url": "",
             "api_key": "",
+            "timeout": 30,
         },
     },
     
@@ -616,6 +623,14 @@ OPTIONAL_ENV_VARS = {
     },
 
     # ── Tool API keys ──
+    "EXA_API_KEY": {
+        "description": "Exa API key for AI-native web search and contents",
+        "prompt": "Exa API key",
+        "url": "https://exa.ai/",
+        "tools": ["web_search", "web_extract"],
+        "password": True,
+        "category": "tool",
+    },
     "PARALLEL_API_KEY": {
         "description": "Parallel API key for AI-native web search and extract",
         "prompt": "Parallel API key",
@@ -1672,6 +1687,7 @@ def show_config():
     keys = [
         ("OPENROUTER_API_KEY", "OpenRouter"),
         ("VOICE_TOOLS_OPENAI_KEY", "OpenAI (STT/TTS)"),
+        ("EXA_API_KEY", "Exa"),
         ("PARALLEL_API_KEY", "Parallel"),
         ("FIRECRAWL_API_KEY", "Firecrawl"),
         ("TAVILY_API_KEY", "Tavily"),
@@ -1831,7 +1847,7 @@ def set_config_value(key: str, value: str):
     # Check if it's an API key (goes to .env)
     api_keys = [
         'OPENROUTER_API_KEY', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'VOICE_TOOLS_OPENAI_KEY',
-        'PARALLEL_API_KEY', 'FIRECRAWL_API_KEY', 'FIRECRAWL_API_URL', 'TAVILY_API_KEY',
+        'EXA_API_KEY', 'PARALLEL_API_KEY', 'FIRECRAWL_API_KEY', 'FIRECRAWL_API_URL', 'TAVILY_API_KEY',
         'BROWSERBASE_API_KEY', 'BROWSERBASE_PROJECT_ID', 'BROWSER_USE_API_KEY',
         'FAL_KEY', 'TELEGRAM_BOT_TOKEN', 'DISCORD_BOT_TOKEN',
         'TERMINAL_SSH_HOST', 'TERMINAL_SSH_USER', 'TERMINAL_SSH_KEY',

hermes_cli/doctor.py

@@ -56,7 +56,7 @@ def _honcho_is_configured_for_doctor() -> bool:
         from honcho_integration.client import HonchoClientConfig
 
         cfg = HonchoClientConfig.from_global_config()
-        return bool(cfg.enabled and cfg.api_key)
+        return bool(cfg.enabled and (cfg.api_key or cfg.base_url))
     except Exception:
         return False
 
@@ -708,8 +708,8 @@ def run_doctor(args):
             check_warn("Honcho config not found", "run: hermes honcho setup")
         elif not hcfg.enabled:
             check_info(f"Honcho disabled (set enabled: true in {_honcho_cfg_path} to activate)")
-        elif not hcfg.api_key:
-            check_fail("Honcho API key not set", "run: hermes honcho setup")
+        elif not (hcfg.api_key or hcfg.base_url):
+            check_fail("Honcho API key or base URL not set", "run: hermes honcho setup")
             issues.append("No Honcho API key — run 'hermes honcho setup'")
         else:
             from honcho_integration.client import get_honcho_client, reset_honcho_client

hermes_cli/gateway.py

@@ -948,13 +948,24 @@ def launchd_uninstall():
     print("✓ Service uninstalled")
 
 def launchd_start():
-    refresh_launchd_plist_if_needed()
     plist_path = get_launchd_plist_path()
     label = get_launchd_label()
+
+    # Self-heal if the plist is missing entirely (e.g., manual cleanup, failed upgrade)
+    if not plist_path.exists():
+        print("↻ launchd plist missing; regenerating service definition")
+        plist_path.parent.mkdir(parents=True, exist_ok=True)
+        plist_path.write_text(generate_launchd_plist(), encoding="utf-8")
+        subprocess.run(["launchctl", "load", str(plist_path)], check=True)
+        subprocess.run(["launchctl", "start", label], check=True)
+        print("✓ Service started")
+        return
+
+    refresh_launchd_plist_if_needed()
     try:
         subprocess.run(["launchctl", "start", label], check=True)
     except subprocess.CalledProcessError as e:
-        if e.returncode != 3 or not plist_path.exists():
+        if e.returncode != 3:
             raise
         print("↻ launchd job was unloaded; reloading service definition")
         subprocess.run(["launchctl", "load", str(plist_path)], check=True)

hermes_cli/main.py

@@ -2339,6 +2339,12 @@ def cmd_cron(args):
     cron_command(args)
 
 
+def cmd_webhook(args):
+    """Webhook subscription management."""
+    from hermes_cli.webhook import webhook_command
+    webhook_command(args)
+
+
 def cmd_doctor(args):
     """Check configuration and dependencies."""
     from hermes_cli.doctor import run_doctor
@@ -2470,8 +2476,18 @@ def _update_via_zip(args):
             )
     else:
         # Use sys.executable to explicitly call the venv's pip module,
-        # avoiding PEP 668 'externally-managed-environment' errors on Debian/Ubuntu
+        # avoiding PEP 668 'externally-managed-environment' errors on Debian/Ubuntu.
+        # Some environments lose pip inside the venv; bootstrap it back with
+        # ensurepip before trying the editable install.
         pip_cmd = [sys.executable, "-m", "pip"]
+        try:
+            subprocess.run(pip_cmd + ["--version"], cwd=PROJECT_ROOT, check=True, capture_output=True)
+        except subprocess.CalledProcessError:
+            subprocess.run(
+                [sys.executable, "-m", "ensurepip", "--upgrade", "--default-pip"],
+                cwd=PROJECT_ROOT,
+                check=True,
+            )
         try:
             subprocess.run(pip_cmd + ["install", "-e", ".[all]", "--quiet"], cwd=PROJECT_ROOT, check=True)
         except subprocess.CalledProcessError:
@@ -2857,8 +2873,18 @@ def cmd_update(args):
                 )
         else:
             # Use sys.executable to explicitly call the venv's pip module,
-            # avoiding PEP 668 'externally-managed-environment' errors on Debian/Ubuntu
+            # avoiding PEP 668 'externally-managed-environment' errors on Debian/Ubuntu.
+            # Some environments lose pip inside the venv; bootstrap it back with
+            # ensurepip before trying the editable install.
             pip_cmd = [sys.executable, "-m", "pip"]
+            try:
+                subprocess.run(pip_cmd + ["--version"], cwd=PROJECT_ROOT, check=True, capture_output=True)
+            except subprocess.CalledProcessError:
+                subprocess.run(
+                    [sys.executable, "-m", "ensurepip", "--upgrade", "--default-pip"],
+                    cwd=PROJECT_ROOT,
+                    check=True,
+                )
             try:
                 subprocess.run(pip_cmd + ["install", "-e", ".[all]", "--quiet"], cwd=PROJECT_ROOT, check=True)
             except subprocess.CalledProcessError:
@@ -3523,7 +3549,38 @@ For more help on a command:
     cron_subparsers.add_parser("tick", help="Run due jobs once and exit")
 
     cron_parser.set_defaults(func=cmd_cron)
-    
+
+    # =========================================================================
+    # webhook command
+    # =========================================================================
+    webhook_parser = subparsers.add_parser(
+        "webhook",
+        help="Manage dynamic webhook subscriptions",
+        description="Create, list, and remove webhook subscriptions for event-driven agent activation",
+    )
+    webhook_subparsers = webhook_parser.add_subparsers(dest="webhook_action")
+
+    wh_sub = webhook_subparsers.add_parser("subscribe", aliases=["add"], help="Create a webhook subscription")
+    wh_sub.add_argument("name", help="Route name (used in URL: /webhooks/<name>)")
+    wh_sub.add_argument("--prompt", default="", help="Prompt template with {dot.notation} payload refs")
+    wh_sub.add_argument("--events", default="", help="Comma-separated event types to accept")
+    wh_sub.add_argument("--description", default="", help="What this subscription does")
+    wh_sub.add_argument("--skills", default="", help="Comma-separated skill names to load")
+    wh_sub.add_argument("--deliver", default="log", help="Delivery target: log, telegram, discord, slack, etc.")
+    wh_sub.add_argument("--deliver-chat-id", default="", help="Target chat ID for cross-platform delivery")
+    wh_sub.add_argument("--secret", default="", help="HMAC secret (auto-generated if omitted)")
+
+    webhook_subparsers.add_parser("list", aliases=["ls"], help="List all dynamic subscriptions")
+
+    wh_rm = webhook_subparsers.add_parser("remove", aliases=["rm"], help="Remove a subscription")
+    wh_rm.add_argument("name", help="Subscription name to remove")
+
+    wh_test = webhook_subparsers.add_parser("test", help="Send a test POST to a webhook route")
+    wh_test.add_argument("name", help="Subscription name to test")
+    wh_test.add_argument("--payload", default="", help="JSON payload to send (default: test payload)")
+
+    webhook_parser.set_defaults(func=cmd_webhook)
+
     # =========================================================================
     # doctor command
     # =========================================================================
@@ -3656,7 +3713,7 @@ For more help on a command:
     skills_snapshot = skills_subparsers.add_parser("snapshot", help="Export/import skill configurations")
     snapshot_subparsers = skills_snapshot.add_subparsers(dest="snapshot_action")
     snap_export = snapshot_subparsers.add_parser("export", help="Export installed skills to a file")
-    snap_export.add_argument("output", help="Output JSON file path")
+    snap_export.add_argument("output", help="Output JSON file path (use - for stdout)")
     snap_import = snapshot_subparsers.add_parser("import", help="Import and install skills from a file")
     snap_import.add_argument("input", help="Input JSON file path")
     snap_import.add_argument("--force", action="store_true", help="Force install despite caution verdict")
@@ -3933,7 +3990,7 @@ For more help on a command:
     sessions_list.add_argument("--limit", type=int, default=20, help="Max sessions to show")
 
     sessions_export = sessions_subparsers.add_parser("export", help="Export sessions to a JSONL file")
-    sessions_export.add_argument("output", help="Output JSONL file path")
+    sessions_export.add_argument("output", help="Output JSONL file path (use - for stdout)")
     sessions_export.add_argument("--source", help="Filter by source")
     sessions_export.add_argument("--session-id", help="Export a specific session")
 
@@ -4014,15 +4071,25 @@ For more help on a command:
                 if not data:
                     print(f"Session '{args.session_id}' not found.")
                     return
-                with open(args.output, "w", encoding="utf-8") as f:
-                    f.write(_json.dumps(data, ensure_ascii=False) + "\n")
-                print(f"Exported 1 session to {args.output}")
+                line = _json.dumps(data, ensure_ascii=False) + "\n"
+                if args.output == "-":
+                    import sys
+                    sys.stdout.write(line)
+                else:
+                    with open(args.output, "w", encoding="utf-8") as f:
+                        f.write(line)
+                    print(f"Exported 1 session to {args.output}")
             else:
                 sessions = db.export_all(source=args.source)
-                with open(args.output, "w", encoding="utf-8") as f:
+                if args.output == "-":
+                    import sys
                     for s in sessions:
-                        f.write(_json.dumps(s, ensure_ascii=False) + "\n")
-                print(f"Exported {len(sessions)} sessions to {args.output}")
+                        sys.stdout.write(_json.dumps(s, ensure_ascii=False) + "\n")
+                else:
+                    with open(args.output, "w", encoding="utf-8") as f:
+                        for s in sessions:
+                            f.write(_json.dumps(s, ensure_ascii=False) + "\n")
+                    print(f"Exported {len(sessions)} sessions to {args.output}")
 
         elif action == "delete":
             resolved_session_id = db.resolve_session_id(args.session_id)

hermes_cli/runtime_provider.py

@@ -63,6 +63,9 @@ def _get_model_config() -> Dict[str, Any]:
     model_cfg = config.get("model")
     if isinstance(model_cfg, dict):
         cfg = dict(model_cfg)
+        # Accept "model" as alias for "default" (users intuitively write model.model)
+        if not cfg.get("default") and cfg.get("model"):
+            cfg["default"] = cfg["model"]
         default = (cfg.get("default") or "").strip()
         base_url = (cfg.get("base_url") or "").strip()
         is_local = "localhost" in base_url or "127.0.0.1" in base_url
@@ -203,7 +206,7 @@ def _resolve_named_custom_runtime(
         or _detect_api_mode_for_url(base_url)
         or "chat_completions",
         "base_url": base_url,
-        "api_key": api_key,
+        "api_key": api_key or "no-key-required",
         "source": f"custom_provider:{custom_provider.get('name', requested_provider)}",
     }
 

hermes_cli/setup.py

@@ -585,11 +585,11 @@ def _print_setup_summary(config: dict, hermes_home):
     else:
         tool_status.append(("Mixture of Agents", False, "OPENROUTER_API_KEY"))
 
-    # Web tools (Parallel, Firecrawl, or Tavily)
-    if get_env_value("PARALLEL_API_KEY") or get_env_value("FIRECRAWL_API_KEY") or get_env_value("FIRECRAWL_API_URL") or get_env_value("TAVILY_API_KEY"):
+    # Web tools (Exa, Parallel, Firecrawl, or Tavily)
+    if get_env_value("EXA_API_KEY") or get_env_value("PARALLEL_API_KEY") or get_env_value("FIRECRAWL_API_KEY") or get_env_value("FIRECRAWL_API_URL") or get_env_value("TAVILY_API_KEY"):
         tool_status.append(("Web Search & Extract", True, None))
     else:
-        tool_status.append(("Web Search & Extract", False, "PARALLEL_API_KEY, FIRECRAWL_API_KEY, or TAVILY_API_KEY"))
+        tool_status.append(("Web Search & Extract", False, "EXA_API_KEY, PARALLEL_API_KEY, FIRECRAWL_API_KEY, or TAVILY_API_KEY"))
 
     # Browser tools (local Chromium or Browserbase cloud)
     import shutil

hermes_cli/skills_hub.py

@@ -887,10 +887,15 @@ def do_snapshot_export(output_path: str, console: Optional[Console] = None) -> N
         "taps": tap_list,
     }
 
-    out = Path(output_path)
-    out.write_text(json.dumps(snapshot, indent=2, ensure_ascii=False) + "\n")
-    c.print(f"[bold green]Snapshot exported:[/] {out}")
-    c.print(f"[dim]{len(installed)} skill(s), {len(tap_list)} tap(s)[/]\n")
+    payload = json.dumps(snapshot, indent=2, ensure_ascii=False) + "\n"
+    if output_path == "-":
+        import sys
+        sys.stdout.write(payload)
+    else:
+        out = Path(output_path)
+        out.write_text(payload)
+        c.print(f"[bold green]Snapshot exported:[/] {out}")
+        c.print(f"[dim]{len(installed)} skill(s), {len(tap_list)} tap(s)[/]\n")
 
 
 def do_snapshot_import(input_path: str, force: bool = False,

hermes_cli/tools_config.py

@@ -190,6 +190,14 @@ TOOL_CATEGORIES = {
                     {"key": "FIRECRAWL_API_KEY", "prompt": "Firecrawl API key", "url": "https://firecrawl.dev"},
                 ],
             },
+            {
+                "name": "Exa",
+                "tag": "AI-native search and contents",
+                "web_backend": "exa",
+                "env_vars": [
+                    {"key": "EXA_API_KEY", "prompt": "Exa API key", "url": "https://exa.ai"},
+                ],
+            },
             {
                 "name": "Parallel",
                 "tag": "AI-native search and extract",

hermes_cli/webhook.py

@@ -0,0 +1,256 @@
+"""hermes webhook — manage dynamic webhook subscriptions from the CLI.
+
+Usage:
+    hermes webhook subscribe <name> [options]
+    hermes webhook list
+    hermes webhook remove <name>
+    hermes webhook test <name> [--payload '{"key": "value"}']
+
+Subscriptions persist to ~/.hermes/webhook_subscriptions.json and are
+hot-reloaded by the webhook adapter without a gateway restart.
+"""
+
+import json
+import os
+import re
+import secrets
+import time
+from pathlib import Path
+from typing import Dict, Optional
+
+
+_SUBSCRIPTIONS_FILENAME = "webhook_subscriptions.json"
+
+
+def _hermes_home() -> Path:
+    return Path(
+        os.getenv("HERMES_HOME", str(Path.home() / ".hermes"))
+    ).expanduser()
+
+
+def _subscriptions_path() -> Path:
+    return _hermes_home() / _SUBSCRIPTIONS_FILENAME
+
+
+def _load_subscriptions() -> Dict[str, dict]:
+    path = _subscriptions_path()
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def _save_subscriptions(subs: Dict[str, dict]) -> None:
+    path = _subscriptions_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(".tmp")
+    tmp_path.write_text(
+        json.dumps(subs, indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+    os.replace(str(tmp_path), str(path))
+
+
+def _get_webhook_config() -> dict:
+    """Load webhook platform config. Returns {} if not configured."""
+    try:
+        from hermes_cli.config import load_config
+        cfg = load_config()
+        return cfg.get("platforms", {}).get("webhook", {})
+    except Exception:
+        return {}
+
+
+def _is_webhook_enabled() -> bool:
+    return bool(_get_webhook_config().get("enabled"))
+
+
+def _get_webhook_base_url() -> str:
+    wh = _get_webhook_config().get("extra", {})
+    host = wh.get("host", "0.0.0.0")
+    port = wh.get("port", 8644)
+    display_host = "localhost" if host == "0.0.0.0" else host
+    return f"http://{display_host}:{port}"
+
+
+_SETUP_HINT = """
+  Webhook platform is not enabled. To set it up:
+
+  1. Run the gateway setup wizard:
+     hermes gateway setup
+
+  2. Or manually add to ~/.hermes/config.yaml:
+     platforms:
+       webhook:
+         enabled: true
+         extra:
+           host: "0.0.0.0"
+           port: 8644
+           secret: "your-global-hmac-secret"
+
+  3. Or set environment variables in ~/.hermes/.env:
+     WEBHOOK_ENABLED=true
+     WEBHOOK_PORT=8644
+     WEBHOOK_SECRET=your-global-secret
+
+  Then start the gateway: hermes gateway run
+"""
+
+
+def _require_webhook_enabled() -> bool:
+    """Check webhook is enabled. Print setup guide and return False if not."""
+    if _is_webhook_enabled():
+        return True
+    print(_SETUP_HINT)
+    return False
+
+
+def webhook_command(args):
+    """Entry point for 'hermes webhook' subcommand."""
+    sub = getattr(args, "webhook_action", None)
+
+    if not sub:
+        print("Usage: hermes webhook {subscribe|list|remove|test}")
+        print("Run 'hermes webhook --help' for details.")
+        return
+
+    if not _require_webhook_enabled():
+        return
+
+    if sub in ("subscribe", "add"):
+        _cmd_subscribe(args)
+    elif sub in ("list", "ls"):
+        _cmd_list(args)
+    elif sub in ("remove", "rm"):
+        _cmd_remove(args)
+    elif sub == "test":
+        _cmd_test(args)
+
+
+def _cmd_subscribe(args):
+    name = args.name.strip().lower().replace(" ", "-")
+    if not re.match(r'^[a-z0-9][a-z0-9_-]*$', name):
+        print(f"Error: Invalid name '{name}'. Use lowercase alphanumeric with hyphens/underscores.")
+        return
+
+    subs = _load_subscriptions()
+    is_update = name in subs
+
+    secret = args.secret or secrets.token_urlsafe(32)
+    events = [e.strip() for e in args.events.split(",")] if args.events else []
+
+    route = {
+        "description": args.description or f"Agent-created subscription: {name}",
+        "events": events,
+        "secret": secret,
+        "prompt": args.prompt or "",
+        "skills": [s.strip() for s in args.skills.split(",")] if args.skills else [],
+        "deliver": args.deliver or "log",
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+
+    if args.deliver_chat_id:
+        route["deliver_extra"] = {"chat_id": args.deliver_chat_id}
+
+    subs[name] = route
+    _save_subscriptions(subs)
+
+    base_url = _get_webhook_base_url()
+    status = "Updated" if is_update else "Created"
+
+    print(f"\n  {status} webhook subscription: {name}")
+    print(f"  URL:    {base_url}/webhooks/{name}")
+    print(f"  Secret: {secret}")
+    if events:
+        print(f"  Events: {', '.join(events)}")
+    else:
+        print("  Events: (all)")
+    print(f"  Deliver: {route['deliver']}")
+    if route.get("prompt"):
+        prompt_preview = route["prompt"][:80] + ("..." if len(route["prompt"]) > 80 else "")
+        print(f"  Prompt: {prompt_preview}")
+    print(f"\n  Configure your service to POST to the URL above.")
+    print(f"  Use the secret for HMAC-SHA256 signature validation.")
+    print(f"  The gateway must be running to receive events (hermes gateway run).\n")
+
+
+def _cmd_list(args):
+    subs = _load_subscriptions()
+    if not subs:
+        print("  No dynamic webhook subscriptions.")
+        print("  Create one with: hermes webhook subscribe <name>")
+        return
+
+    base_url = _get_webhook_base_url()
+    print(f"\n  {len(subs)} webhook subscription(s):\n")
+    for name, route in subs.items():
+        events = ", ".join(route.get("events", [])) or "(all)"
+        deliver = route.get("deliver", "log")
+        desc = route.get("description", "")
+        print(f"  ◆ {name}")
+        if desc:
+            print(f"    {desc}")
+        print(f"    URL:     {base_url}/webhooks/{name}")
+        print(f"    Events:  {events}")
+        print(f"    Deliver: {deliver}")
+        print()
+
+
+def _cmd_remove(args):
+    name = args.name.strip().lower()
+    subs = _load_subscriptions()
+
+    if name not in subs:
+        print(f"  No subscription named '{name}'.")
+        print("  Note: Static routes from config.yaml cannot be removed here.")
+        return
+
+    del subs[name]
+    _save_subscriptions(subs)
+    print(f"  Removed webhook subscription: {name}")
+
+
+def _cmd_test(args):
+    """Send a test POST to a webhook route."""
+    name = args.name.strip().lower()
+    subs = _load_subscriptions()
+
+    if name not in subs:
+        print(f"  No subscription named '{name}'.")
+        return
+
+    route = subs[name]
+    secret = route.get("secret", "")
+    base_url = _get_webhook_base_url()
+    url = f"{base_url}/webhooks/{name}"
+
+    payload = args.payload or '{"test": true, "event_type": "test", "message": "Hello from hermes webhook test"}'
+
+    import hmac
+    import hashlib
+    sig = "sha256=" + hmac.new(
+        secret.encode(), payload.encode(), hashlib.sha256
+    ).hexdigest()
+
+    print(f"  Sending test POST to {url}")
+    try:
+        import urllib.request
+        req = urllib.request.Request(
+            url,
+            data=payload.encode(),
+            headers={
+                "Content-Type": "application/json",
+                "X-Hub-Signature-256": sig,
+                "X-GitHub-Event": "test",
+            },
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            body = resp.read().decode()
+            print(f"  Response ({resp.status}): {body}")
+    except Exception as e:
+        print(f"  Error: {e}")
+        print("  Is the gateway running? (hermes gateway run)")

hermes_constants.py

@@ -17,6 +17,27 @@ def get_hermes_home() -> Path:
     return Path(os.getenv("HERMES_HOME", Path.home() / ".hermes"))
 
 
+def get_hermes_dir(new_subpath: str, old_name: str) -> Path:
+    """Resolve a Hermes subdirectory with backward compatibility.
+
+    New installs get the consolidated layout (e.g. ``cache/images``).
+    Existing installs that already have the old path (e.g. ``image_cache``)
+    keep using it — no migration required.
+
+    Args:
+        new_subpath: Preferred path relative to HERMES_HOME (e.g. ``"cache/images"``).
+        old_name: Legacy path relative to HERMES_HOME (e.g. ``"image_cache"``).
+
+    Returns:
+        Absolute ``Path`` — old location if it exists on disk, otherwise the new one.
+    """
+    home = get_hermes_home()
+    old_path = home / old_name
+    if old_path.exists():
+        return old_path
+    return home / new_subpath
+
+
 VALID_REASONING_EFFORTS = ("xhigh", "high", "medium", "low", "minimal")
 
 

honcho_integration/cli.py

@@ -270,7 +270,7 @@ def cmd_status(args) -> None:
             print(f"    {peer}: {mode}")
     print(f"  Write freq:     {hcfg.write_frequency}")
 
-    if hcfg.enabled and hcfg.api_key:
+    if hcfg.enabled and (hcfg.api_key or hcfg.base_url):
         print("\n  Connection... ", end="", flush=True)
         try:
             get_honcho_client(hcfg)
@@ -278,7 +278,7 @@ def cmd_status(args) -> None:
         except Exception as e:
             print(f"FAILED ({e})\n")
     else:
-        reason = "disabled" if not hcfg.enabled else "no API key"
+        reason = "disabled" if not hcfg.enabled else "no API key or base URL"
         print(f"\n  Not connected ({reason})\n")
 
 

honcho_integration/client.py

@@ -417,9 +417,18 @@ def get_honcho_client(config: HonchoClientConfig | None = None) -> Honcho:
     else:
         logger.info("Initializing Honcho client (host: %s, workspace: %s)", config.host, config.workspace_id)
 
+    # Local Honcho instances don't require an API key, but the SDK
+    # expects a non-empty string.  Use a placeholder for local URLs.
+    _is_local = resolved_base_url and (
+        "localhost" in resolved_base_url
+        or "127.0.0.1" in resolved_base_url
+        or "::1" in resolved_base_url
+    )
+    effective_api_key = config.api_key or ("local" if _is_local else None)
+
     kwargs: dict = {
         "workspace_id": config.workspace_id,
-        "api_key": config.api_key,
+        "api_key": effective_api_key,
         "environment": config.environment,
     }
     if resolved_base_url:

nix/nixosModules.nix

@@ -111,6 +111,7 @@
       fi
       mkdir -p "$TARGET_HOME"
       chown "$HERMES_UID:$HERMES_GID" "$TARGET_HOME"
+      chmod 0750 "$TARGET_HOME"
 
       # Ensure HERMES_HOME is owned by the target user
       if [ -n "''${HERMES_HOME:-}" ] && [ -d "$HERMES_HOME" ]; then
@@ -551,8 +552,8 @@
       # ── Directories ───────────────────────────────────────────────────
       {
         systemd.tmpfiles.rules = [
-          "d ${cfg.stateDir}                0755 ${cfg.user} ${cfg.group} - -"
-          "d ${cfg.stateDir}/.hermes        0755 ${cfg.user} ${cfg.group} - -"
+          "d ${cfg.stateDir}                0750 ${cfg.user} ${cfg.group} - -"
+          "d ${cfg.stateDir}/.hermes        0750 ${cfg.user} ${cfg.group} - -"
           "d ${cfg.stateDir}/home           0750 ${cfg.user} ${cfg.group} - -"
           "d ${cfg.workingDirectory}         0750 ${cfg.user} ${cfg.group} - -"
         ];
@@ -566,21 +567,23 @@
           mkdir -p ${cfg.stateDir}/home
           mkdir -p ${cfg.workingDirectory}
           chown ${cfg.user}:${cfg.group} ${cfg.stateDir} ${cfg.stateDir}/.hermes ${cfg.stateDir}/home ${cfg.workingDirectory}
+          chmod 0750 ${cfg.stateDir} ${cfg.stateDir}/.hermes ${cfg.stateDir}/home ${cfg.workingDirectory}
 
           # Merge Nix settings into existing config.yaml.
           # Preserves user-added keys (skills, streaming, etc.); Nix keys win.
           # If configFile is user-provided (not generated), overwrite instead of merge.
           ${if cfg.configFile != null then ''
-            install -o ${cfg.user} -g ${cfg.group} -m 0644 -D ${configFile} ${cfg.stateDir}/.hermes/config.yaml
+            install -o ${cfg.user} -g ${cfg.group} -m 0640 -D ${configFile} ${cfg.stateDir}/.hermes/config.yaml
           '' else ''
             ${configMergeScript} ${generatedConfigFile} ${cfg.stateDir}/.hermes/config.yaml
             chown ${cfg.user}:${cfg.group} ${cfg.stateDir}/.hermes/config.yaml
-            chmod 0644 ${cfg.stateDir}/.hermes/config.yaml
+            chmod 0640 ${cfg.stateDir}/.hermes/config.yaml
           ''}
 
           # Managed mode marker (so interactive shells also detect NixOS management)
           touch ${cfg.stateDir}/.hermes/.managed
           chown ${cfg.user}:${cfg.group} ${cfg.stateDir}/.hermes/.managed
+          chmod 0644 ${cfg.stateDir}/.hermes/.managed
 
           # Seed auth file if provided
           ${lib.optionalString (cfg.authFile != null) ''
@@ -612,7 +615,7 @@ HERMES_NIX_ENV_EOF
 
           # Link documents into workspace
           ${lib.concatStringsSep "\n" (lib.mapAttrsToList (name: _value: ''
-            install -o ${cfg.user} -g ${cfg.group} -m 0644 ${documentDerivation}/${name} ${cfg.workingDirectory}/${name}
+            install -o ${cfg.user} -g ${cfg.group} -m 0640 ${documentDerivation}/${name} ${cfg.workingDirectory}/${name}
           '') cfg.documents)}
         '';
       }

pyproject.toml

@@ -26,6 +26,7 @@ dependencies = [
   # Interactive CLI (prompt_toolkit is used directly by cli.py)
   "prompt_toolkit>=3.0.52,<4",
   # Tools
+  "exa-py>=2.9.0,<3",
   "firecrawl-py>=4.16.0,<5",
   "parallel-web>=0.4.2,<1",
   "fal-client>=0.13.1,<1",

run_agent.py

@@ -368,6 +368,48 @@ _BUDGET_WARNING_RE = re.compile(
 )
 
 
+# Regex to match lone surrogate code points (U+D800..U+DFFF).
+# These are invalid in UTF-8 and cause UnicodeEncodeError when the OpenAI SDK
+# serialises messages to JSON.  Common source: clipboard paste from Google Docs
+# or other rich-text editors on some platforms.
+_SURROGATE_RE = re.compile(r'[\ud800-\udfff]')
+
+
+def _sanitize_surrogates(text: str) -> str:
+    """Replace lone surrogate code points with U+FFFD (replacement character).
+
+    Surrogates are invalid in UTF-8 and will crash ``json.dumps()`` inside the
+    OpenAI SDK.  This is a fast no-op when the text contains no surrogates.
+    """
+    if _SURROGATE_RE.search(text):
+        return _SURROGATE_RE.sub('\ufffd', text)
+    return text
+
+
+def _sanitize_messages_surrogates(messages: list) -> bool:
+    """Sanitize surrogate characters from all string content in a messages list.
+
+    Walks message dicts in-place.  Returns True if any surrogates were found
+    and replaced, False otherwise.
+    """
+    found = False
+    for msg in messages:
+        if not isinstance(msg, dict):
+            continue
+        content = msg.get("content")
+        if isinstance(content, str) and _SURROGATE_RE.search(content):
+            msg["content"] = _SURROGATE_RE.sub('\ufffd', content)
+            found = True
+        elif isinstance(content, list):
+            for part in content:
+                if isinstance(part, dict):
+                    text = part.get("text")
+                    if isinstance(text, str) and _SURROGATE_RE.search(text):
+                        part["text"] = _SURROGATE_RE.sub('\ufffd', text)
+                        found = True
+    return found
+
+
 def _strip_budget_warnings_from_history(messages: list) -> None:
     """Remove budget pressure warnings from tool-result messages in-place.
 
@@ -1042,8 +1084,8 @@ class AIAgent:
                     else:
                         if not hcfg.enabled:
                             logger.debug("Honcho disabled in global config")
-                        elif not hcfg.api_key:
-                            logger.debug("Honcho enabled but no API key configured")
+                        elif not (hcfg.api_key or hcfg.base_url):
+                            logger.debug("Honcho enabled but no API key or base URL configured")
                         else:
                             logger.debug("Honcho enabled but missing API key or disabled in config")
             except Exception as e:
@@ -2250,8 +2292,14 @@ class AIAgent:
     # ── Honcho integration helpers ──
 
     def _honcho_should_activate(self, hcfg) -> bool:
-        """Return True when remote Honcho should be active."""
-        if not hcfg or not hcfg.enabled or not hcfg.api_key:
+        """Return True when Honcho should be active.
+
+        Self-hosted Honcho may be configured with a base_url and no API key,
+        so activation should accept either credential style.
+        """
+        if not hcfg or not hcfg.enabled:
+            return False
+        if not (hcfg.api_key or hcfg.base_url):
             return False
         return True
 
@@ -5959,6 +6007,14 @@ class AIAgent:
         # Installed once, transparent when streams are healthy, prevents crash on write.
         _install_safe_stdio()
 
+        # Sanitize surrogate characters from user input.  Clipboard paste from
+        # rich-text editors (Google Docs, Word, etc.) can inject lone surrogates
+        # that are invalid UTF-8 and crash JSON serialization in the OpenAI SDK.
+        if isinstance(user_message, str):
+            user_message = _sanitize_surrogates(user_message)
+        if isinstance(persist_user_message, str):
+            persist_user_message = _sanitize_surrogates(persist_user_message)
+
         # Store stream callback for _interruptible_api_call to pick up
         self._stream_callback = stream_callback
         self._persist_user_message_idx = None
@@ -5975,6 +6031,7 @@ class AIAgent:
         self._codex_incomplete_retries = 0
         self._last_content_with_tools = None
         self._mute_post_response = False
+        self._surrogate_sanitized = False
         # NOTE: _turns_since_memory and _iters_since_skill are NOT reset here.
         # They are initialized in __init__ and must persist across run_conversation
         # calls so that nudge logic accumulates correctly in CLI mode.
@@ -6810,6 +6867,24 @@ class AIAgent:
                     if self.thinking_callback:
                         self.thinking_callback("")
 
+                    # -----------------------------------------------------------
+                    # Surrogate character recovery.  UnicodeEncodeError happens
+                    # when the messages contain lone surrogates (U+D800..U+DFFF)
+                    # that are invalid UTF-8.  Common source: clipboard paste
+                    # from Google Docs or similar rich-text editors.  We sanitize
+                    # the entire messages list in-place and retry once.
+                    # -----------------------------------------------------------
+                    if isinstance(api_error, UnicodeEncodeError) and not getattr(self, '_surrogate_sanitized', False):
+                        self._surrogate_sanitized = True
+                        if _sanitize_messages_surrogates(messages):
+                            self._vprint(
+                                f"{self.log_prefix}⚠️  Stripped invalid surrogate characters from messages. Retrying...",
+                                force=True,
+                            )
+                            continue
+                        # Surrogates weren't in messages — might be in system
+                        # prompt or prefill.  Fall through to normal error path.
+
                     status_code = getattr(api_error, "status_code", None)
                     if (
                         self.api_mode == "codex_responses"
@@ -7078,8 +7153,13 @@ class AIAgent:
                     # 529 (Anthropic overloaded) is also transient.
                     # Also catch local validation errors (ValueError, TypeError) — these
                     # are programming bugs, not transient failures.
+                    # Exclude UnicodeEncodeError — it's a ValueError subclass but is
+                    # handled separately by the surrogate sanitization path above.
                     _RETRYABLE_STATUS_CODES = {413, 429, 529}
-                    is_local_validation_error = isinstance(api_error, (ValueError, TypeError))
+                    is_local_validation_error = (
+                        isinstance(api_error, (ValueError, TypeError))
+                        and not isinstance(api_error, UnicodeEncodeError)
+                    )
                     # Detect generic 400s from Anthropic OAuth (transient server-side failures).
                     # Real invalid_request_error responses include a descriptive message;
                     # transient ones contain only "Error" or are empty. (ref: issue #1608)

skills/devops/webhook-subscriptions/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: webhook-subscriptions
+description: Create and manage webhook subscriptions for event-driven agent activation. Use when the user wants external services to trigger agent runs automatically.
+version: 1.0.0
+metadata:
+  hermes:
+    tags: [webhook, events, automation, integrations]
+---
+
+# Webhook Subscriptions
+
+Create dynamic webhook subscriptions so external services (GitHub, GitLab, Stripe, CI/CD, IoT sensors, monitoring tools) can trigger Hermes agent runs by POSTing events to a URL.
+
+## Setup (Required First)
+
+The webhook platform must be enabled before subscriptions can be created. Check with:
+```bash
+hermes webhook list
+```
+
+If it says "Webhook platform is not enabled", set it up:
+
+### Option 1: Setup wizard
+```bash
+hermes gateway setup
+```
+Follow the prompts to enable webhooks, set the port, and set a global HMAC secret.
+
+### Option 2: Manual config
+Add to `~/.hermes/config.yaml`:
+```yaml
+platforms:
+  webhook:
+    enabled: true
+    extra:
+      host: "0.0.0.0"
+      port: 8644
+      secret: "generate-a-strong-secret-here"
+```
+
+### Option 3: Environment variables
+Add to `~/.hermes/.env`:
+```bash
+WEBHOOK_ENABLED=true
+WEBHOOK_PORT=8644
+WEBHOOK_SECRET=generate-a-strong-secret-here
+```
+
+After configuration, start (or restart) the gateway:
+```bash
+hermes gateway run
+# Or if using systemd:
+systemctl --user restart hermes-gateway
+```
+
+Verify it's running:
+```bash
+curl http://localhost:8644/health
+```
+
+## Commands
+
+All management is via the `hermes webhook` CLI command:
+
+### Create a subscription
+```bash
+hermes webhook subscribe <name> \
+  --prompt "Prompt template with {payload.fields}" \
+  --events "event1,event2" \
+  --description "What this does" \
+  --skills "skill1,skill2" \
+  --deliver telegram \
+  --deliver-chat-id "12345" \
+  --secret "optional-custom-secret"
+```
+
+Returns the webhook URL and HMAC secret. The user configures their service to POST to that URL.
+
+### List subscriptions
+```bash
+hermes webhook list
+```
+
+### Remove a subscription
+```bash
+hermes webhook remove <name>
+```
+
+### Test a subscription
+```bash
+hermes webhook test <name>
+hermes webhook test <name> --payload '{"key": "value"}'
+```
+
+## Prompt Templates
+
+Prompts support `{dot.notation}` for accessing nested payload fields:
+
+- `{issue.title}` — GitHub issue title
+- `{pull_request.user.login}` — PR author
+- `{data.object.amount}` — Stripe payment amount
+- `{sensor.temperature}` — IoT sensor reading
+
+If no prompt is specified, the full JSON payload is dumped into the agent prompt.
+
+## Common Patterns
+
+### GitHub: new issues
+```bash
+hermes webhook subscribe github-issues \
+  --events "issues" \
+  --prompt "New GitHub issue #{issue.number}: {issue.title}\n\nAction: {action}\nAuthor: {issue.user.login}\nBody:\n{issue.body}\n\nPlease triage this issue." \
+  --deliver telegram \
+  --deliver-chat-id "-100123456789"
+```
+
+Then in GitHub repo Settings → Webhooks → Add webhook:
+- Payload URL: the returned webhook_url
+- Content type: application/json
+- Secret: the returned secret
+- Events: "Issues"
+
+### GitHub: PR reviews
+```bash
+hermes webhook subscribe github-prs \
+  --events "pull_request" \
+  --prompt "PR #{pull_request.number} {action}: {pull_request.title}\nBy: {pull_request.user.login}\nBranch: {pull_request.head.ref}\n\n{pull_request.body}" \
+  --skills "github-code-review" \
+  --deliver github_comment
+```
+
+### Stripe: payment events
+```bash
+hermes webhook subscribe stripe-payments \
+  --events "payment_intent.succeeded,payment_intent.payment_failed" \
+  --prompt "Payment {data.object.status}: {data.object.amount} cents from {data.object.receipt_email}" \
+  --deliver telegram \
+  --deliver-chat-id "-100123456789"
+```
+
+### CI/CD: build notifications
+```bash
+hermes webhook subscribe ci-builds \
+  --events "pipeline" \
+  --prompt "Build {object_attributes.status} on {project.name} branch {object_attributes.ref}\nCommit: {commit.message}" \
+  --deliver discord \
+  --deliver-chat-id "1234567890"
+```
+
+### Generic monitoring alert
+```bash
+hermes webhook subscribe alerts \
+  --prompt "Alert: {alert.name}\nSeverity: {alert.severity}\nMessage: {alert.message}\n\nPlease investigate and suggest remediation." \
+  --deliver origin
+```
+
+## Security
+
+- Each subscription gets an auto-generated HMAC-SHA256 secret (or provide your own with `--secret`)
+- The webhook adapter validates signatures on every incoming POST
+- Static routes from config.yaml cannot be overwritten by dynamic subscriptions
+- Subscriptions persist to `~/.hermes/webhook_subscriptions.json`
+
+## How It Works
+
+1. `hermes webhook subscribe` writes to `~/.hermes/webhook_subscriptions.json`
+2. The webhook adapter hot-reloads this file on each incoming request (mtime-gated, negligible overhead)
+3. When a POST arrives matching a route, the adapter formats the prompt and triggers an agent run
+4. The agent's response is delivered to the configured target (Telegram, Discord, GitHub comment, etc.)
+
+## Troubleshooting
+
+If webhooks aren't working:
+
+1. **Is the gateway running?** Check with `systemctl --user status hermes-gateway` or `ps aux | grep gateway`
+2. **Is the webhook server listening?** `curl http://localhost:8644/health` should return `{"status": "ok"}`
+3. **Check gateway logs:** `grep webhook ~/.hermes/logs/gateway.log | tail -20`
+4. **Signature mismatch?** Verify the secret in your service matches the one from `hermes webhook list`. GitHub sends `X-Hub-Signature-256`, GitLab sends `X-Gitlab-Token`.
+5. **Firewall/NAT?** The webhook URL must be reachable from the service. For local development, use a tunnel (ngrok, cloudflared).
+6. **Wrong event type?** Check `--events` filter matches what the service sends. Use `hermes webhook test <name>` to verify the route works.

skills/github/github-auth/SKILL.md

@@ -219,6 +219,9 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
   echo "AUTH_METHOD=gh"
 elif [ -n "$GITHUB_TOKEN" ]; then
   echo "AUTH_METHOD=curl"
+elif [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
+  export GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+  echo "AUTH_METHOD=curl"
 elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
   export GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
   echo "AUTH_METHOD=curl"

skills/github/github-auth/scripts/gh-env.sh

@@ -23,6 +23,11 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1; then
     GH_USER=$(gh api user --jq '.login' 2>/dev/null)
 elif [ -n "$GITHUB_TOKEN" ]; then
     GH_AUTH_METHOD="curl"
+elif [ -f "$HOME/.hermes/.env" ] && grep -q "^GITHUB_TOKEN=" "$HOME/.hermes/.env" 2>/dev/null; then
+    GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$HOME/.hermes/.env" | head -1 | cut -d= -f2 | tr -d '\n\r')
+    if [ -n "$GITHUB_TOKEN" ]; then
+        GH_AUTH_METHOD="curl"
+    fi
 elif [ -f "$HOME/.git-credentials" ] && grep -q "github.com" "$HOME/.git-credentials" 2>/dev/null; then
     GITHUB_TOKEN=$(grep "github.com" "$HOME/.git-credentials" | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
     if [ -n "$GITHUB_TOKEN" ]; then

skills/github/github-code-review/SKILL.md

@@ -27,7 +27,11 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
 else
   AUTH="git"
   if [ -z "$GITHUB_TOKEN" ]; then
-    GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    fi
   fi
 fi
 

skills/github/github-issues/SKILL.md

@@ -27,7 +27,11 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
 else
   AUTH="git"
   if [ -z "$GITHUB_TOKEN" ]; then
-    GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    fi
   fi
 fi
 

skills/github/github-pr-workflow/SKILL.md

@@ -29,7 +29,11 @@ else
   AUTH="git"
   # Ensure we have a token for API calls
   if [ -z "$GITHUB_TOKEN" ]; then
-    GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    fi
   fi
 fi
 echo "Using: $AUTH"

skills/github/github-repo-management/SKILL.md

@@ -26,7 +26,11 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
 else
   AUTH="git"
   if [ -z "$GITHUB_TOKEN" ]; then
-    GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    fi
   fi
 fi
 

tests/gateway/test_media_download_retry.py

@@ -171,6 +171,170 @@ class TestCacheImageFromUrl:
         mock_sleep.assert_not_called()
 
 
+# ---------------------------------------------------------------------------
+# cache_audio_from_url (base.py)
+# ---------------------------------------------------------------------------
+
+class TestCacheAudioFromUrl:
+    """Tests for gateway.platforms.base.cache_audio_from_url"""
+
+    def test_success_on_first_attempt(self, tmp_path, monkeypatch):
+        """A clean 200 response caches the audio and returns a path."""
+        monkeypatch.setattr("gateway.platforms.base.AUDIO_CACHE_DIR", tmp_path / "audio")
+
+        fake_response = MagicMock()
+        fake_response.content = b"\x00\x01 fake audio"
+        fake_response.raise_for_status = MagicMock()
+
+        mock_client = AsyncMock()
+        mock_client.get = AsyncMock(return_value=fake_response)
+        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+        mock_client.__aexit__ = AsyncMock(return_value=False)
+
+        async def run():
+            with patch("httpx.AsyncClient", return_value=mock_client):
+                from gateway.platforms.base import cache_audio_from_url
+                return await cache_audio_from_url(
+                    "http://example.com/voice.ogg", ext=".ogg"
+                )
+
+        path = asyncio.run(run())
+        assert path.endswith(".ogg")
+        mock_client.get.assert_called_once()
+
+    def test_retries_on_timeout_then_succeeds(self, tmp_path, monkeypatch):
+        """A timeout on the first attempt is retried; second attempt succeeds."""
+        monkeypatch.setattr("gateway.platforms.base.AUDIO_CACHE_DIR", tmp_path / "audio")
+
+        fake_response = MagicMock()
+        fake_response.content = b"audio data"
+        fake_response.raise_for_status = MagicMock()
+
+        mock_client = AsyncMock()
+        mock_client.get = AsyncMock(
+            side_effect=[_make_timeout_error(), fake_response]
+        )
+        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+        mock_client.__aexit__ = AsyncMock(return_value=False)
+
+        mock_sleep = AsyncMock()
+
+        async def run():
+            with patch("httpx.AsyncClient", return_value=mock_client), \
+                 patch("asyncio.sleep", mock_sleep):
+                from gateway.platforms.base import cache_audio_from_url
+                return await cache_audio_from_url(
+                    "http://example.com/voice.ogg", ext=".ogg", retries=2
+                )
+
+        path = asyncio.run(run())
+        assert path.endswith(".ogg")
+        assert mock_client.get.call_count == 2
+        mock_sleep.assert_called_once()
+
+    def test_retries_on_429_then_succeeds(self, tmp_path, monkeypatch):
+        """A 429 response on the first attempt is retried; second attempt succeeds."""
+        monkeypatch.setattr("gateway.platforms.base.AUDIO_CACHE_DIR", tmp_path / "audio")
+
+        ok_response = MagicMock()
+        ok_response.content = b"audio data"
+        ok_response.raise_for_status = MagicMock()
+
+        mock_client = AsyncMock()
+        mock_client.get = AsyncMock(
+            side_effect=[_make_http_status_error(429), ok_response]
+        )
+        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+        mock_client.__aexit__ = AsyncMock(return_value=False)
+
+        async def run():
+            with patch("httpx.AsyncClient", return_value=mock_client), \
+                 patch("asyncio.sleep", new_callable=AsyncMock):
+                from gateway.platforms.base import cache_audio_from_url
+                return await cache_audio_from_url(
+                    "http://example.com/voice.ogg", ext=".ogg", retries=2
+                )
+
+        path = asyncio.run(run())
+        assert path.endswith(".ogg")
+        assert mock_client.get.call_count == 2
+
+    def test_retries_on_500_then_succeeds(self, tmp_path, monkeypatch):
+        """A 500 response on the first attempt is retried; second attempt succeeds."""
+        monkeypatch.setattr("gateway.platforms.base.AUDIO_CACHE_DIR", tmp_path / "audio")
+
+        ok_response = MagicMock()
+        ok_response.content = b"audio data"
+        ok_response.raise_for_status = MagicMock()
+
+        mock_client = AsyncMock()
+        mock_client.get = AsyncMock(
+            side_effect=[_make_http_status_error(500), ok_response]
+        )
+        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+        mock_client.__aexit__ = AsyncMock(return_value=False)
+
+        async def run():
+            with patch("httpx.AsyncClient", return_value=mock_client), \
+                 patch("asyncio.sleep", new_callable=AsyncMock):
+                from gateway.platforms.base import cache_audio_from_url
+                return await cache_audio_from_url(
+                    "http://example.com/voice.ogg", ext=".ogg", retries=2
+                )
+
+        path = asyncio.run(run())
+        assert path.endswith(".ogg")
+        assert mock_client.get.call_count == 2
+
+    def test_raises_after_max_retries_exhausted(self, tmp_path, monkeypatch):
+        """Timeout on every attempt raises after all retries are consumed."""
+        monkeypatch.setattr("gateway.platforms.base.AUDIO_CACHE_DIR", tmp_path / "audio")
+
+        mock_client = AsyncMock()
+        mock_client.get = AsyncMock(side_effect=_make_timeout_error())
+        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+        mock_client.__aexit__ = AsyncMock(return_value=False)
+
+        async def run():
+            with patch("httpx.AsyncClient", return_value=mock_client), \
+                 patch("asyncio.sleep", new_callable=AsyncMock):
+                from gateway.platforms.base import cache_audio_from_url
+                await cache_audio_from_url(
+                    "http://example.com/voice.ogg", ext=".ogg", retries=2
+                )
+
+        with pytest.raises(httpx.TimeoutException):
+            asyncio.run(run())
+
+        # 3 total calls: initial + 2 retries
+        assert mock_client.get.call_count == 3
+
+    def test_non_retryable_4xx_raises_immediately(self, tmp_path, monkeypatch):
+        """A 404 (non-retryable) is raised immediately without any retry."""
+        monkeypatch.setattr("gateway.platforms.base.AUDIO_CACHE_DIR", tmp_path / "audio")
+
+        mock_sleep = AsyncMock()
+        mock_client = AsyncMock()
+        mock_client.get = AsyncMock(side_effect=_make_http_status_error(404))
+        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+        mock_client.__aexit__ = AsyncMock(return_value=False)
+
+        async def run():
+            with patch("httpx.AsyncClient", return_value=mock_client), \
+                 patch("asyncio.sleep", mock_sleep):
+                from gateway.platforms.base import cache_audio_from_url
+                await cache_audio_from_url(
+                    "http://example.com/voice.ogg", ext=".ogg", retries=2
+                )
+
+        with pytest.raises(httpx.HTTPStatusError):
+            asyncio.run(run())
+
+        # Only 1 attempt, no sleep
+        assert mock_client.get.call_count == 1
+        mock_sleep.assert_not_called()
+
+
 # ---------------------------------------------------------------------------
 # Slack mock setup (mirrors existing test_slack.py approach)
 # ---------------------------------------------------------------------------

tests/gateway/test_webhook_dynamic_routes.py

@@ -0,0 +1,87 @@
+"""Tests for webhook adapter dynamic route loading."""
+
+import json
+import os
+import pytest
+from pathlib import Path
+
+from gateway.config import PlatformConfig
+from gateway.platforms.webhook import WebhookAdapter, _DYNAMIC_ROUTES_FILENAME
+
+
+def _make_adapter(routes=None, extra=None):
+    _extra = extra or {}
+    if routes:
+        _extra["routes"] = routes
+    _extra.setdefault("secret", "test-global-secret")
+    config = PlatformConfig(enabled=True, extra=_extra)
+    return WebhookAdapter(config)
+
+
+@pytest.fixture(autouse=True)
+def _isolate(tmp_path, monkeypatch):
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+
+
+class TestDynamicRouteLoading:
+    def test_no_dynamic_file(self):
+        adapter = _make_adapter(routes={"static": {"secret": "s"}})
+        adapter._reload_dynamic_routes()
+        assert "static" in adapter._routes
+        assert len(adapter._dynamic_routes) == 0
+
+    def test_loads_dynamic_routes(self, tmp_path):
+        subs = {"my-hook": {"secret": "dynamic-secret", "prompt": "test", "events": []}}
+        (tmp_path / _DYNAMIC_ROUTES_FILENAME).write_text(json.dumps(subs))
+
+        adapter = _make_adapter(routes={"static": {"secret": "s"}})
+        adapter._reload_dynamic_routes()
+        assert "my-hook" in adapter._routes
+        assert "static" in adapter._routes
+
+    def test_static_takes_precedence(self, tmp_path):
+        (tmp_path / _DYNAMIC_ROUTES_FILENAME).write_text(
+            json.dumps({"conflict": {"secret": "dynamic", "prompt": "dyn"}})
+        )
+        adapter = _make_adapter(routes={"conflict": {"secret": "static", "prompt": "stat"}})
+        adapter._reload_dynamic_routes()
+        assert adapter._routes["conflict"]["secret"] == "static"
+
+    def test_mtime_gated(self, tmp_path):
+        import time
+        path = tmp_path / _DYNAMIC_ROUTES_FILENAME
+        path.write_text(json.dumps({"v1": {"secret": "s"}}))
+
+        adapter = _make_adapter()
+        adapter._reload_dynamic_routes()
+        assert "v1" in adapter._dynamic_routes
+
+        # Same mtime — no reload
+        adapter._dynamic_routes["injected"] = True
+        adapter._reload_dynamic_routes()
+        assert "injected" in adapter._dynamic_routes
+
+        # New write — reloads
+        time.sleep(0.05)
+        path.write_text(json.dumps({"v2": {"secret": "s"}}))
+        adapter._reload_dynamic_routes()
+        assert "v2" in adapter._dynamic_routes
+        assert "v1" not in adapter._dynamic_routes
+
+    def test_file_removal_clears(self, tmp_path):
+        path = tmp_path / _DYNAMIC_ROUTES_FILENAME
+        path.write_text(json.dumps({"temp": {"secret": "s"}}))
+        adapter = _make_adapter()
+        adapter._reload_dynamic_routes()
+        assert "temp" in adapter._dynamic_routes
+
+        path.unlink()
+        adapter._reload_dynamic_routes()
+        assert len(adapter._dynamic_routes) == 0
+
+    def test_corrupted_file(self, tmp_path):
+        (tmp_path / _DYNAMIC_ROUTES_FILENAME).write_text("not json")
+        adapter = _make_adapter(routes={"static": {"secret": "s"}})
+        adapter._reload_dynamic_routes()
+        assert "static" in adapter._routes
+        assert len(adapter._dynamic_routes) == 0

tests/hermes_cli/test_update_gateway_restart.py

@@ -240,6 +240,33 @@ class TestLaunchdPlistRefresh:
         assert any("unload" in s for s in cmd_strs)
         assert any("start" in s for s in cmd_strs)
 
+    def test_launchd_start_recreates_missing_plist_and_loads_service(self, tmp_path, monkeypatch):
+        """launchd_start self-heals when the plist file is missing entirely."""
+        plist_path = tmp_path / "ai.hermes.gateway.plist"
+        assert not plist_path.exists()
+
+        monkeypatch.setattr(gateway_cli, "get_launchd_plist_path", lambda: plist_path)
+
+        calls = []
+        def fake_run(cmd, check=False, **kwargs):
+            calls.append(cmd)
+            return SimpleNamespace(returncode=0, stdout="", stderr="")
+
+        monkeypatch.setattr(gateway_cli.subprocess, "run", fake_run)
+
+        gateway_cli.launchd_start()
+
+        # Should have created the plist
+        assert plist_path.exists()
+        assert "--replace" in plist_path.read_text()
+
+        cmd_strs = [" ".join(c) for c in calls]
+        # Should load the new plist, then start
+        assert any("load" in s for s in cmd_strs)
+        assert any("start" in s for s in cmd_strs)
+        # Should NOT call unload (nothing to unload)
+        assert not any("unload" in s for s in cmd_strs)
+
 
 class TestCmdUpdateLaunchdRestart:
     """cmd_update correctly detects and handles launchd on macOS."""

tests/hermes_cli/test_webhook_cli.py

@@ -0,0 +1,189 @@
+"""Tests for hermes_cli/webhook.py — webhook subscription CLI."""
+
+import json
+import os
+import pytest
+from argparse import Namespace
+from pathlib import Path
+
+from hermes_cli.webhook import (
+    webhook_command,
+    _load_subscriptions,
+    _save_subscriptions,
+    _subscriptions_path,
+    _is_webhook_enabled,
+)
+
+
+@pytest.fixture(autouse=True)
+def _isolate(tmp_path, monkeypatch):
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+    # Default: webhooks enabled (most tests need this)
+    monkeypatch.setattr(
+        "hermes_cli.webhook._is_webhook_enabled", lambda: True
+    )
+
+
+def _make_args(**kwargs):
+    defaults = {
+        "webhook_action": None,
+        "name": "",
+        "prompt": "",
+        "events": "",
+        "description": "",
+        "skills": "",
+        "deliver": "log",
+        "deliver_chat_id": "",
+        "secret": "",
+        "payload": "",
+    }
+    defaults.update(kwargs)
+    return Namespace(**defaults)
+
+
+class TestSubscribe:
+    def test_basic_create(self, capsys):
+        webhook_command(_make_args(webhook_action="subscribe", name="test-hook"))
+        out = capsys.readouterr().out
+        assert "Created" in out
+        assert "/webhooks/test-hook" in out
+        subs = _load_subscriptions()
+        assert "test-hook" in subs
+
+    def test_with_options(self, capsys):
+        webhook_command(_make_args(
+            webhook_action="subscribe",
+            name="gh-issues",
+            events="issues,pull_request",
+            prompt="Issue: {issue.title}",
+            deliver="telegram",
+            deliver_chat_id="12345",
+            description="Watch GitHub",
+        ))
+        subs = _load_subscriptions()
+        route = subs["gh-issues"]
+        assert route["events"] == ["issues", "pull_request"]
+        assert route["prompt"] == "Issue: {issue.title}"
+        assert route["deliver"] == "telegram"
+        assert route["deliver_extra"] == {"chat_id": "12345"}
+
+    def test_custom_secret(self):
+        webhook_command(_make_args(
+            webhook_action="subscribe", name="s", secret="my-secret"
+        ))
+        assert _load_subscriptions()["s"]["secret"] == "my-secret"
+
+    def test_auto_secret(self):
+        webhook_command(_make_args(webhook_action="subscribe", name="s"))
+        secret = _load_subscriptions()["s"]["secret"]
+        assert len(secret) > 20
+
+    def test_update(self, capsys):
+        webhook_command(_make_args(webhook_action="subscribe", name="x", prompt="v1"))
+        webhook_command(_make_args(webhook_action="subscribe", name="x", prompt="v2"))
+        out = capsys.readouterr().out
+        assert "Updated" in out
+        assert _load_subscriptions()["x"]["prompt"] == "v2"
+
+    def test_invalid_name(self, capsys):
+        webhook_command(_make_args(webhook_action="subscribe", name="bad name!"))
+        out = capsys.readouterr().out
+        assert "Error" in out or "Invalid" in out
+        assert _load_subscriptions() == {}
+
+
+class TestList:
+    def test_empty(self, capsys):
+        webhook_command(_make_args(webhook_action="list"))
+        out = capsys.readouterr().out
+        assert "No dynamic" in out
+
+    def test_with_entries(self, capsys):
+        webhook_command(_make_args(webhook_action="subscribe", name="a"))
+        webhook_command(_make_args(webhook_action="subscribe", name="b"))
+        capsys.readouterr()  # clear
+        webhook_command(_make_args(webhook_action="list"))
+        out = capsys.readouterr().out
+        assert "2 webhook" in out
+        assert "a" in out
+        assert "b" in out
+
+
+class TestRemove:
+    def test_remove_existing(self, capsys):
+        webhook_command(_make_args(webhook_action="subscribe", name="temp"))
+        webhook_command(_make_args(webhook_action="remove", name="temp"))
+        out = capsys.readouterr().out
+        assert "Removed" in out
+        assert _load_subscriptions() == {}
+
+    def test_remove_nonexistent(self, capsys):
+        webhook_command(_make_args(webhook_action="remove", name="nope"))
+        out = capsys.readouterr().out
+        assert "No subscription" in out
+
+    def test_selective_remove(self):
+        webhook_command(_make_args(webhook_action="subscribe", name="keep"))
+        webhook_command(_make_args(webhook_action="subscribe", name="drop"))
+        webhook_command(_make_args(webhook_action="remove", name="drop"))
+        subs = _load_subscriptions()
+        assert "keep" in subs
+        assert "drop" not in subs
+
+
+class TestPersistence:
+    def test_file_written(self):
+        webhook_command(_make_args(webhook_action="subscribe", name="persist"))
+        path = _subscriptions_path()
+        assert path.exists()
+        data = json.loads(path.read_text())
+        assert "persist" in data
+
+    def test_corrupted_file(self):
+        path = _subscriptions_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("broken{{{")
+        assert _load_subscriptions() == {}
+
+
+class TestWebhookEnabledGate:
+    def test_blocks_when_disabled(self, capsys, monkeypatch):
+        monkeypatch.setattr("hermes_cli.webhook._is_webhook_enabled", lambda: False)
+        webhook_command(_make_args(webhook_action="subscribe", name="blocked"))
+        out = capsys.readouterr().out
+        assert "not enabled" in out.lower()
+        assert "hermes gateway setup" in out
+        assert _load_subscriptions() == {}
+
+    def test_blocks_list_when_disabled(self, capsys, monkeypatch):
+        monkeypatch.setattr("hermes_cli.webhook._is_webhook_enabled", lambda: False)
+        webhook_command(_make_args(webhook_action="list"))
+        out = capsys.readouterr().out
+        assert "not enabled" in out.lower()
+
+    def test_allows_when_enabled(self, capsys):
+        # _is_webhook_enabled already patched to True by autouse fixture
+        webhook_command(_make_args(webhook_action="subscribe", name="allowed"))
+        out = capsys.readouterr().out
+        assert "Created" in out
+        assert "allowed" in _load_subscriptions()
+
+    def test_real_check_disabled(self, monkeypatch):
+        monkeypatch.setattr(
+            "hermes_cli.webhook._get_webhook_config",
+            lambda: {},
+        )
+        monkeypatch.setattr(
+            "hermes_cli.webhook._is_webhook_enabled",
+            lambda: bool({}.get("enabled")),
+        )
+        import hermes_cli.webhook as wh_mod
+        assert wh_mod._is_webhook_enabled() is False
+
+    def test_real_check_enabled(self, monkeypatch):
+        monkeypatch.setattr(
+            "hermes_cli.webhook._is_webhook_enabled",
+            lambda: True,
+        )
+        import hermes_cli.webhook as wh_mod
+        assert wh_mod._is_webhook_enabled() is True

tests/test_percentage_clamp.py

@@ -0,0 +1,154 @@
+"""Tests for percentage clamping at 100% across display paths.
+
+PR #3480 capped context pressure percentage at 100% in agent/display.py
+but missed the same unclamped pattern in 4 other files. When token counts
+overshoot the context length (possible during streaming or before
+compression fires), users see >100% in /stats, gateway status, and
+memory tool output.
+"""
+
+import pytest
+
+
+class TestContextCompressorUsagePercent:
+    """agent/context_compressor.py — get_status() usage_percent"""
+
+    def test_usage_percent_capped_at_100(self):
+        """Tokens exceeding context_length should still show max 100%."""
+        from agent.context_compressor import ContextCompressor
+
+        comp = ContextCompressor.__new__(ContextCompressor)
+        comp.last_prompt_tokens = 210_000  # exceeds context_length
+        comp.context_length = 200_000
+        comp.threshold_tokens = 160_000
+        comp.compression_count = 0
+
+        status = comp.get_status()
+        assert status["usage_percent"] <= 100
+
+    def test_usage_percent_normal(self):
+        """Normal usage should show correct percentage."""
+        from agent.context_compressor import ContextCompressor
+
+        comp = ContextCompressor.__new__(ContextCompressor)
+        comp.last_prompt_tokens = 100_000
+        comp.context_length = 200_000
+        comp.threshold_tokens = 160_000
+        comp.compression_count = 0
+
+        status = comp.get_status()
+        assert status["usage_percent"] == 50.0
+
+    def test_usage_percent_zero_context_length(self):
+        """Zero context_length should return 0, not crash."""
+        from agent.context_compressor import ContextCompressor
+
+        comp = ContextCompressor.__new__(ContextCompressor)
+        comp.last_prompt_tokens = 1000
+        comp.context_length = 0
+        comp.threshold_tokens = 0
+        comp.compression_count = 0
+
+        status = comp.get_status()
+        assert status["usage_percent"] == 0
+
+
+class TestMemoryToolPercentClamp:
+    """tools/memory_tool.py — _success_response and _render_block pct"""
+
+    def test_over_limit_clamped_at_100(self):
+        """Percentage should be capped at 100 even if current > limit."""
+        # Simulate the calculation directly
+        current = 5500
+        limit = 5000
+        pct = min(100, int((current / limit) * 100)) if limit > 0 else 0
+        assert pct == 100
+
+    def test_normal_percentage(self):
+        current = 2500
+        limit = 5000
+        pct = min(100, int((current / limit) * 100)) if limit > 0 else 0
+        assert pct == 50
+
+    def test_zero_limit_returns_zero(self):
+        current = 100
+        limit = 0
+        pct = min(100, int((current / limit) * 100)) if limit > 0 else 0
+        assert pct == 0
+
+
+class TestCLIStatsPercentClamp:
+    """cli.py — /stats command percentage"""
+
+    def test_over_context_clamped_at_100(self):
+        """Tokens exceeding context_length should show max 100%."""
+        last_prompt = 210_000
+        ctx_len = 200_000
+        pct = min(100, (last_prompt / ctx_len * 100)) if ctx_len else 0
+        assert pct == 100
+
+    def test_normal_context(self):
+        last_prompt = 100_000
+        ctx_len = 200_000
+        pct = min(100, (last_prompt / ctx_len * 100)) if ctx_len else 0
+        assert pct == 50.0
+
+    def test_zero_context_length(self):
+        last_prompt = 1000
+        ctx_len = 0
+        pct = min(100, (last_prompt / ctx_len * 100)) if ctx_len else 0
+        assert pct == 0
+
+
+class TestGatewayStatsPercentClamp:
+    """gateway/run.py — _format_usage_stats percentage"""
+
+    def test_over_context_clamped_at_100(self):
+        last_prompt_tokens = 210_000
+        context_length = 200_000
+        pct = min(100, last_prompt_tokens / context_length * 100) if context_length else 0
+        assert pct == 100
+
+    def test_normal_context(self):
+        last_prompt_tokens = 150_000
+        context_length = 200_000
+        pct = min(100, last_prompt_tokens / context_length * 100) if context_length else 0
+        assert pct == 75.0
+
+
+class TestSourceLinesAreClamped:
+    """Verify the actual source files have min(100, ...) applied."""
+
+    @staticmethod
+    def _read_file(rel_path: str) -> str:
+        import os
+        base = os.path.dirname(os.path.dirname(__file__))
+        with open(os.path.join(base, rel_path)) as f:
+            return f.read()
+
+    def test_context_compressor_clamped(self):
+        src = self._read_file("agent/context_compressor.py")
+        assert "min(100," in src, (
+            "context_compressor.py usage_percent is not clamped with min(100, ...)"
+        )
+
+    def test_gateway_run_clamped(self):
+        src = self._read_file("gateway/run.py")
+        # Check that the stats handler has min(100, ...)
+        assert "min(100, ctx.last_prompt_tokens" in src, (
+            "gateway/run.py stats pct is not clamped with min(100, ...)"
+        )
+
+    def test_cli_clamped(self):
+        src = self._read_file("cli.py")
+        assert "min(100, (last_prompt" in src, (
+            "cli.py /stats pct is not clamped with min(100, ...)"
+        )
+
+    def test_memory_tool_clamped(self):
+        src = self._read_file("tools/memory_tool.py")
+        # Both _success_response and _render_block should have min(100, ...)
+        count = src.count("min(100, int((current / limit)")
+        assert count >= 2, (
+            f"memory_tool.py has only {count} clamped pct lines, expected >= 2"
+        )

tests/test_surrogate_sanitization.py

@@ -0,0 +1,154 @@
+"""Tests for surrogate character sanitization in user input.
+
+Surrogates (U+D800..U+DFFF) are invalid in UTF-8 and crash json.dumps()
+inside the OpenAI SDK. They can appear via clipboard paste from rich-text
+editors like Google Docs.
+"""
+import json
+import pytest
+from unittest.mock import MagicMock, patch
+
+from run_agent import (
+    _sanitize_surrogates,
+    _sanitize_messages_surrogates,
+    _SURROGATE_RE,
+)
+
+
+class TestSanitizeSurrogates:
+    """Test the _sanitize_surrogates() helper."""
+
+    def test_normal_text_unchanged(self):
+        text = "Hello, this is normal text with unicode: café ñ 日本語 🎉"
+        assert _sanitize_surrogates(text) == text
+
+    def test_empty_string(self):
+        assert _sanitize_surrogates("") == ""
+
+    def test_single_surrogate_replaced(self):
+        result = _sanitize_surrogates("Hello \udce2 world")
+        assert result == "Hello \ufffd world"
+
+    def test_multiple_surrogates_replaced(self):
+        result = _sanitize_surrogates("a\ud800b\udc00c\udfff")
+        assert result == "a\ufffdb\ufffdc\ufffd"
+
+    def test_all_surrogate_range(self):
+        """Verify the regex catches the full surrogate range."""
+        for cp in [0xD800, 0xD900, 0xDA00, 0xDB00, 0xDC00, 0xDD00, 0xDE00, 0xDF00, 0xDFFF]:
+            text = f"test{chr(cp)}end"
+            result = _sanitize_surrogates(text)
+            assert '\ufffd' in result, f"Surrogate U+{cp:04X} not caught"
+
+    def test_result_is_json_serializable(self):
+        """Sanitized text must survive json.dumps + utf-8 encoding."""
+        dirty = "data \udce2\udcb0 from clipboard"
+        clean = _sanitize_surrogates(dirty)
+        serialized = json.dumps({"content": clean}, ensure_ascii=False)
+        # Must not raise UnicodeEncodeError
+        serialized.encode("utf-8")
+
+    def test_original_surrogates_fail_encoding(self):
+        """Confirm the original bug: surrogates crash utf-8 encoding."""
+        dirty = "data \udce2 from clipboard"
+        serialized = json.dumps({"content": dirty}, ensure_ascii=False)
+        with pytest.raises(UnicodeEncodeError):
+            serialized.encode("utf-8")
+
+
+class TestSanitizeMessagesSurrogates:
+    """Test the _sanitize_messages_surrogates() helper for message lists."""
+
+    def test_clean_messages_returns_false(self):
+        msgs = [
+            {"role": "user", "content": "all clean"},
+            {"role": "assistant", "content": "me too"},
+        ]
+        assert _sanitize_messages_surrogates(msgs) is False
+
+    def test_dirty_string_content_sanitized(self):
+        msgs = [
+            {"role": "user", "content": "text with \udce2 surrogate"},
+        ]
+        assert _sanitize_messages_surrogates(msgs) is True
+        assert "\ufffd" in msgs[0]["content"]
+        assert "\udce2" not in msgs[0]["content"]
+
+    def test_dirty_multimodal_content_sanitized(self):
+        msgs = [
+            {"role": "user", "content": [
+                {"type": "text", "text": "multimodal \udce2 content"},
+                {"type": "image_url", "image_url": {"url": "http://example.com"}},
+            ]},
+        ]
+        assert _sanitize_messages_surrogates(msgs) is True
+        assert "\ufffd" in msgs[0]["content"][0]["text"]
+        assert "\udce2" not in msgs[0]["content"][0]["text"]
+
+    def test_mixed_clean_and_dirty(self):
+        msgs = [
+            {"role": "user", "content": "clean text"},
+            {"role": "user", "content": "dirty \udce2 text"},
+            {"role": "assistant", "content": "clean response"},
+        ]
+        assert _sanitize_messages_surrogates(msgs) is True
+        assert msgs[0]["content"] == "clean text"
+        assert "\ufffd" in msgs[1]["content"]
+        assert msgs[2]["content"] == "clean response"
+
+    def test_non_dict_items_skipped(self):
+        msgs = ["not a dict", {"role": "user", "content": "ok"}]
+        assert _sanitize_messages_surrogates(msgs) is False
+
+    def test_tool_messages_sanitized(self):
+        """Tool results could also contain surrogates from file reads etc."""
+        msgs = [
+            {"role": "tool", "content": "result with \udce2 data", "tool_call_id": "x"},
+        ]
+        assert _sanitize_messages_surrogates(msgs) is True
+        assert "\ufffd" in msgs[0]["content"]
+
+
+class TestRunConversationSurrogateSanitization:
+    """Integration: verify run_conversation sanitizes user_message."""
+
+    @patch("run_agent.AIAgent._build_system_prompt")
+    @patch("run_agent.AIAgent._interruptible_streaming_api_call")
+    @patch("run_agent.AIAgent._interruptible_api_call")
+    def test_user_message_surrogates_sanitized(self, mock_api, mock_stream, mock_sys):
+        """Surrogates in user_message are stripped before API call."""
+        from run_agent import AIAgent
+
+        mock_sys.return_value = "system prompt"
+
+        # Mock streaming to return a simple response
+        mock_choice = MagicMock()
+        mock_choice.message.content = "response"
+        mock_choice.message.tool_calls = None
+        mock_choice.message.refusal = None
+        mock_choice.finish_reason = "stop"
+        mock_choice.message.reasoning_content = None
+
+        mock_response = MagicMock()
+        mock_response.choices = [mock_choice]
+        mock_response.usage = MagicMock(prompt_tokens=10, completion_tokens=5, total_tokens=15)
+        mock_response.model = "test-model"
+        mock_response.id = "test-id"
+
+        mock_stream.return_value = mock_response
+        mock_api.return_value = mock_response
+
+        agent = AIAgent(model="test/model", quiet_mode=True, skip_memory=True, skip_context_files=True)
+        agent.client = MagicMock()
+
+        # Pass a message with surrogates
+        result = agent.run_conversation(
+            user_message="test \udce2 message",
+            conversation_history=[],
+        )
+
+        # The message stored in history should have surrogates replaced
+        for msg in result.get("messages", []):
+            if msg.get("role") == "user":
+                assert "\udce2" not in msg["content"], "Surrogate leaked into stored message"
+                assert "\ufffd" in msg["content"], "Replacement char not in stored message"

tests/tools/test_approval.py

@@ -512,6 +512,30 @@ class TestGatewayProtection:
         dangerous, key, desc = detect_dangerous_command(cmd)
         assert dangerous is False
 
+    def test_pkill_hermes_detected(self):
+        """pkill targeting hermes/gateway processes must be caught."""
+        cmd = 'pkill -f "cli.py --gateway"'
+        dangerous, key, desc = detect_dangerous_command(cmd)
+        assert dangerous is True
+        assert "self-termination" in desc
+
+    def test_killall_hermes_detected(self):
+        cmd = "killall hermes"
+        dangerous, key, desc = detect_dangerous_command(cmd)
+        assert dangerous is True
+        assert "self-termination" in desc
+
+    def test_pkill_gateway_detected(self):
+        cmd = "pkill -f gateway"
+        dangerous, key, desc = detect_dangerous_command(cmd)
+        assert dangerous is True
+
+    def test_pkill_unrelated_not_flagged(self):
+        """pkill targeting unrelated processes should not be flagged."""
+        cmd = "pkill -f nginx"
+        dangerous, key, desc = detect_dangerous_command(cmd)
+        assert dangerous is False
+
 
 class TestNormalizationBypass:
     """Obfuscation techniques must not bypass dangerous command detection."""

tests/tools/test_browser_content_none_guard.py

@@ -0,0 +1,109 @@
+"""Tests for None guard on browser_tool LLM response content.
+
+browser_tool.py has two call sites that access response.choices[0].message.content
+without checking for None — _extract_relevant_content (line 996) and
+browser_vision (line 1626). When reasoning-only models (DeepSeek-R1, QwQ)
+return content=None, these produce null snapshots or null analysis.
+
+These tests verify both sites are guarded.
+"""
+
+import types
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+# ── helpers ────────────────────────────────────────────────────────────────
+
+def _make_response(content):
+    """Build a minimal OpenAI-compatible ChatCompletion response stub."""
+    message = types.SimpleNamespace(content=content)
+    choice = types.SimpleNamespace(message=message)
+    return types.SimpleNamespace(choices=[choice])
+
+
+# ── _extract_relevant_content (line 996) ──────────────────────────────────
+
+class TestExtractRelevantContentNoneGuard:
+    """tools/browser_tool.py — _extract_relevant_content()"""
+
+    def test_none_content_falls_back_to_truncated(self):
+        """When LLM returns None content, should fall back to truncated snapshot."""
+        with patch("tools.browser_tool.call_llm", return_value=_make_response(None)), \
+             patch("tools.browser_tool._get_extraction_model", return_value="test-model"):
+            from tools.browser_tool import _extract_relevant_content
+            result = _extract_relevant_content("This is a long snapshot text", "find the button")
+
+        assert result is not None
+        assert isinstance(result, str)
+        assert len(result) > 0
+
+    def test_normal_content_returned(self):
+        """Normal string content should pass through."""
+        with patch("tools.browser_tool.call_llm", return_value=_make_response("Extracted content here")), \
+             patch("tools.browser_tool._get_extraction_model", return_value="test-model"):
+            from tools.browser_tool import _extract_relevant_content
+            result = _extract_relevant_content("snapshot text", "task")
+
+        assert result == "Extracted content here"
+
+    def test_empty_string_content_falls_back(self):
+        """Empty string content should also fall back to truncated."""
+        with patch("tools.browser_tool.call_llm", return_value=_make_response("   ")), \
+             patch("tools.browser_tool._get_extraction_model", return_value="test-model"):
+            from tools.browser_tool import _extract_relevant_content
+            result = _extract_relevant_content("This is a long snapshot text", "task")
+
+        assert result is not None
+        assert len(result) > 0
+
+
+# ── browser_vision (line 1626) ────────────────────────────────────────────
+
+class TestBrowserVisionNoneGuard:
+    """tools/browser_tool.py — browser_vision() analysis extraction"""
+
+    def test_none_content_produces_fallback_message(self):
+        """When LLM returns None content, analysis should have a fallback message."""
+        response = _make_response(None)
+        analysis = (response.choices[0].message.content or "").strip()
+        fallback = analysis or "Vision analysis returned no content."
+
+        assert fallback == "Vision analysis returned no content."
+
+    def test_normal_content_passes_through(self):
+        """Normal analysis content should pass through unchanged."""
+        response = _make_response("  The page shows a login form.  ")
+        analysis = (response.choices[0].message.content or "").strip()
+        fallback = analysis or "Vision analysis returned no content."
+
+        assert fallback == "The page shows a login form."
+
+
+# ── source line verification ──────────────────────────────────────────────
+
+class TestBrowserSourceLinesAreGuarded:
+    """Verify the actual source file has the fix applied."""
+
+    @staticmethod
+    def _read_file() -> str:
+        import os
+        base = os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
+        with open(os.path.join(base, "tools", "browser_tool.py")) as f:
+            return f.read()
+
+    def test_extract_relevant_content_guarded(self):
+        src = self._read_file()
+        # The old unguarded pattern should NOT exist
+        assert "return response.choices[0].message.content\n" not in src, (
+            "browser_tool.py _extract_relevant_content still has unguarded "
+            ".content return — apply None guard"
+        )
+
+    def test_browser_vision_guarded(self):
+        src = self._read_file()
+        assert "analysis = response.choices[0].message.content\n" not in src, (
+            "browser_tool.py browser_vision still has unguarded "
+            ".content assignment — apply None guard"
+        )

tests/tools/test_local_persistent.py

@@ -63,6 +63,18 @@ class TestLocalOneShotRegression:
         assert r["output"].strip() == ""
         env.cleanup()
 
+    def test_oneshot_heredoc_does_not_leak_fence_wrapper(self):
+        """Heredoc closing line must not be merged with the fence wrapper tail."""
+        env = LocalEnvironment(persistent=False)
+        cmd = "cat <<'H_EOF'\nheredoc body line\nH_EOF"
+        r = env.execute(cmd)
+        env.cleanup()
+        assert r["returncode"] == 0
+        assert "heredoc body line" in r["output"]
+        assert "__hermes_rc" not in r["output"]
+        assert "printf '" not in r["output"]
+        assert "exit $" not in r["output"]
+
 
 class TestLocalPersistent:
     @pytest.fixture

tests/tools/test_skill_env_passthrough.py

@@ -63,6 +63,35 @@ class TestSkillViewRegistersPassthrough:
         assert result["success"] is True
         assert is_env_passthrough("TENOR_API_KEY")
 
+    def test_remote_backend_persisted_env_vars_registered(self, tmp_path, monkeypatch):
+        """Remote-backed skills still register locally available env vars."""
+        monkeypatch.setenv("TERMINAL_ENV", "docker")
+        _create_skill(
+            tmp_path,
+            "test-skill",
+            frontmatter_extra=(
+                "required_environment_variables:\n"
+                "  - name: TENOR_API_KEY\n"
+                "    prompt: Enter your Tenor API key\n"
+            ),
+        )
+        monkeypatch.setattr("tools.skills_tool.SKILLS_DIR", tmp_path)
+
+        from hermes_cli.config import save_env_value
+
+        save_env_value("TENOR_API_KEY", "persisted-value-123")
+        monkeypatch.delenv("TENOR_API_KEY", raising=False)
+
+        with patch("tools.skills_tool._secret_capture_callback", None):
+            from tools.skills_tool import skill_view
+
+            result = json.loads(skill_view(name="test-skill"))
+
+        assert result["success"] is True
+        assert result["setup_needed"] is False
+        assert result["missing_required_environment_variables"] == []
+        assert is_env_passthrough("TENOR_API_KEY")
+
     def test_missing_env_vars_not_registered(self, tmp_path, monkeypatch):
         """When a skill declares required_environment_variables but the var is NOT set,
         it should NOT be registered in the passthrough."""

tests/tools/test_skills_tool.py

@@ -813,6 +813,29 @@ class TestSkillViewPrerequisites:
         assert result["setup_needed"] is False
         assert result["missing_required_environment_variables"] == []
 
+    def test_remote_backend_treats_persisted_env_as_available(
+        self, tmp_path, monkeypatch
+    ):
+        monkeypatch.setenv("TERMINAL_ENV", "docker")
+
+        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
+            _make_skill(
+                tmp_path,
+                "remote-ready",
+                frontmatter_extra="prerequisites:\n  env_vars: [PERSISTED_REMOTE_KEY]\n",
+            )
+            from hermes_cli.config import save_env_value
+
+            save_env_value("PERSISTED_REMOTE_KEY", "persisted-value")
+            monkeypatch.delenv("PERSISTED_REMOTE_KEY", raising=False)
+            raw = skill_view("remote-ready")
+
+        result = json.loads(raw)
+        assert result["success"] is True
+        assert result["setup_needed"] is False
+        assert result["missing_required_environment_variables"] == []
+        assert result["readiness_status"] == "available"
+
     def test_no_setup_metadata_when_no_required_envs(self, tmp_path):
         with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
             _make_skill(tmp_path, "plain-skill")
@@ -878,17 +901,11 @@ class TestSkillViewPrerequisites:
         assert result["setup_needed"] is True
 
     @pytest.mark.parametrize(
-        "backend,expected_note",
-        [
-            ("ssh", "remote environment"),
-            ("daytona", "remote environment"),
-            ("docker", "docker-backed skills"),
-            ("singularity", "singularity-backed skills"),
-            ("modal", "modal-backed skills"),
-        ],
+        "backend",
+        ["ssh", "daytona", "docker", "singularity", "modal"],
     )
-    def test_remote_backend_keeps_setup_needed_after_local_secret_capture(
-        self, tmp_path, monkeypatch, backend, expected_note
+    def test_remote_backend_becomes_available_after_local_secret_capture(
+        self, tmp_path, monkeypatch, backend
     ):
         monkeypatch.setenv("TERMINAL_ENV", backend)
         monkeypatch.delenv("TENOR_API_KEY", raising=False)
@@ -926,10 +943,10 @@ class TestSkillViewPrerequisites:
         result = json.loads(raw)
         assert result["success"] is True
         assert len(calls) == 1
-        assert result["setup_needed"] is True
-        assert result["readiness_status"] == "setup_needed"
-        assert result["missing_required_environment_variables"] == ["TENOR_API_KEY"]
-        assert expected_note in result["setup_note"].lower()
+        assert result["setup_needed"] is False
+        assert result["readiness_status"] == "available"
+        assert result["missing_required_environment_variables"] == []
+        assert "setup_note" not in result
 
     def test_skill_view_surfaces_skill_read_errors(self, tmp_path, monkeypatch):
         with patch("tools.skills_tool.SKILLS_DIR", tmp_path):

tools/approval.py

@@ -53,6 +53,8 @@ DANGEROUS_PATTERNS = [
     # Gateway protection: never start gateway outside systemd management
     (r'gateway\s+run\b.*(&\s*$|&\s*;|\bdisown\b|\bsetsid\b)', "start gateway outside systemd (use 'systemctl --user restart hermes-gateway')"),
     (r'\bnohup\b.*gateway\s+run\b', "start gateway outside systemd (use 'systemctl --user restart hermes-gateway')"),
+    # Self-termination protection: prevent agent from killing its own process
+    (r'\b(pkill|killall)\b.*\b(hermes|gateway|cli\.py)\b', "kill hermes/gateway process (self-termination)"),
 ]
 
 

tools/browser_tool.py

@@ -993,7 +993,7 @@ def _extract_relevant_content(
         if model:
             call_kwargs["model"] = model
         response = call_llm(**call_kwargs)
-        return response.choices[0].message.content
+        return (response.choices[0].message.content or "").strip() or _truncate_snapshot(snapshot_text)
     except Exception:
         return _truncate_snapshot(snapshot_text)
 
@@ -1523,8 +1523,8 @@ def browser_vision(question: str, annotate: bool = False, task_id: Optional[str]
     effective_task_id = task_id or "default"
     
     # Save screenshot to persistent location so it can be shared with users
-    hermes_home = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
-    screenshots_dir = hermes_home / "browser_screenshots"
+    from hermes_constants import get_hermes_dir
+    screenshots_dir = get_hermes_dir("cache/screenshots", "browser_screenshots")
     screenshot_path = screenshots_dir / f"browser_screenshot_{uuid_mod.uuid4().hex}.png"
     
     try:
@@ -1623,10 +1623,10 @@ def browser_vision(question: str, annotate: bool = False, task_id: Optional[str]
             call_kwargs["model"] = vision_model
         response = call_llm(**call_kwargs)
         
-        analysis = response.choices[0].message.content
+        analysis = (response.choices[0].message.content or "").strip()
         response_data = {
             "success": True,
-            "analysis": analysis,
+            "analysis": analysis or "Vision analysis returned no content.",
             "screenshot_path": str(screenshot_path),
         }
         # Include annotation data if annotated screenshot was taken

tools/environments/local.py

@@ -391,12 +391,17 @@ class LocalEnvironment(PersistentShellMixin, BaseEnvironment):
             effective_stdin = stdin_data
 
         user_shell = _find_bash()
+        # Newline-separated wrapper (not `cmd; __hermes_rc=...` on one line).
+        # A trailing `; __hermes_rc` glued to `<<EOF` / a closing `EOF` line breaks
+        # heredoc parsing: the delimiter must be alone on its line, otherwise the
+        # rest of this script becomes heredoc body and leaks into stdout (e.g. gh
+        # issue/PR flows that use here-documents for bodies).
         fenced_cmd = (
-            f"printf '{_OUTPUT_FENCE}';"
-            f" {exec_command};"
-            f" __hermes_rc=$?;"
-            f" printf '{_OUTPUT_FENCE}';"
-            f" exit $__hermes_rc"
+            f"printf '{_OUTPUT_FENCE}'\n"
+            f"{exec_command}\n"
+            f"__hermes_rc=$?\n"
+            f"printf '{_OUTPUT_FENCE}'\n"
+            f"exit $__hermes_rc\n"
         )
         run_env = _make_run_env(self.env)
 

tools/mcp_tool.py

@@ -98,6 +98,13 @@ try:
         _MCP_HTTP_AVAILABLE = True
     except ImportError:
         _MCP_HTTP_AVAILABLE = False
+    # Prefer the non-deprecated API (mcp >= 1.24.0); fall back to the
+    # deprecated wrapper for older SDK versions.
+    try:
+        from mcp.client.streamable_http import streamable_http_client
+        _MCP_NEW_HTTP = True
+    except ImportError:
+        _MCP_NEW_HTTP = False
     # Sampling types -- separated so older SDK versions don't break MCP support
     try:
         from mcp.types import (
@@ -762,21 +769,50 @@ class MCPServerTask:
                 logger.warning("MCP OAuth setup failed for '%s': %s", self.name, exc)
 
         sampling_kwargs = self._sampling.session_kwargs() if self._sampling else {}
-        _http_kwargs: dict = {
-            "headers": headers,
-            "timeout": float(connect_timeout),
-        }
-        if _oauth_auth is not None:
-            _http_kwargs["auth"] = _oauth_auth
-        async with streamablehttp_client(url, **_http_kwargs) as (
-            read_stream, write_stream, _get_session_id,
-        ):
-            async with ClientSession(read_stream, write_stream, **sampling_kwargs) as session:
-                await session.initialize()
-                self.session = session
-                await self._discover_tools()
-                self._ready.set()
-                await self._shutdown_event.wait()
+
+        if _MCP_NEW_HTTP:
+            # New API (mcp >= 1.24.0): build an explicit httpx.AsyncClient
+            # matching the SDK's own create_mcp_http_client defaults.
+            import httpx
+
+            client_kwargs: dict = {
+                "follow_redirects": True,
+                "timeout": httpx.Timeout(float(connect_timeout), read=300.0),
+            }
+            if headers:
+                client_kwargs["headers"] = headers
+            if _oauth_auth is not None:
+                client_kwargs["auth"] = _oauth_auth
+
+            # Caller owns the client lifecycle — the SDK skips cleanup when
+            # http_client is provided, so we wrap in async-with.
+            async with httpx.AsyncClient(**client_kwargs) as http_client:
+                async with streamable_http_client(url, http_client=http_client) as (
+                    read_stream, write_stream, _get_session_id,
+                ):
+                    async with ClientSession(read_stream, write_stream, **sampling_kwargs) as session:
+                        await session.initialize()
+                        self.session = session
+                        await self._discover_tools()
+                        self._ready.set()
+                        await self._shutdown_event.wait()
+        else:
+            # Deprecated API (mcp < 1.24.0): manages httpx client internally.
+            _http_kwargs: dict = {
+                "headers": headers,
+                "timeout": float(connect_timeout),
+            }
+            if _oauth_auth is not None:
+                _http_kwargs["auth"] = _oauth_auth
+            async with streamablehttp_client(url, **_http_kwargs) as (
+                read_stream, write_stream, _get_session_id,
+            ):
+                async with ClientSession(read_stream, write_stream, **sampling_kwargs) as session:
+                    await session.initialize()
+                    self.session = session
+                    await self._discover_tools()
+                    self._ready.set()
+                    await self._shutdown_event.wait()
 
     async def _discover_tools(self):
         """Discover tools from the connected session."""

tools/memory_tool.py

@@ -339,7 +339,7 @@ class MemoryStore:
         entries = self._entries_for(target)
         current = self._char_count(target)
         limit = self._char_limit(target)
-        pct = int((current / limit) * 100) if limit > 0 else 0
+        pct = min(100, int((current / limit) * 100)) if limit > 0 else 0
 
         resp = {
             "success": True,
@@ -360,7 +360,7 @@ class MemoryStore:
         limit = self._char_limit(target)
         content = ENTRY_DELIMITER.join(entries)
         current = len(content)
-        pct = int((current / limit) * 100) if limit > 0 else 0
+        pct = min(100, int((current / limit) * 100)) if limit > 0 else 0
 
         if target == "user":
             header = f"USER PROFILE (who the user is) [{pct}% — {current:,}/{limit:,} chars]"

tools/skills_hub.py

@@ -251,6 +251,7 @@ class GitHubSource(SkillSource):
         {"repo": "openai/skills", "path": "skills/"},
         {"repo": "anthropics/skills", "path": "skills/"},
         {"repo": "VoltAgent/awesome-agent-skills", "path": "skills/"},
+        {"repo": "garrytan/gstack", "path": ""},
     ]
 
     def __init__(self, auth: GitHubAuth, extra_taps: Optional[List[Dict]] = None):
@@ -395,7 +396,8 @@ class GitHubSource(SkillSource):
             if dir_name.startswith(".") or dir_name.startswith("_"):
                 continue
 
-            skill_identifier = f"{repo}/{path.rstrip('/')}/{dir_name}"
+            prefix = path.rstrip("/")
+            skill_identifier = f"{repo}/{prefix}/{dir_name}" if prefix else f"{repo}/{dir_name}"
             meta = self.inspect(skill_identifier)
             if meta:
                 skills.append(meta)

tools/skills_tool.py

@@ -355,13 +355,8 @@ def _remaining_required_environment_names(
     capture_result: Dict[str, Any],
     *,
     env_snapshot: Dict[str, str] | None = None,
-    backend: str | None = None,
 ) -> List[str]:
-    if backend is None:
-        backend = _get_terminal_backend_name()
     missing_names = set(capture_result["missing_names"])
-    if backend in _REMOTE_ENV_BACKENDS:
-        return [entry["name"] for entry in required_env_vars]
 
     if env_snapshot is None:
         env_snapshot = load_env()
@@ -1076,8 +1071,7 @@ def skill_view(name: str, file_path: str = None, task_id: str = None) -> str:
         missing_required_env_vars = [
             e
             for e in required_env_vars
-            if backend in _REMOTE_ENV_BACKENDS
-            or not _is_env_var_persisted(e["name"], env_snapshot)
+            if not _is_env_var_persisted(e["name"], env_snapshot)
         ]
         capture_result = _capture_required_environment_variables(
             skill_name,
@@ -1089,7 +1083,6 @@ def skill_view(name: str, file_path: str = None, task_id: str = None) -> str:
             required_env_vars,
             capture_result,
             env_snapshot=env_snapshot,
-            backend=backend,
         )
         setup_needed = bool(remaining_missing_required_envs)
 

tools/tts_tool.py

@@ -74,7 +74,11 @@ DEFAULT_ELEVENLABS_MODEL_ID = "eleven_multilingual_v2"
 DEFAULT_ELEVENLABS_STREAMING_MODEL_ID = "eleven_flash_v2_5"
 DEFAULT_OPENAI_MODEL = "gpt-4o-mini-tts"
 DEFAULT_OPENAI_VOICE = "alloy"
-DEFAULT_OUTPUT_DIR = str(get_hermes_home() / "audio_cache")
+def _get_default_output_dir() -> str:
+    from hermes_constants import get_hermes_dir
+    return str(get_hermes_dir("cache/audio", "audio_cache"))
+
+DEFAULT_OUTPUT_DIR = _get_default_output_dir()
 MAX_TEXT_LENGTH = 4000
 
 
@@ -828,7 +832,7 @@ TTS_SCHEMA = {
             },
             "output_path": {
                 "type": "string",
-                "description": "Optional custom file path to save the audio. Defaults to ~/.hermes/audio_cache/<timestamp>.mp3"
+                "description": "Optional custom file path to save the audio. Defaults to ~/.hermes/cache/audio/<timestamp>.mp3"
             }
         },
         "required": ["text"]

tools/web_tools.py

@@ -74,14 +74,16 @@ def _get_backend() -> str:
     keys manually without running setup.
     """
     configured = (_load_web_config().get("backend") or "").lower().strip()
-    if configured in ("parallel", "firecrawl", "tavily"):
+    if configured in ("parallel", "firecrawl", "tavily", "exa"):
         return configured
 
     # Fallback for manual / legacy config — use whichever key is present.
     has_firecrawl = _has_env("FIRECRAWL_API_KEY") or _has_env("FIRECRAWL_API_URL")
     has_parallel = _has_env("PARALLEL_API_KEY")
     has_tavily = _has_env("TAVILY_API_KEY")
-
+    has_exa = _has_env("EXA_API_KEY")
+    if has_exa and not has_firecrawl and not has_parallel and not has_tavily:
+        return "exa"
     if has_tavily and not has_firecrawl and not has_parallel:
         return "tavily"
     if has_parallel and not has_firecrawl:
@@ -605,6 +607,91 @@ def clean_base64_images(text: str) -> str:
     return cleaned_text
 
 
+# ─── Exa Client ──────────────────────────────────────────────────────────────
+
+_exa_client = None
+
+def _get_exa_client():
+    """Get or create the Exa client (lazy initialization).
+
+    Requires EXA_API_KEY environment variable.
+    """
+    from exa_py import Exa
+    global _exa_client
+    if _exa_client is None:
+        api_key = os.getenv("EXA_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "EXA_API_KEY environment variable not set. "
+                "Get your API key at https://exa.ai"
+            )
+        _exa_client = Exa(api_key=api_key)
+        _exa_client.headers["x-exa-integration"] = "hermes-agent"
+    return _exa_client
+
+
+# ─── Exa Search & Extract Helpers ─────────────────────────────────────────────
+
+def _exa_search(query: str, limit: int = 10) -> dict:
+    """Search using the Exa SDK and return results as a dict."""
+    from tools.interrupt import is_interrupted
+    if is_interrupted():
+        return {"error": "Interrupted", "success": False}
+
+    logger.info("Exa search: '%s' (limit=%d)", query, limit)
+    response = _get_exa_client().search(
+        query,
+        num_results=limit,
+        contents={
+            "highlights": True,
+        },
+    )
+
+    web_results = []
+    for i, result in enumerate(response.results or []):
+        highlights = result.highlights or []
+        web_results.append({
+            "url": result.url or "",
+            "title": result.title or "",
+            "description": " ".join(highlights) if highlights else "",
+            "position": i + 1,
+        })
+
+    return {"success": True, "data": {"web": web_results}}
+
+
+def _exa_extract(urls: List[str]) -> List[Dict[str, Any]]:
+    """Extract content from URLs using the Exa SDK.
+
+    Returns a list of result dicts matching the structure expected by the
+    LLM post-processing pipeline (url, title, content, metadata).
+    """
+    from tools.interrupt import is_interrupted
+    if is_interrupted():
+        return [{"url": u, "error": "Interrupted", "title": ""} for u in urls]
+
+    logger.info("Exa extract: %d URL(s)", len(urls))
+    response = _get_exa_client().get_contents(
+        urls,
+        text=True,
+    )
+
+    results = []
+    for result in response.results or []:
+        content = result.text or ""
+        url = result.url or ""
+        title = result.title or ""
+        results.append({
+            "url": url,
+            "title": title,
+            "content": content,
+            "raw_content": content,
+            "metadata": {"sourceURL": url, "title": title},
+        })
+
+    return results
+
+
 # ─── Parallel Search & Extract Helpers ────────────────────────────────────────
 
 def _parallel_search(query: str, limit: int = 5) -> dict:
@@ -742,6 +829,15 @@ def web_search_tool(query: str, limit: int = 5) -> str:
             _debug.save()
             return result_json
 
+        if backend == "exa":
+            response_data = _exa_search(query, limit)
+            debug_call_data["results_count"] = len(response_data.get("data", {}).get("web", []))
+            result_json = json.dumps(response_data, indent=2, ensure_ascii=False)
+            debug_call_data["final_response_size"] = len(result_json)
+            _debug.log_call("web_search_tool", debug_call_data)
+            _debug.save()
+            return result_json
+
         if backend == "tavily":
             logger.info("Tavily search: '%s' (limit: %d)", query, limit)
             raw = _tavily_request("search", {
@@ -897,6 +993,8 @@ async def web_extract_tool(
 
             if backend == "parallel":
                 results = await _parallel_extract(safe_urls)
+            elif backend == "exa":
+                results = _exa_extract(safe_urls)
             elif backend == "tavily":
                 logger.info("Tavily extract: %d URL(s)", len(safe_urls))
                 raw = _tavily_request("extract", {
@@ -1567,9 +1665,10 @@ def check_firecrawl_api_key() -> bool:
 
 
 def check_web_api_key() -> bool:
-    """Check if any web backend API key is available (Parallel, Firecrawl, or Tavily)."""
+    """Check if any web backend API key is available (Exa, Parallel, Firecrawl, or Tavily)."""
     return bool(
-        os.getenv("PARALLEL_API_KEY")
+        os.getenv("EXA_API_KEY")
+        or os.getenv("PARALLEL_API_KEY")
         or os.getenv("FIRECRAWL_API_KEY")
         or os.getenv("FIRECRAWL_API_URL")
         or os.getenv("TAVILY_API_KEY")
@@ -1608,7 +1707,9 @@ if __name__ == "__main__":
     if web_available:
         backend = _get_backend()
         print(f"✅ Web backend: {backend}")
-        if backend == "parallel":
+        if backend == "exa":
+            print("   Using Exa API (https://exa.ai)")
+        elif backend == "parallel":
             print("   Using Parallel API (https://parallel.ai)")
         elif backend == "tavily":
             print("   Using Tavily API (https://tavily.com)")
@@ -1616,7 +1717,7 @@ if __name__ == "__main__":
             print("   Using Firecrawl API (https://firecrawl.dev)")
     else:
         print("❌ No web search backend configured")
-        print("Set PARALLEL_API_KEY, TAVILY_API_KEY, or FIRECRAWL_API_KEY")
+        print("Set EXA_API_KEY, PARALLEL_API_KEY, TAVILY_API_KEY, or FIRECRAWL_API_KEY")
 
     if not nous_available:
         print("❌ No auxiliary model available for LLM content processing")
@@ -1726,7 +1827,7 @@ registry.register(
     schema=WEB_SEARCH_SCHEMA,
     handler=lambda args, **kw: web_search_tool(args.get("query", ""), limit=5),
     check_fn=check_web_api_key,
-    requires_env=["PARALLEL_API_KEY", "FIRECRAWL_API_KEY", "TAVILY_API_KEY"],
+    requires_env=["EXA_API_KEY", "PARALLEL_API_KEY", "FIRECRAWL_API_KEY", "TAVILY_API_KEY"],
     emoji="🔍",
 )
 registry.register(
@@ -1736,7 +1837,7 @@ registry.register(
     handler=lambda args, **kw: web_extract_tool(
         args.get("urls", [])[:5] if isinstance(args.get("urls"), list) else [], "markdown"),
     check_fn=check_web_api_key,
-    requires_env=["PARALLEL_API_KEY", "FIRECRAWL_API_KEY", "TAVILY_API_KEY"],
+    requires_env=["EXA_API_KEY", "PARALLEL_API_KEY", "FIRECRAWL_API_KEY", "TAVILY_API_KEY"],
     is_async=True,
     emoji="📄",
 )

website/docs/reference/cli-commands.md

@@ -39,6 +39,7 @@ hermes [global-options] <command> [subcommand/options]
 | `hermes login` / `logout` | Authenticate with OAuth-backed providers. |
 | `hermes status` | Show agent, auth, and platform status. |
 | `hermes cron` | Inspect and tick the cron scheduler. |
+| `hermes webhook` | Manage dynamic webhook subscriptions for event-driven activation. |
 | `hermes doctor` | Diagnose config and dependency issues. |
 | `hermes config` | Show, edit, migrate, and query configuration files. |
 | `hermes pairing` | Approve or revoke messaging pairing codes. |
@@ -66,7 +67,7 @@ Common options:
 | `-q`, `--query "..."` | One-shot, non-interactive prompt. |
 | `-m`, `--model <model>` | Override the model for this run. |
 | `-t`, `--toolsets <csv>` | Enable a comma-separated set of toolsets. |
-| `--provider <provider>` | Force a provider: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `huggingface`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `kilocode`. |
+| `--provider <provider>` | Force a provider: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `huggingface`, `alibaba`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `kilocode`. |
 | `-s`, `--skills <name>` | Preload one or more skills for the session (can be repeated or comma-separated). |
 | `-v`, `--verbose` | Verbose output. |
 | `-Q`, `--quiet` | Programmatic mode: suppress banner/spinner/tool previews. |
@@ -214,6 +215,39 @@ hermes cron <list|create|edit|pause|resume|run|remove|status|tick>
 | `status` | Check whether the cron scheduler is running. |
 | `tick` | Run due jobs once and exit. |
 
+## `hermes webhook`
+
+```bash
+hermes webhook <subscribe|list|remove|test>
+```
+
+Manage dynamic webhook subscriptions for event-driven agent activation. Requires the webhook platform to be enabled in config — if not configured, prints setup instructions.
+
+| Subcommand | Description |
+|------------|-------------|
+| `subscribe` / `add` | Create a webhook route. Returns the URL and HMAC secret to configure on your service. |
+| `list` / `ls` | Show all agent-created subscriptions. |
+| `remove` / `rm` | Delete a dynamic subscription. Static routes from config.yaml are not affected. |
+| `test` | Send a test POST to verify a subscription is working. |
+
+### `hermes webhook subscribe`
+
+```bash
+hermes webhook subscribe <name> [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--prompt` | Prompt template with `{dot.notation}` payload references. |
+| `--events` | Comma-separated event types to accept (e.g. `issues,pull_request`). Empty = all. |
+| `--description` | Human-readable description. |
+| `--skills` | Comma-separated skill names to load for the agent run. |
+| `--deliver` | Delivery target: `log` (default), `telegram`, `discord`, `slack`, `github_comment`. |
+| `--deliver-chat-id` | Target chat/channel ID for cross-platform delivery. |
+| `--secret` | Custom HMAC secret. Auto-generated if omitted. |
+
+Subscriptions persist to `~/.hermes/webhook_subscriptions.json` and are hot-reloaded by the webhook adapter without a gateway restart.
+
 ## `hermes doctor`
 
 ```bash

website/docs/reference/environment-variables.md

@@ -42,7 +42,7 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config
 | `ANTHROPIC_API_KEY` | Anthropic Console API key ([console.anthropic.com](https://console.anthropic.com/)) |
 | `ANTHROPIC_TOKEN` | Manual or legacy Anthropic OAuth/setup-token override |
 | `DASHSCOPE_API_KEY` | Alibaba Cloud DashScope API key for Qwen models ([modelstudio.console.alibabacloud.com](https://modelstudio.console.alibabacloud.com/)) |
-| `DASHSCOPE_BASE_URL` | Custom DashScope base URL (default: international endpoint) |
+| `DASHSCOPE_BASE_URL` | Custom DashScope base URL (default: `https://coding-intl.dashscope.aliyuncs.com/v1`) |
 | `DEEPSEEK_API_KEY` | DeepSeek API key for direct DeepSeek access ([platform.deepseek.com](https://platform.deepseek.com/api_keys)) |
 | `DEEPSEEK_BASE_URL` | Custom DeepSeek API base URL |
 | `OPENCODE_ZEN_API_KEY` | OpenCode Zen API key — pay-as-you-go access to curated models ([opencode.ai](https://opencode.ai/auth)) |

website/docs/reference/skills-catalog.md

@@ -48,6 +48,14 @@ Creative content generation — ASCII art, hand-drawn style diagrams, and visual
 | `ascii-video` | "Production pipeline for ASCII art video — any format. Converts video/audio/images/generative input into colored ASCII character video output (MP4, GIF, image sequence). Covers: video-to-ASCII conversion, audio-reactive music visualizers, generative ASCII art animations, hybrid… | `creative/ascii-video` |
 | `excalidraw` | Create hand-drawn style diagrams using Excalidraw JSON format. Generate .excalidraw files for architecture diagrams, flowcharts, sequence diagrams, concept maps, and more. Files can be opened at excalidraw.com or uploaded for shareable links. | `creative/excalidraw` |
 
+## devops
+
+DevOps and infrastructure automation skills.
+
+| Skill | Description | Path |
+|-------|-------------|------|
+| `webhook-subscriptions` | Create and manage webhook subscriptions for event-driven agent activation. External services (GitHub, Stripe, CI/CD, IoT) POST events to trigger agent runs. Requires webhook platform to be enabled. | `devops/webhook-subscriptions` |
+
 ## dogfood
 
 | Skill | Description | Path |

website/docs/reference/toolsets-reference.md

@@ -19,10 +19,14 @@ Toolsets are named bundles of tools that you can enable with `hermes chat --tool
 | `file` | core | `patch`, `read_file`, `search_files`, `write_file` |
 | `hermes-acp` | platform | `browser_back`, `browser_click`, `browser_close`, `browser_console`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `delegate_task`, `execute_code`, `memory`, `patch`, `process`, `read_file`, `search_files`, `session_search`, `skill_manage`, `skill_view`, `skills_list`, `terminal`, `todo`, `vision_analyze`, `web_extract`, `web_search`, `write_file` |
 | `hermes-cli` | platform | `browser_back`, `browser_click`, `browser_close`, `browser_console`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `clarify`, `cronjob`, `delegate_task`, `execute_code`, `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services`, `honcho_conclude`, `honcho_context`, `honcho_profile`, `honcho_search`, `image_generate`, `memory`, `mixture_of_agents`, `patch`, `process`, `read_file`, `search_files`, `send_message`, `session_search`, `skill_manage`, `skill_view`, `skills_list`, `terminal`, `text_to_speech`, `todo`, `vision_analyze`, `web_extract`, `web_search`, `write_file` |
+| `hermes-api-server` | platform | _(same as hermes-cli)_ |
+| `hermes-dingtalk` | platform | _(same as hermes-cli)_ |
 | `hermes-discord` | platform | _(same as hermes-cli)_ |
 | `hermes-email` | platform | _(same as hermes-cli)_ |
 | `hermes-gateway` | composite | Union of all messaging platform toolsets |
 | `hermes-homeassistant` | platform | _(same as hermes-cli)_ |
+| `hermes-matrix` | platform | _(same as hermes-cli)_ |
+| `hermes-mattermost` | platform | _(same as hermes-cli)_ |
 | `hermes-signal` | platform | _(same as hermes-cli)_ |
 | `hermes-slack` | platform | _(same as hermes-cli)_ |
 | `hermes-sms` | platform | _(same as hermes-cli)_ |

website/docs/user-guide/configuration.md

@@ -95,6 +95,10 @@ You need at least one way to connect to an LLM. Use `hermes model` to switch pro
 | **Hugging Face** | `HF_TOKEN` in `~/.hermes/.env` (provider: `huggingface`, aliases: `hf`) |
 | **Custom Endpoint** | `hermes model` (saved in `config.yaml`) or `OPENAI_BASE_URL` + `OPENAI_API_KEY` in `~/.hermes/.env` |
 
+:::tip Model key alias
+In the `model:` config section, you can use either `default:` or `model:` as the key name for your model ID. Both `model: { default: my-model }` and `model: { model: my-model }` work identically.
+:::
+
 :::info Codex Note
 The OpenAI Codex provider authenticates via device code (open a URL, enter a code). Hermes stores the resulting credentials in its own auth store under `~/.hermes/auth.json` and can import existing Codex CLI credentials from `~/.codex/auth.json` when present. No Codex CLI installation is required.
 :::
@@ -212,7 +216,7 @@ hermes chat --provider minimax-cn --model MiniMax-M2.7
 # Requires: MINIMAX_CN_API_KEY in ~/.hermes/.env
 
 # Alibaba Cloud / DashScope (Qwen models)
-hermes chat --provider alibaba --model qwen-plus
+hermes chat --provider alibaba --model qwen3.5-plus
 # Requires: DASHSCOPE_API_KEY in ~/.hermes/.env
 ```
 
@@ -1022,6 +1026,7 @@ auxiliary:
     model: ""                  # e.g. "google/gemini-2.5-flash"
     base_url: ""
     api_key: ""
+    timeout: 30                # seconds
 
   # Dangerous command approval classifier
   approval:
@@ -1029,8 +1034,17 @@ auxiliary:
     model: ""
     base_url: ""
     api_key: ""
+    timeout: 30                # seconds
+
+  # Context compression timeout (separate from compression.* config)
+  compression:
+    timeout: 120               # seconds — compression summarizes long conversations, needs more time
 ```
 
+:::tip
+Each auxiliary task has a configurable `timeout` (in seconds). Defaults: vision 30s, web_extract 30s, approval 30s, compression 120s. Increase these if you use slow local models for auxiliary tasks.
+:::
+
 :::info
 Context compression has its own top-level `compression:` block with `summary_provider`, `summary_model`, and `summary_base_url` — see [Context Compression](#context-compression) above. The fallback model uses a `fallback_model:` block — see [Fallback Model](#fallback-model) above. All three follow the same provider/model/base_url pattern.
 :::
@@ -1162,6 +1176,24 @@ You can also change the reasoning effort at runtime with the `/reasoning` comman
 /reasoning hide      # Hide model thinking
 ```
 
+## Tool-Use Enforcement
+
+Some models (especially GPT-family) occasionally describe intended actions as text instead of making tool calls. Tool-use enforcement injects guidance that steers the model back to actually calling tools.
+
+```yaml
+agent:
+  tool_use_enforcement: "auto"   # "auto" | true | false | ["model-substring", ...]
+```
+
+| Value | Behavior |
+|-------|----------|
+| `"auto"` (default) | Enabled for GPT models (`gpt-`, `openai/gpt-`) and disabled for all others. |
+| `true` | Always enabled for all models. |
+| `false` | Always disabled. |
+| `["gpt-", "o1-", "custom-model"]` | Enabled only for models whose name contains one of the listed substrings. |
+
+When enabled, the system prompt includes guidance reminding the model to make actual tool calls rather than describing what it would do. This is transparent to the user and has no effect on models that already use tools reliably.
+
 ## TTS Configuration
 
 ```yaml

website/docs/user-guide/features/api-server.md

@@ -154,7 +154,7 @@ Lists `hermes-agent` as an available model. Required by most frontends for model
 
 ### GET /health
 
-Health check. Returns `{"status": "ok"}`.
+Health check. Returns `{"status": "ok"}`. Also available at **GET /v1/health** for OpenAI-compatible clients that expect the `/v1/` prefix.
 
 ## System Prompt Handling
 
@@ -199,6 +199,12 @@ The default bind address (`127.0.0.1`) is for local-only use. Browser access is
 # config.yaml support coming in a future release.
 ```
 
+## Security Headers
+
+All responses include security headers:
+- `X-Content-Type-Options: nosniff` — prevents MIME type sniffing
+- `Referrer-Policy: no-referrer` — prevents referrer leakage
+
 ## CORS
 
 The API server does **not** enable browser CORS by default.
@@ -209,6 +215,11 @@ For direct browser access, set an explicit allowlist:
 API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
 ```
 
+When CORS is enabled:
+- **Preflight responses** include `Access-Control-Max-Age: 600` (10 minute cache)
+- **SSE streaming responses** include CORS headers so browser EventSource clients work correctly
+- **`Idempotency-Key`** is an allowed request header — clients can send it for deduplication (responses are cached by key for 5 minutes)
+
 Most documented frontends such as Open WebUI connect server-to-server and do not need CORS at all.
 
 ## Compatible Frontends

website/docs/user-guide/features/fallback-providers.md

@@ -44,6 +44,7 @@ Both `provider` and `model` are **required**. If either is missing, the fallback
 | MiniMax | `minimax` | `MINIMAX_API_KEY` |
 | MiniMax (China) | `minimax-cn` | `MINIMAX_CN_API_KEY` |
 | Kilo Code | `kilocode` | `KILOCODE_API_KEY` |
+| Alibaba / DashScope | `alibaba` | `DASHSCOPE_API_KEY` |
 | Hugging Face | `huggingface` | `HF_TOKEN` |
 | Custom endpoint | `custom` | `base_url` + `api_key_env` (see below) |
 

website/docs/user-guide/features/hooks.md

@@ -209,10 +209,10 @@ def register(ctx):
 |------|-----------|-------------------|
 | `pre_tool_call` | Before any tool executes | `tool_name`, `args`, `task_id` |
 | `post_tool_call` | After any tool returns | `tool_name`, `args`, `result`, `task_id` |
-| `pre_llm_call` | Before LLM API request | *(planned — not yet wired)* |
-| `post_llm_call` | After LLM API response | *(planned — not yet wired)* |
-| `on_session_start` | Session begins | *(planned — not yet wired)* |
-| `on_session_end` | Session ends | *(planned — not yet wired)* |
+| `pre_llm_call` | Before LLM API request | `session_id`, `user_message`, `conversation_history`, `is_first_turn`, `model`, `platform` |
+| `post_llm_call` | After LLM API response | `session_id`, `user_message`, `assistant_response`, `conversation_history`, `model`, `platform` |
+| `on_session_start` | Session begins | `session_id`, `model`, `platform` |
+| `on_session_end` | Session ends | `session_id`, `completed`, `interrupted`, `model`, `platform` |
 
 Callbacks receive keyword arguments matching the columns above:
 

website/docs/user-guide/features/skills.md

@@ -277,9 +277,12 @@ hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mi
 
 Hermes can install directly from GitHub repositories and GitHub-based taps. This is useful when you already know the repo/path or want to add your own custom source repo.
 
-- OpenAI skills: [openai/skills](https://github.com/openai/skills)
-- Anthropic skills: [anthropics/skills](https://github.com/anthropics/skills)
-- Example community tap source: [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)
+Default taps (browsable without any setup):
+- [openai/skills](https://github.com/openai/skills)
+- [anthropics/skills](https://github.com/anthropics/skills)
+- [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)
+- [garrytan/gstack](https://github.com/garrytan/gstack)
+
 - Example:
 
 ```bash

website/docs/user-guide/messaging/email.md

@@ -104,6 +104,7 @@ The adapter polls the IMAP inbox for UNSEEN messages at a configurable interval
   - Documents (PDF, ZIP, etc.) → available for file access
 - **HTML-only emails** have tags stripped for plain text extraction
 - **Self-messages** are filtered out to prevent reply loops
+- **Automated/noreply senders** are silently ignored — `noreply@`, `mailer-daemon@`, `bounce@`, `no-reply@`, and emails with `Auto-Submitted`, `Precedence: bulk`, or `List-Unsubscribe` headers
 
 ### Sending Replies
 

website/docs/user-guide/messaging/webhooks.md

@@ -15,7 +15,7 @@ The agent processes the event and can respond by posting comments on PRs, sendin
 ## Quick Start
 
 1. Enable via `hermes gateway setup` or environment variables
-2. Define webhook routes in `config.yaml`
+2. Define routes in `config.yaml` **or** create them dynamically with `hermes webhook subscribe`
 3. Point your service at `http://your-server:8644/webhooks/<route-name>`
 
 ---
@@ -205,6 +205,56 @@ For cross-platform delivery (telegram, discord, slack, signal, sms), the target
 
 ---
 
+## Dynamic Subscriptions (CLI) {#dynamic-subscriptions}
+
+In addition to static routes in `config.yaml`, you can create webhook subscriptions dynamically using the `hermes webhook` CLI command. This is especially useful when the agent itself needs to set up event-driven triggers.
+
+### Create a subscription
+
+```bash
+hermes webhook subscribe github-issues \
+  --events "issues" \
+  --prompt "New issue #{issue.number}: {issue.title}\nBy: {issue.user.login}\n\n{issue.body}" \
+  --deliver telegram \
+  --deliver-chat-id "-100123456789" \
+  --description "Triage new GitHub issues"
+```
+
+This returns the webhook URL and an auto-generated HMAC secret. Configure your service to POST to that URL.
+
+### List subscriptions
+
+```bash
+hermes webhook list
+```
+
+### Remove a subscription
+
+```bash
+hermes webhook remove github-issues
+```
+
+### Test a subscription
+
+```bash
+hermes webhook test github-issues
+hermes webhook test github-issues --payload '{"issue": {"number": 42, "title": "Test"}}'
+```
+
+### How dynamic subscriptions work
+
+- Subscriptions are stored in `~/.hermes/webhook_subscriptions.json`
+- The webhook adapter hot-reloads this file on each incoming request (mtime-gated, negligible overhead)
+- Static routes from `config.yaml` always take precedence over dynamic ones with the same name
+- Dynamic subscriptions use the same route format and capabilities as static routes (events, prompt templates, skills, delivery)
+- No gateway restart required — subscribe and it's immediately live
+
+### Agent-driven subscriptions
+
+The agent can create subscriptions via the terminal tool when guided by the `webhook-subscriptions` skill. Ask the agent to "set up a webhook for GitHub issues" and it will run the appropriate `hermes webhook subscribe` command.
+
+---
+
 ## Security {#security}
 
 The webhook adapter includes multiple layers of security:

website/docs/user-guide/security.md

@@ -43,6 +43,8 @@ The following patterns trigger approval prompts (defined in `tools/approval.py`)
 | `bash -c`, `python -e` | Shell/script execution via flags |
 | `find -exec rm`, `find -delete` | Find with destructive actions |
 | Fork bomb patterns | Fork bombs |
+| `pkill`/`killall` hermes/gateway | Self-termination prevention |
+| `gateway run` with `&`/`disown`/`nohup` | Prevents starting gateway outside service manager |
 
 :::info
 **Container bypass**: When running in `docker`, `singularity`, `modal`, or `daytona` backends, dangerous command checks are **skipped** because the container itself is the security boundary. Destructive commands inside a container can't harm the host.
@@ -392,7 +394,7 @@ security:
 
 When `tirith_fail_open` is `true` (default), commands proceed if tirith is not installed or times out. Set to `false` in high-security environments to block commands when tirith is unavailable.
 
-Tirith's verdict integrates with the approval flow: safe commands pass through, suspicious commands trigger user approval, and dangerous commands are blocked.
+Tirith's verdict integrates with the approval flow: safe commands pass through, while both suspicious and blocked commands trigger user approval with the full tirith findings (severity, title, description, safer alternatives). Users can approve or deny — the default choice is deny to keep unattended scenarios secure.
 
 ### Context File Injection Protection