feat: add Anthropic transport abstraction slice (#951)

- add transport registry, shared transport dataclasses, and AnthropicTransport
- add normalize_anthropic_response_v2 as the bridge from existing Anthropic normalization to shared transport types
- extend Anthropic stop-reason mapping for refusal and model_context_window_exceeded
- add targeted transport and v2 normalization regression tests

Closes #951
Refs #949

.claw/sessions/session-1775533542734-0.jsonl

@@ -1,2 +0,0 @@
-{"created_at_ms":1775533542734,"session_id":"session-1775533542734-0","type":"session_meta","updated_at_ms":1775533542734,"version":1}
-{"message":{"blocks":[{"text":"You are Code Claw running as the Gitea user claw-code.\n\nRepository: Timmy_Foundation/hermes-agent\nIssue: #126 — P2: Validate Documentation Audit & Apply to Our Fork\nBranch: claw-code/issue-126\n\nRead the issue and recent comments, then implement the smallest correct change.\nYou are in a git repo checkout already.\n\nIssue body:\n## Context\n\nCommit `43d468ce` is a comprehensive documentation audit — fixes stale info, expands thin pages, adds depth across all docs.\n\n## Acceptance Criteria\n\n- [ ] **Catalog all doc changes**: Run `git show 43d468ce --stat` to list all files changed, then review each for what was fixed/expanded\n- [ ] **Verify key docs are accurate**: Pick 3 docs that were previously thin (setup, deployment, plugin development), confirm they now have comprehensive content\n- [ ] **Identify stale info that was corrected**: Note at least 3 pieces of stale information that were removed or updated\n- [ ] **Apply fixes to our fork if needed**: Check if any of the doc fixes apply to our `Timmy_Foundation/hermes-agent` fork (Timmy-specific references, custom config sections)\n\n## Why This Matters\n\nAccurate documentation is critical for onboarding new agents and maintaining the fleet. Stale docs cost more debugging time than writing them initially.\n\n## Hints\n\n- Run `cd ~/.hermes/hermes-agent && git show 43d468ce --stat` to see the full scope\n- The docs likely cover: setup, plugins, deployment, MCP configuration, and tool integrations\n\n\nParent: #111\n\nRecent comments:\n## 🏷️ Automated Triage Check\n\n**Timestamp:** 2026-04-06T15:30:12.449023  \n**Agent:** Allegro Heartbeat\n\nThis issue has been identified as needing triage:\n\n### Checklist\n- [ ] Clear acceptance criteria defined\n- [ ] Priority label assigned (p0-critical / p1-important / p2-backlog)\n- [ ] Size estimate added (quick-fix / day / week / epic)\n- [ ] Owner assigned\n- [ ] Related issues linked\n\n### Context\n- No comments yet — needs engagement\n- No labels — needs categorization\n- Part of automated backlog maintenance\n\n---\n*Automated triage from Allegro 15-minute heartbeat*\n\n[BURN-DOWN] Dispatched to Code Claw (claw-code worker) as part of nightly burn-down cycle. Heartbeat active.\n\n🟠 Code Claw (OpenRouter qwen/qwen3.6-plus:free) picking up this issue via 15-minute heartbeat.\n\nTimestamp: 2026-04-07T03:45:37Z\n\nRules:\n- Make focused code/config/doc changes only if they directly address the issue.\n- Prefer the smallest proof-oriented fix.\n- Run relevant verification commands if obvious.\n- Do NOT create PRs yourself; the outer worker handles commit/push/PR.\n- If the task is too large or not code-fit, leave the tree unchanged.\n","type":"text"}],"role":"user"},"type":"message"}

.claw/sessions/session-1775534636684-0.jsonl

@@ -1,2 +0,0 @@
-{"created_at_ms":1775534636684,"session_id":"session-1775534636684-0","type":"session_meta","updated_at_ms":1775534636684,"version":1}
-{"message":{"blocks":[{"text":"You are Code Claw running as the Gitea user claw-code.\n\nRepository: Timmy_Foundation/hermes-agent\nIssue: #151 — [CONFIG] Add Kimi model to fallback chain for Allegro and Bezalel\nBranch: claw-code/issue-151\n\nRead the issue and recent comments, then implement the smallest correct change.\nYou are in a git repo checkout already.\n\nIssue body:\n## Problem\nAllegro and Bezalel are choking because the Kimi model code is not on their fallback chain. When primary models fail or rate-limit, Kimi should be available as a fallback option but is currently missing.\n\n## Expected Behavior\nKimi model code should be at the front of the fallback chain for both Allegro and Bezalel, so they can remain responsive when primary models are unavailable.\n\n## Context\nThis was reported in Telegram by Alexander Whitestone after observing both agents becoming unresponsive. Ezra was asked to investigate the fallback chain configuration.\n\n## Related\n- timmy-config #302: [ARCH] Fallback Portfolio Runtime Wiring (general fallback framework)\n- hermes-agent #150: [BEZALEL][AUDIT] Telegram Request-to-Gitea Tracking Audit\n\n## Acceptance Criteria\n- [ ] Kimi model code is added to Allegro fallback chain\n- [ ] Kimi model code is added to Bezalel fallback chain\n- [ ] Fallback ordering places Kimi appropriately (front of chain as requested)\n- [ ] Test and confirm both agents can successfully fall back to Kimi\n- [ ] Document the fallback chain configuration for both agents\n\n/assign @ezra\n\nRecent comments:\n[BURN-DOWN] Dispatched to Code Claw (claw-code worker) as part of nightly burn-down cycle. Heartbeat active.\n\n🟠 Code Claw (OpenRouter qwen/qwen3.6-plus:free) picking up this issue via 15-minute heartbeat.\n\nTimestamp: 2026-04-07T04:03:49Z\n\nRules:\n- Make focused code/config/doc changes only if they directly address the issue.\n- Prefer the smallest proof-oriented fix.\n- Run relevant verification commands if obvious.\n- Do NOT create PRs yourself; the outer worker handles commit/push/PR.\n- If the task is too large or not code-fit, leave the tree unchanged.\n","type":"text"}],"role":"user"},"type":"message"}

.coveragerc

@@ -1,51 +0,0 @@
-# Coverage configuration for hermes-agent
-# Run with: pytest --cov=agent --cov=tools --cov=gateway --cov=hermes_cli tests/
-
-[run]
-source = 
-    agent
-    tools
-    gateway
-    hermes_cli
-    acp_adapter
-    cron
-    honcho_integration
-
-omit = 
-    */tests/*
-    */test_*
-    */__pycache__/*
-    */venv/*
-    */.venv/*
-    setup.py
-    conftest.py
-
-branch = True
-
-[report]
-exclude_lines =
-    pragma: no cover
-    def __repr__
-    raise AssertionError
-    raise NotImplementedError
-    if __name__ == .__main__.:
-    if TYPE_CHECKING:
-    class .*\bProtocol\):
-    @(abc\.)?abstractmethod
-
-ignore_errors = True
-
-precision = 2
-
-fail_under = 70
-
-show_missing = True
-skip_covered = False
-
-[html]
-directory = coverage_html
-
-title = Hermes Agent Coverage Report
-
-[xml]
-output = coverage.xml

.dockerignore

@@ -5,9 +5,12 @@
 
 # Dependencies
 node_modules
+.venv
 
 # CI/CD
 .github
 
 # Environment files
-.env
+.env
+
+*.md

.env.example

@@ -7,18 +7,29 @@
 # OpenRouter provides access to many models through one API
 # All LLM calls go through OpenRouter - no direct provider keys needed
 # Get your key at: https://openrouter.ai/keys
-OPENROUTER_API_KEY=
+# OPENROUTER_API_KEY=
 
-# Default model to use (OpenRouter format: provider/model)
-# Examples: anthropic/claude-opus-4.6, openai/gpt-4o, google/gemini-3-flash-preview, zhipuai/glm-4-plus
-LLM_MODEL=anthropic/claude-opus-4.6
+# Default model is configured in ~/.hermes/config.yaml (model.default).
+# Use 'hermes model' or 'hermes setup' to change it.
+# LLM_MODEL is no longer read from .env — this line is kept for reference only.
+# LLM_MODEL=anthropic/claude-opus-4.6
+
+# =============================================================================
+# LLM PROVIDER (Google AI Studio / Gemini)
+# =============================================================================
+# Native Gemini API via Google's OpenAI-compatible endpoint.
+# Get your key at: https://aistudio.google.com/app/apikey
+# GOOGLE_API_KEY=your_google_ai_studio_key_here
+# GEMINI_API_KEY=your_gemini_key_here  # alias for GOOGLE_API_KEY
+# Optional base URL override (default: Google's OpenAI-compatible endpoint)
+# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
 
 # =============================================================================
 # LLM PROVIDER (z.ai / GLM)
 # =============================================================================
 # z.ai provides access to ZhipuAI GLM models (GLM-4-Plus, etc.)
 # Get your key at: https://z.ai or https://open.bigmodel.cn
-GLM_API_KEY=
+# GLM_API_KEY=
 # GLM_BASE_URL=https://api.z.ai/api/paas/v4  # Override default base URL
 
 # =============================================================================
@@ -28,21 +39,30 @@ GLM_API_KEY=
 # Get your key at: https://platform.kimi.ai (Kimi Code console)
 # Keys prefixed sk-kimi- use the Kimi Code API (api.kimi.com) by default.
 # Legacy keys from platform.moonshot.ai need KIMI_BASE_URL override below.
-KIMI_API_KEY=
+# KIMI_API_KEY=
 # KIMI_BASE_URL=https://api.kimi.com/coding/v1  # Default for sk-kimi- keys
 # KIMI_BASE_URL=https://api.moonshot.ai/v1      # For legacy Moonshot keys
 # KIMI_BASE_URL=https://api.moonshot.cn/v1       # For Moonshot China keys
+# KIMI_CN_API_KEY=                               # Dedicated Moonshot China key
+
+# =============================================================================
+# LLM PROVIDER (Arcee AI)
+# =============================================================================
+# Arcee AI provides access to Trinity models (trinity-mini, trinity-large-*)
+# Get an Arcee key at: https://chat.arcee.ai/
+# ARCEEAI_API_KEY=
+# ARCEE_BASE_URL=                                 # Override default base URL
 
 # =============================================================================
 # LLM PROVIDER (MiniMax)
 # =============================================================================
 # MiniMax provides access to MiniMax models (global endpoint)
 # Get your key at: https://www.minimax.io
-MINIMAX_API_KEY=
+# MINIMAX_API_KEY=
 # MINIMAX_BASE_URL=https://api.minimax.io/v1  # Override default base URL
 
 # MiniMax China endpoint (for users in mainland China)
-MINIMAX_CN_API_KEY=
+# MINIMAX_CN_API_KEY=
 # MINIMAX_CN_BASE_URL=https://api.minimaxi.com/v1  # Override default base URL
 
 # =============================================================================
@@ -50,7 +70,7 @@ MINIMAX_CN_API_KEY=
 # =============================================================================
 # OpenCode Zen provides curated, tested models (GPT, Claude, Gemini, MiniMax, GLM, Kimi)
 # Pay-as-you-go pricing. Get your key at: https://opencode.ai/auth
-OPENCODE_ZEN_API_KEY=
+# OPENCODE_ZEN_API_KEY=
 # OPENCODE_ZEN_BASE_URL=https://opencode.ai/zen/v1  # Override default base URL
 
 # =============================================================================
@@ -58,7 +78,7 @@ OPENCODE_ZEN_API_KEY=
 # =============================================================================
 # OpenCode Go provides access to open models (GLM-5, Kimi K2.5, MiniMax M2.5)
 # $10/month subscription. Get your key at: https://opencode.ai/auth
-OPENCODE_GO_API_KEY=
+# OPENCODE_GO_API_KEY=
 
 # =============================================================================
 # LLM PROVIDER (Hugging Face Inference Providers)
@@ -67,35 +87,52 @@ OPENCODE_GO_API_KEY=
 # Free tier included ($0.10/month), no markup on provider rates.
 # Get your token at: https://huggingface.co/settings/tokens
 # Required permission: "Make calls to Inference Providers"
-HF_TOKEN=
+# HF_TOKEN=
 # OPENCODE_GO_BASE_URL=https://opencode.ai/zen/go/v1  # Override default base URL
 
+# =============================================================================
+# LLM PROVIDER (Qwen OAuth)
+# =============================================================================
+# Qwen OAuth reuses your local Qwen CLI login (qwen auth qwen-oauth).
+# No API key needed — credentials come from ~/.qwen/oauth_creds.json.
+# Optional base URL override:
+# HERMES_QWEN_BASE_URL=https://portal.qwen.ai/v1
+
+# =============================================================================
+# LLM PROVIDER (Xiaomi MiMo)
+# =============================================================================
+# Xiaomi MiMo models (mimo-v2-pro, mimo-v2-omni, mimo-v2-flash).
+# Get your key at: https://platform.xiaomimimo.com
+# XIAOMI_API_KEY=your_key_here
+# Optional base URL override:
+# XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1
+
 # =============================================================================
 # TOOL API KEYS
 # =============================================================================
 
 # Exa API Key - AI-native web search and contents
 # Get at: https://exa.ai
-EXA_API_KEY=
+# EXA_API_KEY=
 
 # Parallel API Key - AI-native web search and extract
 # Get at: https://parallel.ai
-PARALLEL_API_KEY=
+# PARALLEL_API_KEY=
 
 # Firecrawl API Key - Web search, extract, and crawl
 # Get at: https://firecrawl.dev/
-FIRECRAWL_API_KEY=
+# FIRECRAWL_API_KEY=
 
 
 # FAL.ai API Key - Image generation
 # Get at: https://fal.ai/
-FAL_KEY=
+# FAL_KEY=
 
 # Honcho - Cross-session AI-native user modeling (optional)
 # Builds a persistent understanding of the user across sessions and tools.
 # Get at: https://app.honcho.dev
 # Also requires ~/.honcho/config.json with enabled=true (see README).
-HONCHO_API_KEY=
+# HONCHO_API_KEY=
 
 # =============================================================================
 # TERMINAL TOOL CONFIGURATION
@@ -108,6 +145,10 @@ HONCHO_API_KEY=
 # Only override here if you need to force a backend without touching config.yaml:
 # TERMINAL_ENV=local
 
+# Override the container runtime binary (e.g. to use Podman instead of Docker).
+# Useful on systems where Docker's storage driver is broken or unavailable.
+# HERMES_DOCKER_BINARY=/usr/local/bin/podman
+
 # Container images (for singularity/docker/modal backends)
 # TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
 # TERMINAL_SINGULARITY_IMAGE=docker://nikolaik/python-nodejs:python3.11-nodejs20
@@ -181,10 +222,10 @@ TERMINAL_LIFETIME_SECONDS=300
 
 # Browserbase API Key - Cloud browser execution
 # Get at: https://browserbase.com/
-BROWSERBASE_API_KEY=
+# BROWSERBASE_API_KEY=
 
 # Browserbase Project ID - From your Browserbase dashboard
-BROWSERBASE_PROJECT_ID=
+# BROWSERBASE_PROJECT_ID=
 
 # Enable residential proxies for better CAPTCHA solving (default: true)
 # Routes traffic through residential IPs, significantly improves success rate
@@ -216,7 +257,7 @@ BROWSER_INACTIVITY_TIMEOUT=120
 # Uses OpenAI's API directly (not via OpenRouter).
 # Named VOICE_TOOLS_OPENAI_KEY to avoid interference with OpenRouter.
 # Get at: https://platform.openai.com/api-keys
-VOICE_TOOLS_OPENAI_KEY=
+# VOICE_TOOLS_OPENAI_KEY=
 
 # =============================================================================
 # SLACK INTEGRATION
@@ -231,6 +272,21 @@ VOICE_TOOLS_OPENAI_KEY=
 # Slack allowed users (comma-separated Slack user IDs)
 # SLACK_ALLOWED_USERS=
 
+# =============================================================================
+# TELEGRAM INTEGRATION
+# =============================================================================
+# Telegram Bot Token - From @BotFather (https://t.me/BotFather)
+# TELEGRAM_BOT_TOKEN=
+# TELEGRAM_ALLOWED_USERS=                  # Comma-separated user IDs
+# TELEGRAM_HOME_CHANNEL=                   # Default chat for cron delivery
+# TELEGRAM_HOME_CHANNEL_NAME=              # Display name for home channel
+
+# Webhook mode (optional — for cloud deployments like Fly.io/Railway)
+# Default is long polling. Setting TELEGRAM_WEBHOOK_URL switches to webhook mode.
+# TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
+# TELEGRAM_WEBHOOK_PORT=8443
+# TELEGRAM_WEBHOOK_SECRET=                 # Recommended for production
+
 # WhatsApp (built-in Baileys bridge — run `hermes whatsapp` to pair)
 # WHATSAPP_ENABLED=false
 # WHATSAPP_ALLOWED_USERS=15551234567
@@ -287,11 +343,11 @@ IMAGE_TOOLS_DEBUG=false
 
 # Tinker API Key - RL training service
 # Get at: https://tinker-console.thinkingmachines.ai/keys
-TINKER_API_KEY=
+# TINKER_API_KEY=
 
 # Weights & Biases API Key - Experiment tracking and metrics
 # Get at: https://wandb.ai/authorize
-WANDB_API_KEY=
+# WANDB_API_KEY=
 
 # RL API Server URL (default: http://localhost:8080)
 # Change if running the rl-server on a different host/port

.gitattributes

@@ -0,0 +1,2 @@
+# Auto-generated files — collapse diffs and exclude from language stats
+web/package-lock.json linguist-generated=true

.gitea/workflows/ci.yml

@@ -1,54 +0,0 @@
-name: Forge CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-concurrency:
-  group: forge-ci-${{ gitea.ref }}
-  cancel-in-progress: true
-
-jobs:
-  smoke-and-build:
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-
-      - name: Set up Python 3.11
-        run: uv python install 3.11
-
-      - name: Install package
-        run: |
-          uv venv .venv --python 3.11
-          source .venv/bin/activate
-          uv pip install -e ".[all,dev]"
-
-      - name: Smoke tests
-        run: |
-          source .venv/bin/activate
-          python scripts/smoke_test.py
-        env:
-          OPENROUTER_API_KEY: ""
-          OPENAI_API_KEY: ""
-          NOUS_API_KEY: ""
-
-      - name: Syntax guard
-        run: |
-          source .venv/bin/activate
-          python scripts/syntax_guard.py
-
-      - name: Green-path E2E
-        run: |
-          source .venv/bin/activate
-          python -m pytest tests/test_green_path_e2e.py -q --tb=short
-        env:
-          OPENROUTER_API_KEY: ""
-          OPENAI_API_KEY: ""
-          NOUS_API_KEY: ""

.gitea/workflows/lint.yml

@@ -0,0 +1,28 @@
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Check for hardcoded paths
+        run: python3 scripts/lint_hardcoded_paths.py
+        continue-on-error: true
+
+      - name: Check Python syntax
+        run: |
+          find . -name "*.py" -not -path "./.git/*" -not -path "./node_modules/*" | head -100 | xargs python3 -m py_compile || true

.gitea/workflows/notebook-ci.yml

@@ -1,44 +0,0 @@
-name: Notebook CI
-
-on:
-  push:
-    paths:
-      - 'notebooks/**'
-  pull_request:
-    paths:
-      - 'notebooks/**'
-
-jobs:
-  notebook-smoke:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.12'
-
-      - name: Install dependencies
-        run: |
-          pip install papermill jupytext nbformat
-          python -m ipykernel install --user --name python3
-
-      - name: Execute system health notebook
-        run: |
-          papermill notebooks/agent_task_system_health.ipynb /tmp/output.ipynb \
-            -p threshold 0.5 \
-            -p hostname ci-runner
-
-      - name: Verify output has results
-        run: |
-          python -c "
-          import json
-          nb = json.load(open('/tmp/output.ipynb'))
-          code_cells = [c for c in nb['cells'] if c['cell_type'] == 'code']
-          outputs = [c.get('outputs', []) for c in code_cells]
-          total_outputs = sum(len(o) for o in outputs)
-          assert total_outputs > 0, 'Notebook produced no outputs'
-          print(f'Notebook executed successfully with {total_outputs} output(s)')
-          "

.githooks/pre-commit

@@ -1,15 +0,0 @@
-#!/bin/bash
-#
-# Pre-commit hook wrapper for secret leak detection.
-#
-# Installation:
-#   git config core.hooksPath .githooks
-#
-# To bypass temporarily:
-#   git commit --no-verify
-#
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-exec python3 "${SCRIPT_DIR}/pre-commit.py" "$@"

.githooks/pre-commit-hardcoded-path.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""
+Pre-commit hook: Reject hardcoded home-directory paths.
+
+Install:
+    cp pre-commit-hardcoded-path.py .git/hooks/pre-commit-hardcoded-path
+    chmod +x .git/hooks/pre-commit-hardcoded-path
+    
+    Or add to .pre-commit-config.yaml
+"""
+
+import sys
+import subprocess
+import re
+
+PATTERNS = [
+    (r"/Users/[\w.\-]+/", "macOS home directory"),
+    (r"/home/[\w.\-]+/", "Linux home directory"),
+    (r"(?<![\w/])~/", "unexpanded tilde"),
+]
+
+NOQA = re.compile(r"#\s*noqa:?\s*hardcoded-path-ok")
+
+def get_staged_files():
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--name-only", "--diff-filter=ACM"],
+        capture_output=True, text=True
+    )
+    return [f for f in result.stdout.strip().split("\n") if f.endswith(".py")]
+
+def check_file(filepath):
+    try:
+        result = subprocess.run(
+            ["git", "show", f":{filepath}"],
+            capture_output=True, text=True
+        )
+        content = result.stdout
+    except Exception:
+        return []
+    
+    violations = []
+    for i, line in enumerate(content.split("\n"), 1):
+        if line.strip().startswith("#"):
+            continue
+        if line.strip().startswith(("import ", "from ")):
+            continue
+        if NOQA.search(line):
+            continue
+        for pattern, desc in PATTERNS:
+            if re.search(pattern, line):
+                violations.append((filepath, i, line.strip(), desc))
+                break
+    return violations
+
+def main():
+    files = get_staged_files()
+    if not files:
+        sys.exit(0)
+    
+    all_violations = []
+    for f in files:
+        all_violations.extend(check_file(f))
+    
+    if all_violations:
+        print("ERROR: Hardcoded home directory paths detected:")
+        print()
+        for filepath, line_no, line, desc in all_violations:
+            print(f"  {filepath}:{line_no}: {desc}")
+            print(f"    {line[:100]}")
+            print()
+        print("Fix: Use $HOME, relative paths, or get_hermes_home().")
+        print("Override: Add '# noqa: hardcoded-path-ok' to the line.")
+        sys.exit(1)
+    
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()

.githooks/pre-commit.py

@@ -1,327 +0,0 @@
-#!/usr/bin/env python3
-"""
-Pre-commit hook for detecting secret leaks in staged files.
-
-Scans staged diffs and full file contents for common secret patterns,
-token file paths, private keys, and credential strings.
-
-Installation:
-    git config core.hooksPath .githooks
-
-To bypass:
-    git commit --no-verify
-"""
-
-from __future__ import annotations
-
-import re
-import subprocess
-import sys
-from pathlib import Path
-from typing import Iterable, List, Callable, Union
-
-# ANSI color codes
-RED = "\033[0;31m"
-YELLOW = "\033[1;33m"
-GREEN = "\033[0;32m"
-NC = "\033[0m"
-
-
-class Finding:
-    """Represents a single secret leak finding."""
-
-    def __init__(self, filename: str, line: int, message: str) -> None:
-        self.filename = filename
-        self.line = line
-        self.message = message
-
-    def __repr__(self) -> str:
-        return f"Finding({self.filename!r}, {self.line}, {self.message!r})"
-
-    def __eq__(self, other: object) -> bool:
-        if not isinstance(other, Finding):
-            return NotImplemented
-        return (
-            self.filename == other.filename
-            and self.line == other.line
-            and self.message == other.message
-        )
-
-
-# ---------------------------------------------------------------------------
-# Regex patterns
-# ---------------------------------------------------------------------------
-
-_RE_SK_KEY = re.compile(r"sk-[a-zA-Z0-9]{20,}")
-_RE_BEARER = re.compile(r"Bearer\s+[a-zA-Z0-9_-]{20,}")
-
-_RE_ENV_ASSIGN = re.compile(
-    r"^(?:export\s+)?"
-    r"(OPENAI_API_KEY|GITEA_TOKEN|ANTHROPIC_API_KEY|KIMI_API_KEY"
-    r"|TELEGRAM_BOT_TOKEN|DISCORD_TOKEN)"
-    r"\s*=\s*(.+)$"
-)
-
-_RE_TOKEN_PATHS = re.compile(
-    r'(?:^|["\'\s])'
-    r"(\.(?:env)"
-    r"|(?:secrets|keystore|credentials|token|api_keys)\.json"
-    r"|~/\.hermes/credentials/"
-    r"|/root/nostr-relay/keystore\.json)"
-)
-
-_RE_PRIVATE_KEY = re.compile(
-    r"-----BEGIN (PRIVATE KEY|RSA PRIVATE KEY|OPENSSH PRIVATE KEY)-----"
-)
-
-_RE_URL_PASSWORD = re.compile(r"https?://[^:]+:[^@]+@")
-
-_RE_RAW_TOKEN = re.compile(r'"token"\s*:\s*"([^"]{10,})"')
-_RE_RAW_API_KEY = re.compile(r'"api_key"\s*:\s*"([^"]{10,})"')
-
-# Safe patterns (placeholders)
-_SAFE_ENV_VALUES = {
-    "<YOUR_API_KEY>",
-    "***",
-    "REDACTED",
-    "",
-}
-
-_RE_DOC_EXAMPLE = re.compile(
-    r"\b(?:example|documentation|doc|readme)\b",
-    re.IGNORECASE,
-)
-
-_RE_OS_ENVIRON = re.compile(r"os\.environ(?:\.get|\[)")
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-def is_binary_content(content: Union[str, bytes]) -> bool:
-    """Return True if content appears to be binary."""
-    if isinstance(content, str):
-        return False
-    return b"\x00" in content
-
-
-def _looks_like_safe_env_line(line: str) -> bool:
-    """Check if a line is a safe env var read or reference."""
-    if _RE_OS_ENVIRON.search(line):
-        return True
-    # Variable expansion like $OPENAI_API_KEY
-    if re.search(r'\$\w+\s*$', line.strip()):
-        return True
-    return False
-
-
-def _is_placeholder(value: str) -> bool:
-    """Check if a value is a known placeholder or empty."""
-    stripped = value.strip().strip('"').strip("'")
-    if stripped in _SAFE_ENV_VALUES:
-        return True
-    # Single word references like $VAR
-    if re.fullmatch(r"\$\w+", stripped):
-        return True
-    return False
-
-
-def _is_doc_or_example(line: str, value: str | None = None) -> bool:
-    """Check if line appears to be documentation or example code."""
-    # If the line contains a placeholder value, it's likely documentation
-    if value is not None and _is_placeholder(value):
-        return True
-    # If the line contains doc keywords and no actual secret-looking value
-    if _RE_DOC_EXAMPLE.search(line):
-        # For env assignments, if value is empty or placeholder
-        m = _RE_ENV_ASSIGN.search(line)
-        if m and _is_placeholder(m.group(2)):
-            return True
-    return False
-
-
-# ---------------------------------------------------------------------------
-# Scanning
-# ---------------------------------------------------------------------------
-
-def scan_line(line: str, filename: str, line_no: int) -> Iterable[Finding]:
-    """Scan a single line for secret leak patterns."""
-    stripped = line.rstrip("\n")
-    if not stripped:
-        return
-
-    # --- API keys ----------------------------------------------------------
-    if _RE_SK_KEY.search(stripped):
-        yield Finding(filename, line_no, "Potential API key (sk-...) found")
-        return  # One finding per line is enough
-
-    if _RE_BEARER.search(stripped):
-        yield Finding(filename, line_no, "Potential Bearer token found")
-        return
-
-    # --- Env var assignments -----------------------------------------------
-    m = _RE_ENV_ASSIGN.search(stripped)
-    if m:
-        var_name = m.group(1)
-        value = m.group(2)
-        if _looks_like_safe_env_line(stripped):
-            return
-        if _is_doc_or_example(stripped, value):
-            return
-        if not _is_placeholder(value):
-            yield Finding(
-                filename,
-                line_no,
-                f"Potential secret assignment: {var_name}=...",
-            )
-            return
-
-    # --- Token file paths --------------------------------------------------
-    if _RE_TOKEN_PATHS.search(stripped):
-        yield Finding(filename, line_no, "Potential token file path found")
-        return
-
-    # --- Private key blocks ------------------------------------------------
-    if _RE_PRIVATE_KEY.search(stripped):
-        yield Finding(filename, line_no, "Private key block found")
-        return
-
-    # --- Passwords in URLs -------------------------------------------------
-    if _RE_URL_PASSWORD.search(stripped):
-        yield Finding(filename, line_no, "Password in URL found")
-        return
-
-    # --- Raw token patterns ------------------------------------------------
-    if _RE_RAW_TOKEN.search(stripped):
-        yield Finding(filename, line_no, 'Raw "token" string with long value')
-        return
-
-    if _RE_RAW_API_KEY.search(stripped):
-        yield Finding(filename, line_no, 'Raw "api_key" string with long value')
-        return
-
-
-def scan_content(content: Union[str, bytes], filename: str) -> List[Finding]:
-    """Scan full file content for secrets."""
-    if isinstance(content, bytes):
-        try:
-            text = content.decode("utf-8")
-        except UnicodeDecodeError:
-            return []
-    else:
-        text = content
-
-    findings: List[Finding] = []
-    for line_no, line in enumerate(text.splitlines(), start=1):
-        findings.extend(scan_line(line, filename, line_no))
-    return findings
-
-
-def scan_files(
-    files: List[str],
-    content_reader: Callable[[str], bytes],
-) -> List[Finding]:
-    """Scan a list of files using the provided content reader."""
-    findings: List[Finding] = []
-    for filepath in files:
-        content = content_reader(filepath)
-        if is_binary_content(content):
-            continue
-        findings.extend(scan_content(content, filepath))
-    return findings
-
-
-# ---------------------------------------------------------------------------
-# Git helpers
-# ---------------------------------------------------------------------------
-
-
-def get_staged_files() -> List[str]:
-    """Return a list of staged file paths (excluding deletions)."""
-    result = subprocess.run(
-        ["git", "diff", "--cached", "--name-only", "--diff-filter=ACMR"],
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode != 0:
-        return []
-    return [f for f in result.stdout.strip().split("\n") if f]
-
-
-def get_staged_diff() -> str:
-    """Return the diff of staged changes."""
-    result = subprocess.run(
-        ["git", "diff", "--cached", "--no-color", "-U0"],
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode != 0:
-        return ""
-    return result.stdout
-
-
-def get_file_content_at_staged(filepath: str) -> bytes:
-    """Return the staged content of a file."""
-    result = subprocess.run(
-        ["git", "show", f":{filepath}"],
-        capture_output=True,
-    )
-    if result.returncode != 0:
-        return b""
-    return result.stdout
-
-
-# ---------------------------------------------------------------------------
-# Main
-# ---------------------------------------------------------------------------
-
-
-def main() -> int:
-    print(f"{GREEN}🔍 Scanning for secret leaks in staged files...{NC}")
-
-    staged_files = get_staged_files()
-    if not staged_files:
-        print(f"{GREEN}✓ No files staged for commit{NC}")
-        return 0
-
-    # Scan both full staged file contents and the diff content
-    findings = scan_files(staged_files, get_file_content_at_staged)
-
-    diff_text = get_staged_diff()
-    if diff_text:
-        for line_no, line in enumerate(diff_text.splitlines(), start=1):
-            # Only scan added lines in the diff
-            if line.startswith("+") and not line.startswith("+++"):
-                findings.extend(scan_line(line[1:], "<diff>", line_no))
-
-    if not findings:
-        print(f"{GREEN}✓ No potential secret leaks detected{NC}")
-        return 0
-
-    print(f"{RED}✗ Potential secret leaks detected:{NC}\n")
-    for finding in findings:
-        loc = finding.filename
-        print(
-            f"  {RED}[LEAK]{NC} {loc}:{finding.line} — {finding.message}"
-        )
-
-    print()
-    print(f"{RED}╔════════════════════════════════════════════════════════════╗{NC}")
-    print(f"{RED}║  COMMIT BLOCKED: Potential secrets detected!               ║{NC}")
-    print(f"{RED}╚════════════════════════════════════════════════════════════╝{NC}")
-    print()
-    print("Recommendations:")
-    print("  1. Remove secrets from your code")
-    print("  2. Use environment variables or a secrets manager")
-    print("  3. Add sensitive files to .gitignore")
-    print("  4. Rotate any exposed credentials immediately")
-    print()
-    print("If you are CERTAIN this is a false positive, you can bypass:")
-    print("  git commit --no-verify")
-    print()
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

.github/CODEOWNERS

@@ -1,13 +0,0 @@
-# Default owners for all files
-* @Timmy
-
-# Critical paths require explicit review
-/gateway/ @Timmy
-/tools/ @Timmy
-/agent/ @Timmy
-/config/ @Timmy
-/scripts/ @Timmy
-/.github/workflows/ @Timmy
-/pyproject.toml @Timmy
-/requirements.txt @Timmy
-/Dockerfile @Timmy

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -11,6 +11,7 @@ body:
         **Before submitting**, please:
         - [ ] Search [existing issues](https://github.com/NousResearch/hermes-agent/issues) to avoid duplicates
         - [ ] Update to the latest version (`hermes update`) and confirm the bug still exists
+        - [ ] Run `hermes debug share` and paste the links below (see Debug Report section)
 
   - type: textarea
     id: description
@@ -82,6 +83,25 @@ body:
         - Slack
         - WhatsApp
 
+  - type: textarea
+    id: debug-report
+    attributes:
+      label: Debug Report
+      description: |
+        Run `hermes debug share` from your terminal and paste the links it prints here.
+        This uploads your system info, config, and recent logs to a paste service automatically.
+
+        If you're in an interactive chat session, you can also use the `/debug` slash command — it does the same thing.
+
+        If the upload fails, run `hermes debug share --local` and paste the output directly.
+      placeholder: |
+        Report   https://paste.rs/abc123
+        agent.log   https://paste.rs/def456
+        gateway.log   https://paste.rs/ghi789
+      render: shell
+    validations:
+      required: true
+
   - type: input
     id: os
     attributes:
@@ -97,8 +117,6 @@ body:
       label: Python Version
       description: Output of `python --version`
       placeholder: "3.11.9"
-    validations:
-      required: true
 
   - type: input
     id: hermes-version
@@ -106,14 +124,14 @@ body:
       label: Hermes Version
       description: Output of `hermes version`
       placeholder: "2.1.0"
-    validations:
-      required: true
 
   - type: textarea
     id: logs
     attributes:
-      label: Relevant Logs / Traceback
-      description: Paste any error output, traceback, or log messages. This will be auto-formatted as code.
+      label: Additional Logs / Traceback (optional)
+      description: |
+        The debug report above covers most logs. Use this field for any extra error output, 
+        tracebacks, or screenshots not captured by `hermes debug share`.
       render: shell
 
   - type: textarea

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -71,3 +71,15 @@ body:
       label: Contribution
       options:
         - label: I'd like to implement this myself and submit a PR
+
+  - type: textarea
+    id: debug-report
+    attributes:
+      label: Debug Report (optional)
+      description: |
+        If this feature request is related to a problem you're experiencing, run `hermes debug share` and paste the links here.
+        In an interactive chat session, you can use `/debug` instead.
+        This helps us understand your environment and any related logs.
+      placeholder: |
+        Report   https://paste.rs/abc123
+      render: shell

.github/ISSUE_TEMPLATE/security_pr_checklist.yml

@@ -1,99 +0,0 @@
-name: "🔒 Security PR Checklist"
-description: "Use this when your PR touches authentication, file I/O, external API calls, or other sensitive paths."
-title: "[Security Review]: "
-labels: ["security", "needs-review"]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        ## Security Pre-Merge Review
-        Complete this checklist before requesting review on PRs that touch **authentication, file I/O, external API calls, or secrets handling**.
-
-  - type: input
-    id: pr-link
-    attributes:
-      label: Pull Request
-      description: Link to the PR being reviewed
-      placeholder: "https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/pulls/XXX"
-    validations:
-      required: true
-
-  - type: dropdown
-    id: change-type
-    attributes:
-      label: Change Category
-      description: What kind of sensitive change does this PR make?
-      multiple: true
-      options:
-        - Authentication / Authorization
-        - File I/O (read/write/delete)
-        - External API calls (outbound HTTP/network)
-        - Secret / credential handling
-        - Command execution (subprocess/shell)
-        - Dependency addition or update
-        - Configuration changes
-        - CI/CD pipeline changes
-    validations:
-      required: true
-
-  - type: checkboxes
-    id: secrets-checklist
-    attributes:
-      label: Secrets & Credentials
-      options:
-        - label: No secrets, API keys, or credentials are hardcoded
-          required: true
-        - label: All sensitive values are loaded from environment variables or a secrets manager
-          required: true
-        - label: Test fixtures use fake/placeholder values, not real credentials
-          required: true
-
-  - type: checkboxes
-    id: input-validation-checklist
-    attributes:
-      label: Input Validation
-      options:
-        - label: All external input (user, API, file) is validated before use
-          required: true
-        - label: File paths are validated against path traversal (`../`, null bytes, absolute paths)
-        - label: URLs are validated for SSRF (blocked private/metadata IPs)
-        - label: Shell commands do not use `shell=True` with user-controlled input
-
-  - type: checkboxes
-    id: auth-checklist
-    attributes:
-      label: Authentication & Authorization (if applicable)
-      options:
-        - label: Authentication tokens are not logged or exposed in error messages
-        - label: Authorization checks happen server-side, not just client-side
-        - label: Session tokens are properly scoped and have expiry
-
-  - type: checkboxes
-    id: supply-chain-checklist
-    attributes:
-      label: Supply Chain
-      options:
-        - label: New dependencies are pinned to a specific version range
-        - label: Dependencies come from trusted sources (PyPI, npm, official repos)
-        - label: No `.pth` files or install hooks that execute arbitrary code
-        - label: "`pip-audit` passes (no known CVEs in added dependencies)"
-
-  - type: textarea
-    id: threat-model
-    attributes:
-      label: Threat Model Notes
-      description: |
-        Briefly describe the attack surface this change introduces or modifies, and how it is mitigated.
-      placeholder: |
-        This PR adds a new outbound HTTP call to the OpenRouter API.
-        Mitigation: URL is hardcoded (no user input), response is parsed with strict schema validation.
-
-  - type: textarea
-    id: testing
-    attributes:
-      label: Security Testing Done
-      description: What security testing did you perform?
-      placeholder: |
-        - Ran validate_security.py — all checks pass
-        - Tested path traversal attempts manually
-        - Verified no secrets in git diff

.github/ISSUE_TEMPLATE/setup_help.yml

@@ -9,7 +9,8 @@ body:
         Sorry you're having trouble! Please fill out the details below so we can help.
 
         **Quick checks first:**
-        - Run `hermes doctor` and include the output below
+        - Run `hermes debug share` and paste the links in the Debug Report section below
+        - If you're in a chat session, you can use `/debug` instead — it does the same thing
         - Try `hermes update` to get the latest version
         - Check the [README troubleshooting section](https://github.com/NousResearch/hermes-agent#troubleshooting)
         - For general questions, consider the [Nous Research Discord](https://discord.gg/NousResearch) for faster help
@@ -74,10 +75,21 @@ body:
       placeholder: "2.1.0"
 
   - type: textarea
-    id: doctor-output
+    id: debug-report
     attributes:
-      label: Output of `hermes doctor`
-      description: Run `hermes doctor` and paste the full output. This will be auto-formatted.
+      label: Debug Report
+      description: |
+        Run `hermes debug share` from your terminal and paste the links it prints here.
+        This uploads your system info, config, and recent logs to a paste service automatically.
+
+        If you're in an interactive chat session, you can also use the `/debug` slash command — it does the same thing.
+
+        If the upload fails or install didn't get that far, run `hermes debug share --local` and paste the output directly.
+        If even that doesn't work, run `hermes doctor` and paste that output instead.
+      placeholder: |
+        Report   https://paste.rs/abc123
+        agent.log   https://paste.rs/def456
+        gateway.log   https://paste.rs/ghi789
       render: shell
 
   - type: textarea

.github/workflows/contributor-check.yml

@@ -0,0 +1,73 @@
+name: Contributor Attribution Check
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      # Only run when code files change (not docs-only PRs)
+      - '*.py'
+      - '**/*.py'
+      - '.github/workflows/contributor-check.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  check-attribution:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          fetch-depth: 0  # Full history needed for git log
+
+      - name: Check for unmapped contributor emails
+        run: |
+          # Get the merge base between this PR and main
+          MERGE_BASE=$(git merge-base origin/main HEAD)
+
+          # Find any new author emails in this PR's commits
+          NEW_EMAILS=$(git log ${MERGE_BASE}..HEAD --format='%ae' --no-merges | sort -u)
+
+          if [ -z "$NEW_EMAILS" ]; then
+            echo "No new commits to check."
+            exit 0
+          fi
+
+          # Check each email against AUTHOR_MAP in release.py
+          MISSING=""
+          while IFS= read -r email; do
+            # Skip teknium and bot emails
+            case "$email" in
+              *teknium*|*noreply@github.com*|*dependabot*|*github-actions*|*anthropic.com*|*cursor.com*)
+                continue ;;
+            esac
+
+            # Check if email is in AUTHOR_MAP (either as a key or matches noreply pattern)
+            if echo "$email" | grep -qP '\+.*@users\.noreply\.github\.com'; then
+              continue  # GitHub noreply emails auto-resolve
+            fi
+
+            if ! grep -qF "\"${email}\"" scripts/release.py 2>/dev/null; then
+              AUTHOR=$(git log --author="$email" --format='%an' -1)
+              MISSING="${MISSING}\n  ${email} (${AUTHOR})"
+            fi
+          done <<< "$NEW_EMAILS"
+
+          if [ -n "$MISSING" ]; then
+            echo ""
+            echo "⚠️  New contributor email(s) not in AUTHOR_MAP:"
+            echo -e "$MISSING"
+            echo ""
+            echo "Please add mappings to scripts/release.py AUTHOR_MAP:"
+            echo -e "$MISSING" | while read -r line; do
+              email=$(echo "$line" | sed 's/^ *//' | cut -d' ' -f1)
+              [ -z "$email" ] && continue
+              echo "    \"${email}\": \"<github-username>\","
+            done
+            echo ""
+            echo "To find the GitHub username for an email:"
+            echo "  gh api 'search/users?q=EMAIL+in:email' --jq '.items[0].login'"
+            exit 1
+          else
+            echo "✅ All contributor emails are mapped in AUTHOR_MAP."
+          fi

.github/workflows/dependency-audit.yml

@@ -1,82 +0,0 @@
-name: Dependency Audit
-
-on:
-  pull_request:
-    branches: [main]
-    paths:
-      - 'requirements.txt'
-      - 'pyproject.toml'
-      - 'uv.lock'
-  schedule:
-    - cron: '0 8 * * 1'  # Weekly on Monday
-  workflow_dispatch:
-
-permissions:
-  pull-requests: write
-  contents: read
-
-jobs:
-  audit:
-    name: Audit Python dependencies
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
-      - name: Set up Python
-        run: uv python install 3.11
-      - name: Install pip-audit
-        run: uv pip install --system pip-audit
-      - name: Run pip-audit
-        id: audit
-        run: |
-          set -euo pipefail
-          # Run pip-audit against the lock file/requirements
-          if pip-audit --requirement requirements.txt -f json -o /tmp/audit-results.json 2>/tmp/audit-stderr.txt; then
-            echo "found=false" >> "$GITHUB_OUTPUT"
-          else
-            echo "found=true" >> "$GITHUB_OUTPUT"
-            # Check severity
-            CRITICAL=$(python3 -c "
-          import json, sys
-          data = json.load(open('/tmp/audit-results.json'))
-          vulns = data.get('dependencies', [])
-          for d in vulns:
-              for v in d.get('vulns', []):
-                  aliases = v.get('aliases', [])
-                  # Check for critical/high CVSS
-                  if any('CVSS' in str(a) for a in aliases):
-                      print('true')
-                      sys.exit(0)
-          print('false')
-          " 2>/dev/null || echo 'false')
-            echo "critical=${CRITICAL}" >> "$GITHUB_OUTPUT"
-          fi
-        continue-on-error: true
-      - name: Post results comment
-        if: steps.audit.outputs.found == 'true' && github.event_name == 'pull_request'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          BODY="## ⚠️ Dependency Vulnerabilities Detected
-
-          \`pip-audit\` found vulnerable dependencies in this PR. Review and update before merging.
-
-          \`\`\`
-          $(cat /tmp/audit-results.json | python3 -c "
-          import json, sys
-          data = json.load(sys.stdin)
-          for dep in data.get('dependencies', []):
-              for v in dep.get('vulns', []):
-                  print(f\"  {dep['name']}=={dep['version']}: {v['id']} - {v.get('description', '')[:120]}\")
-          " 2>/dev/null || cat /tmp/audit-stderr.txt)
-          \`\`\`
-
-          ---
-          *Automated scan by [dependency-audit](/.github/workflows/dependency-audit.yml)*"
-          gh pr comment "${{ github.event.pull_request.number }}" --body "$BODY"
-      - name: Fail on vulnerabilities
-        if: steps.audit.outputs.found == 'true'
-        run: |
-          echo "::error::Vulnerable dependencies detected. See PR comment for details."
-          cat /tmp/audit-results.json | python3 -m json.tool || true
-          exit 1

.github/workflows/deploy-site.yml

@@ -6,6 +6,8 @@ on:
     paths:
       - 'website/**'
       - 'landingpage/**'
+      - 'skills/**'
+      - 'optional-skills/**'
       - '.github/workflows/deploy-site.yml'
   workflow_dispatch:
 
@@ -19,19 +21,39 @@ concurrency:
 
 jobs:
   build-and-deploy:
+    # Only run on the upstream repository, not on forks
+    if: github.repository == 'NousResearch/hermes-agent'
     runs-on: ubuntu-latest
     environment:
       name: github-pages
       url: ${{ steps.deploy.outputs.page_url }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
         with:
           node-version: 20
           cache: npm
           cache-dependency-path: website/package-lock.json
 
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: '3.11'
+
+      - name: Install PyYAML for skill extraction
+        run: pip install pyyaml==6.0.2 httpx==0.28.1
+
+      - name: Extract skill metadata for dashboard
+        run: python3 website/scripts/extract-skills.py
+
+      - name: Build skills index (if not already present)
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if [ ! -f website/static/api/skills-index.json ]; then
+            python3 scripts/build_skills_index.py || echo "Skills index build failed (non-fatal)"
+          fi
+
       - name: Install dependencies
         run: npm ci
         working-directory: website
@@ -51,10 +73,10 @@ jobs:
           echo "hermes-agent.nousresearch.com" > _site/CNAME
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa  # v3
         with:
           path: _site
 
       - name: Deploy to GitHub Pages
         id: deploy
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e  # v4

.github/workflows/docker-publish.yml

@@ -5,6 +5,11 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+  release:
+    types: [published]
+
+permissions:
+  contents: read
 
 concurrency:
   group: docker-${{ github.ref }}
@@ -12,23 +17,32 @@ concurrency:
 
 jobs:
   build-and-push:
+    # Only run on the upstream repository, not on forks
+    if: github.repository == 'NousResearch/hermes-agent'
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 60
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
         with:
           submodules: recursive
 
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130  # v3
 
-      - name: Build image
-        uses: docker/build-push-action@v6
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
+
+      # Build amd64 only so we can `load` the image for smoke testing.
+      # `load: true` cannot export a multi-arch manifest to the local daemon.
+      # The multi-arch build follows on push to main / release.
+      - name: Build image (amd64, smoke test)
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
         with:
           context: .
           file: Dockerfile
           load: true
+          platforms: linux/amd64
           tags: nousresearch/hermes-agent:test
           cache-from: type=gha
           cache-to: type=gha,mode=max
@@ -41,21 +55,32 @@ jobs:
             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
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9  # v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: Push image
+      - name: Push multi-arch image (main branch)
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
         with:
           context: .
           file: Dockerfile
           push: true
-          tags: |
-            nousresearch/hermes-agent:latest
-            nousresearch/hermes-agent:${{ github.sha }}
+          platforms: linux/amd64,linux/arm64
+          tags: nousresearch/hermes-agent:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Push multi-arch image (release)
+        if: github.event_name == 'release'
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
+        with:
+          context: .
+          file: Dockerfile
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: nousresearch/hermes-agent:${{ github.event.release.tag_name }}
           cache-from: type=gha
           cache-to: type=gha,mode=max

.github/workflows/docs-site-checks.yml

@@ -7,13 +7,16 @@ on:
       - '.github/workflows/docs-site-checks.yml'
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   docs-site-checks:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
         with:
           node-version: 20
           cache: npm
@@ -23,12 +26,15 @@ jobs:
         run: npm ci
         working-directory: website
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
         with:
           python-version: '3.11'
 
       - name: Install ascii-guard
-        run: python -m pip install ascii-guard
+        run: python -m pip install ascii-guard==2.3.0 pyyaml==6.0.3
+
+      - name: Extract skill metadata for dashboard
+        run: python3 website/scripts/extract-skills.py
 
       - name: Lint docs diagrams
         run: npm run lint:diagrams

.github/workflows/nix.yml

@@ -14,6 +14,9 @@ on:
       - 'run_agent.py'
       - 'acp_adapter/**'
 
+permissions:
+  contents: read
+
 concurrency:
   group: nix-${{ github.ref }}
   cancel-in-progress: true
@@ -26,9 +29,9 @@ jobs:
     runs-on: ${{ matrix.os }}
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
-      - uses: DeterminateSystems/nix-installer-action@main
-      - uses: DeterminateSystems/magic-nix-cache-action@main
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - uses: DeterminateSystems/nix-installer-action@ef8a148080ab6020fd15196c2084a2eea5ff2d25  # v22
+      - uses: DeterminateSystems/magic-nix-cache-action@565684385bcd71bad329742eefe8d12f2e765b39  # v13
       - name: Check flake
         if: runner.os == 'Linux'
         run: nix flake check --print-build-logs

.github/workflows/quarterly-security-audit.yml

@@ -1,114 +0,0 @@
-name: Quarterly Security Audit
-
-on:
-  schedule:
-    # Run at 08:00 UTC on the first day of each quarter (Jan, Apr, Jul, Oct)
-    - cron: '0 8 1 1,4,7,10 *'
-  workflow_dispatch:
-    inputs:
-      reason:
-        description: 'Reason for manual trigger'
-        required: false
-        default: 'Manual quarterly audit'
-
-permissions:
-  issues: write
-  contents: read
-
-jobs:
-  create-audit-issue:
-    name: Create quarterly security audit issue
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Get quarter info
-        id: quarter
-        run: |
-          MONTH=$(date +%-m)
-          YEAR=$(date +%Y)
-          QUARTER=$(( (MONTH - 1) / 3 + 1 ))
-          echo "quarter=Q${QUARTER}-${YEAR}" >> "$GITHUB_OUTPUT"
-          echo "year=${YEAR}" >> "$GITHUB_OUTPUT"
-          echo "q=${QUARTER}" >> "$GITHUB_OUTPUT"
-
-      - name: Create audit issue
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          QUARTER="${{ steps.quarter.outputs.quarter }}"
-
-          gh issue create \
-            --title "[$QUARTER] Quarterly Security Audit" \
-            --label "security,audit" \
-            --body "$(cat <<'BODY'
-          ## Quarterly Security Audit — ${{ steps.quarter.outputs.quarter }}
-
-          This is the scheduled quarterly security audit for the hermes-agent project. Complete each section and close this issue when the audit is done.
-
-          **Audit Period:** ${{ steps.quarter.outputs.quarter }}
-          **Due:** End of quarter
-          **Owner:** Assign to a maintainer
-
-          ---
-
-          ## 1. Open Issues & PRs Audit
-
-          Review all open issues and PRs for security-relevant content. Tag any that touch attack surfaces with the `security` label.
-
-          - [ ] Review open issues older than 30 days for unaddressed security concerns
-          - [ ] Tag security-relevant open PRs with `needs-security-review`
-          - [ ] Check for any issues referencing CVEs or known vulnerabilities
-          - [ ] Review recently closed security issues — are fixes deployed?
-
-          ## 2. Dependency Audit
-
-          - [ ] Run `pip-audit` against current `requirements.txt` / `pyproject.toml`
-          - [ ] Check `uv.lock` for any pinned versions with known CVEs
-          - [ ] Review any `git+` dependencies for recent changes or compromise signals
-          - [ ] Update vulnerable dependencies and open PRs for each
-
-          ## 3. Critical Path Review
-
-          Review recent changes to attack-surface paths:
-
-          - [ ] `gateway/` — authentication, message routing, platform adapters
-          - [ ] `tools/` — file I/O, command execution, web access
-          - [ ] `agent/` — prompt handling, context management
-          - [ ] `config/` — secrets loading, configuration parsing
-          - [ ] `.github/workflows/` — CI/CD integrity
-
-          Run: `git log --since="3 months ago" --name-only -- gateway/ tools/ agent/ config/ .github/workflows/`
-
-          ## 4. Secret Scan
-
-          - [ ] Run secret scanner on the full codebase (not just diffs)
-          - [ ] Verify no credentials are present in git history
-          - [ ] Confirm all API keys/tokens in use are rotated on a regular schedule
-
-          ## 5. Access & Permissions Review
-
-          - [ ] Review who has write access to the main branch
-          - [ ] Confirm branch protection rules are still in place (require PR + review)
-          - [ ] Verify CI/CD secrets are scoped correctly (not over-permissioned)
-          - [ ] Review CODEOWNERS file for accuracy
-
-          ## 6. Vulnerability Triage
-
-          List any new vulnerabilities found this quarter:
-
-          | ID | Component | Severity | Status | Owner |
-          |----|-----------|----------|--------|-------|
-          | | | | | |
-
-          ## 7. Action Items
-
-          | Action | Owner | Due Date | Status |
-          |--------|-------|----------|--------|
-          | | | | |
-
-          ---
-
-          *Auto-generated by [quarterly-security-audit](/.github/workflows/quarterly-security-audit.yml). Close this issue when the audit is complete.*
-          BODY
-          )"

.github/workflows/secret-scan.yml

@@ -1,136 +0,0 @@
-name: Secret Scan
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-
-permissions:
-  pull-requests: write
-  contents: read
-
-jobs:
-  scan:
-    name: Scan for secrets
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Fetch base branch
-        run: git fetch origin ${{ github.base_ref }}
-
-      - name: Scan diff for secrets
-        id: scan
-        run: |
-          set -euo pipefail
-
-          # Get only added lines from the diff (exclude deletions and context lines)
-          DIFF=$(git diff "origin/${{ github.base_ref }}"...HEAD -- \
-            ':!*.lock' ':!uv.lock' ':!package-lock.json' ':!yarn.lock' \
-            | grep '^+' | grep -v '^+++' || true)
-
-          FINDINGS=""
-          CRITICAL=false
-
-          check() {
-            local label="$1"
-            local pattern="$2"
-            local critical="${3:-false}"
-            local matches
-            matches=$(echo "$DIFF" | grep -oP "$pattern" || true)
-            if [ -n "$matches" ]; then
-              FINDINGS="${FINDINGS}\n- **${label}**: pattern matched"
-              if [ "$critical" = "true" ]; then
-                CRITICAL=true
-              fi
-            fi
-          }
-
-          # AWS keys — critical
-          check "AWS Access Key" 'AKIA[0-9A-Z]{16}' true
-
-          # Private key headers — critical
-          check "Private Key Header" '-----BEGIN (RSA|EC|DSA|OPENSSH|PGP) PRIVATE KEY' true
-
-          # OpenAI / Anthropic style keys
-          check "OpenAI-style API key (sk-)" 'sk-[a-zA-Z0-9]{20,}' false
-
-          # GitHub tokens
-          check "GitHub personal access token (ghp_)" 'ghp_[a-zA-Z0-9]{36}' true
-          check "GitHub fine-grained PAT (github_pat_)" 'github_pat_[a-zA-Z0-9_]{1,}' true
-
-          # Slack tokens
-          check "Slack bot token (xoxb-)" 'xoxb-[0-9A-Za-z\-]{10,}' true
-          check "Slack user token (xoxp-)" 'xoxp-[0-9A-Za-z\-]{10,}' true
-
-          # Generic assignment patterns — exclude obvious placeholders
-          GENERIC=$(echo "$DIFF" | grep -iP '(api_key|apikey|api-key|secret_key|access_token|auth_token)\s*[=:]\s*['"'"'"][^'"'"'"]{20,}['"'"'"]' \
-            | grep -ivP '(fake|mock|test|placeholder|example|dummy|your[_-]|xxx|<|>|\{\{)' || true)
-          if [ -n "$GENERIC" ]; then
-            FINDINGS="${FINDINGS}\n- **Generic credential assignment**: possible hardcoded secret"
-          fi
-
-          # .env additions with long values
-          ENV_DIFF=$(git diff "origin/${{ github.base_ref }}"...HEAD -- '*.env' '**/.env' '.env*' \
-            | grep '^+' | grep -v '^+++' || true)
-          ENV_MATCHES=$(echo "$ENV_DIFF" | grep -P '^[A-Z_]+=.{16,}' \
-            | grep -ivP '(fake|mock|test|placeholder|example|dummy|your[_-]|xxx)' || true)
-          if [ -n "$ENV_MATCHES" ]; then
-            FINDINGS="${FINDINGS}\n- **.env file**: lines with potentially real secret values detected"
-          fi
-
-          # Write outputs
-          if [ -n "$FINDINGS" ]; then
-            echo "found=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "found=false" >> "$GITHUB_OUTPUT"
-          fi
-
-          if [ "$CRITICAL" = "true" ]; then
-            echo "critical=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "critical=false" >> "$GITHUB_OUTPUT"
-          fi
-
-          # Store findings in a file to use in comment step
-          printf "%b" "$FINDINGS" > /tmp/secret-findings.txt
-
-      - name: Post PR comment with findings
-        if: steps.scan.outputs.found == 'true' && github.event_name == 'pull_request'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          FINDINGS=$(cat /tmp/secret-findings.txt)
-          SEVERITY="warning"
-          if [ "${{ steps.scan.outputs.critical }}" = "true" ]; then
-            SEVERITY="CRITICAL"
-          fi
-
-          BODY="## Secret Scan — ${SEVERITY} findings
-
-          The automated secret scanner detected potential secrets in the diff for this PR.
-
-          ### Findings
-          ${FINDINGS}
-
-          ### What to do
-          1. Remove any real credentials from the diff immediately.
-          2. If the match is a false positive (test fixture, placeholder), add a comment explaining why or rename the variable to include \`fake\`, \`mock\`, or \`test\`.
-          3. Rotate any exposed credentials regardless of whether this PR is merged.
-
-          ---
-          *Automated scan by [secret-scan](/.github/workflows/secret-scan.yml)*"
-
-          gh pr comment "${{ github.event.pull_request.number }}" --body "$BODY"
-
-      - name: Fail on critical secrets
-        if: steps.scan.outputs.critical == 'true'
-        run: |
-          echo "::error::Critical secrets detected in diff (private keys, AWS keys, or GitHub tokens). Remove them before merging."
-          exit 1
-
-      - name: Warn on non-critical findings
-        if: steps.scan.outputs.found == 'true' && steps.scan.outputs.critical == 'false'
-        run: |
-          echo "::warning::Potential secrets detected in diff. Review the PR comment for details."

.github/workflows/skills-index.yml

@@ -0,0 +1,101 @@
+name: Build Skills Index
+
+on:
+  schedule:
+    # Run twice daily: 6 AM and 6 PM UTC
+    - cron: '0 6,18 * * *'
+  workflow_dispatch:  # Manual trigger
+  push:
+    branches: [main]
+    paths:
+      - 'scripts/build_skills_index.py'
+      - '.github/workflows/skills-index.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  build-index:
+    # Only run on the upstream repository, not on forks
+    if: github.repository == 'NousResearch/hermes-agent'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install httpx==0.28.1 pyyaml==6.0.2
+
+      - name: Build skills index
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: python scripts/build_skills_index.py
+
+      - name: Upload index artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: skills-index
+          path: website/static/api/skills-index.json
+          retention-days: 7
+
+  deploy-with-index:
+    needs: build-index
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    # Only deploy on schedule or manual trigger (not on every push to the script)
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: skills-index
+          path: website/static/api/
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: '3.11'
+
+      - name: Install PyYAML for skill extraction
+        run: pip install pyyaml==6.0.2
+
+      - name: Extract skill metadata for dashboard
+        run: python3 website/scripts/extract-skills.py
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: website
+
+      - name: Build Docusaurus
+        run: npm run build
+        working-directory: website
+
+      - name: Stage deployment
+        run: |
+          mkdir -p _site/docs
+          cp -r landingpage/* _site/
+          cp -r website/build/* _site/docs/
+          echo "hermes-agent.nousresearch.com" > _site/CNAME
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa  # v3
+        with:
+          path: _site
+
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e  # v4

.github/workflows/supply-chain-audit.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
         with:
           fetch-depth: 0
 
@@ -149,6 +149,62 @@ jobs:
           "
           fi
 
+          # --- CI/CD workflow files modified ---
+          WORKFLOW_HITS=$(git diff --name-only "$BASE".."$HEAD" | grep -E '\.github/workflows/.*\.ya?ml$' || true)
+          if [ -n "$WORKFLOW_HITS" ]; then
+            FINDINGS="${FINDINGS}
+          ### ⚠️ WARNING: CI/CD workflow files modified
+          Changes to workflow files can alter build pipelines, inject steps, or modify permissions. Verify no unauthorized actions or secrets access were added.
+
+          **Files:**
+          \`\`\`
+          ${WORKFLOW_HITS}
+          \`\`\`
+          "
+          fi
+
+          # --- Dockerfile / container build files modified ---
+          DOCKER_HITS=$(git diff --name-only "$BASE".."$HEAD" | grep -iE '(Dockerfile|\.dockerignore|docker-compose)' || true)
+          if [ -n "$DOCKER_HITS" ]; then
+            FINDINGS="${FINDINGS}
+          ### ⚠️ WARNING: Container build files modified
+          Changes to Dockerfiles or compose files can alter base images, add build steps, or expose ports. Verify base image pins and build commands.
+
+          **Files:**
+          \`\`\`
+          ${DOCKER_HITS}
+          \`\`\`
+          "
+          fi
+
+          # --- Dependency manifest files modified ---
+          DEP_HITS=$(git diff --name-only "$BASE".."$HEAD" | grep -E '(pyproject\.toml|requirements.*\.txt|package\.json|Gemfile|go\.mod|Cargo\.toml)$' || true)
+          if [ -n "$DEP_HITS" ]; then
+            FINDINGS="${FINDINGS}
+          ### ⚠️ WARNING: Dependency manifest files modified
+          Changes to dependency files can introduce new packages or change version pins. Verify all dependency changes are intentional and from trusted sources.
+
+          **Files:**
+          \`\`\`
+          ${DEP_HITS}
+          \`\`\`
+          "
+          fi
+
+          # --- GitHub Actions version unpinning (mutable tags instead of SHAs) ---
+          ACTIONS_UNPIN=$(echo "$DIFF" | grep -n '^\+' | grep 'uses:' | grep -v '#' | grep -E '@v[0-9]' | head -10 || true)
+          if [ -n "$ACTIONS_UNPIN" ]; then
+            FINDINGS="${FINDINGS}
+          ### ⚠️ WARNING: GitHub Actions with mutable version tags
+          Actions should be pinned to full commit SHAs (not \`@v4\`, \`@v5\`). Mutable tags can be retargeted silently if a maintainer account is compromised.
+
+          **Matches:**
+          \`\`\`
+          ${ACTIONS_UNPIN}
+          \`\`\`
+          "
+          fi
+
           # --- Output results ---
           if [ -n "$FINDINGS" ]; then
             echo "found=true" >> "$GITHUB_OUTPUT"
@@ -183,7 +239,7 @@ jobs:
           ---
           *Automated scan triggered by [supply-chain-audit](/.github/workflows/supply-chain-audit.yml). If this is a false positive, a maintainer can approve after manual review.*"
 
-          gh pr comment "${{ github.event.pull_request.number }}" --body "$BODY"
+          gh pr comment "${{ github.event.pull_request.number }}" --body "$BODY" || echo "::warning::Could not post PR comment (expected for fork PRs — GITHUB_TOKEN is read-only)"
 
       - name: Fail on critical findings
         if: steps.scan.outputs.critical == 'true'

.github/workflows/tests.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 # Cancel in-progress runs for the same PR/branch
 concurrency:
   group: tests-${{ github.ref }}
@@ -17,10 +20,17 @@ jobs:
     timeout-minutes: 10
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y ripgrep
+
+      - name: Check for hardcoded paths
+        run: python3 scripts/lint_hardcoded_paths.py || true
+        continue-on-error: true
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86  # v5
 
       - name: Set up Python 3.11
         run: uv python install 3.11
@@ -34,9 +44,37 @@ jobs:
       - name: Run tests
         run: |
           source .venv/bin/activate
-          python -m pytest tests/ -q --ignore=tests/integration --tb=short -n auto
+          python -m pytest tests/ -q --ignore=tests/integration --ignore=tests/e2e --tb=short -n auto
         env:
           # Ensure tests don't accidentally call real APIs
           OPENROUTER_API_KEY: ""
           OPENAI_API_KEY: ""
           NOUS_API_KEY: ""
+
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86  # v5
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: |
+          uv venv .venv --python 3.11
+          source .venv/bin/activate
+          uv pip install -e ".[all,dev]"
+
+      - name: Run e2e tests
+        run: |
+          source .venv/bin/activate
+          python -m pytest tests/e2e/ -v --tb=short
+        env:
+          OPENROUTER_API_KEY: ""
+          OPENAI_API_KEY: ""
+          NOUS_API_KEY: ""

.gitignore

@@ -51,6 +51,9 @@ ignored/
 .worktrees/
 environments/benchmarks/evals/
 
+# Web UI build output
+hermes_cli/web_dist/
+
 # Release script temp files
 .release_notes.md
 mini-swe-agent/
@@ -58,3 +61,4 @@ mini-swe-agent/
 # Nix
 .direnv/
 result
+website/static/api/skills-index.json

.mailmap

@@ -0,0 +1,107 @@
+# .mailmap — canonical author mapping for git shortlog / git log / GitHub
+# Format: Canonical Name <canonical@email> <commit@email>
+# See: https://git-scm.com/docs/gitmailmap
+#
+# This maps commit emails to GitHub noreply addresses so that:
+# 1. `git shortlog -sn` shows deduplicated contributor counts
+# 2. GitHub's contributor graph can attribute commits correctly
+# 3. Contributors with personal/work emails get proper credit
+#
+# When adding entries: use the contributor's GitHub noreply email as canonical
+# so GitHub can link commits to their profile.
+
+# === Teknium (multiple emails) ===
+Teknium <127238744+teknium1@users.noreply.github.com> <teknium1@gmail.com>
+Teknium <127238744+teknium1@users.noreply.github.com> <teknium@nousresearch.com>
+
+# === Contributors — personal/work emails mapped to GitHub noreply ===
+# Format: Canonical Name <GH-noreply> <commit-email>
+
+# Verified via GH API email search
+luyao618 <364939526@qq.com> <364939526@qq.com>
+ethernet8023 <arilotter@gmail.com> <arilotter@gmail.com>
+nicoloboschi <boschi1997@gmail.com> <boschi1997@gmail.com>
+cherifya <chef.ya@gmail.com> <chef.ya@gmail.com>
+BongSuCHOI <chlqhdtn98@gmail.com> <chlqhdtn98@gmail.com>
+dsocolobsky <dsocolobsky@gmail.com> <dsocolobsky@gmail.com>
+pefontana <fontana.pedro93@gmail.com> <fontana.pedro93@gmail.com>
+Helmi <frank@helmschrott.de> <frank@helmschrott.de>
+hata1234 <hata1234@gmail.com> <hata1234@gmail.com>
+
+# Verified via PR investigation / salvage PR bodies
+DeployFaith <agents@kylefrench.dev> <agents@kylefrench.dev>
+flobo3 <floptopbot33@gmail.com> <floptopbot33@gmail.com>
+gaixianggeng <gaixg94@gmail.com> <gaixg94@gmail.com>
+KUSH42 <xush@xush.org> <xush@xush.org>
+konsisumer <der@konsi.org> <der@konsi.org>
+WorldInnovationsDepartment <vorvul.danylo@gmail.com> <vorvul.danylo@gmail.com>
+m0n5t3r <iacobs@m0n5t3r.info> <iacobs@m0n5t3r.info>
+sprmn24 <oncuevtv@gmail.com> <oncuevtv@gmail.com>
+fancydirty <fancydirty@gmail.com> <fancydirty@gmail.com>
+fxfitz <francis.x.fitzpatrick@gmail.com> <francis.x.fitzpatrick@gmail.com>
+limars874 <limars874@gmail.com> <limars874@gmail.com>
+AaronWong1999 <aaronwong1999@icloud.com> <aaronwong1999@icloud.com>
+dippwho <dipp.who@gmail.com> <dipp.who@gmail.com>
+duerzy <duerzy@gmail.com> <duerzy@gmail.com>
+geoffwellman <geoff.wellman@gmail.com> <geoff.wellman@gmail.com>
+hcshen0111 <shenhaocheng19990111@gmail.com> <shenhaocheng19990111@gmail.com>
+jamesarch <han.shan@live.cn> <han.shan@live.cn>
+stephenschoettler <stephenschoettler@gmail.com> <stephenschoettler@gmail.com>
+Tranquil-Flow <tranquil_flow@protonmail.com> <tranquil_flow@protonmail.com>
+Dusk1e <yusufalweshdemir@gmail.com> <yusufalweshdemir@gmail.com>
+Awsh1 <ysfalweshcan@gmail.com> <ysfalweshcan@gmail.com>
+WAXLYY <ysfwaxlycan@gmail.com> <ysfwaxlycan@gmail.com>
+donrhmexe <don.rhm@gmail.com> <don.rhm@gmail.com>
+hqhq1025 <1506751656@qq.com> <1506751656@qq.com>
+BlackishGreen33 <s5460703@gmail.com> <s5460703@gmail.com>
+tomqiaozc <zqiao@microsoft.com> <zqiao@microsoft.com>
+MagicRay1217 <mingjwan@microsoft.com> <mingjwan@microsoft.com>
+aaronagent <1115117931@qq.com> <1115117931@qq.com>
+YoungYang963 <young@YoungdeMacBook-Pro.local> <young@YoungdeMacBook-Pro.local>
+LongOddCode <haolong@microsoft.com> <haolong@microsoft.com>
+Cafexss <coffeemjj@gmail.com> <coffeemjj@gmail.com>
+Cygra <sjtuwbh@gmail.com> <sjtuwbh@gmail.com>
+DomGrieco <dgrieco@redhat.com> <dgrieco@redhat.com>
+
+# Duplicate email mapping (same person, multiple emails)
+Sertug17 <104278804+Sertug17@users.noreply.github.com> <srhtsrht17@gmail.com>
+yyovil <birdiegyal@gmail.com> <tanishq231003@gmail.com>
+DomGrieco <dgrieco@redhat.com> <dgrieco@redhat.com>
+dsocolobsky <dsocolobsky@gmail.com> <dylan.socolobsky@lambdaclass.com>
+olafthiele <programming@olafthiele.com> <olafthiele@gmail.com>
+
+# Verified via git display name matching GH contributor username
+cokemine <aptx4561@gmail.com> <aptx4561@gmail.com>
+dalianmao000 <dalianmao0107@gmail.com> <dalianmao0107@gmail.com>
+emozilla <emozilla@nousresearch.com> <emozilla@nousresearch.com>
+jjovalle99 <juan.ovalle@mistral.ai> <juan.ovalle@mistral.ai>
+kagura-agent <kagura.chen28@gmail.com> <kagura.chen28@gmail.com>
+spniyant <niyant@spicefi.xyz> <niyant@spicefi.xyz>
+olafthiele <programming@olafthiele.com> <programming@olafthiele.com>
+r266-tech <r2668940489@gmail.com> <r2668940489@gmail.com>
+xingkongliang <tianliangjay@gmail.com> <tianliangjay@gmail.com>
+win4r <win4r@outlook.com> <win4r@outlook.com>
+zhouboli <zhouboli@gmail.com> <zhouboli@gmail.com>
+yongtenglei <yongtenglei@gmail.com> <yongtenglei@gmail.com>
+
+# Nous Research team
+benbarclay <ben@nousresearch.com> <ben@nousresearch.com>
+jquesnelle <jonny@nousresearch.com> <jonny@nousresearch.com>
+
+# GH contributor list verified
+spideystreet <dhicham.pro@gmail.com> <dhicham.pro@gmail.com>
+dorukardahan <dorukardahan@hotmail.com> <dorukardahan@hotmail.com>
+MustafaKara7 <karamusti912@gmail.com> <karamusti912@gmail.com>
+Hmbown <hmbown@gmail.com> <hmbown@gmail.com>
+kamil-gwozdz <kamil@gwozdz.me> <kamil@gwozdz.me>
+kira-ariaki <kira@ariaki.me> <kira@ariaki.me>
+knopki <knopki@duck.com> <knopki@duck.com>
+Unayung <unayung@gmail.com> <unayung@gmail.com>
+SeeYangZhi <yangzhi.see@gmail.com> <yangzhi.see@gmail.com>
+Julientalbot <julien.talbot@ergonomia.re> <julien.talbot@ergonomia.re>
+lesterli <lisicheng168@gmail.com> <lisicheng168@gmail.com>
+JiayuuWang <jiayuw794@gmail.com> <jiayuw794@gmail.com>
+tesseracttars-creator <tesseracttars@gmail.com> <tesseracttars@gmail.com>
+xinbenlv <zzn+pa@zzn.im> <zzn+pa@zzn.im>
+SaulJWu <saul.jj.wu@gmail.com> <saul.jj.wu@gmail.com>
+angelos <angelos@oikos.lan.home.malaiwah.com> <angelos@oikos.lan.home.malaiwah.com>

.pre-commit-config.yaml

@@ -1,25 +0,0 @@
-repos:
-  # Secret detection
-  - repo: https://github.com/gitleaks/gitleaks
-    rev: v8.21.2
-    hooks:
-      - id: gitleaks
-        name: Detect secrets with gitleaks
-        description: Detect hardcoded secrets, API keys, and credentials
-
-  # Basic security hygiene
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
-    hooks:
-      - id: check-added-large-files
-        args: ['--maxkb=500']
-      - id: detect-private-key
-        name: Detect private keys
-      - id: check-merge-conflict
-      - id: check-yaml
-      - id: check-toml
-      - id: end-of-file-fixer
-      - id: trailing-whitespace
-        args: ['--markdown-linebreak-ext=md']
-      - id: no-commit-to-branch
-        args: ['--branch', 'main']

AGENTS.md

@@ -13,7 +13,7 @@ source venv/bin/activate  # ALWAYS activate before running Python
 ```
 hermes-agent/
 ├── run_agent.py          # AIAgent class — core conversation loop
-├── model_tools.py        # Tool orchestration, _discover_tools(), handle_function_call()
+├── model_tools.py        # Tool orchestration, discover_builtin_tools(), handle_function_call()
 ├── toolsets.py           # Toolset definitions, _HERMES_CORE_TOOLS list
 ├── cli.py                # HermesCLI class — interactive CLI orchestrator
 ├── hermes_state.py       # SessionDB — SQLite session store (FTS5 search)
@@ -55,7 +55,7 @@ hermes-agent/
 ├── gateway/              # Messaging platform gateway
 │   ├── run.py            # Main loop, slash commands, message dispatch
 │   ├── session.py        # SessionStore — conversation persistence
-│   └── platforms/        # Adapters: telegram, discord, slack, whatsapp, homeassistant, signal
+│   └── platforms/        # Adapters: telegram, discord, slack, whatsapp, homeassistant, signal, qqbot
 ├── acp_adapter/          # ACP server (VS Code / Zed / JetBrains integration)
 ├── cron/                 # Scheduler (jobs.py, scheduler.py)
 ├── environments/         # RL training environments (Atropos)
@@ -181,7 +181,7 @@ if canonical == "mycommand":
 
 ## Adding New Tools
 
-Requires changes in **3 files**:
+Requires changes in **2 files**:
 
 **1. Create `tools/your_tool.py`:**
 ```python
@@ -204,9 +204,9 @@ registry.register(
 )
 ```
 
-**2. Add import** in `model_tools.py` `_discover_tools()` list.
+**2. Add to `toolsets.py`** — either `_HERMES_CORE_TOOLS` (all platforms) or a new toolset.
 
-**3. Add to `toolsets.py`** — either `_HERMES_CORE_TOOLS` (all platforms) or a new toolset.
+Auto-discovery: any `tools/*.py` file with a top-level `registry.register()` call is imported automatically — no manual import list to maintain.
 
 The registry handles schema collection, dispatch, availability checking, and error wrapping. All handlers MUST return a JSON string.
 
@@ -351,8 +351,9 @@ Cache-breaking forces dramatically higher costs. The ONLY time we alter context
 
 ### Background Process Notifications (Gateway)
 
-When `terminal(background=true, check_interval=...)` is used, the gateway runs a watcher that
-pushes status updates to the user's chat. Control verbosity with `display.background_process_notifications`
+When `terminal(background=true, notify_on_complete=true)` is used, the gateway runs a watcher that
+detects process completion and triggers a new agent turn. Control verbosity of background process
+messages with `display.background_process_notifications`
 in config.yaml (or `HERMES_BACKGROUND_NOTIFICATIONS` env var):
 
 - `all` — running-output updates + final message (default)

DEPLOY.md

@@ -1,569 +0,0 @@
-# Hermes Agent — Sovereign Deployment Runbook
-
-> **Goal**: A new VPS can go from bare OS to a running Hermes instance in under 30 minutes using only this document.
-
----
-
-## Table of Contents
-
-1. [Prerequisites](#1-prerequisites)
-2. [Environment Setup](#2-environment-setup)
-3. [Secret Injection](#3-secret-injection)
-4. [Installation](#4-installation)
-5. [Starting the Stack](#5-starting-the-stack)
-6. [Health Checks](#6-health-checks)
-7. [Stop / Restart Procedures](#7-stop--restart-procedures)
-8. [Zero-Downtime Restart](#8-zero-downtime-restart)
-9. [Rollback Procedure](#9-rollback-procedure)
-10. [Database / State Migrations](#10-database--state-migrations)
-11. [Docker Compose Deployment](#11-docker-compose-deployment)
-12. [systemd Deployment](#12-systemd-deployment)
-13. [Monitoring & Logs](#13-monitoring--logs)
-14. [Security Checklist](#14-security-checklist)
-15. [Troubleshooting](#15-troubleshooting)
-
----
-
-## 1. Prerequisites
-
-| Requirement | Minimum | Recommended |
-|-------------|---------|-------------|
-| OS | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS |
-| RAM | 512 MB | 2 GB |
-| CPU | 1 vCPU | 2 vCPU |
-| Disk | 5 GB | 20 GB |
-| Python | 3.11 | 3.12 |
-| Node.js | 18 | 20 |
-| Git | any | any |
-
-**Optional but recommended:**
-- Docker Engine ≥ 24 + Compose plugin (for containerised deployment)
-- `curl`, `jq` (for health-check scripting)
-
----
-
-## 2. Environment Setup
-
-### 2a. Create a dedicated system user (bare-metal deployments)
-
-```bash
-sudo useradd -m -s /bin/bash hermes
-sudo su - hermes
-```
-
-### 2b. Install Hermes
-
-```bash
-# Official one-liner installer
-curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
-
-# Reload PATH so `hermes` is available
-source ~/.bashrc
-```
-
-The installer places:
-- The agent code at `~/.local/lib/python3.x/site-packages/` (pip editable install)
-- The `hermes` entry point at `~/.local/bin/hermes`
-- Default config directory at `~/.hermes/`
-
-### 2c. Verify installation
-
-```bash
-hermes --version
-hermes doctor
-```
-
----
-
-## 3. Secret Injection
-
-**Rule: secrets never live in the repository. They live only in `~/.hermes/.env`.**
-
-```bash
-# Copy the template (do NOT edit the repo copy)
-cp /path/to/hermes-agent/.env.example ~/.hermes/.env
-chmod 600 ~/.hermes/.env
-
-# Edit with your preferred editor
-nano ~/.hermes/.env
-```
-
-### Minimum required keys
-
-| Variable | Purpose | Where to get it |
-|----------|---------|----------------|
-| `OPENROUTER_API_KEY` | LLM inference | https://openrouter.ai/keys |
-| `TELEGRAM_BOT_TOKEN` | Telegram gateway | @BotFather on Telegram |
-
-### Optional but common keys
-
-| Variable | Purpose |
-|----------|---------|
-| `DISCORD_BOT_TOKEN` | Discord gateway |
-| `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` | Slack gateway |
-| `EXA_API_KEY` | Web search tool |
-| `FAL_KEY` | Image generation |
-| `ANTHROPIC_API_KEY` | Direct Anthropic inference |
-
-### Pre-flight validation
-
-Before starting the stack, run:
-
-```bash
-python scripts/deploy-validate --check-ports --skip-health
-```
-
-This catches missing keys, placeholder values, and misconfigurations without touching running services.
-
----
-
-## 4. Installation
-
-### 4a. Clone the repository (if not using the installer)
-
-```bash
-git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent.git
-cd hermes-agent
-pip install -e ".[all]" --user
-npm install
-```
-
-### 4b. Run the setup wizard
-
-```bash
-hermes setup
-```
-
-The wizard configures your LLM provider, messaging platforms, and data directory interactively.
-
----
-
-## 5. Starting the Stack
-
-### Bare-metal (foreground — useful for first run)
-
-```bash
-# Agent + gateway combined
-hermes gateway start
-
-# Or just the CLI agent (no messaging)
-hermes
-```
-
-### Bare-metal (background daemon)
-
-```bash
-hermes gateway start &
-echo $! > ~/.hermes/gateway.pid
-```
-
-### Via systemd (recommended for production)
-
-See [Section 12](#12-systemd-deployment).
-
-### Via Docker Compose
-
-See [Section 11](#11-docker-compose-deployment).
-
----
-
-## 6. Health Checks
-
-### 6a. API server liveness probe
-
-The API server (enabled via `api_server` platform in gateway config) exposes `/health`:
-
-```bash
-curl -s http://127.0.0.1:8642/health | jq .
-```
-
-Expected response:
-
-```json
-{
-  "status": "ok",
-  "platform": "hermes-agent",
-  "version": "0.5.0",
-  "uptime_seconds": 123,
-  "gateway_state": "running",
-  "platforms": {
-    "telegram": {"state": "connected"},
-    "discord":  {"state": "connected"}
-  }
-}
-```
-
-| Field | Meaning |
-|-------|---------|
-| `status` | `"ok"` — HTTP server is alive. Any non-200 = down. |
-| `gateway_state` | `"running"` — all platforms started. `"starting"` — still initialising. |
-| `platforms` | Per-adapter connection state. |
-
-### 6b. Gateway runtime status file
-
-```bash
-cat ~/.hermes/gateway_state.json | jq '{state: .gateway_state, platforms: .platforms}'
-```
-
-### 6c. Deploy-validate script
-
-```bash
-python scripts/deploy-validate
-```
-
-Runs all checks and prints a pass/fail summary. Exit code 0 = healthy.
-
-### 6d. systemd health
-
-```bash
-systemctl status hermes-gateway
-journalctl -u hermes-gateway --since "5 minutes ago"
-```
-
----
-
-## 7. Stop / Restart Procedures
-
-### Graceful stop
-
-```bash
-# systemd
-sudo systemctl stop hermes-gateway
-
-# Docker Compose
-docker compose -f deploy/docker-compose.yml down
-
-# Process signal (if running ad-hoc)
-kill -TERM $(cat ~/.hermes/gateway.pid)
-```
-
-### Restart
-
-```bash
-# systemd
-sudo systemctl restart hermes-gateway
-
-# Docker Compose
-docker compose -f deploy/docker-compose.yml restart hermes
-
-# Ad-hoc
-hermes gateway start --replace
-```
-
-The `--replace` flag removes stale PID/lock files from an unclean shutdown before starting.
-
----
-
-## 8. Zero-Downtime Restart
-
-Hermes is a stateful long-running process (persistent sessions, active cron jobs). True zero-downtime requires careful sequencing.
-
-### Strategy A — systemd rolling restart (recommended)
-
-systemd's `Restart=on-failure` with a 5-second back-off ensures automatic recovery from crashes. For intentional restarts, use:
-
-```bash
-sudo systemctl reload-or-restart hermes-gateway
-```
-
-`hermes-gateway.service` uses `TimeoutStopSec=30` so in-flight agent turns finish before the old process dies.
-
-> **Note:** Active messaging conversations will see a brief pause (< 30 s) while the gateway reconnects to platforms. The session store is file-based and persists across restarts — conversations resume where they left off.
-
-### Strategy B — Blue/green with two HERMES_HOME directories
-
-For zero-downtime where even a brief pause is unacceptable:
-
-```bash
-# 1. Prepare the new environment (different HERMES_HOME)
-export HERMES_HOME=/home/hermes/.hermes-green
-hermes setup   # configure green env with same .env
-
-# 2. Start green on a different port (e.g. 8643)
-API_SERVER_PORT=8643 hermes gateway start &
-
-# 3. Verify green is healthy
-curl -s http://127.0.0.1:8643/health | jq .gateway_state
-
-# 4. Switch load balancer (nginx/caddy) to port 8643
-
-# 5. Gracefully stop blue
-kill -TERM $(cat ~/.hermes/.hermes/gateway.pid)
-```
-
-### Strategy C — Docker Compose rolling update
-
-```bash
-# Pull the new image
-docker compose -f deploy/docker-compose.yml pull hermes
-
-# Recreate with zero-downtime if you have a replicated setup
-docker compose -f deploy/docker-compose.yml up -d --no-deps hermes
-```
-
-Docker stops the old container only after the new one passes its healthcheck.
-
----
-
-## 9. Rollback Procedure
-
-### 9a. Code rollback (pip install)
-
-```bash
-# Find the previous version tag
-git log --oneline --tags | head -10
-
-# Roll back to a specific tag
-git checkout v0.4.0
-pip install -e ".[all]" --user --quiet
-
-# Restart the gateway
-sudo systemctl restart hermes-gateway
-```
-
-### 9b. Docker image rollback
-
-```bash
-# Pull a specific version
-docker pull ghcr.io/nousresearch/hermes-agent:v0.4.0
-
-# Update docker-compose.yml image tag, then:
-docker compose -f deploy/docker-compose.yml up -d
-```
-
-### 9c. State / data rollback
-
-The data directory (`~/.hermes/` or the Docker volume `hermes_data`) contains sessions, memories, cron jobs, and the response store. Back it up before every update:
-
-```bash
-# Backup (run BEFORE updating)
-tar czf ~/backups/hermes_data_$(date +%F_%H%M).tar.gz ~/.hermes/
-
-# Restore from backup
-sudo systemctl stop hermes-gateway
-rm -rf ~/.hermes/
-tar xzf ~/backups/hermes_data_2026-04-06_1200.tar.gz -C ~/
-sudo systemctl start hermes-gateway
-```
-
-> **Tested rollback**: The rollback procedure above was validated in staging on 2026-04-06. Data integrity was confirmed by checking session count before/after: `ls ~/.hermes/sessions/ | wc -l`.
-
----
-
-## 10. Database / State Migrations
-
-Hermes uses two persistent stores:
-
-| Store | Location | Format |
-|-------|----------|--------|
-| Session store | `~/.hermes/sessions/*.json` | JSON files |
-| Response store (API server) | `~/.hermes/response_store.db` | SQLite WAL |
-| Gateway state | `~/.hermes/gateway_state.json` | JSON |
-| Memories | `~/.hermes/memories/*.md` | Markdown files |
-| Cron jobs | `~/.hermes/cron/*.json` | JSON files |
-
-### Migration steps (between versions)
-
-1. **Stop** the gateway before migrating.
-2. **Backup** the data directory (see Section 9c).
-3. **Check release notes** for migration instructions (see `RELEASE_*.md`).
-4. **Run** `hermes doctor` after starting the new version — it validates state compatibility.
-5. **Verify** health via `python scripts/deploy-validate`.
-
-There are currently no SQL migrations to run manually. The SQLite schema is
-created automatically on first use with `CREATE TABLE IF NOT EXISTS`.
-
----
-
-## 11. Docker Compose Deployment
-
-### First-time setup
-
-```bash
-# 1. Copy .env.example to .env in the repo root
-cp .env.example .env
-nano .env   # fill in your API keys
-
-# 2. Validate config before starting
-python scripts/deploy-validate --skip-health
-
-# 3. Start the stack
-docker compose -f deploy/docker-compose.yml up -d
-
-# 4. Watch startup logs
-docker compose -f deploy/docker-compose.yml logs -f
-
-# 5. Verify health
-curl -s http://127.0.0.1:8642/health | jq .
-```
-
-### Updating to a new version
-
-```bash
-# Pull latest image
-docker compose -f deploy/docker-compose.yml pull
-
-# Recreate container (Docker waits for healthcheck before stopping old)
-docker compose -f deploy/docker-compose.yml up -d
-
-# Watch logs
-docker compose -f deploy/docker-compose.yml logs -f --since 2m
-```
-
-### Data backup (Docker)
-
-```bash
-docker run --rm \
-  -v hermes_data:/data \
-  -v $(pwd)/backups:/backup \
-  alpine tar czf /backup/hermes_data_$(date +%F).tar.gz /data
-```
-
----
-
-## 12. systemd Deployment
-
-### Install unit files
-
-```bash
-# From the repo root
-sudo cp deploy/hermes-agent.service  /etc/systemd/system/
-sudo cp deploy/hermes-gateway.service /etc/systemd/system/
-
-sudo systemctl daemon-reload
-
-# Enable on boot + start now
-sudo systemctl enable --now hermes-gateway
-
-# (Optional) also run the CLI agent as a background service
-# sudo systemctl enable --now hermes-agent
-```
-
-### Adjust the unit file for your user/paths
-
-Edit `/etc/systemd/system/hermes-gateway.service`:
-
-```ini
-[Service]
-User=youruser          # change from 'hermes'
-WorkingDirectory=/home/youruser
-EnvironmentFile=/home/youruser/.hermes/.env
-ExecStart=/home/youruser/.local/bin/hermes gateway start --replace
-```
-
-Then:
-
-```bash
-sudo systemctl daemon-reload
-sudo systemctl restart hermes-gateway
-```
-
-### Verify
-
-```bash
-systemctl status hermes-gateway
-journalctl -u hermes-gateway -f
-```
-
----
-
-## 13. Monitoring & Logs
-
-### Log locations
-
-| Log | Location |
-|-----|----------|
-| Gateway (systemd) | `journalctl -u hermes-gateway` |
-| Gateway (Docker) | `docker compose logs hermes` |
-| Session trajectories | `~/.hermes/logs/session_*.json` |
-| Deploy events | `~/.hermes/logs/deploy.log` |
-| Runtime state | `~/.hermes/gateway_state.json` |
-
-### Useful log commands
-
-```bash
-# Last 100 lines, follow
-journalctl -u hermes-gateway -n 100 -f
-
-# Errors only
-journalctl -u hermes-gateway -p err --since today
-
-# Docker: structured logs with timestamps
-docker compose -f deploy/docker-compose.yml logs --timestamps hermes
-```
-
-### Alerting
-
-Add a cron job on the host to page you if the health check fails:
-
-```bash
-# /etc/cron.d/hermes-healthcheck
-* * * * * root curl -sf http://127.0.0.1:8642/health > /dev/null || \
-  echo "Hermes unhealthy at $(date)" | mail -s "ALERT: Hermes down" ops@example.com
-```
-
----
-
-## 14. Security Checklist
-
-- [ ] `.env` has permissions `600` and is **not** tracked by git (`git ls-files .env` returns nothing).
-- [ ] `API_SERVER_KEY` is set if the API server is exposed beyond `127.0.0.1`.
-- [ ] API server is bound to `127.0.0.1` (not `0.0.0.0`) unless behind a TLS-terminating reverse proxy.
-- [ ] Firewall allows only the ports your platforms require (no unnecessary open ports).
-- [ ] systemd unit uses `NoNewPrivileges=true`, `PrivateTmp=true`, `ProtectSystem=strict`.
-- [ ] Docker container has resource limits set (`deploy.resources.limits`).
-- [ ] Backups of `~/.hermes/` are stored outside the server (e.g. S3, remote NAS).
-- [ ] `hermes doctor` returns no errors on the running instance.
-- [ ] `python scripts/deploy-validate` exits 0 after every configuration change.
-
----
-
-## 15. Troubleshooting
-
-### Gateway won't start
-
-```bash
-hermes gateway start --replace   # clears stale PID files
-
-# Check for port conflicts
-ss -tlnp | grep 8642
-
-# Verbose logs
-HERMES_LOG_LEVEL=DEBUG hermes gateway start
-```
-
-### Health check returns `gateway_state: "starting"` for more than 60 s
-
-Platform adapters take time to authenticate (especially Telegram + Discord). Check logs for auth errors:
-
-```bash
-journalctl -u hermes-gateway --since "2 minutes ago" | grep -i "error\|token\|auth"
-```
-
-### `/health` returns connection refused
-
-The API server platform may not be enabled. Verify your gateway config (`~/.hermes/config.yaml`) includes:
-
-```yaml
-gateway:
-  platforms:
-    - api_server
-```
-
-### Rollback needed after failed update
-
-See [Section 9](#9-rollback-procedure). If you backed up before updating, rollback takes < 5 minutes.
-
-### Sessions lost after restart
-
-Sessions are file-based in `~/.hermes/sessions/`. They persist across restarts. If they are gone, check:
-
-```bash
-ls -la ~/.hermes/sessions/
-# Verify the volume is mounted (Docker):
-docker exec hermes-agent ls /opt/data/sessions/
-```
-
----
-
-*This runbook is owned by the Bezalel epic backlog. Update it whenever deployment procedures change.*

Dockerfile

@@ -1,20 +1,46 @@
+FROM ghcr.io/astral-sh/uv:0.11.6-python3.13-trixie@sha256:b3c543b6c4f23a5f2df22866bd7857e5d304b67a564f4feab6ac22044dde719b AS uv_source
+FROM tianon/gosu:1.19-trixie@sha256:3b176695959c71e123eb390d427efc665eeb561b1540e82679c15e992006b8b9 AS gosu_source
 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
+# Disable Python stdout buffering to ensure logs are printed immediately
+ENV PYTHONUNBUFFERED=1
+
+# Store Playwright browsers outside the volume mount so the build-time
+# install survives the /opt/data volume overlay at runtime.
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/hermes/.playwright
+
+# Install system dependencies in one layer, clear APT cache
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        build-essential nodejs npm python3 ripgrep ffmpeg gcc python3-dev libffi-dev procps git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Non-root user for runtime; UID can be overridden via HERMES_UID at runtime
+RUN useradd -u 10000 -m -d /opt/data hermes
+
+COPY --chmod=0755 --from=gosu_source /gosu /usr/local/bin/
+COPY --chmod=0755 --from=uv_source /usr/local/bin/uv /usr/local/bin/uvx /usr/local/bin/
 
 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
+# Install Node dependencies and Playwright as root (--with-deps needs apt)
+RUN npm install --prefer-offline --no-audit && \
+    npx playwright install --with-deps chromium --only-shell && \
+    cd /opt/hermes/scripts/whatsapp-bridge && \
+    npm install --prefer-offline --no-audit && \
+    npm cache clean --force
 
-WORKDIR /opt/hermes
+# Hand ownership to hermes user, then install Python deps in a virtualenv
+RUN chown -R hermes:hermes /opt/hermes
+USER hermes
+
+RUN uv venv && \
+    uv pip install --no-cache-dir -e ".[all]"
+
+USER root
 RUN chmod +x /opt/hermes/docker/entrypoint.sh
 
 ENV HERMES_HOME=/opt/data
 VOLUME [ "/opt/data" ]
-ENTRYPOINT [ "/opt/hermes/docker/entrypoint.sh" ]
+ENTRYPOINT [ "/opt/hermes/docker/entrypoint.sh" ]

MANIFEST.in

@@ -0,0 +1,4 @@
+graft skills
+graft optional-skills
+global-exclude __pycache__
+global-exclude *.py[cod]

PERFORMANCE_ANALYSIS_REPORT.md

@@ -1,589 +0,0 @@
-# Hermes Agent Performance Analysis Report
-
-**Date:** 2025-03-30  
-**Scope:** Entire codebase - run_agent.py, gateway, tools  
-**Lines Analyzed:** 50,000+ lines of Python code  
-
----
-
-## Executive Summary
-
-The codebase exhibits **severe performance bottlenecks** across multiple dimensions. The monolithic architecture, excessive synchronous I/O, lack of caching, and inefficient algorithms result in significant performance degradation under load.
-
-**Critical Issues Found:**
-- 113 lock primitives (potential contention points)
-- 482 sleep calls (blocking delays)
-- 1,516 JSON serialization calls (CPU overhead)
-- 8,317-line run_agent.py (unmaintainable, slow import)
-- Synchronous HTTP requests in async contexts
-
----
-
-## 1. HOTSPOT ANALYSIS (Slowest Code Paths)
-
-### 1.1 run_agent.py - The Monolithic Bottleneck
-
-**File Size:** 8,317 lines, 419KB  
-**Severity:** CRITICAL
-
-**Issues:**
-```python
-# Lines 460-1000: Massive __init__ method with 50+ parameters
-# Lines 3759-3826: _anthropic_messages_create - blocking API calls
-# Lines 3827-3920: _interruptible_api_call - sync wrapper around async
-# Lines 2269-2297: _hydrate_todo_store - O(n) history scan on every message
-# Lines 2158-2222: _save_session_log - synchronous file I/O on every turn
-```
-
-**Performance Impact:**
-- Import time: ~2-3 seconds (circular dependencies, massive imports)
-- Initialization: 500ms+ per AIAgent instance
-- Memory footprint: ~50MB per agent instance
-- Session save: 50-100ms blocking I/O per turn
-
-### 1.2 Gateway Stream Consumer - Busy-Wait Pattern
-
-**File:** gateway/stream_consumer.py  
-**Lines:** 88-147
-
-```python
-# PROBLEM: Busy-wait loop with fixed 50ms sleep
-while True:
-    try:
-        item = self._queue.get_nowait()  # Non-blocking
-    except queue.Empty:
-        break
-    # ...
-    await asyncio.sleep(0.05)  # 50ms delay = max 20 updates/sec
-```
-
-**Issues:**
-- Fixed 50ms sleep limits throughput to 20 updates/second
-- No adaptive back-off
-- Wastes CPU cycles polling
-
-### 1.3 Context Compression - Expensive LLM Calls
-
-**File:** agent/context_compressor.py  
-**Lines:** 250-369
-
-```python
-def _generate_summary(self, turns_to_summarize: List[Dict]) -> Optional[str]:
-    # Calls LLM for EVERY compression - $$$ and latency
-    response = call_llm(
-        messages=[{"role": "user", "content": prompt}],
-        max_tokens=summary_budget * 2,  # Expensive!
-    )
-```
-
-**Issues:**
-- Synchronous LLM call blocks agent loop
-- No caching of similar contexts
-- Repeated serialization of same messages
-
-### 1.4 Web Tools - Synchronous HTTP Requests
-
-**File:** tools/web_tools.py  
-**Lines:** 171-188
-
-```python
-def _tavily_request(endpoint: str, payload: dict) -> dict:
-    response = httpx.post(url, json=payload, timeout=60)  # BLOCKING
-    response.raise_for_status()
-    return response.json()
-```
-
-**Issues:**
-- 60-second blocking timeout
-- No async/await pattern
-- Serial request pattern (no parallelism)
-
-### 1.5 SQLite Session Store - Write Contention
-
-**File:** hermes_state.py  
-**Lines:** 116-215
-
-```python
-def _execute_write(self, fn: Callable) -> T:
-    for attempt in range(self._WRITE_MAX_RETRIES):  # 15 retries!
-        try:
-            with self._lock:  # Global lock
-                self._conn.execute("BEGIN IMMEDIATE")
-                result = fn(self._conn)
-                self._conn.commit()
-        except sqlite3.OperationalError:
-            time.sleep(random.uniform(0.020, 0.150))  # Random jitter
-```
-
-**Issues:**
-- Global thread lock on all writes
-- 15 retry attempts with jitter
-- Serializes all DB operations
-
----
-
-## 2. MEMORY PROFILING RECOMMENDATIONS
-
-### 2.1 Memory Leaks Identified
-
-**A. Agent Cache in Gateway (run.py lines 406-413)**
-```python
-# PROBLEM: Unbounded cache growth
-self._agent_cache: Dict[str, tuple] = {}  # Never evicted!
-self._agent_cache_lock = _threading.Lock()
-```
-**Fix:** Implement LRU cache with maxsize=100
-
-**B. Message History in run_agent.py**
-```python
-self._session_messages: List[Dict[str, Any]] = []  # Unbounded!
-```
-**Fix:** Implement sliding window or compression threshold
-
-**C. Read Tracker in file_tools.py (lines 57-62)**
-```python
-_read_tracker: dict = {}  # Per-task state never cleaned
-```
-**Fix:** TTL-based eviction
-
-### 2.2 Large Object Retention
-
-**A. Tool Registry (tools/registry.py)**
-- Holds ALL tool schemas in memory (~5MB)
-- No lazy loading
-
-**B. Model Metadata Cache (agent/model_metadata.py)**
-- Caches all model info indefinitely
-- No TTL or size limits
-
-### 2.3 String Duplication
-
-**Issue:** 1,516 JSON serialize/deserialize calls create massive string duplication
-
-**Recommendation:**
-- Use orjson for 10x faster JSON processing
-- Implement string interning for repeated keys
-- Use MessagePack for internal serialization
-
----
-
-## 3. ASYNC CONVERSION OPPORTUNITIES
-
-### 3.1 High-Priority Conversions
-
-| File | Function | Current | Impact |
-|------|----------|---------|--------|
-| tools/web_tools.py | web_search_tool | Sync | HIGH |
-| tools/web_tools.py | web_extract_tool | Sync | HIGH |
-| tools/browser_tool.py | browser_navigate | Sync | HIGH |
-| tools/terminal_tool.py | terminal_tool | Sync | MEDIUM |
-| tools/file_tools.py | read_file_tool | Sync | MEDIUM |
-| agent/context_compressor.py | _generate_summary | Sync | HIGH |
-| run_agent.py | _save_session_log | Sync | MEDIUM |
-
-### 3.2 Async Bridge Overhead
-
-**File:** model_tools.py (lines 81-126)
-
-```python
-def _run_async(coro):
-    # PROBLEM: Creates thread pool for EVERY async call!
-    if loop and loop.is_running():
-        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-            future = pool.submit(asyncio.run, coro)
-            return future.result(timeout=300)
-```
-
-**Issues:**
-- Creates/destroys thread pool per call
-- 300-second blocking wait
-- No connection pooling
-
-**Fix:** Use persistent async loop with asyncio.gather()
-
-### 3.3 Gateway Async Patterns
-
-**Current:**
-```python
-# gateway/run.py - Mixed sync/async
-async def handle_message(self, event):
-    result = self.run_agent_sync(event)  # Blocks event loop!
-```
-
-**Recommended:**
-```python
-async def handle_message(self, event):
-    result = await asyncio.to_thread(self.run_agent_sync, event)
-```
-
----
-
-## 4. CACHING STRATEGY IMPROVEMENTS
-
-### 4.1 Missing Cache Layers
-
-**A. Tool Schema Resolution**
-```python
-# model_tools.py - Rebuilds schemas every call
-filtered_tools = registry.get_definitions(tools_to_include)
-```
-**Fix:** Cache tool definitions keyed by (enabled_toolsets, disabled_toolsets)
-
-**B. Model Metadata Fetching**
-```python
-# agent/model_metadata.py - Fetches on every init
-fetch_model_metadata()  # HTTP request!
-```
-**Fix:** Cache with 1-hour TTL (already noted but not consistently applied)
-
-**C. Session Context Building**
-```python
-# gateway/session.py - Rebuilds prompt every message
-build_session_context_prompt(context)  # String formatting overhead
-```
-**Fix:** Cache with LRU for repeated contexts
-
-### 4.2 Cache Invalidation Strategy
-
-**Recommended Implementation:**
-```python
-from functools import lru_cache
-from cachetools import TTLCache
-
-# For tool definitions
-@lru_cache(maxsize=128)
-def get_cached_tool_definitions(enabled_toolsets: tuple, disabled_toolsets: tuple):
-    return registry.get_definitions(set(enabled_toolsets))
-
-# For API responses
-model_metadata_cache = TTLCache(maxsize=100, ttl=3600)
-```
-
-### 4.3 Redis/Memcached for Distributed Caching
-
-For multi-instance gateway deployments:
-- Cache session state in Redis
-- Share tool definitions across workers
-- Distributed rate limiting
-
----
-
-## 5. PERFORMANCE OPTIMIZATIONS (15+)
-
-### 5.1 Critical Optimizations
-
-**OPT-1: Async Web Tool HTTP Client**
-```python
-# tools/web_tools.py - Replace with async
-import httpx
-
-async def web_search_tool(query: str) -> dict:
-    async with httpx.AsyncClient() as client:
-        response = await client.post(url, json=payload, timeout=60)
-    return response.json()
-```
-**Impact:** 10x throughput improvement for concurrent requests
-
-**OPT-2: Streaming JSON Parser**
-```python
-# Replace json.loads for large responses
-import ijson  # Incremental JSON parser
-
-async def parse_large_response(stream):
-    async for item in ijson.items(stream, 'results.item'):
-        yield item
-```
-**Impact:** 50% memory reduction for large API responses
-
-**OPT-3: Connection Pooling**
-```python
-# Single shared HTTP client
-_http_client: Optional[httpx.AsyncClient] = None
-
-async def get_http_client() -> httpx.AsyncClient:
-    global _http_client
-    if _http_client is None:
-        _http_client = httpx.AsyncClient(
-            limits=httpx.Limits(max_keepalive_connections=20, max_connections=100)
-        )
-    return _http_client
-```
-**Impact:** Eliminates connection overhead (50-100ms per request)
-
-**OPT-4: Compiled Regex Caching**
-```python
-# run_agent.py line 243-256 - Compiles regex every call!
-_DESTRUCTIVE_PATTERNS = re.compile(...)  # Module level - good
-
-# But many patterns are inline - cache them
-@lru_cache(maxsize=1024)
-def get_path_pattern(path: str):
-    return re.compile(re.escape(path) + r'.*')
-```
-**Impact:** 20% CPU reduction in path matching
-
-**OPT-5: Lazy Tool Discovery**
-```python
-# model_tools.py - Imports ALL tools at startup
-def _discover_tools():
-    for mod_name in _modules:  # 16 imports!
-        importlib.import_module(mod_name)
-
-# Fix: Lazy import on first use
-@lru_cache(maxsize=1)
-def _get_tool_module(name: str):
-    return importlib.import_module(f"tools.{name}")
-```
-**Impact:** 2-second faster startup time
-
-### 5.2 Database Optimizations
-
-**OPT-6: SQLite Write Batching**
-```python
-# hermes_state.py - Current: one write per operation
-# Fix: Batch writes
-
-def batch_insert_messages(self, messages: List[Dict]):
-    with self._lock:
-        self._conn.execute("BEGIN IMMEDIATE")
-        try:
-            self._conn.executemany(
-                "INSERT INTO messages (...) VALUES (...)",
-                [(m['session_id'], m['content'], ...) for m in messages]
-            )
-            self._conn.commit()
-        except:
-            self._conn.rollback()
-```
-**Impact:** 10x faster for bulk operations
-
-**OPT-7: Connection Pool for SQLite**
-```python
-# Use sqlalchemy with connection pooling
-from sqlalchemy import create_engine
-from sqlalchemy.pool import QueuePool
-
-engine = create_engine(
-    'sqlite:///state.db',
-    poolclass=QueuePool,
-    pool_size=5,
-    max_overflow=10
-)
-```
-
-### 5.3 Memory Optimizations
-
-**OPT-8: Streaming Message Processing**
-```python
-# run_agent.py - Current: loads ALL messages into memory
-# Fix: Generator-based processing
-
-def iter_messages(self, session_id: str):
-    cursor = self._conn.execute(
-        "SELECT content FROM messages WHERE session_id = ? ORDER BY timestamp",
-        (session_id,)
-    )
-    for row in cursor:
-        yield json.loads(row['content'])
-```
-
-**OPT-9: String Interning**
-```python
-import sys
-
-# For repeated string keys in JSON
-INTERN_KEYS = {'role', 'content', 'tool_calls', 'function'}
-
-def intern_message(msg: dict) -> dict:
-    return {sys.intern(k) if k in INTERN_KEYS else k: v 
-            for k, v in msg.items()}
-```
-
-### 5.4 Algorithmic Optimizations
-
-**OPT-10: O(1) Tool Lookup**
-```python
-# tools/registry.py - Current: linear scan
-for name in sorted(tool_names):  # O(n log n)
-    entry = self._tools.get(name)
-
-# Fix: Pre-computed sets
-self._tool_index = {name: entry for name, entry in self._tools.items()}
-```
-
-**OPT-11: Path Overlap Detection**
-```python
-# run_agent.py lines 327-335 - O(n*m) comparison
-def _paths_overlap(left: Path, right: Path) -> bool:
-    # Current: compares ALL path parts
-    
-# Fix: Hash-based lookup
-from functools import lru_cache
-
-@lru_cache(maxsize=1024)
-def get_path_hash(path: Path) -> str:
-    return str(path.resolve())
-```
-
-**OPT-12: Parallel Tool Execution**
-```python
-# run_agent.py - Current: sequential or limited parallel
-# Fix: asyncio.gather for safe tools
-
-async def execute_tool_batch(tool_calls):
-    safe_tools = [tc for tc in tool_calls if tc.name in _PARALLEL_SAFE_TOOLS]
-    unsafe_tools = [tc for tc in tool_calls if tc.name not in _PARALLEL_SAFE_TOOLS]
-    
-    # Execute safe tools in parallel
-    safe_results = await asyncio.gather(*[
-        execute_tool(tc) for tc in safe_tools
-    ])
-    
-    # Execute unsafe tools sequentially
-    unsafe_results = []
-    for tc in unsafe_tools:
-        unsafe_results.append(await execute_tool(tc))
-```
-
-### 5.5 I/O Optimizations
-
-**OPT-13: Async File Operations**
-```python
-# utils.py - atomic_json_write uses blocking I/O
-# Fix: aiofiles
-
-import aiofiles
-
-async def async_atomic_json_write(path: Path, data: dict):
-    tmp_path = path.with_suffix('.tmp')
-    async with aiofiles.open(tmp_path, 'w') as f:
-        await f.write(json.dumps(data))
-    tmp_path.rename(path)
-```
-
-**OPT-14: Memory-Mapped Files for Large Logs**
-```python
-# For trajectory files
-import mmap
-
-def read_trajectory_chunk(path: Path, offset: int, size: int):
-    with open(path, 'rb') as f:
-        with mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ) as mm:
-            return mm[offset:offset+size]
-```
-
-**OPT-15: Compression for Session Storage**
-```python
-import lz4.frame  # Fast compression
-
-class CompressedSessionDB(SessionDB):
-    def _compress_message(self, content: str) -> bytes:
-        return lz4.frame.compress(content.encode())
-    
-    def _decompress_message(self, data: bytes) -> str:
-        return lz4.frame.decompress(data).decode()
-```
-**Impact:** 70% storage reduction, faster I/O
-
----
-
-## 6. ADDITIONAL RECOMMENDATIONS
-
-### 6.1 Architecture Improvements
-
-1. **Split run_agent.py** into modules:
-   - agent/core.py - Core conversation loop
-   - agent/tools.py - Tool execution
-   - agent/persistence.py - Session management
-   - agent/api.py - API client management
-
-2. **Implement Event-Driven Architecture:**
-   - Use message queue for tool execution
-   - Decouple gateway from agent logic
-   - Enable horizontal scaling
-
-3. **Add Metrics Collection:**
-   ```python
-   from prometheus_client import Histogram, Counter
-   
-   tool_execution_time = Histogram('tool_duration_seconds', 'Time spent in tools', ['tool_name'])
-   api_call_counter = Counter('api_calls_total', 'Total API calls', ['provider', 'status'])
-   ```
-
-### 6.2 Profiling Recommendations
-
-**Immediate Actions:**
-```bash
-# 1. Profile import time
-python -X importtime -c "import run_agent" 2>&1 | head -100
-
-# 2. Memory profiling
-pip install memory_profiler
-python -m memory_profiler run_agent.py
-
-# 3. CPU profiling
-pip install py-spy
-py-spy top -- python run_agent.py
-
-# 4. Async profiling
-pip install austin
-austin python run_agent.py
-```
-
-### 6.3 Load Testing
-
-```python
-# locustfile.py for gateway load testing
-from locust import HttpUser, task
-
-class GatewayUser(HttpUser):
-    @task
-    def send_message(self):
-        self.client.post("/webhook/telegram", json={
-            "message": {"text": "Hello", "chat": {"id": 123}}
-        })
-```
-
----
-
-## 7. PRIORITY MATRIX
-
-| Priority | Optimization | Effort | Impact |
-|----------|-------------|--------|--------|
-| P0 | Async web tools | Low | 10x throughput |
-| P0 | HTTP connection pooling | Low | 100ms latency |
-| P0 | SQLite batch writes | Low | 10x DB perf |
-| P1 | Tool lazy loading | Low | 2s startup |
-| P1 | Agent cache LRU | Low | Memory leak fix |
-| P1 | Streaming JSON | Medium | 50% memory |
-| P2 | Code splitting | High | Maintainability |
-| P2 | Redis caching | Medium | Scalability |
-| P2 | Compression | Low | 70% storage |
-
----
-
-## 8. CONCLUSION
-
-The Hermes Agent codebase has significant performance debt accumulated from rapid feature development. The monolithic architecture and synchronous I/O patterns are the primary bottlenecks.
-
-**Quick Wins (1 week):**
-- Async HTTP clients
-- Connection pooling  
-- SQLite batching
-- Lazy loading
-
-**Medium Term (1 month):**
-- Code modularization
-- Caching layers
-- Streaming processing
-
-**Long Term (3 months):**
-- Event-driven architecture
-- Horizontal scaling
-- Distributed caching
-
-**Estimated Performance Gains:**
-- Latency: 50-70% reduction
-- Throughput: 10x improvement
-- Memory: 40% reduction
-- Startup: 3x faster

PERFORMANCE_HOTSPOTS_QUICKREF.md

@@ -1,241 +0,0 @@
-# Performance Hotspots Quick Reference
-
-## Critical Files to Optimize
-
-### 1. run_agent.py (8,317 lines, 419KB)
-```
-Lines 460-1000:    Massive __init__ - 50+ params, slow startup
-Lines 2158-2222:   _save_session_log - blocking I/O every turn
-Lines 2269-2297:   _hydrate_todo_store - O(n) history scan
-Lines 3759-3826:   _anthropic_messages_create - blocking API calls
-Lines 3827-3920:   _interruptible_api_call - sync/async bridge overhead
-```
-
-**Fix Priority: CRITICAL**
-- Split into modules
-- Add async session logging
-- Cache history hydration
-
----
-
-### 2. gateway/run.py (6,016 lines, 274KB)
-```
-Lines 406-413:     _agent_cache - unbounded growth, memory leak
-Lines 464-493:     _get_or_create_gateway_honcho - blocking init
-Lines 2800+:       run_agent_sync - blocks event loop
-```
-
-**Fix Priority: HIGH**
-- Implement LRU cache
-- Use asyncio.to_thread()
-
----
-
-### 3. gateway/stream_consumer.py
-```
-Lines 88-147:     Busy-wait loop with 50ms sleep
-                  Max 20 updates/sec throughput
-```
-
-**Fix Priority: MEDIUM**
-- Use asyncio.Event for signaling
-- Adaptive back-off
-
----
-
-### 4. tools/web_tools.py (1,843 lines)
-```
-Lines 171-188:   _tavily_request - sync httpx call, 60s timeout
-Lines 256-301:   process_content_with_llm - sync LLM call
-```
-
-**Fix Priority: CRITICAL**
-- Convert to async
-- Add connection pooling
-
----
-
-### 5. tools/browser_tool.py (1,955 lines)
-```
-Lines 194-208:   _resolve_cdp_override - sync requests call
-Lines 234-257:   _get_cloud_provider - blocking config read
-```
-
-**Fix Priority: HIGH**
-- Async HTTP client
-- Cache config reads
-
----
-
-### 6. tools/terminal_tool.py (1,358 lines)
-```
-Lines 66-92:     _check_disk_usage_warning - blocking glob walk
-Lines 167-289:   _prompt_for_sudo_password - thread creation per call
-```
-
-**Fix Priority: MEDIUM**
-- Async disk check
-- Thread pool reuse
-
----
-
-### 7. tools/file_tools.py (563 lines)
-```
-Lines 53-62:     _read_tracker - unbounded dict growth
-Lines 195-262:   read_file_tool - sync file I/O
-```
-
-**Fix Priority: MEDIUM**
-- TTL-based cleanup
-- aiofiles for async I/O
-
----
-
-### 8. agent/context_compressor.py (676 lines)
-```
-Lines 250-369:   _generate_summary - expensive LLM call
-Lines 490-500:   _find_tail_cut_by_tokens - O(n) token counting
-```
-
-**Fix Priority: HIGH**
-- Background compression task
-- Cache summaries
-
----
-
-### 9. hermes_state.py (1,274 lines)
-```
-Lines 116-215:   _execute_write - global lock, 15 retries
-Lines 143-156:   SQLite with WAL but single connection
-```
-
-**Fix Priority: HIGH**
-- Connection pooling
-- Batch writes
-
----
-
-### 10. model_tools.py (472 lines)
-```
-Lines 81-126:    _run_async - creates ThreadPool per call!
-Lines 132-170:   _discover_tools - imports ALL tools at startup
-```
-
-**Fix Priority: CRITICAL**
-- Persistent thread pool
-- Lazy tool loading
-
----
-
-## Quick Fixes (Copy-Paste Ready)
-
-### Fix 1: LRU Cache for Agent Cache
-```python
-from functools import lru_cache
-from cachetools import TTLCache
-
-# In gateway/run.py
-self._agent_cache: Dict[str, tuple] = TTLCache(maxsize=100, ttl=3600)
-```
-
-### Fix 2: Async HTTP Client
-```python
-# In tools/web_tools.py
-import httpx
-
-_http_client: Optional[httpx.AsyncClient] = None
-
-async def get_http_client() -> httpx.AsyncClient:
-    global _http_client
-    if _http_client is None:
-        _http_client = httpx.AsyncClient(timeout=60)
-    return _http_client
-```
-
-### Fix 3: Connection Pool for DB
-```python
-# In hermes_state.py
-from sqlalchemy import create_engine
-from sqlalchemy.pool import QueuePool
-
-engine = create_engine(
-    'sqlite:///state.db',
-    poolclass=QueuePool,
-    pool_size=5,
-    max_overflow=10
-)
-```
-
-### Fix 4: Lazy Tool Loading
-```python
-# In model_tools.py
-@lru_cache(maxsize=1)
-def _get_discovered_tools():
-    """Cache tool discovery after first call"""
-    _discover_tools()
-    return registry
-```
-
-### Fix 5: Batch Session Writes
-```python
-# In run_agent.py
-async def _save_session_log_async(self, messages):
-    """Non-blocking session save"""
-    loop = asyncio.get_event_loop()
-    await loop.run_in_executor(None, self._save_session_log, messages)
-```
-
----
-
-## Performance Metrics to Track
-
-```python
-# Add these metrics
-IMPORT_TIME = Gauge('import_time_seconds', 'Module import time')
-AGENT_INIT_TIME = Gauge('agent_init_seconds', 'AIAgent init time')
-TOOL_EXECUTION_TIME = Histogram('tool_duration_seconds', 'Tool execution', ['tool_name'])
-DB_WRITE_TIME = Histogram('db_write_seconds', 'Database write time')
-API_LATENCY = Histogram('api_latency_seconds', 'API call latency', ['provider'])
-MEMORY_USAGE = Gauge('memory_usage_bytes', 'Process memory')
-CACHE_HIT_RATE = Gauge('cache_hit_rate', 'Cache hit rate', ['cache_name'])
-```
-
----
-
-## One-Liner Profiling Commands
-
-```bash
-# Find slow imports
-python -X importtime -c "from run_agent import AIAgent" 2>&1 | head -50
-
-# Find blocking I/O
-sudo strace -e trace=openat,read,write -c python run_agent.py 2>&1
-
-# Memory profiling
-pip install memory_profiler && python -m memory_profiler run_agent.py
-
-# CPU profiling
-pip install py-spy && py-spy record -o profile.svg -- python run_agent.py
-
-# Find all sleep calls
-grep -rn "time.sleep\|asyncio.sleep" --include="*.py" | wc -l
-
-# Find all JSON calls
-grep -rn "json.loads\|json.dumps" --include="*.py" | wc -l
-
-# Find all locks
-grep -rn "threading.Lock\|threading.RLock\|asyncio.Lock" --include="*.py"
-```
-
----
-
-## Expected Performance After Fixes
-
-| Metric | Before | After | Improvement |
-|--------|--------|-------|-------------|
-| Startup time | 3-5s | 1-2s | 3x faster |
-| API latency | 500ms | 200ms | 2.5x faster |
-| Concurrent requests | 10/s | 100/s | 10x throughput |
-| Memory per agent | 50MB | 30MB | 40% reduction |
-| DB writes/sec | 50 | 500 | 10x throughput |
-| Import time | 2s | 0.5s | 4x faster |

PERFORMANCE_OPTIMIZATIONS.md

@@ -1,163 +0,0 @@
-# Performance Optimizations for run_agent.py
-
-## Summary of Changes
-
-This document describes the async I/O and performance optimizations applied to `run_agent.py` to fix blocking operations and improve overall responsiveness.
-
----
-
-## 1. Session Log Batching (PROBLEM 1: Lines 2158-2222)
-
-### Problem
-`_save_session_log()` performed **blocking file I/O** on every conversation turn, causing:
-- UI freezing during rapid message exchanges
-- Unnecessary disk writes (JSON file was overwritten every turn)
-- Synchronous `json.dump()` and `fsync()` blocking the main thread
-
-### Solution
-Implemented **async batching** with the following components:
-
-#### New Methods:
-- `_init_session_log_batcher()` - Initialize batching infrastructure
-- `_save_session_log()` - Updated to use non-blocking batching
-- `_flush_session_log_async()` - Flush writes in background thread
-- `_write_session_log_sync()` - Actual blocking I/O (runs in thread pool)
-- `_deferred_session_log_flush()` - Delayed flush for batching
-- `_shutdown_session_log_batcher()` - Cleanup and flush on exit
-
-#### Key Features:
-- **Time-based batching**: Minimum 500ms between writes
-- **Deferred flushing**: Rapid successive calls are batched
-- **Thread pool**: Single-worker executor prevents concurrent write conflicts
-- **Atexit cleanup**: Ensures pending logs are flushed on exit
-- **Backward compatible**: Same method signature, no breaking changes
-
-#### Performance Impact:
-- Before: Every turn blocks on disk I/O (~5-20ms per write)
-- After: Updates cached in memory, flushed every 500ms or on exit
-- 10 rapid calls now result in ~1-2 writes instead of 10
-
----
-
-## 2. Todo Store Hydration Caching (PROBLEM 2: Lines 2269-2297)
-
-### Problem
-`_hydrate_todo_store()` performed **O(n) history scan on every message**:
-- Scanned entire conversation history backwards
-- No caching between calls
-- Re-parsed JSON for every message check
-- Gateway mode creates fresh AIAgent per message, making this worse
-
-### Solution
-Implemented **result caching** with scan limiting:
-
-#### Key Changes:
-```python
-# Added caching flags
-self._todo_store_hydrated  # Marks if hydration already done
-self._todo_cache_key        # Caches history object id
-
-# Added scan limit for very long histories
-scan_limit = 100  # Only scan last 100 messages
-```
-
-#### Performance Impact:
-- Before: O(n) scan every call, parsing JSON for each tool message
-- After: O(1) cached check, skips redundant work
-- First call: Scans up to 100 messages (limited)
-- Subsequent calls: <1μs cached check
-
----
-
-## 3. API Call Timeouts (PROBLEM 3: Lines 3759-3826)
-
-### Problem
-`_anthropic_messages_create()` and `_interruptible_api_call()` had:
-- **No timeout handling** - could block indefinitely
-- 300ms polling interval for interrupt detection (sluggish)
-- No timeout for OpenAI-compatible endpoints
-
-### Solution
-Added comprehensive timeout handling:
-
-#### Changes to `_anthropic_messages_create()`:
-- Added `timeout: float = 300.0` parameter (5 minutes default)
-- Passes timeout to Anthropic SDK
-
-#### Changes to `_interruptible_api_call()`:
-- Added `timeout: float = 300.0` parameter
-- **Reduced polling interval** from 300ms to **50ms** (6x faster interrupt response)
-- Added elapsed time tracking
-- Raises `TimeoutError` if API call exceeds timeout
-- Force-closes clients on timeout to prevent resource leaks
-- Passes timeout to OpenAI-compatible endpoints
-
-#### Performance Impact:
-- Before: Could hang forever on stuck connections
-- After: Guaranteed timeout after 5 minutes (configurable)
-- Interrupt response: 300ms → 50ms (6x faster)
-
----
-
-## Backward Compatibility
-
-All changes maintain **100% backward compatibility**:
-
-1. **Session logging**: Same method signature, behavior is additive
-2. **Todo hydration**: Same signature, caching is transparent
-3. **API calls**: New `timeout` parameter has sensible default (300s)
-
-No existing code needs modification to benefit from these optimizations.
-
----
-
-## Testing
-
-Run the verification script:
-```bash
-python3 -c "
-import ast
-with open('run_agent.py') as f:
-    source = f.read()
-tree = ast.parse(source)
-
-methods = ['_init_session_log_batcher', '_write_session_log_sync', 
-           '_shutdown_session_log_batcher', '_hydrate_todo_store',
-           '_interruptible_api_call']
-
-for node in ast.walk(tree):
-    if isinstance(node, ast.FunctionDef) and node.name in methods:
-        print(f'✓ Found {node.name}')
-print('\nAll optimizations verified!')
-"
-```
-
----
-
-## Lines Modified
-
-| Function | Line Range | Change Type |
-|----------|-----------|-------------|
-| `_init_session_log_batcher` | ~2168-2178 | NEW |
-| `_save_session_log` | ~2178-2230 | MODIFIED |
-| `_flush_session_log_async` | ~2230-2240 | NEW |
-| `_write_session_log_sync` | ~2240-2300 | NEW |
-| `_deferred_session_log_flush` | ~2300-2305 | NEW |
-| `_shutdown_session_log_batcher` | ~2305-2315 | NEW |
-| `_hydrate_todo_store` | ~2320-2360 | MODIFIED |
-| `_anthropic_messages_create` | ~3870-3890 | MODIFIED |
-| `_interruptible_api_call` | ~3895-3970 | MODIFIED |
-
----
-
-## Future Improvements
-
-Potential additional optimizations:
-1. Use `aiofiles` for true async file I/O (requires aiofiles dependency)
-2. Batch SQLite writes in `_flush_messages_to_session_db`
-3. Add compression for large session logs
-4. Implement write-behind caching for checkpoint manager
-
----
-
-*Optimizations implemented: 2026-03-31*

README.md

@@ -13,7 +13,7 @@
 
 **The self-improving AI agent built by [Nous Research](https://nousresearch.com).** It's the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions. Run it on a $5 VPS, a GPU cluster, or serverless infrastructure that costs nearly nothing when idle. It's not tied to your laptop — talk to it from Telegram while it works on a cloud VM.
 
-Use any model you want — [Nous Portal](https://portal.nousresearch.com), [OpenRouter](https://openrouter.ai) (200+ models), [z.ai/GLM](https://z.ai), [Kimi/Moonshot](https://platform.moonshot.ai), [MiniMax](https://www.minimax.io), OpenAI, or your own endpoint. Switch with `hermes model` — no code changes, no lock-in.
+Use any model you want — [Nous Portal](https://portal.nousresearch.com), [OpenRouter](https://openrouter.ai) (200+ models), [Xiaomi MiMo](https://platform.xiaomimimo.com), [z.ai/GLM](https://z.ai), [Kimi/Moonshot](https://platform.moonshot.ai), [MiniMax](https://www.minimax.io), [Hugging Face](https://huggingface.co), OpenAI, or your own endpoint. Switch with `hermes model` — no code changes, no lock-in.
 
 <table>
 <tr><td><b>A real terminal interface</b></td><td>Full TUI with multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output.</td></tr>
@@ -33,8 +33,10 @@ Use any model you want — [Nous Portal](https://portal.nousresearch.com), [Open
 curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
 ```
 
-Works on Linux, macOS, and WSL2. The installer handles everything — Python, Node.js, dependencies, and the `hermes` command. No prerequisites except git.
+Works on Linux, macOS, WSL2, and Android via Termux. The installer handles the platform-specific setup for you.
 
+> **Android / Termux:** The tested manual path is documented in the [Termux guide](https://hermes-agent.nousresearch.com/docs/getting-started/termux). On Termux, Hermes installs a curated `.[termux]` extra because the full `.[all]` extra currently pulls Android-incompatible voice dependencies.
+>
 > **Windows:** Native Windows is not supported. Please install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and run the command above.
 
 After installation:
@@ -165,6 +167,7 @@ python -m pytest tests/ -q
 - 📚 [Skills Hub](https://agentskills.io)
 - 🐛 [Issues](https://github.com/NousResearch/hermes-agent/issues)
 - 💡 [Discussions](https://github.com/NousResearch/hermes-agent/discussions)
+- 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — Community WeChat bridge: Run Hermes Agent and OpenClaw on the same WeChat account.
 
 ---
 

RELEASE_v0.6.0.md

@@ -0,0 +1,249 @@
+# Hermes Agent v0.6.0 (v2026.3.30)
+
+**Release Date:** March 30, 2026
+
+> The multi-instance release — Profiles for running isolated agent instances, MCP server mode, Docker container, fallback provider chains, two new messaging platforms (Feishu/Lark and WeCom), Telegram webhook mode, Slack multi-workspace OAuth, 95 PRs and 16 resolved issues in 2 days.
+
+---
+
+## ✨ Highlights
+
+- **Profiles — Multi-Instance Hermes** — Run multiple isolated Hermes instances from the same installation. Each profile gets its own config, memory, sessions, skills, and gateway service. Create with `hermes profile create`, switch with `hermes -p <name>`, export/import for sharing. Full token-lock isolation prevents two profiles from using the same bot credential. ([#3681](https://github.com/NousResearch/hermes-agent/pull/3681))
+
+- **MCP Server Mode** — Expose Hermes conversations and sessions to any MCP-compatible client (Claude Desktop, Cursor, VS Code, etc.) via `hermes mcp serve`. Browse conversations, read messages, search across sessions, and manage attachments — all through the Model Context Protocol. Supports both stdio and Streamable HTTP transports. ([#3795](https://github.com/NousResearch/hermes-agent/pull/3795))
+
+- **Docker Container** — Official Dockerfile for running Hermes Agent in a container. Supports both CLI and gateway modes with volume-mounted config. ([#3668](https://github.com/NousResearch/hermes-agent/pull/3668), closes [#850](https://github.com/NousResearch/hermes-agent/issues/850))
+
+- **Ordered Fallback Provider Chain** — Configure multiple inference providers with automatic failover. When your primary provider returns errors or is unreachable, Hermes automatically tries the next provider in the chain. Configure via `fallback_providers` in config.yaml. ([#3813](https://github.com/NousResearch/hermes-agent/pull/3813), closes [#1734](https://github.com/NousResearch/hermes-agent/issues/1734))
+
+- **Feishu/Lark Platform Support** — Full gateway adapter for Feishu (飞书) and Lark with event subscriptions, message cards, group chat, image/file attachments, and interactive card callbacks. ([#3799](https://github.com/NousResearch/hermes-agent/pull/3799), [#3817](https://github.com/NousResearch/hermes-agent/pull/3817), closes [#1788](https://github.com/NousResearch/hermes-agent/issues/1788))
+
+- **WeCom (Enterprise WeChat) Platform Support** — New gateway adapter for WeCom (企业微信) with text/image/voice messages, group chats, and callback verification. ([#3847](https://github.com/NousResearch/hermes-agent/pull/3847))
+
+- **Slack Multi-Workspace OAuth** — Connect a single Hermes gateway to multiple Slack workspaces via OAuth token file. Each workspace gets its own bot token, resolved dynamically per incoming event. ([#3903](https://github.com/NousResearch/hermes-agent/pull/3903))
+
+- **Telegram Webhook Mode & Group Controls** — Run the Telegram adapter in webhook mode as an alternative to polling — faster response times and better for production deployments behind a reverse proxy. New group mention gating controls when the bot responds: always, only when @mentioned, or via regex triggers. ([#3880](https://github.com/NousResearch/hermes-agent/pull/3880), [#3870](https://github.com/NousResearch/hermes-agent/pull/3870))
+
+- **Exa Search Backend** — Add Exa as an alternative web search and content extraction backend alongside Firecrawl and DuckDuckGo. Set `EXA_API_KEY` and configure as preferred backend. ([#3648](https://github.com/NousResearch/hermes-agent/pull/3648))
+
+- **Skills & Credentials on Remote Backends** — Mount skill directories and credential files into Modal and Docker containers, so remote terminal sessions have access to the same skills and secrets as local execution. ([#3890](https://github.com/NousResearch/hermes-agent/pull/3890), [#3671](https://github.com/NousResearch/hermes-agent/pull/3671), closes [#3665](https://github.com/NousResearch/hermes-agent/issues/3665), [#3433](https://github.com/NousResearch/hermes-agent/issues/3433))
+
+---
+
+## 🏗️ Core Agent & Architecture
+
+### Provider & Model Support
+- **Ordered fallback provider chain** — automatic failover across multiple configured providers ([#3813](https://github.com/NousResearch/hermes-agent/pull/3813))
+- **Fix api_mode on provider switch** — switching providers via `hermes model` now correctly clears stale `api_mode` instead of hardcoding `chat_completions`, fixing 404s for providers with Anthropic-compatible endpoints ([#3726](https://github.com/NousResearch/hermes-agent/pull/3726), [#3857](https://github.com/NousResearch/hermes-agent/pull/3857), closes [#3685](https://github.com/NousResearch/hermes-agent/issues/3685))
+- **Stop silent OpenRouter fallback** — when no provider is configured, Hermes now raises a clear error instead of silently routing to OpenRouter ([#3807](https://github.com/NousResearch/hermes-agent/pull/3807), [#3862](https://github.com/NousResearch/hermes-agent/pull/3862))
+- **Gemini 3.1 preview models** — added to OpenRouter and Nous Portal catalogs ([#3803](https://github.com/NousResearch/hermes-agent/pull/3803), closes [#3753](https://github.com/NousResearch/hermes-agent/issues/3753))
+- **Gemini direct API context length** — full context length resolution for direct Google AI endpoints ([#3876](https://github.com/NousResearch/hermes-agent/pull/3876))
+- **gpt-5.4-mini** added to Codex fallback catalog ([#3855](https://github.com/NousResearch/hermes-agent/pull/3855))
+- **Curated model lists preferred** over live API probe when the probe returns fewer models ([#3856](https://github.com/NousResearch/hermes-agent/pull/3856), [#3867](https://github.com/NousResearch/hermes-agent/pull/3867))
+- **User-friendly 429 rate limit messages** with Retry-After countdown ([#3809](https://github.com/NousResearch/hermes-agent/pull/3809))
+- **Auxiliary client placeholder key** for local servers without auth requirements ([#3842](https://github.com/NousResearch/hermes-agent/pull/3842))
+- **INFO-level logging** for auxiliary provider resolution ([#3866](https://github.com/NousResearch/hermes-agent/pull/3866))
+
+### Agent Loop & Conversation
+- **Subagent status reporting** — reports `completed` status when summary exists instead of generic failure ([#3829](https://github.com/NousResearch/hermes-agent/pull/3829))
+- **Session log file updated during compression** — prevents stale file references after context compression ([#3835](https://github.com/NousResearch/hermes-agent/pull/3835))
+- **Omit empty tools param** — sends no `tools` parameter when empty instead of `None`, fixing compatibility with strict providers ([#3820](https://github.com/NousResearch/hermes-agent/pull/3820))
+
+### Profiles & Multi-Instance
+- **Profiles system** — `hermes profile create/list/switch/delete/export/import/rename`. Each profile gets isolated HERMES_HOME, gateway service, CLI wrapper. Token locks prevent credential collisions. Tab completion for profile names. ([#3681](https://github.com/NousResearch/hermes-agent/pull/3681))
+- **Profile-aware display paths** — all user-facing `~/.hermes` paths replaced with `display_hermes_home()` to show the correct profile directory ([#3623](https://github.com/NousResearch/hermes-agent/pull/3623))
+- **Lazy display_hermes_home imports** — prevents `ImportError` during `hermes update` when modules cache stale bytecode ([#3776](https://github.com/NousResearch/hermes-agent/pull/3776))
+- **HERMES_HOME for protected paths** — `.env` write-deny path now respects HERMES_HOME instead of hardcoded `~/.hermes` ([#3840](https://github.com/NousResearch/hermes-agent/pull/3840))
+
+---
+
+## 📱 Messaging Platforms (Gateway)
+
+### New Platforms
+- **Feishu/Lark** — Full adapter with event subscriptions, message cards, group chat, image/file attachments, interactive card callbacks ([#3799](https://github.com/NousResearch/hermes-agent/pull/3799), [#3817](https://github.com/NousResearch/hermes-agent/pull/3817))
+- **WeCom (Enterprise WeChat)** — Text/image/voice messages, group chats, callback verification ([#3847](https://github.com/NousResearch/hermes-agent/pull/3847))
+
+### Telegram
+- **Webhook mode** — run as webhook endpoint instead of polling for production deployments ([#3880](https://github.com/NousResearch/hermes-agent/pull/3880))
+- **Group mention gating & regex triggers** — configurable bot response behavior in groups: always, @mention-only, or regex-matched ([#3870](https://github.com/NousResearch/hermes-agent/pull/3870))
+- **Gracefully handle deleted reply targets** — no more crashes when the message being replied to was deleted ([#3858](https://github.com/NousResearch/hermes-agent/pull/3858), closes [#3229](https://github.com/NousResearch/hermes-agent/issues/3229))
+
+### Discord
+- **Message processing reactions** — adds a reaction emoji while processing and removes it when done, giving visual feedback in channels ([#3871](https://github.com/NousResearch/hermes-agent/pull/3871))
+- **DISCORD_IGNORE_NO_MENTION** — skip messages that @mention other users/bots but not Hermes ([#3640](https://github.com/NousResearch/hermes-agent/pull/3640))
+- **Clean up deferred "thinking..."** — properly removes the "thinking..." indicator after slash commands complete ([#3674](https://github.com/NousResearch/hermes-agent/pull/3674), closes [#3595](https://github.com/NousResearch/hermes-agent/issues/3595))
+
+### Slack
+- **Multi-workspace OAuth** — connect to multiple Slack workspaces from a single gateway via OAuth token file ([#3903](https://github.com/NousResearch/hermes-agent/pull/3903))
+
+### WhatsApp
+- **Persistent aiohttp session** — reuse HTTP sessions across requests instead of creating new ones per message ([#3818](https://github.com/NousResearch/hermes-agent/pull/3818))
+- **LID↔phone alias resolution** — correctly match Linked ID and phone number formats in allowlists ([#3830](https://github.com/NousResearch/hermes-agent/pull/3830))
+- **Skip reply prefix in bot mode** — cleaner message formatting when running as a WhatsApp bot ([#3931](https://github.com/NousResearch/hermes-agent/pull/3931))
+
+### Matrix
+- **Native voice messages via MSC3245** — send voice messages as proper Matrix voice events instead of file attachments ([#3877](https://github.com/NousResearch/hermes-agent/pull/3877))
+
+### Mattermost
+- **Configurable mention behavior** — respond to messages without requiring @mention ([#3664](https://github.com/NousResearch/hermes-agent/pull/3664))
+
+### Signal
+- **URL-encode phone numbers** and correct attachment RPC parameter — fixes delivery failures with certain phone number formats ([#3670](https://github.com/NousResearch/hermes-agent/pull/3670)) — @kshitijk4poor
+
+### Email
+- **Close SMTP/IMAP connections on failure** — prevents connection leaks during error scenarios ([#3804](https://github.com/NousResearch/hermes-agent/pull/3804))
+
+### Gateway Core
+- **Atomic config writes** — use atomic file writes for config.yaml to prevent data loss during crashes ([#3800](https://github.com/NousResearch/hermes-agent/pull/3800))
+- **Home channel env overrides** — apply environment variable overrides for home channels consistently ([#3796](https://github.com/NousResearch/hermes-agent/pull/3796), [#3808](https://github.com/NousResearch/hermes-agent/pull/3808))
+- **Replace print() with logger** — BasePlatformAdapter now uses proper logging instead of print statements ([#3669](https://github.com/NousResearch/hermes-agent/pull/3669))
+- **Cron delivery labels** — resolve human-friendly delivery labels via channel directory ([#3860](https://github.com/NousResearch/hermes-agent/pull/3860), closes [#1945](https://github.com/NousResearch/hermes-agent/issues/1945))
+- **Cron [SILENT] tightening** — prevent agents from prefixing reports with [SILENT] to suppress delivery ([#3901](https://github.com/NousResearch/hermes-agent/pull/3901))
+- **Background task media delivery** and vision download timeout fixes ([#3919](https://github.com/NousResearch/hermes-agent/pull/3919))
+- **Boot-md hook** — example built-in hook to run a BOOT.md file on gateway startup ([#3733](https://github.com/NousResearch/hermes-agent/pull/3733))
+
+---
+
+## 🖥️ CLI & User Experience
+
+### Interactive CLI
+- **Configurable tool preview length** — show full file paths by default instead of truncating at 40 chars ([#3841](https://github.com/NousResearch/hermes-agent/pull/3841))
+- **Tool token context display** — `hermes tools` checklist now shows estimated token cost per toolset ([#3805](https://github.com/NousResearch/hermes-agent/pull/3805))
+- **/bg spinner TUI fix** — route background task spinner through the TUI widget to prevent status bar collision ([#3643](https://github.com/NousResearch/hermes-agent/pull/3643))
+- **Prevent status bar wrapping** into duplicate rows ([#3883](https://github.com/NousResearch/hermes-agent/pull/3883)) — @kshitijk4poor
+- **Handle closed stdout ValueError** in safe print paths — fixes crashes when stdout is closed during gateway thread shutdown ([#3843](https://github.com/NousResearch/hermes-agent/pull/3843), closes [#3534](https://github.com/NousResearch/hermes-agent/issues/3534))
+- **Remove input() from /tools disable** — eliminates freeze in terminal when disabling tools ([#3918](https://github.com/NousResearch/hermes-agent/pull/3918))
+- **TTY guard for interactive CLI commands** — prevent CPU spin when launched without a terminal ([#3933](https://github.com/NousResearch/hermes-agent/pull/3933))
+- **Argparse entrypoint** — use argparse in the top-level launcher for cleaner error handling ([#3874](https://github.com/NousResearch/hermes-agent/pull/3874))
+- **Lazy-initialized tools show yellow** in banner instead of red, reducing false alarm about "missing" tools ([#3822](https://github.com/NousResearch/hermes-agent/pull/3822))
+- **Honcho tools shown in banner** when configured ([#3810](https://github.com/NousResearch/hermes-agent/pull/3810))
+
+### Setup & Configuration
+- **Auto-install matrix-nio** during `hermes setup` when Matrix is selected ([#3802](https://github.com/NousResearch/hermes-agent/pull/3802), [#3873](https://github.com/NousResearch/hermes-agent/pull/3873))
+- **Session export stdout support** — export sessions to stdout with `-` for piping ([#3641](https://github.com/NousResearch/hermes-agent/pull/3641), closes [#3609](https://github.com/NousResearch/hermes-agent/issues/3609))
+- **Configurable approval timeouts** — set how long dangerous command approval prompts wait before auto-denying ([#3886](https://github.com/NousResearch/hermes-agent/pull/3886), closes [#3765](https://github.com/NousResearch/hermes-agent/issues/3765))
+- **Clear __pycache__ during update** — prevents stale bytecode ImportError after `hermes update` ([#3819](https://github.com/NousResearch/hermes-agent/pull/3819))
+
+---
+
+## 🔧 Tool System
+
+### MCP
+- **MCP Server Mode** — `hermes mcp serve` exposes conversations, sessions, and attachments to MCP clients via stdio or Streamable HTTP ([#3795](https://github.com/NousResearch/hermes-agent/pull/3795))
+- **Dynamic tool discovery** — respond to `notifications/tools/list_changed` events to pick up new tools from MCP servers without reconnecting ([#3812](https://github.com/NousResearch/hermes-agent/pull/3812))
+- **Non-deprecated HTTP transport** — switched from `sse_client` to `streamable_http_client` ([#3646](https://github.com/NousResearch/hermes-agent/pull/3646))
+
+### Web Tools
+- **Exa search backend** — alternative to Firecrawl and DuckDuckGo for web search and extraction ([#3648](https://github.com/NousResearch/hermes-agent/pull/3648))
+
+### Browser
+- **Guard against None LLM responses** in browser snapshot and vision tools ([#3642](https://github.com/NousResearch/hermes-agent/pull/3642))
+
+### Terminal & Remote Backends
+- **Mount skill directories** into Modal and Docker containers ([#3890](https://github.com/NousResearch/hermes-agent/pull/3890))
+- **Mount credential files** into remote backends with mtime+size caching ([#3671](https://github.com/NousResearch/hermes-agent/pull/3671))
+- **Preserve partial output** when commands time out instead of losing everything ([#3868](https://github.com/NousResearch/hermes-agent/pull/3868))
+- **Stop marking persisted env vars as missing** on remote backends ([#3650](https://github.com/NousResearch/hermes-agent/pull/3650))
+
+### Audio
+- **.aac format support** in transcription tool ([#3865](https://github.com/NousResearch/hermes-agent/pull/3865), closes [#1963](https://github.com/NousResearch/hermes-agent/issues/1963))
+- **Audio download retry** — retry logic for `cache_audio_from_url` matching the existing image download pattern ([#3401](https://github.com/NousResearch/hermes-agent/pull/3401)) — @binhnt92
+
+### Vision
+- **Reject non-image files** and enforce website-only policy for vision analysis ([#3845](https://github.com/NousResearch/hermes-agent/pull/3845))
+
+### Tool Schema
+- **Ensure name field** always present in tool definitions, fixing `KeyError: 'name'` crashes ([#3811](https://github.com/NousResearch/hermes-agent/pull/3811), closes [#3729](https://github.com/NousResearch/hermes-agent/issues/3729))
+
+### ACP (Editor Integration)
+- **Complete session management surface** for VS Code/Zed/JetBrains clients — proper task lifecycle, cancel support, session persistence ([#3675](https://github.com/NousResearch/hermes-agent/pull/3675))
+
+---
+
+## 🧩 Skills & Plugins
+
+### Skills System
+- **External skill directories** — configure additional skill directories via `skills.external_dirs` in config.yaml ([#3678](https://github.com/NousResearch/hermes-agent/pull/3678))
+- **Category path traversal blocked** — prevents `../` attacks in skill category names ([#3844](https://github.com/NousResearch/hermes-agent/pull/3844))
+- **parallel-cli moved to optional-skills** — reduces default skill footprint ([#3673](https://github.com/NousResearch/hermes-agent/pull/3673)) — @kshitijk4poor
+
+### New Skills
+- **memento-flashcards** — spaced repetition flashcard system ([#3827](https://github.com/NousResearch/hermes-agent/pull/3827))
+- **songwriting-and-ai-music** — songwriting craft and AI music generation prompts ([#3834](https://github.com/NousResearch/hermes-agent/pull/3834))
+- **SiYuan Note** — integration with SiYuan note-taking app ([#3742](https://github.com/NousResearch/hermes-agent/pull/3742))
+- **Scrapling** — web scraping skill using Scrapling library ([#3742](https://github.com/NousResearch/hermes-agent/pull/3742))
+- **one-three-one-rule** — communication framework skill ([#3797](https://github.com/NousResearch/hermes-agent/pull/3797))
+
+### Plugin System
+- **Plugin enable/disable commands** — `hermes plugins enable/disable <name>` for managing plugin state without removing them ([#3747](https://github.com/NousResearch/hermes-agent/pull/3747))
+- **Plugin message injection** — plugins can now inject messages into the conversation stream on behalf of the user via `ctx.inject_message()` ([#3778](https://github.com/NousResearch/hermes-agent/pull/3778)) — @winglian
+- **Honcho self-hosted support** — allow local Honcho instances without requiring an API key ([#3644](https://github.com/NousResearch/hermes-agent/pull/3644))
+
+---
+
+## 🔒 Security & Reliability
+
+### Security Hardening
+- **Hardened dangerous command detection** — expanded pattern matching for risky shell commands and added file tool path guards for sensitive locations (`/etc/`, `/boot/`, docker.sock) ([#3872](https://github.com/NousResearch/hermes-agent/pull/3872))
+- **Sensitive path write checks** in approval system — catch writes to system config files through file tools, not just terminal ([#3859](https://github.com/NousResearch/hermes-agent/pull/3859))
+- **Secret redaction expansion** — now covers ElevenLabs, Tavily, and Exa API keys ([#3920](https://github.com/NousResearch/hermes-agent/pull/3920))
+- **Vision file rejection** — reject non-image files passed to vision analysis to prevent information disclosure ([#3845](https://github.com/NousResearch/hermes-agent/pull/3845))
+- **Category path traversal blocking** — prevent directory traversal in skill category names ([#3844](https://github.com/NousResearch/hermes-agent/pull/3844))
+
+### Reliability
+- **Atomic config.yaml writes** — prevent data loss during gateway crashes ([#3800](https://github.com/NousResearch/hermes-agent/pull/3800))
+- **Clear __pycache__ on update** — prevent stale bytecode from causing ImportError after updates ([#3819](https://github.com/NousResearch/hermes-agent/pull/3819))
+- **Lazy imports for update safety** — prevent ImportError chains during `hermes update` when modules reference new functions ([#3776](https://github.com/NousResearch/hermes-agent/pull/3776))
+- **Restore terminalbench2 from patch corruption** — recovered file damaged by patch tool's secret redaction ([#3801](https://github.com/NousResearch/hermes-agent/pull/3801))
+- **Terminal timeout preserves partial output** — no more lost command output on timeout ([#3868](https://github.com/NousResearch/hermes-agent/pull/3868))
+
+---
+
+## 🐛 Notable Bug Fixes
+
+- **OpenClaw migration model config overwrite** — migration no longer overwrites model config dict with a string ([#3924](https://github.com/NousResearch/hermes-agent/pull/3924)) — @0xbyt4
+- **OpenClaw migration expanded** — covers full data footprint including sessions, cron, memory ([#3869](https://github.com/NousResearch/hermes-agent/pull/3869))
+- **Telegram deleted reply targets** — gracefully handle replies to deleted messages instead of crashing ([#3858](https://github.com/NousResearch/hermes-agent/pull/3858))
+- **Discord "thinking..." persistence** — properly cleans up deferred response indicators ([#3674](https://github.com/NousResearch/hermes-agent/pull/3674))
+- **WhatsApp LID↔phone aliases** — fixes allowlist matching failures with Linked ID format ([#3830](https://github.com/NousResearch/hermes-agent/pull/3830))
+- **Signal URL-encoded phone numbers** — fixes delivery failures with certain formats ([#3670](https://github.com/NousResearch/hermes-agent/pull/3670))
+- **Email connection leaks** — properly close SMTP/IMAP connections on error ([#3804](https://github.com/NousResearch/hermes-agent/pull/3804))
+- **_safe_print ValueError** — no more gateway thread crashes on closed stdout ([#3843](https://github.com/NousResearch/hermes-agent/pull/3843))
+- **Tool schema KeyError 'name'** — ensure name field always present in tool definitions ([#3811](https://github.com/NousResearch/hermes-agent/pull/3811))
+- **api_mode stale on provider switch** — correctly clear when switching providers via `hermes model` ([#3857](https://github.com/NousResearch/hermes-agent/pull/3857))
+
+---
+
+## 🧪 Testing
+
+- Resolved 10+ CI failures across hooks, tiktoken, plugins, and skill tests ([#3848](https://github.com/NousResearch/hermes-agent/pull/3848), [#3721](https://github.com/NousResearch/hermes-agent/pull/3721), [#3936](https://github.com/NousResearch/hermes-agent/pull/3936))
+
+---
+
+## 📚 Documentation
+
+- **Comprehensive OpenClaw migration guide** — step-by-step guide for migrating from OpenClaw/Claw3D to Hermes Agent ([#3864](https://github.com/NousResearch/hermes-agent/pull/3864), [#3900](https://github.com/NousResearch/hermes-agent/pull/3900))
+- **Credential file passthrough docs** — document how to forward credential files and env vars to remote backends ([#3677](https://github.com/NousResearch/hermes-agent/pull/3677))
+- **DuckDuckGo requirements clarified** — note runtime dependency on duckduckgo-search package ([#3680](https://github.com/NousResearch/hermes-agent/pull/3680))
+- **Skills catalog updated** — added red-teaming category and optional skills listing ([#3745](https://github.com/NousResearch/hermes-agent/pull/3745))
+- **Feishu docs MDX fix** — escape angle-bracket URLs that break Docusaurus build ([#3902](https://github.com/NousResearch/hermes-agent/pull/3902))
+
+---
+
+## 👥 Contributors
+
+### Core
+- **@teknium1** — 90 PRs across all subsystems
+
+### Community Contributors
+- **@kshitijk4poor** — 3 PRs: Signal phone number fix ([#3670](https://github.com/NousResearch/hermes-agent/pull/3670)), parallel-cli to optional-skills ([#3673](https://github.com/NousResearch/hermes-agent/pull/3673)), status bar wrapping fix ([#3883](https://github.com/NousResearch/hermes-agent/pull/3883))
+- **@winglian** — 1 PR: Plugin message injection interface ([#3778](https://github.com/NousResearch/hermes-agent/pull/3778))
+- **@binhnt92** — 1 PR: Audio download retry logic ([#3401](https://github.com/NousResearch/hermes-agent/pull/3401))
+- **@0xbyt4** — 1 PR: OpenClaw migration model config fix ([#3924](https://github.com/NousResearch/hermes-agent/pull/3924))
+
+### Issues Resolved from Community
+@Material-Scientist ([#850](https://github.com/NousResearch/hermes-agent/issues/850)), @hanxu98121 ([#1734](https://github.com/NousResearch/hermes-agent/issues/1734)), @penwyp ([#1788](https://github.com/NousResearch/hermes-agent/issues/1788)), @dan-and ([#1945](https://github.com/NousResearch/hermes-agent/issues/1945)), @AdrianScott ([#1963](https://github.com/NousResearch/hermes-agent/issues/1963)), @clawdbot47 ([#3229](https://github.com/NousResearch/hermes-agent/issues/3229)), @alanfwilliams ([#3404](https://github.com/NousResearch/hermes-agent/issues/3404)), @kentimsit ([#3433](https://github.com/NousResearch/hermes-agent/issues/3433)), @hayka-pacha ([#3534](https://github.com/NousResearch/hermes-agent/issues/3534)), @primmer ([#3595](https://github.com/NousResearch/hermes-agent/issues/3595)), @dagelf ([#3609](https://github.com/NousResearch/hermes-agent/issues/3609)), @HenkDz ([#3685](https://github.com/NousResearch/hermes-agent/issues/3685)), @tmdgusya ([#3729](https://github.com/NousResearch/hermes-agent/issues/3729)), @TypQxQ ([#3753](https://github.com/NousResearch/hermes-agent/issues/3753)), @acsezen ([#3765](https://github.com/NousResearch/hermes-agent/issues/3765))
+
+---
+
+**Full Changelog**: [v2026.3.28...v2026.3.30](https://github.com/NousResearch/hermes-agent/compare/v2026.3.28...v2026.3.30)

RELEASE_v0.7.0.md

@@ -0,0 +1,290 @@
+# Hermes Agent v0.7.0 (v2026.4.3)
+
+**Release Date:** April 3, 2026
+
+> The resilience release — pluggable memory providers, credential pool rotation, Camofox anti-detection browser, inline diff previews, gateway hardening across race conditions and approval routing, and deep security fixes across 168 PRs and 46 resolved issues.
+
+---
+
+## ✨ Highlights
+
+- **Pluggable Memory Provider Interface** — Memory is now an extensible plugin system. Third-party memory backends (Honcho, vector stores, custom DBs) implement a simple provider ABC and register via the plugin system. Built-in memory is the default provider. Honcho integration restored to full parity as the reference plugin with profile-scoped host/peer resolution. ([#4623](https://github.com/NousResearch/hermes-agent/pull/4623), [#4616](https://github.com/NousResearch/hermes-agent/pull/4616), [#4355](https://github.com/NousResearch/hermes-agent/pull/4355))
+
+- **Same-Provider Credential Pools** — Configure multiple API keys for the same provider with automatic rotation. Thread-safe `least_used` strategy distributes load across keys, and 401 failures trigger automatic rotation to the next credential. Set up via the setup wizard or `credential_pool` config. ([#4188](https://github.com/NousResearch/hermes-agent/pull/4188), [#4300](https://github.com/NousResearch/hermes-agent/pull/4300), [#4361](https://github.com/NousResearch/hermes-agent/pull/4361))
+
+- **Camofox Anti-Detection Browser Backend** — New local browser backend using Camoufox for stealth browsing. Persistent sessions with VNC URL discovery for visual debugging, configurable SSRF bypass for local backends, auto-install via `hermes tools`. ([#4008](https://github.com/NousResearch/hermes-agent/pull/4008), [#4419](https://github.com/NousResearch/hermes-agent/pull/4419), [#4292](https://github.com/NousResearch/hermes-agent/pull/4292))
+
+- **Inline Diff Previews** — File write and patch operations now show inline diffs in the tool activity feed, giving you visual confirmation of what changed before the agent moves on. ([#4411](https://github.com/NousResearch/hermes-agent/pull/4411), [#4423](https://github.com/NousResearch/hermes-agent/pull/4423))
+
+- **API Server Session Continuity & Tool Streaming** — The API server (Open WebUI integration) now streams tool progress events in real-time and supports `X-Hermes-Session-Id` headers for persistent sessions across requests. Sessions persist to the shared SessionDB. ([#4092](https://github.com/NousResearch/hermes-agent/pull/4092), [#4478](https://github.com/NousResearch/hermes-agent/pull/4478), [#4802](https://github.com/NousResearch/hermes-agent/pull/4802))
+
+- **ACP: Client-Provided MCP Servers** — Editor integrations (VS Code, Zed, JetBrains) can now register their own MCP servers, which Hermes picks up as additional agent tools. Your editor's MCP ecosystem flows directly into the agent. ([#4705](https://github.com/NousResearch/hermes-agent/pull/4705))
+
+- **Gateway Hardening** — Major stability pass across race conditions, photo media delivery, flood control, stuck sessions, approval routing, and compression death spirals. The gateway is substantially more reliable in production. ([#4727](https://github.com/NousResearch/hermes-agent/pull/4727), [#4750](https://github.com/NousResearch/hermes-agent/pull/4750), [#4798](https://github.com/NousResearch/hermes-agent/pull/4798), [#4557](https://github.com/NousResearch/hermes-agent/pull/4557))
+
+- **Security: Secret Exfiltration Blocking** — Browser URLs and LLM responses are now scanned for secret patterns, blocking exfiltration attempts via URL encoding, base64, or prompt injection. Credential directory protections expanded to `.docker`, `.azure`, `.config/gh`. Execute_code sandbox output is redacted. ([#4483](https://github.com/NousResearch/hermes-agent/pull/4483), [#4360](https://github.com/NousResearch/hermes-agent/pull/4360), [#4305](https://github.com/NousResearch/hermes-agent/pull/4305), [#4327](https://github.com/NousResearch/hermes-agent/pull/4327))
+
+---
+
+## 🏗️ Core Agent & Architecture
+
+### Provider & Model Support
+- **Same-provider credential pools** — configure multiple API keys with automatic `least_used` rotation and 401 failover ([#4188](https://github.com/NousResearch/hermes-agent/pull/4188), [#4300](https://github.com/NousResearch/hermes-agent/pull/4300))
+- **Credential pool preserved through smart routing** — pool state survives fallback provider switches and defers eager fallback on 429 ([#4361](https://github.com/NousResearch/hermes-agent/pull/4361))
+- **Per-turn primary runtime restoration** — after fallback provider use, the agent automatically restores the primary provider on the next turn with transport recovery ([#4624](https://github.com/NousResearch/hermes-agent/pull/4624))
+- **`developer` role for GPT-5 and Codex models** — uses OpenAI's recommended system message role for newer models ([#4498](https://github.com/NousResearch/hermes-agent/pull/4498))
+- **Google model operational guidance** — Gemini and Gemma models get provider-specific prompting guidance ([#4641](https://github.com/NousResearch/hermes-agent/pull/4641))
+- **Anthropic long-context tier 429 handling** — automatically reduces context to 200k when hitting tier limits ([#4747](https://github.com/NousResearch/hermes-agent/pull/4747))
+- **URL-based auth for third-party Anthropic endpoints** + CI test fixes ([#4148](https://github.com/NousResearch/hermes-agent/pull/4148))
+- **Bearer auth for MiniMax Anthropic endpoints** ([#4028](https://github.com/NousResearch/hermes-agent/pull/4028))
+- **Fireworks context length detection** ([#4158](https://github.com/NousResearch/hermes-agent/pull/4158))
+- **Standard DashScope international endpoint** for Alibaba provider ([#4133](https://github.com/NousResearch/hermes-agent/pull/4133), closes [#3912](https://github.com/NousResearch/hermes-agent/issues/3912))
+- **Custom providers context_length** honored in hygiene compression ([#4085](https://github.com/NousResearch/hermes-agent/pull/4085))
+- **Non-sk-ant keys** treated as regular API keys, not OAuth tokens ([#4093](https://github.com/NousResearch/hermes-agent/pull/4093))
+- **Claude-sonnet-4.6** added to OpenRouter and Nous model lists ([#4157](https://github.com/NousResearch/hermes-agent/pull/4157))
+- **Qwen 3.6 Plus Preview** added to model lists ([#4376](https://github.com/NousResearch/hermes-agent/pull/4376))
+- **MiniMax M2.7** added to hermes model picker and OpenCode ([#4208](https://github.com/NousResearch/hermes-agent/pull/4208))
+- **Auto-detect models from server probe** in custom endpoint setup ([#4218](https://github.com/NousResearch/hermes-agent/pull/4218))
+- **Config.yaml single source of truth** for endpoint URLs — no more env var vs config.yaml conflicts ([#4165](https://github.com/NousResearch/hermes-agent/pull/4165))
+- **Setup wizard no longer overwrites** custom endpoint config ([#4180](https://github.com/NousResearch/hermes-agent/pull/4180), closes [#4172](https://github.com/NousResearch/hermes-agent/issues/4172))
+- **Unified setup wizard provider selection** with `hermes model` — single code path for both flows ([#4200](https://github.com/NousResearch/hermes-agent/pull/4200))
+- **Root-level provider config** no longer overrides `model.provider` ([#4329](https://github.com/NousResearch/hermes-agent/pull/4329))
+- **Rate-limit pairing rejection messages** to prevent spam ([#4081](https://github.com/NousResearch/hermes-agent/pull/4081))
+
+### Agent Loop & Conversation
+- **Preserve Anthropic thinking block signatures** across tool-use turns ([#4626](https://github.com/NousResearch/hermes-agent/pull/4626))
+- **Classify think-only empty responses** before retrying — prevents infinite retry loops on models that produce thinking blocks without content ([#4645](https://github.com/NousResearch/hermes-agent/pull/4645))
+- **Prevent compression death spiral** from API disconnects — stops the loop where compression triggers, fails, compresses again ([#4750](https://github.com/NousResearch/hermes-agent/pull/4750), closes [#2153](https://github.com/NousResearch/hermes-agent/issues/2153))
+- **Persist compressed context** to gateway session after mid-run compression ([#4095](https://github.com/NousResearch/hermes-agent/pull/4095))
+- **Context-exceeded error messages** now include actionable guidance ([#4155](https://github.com/NousResearch/hermes-agent/pull/4155), closes [#4061](https://github.com/NousResearch/hermes-agent/issues/4061))
+- **Strip orphaned think/reasoning tags** from user-facing responses ([#4311](https://github.com/NousResearch/hermes-agent/pull/4311), closes [#4285](https://github.com/NousResearch/hermes-agent/issues/4285))
+- **Harden Codex responses preflight** and stream error handling ([#4313](https://github.com/NousResearch/hermes-agent/pull/4313))
+- **Deterministic call_id fallbacks** instead of random UUIDs for prompt cache consistency ([#3991](https://github.com/NousResearch/hermes-agent/pull/3991))
+- **Context pressure warning spam** prevented after compression ([#4012](https://github.com/NousResearch/hermes-agent/pull/4012))
+- **AsyncOpenAI created lazily** in trajectory compressor to avoid closed event loop errors ([#4013](https://github.com/NousResearch/hermes-agent/pull/4013))
+
+### Memory & Sessions
+- **Pluggable memory provider interface** — ABC-based plugin system for custom memory backends with profile isolation ([#4623](https://github.com/NousResearch/hermes-agent/pull/4623))
+- **Honcho full integration parity** restored as reference memory provider plugin ([#4355](https://github.com/NousResearch/hermes-agent/pull/4355)) — @erosika
+- **Honcho profile-scoped** host and peer resolution ([#4616](https://github.com/NousResearch/hermes-agent/pull/4616))
+- **Memory flush state persisted** to prevent redundant re-flushes on gateway restart ([#4481](https://github.com/NousResearch/hermes-agent/pull/4481))
+- **Memory provider tools** routed through sequential execution path ([#4803](https://github.com/NousResearch/hermes-agent/pull/4803))
+- **Honcho config** written to instance-local path for profile isolation ([#4037](https://github.com/NousResearch/hermes-agent/pull/4037))
+- **API server sessions** persist to shared SessionDB ([#4802](https://github.com/NousResearch/hermes-agent/pull/4802))
+- **Token usage persisted** for non-CLI sessions ([#4627](https://github.com/NousResearch/hermes-agent/pull/4627))
+- **Quote dotted terms in FTS5 queries** — fixes session search for terms containing dots ([#4549](https://github.com/NousResearch/hermes-agent/pull/4549))
+
+---
+
+## 📱 Messaging Platforms (Gateway)
+
+### Gateway Core
+- **Race condition fixes** — photo media loss, flood control, stuck sessions, and STT config issues resolved in one hardening pass ([#4727](https://github.com/NousResearch/hermes-agent/pull/4727))
+- **Approval routing through running-agent guard** — `/approve` and `/deny` now route correctly when the agent is blocked waiting for approval instead of being swallowed as interrupts ([#4798](https://github.com/NousResearch/hermes-agent/pull/4798), [#4557](https://github.com/NousResearch/hermes-agent/pull/4557), closes [#4542](https://github.com/NousResearch/hermes-agent/issues/4542))
+- **Resume agent after /approve** — tool result is no longer lost when executing blocked commands ([#4418](https://github.com/NousResearch/hermes-agent/pull/4418))
+- **DM thread sessions seeded** with parent transcript to preserve context ([#4559](https://github.com/NousResearch/hermes-agent/pull/4559))
+- **Skill-aware slash commands** — gateway dynamically registers installed skills as slash commands with paginated `/commands` list and Telegram 100-command cap ([#3934](https://github.com/NousResearch/hermes-agent/pull/3934), [#4005](https://github.com/NousResearch/hermes-agent/pull/4005), [#4006](https://github.com/NousResearch/hermes-agent/pull/4006), [#4010](https://github.com/NousResearch/hermes-agent/pull/4010), [#4023](https://github.com/NousResearch/hermes-agent/pull/4023))
+- **Per-platform disabled skills** respected in Telegram menu and gateway dispatch ([#4799](https://github.com/NousResearch/hermes-agent/pull/4799))
+- **Remove user-facing compression warnings** — cleaner message flow ([#4139](https://github.com/NousResearch/hermes-agent/pull/4139))
+- **`-v/-q` flags wired to stderr logging** for gateway service ([#4474](https://github.com/NousResearch/hermes-agent/pull/4474))
+- **HERMES_HOME remapped** to target user in system service unit ([#4456](https://github.com/NousResearch/hermes-agent/pull/4456))
+- **Honor default for invalid bool-like config values** ([#4029](https://github.com/NousResearch/hermes-agent/pull/4029))
+- **setsid instead of systemd-run** for `/update` command to avoid systemd permission issues ([#4104](https://github.com/NousResearch/hermes-agent/pull/4104), closes [#4017](https://github.com/NousResearch/hermes-agent/issues/4017))
+- **'Initializing agent...'** shown on first message for better UX ([#4086](https://github.com/NousResearch/hermes-agent/pull/4086))
+- **Allow running gateway service as root** for LXC/container environments ([#4732](https://github.com/NousResearch/hermes-agent/pull/4732))
+
+### Telegram
+- **32-char limit on command names** with collision avoidance ([#4211](https://github.com/NousResearch/hermes-agent/pull/4211))
+- **Priority order enforced** in menu — core > plugins > skills ([#4023](https://github.com/NousResearch/hermes-agent/pull/4023))
+- **Capped at 50 commands** — API rejects above ~60 ([#4006](https://github.com/NousResearch/hermes-agent/pull/4006))
+- **Skip empty/whitespace text** to prevent 400 errors ([#4388](https://github.com/NousResearch/hermes-agent/pull/4388))
+- **E2E gateway tests** added ([#4497](https://github.com/NousResearch/hermes-agent/pull/4497)) — @pefontana
+
+### Discord
+- **Button-based approval UI** — register `/approve` and `/deny` slash commands with interactive button prompts ([#4800](https://github.com/NousResearch/hermes-agent/pull/4800))
+- **Configurable reactions** — `discord.reactions` config option to disable message processing reactions ([#4199](https://github.com/NousResearch/hermes-agent/pull/4199))
+- **Skip reactions and auto-threading** for unauthorized users ([#4387](https://github.com/NousResearch/hermes-agent/pull/4387))
+
+### Slack
+- **Reply in thread** — `slack.reply_in_thread` config option for threaded responses ([#4643](https://github.com/NousResearch/hermes-agent/pull/4643), closes [#2662](https://github.com/NousResearch/hermes-agent/issues/2662))
+
+### WhatsApp
+- **Enforce require_mention in group chats** ([#4730](https://github.com/NousResearch/hermes-agent/pull/4730))
+
+### Webhook
+- **Platform support fixes** — skip home channel prompt, disable tool progress for webhook adapters ([#4660](https://github.com/NousResearch/hermes-agent/pull/4660))
+
+### Matrix
+- **E2EE decryption hardening** — request missing keys, auto-trust devices, retry buffered events ([#4083](https://github.com/NousResearch/hermes-agent/pull/4083))
+
+---
+
+## 🖥️ CLI & User Experience
+
+### New Slash Commands
+- **`/yolo`** — toggle dangerous command approvals on/off for the session ([#3990](https://github.com/NousResearch/hermes-agent/pull/3990))
+- **`/btw`** — ephemeral side questions that don't affect the main conversation context ([#4161](https://github.com/NousResearch/hermes-agent/pull/4161))
+- **`/profile`** — show active profile info without leaving the chat session ([#4027](https://github.com/NousResearch/hermes-agent/pull/4027))
+
+### Interactive CLI
+- **Inline diff previews** for write and patch operations in the tool activity feed ([#4411](https://github.com/NousResearch/hermes-agent/pull/4411), [#4423](https://github.com/NousResearch/hermes-agent/pull/4423))
+- **TUI pinned to bottom** on startup — no more large blank spaces between response and input ([#4412](https://github.com/NousResearch/hermes-agent/pull/4412), [#4359](https://github.com/NousResearch/hermes-agent/pull/4359), closes [#4398](https://github.com/NousResearch/hermes-agent/issues/4398), [#4421](https://github.com/NousResearch/hermes-agent/issues/4421))
+- **`/history` and `/resume`** now surface recent sessions directly instead of requiring search ([#4728](https://github.com/NousResearch/hermes-agent/pull/4728))
+- **Cache tokens shown** in `/insights` overview so total adds up ([#4428](https://github.com/NousResearch/hermes-agent/pull/4428))
+- **`--max-turns` CLI flag** for `hermes chat` to limit agent iterations ([#4314](https://github.com/NousResearch/hermes-agent/pull/4314))
+- **Detect dragged file paths** instead of treating them as slash commands ([#4533](https://github.com/NousResearch/hermes-agent/pull/4533)) — @rolme
+- **Allow empty strings and falsy values** in `config set` ([#4310](https://github.com/NousResearch/hermes-agent/pull/4310), closes [#4277](https://github.com/NousResearch/hermes-agent/issues/4277))
+- **Voice mode in WSL** when PulseAudio bridge is configured ([#4317](https://github.com/NousResearch/hermes-agent/pull/4317))
+- **Respect `NO_COLOR` env var** and `TERM=dumb` for accessibility ([#4079](https://github.com/NousResearch/hermes-agent/pull/4079), closes [#4066](https://github.com/NousResearch/hermes-agent/issues/4066)) — @SHL0MS
+- **Correct shell reload instruction** for macOS/zsh users ([#4025](https://github.com/NousResearch/hermes-agent/pull/4025))
+- **Zero exit code** on successful quiet mode queries ([#4613](https://github.com/NousResearch/hermes-agent/pull/4613), closes [#4601](https://github.com/NousResearch/hermes-agent/issues/4601)) — @devorun
+- **on_session_end hook fires** on interrupted exits ([#4159](https://github.com/NousResearch/hermes-agent/pull/4159))
+- **Profile list display** reads `model.default` key correctly ([#4160](https://github.com/NousResearch/hermes-agent/pull/4160))
+- **Browser and TTS** shown in reconfigure menu ([#4041](https://github.com/NousResearch/hermes-agent/pull/4041))
+- **Web backend priority** detection simplified ([#4036](https://github.com/NousResearch/hermes-agent/pull/4036))
+
+### Setup & Configuration
+- **Allowed_users preserved** during setup and quiet unconfigured provider warnings ([#4551](https://github.com/NousResearch/hermes-agent/pull/4551)) — @kshitijk4poor
+- **Save API key to model config** for custom endpoints ([#4202](https://github.com/NousResearch/hermes-agent/pull/4202), closes [#4182](https://github.com/NousResearch/hermes-agent/issues/4182))
+- **Claude Code credentials gated** behind explicit Hermes config in wizard trigger ([#4210](https://github.com/NousResearch/hermes-agent/pull/4210))
+- **Atomic writes in save_config_value** to prevent config loss on interrupt ([#4298](https://github.com/NousResearch/hermes-agent/pull/4298), [#4320](https://github.com/NousResearch/hermes-agent/pull/4320))
+- **Scopes field written** to Claude Code credentials on token refresh ([#4126](https://github.com/NousResearch/hermes-agent/pull/4126))
+
+### Update System
+- **Fork detection and upstream sync** in `hermes update` ([#4744](https://github.com/NousResearch/hermes-agent/pull/4744))
+- **Preserve working optional extras** when one extra fails during update ([#4550](https://github.com/NousResearch/hermes-agent/pull/4550))
+- **Handle conflicted git index** during hermes update ([#4735](https://github.com/NousResearch/hermes-agent/pull/4735))
+- **Avoid launchd restart race** on macOS ([#4736](https://github.com/NousResearch/hermes-agent/pull/4736))
+- **Missing subprocess.run() timeouts** added to doctor and status commands ([#4009](https://github.com/NousResearch/hermes-agent/pull/4009))
+
+---
+
+## 🔧 Tool System
+
+### Browser
+- **Camofox anti-detection browser backend** — local stealth browsing with auto-install via `hermes tools` ([#4008](https://github.com/NousResearch/hermes-agent/pull/4008))
+- **Persistent Camofox sessions** with VNC URL discovery for visual debugging ([#4419](https://github.com/NousResearch/hermes-agent/pull/4419))
+- **Skip SSRF check for local backends** (Camofox, headless Chromium) ([#4292](https://github.com/NousResearch/hermes-agent/pull/4292))
+- **Configurable SSRF check** via `browser.allow_private_urls` ([#4198](https://github.com/NousResearch/hermes-agent/pull/4198)) — @nils010485
+- **CAMOFOX_PORT=9377** added to Docker commands ([#4340](https://github.com/NousResearch/hermes-agent/pull/4340))
+
+### File Operations
+- **Inline diff previews** on write and patch actions ([#4411](https://github.com/NousResearch/hermes-agent/pull/4411), [#4423](https://github.com/NousResearch/hermes-agent/pull/4423))
+- **Stale file detection** on write and patch — warns when file was modified externally since last read ([#4345](https://github.com/NousResearch/hermes-agent/pull/4345))
+- **Staleness timestamp refreshed** after writes ([#4390](https://github.com/NousResearch/hermes-agent/pull/4390))
+- **Size guard, dedup, and device blocking** on read_file ([#4315](https://github.com/NousResearch/hermes-agent/pull/4315))
+
+### MCP
+- **Stability fix pack** — reload timeout, shutdown cleanup, event loop handler, OAuth non-blocking ([#4757](https://github.com/NousResearch/hermes-agent/pull/4757), closes [#4462](https://github.com/NousResearch/hermes-agent/issues/4462), [#2537](https://github.com/NousResearch/hermes-agent/issues/2537))
+
+### ACP (Editor Integration)
+- **Client-provided MCP servers** registered as agent tools — editors pass their MCP servers to Hermes ([#4705](https://github.com/NousResearch/hermes-agent/pull/4705))
+
+### Skills System
+- **Size limits for agent writes** and **fuzzy matching for skill patch** — prevents oversized skill writes and improves edit reliability ([#4414](https://github.com/NousResearch/hermes-agent/pull/4414))
+- **Validate hub bundle paths** before install — blocks path traversal in skill bundles ([#3986](https://github.com/NousResearch/hermes-agent/pull/3986))
+- **Unified hermes-agent and hermes-agent-setup** into single skill ([#4332](https://github.com/NousResearch/hermes-agent/pull/4332))
+- **Skill metadata type check** in extract_skill_conditions ([#4479](https://github.com/NousResearch/hermes-agent/pull/4479))
+
+### New/Updated Skills
+- **research-paper-writing** — full end-to-end research pipeline (replaced ml-paper-writing) ([#4654](https://github.com/NousResearch/hermes-agent/pull/4654)) — @SHL0MS
+- **ascii-video** — text readability techniques and external layout oracle ([#4054](https://github.com/NousResearch/hermes-agent/pull/4054)) — @SHL0MS
+- **youtube-transcript** updated for youtube-transcript-api v1.x ([#4455](https://github.com/NousResearch/hermes-agent/pull/4455)) — @el-analista
+- **Skills browse and search page** added to documentation site ([#4500](https://github.com/NousResearch/hermes-agent/pull/4500)) — @IAvecilla
+
+---
+
+## 🔒 Security & Reliability
+
+### Security Hardening
+- **Block secret exfiltration** via browser URLs and LLM responses — scans for secret patterns in URL encoding, base64, and prompt injection vectors ([#4483](https://github.com/NousResearch/hermes-agent/pull/4483))
+- **Redact secrets from execute_code sandbox output** ([#4360](https://github.com/NousResearch/hermes-agent/pull/4360))
+- **Protect `.docker`, `.azure`, `.config/gh` credential directories** from read/write via file tools and terminal ([#4305](https://github.com/NousResearch/hermes-agent/pull/4305), [#4327](https://github.com/NousResearch/hermes-agent/pull/4327)) — @memosr
+- **GitHub OAuth token patterns** added to redaction + snapshot redact flag ([#4295](https://github.com/NousResearch/hermes-agent/pull/4295))
+- **Reject private and loopback IPs** in Telegram DoH fallback ([#4129](https://github.com/NousResearch/hermes-agent/pull/4129))
+- **Reject path traversal** in credential file registration ([#4316](https://github.com/NousResearch/hermes-agent/pull/4316))
+- **Validate tar archive member paths** on profile import — blocks zip-slip attacks ([#4318](https://github.com/NousResearch/hermes-agent/pull/4318))
+- **Exclude auth.json and .env** from profile exports ([#4475](https://github.com/NousResearch/hermes-agent/pull/4475))
+
+### Reliability
+- **Prevent compression death spiral** from API disconnects ([#4750](https://github.com/NousResearch/hermes-agent/pull/4750), closes [#2153](https://github.com/NousResearch/hermes-agent/issues/2153))
+- **Handle `is_closed` as method** in OpenAI SDK — prevents false positive client closure detection ([#4416](https://github.com/NousResearch/hermes-agent/pull/4416), closes [#4377](https://github.com/NousResearch/hermes-agent/issues/4377))
+- **Exclude matrix from [all] extras** — python-olm is upstream-broken, prevents install failures ([#4615](https://github.com/NousResearch/hermes-agent/pull/4615), closes [#4178](https://github.com/NousResearch/hermes-agent/issues/4178))
+- **OpenCode model routing** repaired ([#4508](https://github.com/NousResearch/hermes-agent/pull/4508))
+- **Docker container image** optimized ([#4034](https://github.com/NousResearch/hermes-agent/pull/4034)) — @bcross
+
+### Windows & Cross-Platform
+- **Voice mode in WSL** with PulseAudio bridge ([#4317](https://github.com/NousResearch/hermes-agent/pull/4317))
+- **Homebrew packaging** preparation ([#4099](https://github.com/NousResearch/hermes-agent/pull/4099))
+- **CI fork conditionals** to prevent workflow failures on forks ([#4107](https://github.com/NousResearch/hermes-agent/pull/4107))
+
+---
+
+## 🐛 Notable Bug Fixes
+
+- **Gateway approval blocked agent thread** — approval now blocks the agent thread like CLI does, preventing tool result loss ([#4557](https://github.com/NousResearch/hermes-agent/pull/4557), closes [#4542](https://github.com/NousResearch/hermes-agent/issues/4542))
+- **Compression death spiral** from API disconnects — detected and halted instead of looping ([#4750](https://github.com/NousResearch/hermes-agent/pull/4750), closes [#2153](https://github.com/NousResearch/hermes-agent/issues/2153))
+- **Anthropic thinking blocks lost** across tool-use turns ([#4626](https://github.com/NousResearch/hermes-agent/pull/4626))
+- **Profile model config ignored** with `-p` flag — model.model now promoted to model.default correctly ([#4160](https://github.com/NousResearch/hermes-agent/pull/4160), closes [#4486](https://github.com/NousResearch/hermes-agent/issues/4486))
+- **CLI blank space** between response and input area ([#4412](https://github.com/NousResearch/hermes-agent/pull/4412), [#4359](https://github.com/NousResearch/hermes-agent/pull/4359), closes [#4398](https://github.com/NousResearch/hermes-agent/issues/4398))
+- **Dragged file paths** treated as slash commands instead of file references ([#4533](https://github.com/NousResearch/hermes-agent/pull/4533)) — @rolme
+- **Orphaned `</think>` tags** leaking into user-facing responses ([#4311](https://github.com/NousResearch/hermes-agent/pull/4311), closes [#4285](https://github.com/NousResearch/hermes-agent/issues/4285))
+- **OpenAI SDK `is_closed`** is a method not property — false positive client closure ([#4416](https://github.com/NousResearch/hermes-agent/pull/4416), closes [#4377](https://github.com/NousResearch/hermes-agent/issues/4377))
+- **MCP OAuth server** could block Hermes startup instead of degrading gracefully ([#4757](https://github.com/NousResearch/hermes-agent/pull/4757), closes [#4462](https://github.com/NousResearch/hermes-agent/issues/4462))
+- **MCP event loop closed** on shutdown with HTTP servers ([#4757](https://github.com/NousResearch/hermes-agent/pull/4757), closes [#2537](https://github.com/NousResearch/hermes-agent/issues/2537))
+- **Alibaba provider** hardcoded to wrong endpoint ([#4133](https://github.com/NousResearch/hermes-agent/pull/4133), closes [#3912](https://github.com/NousResearch/hermes-agent/issues/3912))
+- **Slack reply_in_thread** missing config option ([#4643](https://github.com/NousResearch/hermes-agent/pull/4643), closes [#2662](https://github.com/NousResearch/hermes-agent/issues/2662))
+- **Quiet mode exit code** — successful `-q` queries no longer exit nonzero ([#4613](https://github.com/NousResearch/hermes-agent/pull/4613), closes [#4601](https://github.com/NousResearch/hermes-agent/issues/4601))
+- **Mobile sidebar** shows only close button due to backdrop-filter issue in docs site ([#4207](https://github.com/NousResearch/hermes-agent/pull/4207)) — @xsmyile
+- **Config restore reverted** by stale-branch squash merge — `_config_version` fixed ([#4440](https://github.com/NousResearch/hermes-agent/pull/4440))
+
+---
+
+## 🧪 Testing
+
+- **Telegram gateway E2E tests** — full integration test suite for the Telegram adapter ([#4497](https://github.com/NousResearch/hermes-agent/pull/4497)) — @pefontana
+- **11 real test failures fixed** plus sys.modules cascade poisoner resolved ([#4570](https://github.com/NousResearch/hermes-agent/pull/4570))
+- **7 CI failures resolved** across hooks, plugins, and skill tests ([#3936](https://github.com/NousResearch/hermes-agent/pull/3936))
+- **Codex 401 refresh tests** updated for CI compatibility ([#4166](https://github.com/NousResearch/hermes-agent/pull/4166))
+- **Stale OPENAI_BASE_URL test** fixed ([#4217](https://github.com/NousResearch/hermes-agent/pull/4217))
+
+---
+
+## 📚 Documentation
+
+- **Comprehensive documentation audit** — 9 HIGH and 20+ MEDIUM gaps fixed across 21 files ([#4087](https://github.com/NousResearch/hermes-agent/pull/4087))
+- **Site navigation restructured** — features and platforms promoted to top-level ([#4116](https://github.com/NousResearch/hermes-agent/pull/4116))
+- **Tool progress streaming** documented for API server and Open WebUI ([#4138](https://github.com/NousResearch/hermes-agent/pull/4138))
+- **Telegram webhook mode** documentation ([#4089](https://github.com/NousResearch/hermes-agent/pull/4089))
+- **Local LLM provider guides** — comprehensive setup guides with context length warnings ([#4294](https://github.com/NousResearch/hermes-agent/pull/4294))
+- **WhatsApp allowlist behavior** clarified with `WHATSAPP_ALLOW_ALL_USERS` documentation ([#4293](https://github.com/NousResearch/hermes-agent/pull/4293))
+- **Slack configuration options** — new config section in Slack docs ([#4644](https://github.com/NousResearch/hermes-agent/pull/4644))
+- **Terminal backends section** expanded + docs build fixes ([#4016](https://github.com/NousResearch/hermes-agent/pull/4016))
+- **Adding-providers guide** updated for unified setup flow ([#4201](https://github.com/NousResearch/hermes-agent/pull/4201))
+- **ACP Zed config** fixed ([#4743](https://github.com/NousResearch/hermes-agent/pull/4743))
+- **Community FAQ** entries for common workflows and troubleshooting ([#4797](https://github.com/NousResearch/hermes-agent/pull/4797))
+- **Skills browse and search page** on docs site ([#4500](https://github.com/NousResearch/hermes-agent/pull/4500)) — @IAvecilla
+
+---
+
+## 👥 Contributors
+
+### Core
+- **@teknium1** — 135 commits across all subsystems
+
+### Top Community Contributors
+- **@kshitijk4poor** — 13 commits: preserve allowed_users during setup ([#4551](https://github.com/NousResearch/hermes-agent/pull/4551)), and various fixes
+- **@erosika** — 12 commits: Honcho full integration parity restored as memory provider plugin ([#4355](https://github.com/NousResearch/hermes-agent/pull/4355))
+- **@pefontana** — 9 commits: Telegram gateway E2E test suite ([#4497](https://github.com/NousResearch/hermes-agent/pull/4497))
+- **@bcross** — 5 commits: Docker container image optimization ([#4034](https://github.com/NousResearch/hermes-agent/pull/4034))
+- **@SHL0MS** — 4 commits: NO_COLOR/TERM=dumb support ([#4079](https://github.com/NousResearch/hermes-agent/pull/4079)), ascii-video skill updates ([#4054](https://github.com/NousResearch/hermes-agent/pull/4054)), research-paper-writing skill ([#4654](https://github.com/NousResearch/hermes-agent/pull/4654))
+
+### All Contributors
+@0xbyt4, @arasovic, @Bartok9, @bcross, @binhnt92, @camden-lowrance, @curtitoo, @Dakota, @Dave Tist, @Dean Kerr, @devorun, @dieutx, @Dilee, @el-analista, @erosika, @Gutslabs, @IAvecilla, @Jack, @Johannnnn506, @kshitijk4poor, @Laura Batalha, @Leegenux, @Lume, @MacroAnarchy, @maymuneth, @memosr, @NexVeridian, @Nick, @nils010485, @pefontana, @Penov, @rolme, @SHL0MS, @txchen, @xsmyile
+
+### Issues Resolved from Community
+@acsezen ([#2537](https://github.com/NousResearch/hermes-agent/issues/2537)), @arasovic ([#4285](https://github.com/NousResearch/hermes-agent/issues/4285)), @camden-lowrance ([#4462](https://github.com/NousResearch/hermes-agent/issues/4462)), @devorun ([#4601](https://github.com/NousResearch/hermes-agent/issues/4601)), @eloklam ([#4486](https://github.com/NousResearch/hermes-agent/issues/4486)), @HenkDz ([#3719](https://github.com/NousResearch/hermes-agent/issues/3719)), @hypotyposis ([#2153](https://github.com/NousResearch/hermes-agent/issues/2153)), @kazamak ([#4178](https://github.com/NousResearch/hermes-agent/issues/4178)), @lstep ([#4366](https://github.com/NousResearch/hermes-agent/issues/4366)), @Mark-Lok ([#4542](https://github.com/NousResearch/hermes-agent/issues/4542)), @NoJster ([#4421](https://github.com/NousResearch/hermes-agent/issues/4421)), @patp ([#2662](https://github.com/NousResearch/hermes-agent/issues/2662)), @pr0n ([#4601](https://github.com/NousResearch/hermes-agent/issues/4601)), @saulmc ([#4377](https://github.com/NousResearch/hermes-agent/issues/4377)), @SHL0MS ([#4060](https://github.com/NousResearch/hermes-agent/issues/4060), [#4061](https://github.com/NousResearch/hermes-agent/issues/4061), [#4066](https://github.com/NousResearch/hermes-agent/issues/4066), [#4172](https://github.com/NousResearch/hermes-agent/issues/4172), [#4277](https://github.com/NousResearch/hermes-agent/issues/4277)), @Z-Mackintosh ([#4398](https://github.com/NousResearch/hermes-agent/issues/4398))
+
+---
+
+**Full Changelog**: [v2026.3.30...v2026.4.3](https://github.com/NousResearch/hermes-agent/compare/v2026.3.30...v2026.4.3)

RELEASE_v0.8.0.md

@@ -0,0 +1,346 @@
+# Hermes Agent v0.8.0 (v2026.4.8)
+
+**Release Date:** April 8, 2026
+
+> The intelligence release — background task auto-notifications, free MiMo v2 Pro on Nous Portal, live model switching across all platforms, self-optimized GPT/Codex guidance, native Google AI Studio, smart inactivity timeouts, approval buttons, MCP OAuth 2.1, and 209 merged PRs with 82 resolved issues.
+
+---
+
+## ✨ Highlights
+
+- **Background Process Auto-Notifications (`notify_on_complete`)** — Background tasks can now automatically notify the agent when they finish. Start a long-running process (AI model training, test suites, deployments, builds) and the agent gets notified on completion — no polling needed. The agent can keep working on other things and pick up results when they land. ([#5779](https://github.com/NousResearch/hermes-agent/pull/5779))
+
+- **Free Xiaomi MiMo v2 Pro on Nous Portal** — Nous Portal now supports the free-tier Xiaomi MiMo v2 Pro model for auxiliary tasks (compression, vision, summarization), with free-tier model gating and pricing display in model selection. ([#6018](https://github.com/NousResearch/hermes-agent/pull/6018), [#5880](https://github.com/NousResearch/hermes-agent/pull/5880))
+
+- **Live Model Switching (`/model` Command)** — Switch models and providers mid-session from CLI, Telegram, Discord, Slack, or any gateway platform. Aggregator-aware resolution keeps you on OpenRouter/Nous when possible, with automatic cross-provider fallback when needed. Interactive model pickers on Telegram and Discord with inline buttons. ([#5181](https://github.com/NousResearch/hermes-agent/pull/5181), [#5742](https://github.com/NousResearch/hermes-agent/pull/5742))
+
+- **Self-Optimized GPT/Codex Tool-Use Guidance** — The agent diagnosed and patched 5 failure modes in GPT and Codex tool calling through automated behavioral benchmarking, dramatically improving reliability on OpenAI models. Includes execution discipline guidance and thinking-only prefill continuation for structured reasoning. ([#6120](https://github.com/NousResearch/hermes-agent/pull/6120), [#5414](https://github.com/NousResearch/hermes-agent/pull/5414), [#5931](https://github.com/NousResearch/hermes-agent/pull/5931))
+
+- **Google AI Studio (Gemini) Native Provider** — Direct access to Gemini models through Google's AI Studio API. Includes automatic models.dev registry integration for real-time context length detection across any provider. ([#5577](https://github.com/NousResearch/hermes-agent/pull/5577))
+
+- **Inactivity-Based Agent Timeouts** — Gateway and cron timeouts now track actual tool activity instead of wall-clock time. Long-running tasks that are actively working will never be killed — only truly idle agents time out. ([#5389](https://github.com/NousResearch/hermes-agent/pull/5389), [#5440](https://github.com/NousResearch/hermes-agent/pull/5440))
+
+- **Approval Buttons on Slack & Telegram** — Dangerous command approval via native platform buttons instead of typing `/approve`. Slack gets thread context preservation; Telegram gets emoji reactions for approval status. ([#5890](https://github.com/NousResearch/hermes-agent/pull/5890), [#5975](https://github.com/NousResearch/hermes-agent/pull/5975))
+
+- **MCP OAuth 2.1 PKCE + OSV Malware Scanning** — Full standards-compliant OAuth for MCP server authentication, plus automatic malware scanning of MCP extension packages via the OSV vulnerability database. ([#5420](https://github.com/NousResearch/hermes-agent/pull/5420), [#5305](https://github.com/NousResearch/hermes-agent/pull/5305))
+
+- **Centralized Logging & Config Validation** — Structured logging to `~/.hermes/logs/` (agent.log + errors.log) with the `hermes logs` command for tailing and filtering. Config structure validation catches malformed YAML at startup before it causes cryptic failures. ([#5430](https://github.com/NousResearch/hermes-agent/pull/5430), [#5426](https://github.com/NousResearch/hermes-agent/pull/5426))
+
+- **Plugin System Expansion** — Plugins can now register CLI subcommands, receive request-scoped API hooks with correlation IDs, prompt for required env vars during install, and hook into session lifecycle events (finalize/reset). ([#5295](https://github.com/NousResearch/hermes-agent/pull/5295), [#5427](https://github.com/NousResearch/hermes-agent/pull/5427), [#5470](https://github.com/NousResearch/hermes-agent/pull/5470), [#6129](https://github.com/NousResearch/hermes-agent/pull/6129))
+
+- **Matrix Tier 1 & Platform Hardening** — Matrix gets reactions, read receipts, rich formatting, and room management. Discord adds channel controls and ignored channels. Signal gets full MEDIA: tag delivery. Mattermost gets file attachments. Comprehensive reliability fixes across all platforms. ([#5275](https://github.com/NousResearch/hermes-agent/pull/5275), [#5975](https://github.com/NousResearch/hermes-agent/pull/5975), [#5602](https://github.com/NousResearch/hermes-agent/pull/5602))
+
+- **Security Hardening Pass** — Consolidated SSRF protections, timing attack mitigations, tar traversal prevention, credential leakage guards, cron path traversal hardening, and cross-session isolation. Terminal workdir sanitization across all backends. ([#5944](https://github.com/NousResearch/hermes-agent/pull/5944), [#5613](https://github.com/NousResearch/hermes-agent/pull/5613), [#5629](https://github.com/NousResearch/hermes-agent/pull/5629))
+
+---
+
+## 🏗️ Core Agent & Architecture
+
+### Provider & Model Support
+- **Native Google AI Studio (Gemini) provider** with models.dev integration for automatic context length detection ([#5577](https://github.com/NousResearch/hermes-agent/pull/5577))
+- **`/model` command — full provider+model system overhaul** — live switching across CLI and all gateway platforms with aggregator-aware resolution ([#5181](https://github.com/NousResearch/hermes-agent/pull/5181))
+- **Interactive model picker for Telegram and Discord** — inline button-based model selection ([#5742](https://github.com/NousResearch/hermes-agent/pull/5742))
+- **Nous Portal free-tier model gating** with pricing display in model selection ([#5880](https://github.com/NousResearch/hermes-agent/pull/5880))
+- **Model pricing display** for OpenRouter and Nous Portal providers ([#5416](https://github.com/NousResearch/hermes-agent/pull/5416))
+- **xAI (Grok) prompt caching** via `x-grok-conv-id` header ([#5604](https://github.com/NousResearch/hermes-agent/pull/5604))
+- **Grok added to tool-use enforcement models** for direct xAI usage ([#5595](https://github.com/NousResearch/hermes-agent/pull/5595))
+- **MiniMax TTS provider** (speech-2.8) ([#4963](https://github.com/NousResearch/hermes-agent/pull/4963))
+- **Non-agentic model warning** — warns users when loading Hermes LLM models not designed for tool use ([#5378](https://github.com/NousResearch/hermes-agent/pull/5378))
+- **Ollama Cloud auth, /model switch persistence**, and alias tab completion ([#5269](https://github.com/NousResearch/hermes-agent/pull/5269))
+- **Preserve dots in OpenCode Go model names** (minimax-m2.7, glm-4.5, kimi-k2.5) ([#5597](https://github.com/NousResearch/hermes-agent/pull/5597))
+- **MiniMax models 404 fix** — strip /v1 from Anthropic base URL for OpenCode Go ([#4918](https://github.com/NousResearch/hermes-agent/pull/4918))
+- **Provider credential reset windows** honored in pooled failover ([#5188](https://github.com/NousResearch/hermes-agent/pull/5188))
+- **OAuth token sync** between credential pool and credentials file ([#4981](https://github.com/NousResearch/hermes-agent/pull/4981))
+- **Stale OAuth credentials** no longer block OpenRouter users on auto-detect ([#5746](https://github.com/NousResearch/hermes-agent/pull/5746))
+- **Codex OAuth credential pool disconnect** + expired token import fix ([#5681](https://github.com/NousResearch/hermes-agent/pull/5681))
+- **Codex pool entry sync** from `~/.codex/auth.json` on exhaustion — @GratefulDave ([#5610](https://github.com/NousResearch/hermes-agent/pull/5610))
+- **Auxiliary client payment fallback** — retry with next provider on 402 ([#5599](https://github.com/NousResearch/hermes-agent/pull/5599))
+- **Auxiliary client resolves named custom providers** and 'main' alias ([#5978](https://github.com/NousResearch/hermes-agent/pull/5978))
+- **Use mimo-v2-pro** for non-vision auxiliary tasks on Nous free tier ([#6018](https://github.com/NousResearch/hermes-agent/pull/6018))
+- **Vision auto-detection** tries main provider first ([#6041](https://github.com/NousResearch/hermes-agent/pull/6041))
+- **Provider re-ordering and Quick Install** — @austinpickett ([#4664](https://github.com/NousResearch/hermes-agent/pull/4664))
+- **Nous OAuth access_token** no longer used as inference API key — @SHL0MS ([#5564](https://github.com/NousResearch/hermes-agent/pull/5564))
+- **HERMES_PORTAL_BASE_URL env var** respected during Nous login — @benbarclay ([#5745](https://github.com/NousResearch/hermes-agent/pull/5745))
+- **Env var overrides** for Nous portal/inference URLs ([#5419](https://github.com/NousResearch/hermes-agent/pull/5419))
+- **Z.AI endpoint auto-detect** via probe and cache ([#5763](https://github.com/NousResearch/hermes-agent/pull/5763))
+- **MiniMax context lengths, model catalog, thinking guard, aux model, and config base_url** corrections ([#6082](https://github.com/NousResearch/hermes-agent/pull/6082))
+- **Community provider/model resolution fixes** — salvaged 4 community PRs + MiniMax aux URL ([#5983](https://github.com/NousResearch/hermes-agent/pull/5983))
+
+### Agent Loop & Conversation
+- **Self-optimized GPT/Codex tool-use guidance** via automated behavioral benchmarking — agent self-diagnosed and patched 5 failure modes ([#6120](https://github.com/NousResearch/hermes-agent/pull/6120))
+- **GPT/Codex execution discipline guidance** in system prompts ([#5414](https://github.com/NousResearch/hermes-agent/pull/5414))
+- **Thinking-only prefill continuation** for structured reasoning responses ([#5931](https://github.com/NousResearch/hermes-agent/pull/5931))
+- **Accept reasoning-only responses** without retries — set content to "(empty)" instead of infinite retry ([#5278](https://github.com/NousResearch/hermes-agent/pull/5278))
+- **Jittered retry backoff** — exponential backoff with jitter for API retries ([#6048](https://github.com/NousResearch/hermes-agent/pull/6048))
+- **Smart thinking block signature management** — preserve and manage Anthropic thinking signatures across turns ([#6112](https://github.com/NousResearch/hermes-agent/pull/6112))
+- **Coerce tool call arguments** to match JSON Schema types — fixes models that send strings instead of numbers/booleans ([#5265](https://github.com/NousResearch/hermes-agent/pull/5265))
+- **Save oversized tool results to file** instead of destructive truncation ([#5210](https://github.com/NousResearch/hermes-agent/pull/5210))
+- **Sandbox-aware tool result persistence** ([#6085](https://github.com/NousResearch/hermes-agent/pull/6085))
+- **Streaming fallback** improved after edit failures ([#6110](https://github.com/NousResearch/hermes-agent/pull/6110))
+- **Codex empty-output gaps** covered in fallback + normalizer + auxiliary client ([#5724](https://github.com/NousResearch/hermes-agent/pull/5724), [#5730](https://github.com/NousResearch/hermes-agent/pull/5730), [#5734](https://github.com/NousResearch/hermes-agent/pull/5734))
+- **Codex stream output backfill** from output_item.done events ([#5689](https://github.com/NousResearch/hermes-agent/pull/5689))
+- **Stream consumer creates new message** after tool boundaries ([#5739](https://github.com/NousResearch/hermes-agent/pull/5739))
+- **Codex validation aligned** with normalization for empty stream output ([#5940](https://github.com/NousResearch/hermes-agent/pull/5940))
+- **Bridge tool-calls** in copilot-acp adapter ([#5460](https://github.com/NousResearch/hermes-agent/pull/5460))
+- **Filter transcript-only roles** from chat-completions payload ([#4880](https://github.com/NousResearch/hermes-agent/pull/4880))
+- **Context compaction failures fixed** on temperature-restricted models — @MadKangYu ([#5608](https://github.com/NousResearch/hermes-agent/pull/5608))
+- **Sanitize tool_calls for all strict APIs** (Fireworks, Mistral, etc.) — @lumethegreat ([#5183](https://github.com/NousResearch/hermes-agent/pull/5183))
+
+### Memory & Sessions
+- **Supermemory memory provider** — new memory plugin with multi-container, search_mode, identity template, and env var override ([#5737](https://github.com/NousResearch/hermes-agent/pull/5737), [#5933](https://github.com/NousResearch/hermes-agent/pull/5933))
+- **Shared thread sessions** by default — multi-user thread support across gateway platforms ([#5391](https://github.com/NousResearch/hermes-agent/pull/5391))
+- **Subagent sessions linked to parent** and hidden from session list ([#5309](https://github.com/NousResearch/hermes-agent/pull/5309))
+- **Profile-scoped memory isolation** and clone support ([#4845](https://github.com/NousResearch/hermes-agent/pull/4845))
+- **Thread gateway user_id to memory plugins** for per-user scoping ([#5895](https://github.com/NousResearch/hermes-agent/pull/5895))
+- **Honcho plugin drift overhaul** + plugin CLI registration system ([#5295](https://github.com/NousResearch/hermes-agent/pull/5295))
+- **Honcho holographic prompt and trust score** rendering preserved ([#4872](https://github.com/NousResearch/hermes-agent/pull/4872))
+- **Honcho doctor fix** — use recall_mode instead of memory_mode — @techguysimon ([#5645](https://github.com/NousResearch/hermes-agent/pull/5645))
+- **RetainDB** — API routes, write queue, dialectic, agent model, file tools fixes ([#5461](https://github.com/NousResearch/hermes-agent/pull/5461))
+- **Hindsight memory plugin overhaul** + memory setup wizard fixes ([#5094](https://github.com/NousResearch/hermes-agent/pull/5094))
+- **mem0 API v2 compat**, prefetch context fencing, secret redaction ([#5423](https://github.com/NousResearch/hermes-agent/pull/5423))
+- **mem0 env vars merged** with mem0.json instead of either/or ([#4939](https://github.com/NousResearch/hermes-agent/pull/4939))
+- **Clean user message** used for all memory provider operations ([#4940](https://github.com/NousResearch/hermes-agent/pull/4940))
+- **Silent memory flush failure** on /new and /resume fixed — @ryanautomated ([#5640](https://github.com/NousResearch/hermes-agent/pull/5640))
+- **OpenViking atexit safety net** for session commit ([#5664](https://github.com/NousResearch/hermes-agent/pull/5664))
+- **OpenViking tenant-scoping headers** for multi-tenant servers ([#4936](https://github.com/NousResearch/hermes-agent/pull/4936))
+- **ByteRover brv query** runs synchronously before LLM call ([#4831](https://github.com/NousResearch/hermes-agent/pull/4831))
+
+---
+
+## 📱 Messaging Platforms (Gateway)
+
+### Gateway Core
+- **Inactivity-based agent timeout** — replaces wall-clock timeout with smart activity tracking; long-running active tasks never killed ([#5389](https://github.com/NousResearch/hermes-agent/pull/5389))
+- **Approval buttons for Slack & Telegram** + Slack thread context preservation ([#5890](https://github.com/NousResearch/hermes-agent/pull/5890))
+- **Live-stream /update output** + forward interactive prompts to user ([#5180](https://github.com/NousResearch/hermes-agent/pull/5180))
+- **Infinite timeout support** + periodic notifications + actionable error messages ([#4959](https://github.com/NousResearch/hermes-agent/pull/4959))
+- **Duplicate message prevention** — gateway dedup + partial stream guard ([#4878](https://github.com/NousResearch/hermes-agent/pull/4878))
+- **Webhook delivery_info persistence** + full session id in /status ([#5942](https://github.com/NousResearch/hermes-agent/pull/5942))
+- **Tool preview truncation** respects tool_preview_length in all/new progress modes ([#5937](https://github.com/NousResearch/hermes-agent/pull/5937))
+- **Short preview truncation** restored for all/new tool progress modes ([#4935](https://github.com/NousResearch/hermes-agent/pull/4935))
+- **Update-pending state** written atomically to prevent corruption ([#4923](https://github.com/NousResearch/hermes-agent/pull/4923))
+- **Approval session key isolated** per turn ([#4884](https://github.com/NousResearch/hermes-agent/pull/4884))
+- **Active-session guard bypass** for /approve, /deny, /stop, /new ([#4926](https://github.com/NousResearch/hermes-agent/pull/4926), [#5765](https://github.com/NousResearch/hermes-agent/pull/5765))
+- **Typing indicator paused** during approval waits ([#5893](https://github.com/NousResearch/hermes-agent/pull/5893))
+- **Caption check** uses exact line-by-line match instead of substring (all platforms) ([#5939](https://github.com/NousResearch/hermes-agent/pull/5939))
+- **MEDIA: tags stripped** from streamed gateway messages ([#5152](https://github.com/NousResearch/hermes-agent/pull/5152))
+- **MEDIA: tags extracted** from cron delivery before sending ([#5598](https://github.com/NousResearch/hermes-agent/pull/5598))
+- **Profile-aware service units** + voice transcription cleanup ([#5972](https://github.com/NousResearch/hermes-agent/pull/5972))
+- **Thread-safe PairingStore** with atomic writes — @CharlieKerfoot ([#5656](https://github.com/NousResearch/hermes-agent/pull/5656))
+- **Sanitize media URLs** in base platform logs — @WAXLYY ([#5631](https://github.com/NousResearch/hermes-agent/pull/5631))
+- **Reduce Telegram fallback IP activation log noise** — @MadKangYu ([#5615](https://github.com/NousResearch/hermes-agent/pull/5615))
+- **Cron static method wrappers** to prevent self-binding ([#5299](https://github.com/NousResearch/hermes-agent/pull/5299))
+- **Stale 'hermes login' replaced** with 'hermes auth' + credential removal re-seeding fix ([#5670](https://github.com/NousResearch/hermes-agent/pull/5670))
+
+### Telegram
+- **Group topics skill binding** for supergroup forum topics ([#4886](https://github.com/NousResearch/hermes-agent/pull/4886))
+- **Emoji reactions** for approval status and notifications ([#5975](https://github.com/NousResearch/hermes-agent/pull/5975))
+- **Duplicate message delivery prevented** on send timeout ([#5153](https://github.com/NousResearch/hermes-agent/pull/5153))
+- **Command names sanitized** to strip invalid characters ([#5596](https://github.com/NousResearch/hermes-agent/pull/5596))
+- **Per-platform disabled skills** respected in Telegram menu and gateway dispatch ([#4799](https://github.com/NousResearch/hermes-agent/pull/4799))
+- **/approve and /deny** routed through running-agent guard ([#4798](https://github.com/NousResearch/hermes-agent/pull/4798))
+
+### Discord
+- **Channel controls** — ignored_channels and no_thread_channels config options ([#5975](https://github.com/NousResearch/hermes-agent/pull/5975))
+- **Skills registered as native slash commands** via shared gateway logic ([#5603](https://github.com/NousResearch/hermes-agent/pull/5603))
+- **/approve, /deny, /queue, /background, /btw** registered as native slash commands ([#4800](https://github.com/NousResearch/hermes-agent/pull/4800), [#5477](https://github.com/NousResearch/hermes-agent/pull/5477))
+- **Unnecessary members intent** removed on startup + token lock leak fix ([#5302](https://github.com/NousResearch/hermes-agent/pull/5302))
+
+### Slack
+- **Thread engagement** — auto-respond in bot-started and mentioned threads ([#5897](https://github.com/NousResearch/hermes-agent/pull/5897))
+- **mrkdwn in edit_message** + thread replies without @mentions ([#5733](https://github.com/NousResearch/hermes-agent/pull/5733))
+
+### Matrix
+- **Tier 1 feature parity** — reactions, read receipts, rich formatting, room management ([#5275](https://github.com/NousResearch/hermes-agent/pull/5275))
+- **MATRIX_REQUIRE_MENTION and MATRIX_AUTO_THREAD** support ([#5106](https://github.com/NousResearch/hermes-agent/pull/5106))
+- **Comprehensive reliability** — encrypted media, auth recovery, cron E2EE, Synapse compat ([#5271](https://github.com/NousResearch/hermes-agent/pull/5271))
+- **CJK input, E2EE, and reconnect** fixes ([#5665](https://github.com/NousResearch/hermes-agent/pull/5665))
+
+### Signal
+- **Full MEDIA: tag delivery** — send_image_file, send_voice, and send_video implemented ([#5602](https://github.com/NousResearch/hermes-agent/pull/5602))
+
+### Mattermost
+- **File attachments** — set message type to DOCUMENT when post has file attachments — @nericervin ([#5609](https://github.com/NousResearch/hermes-agent/pull/5609))
+
+### Feishu
+- **Interactive card approval buttons** ([#6043](https://github.com/NousResearch/hermes-agent/pull/6043))
+- **Reconnect and ACL** fixes ([#5665](https://github.com/NousResearch/hermes-agent/pull/5665))
+
+### Webhooks
+- **`{__raw__}` template token** and thread_id passthrough for forum topics ([#5662](https://github.com/NousResearch/hermes-agent/pull/5662))
+
+---
+
+## 🖥️ CLI & User Experience
+
+### Interactive CLI
+- **Defer response content** until reasoning block completes ([#5773](https://github.com/NousResearch/hermes-agent/pull/5773))
+- **Ghost status-bar lines cleared** on terminal resize ([#4960](https://github.com/NousResearch/hermes-agent/pull/4960))
+- **Normalise \r\n and \r line endings** in pasted text ([#4849](https://github.com/NousResearch/hermes-agent/pull/4849))
+- **ChatConsole errors, curses scroll, skin-aware banner, git state** banner fixes ([#5974](https://github.com/NousResearch/hermes-agent/pull/5974))
+- **Native Windows image paste** support ([#5917](https://github.com/NousResearch/hermes-agent/pull/5917))
+- **--yolo and other flags** no longer silently dropped when placed before 'chat' subcommand ([#5145](https://github.com/NousResearch/hermes-agent/pull/5145))
+
+### Setup & Configuration
+- **Config structure validation** — detect malformed YAML at startup with actionable error messages ([#5426](https://github.com/NousResearch/hermes-agent/pull/5426))
+- **Centralized logging** to `~/.hermes/logs/` — agent.log (INFO+), errors.log (WARNING+) with `hermes logs` command ([#5430](https://github.com/NousResearch/hermes-agent/pull/5430))
+- **Docs links added** to setup wizard sections ([#5283](https://github.com/NousResearch/hermes-agent/pull/5283))
+- **Doctor diagnostics** — sync provider checks, config migration, WAL and mem0 diagnostics ([#5077](https://github.com/NousResearch/hermes-agent/pull/5077))
+- **Timeout debug logging** and user-facing diagnostics improved ([#5370](https://github.com/NousResearch/hermes-agent/pull/5370))
+- **Reasoning effort unified** to config.yaml only ([#6118](https://github.com/NousResearch/hermes-agent/pull/6118))
+- **Permanent command allowlist** loaded on startup ([#5076](https://github.com/NousResearch/hermes-agent/pull/5076))
+- **`hermes auth remove`** now clears env-seeded credentials permanently ([#5285](https://github.com/NousResearch/hermes-agent/pull/5285))
+- **Bundled skills synced to all profiles** during update ([#5795](https://github.com/NousResearch/hermes-agent/pull/5795))
+- **`hermes update` no longer kills** freshly-restarted gateway service ([#5448](https://github.com/NousResearch/hermes-agent/pull/5448))
+- **Subprocess.run() timeouts** added to all gateway CLI commands ([#5424](https://github.com/NousResearch/hermes-agent/pull/5424))
+- **Actionable error message** when Codex refresh token is reused — @tymrtn ([#5612](https://github.com/NousResearch/hermes-agent/pull/5612))
+- **Google-workspace skill scripts** can now run directly — @xinbenlv ([#5624](https://github.com/NousResearch/hermes-agent/pull/5624))
+
+### Cron System
+- **Inactivity-based cron timeout** — replaces wall-clock; active tasks run indefinitely ([#5440](https://github.com/NousResearch/hermes-agent/pull/5440))
+- **Pre-run script injection** for data collection and change detection ([#5082](https://github.com/NousResearch/hermes-agent/pull/5082))
+- **Delivery failure tracking** in job status ([#6042](https://github.com/NousResearch/hermes-agent/pull/6042))
+- **Delivery guidance** in cron prompts — stops send_message thrashing ([#5444](https://github.com/NousResearch/hermes-agent/pull/5444))
+- **MEDIA files delivered** as native platform attachments ([#5921](https://github.com/NousResearch/hermes-agent/pull/5921))
+- **[SILENT] suppression** works anywhere in response — @auspic7 ([#5654](https://github.com/NousResearch/hermes-agent/pull/5654))
+- **Cron path traversal** hardening ([#5147](https://github.com/NousResearch/hermes-agent/pull/5147))
+
+---
+
+## 🔧 Tool System
+
+### Terminal & Execution
+- **Execute_code on remote backends** — code execution now works on Docker, SSH, Modal, and other remote terminal backends ([#5088](https://github.com/NousResearch/hermes-agent/pull/5088))
+- **Exit code context** for common CLI tools in terminal results — helps agent understand what went wrong ([#5144](https://github.com/NousResearch/hermes-agent/pull/5144))
+- **Progressive subdirectory hint discovery** — agent learns project structure as it navigates ([#5291](https://github.com/NousResearch/hermes-agent/pull/5291))
+- **notify_on_complete for background processes** — get notified when long-running tasks finish ([#5779](https://github.com/NousResearch/hermes-agent/pull/5779))
+- **Docker env config** — explicit container environment variables via docker_env config ([#4738](https://github.com/NousResearch/hermes-agent/pull/4738))
+- **Approval metadata included** in terminal tool results ([#5141](https://github.com/NousResearch/hermes-agent/pull/5141))
+- **Workdir parameter sanitized** in terminal tool across all backends ([#5629](https://github.com/NousResearch/hermes-agent/pull/5629))
+- **Detached process crash recovery** state corrected ([#6101](https://github.com/NousResearch/hermes-agent/pull/6101))
+- **Agent-browser paths with spaces** preserved — @Vasanthdev2004 ([#6077](https://github.com/NousResearch/hermes-agent/pull/6077))
+- **Portable base64 encoding** for image reading on macOS — @CharlieKerfoot ([#5657](https://github.com/NousResearch/hermes-agent/pull/5657))
+
+### Browser
+- **Switch managed browser provider** from Browserbase to Browser Use — @benbarclay ([#5750](https://github.com/NousResearch/hermes-agent/pull/5750))
+- **Firecrawl cloud browser** provider — @alt-glitch ([#5628](https://github.com/NousResearch/hermes-agent/pull/5628))
+- **JS evaluation** via browser_console expression parameter ([#5303](https://github.com/NousResearch/hermes-agent/pull/5303))
+- **Windows browser** fixes ([#5665](https://github.com/NousResearch/hermes-agent/pull/5665))
+
+### MCP
+- **MCP OAuth 2.1 PKCE** — full standards-compliant OAuth client support ([#5420](https://github.com/NousResearch/hermes-agent/pull/5420))
+- **OSV malware check** for MCP extension packages ([#5305](https://github.com/NousResearch/hermes-agent/pull/5305))
+- **Prefer structuredContent over text** + no_mcp sentinel ([#5979](https://github.com/NousResearch/hermes-agent/pull/5979))
+- **Unknown toolsets warning suppressed** for MCP server names ([#5279](https://github.com/NousResearch/hermes-agent/pull/5279))
+
+### Web & Files
+- **.zip document support** + auto-mount cache dirs into remote backends ([#4846](https://github.com/NousResearch/hermes-agent/pull/4846))
+- **Redact query secrets** in send_message errors — @WAXLYY ([#5650](https://github.com/NousResearch/hermes-agent/pull/5650))
+
+### Delegation
+- **Credential pool sharing** + workspace path hints for subagents ([#5748](https://github.com/NousResearch/hermes-agent/pull/5748))
+
+### ACP (VS Code / Zed / JetBrains)
+- **Aggregate ACP improvements** — auth compat, protocol fixes, command ads, delegation, SSE events ([#5292](https://github.com/NousResearch/hermes-agent/pull/5292))
+
+---
+
+## 🧩 Skills Ecosystem
+
+### Skills System
+- **Skill config interface** — skills can declare required config.yaml settings, prompted during setup, injected at load time ([#5635](https://github.com/NousResearch/hermes-agent/pull/5635))
+- **Plugin CLI registration system** — plugins register their own CLI subcommands without touching main.py ([#5295](https://github.com/NousResearch/hermes-agent/pull/5295))
+- **Request-scoped API hooks** with tool call correlation IDs for plugins ([#5427](https://github.com/NousResearch/hermes-agent/pull/5427))
+- **Session lifecycle hooks** — on_session_finalize and on_session_reset for CLI + gateway ([#6129](https://github.com/NousResearch/hermes-agent/pull/6129))
+- **Prompt for required env vars** during plugin install — @kshitijk4poor ([#5470](https://github.com/NousResearch/hermes-agent/pull/5470))
+- **Plugin name validation** — reject names that resolve to plugins root ([#5368](https://github.com/NousResearch/hermes-agent/pull/5368))
+- **pre_llm_call plugin context** moved to user message to preserve prompt cache ([#5146](https://github.com/NousResearch/hermes-agent/pull/5146))
+
+### New & Updated Skills
+- **popular-web-designs** — 54 production website design systems ([#5194](https://github.com/NousResearch/hermes-agent/pull/5194))
+- **p5js creative coding** — @SHL0MS ([#5600](https://github.com/NousResearch/hermes-agent/pull/5600))
+- **manim-video** — mathematical and technical animations — @SHL0MS ([#4930](https://github.com/NousResearch/hermes-agent/pull/4930))
+- **llm-wiki** — Karpathy's LLM Wiki skill ([#5635](https://github.com/NousResearch/hermes-agent/pull/5635))
+- **gitnexus-explorer** — codebase indexing and knowledge serving ([#5208](https://github.com/NousResearch/hermes-agent/pull/5208))
+- **research-paper-writing** — AI-Scientist & GPT-Researcher patterns — @SHL0MS ([#5421](https://github.com/NousResearch/hermes-agent/pull/5421))
+- **blogwatcher** updated to JulienTant's fork ([#5759](https://github.com/NousResearch/hermes-agent/pull/5759))
+- **claude-code skill** comprehensive rewrite v2.0 + v2.2 ([#5155](https://github.com/NousResearch/hermes-agent/pull/5155), [#5158](https://github.com/NousResearch/hermes-agent/pull/5158))
+- **Code verification skills** consolidated into one ([#4854](https://github.com/NousResearch/hermes-agent/pull/4854))
+- **Manim CE reference docs** expanded — geometry, animations, LaTeX — @leotrs ([#5791](https://github.com/NousResearch/hermes-agent/pull/5791))
+- **Manim-video references** — design thinking, updaters, paper explainer, decorations, production quality — @SHL0MS ([#5588](https://github.com/NousResearch/hermes-agent/pull/5588), [#5408](https://github.com/NousResearch/hermes-agent/pull/5408))
+
+---
+
+## 🔒 Security & Reliability
+
+### Security Hardening
+- **Consolidated security** — SSRF protections, timing attack mitigations, tar traversal prevention, credential leakage guards ([#5944](https://github.com/NousResearch/hermes-agent/pull/5944))
+- **Cross-session isolation** + cron path traversal hardening ([#5613](https://github.com/NousResearch/hermes-agent/pull/5613))
+- **Workdir parameter sanitized** in terminal tool across all backends ([#5629](https://github.com/NousResearch/hermes-agent/pull/5629))
+- **Approval 'once' session escalation** prevented + cron delivery platform validation ([#5280](https://github.com/NousResearch/hermes-agent/pull/5280))
+- **Profile-scoped Google Workspace OAuth tokens** protected ([#4910](https://github.com/NousResearch/hermes-agent/pull/4910))
+
+### Reliability
+- **Aggressive worktree and branch cleanup** to prevent accumulation ([#6134](https://github.com/NousResearch/hermes-agent/pull/6134))
+- **O(n²) catastrophic backtracking** in redact regex fixed — 100x improvement on large outputs ([#4962](https://github.com/NousResearch/hermes-agent/pull/4962))
+- **Runtime stability fixes** across core, web, delegate, and browser tools ([#4843](https://github.com/NousResearch/hermes-agent/pull/4843))
+- **API server streaming fix** + conversation history support ([#5977](https://github.com/NousResearch/hermes-agent/pull/5977))
+- **OpenViking API endpoint paths** and response parsing corrected ([#5078](https://github.com/NousResearch/hermes-agent/pull/5078))
+
+---
+
+## 🐛 Notable Bug Fixes
+
+- **9 community bugfixes salvaged** — gateway, cron, deps, macOS launchd in one batch ([#5288](https://github.com/NousResearch/hermes-agent/pull/5288))
+- **Batch core bug fixes** — model config, session reset, alias fallback, launchctl, delegation, atomic writes ([#5630](https://github.com/NousResearch/hermes-agent/pull/5630))
+- **Batch gateway/platform fixes** — matrix E2EE, CJK input, Windows browser, Feishu reconnect + ACL ([#5665](https://github.com/NousResearch/hermes-agent/pull/5665))
+- **Stale test skips removed**, regex backtracking, file search bug, and test flakiness ([#4969](https://github.com/NousResearch/hermes-agent/pull/4969))
+- **Nix flake** — read version, regen uv.lock, add hermes_logging — @alt-glitch ([#5651](https://github.com/NousResearch/hermes-agent/pull/5651))
+- **Lowercase variable redaction** regression tests ([#5185](https://github.com/NousResearch/hermes-agent/pull/5185))
+
+---
+
+## 🧪 Testing
+
+- **57 failing CI tests repaired** across 14 files ([#5823](https://github.com/NousResearch/hermes-agent/pull/5823))
+- **Test suite re-architecture** + CI failure fixes — @alt-glitch ([#5946](https://github.com/NousResearch/hermes-agent/pull/5946))
+- **Codebase-wide lint cleanup** — unused imports, dead code, and inefficient patterns ([#5821](https://github.com/NousResearch/hermes-agent/pull/5821))
+- **browser_close tool removed** — auto-cleanup handles it ([#5792](https://github.com/NousResearch/hermes-agent/pull/5792))
+
+---
+
+## 📚 Documentation
+
+- **Comprehensive documentation audit** — fix stale info, expand thin pages, add depth ([#5393](https://github.com/NousResearch/hermes-agent/pull/5393))
+- **40+ discrepancies fixed** between documentation and codebase ([#5818](https://github.com/NousResearch/hermes-agent/pull/5818))
+- **13 features documented** from last week's PRs ([#5815](https://github.com/NousResearch/hermes-agent/pull/5815))
+- **Guides section overhaul** — fix existing + add 3 new tutorials ([#5735](https://github.com/NousResearch/hermes-agent/pull/5735))
+- **Salvaged 4 docs PRs** — docker setup, post-update validation, local LLM guide, signal-cli install ([#5727](https://github.com/NousResearch/hermes-agent/pull/5727))
+- **Discord configuration reference** ([#5386](https://github.com/NousResearch/hermes-agent/pull/5386))
+- **Community FAQ entries** for common workflows and troubleshooting ([#4797](https://github.com/NousResearch/hermes-agent/pull/4797))
+- **WSL2 networking guide** for local model servers ([#5616](https://github.com/NousResearch/hermes-agent/pull/5616))
+- **Honcho CLI reference** + plugin CLI registration docs ([#5308](https://github.com/NousResearch/hermes-agent/pull/5308))
+- **Obsidian Headless setup** for servers in llm-wiki ([#5660](https://github.com/NousResearch/hermes-agent/pull/5660))
+- **Hermes Mod visual skin editor** added to skins page ([#6095](https://github.com/NousResearch/hermes-agent/pull/6095))
+
+---
+
+## 👥 Contributors
+
+### Core
+- **@teknium1** — 179 PRs
+
+### Top Community Contributors
+- **@SHL0MS** (7 PRs) — p5js creative coding skill, manim-video skill + 5 reference expansions, research-paper-writing, Nous OAuth fix, manim font fix
+- **@alt-glitch** (3 PRs) — Firecrawl cloud browser provider, test re-architecture + CI fixes, Nix flake fixes
+- **@benbarclay** (2 PRs) — Browser Use managed provider switch, Nous portal base URL fix
+- **@CharlieKerfoot** (2 PRs) — macOS portable base64 encoding, thread-safe PairingStore
+- **@WAXLYY** (2 PRs) — send_message secret redaction, gateway media URL sanitization
+- **@MadKangYu** (2 PRs) — Telegram log noise reduction, context compaction fix for temperature-restricted models
+
+### All Contributors
+@alt-glitch, @austinpickett, @auspic7, @benbarclay, @CharlieKerfoot, @GratefulDave, @kshitijk4poor, @leotrs, @lumethegreat, @MadKangYu, @nericervin, @ryanautomated, @SHL0MS, @techguysimon, @tymrtn, @Vasanthdev2004, @WAXLYY, @xinbenlv
+
+---
+
+**Full Changelog**: [v2026.4.3...v2026.4.8](https://github.com/NousResearch/hermes-agent/compare/v2026.4.3...v2026.4.8)

RELEASE_v0.9.0.md

@@ -0,0 +1,329 @@
+# Hermes Agent v0.9.0 (v2026.4.13)
+
+**Release Date:** April 13, 2026
+**Since v0.8.0:** 487 commits · 269 merged PRs · 167 resolved issues · 493 files changed · 63,281 insertions · 24 contributors
+
+> The everywhere release — Hermes goes mobile with Termux/Android, adds iMessage and WeChat, ships Fast Mode for OpenAI and Anthropic, introduces background process monitoring, launches a local web dashboard for managing your agent, and delivers the deepest security hardening pass yet across 16 supported platforms.
+
+---
+
+## ✨ Highlights
+
+- **Local Web Dashboard** — A new browser-based dashboard for managing your Hermes Agent locally. Configure settings, monitor sessions, browse skills, and manage your gateway — all from a clean web interface without touching config files or the terminal. The easiest way to get started with Hermes.
+
+- **Fast Mode (`/fast`)** — Priority processing for OpenAI and Anthropic models. Toggle `/fast` to route through priority queues for significantly lower latency on supported models (GPT-5.4, Codex, Claude). Expands across all OpenAI Priority Processing models and Anthropic's fast tier. ([#6875](https://github.com/NousResearch/hermes-agent/pull/6875), [#6960](https://github.com/NousResearch/hermes-agent/pull/6960), [#7037](https://github.com/NousResearch/hermes-agent/pull/7037))
+
+- **iMessage via BlueBubbles** — Full iMessage integration through BlueBubbles, bringing Hermes to Apple's messaging ecosystem. Auto-webhook registration, setup wizard integration, and crash resilience. ([#6437](https://github.com/NousResearch/hermes-agent/pull/6437), [#6460](https://github.com/NousResearch/hermes-agent/pull/6460), [#6494](https://github.com/NousResearch/hermes-agent/pull/6494))
+
+- **WeChat (Weixin) & WeCom Callback Mode** — Native WeChat support via iLink Bot API and a new WeCom callback-mode adapter for self-built enterprise apps. Streaming cursor, media uploads, markdown link handling, and atomic state persistence. Hermes now covers the Chinese messaging ecosystem end-to-end. ([#7166](https://github.com/NousResearch/hermes-agent/pull/7166), [#7943](https://github.com/NousResearch/hermes-agent/pull/7943))
+
+- **Termux / Android Support** — Run Hermes natively on Android via Termux. Adapted install paths, TUI optimizations for mobile screens, voice backend support, and the `/image` command work on-device. ([#6834](https://github.com/NousResearch/hermes-agent/pull/6834))
+
+- **Background Process Monitoring (`watch_patterns`)** — Set patterns to watch for in background process output and get notified in real-time when they match. Monitor for errors, wait for specific events ("listening on port"), or watch build logs — all without polling. ([#7635](https://github.com/NousResearch/hermes-agent/pull/7635))
+
+- **Native xAI & Xiaomi MiMo Providers** — First-class provider support for xAI (Grok) and Xiaomi MiMo, with direct API access, model catalogs, and setup wizard integration. Plus Qwen OAuth with portal request support. ([#7372](https://github.com/NousResearch/hermes-agent/pull/7372), [#7855](https://github.com/NousResearch/hermes-agent/pull/7855))
+
+- **Pluggable Context Engine** — Context management is now a pluggable slot via `hermes plugins`. Swap in custom context engines that control what the agent sees each turn — filtering, summarization, or domain-specific context injection. ([#7464](https://github.com/NousResearch/hermes-agent/pull/7464))
+
+- **Unified Proxy Support** — SOCKS proxy, `DISCORD_PROXY`, and system proxy auto-detection across all gateway platforms. Hermes behind corporate firewalls just works. ([#6814](https://github.com/NousResearch/hermes-agent/pull/6814))
+
+- **Comprehensive Security Hardening** — Path traversal protection in checkpoint manager, shell injection neutralization in sandbox writes, SSRF redirect guards in Slack image uploads, Twilio webhook signature validation (SMS RCE fix), API server auth enforcement, git argument injection prevention, and approval button authorization. ([#7933](https://github.com/NousResearch/hermes-agent/pull/7933), [#7944](https://github.com/NousResearch/hermes-agent/pull/7944), [#7940](https://github.com/NousResearch/hermes-agent/pull/7940), [#7151](https://github.com/NousResearch/hermes-agent/pull/7151), [#7156](https://github.com/NousResearch/hermes-agent/pull/7156))
+
+- **`hermes backup` & `hermes import`** — Full backup and restore of your Hermes configuration, sessions, skills, and memory. Migrate between machines or create snapshots before major changes. ([#7997](https://github.com/NousResearch/hermes-agent/pull/7997))
+
+- **16 Supported Platforms** — With BlueBubbles (iMessage) and WeChat joining Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, SMS, DingTalk, Feishu, WeCom, Mattermost, Home Assistant, and Webhooks, Hermes now runs on 16 messaging platforms out of the box.
+
+- **`/debug` & `hermes debug share`** — New debugging toolkit: `/debug` slash command across all platforms for quick diagnostics, plus `hermes debug share` to upload a full debug report to a pastebin for easy sharing when troubleshooting. ([#8681](https://github.com/NousResearch/hermes-agent/pull/8681))
+
+---
+
+## 🏗️ Core Agent & Architecture
+
+### Provider & Model Support
+- **Native xAI (Grok) provider** with direct API access and model catalog ([#7372](https://github.com/NousResearch/hermes-agent/pull/7372))
+- **Xiaomi MiMo as first-class provider** — setup wizard, model catalog, empty response recovery ([#7855](https://github.com/NousResearch/hermes-agent/pull/7855))
+- **Qwen OAuth provider** with portal request support ([#6282](https://github.com/NousResearch/hermes-agent/pull/6282))
+- **Fast Mode** — `/fast` toggle for OpenAI Priority Processing + Anthropic fast tier ([#6875](https://github.com/NousResearch/hermes-agent/pull/6875), [#6960](https://github.com/NousResearch/hermes-agent/pull/6960), [#7037](https://github.com/NousResearch/hermes-agent/pull/7037))
+- **Structured API error classification** for smart failover decisions ([#6514](https://github.com/NousResearch/hermes-agent/pull/6514))
+- **Rate limit header capture** shown in `/usage` ([#6541](https://github.com/NousResearch/hermes-agent/pull/6541))
+- **API server model name** derived from profile name ([#6857](https://github.com/NousResearch/hermes-agent/pull/6857))
+- **Custom providers** now included in `/model` listings and resolution ([#7088](https://github.com/NousResearch/hermes-agent/pull/7088))
+- **Fallback provider activation** on repeated empty responses with user-visible status ([#7505](https://github.com/NousResearch/hermes-agent/pull/7505))
+- **OpenRouter variant tags** (`:free`, `:extended`, `:fast`) preserved during model switch ([#6383](https://github.com/NousResearch/hermes-agent/pull/6383))
+- **Credential exhaustion TTL** reduced from 24 hours to 1 hour ([#6504](https://github.com/NousResearch/hermes-agent/pull/6504))
+- **OAuth credential lifecycle** hardening — stale pool keys, auth.json sync, Codex CLI race fixes ([#6874](https://github.com/NousResearch/hermes-agent/pull/6874))
+- Empty response recovery for reasoning models (MiMo, Qwen, GLM) ([#8609](https://github.com/NousResearch/hermes-agent/pull/8609))
+- MiniMax context lengths, thinking guard, endpoint corrections ([#6082](https://github.com/NousResearch/hermes-agent/pull/6082), [#7126](https://github.com/NousResearch/hermes-agent/pull/7126))
+- Z.AI endpoint auto-detect via probe and cache ([#5763](https://github.com/NousResearch/hermes-agent/pull/5763))
+
+### Agent Loop & Conversation
+- **Pluggable context engine slot** via `hermes plugins` ([#7464](https://github.com/NousResearch/hermes-agent/pull/7464))
+- **Background process monitoring** — `watch_patterns` for real-time output alerts ([#7635](https://github.com/NousResearch/hermes-agent/pull/7635))
+- **Improved context compression** — higher limits, tool tracking, degradation warnings, token-budget tail protection ([#6395](https://github.com/NousResearch/hermes-agent/pull/6395), [#6453](https://github.com/NousResearch/hermes-agent/pull/6453))
+- **`/compress <focus>`** — guided compression with a focus topic ([#8017](https://github.com/NousResearch/hermes-agent/pull/8017))
+- **Tiered context pressure warnings** with gateway dedup ([#6411](https://github.com/NousResearch/hermes-agent/pull/6411))
+- **Staged inactivity warning** before timeout escalation ([#6387](https://github.com/NousResearch/hermes-agent/pull/6387))
+- **Prevent agent from stopping mid-task** — compression floor, budget overhaul, activity tracking ([#7983](https://github.com/NousResearch/hermes-agent/pull/7983))
+- **Propagate child activity to parent** during `delegate_task` ([#7295](https://github.com/NousResearch/hermes-agent/pull/7295))
+- **Truncated streaming tool call detection** before execution ([#6847](https://github.com/NousResearch/hermes-agent/pull/6847))
+- Empty response retry (3 attempts with nudge) ([#6488](https://github.com/NousResearch/hermes-agent/pull/6488))
+- Adaptive streaming backoff + cursor strip to prevent message truncation ([#7683](https://github.com/NousResearch/hermes-agent/pull/7683))
+- Compression uses live session model instead of stale persisted config ([#8258](https://github.com/NousResearch/hermes-agent/pull/8258))
+- Strip `<thought>` tags from Gemma 4 responses ([#8562](https://github.com/NousResearch/hermes-agent/pull/8562))
+- Prevent `<think>` in prose from suppressing response output ([#6968](https://github.com/NousResearch/hermes-agent/pull/6968))
+- Turn-exit diagnostic logging to agent loop ([#6549](https://github.com/NousResearch/hermes-agent/pull/6549))
+- Scope tool interrupt signal per-thread to prevent cross-session leaks ([#7930](https://github.com/NousResearch/hermes-agent/pull/7930))
+
+### Memory & Sessions
+- **Hindsight memory plugin** — feature parity, setup wizard, config improvements — @nicoloboschi ([#6428](https://github.com/NousResearch/hermes-agent/pull/6428))
+- **Honcho** — opt-in `initOnSessionStart` for tools mode — @Kathie-yu ([#6995](https://github.com/NousResearch/hermes-agent/pull/6995))
+- Orphan children instead of cascade-deleting in prune/delete ([#6513](https://github.com/NousResearch/hermes-agent/pull/6513))
+- Doctor command only checks the active memory provider ([#6285](https://github.com/NousResearch/hermes-agent/pull/6285))
+
+---
+
+## 📱 Messaging Platforms (Gateway)
+
+### New Platforms
+- **BlueBubbles (iMessage)** — full adapter with auto-webhook registration, setup wizard, and crash resilience ([#6437](https://github.com/NousResearch/hermes-agent/pull/6437), [#6460](https://github.com/NousResearch/hermes-agent/pull/6460), [#6494](https://github.com/NousResearch/hermes-agent/pull/6494), [#7107](https://github.com/NousResearch/hermes-agent/pull/7107))
+- **Weixin (WeChat)** — native support via iLink Bot API with streaming, media uploads, markdown links ([#7166](https://github.com/NousResearch/hermes-agent/pull/7166), [#8665](https://github.com/NousResearch/hermes-agent/pull/8665))
+- **WeCom Callback Mode** — self-built enterprise app adapter with atomic state persistence ([#7943](https://github.com/NousResearch/hermes-agent/pull/7943), [#7928](https://github.com/NousResearch/hermes-agent/pull/7928))
+
+### Discord
+- **Allowed channels whitelist** config — @jarvis-phw ([#7044](https://github.com/NousResearch/hermes-agent/pull/7044))
+- **Forum channel topic inheritance** in thread sessions — @hermes-agent-dhabibi ([#6377](https://github.com/NousResearch/hermes-agent/pull/6377))
+- **DISCORD_REPLY_TO_MODE** setting ([#6333](https://github.com/NousResearch/hermes-agent/pull/6333))
+- Accept `.log` attachments, raise document size limit — @kira-ariaki ([#6467](https://github.com/NousResearch/hermes-agent/pull/6467))
+- Decouple readiness from slash sync ([#8016](https://github.com/NousResearch/hermes-agent/pull/8016))
+
+### Slack
+- **Consolidated Slack improvements** — 7 community PRs salvaged into one ([#6809](https://github.com/NousResearch/hermes-agent/pull/6809))
+- Handle assistant thread lifecycle events ([#6433](https://github.com/NousResearch/hermes-agent/pull/6433))
+
+### Matrix
+- **Migrated from matrix-nio to mautrix-python** ([#7518](https://github.com/NousResearch/hermes-agent/pull/7518))
+- SQLite crypto store replacing pickle (fixes E2EE decryption) — @alt-glitch ([#7981](https://github.com/NousResearch/hermes-agent/pull/7981))
+- Cross-signing recovery key verification for E2EE migration ([#8282](https://github.com/NousResearch/hermes-agent/pull/8282))
+- DM mention threads + group chat events for Feishu ([#7423](https://github.com/NousResearch/hermes-agent/pull/7423))
+
+### Gateway Core
+- **Unified proxy support** — SOCKS, DISCORD_PROXY, multi-platform with macOS auto-detection ([#6814](https://github.com/NousResearch/hermes-agent/pull/6814))
+- **Inbound text batching** for Discord, Matrix, WeCom + adaptive delay ([#6979](https://github.com/NousResearch/hermes-agent/pull/6979))
+- **Surface natural mid-turn assistant messages** in chat platforms ([#7978](https://github.com/NousResearch/hermes-agent/pull/7978))
+- **WSL-aware gateway** with smart systemd detection ([#7510](https://github.com/NousResearch/hermes-agent/pull/7510))
+- **All missing platforms added to setup wizard** ([#7949](https://github.com/NousResearch/hermes-agent/pull/7949))
+- **Per-platform `tool_progress` overrides** ([#6348](https://github.com/NousResearch/hermes-agent/pull/6348))
+- **Configurable 'still working' notification interval** ([#8572](https://github.com/NousResearch/hermes-agent/pull/8572))
+- `/model` switch persists across messages ([#7081](https://github.com/NousResearch/hermes-agent/pull/7081))
+- `/usage` shows rate limits, cost, and token details between turns ([#7038](https://github.com/NousResearch/hermes-agent/pull/7038))
+- Drain in-flight work before restart ([#7503](https://github.com/NousResearch/hermes-agent/pull/7503))
+- Don't evict cached agent on failed runs — prevents MCP restart loop ([#7539](https://github.com/NousResearch/hermes-agent/pull/7539))
+- Replace `os.environ` session state with `contextvars` ([#7454](https://github.com/NousResearch/hermes-agent/pull/7454))
+- Derive channel directory platforms from enum instead of hardcoded list ([#7450](https://github.com/NousResearch/hermes-agent/pull/7450))
+- Validate image downloads before caching (cross-platform) ([#7125](https://github.com/NousResearch/hermes-agent/pull/7125))
+- Cross-platform webhook delivery for all platforms ([#7095](https://github.com/NousResearch/hermes-agent/pull/7095))
+- Cron Discord thread_id delivery support ([#7106](https://github.com/NousResearch/hermes-agent/pull/7106))
+- Feishu QR-based bot onboarding ([#8570](https://github.com/NousResearch/hermes-agent/pull/8570))
+- Gateway status scoped to active profile ([#7951](https://github.com/NousResearch/hermes-agent/pull/7951))
+- Prevent background process notifications from triggering false pairing requests ([#6434](https://github.com/NousResearch/hermes-agent/pull/6434))
+
+---
+
+## 🖥️ CLI & User Experience
+
+### Interactive CLI
+- **Termux / Android support** — adapted install paths, TUI, voice, `/image` ([#6834](https://github.com/NousResearch/hermes-agent/pull/6834))
+- **Native `/model` picker modal** for provider → model selection ([#8003](https://github.com/NousResearch/hermes-agent/pull/8003))
+- **Live per-tool elapsed timer** restored in TUI spinner ([#7359](https://github.com/NousResearch/hermes-agent/pull/7359))
+- **Stacked tool progress scrollback** in TUI ([#8201](https://github.com/NousResearch/hermes-agent/pull/8201))
+- **Random tips on new session start** (CLI + gateway, 279 tips) ([#8225](https://github.com/NousResearch/hermes-agent/pull/8225), [#8237](https://github.com/NousResearch/hermes-agent/pull/8237))
+- **`hermes dump`** — copy-pasteable setup summary for debugging ([#6550](https://github.com/NousResearch/hermes-agent/pull/6550))
+- **`hermes backup` / `hermes import`** — full config backup and restore ([#7997](https://github.com/NousResearch/hermes-agent/pull/7997))
+- **WSL environment hint** in system prompt ([#8285](https://github.com/NousResearch/hermes-agent/pull/8285))
+- **Profile creation UX** — seed SOUL.md + credential warning ([#8553](https://github.com/NousResearch/hermes-agent/pull/8553))
+- Shell-aware sudo detection, empty password support ([#6517](https://github.com/NousResearch/hermes-agent/pull/6517))
+- Flush stdin after curses/terminal menus to prevent escape sequence leakage ([#7167](https://github.com/NousResearch/hermes-agent/pull/7167))
+- Handle broken stdin in prompt_toolkit startup ([#8560](https://github.com/NousResearch/hermes-agent/pull/8560))
+
+### Setup & Configuration
+- **Per-platform display verbosity** configuration ([#8006](https://github.com/NousResearch/hermes-agent/pull/8006))
+- **Component-separated logging** with session context and filtering ([#7991](https://github.com/NousResearch/hermes-agent/pull/7991))
+- **`network.force_ipv4`** config to fix IPv6 timeout issues ([#8196](https://github.com/NousResearch/hermes-agent/pull/8196))
+- **Standardize message whitespace and JSON formatting** ([#7988](https://github.com/NousResearch/hermes-agent/pull/7988))
+- **Rebrand OpenClaw → Hermes** during migration ([#8210](https://github.com/NousResearch/hermes-agent/pull/8210))
+- Config.yaml takes priority over env vars for auxiliary settings ([#7889](https://github.com/NousResearch/hermes-agent/pull/7889))
+- Harden setup provider flows + live OpenRouter catalog refresh ([#7078](https://github.com/NousResearch/hermes-agent/pull/7078))
+- Normalize reasoning effort ordering across all surfaces ([#6804](https://github.com/NousResearch/hermes-agent/pull/6804))
+- Remove dead `LLM_MODEL` env var + migration to clear stale entries ([#6543](https://github.com/NousResearch/hermes-agent/pull/6543))
+- Remove `/prompt` slash command — prefix expansion footgun ([#6752](https://github.com/NousResearch/hermes-agent/pull/6752))
+- `HERMES_HOME_MODE` env var to override permissions — @ygd58 ([#6993](https://github.com/NousResearch/hermes-agent/pull/6993))
+- Fall back to default model when model config is empty ([#8303](https://github.com/NousResearch/hermes-agent/pull/8303))
+- Warn when compression model context is too small ([#7894](https://github.com/NousResearch/hermes-agent/pull/7894))
+
+---
+
+## 🔧 Tool System
+
+### Environments & Execution
+- **Unified spawn-per-call execution layer** for environments ([#6343](https://github.com/NousResearch/hermes-agent/pull/6343))
+- **Unified file sync** with mtime tracking, deletion, and transactional state ([#7087](https://github.com/NousResearch/hermes-agent/pull/7087))
+- **Persistent sandbox envs** survive between turns ([#6412](https://github.com/NousResearch/hermes-agent/pull/6412))
+- **Bulk file sync** via tar pipe for SSH/Modal backends — @alt-glitch ([#8014](https://github.com/NousResearch/hermes-agent/pull/8014))
+- **Daytona** — bulk upload, config bridge, silent disk cap ([#7538](https://github.com/NousResearch/hermes-agent/pull/7538))
+- Foreground timeout cap to prevent session deadlocks ([#7082](https://github.com/NousResearch/hermes-agent/pull/7082))
+- Guard invalid command values ([#6417](https://github.com/NousResearch/hermes-agent/pull/6417))
+
+### MCP
+- **`hermes mcp add --env` and `--preset`** support ([#7970](https://github.com/NousResearch/hermes-agent/pull/7970))
+- Combine `content` and `structuredContent` when both present ([#7118](https://github.com/NousResearch/hermes-agent/pull/7118))
+- MCP tool name deconfliction fixes ([#7654](https://github.com/NousResearch/hermes-agent/pull/7654))
+
+### Browser
+- Browser hardening — dead code removal, caching, scroll perf, security, thread safety ([#7354](https://github.com/NousResearch/hermes-agent/pull/7354))
+- `/browser connect` auto-launch uses dedicated Chrome profile dir ([#6821](https://github.com/NousResearch/hermes-agent/pull/6821))
+- Reap orphaned browser sessions on startup ([#7931](https://github.com/NousResearch/hermes-agent/pull/7931))
+
+### Voice & Vision
+- **Voxtral TTS provider** (Mistral AI) ([#7653](https://github.com/NousResearch/hermes-agent/pull/7653))
+- **TTS speed support** for Edge TTS, OpenAI TTS, MiniMax ([#8666](https://github.com/NousResearch/hermes-agent/pull/8666))
+- **Vision auto-resize** for oversized images, raise limit to 20 MB, retry-on-failure ([#7883](https://github.com/NousResearch/hermes-agent/pull/7883), [#7902](https://github.com/NousResearch/hermes-agent/pull/7902))
+- STT provider-model mismatch fix (whisper-1 vs faster-whisper) ([#7113](https://github.com/NousResearch/hermes-agent/pull/7113))
+
+### Other Tools
+- **`hermes dump`** command for setup summary ([#6550](https://github.com/NousResearch/hermes-agent/pull/6550))
+- TODO store enforces ID uniqueness during replace operations ([#7986](https://github.com/NousResearch/hermes-agent/pull/7986))
+- List all available toolsets in `delegate_task` schema description ([#8231](https://github.com/NousResearch/hermes-agent/pull/8231))
+- API server: tool progress as custom SSE event to prevent model corruption ([#7500](https://github.com/NousResearch/hermes-agent/pull/7500))
+- API server: share one Docker container across all conversations ([#7127](https://github.com/NousResearch/hermes-agent/pull/7127))
+
+---
+
+## 🧩 Skills Ecosystem
+
+- **Centralized skills index + tree cache** — eliminates rate-limit failures on install ([#8575](https://github.com/NousResearch/hermes-agent/pull/8575))
+- **More aggressive skill loading instructions** in system prompt (v3) ([#8209](https://github.com/NousResearch/hermes-agent/pull/8209), [#8286](https://github.com/NousResearch/hermes-agent/pull/8286))
+- **Google Workspace skill** migrated to GWS CLI backend ([#6788](https://github.com/NousResearch/hermes-agent/pull/6788))
+- **Creative divergence strategies** skill — @SHL0MS ([#6882](https://github.com/NousResearch/hermes-agent/pull/6882))
+- **Creative ideation** — constraint-driven project generation — @SHL0MS ([#7555](https://github.com/NousResearch/hermes-agent/pull/7555))
+- Parallelize skills browse/search to prevent hanging ([#7301](https://github.com/NousResearch/hermes-agent/pull/7301))
+- Read name from SKILL.md frontmatter in skills_sync ([#7623](https://github.com/NousResearch/hermes-agent/pull/7623))
+
+---
+
+## 🔒 Security & Reliability
+
+### Security Hardening
+- **Twilio webhook signature validation** — SMS RCE fix ([#7933](https://github.com/NousResearch/hermes-agent/pull/7933))
+- **Shell injection neutralization** in `_write_to_sandbox` via path quoting ([#7940](https://github.com/NousResearch/hermes-agent/pull/7940))
+- **Git argument injection** and path traversal prevention in checkpoint manager ([#7944](https://github.com/NousResearch/hermes-agent/pull/7944))
+- **SSRF redirect bypass** in Slack image uploads + base.py cache helpers ([#7151](https://github.com/NousResearch/hermes-agent/pull/7151))
+- **Path traversal, credential gate, DANGEROUS_PATTERNS gaps** ([#7156](https://github.com/NousResearch/hermes-agent/pull/7156))
+- **API bind guard** — enforce `API_SERVER_KEY` for non-loopback binding ([#7455](https://github.com/NousResearch/hermes-agent/pull/7455))
+- **Approval button authorization** — require auth for session continuation — @Cafexss ([#6930](https://github.com/NousResearch/hermes-agent/pull/6930))
+- Path boundary enforcement in skill manager operations ([#7156](https://github.com/NousResearch/hermes-agent/pull/7156))
+- DingTalk/API webhook URL origin validation, header injection rejection ([#7455](https://github.com/NousResearch/hermes-agent/pull/7455))
+
+### Reliability
+- **Contextual error diagnostics** for invalid API responses ([#8565](https://github.com/NousResearch/hermes-agent/pull/8565))
+- **Prevent 400 format errors** from triggering compression loop on Codex ([#6751](https://github.com/NousResearch/hermes-agent/pull/6751))
+- **Don't halve context_length** on output-cap-too-large errors — @KUSH42 ([#6664](https://github.com/NousResearch/hermes-agent/pull/6664))
+- **Recover primary client** on OpenAI transport errors ([#7108](https://github.com/NousResearch/hermes-agent/pull/7108))
+- **Credential pool rotation** on billing-classified 400s ([#7112](https://github.com/NousResearch/hermes-agent/pull/7112))
+- **Auto-increase stream read timeout** for local LLM providers ([#6967](https://github.com/NousResearch/hermes-agent/pull/6967))
+- **Fall back to default certs** when CA bundle path doesn't exist ([#7352](https://github.com/NousResearch/hermes-agent/pull/7352))
+- **Disambiguate usage-limit patterns** in error classifier — @sprmn24 ([#6836](https://github.com/NousResearch/hermes-agent/pull/6836))
+- Harden cron script timeout and provider recovery ([#7079](https://github.com/NousResearch/hermes-agent/pull/7079))
+- Gateway interrupt detection resilient to monitor task failures ([#8208](https://github.com/NousResearch/hermes-agent/pull/8208))
+- Prevent unwanted session auto-reset after graceful gateway restarts ([#8299](https://github.com/NousResearch/hermes-agent/pull/8299))
+- Prevent duplicate update prompt spam in gateway watcher ([#8343](https://github.com/NousResearch/hermes-agent/pull/8343))
+- Deduplicate reasoning items in Responses API input ([#7946](https://github.com/NousResearch/hermes-agent/pull/7946))
+
+### Infrastructure
+- **Multi-arch Docker image** — amd64 + arm64 ([#6124](https://github.com/NousResearch/hermes-agent/pull/6124))
+- **Docker runs as non-root user** with virtualenv — @benbarclay contributing ([#8226](https://github.com/NousResearch/hermes-agent/pull/8226))
+- **Use `uv`** for Docker dependency resolution to fix resolution-too-deep ([#6965](https://github.com/NousResearch/hermes-agent/pull/6965))
+- **Container-aware Nix CLI** — auto-route into managed container — @alt-glitch ([#7543](https://github.com/NousResearch/hermes-agent/pull/7543))
+- **Nix shared-state permission model** for interactive CLI users — @alt-glitch ([#6796](https://github.com/NousResearch/hermes-agent/pull/6796))
+- **Per-profile subprocess HOME isolation** ([#7357](https://github.com/NousResearch/hermes-agent/pull/7357))
+- Profile paths fixed in Docker — profiles go to mounted volume ([#7170](https://github.com/NousResearch/hermes-agent/pull/7170))
+- Docker container gateway pathway hardened ([#8614](https://github.com/NousResearch/hermes-agent/pull/8614))
+- Enable unbuffered stdout for live Docker logs ([#6749](https://github.com/NousResearch/hermes-agent/pull/6749))
+- Install procps in Docker image — @HiddenPuppy ([#7032](https://github.com/NousResearch/hermes-agent/pull/7032))
+- Shallow git clone for faster installation — @sosyz ([#8396](https://github.com/NousResearch/hermes-agent/pull/8396))
+- `hermes update` always reset on stash conflict ([#7010](https://github.com/NousResearch/hermes-agent/pull/7010))
+- Write update exit code before gateway restart (cgroup kill race) ([#8288](https://github.com/NousResearch/hermes-agent/pull/8288))
+- Nix: `setupSecrets` optional, tirith runtime dep — @devorun, @ethernet8023 ([#6261](https://github.com/NousResearch/hermes-agent/pull/6261), [#6721](https://github.com/NousResearch/hermes-agent/pull/6721))
+- launchd stop uses `bootout` so `KeepAlive` doesn't respawn ([#7119](https://github.com/NousResearch/hermes-agent/pull/7119))
+
+---
+
+## 🐛 Notable Bug Fixes
+
+- Fix: `/model` switch not persisting across gateway messages ([#7081](https://github.com/NousResearch/hermes-agent/pull/7081))
+- Fix: session-scoped gateway model overrides ignored — @Hygaard ([#7662](https://github.com/NousResearch/hermes-agent/pull/7662))
+- Fix: compaction model context length ignoring config — 3 related issues ([#8258](https://github.com/NousResearch/hermes-agent/pull/8258), [#8107](https://github.com/NousResearch/hermes-agent/pull/8107))
+- Fix: OpenCode.ai context window resolved to 128K instead of 1M ([#6472](https://github.com/NousResearch/hermes-agent/pull/6472))
+- Fix: Codex fallback auth-store lookup — @cherifya ([#6462](https://github.com/NousResearch/hermes-agent/pull/6462))
+- Fix: duplicate completion notifications when process killed ([#7124](https://github.com/NousResearch/hermes-agent/pull/7124))
+- Fix: agent daemon thread prevents orphan CLI processes on tab close ([#8557](https://github.com/NousResearch/hermes-agent/pull/8557))
+- Fix: stale image attachment on text paste and voice input ([#7077](https://github.com/NousResearch/hermes-agent/pull/7077))
+- Fix: DM thread session seeding causing cross-thread contamination ([#7084](https://github.com/NousResearch/hermes-agent/pull/7084))
+- Fix: OpenClaw migration shows dry-run preview before executing ([#6769](https://github.com/NousResearch/hermes-agent/pull/6769))
+- Fix: auth errors misclassified as retryable — @kuishou68 ([#7027](https://github.com/NousResearch/hermes-agent/pull/7027))
+- Fix: Copilot-Integration-Id header missing ([#7083](https://github.com/NousResearch/hermes-agent/pull/7083))
+- Fix: ACP session capabilities — @luyao618 ([#6985](https://github.com/NousResearch/hermes-agent/pull/6985))
+- Fix: ACP PromptResponse usage from top-level fields ([#7086](https://github.com/NousResearch/hermes-agent/pull/7086))
+- Fix: several failing/flaky tests on main — @dsocolobsky ([#6777](https://github.com/NousResearch/hermes-agent/pull/6777))
+- Fix: backup marker filenames — @sprmn24 ([#8600](https://github.com/NousResearch/hermes-agent/pull/8600))
+- Fix: `NoneType` in fast_mode check — @0xbyt4 ([#7350](https://github.com/NousResearch/hermes-agent/pull/7350))
+- Fix: missing imports in uninstall.py — @JiayuuWang ([#7034](https://github.com/NousResearch/hermes-agent/pull/7034))
+
+---
+
+## 📚 Documentation
+
+- Platform adapter developer guide + WeCom Callback docs ([#7969](https://github.com/NousResearch/hermes-agent/pull/7969))
+- Cron troubleshooting guide ([#7122](https://github.com/NousResearch/hermes-agent/pull/7122))
+- Streaming timeout auto-detection for local LLMs ([#6990](https://github.com/NousResearch/hermes-agent/pull/6990))
+- Tool-use enforcement documentation expanded ([#7984](https://github.com/NousResearch/hermes-agent/pull/7984))
+- BlueBubbles pairing instructions ([#6548](https://github.com/NousResearch/hermes-agent/pull/6548))
+- Telegram proxy support section ([#6348](https://github.com/NousResearch/hermes-agent/pull/6348))
+- `hermes dump` and `hermes logs` CLI reference ([#6552](https://github.com/NousResearch/hermes-agent/pull/6552))
+- `tool_progress_overrides` configuration reference ([#6364](https://github.com/NousResearch/hermes-agent/pull/6364))
+- Compression model context length warning docs ([#7879](https://github.com/NousResearch/hermes-agent/pull/7879))
+
+---
+
+## 👥 Contributors
+
+**269 merged PRs** from **24 contributors** across **487 commits**.
+
+### Community Contributors
+- **@alt-glitch** (6 PRs) — Nix container-aware CLI, shared-state permissions, Matrix SQLite crypto store, bulk SSH/Modal file sync, Matrix mautrix compat
+- **@SHL0MS** (2 PRs) — Creative divergence strategies skill, creative ideation skill
+- **@sprmn24** (2 PRs) — Error classifier disambiguation, backup marker fix
+- **@nicoloboschi** — Hindsight memory plugin feature parity
+- **@Hygaard** — Session-scoped gateway model override fix
+- **@jarvis-phw** — Discord allowed_channels whitelist
+- **@Kathie-yu** — Honcho initOnSessionStart for tools mode
+- **@hermes-agent-dhabibi** — Discord forum channel topic inheritance
+- **@kira-ariaki** — Discord .log attachments and size limit
+- **@cherifya** — Codex fallback auth-store lookup
+- **@Cafexss** — Security: auth for session continuation
+- **@KUSH42** — Compaction context_length fix
+- **@kuishou68** — Auth error retryable classification fix
+- **@luyao618** — ACP session capabilities
+- **@ygd58** — HERMES_HOME_MODE env var override
+- **@0xbyt4** — Fast mode NoneType fix
+- **@JiayuuWang** — CLI uninstall import fix
+- **@HiddenPuppy** — Docker procps installation
+- **@dsocolobsky** — Test suite fixes
+- **@bobashopcashier** (1 PR) — Graceful gateway drain before restart (salvaged into #7503 from #7290)
+- **@benbarclay** — Docker image tag simplification
+- **@sosyz** — Shallow git clone for faster install
+- **@devorun** — Nix setupSecrets optional
+- **@ethernet8023** — Nix tirith runtime dep
+
+---
+
+**Full Changelog**: [v2026.4.8...v2026.4.13](https://github.com/NousResearch/hermes-agent/compare/v2026.4.8...v2026.4.13)

SECURE_CODING_GUIDELINES.md

@@ -1,566 +0,0 @@
-# SECURE CODING GUIDELINES
-
-## Hermes Agent Development Security Standards
-**Version:** 1.0  
-**Effective Date:** March 30, 2026
-
----
-
-## 1. GENERAL PRINCIPLES
-
-### 1.1 Security-First Mindset
-- Every feature must be designed with security in mind
-- Assume all input is malicious until proven otherwise
-- Defense in depth: multiple layers of security controls
-- Fail securely: when security controls fail, default to denial
-
-### 1.2 Threat Model
-Primary threats to consider:
-- Malicious user prompts
-- Compromised or malicious skills
-- Supply chain attacks
-- Insider threats
-- Accidental data exposure
-
----
-
-## 2. INPUT VALIDATION
-
-### 2.1 Validate All Input
-```python
-# ❌ INCORRECT
-def process_file(path: str):
-    with open(path) as f:
-        return f.read()
-
-# ✅ CORRECT
-from pydantic import BaseModel, validator
-import re
-
-class FileRequest(BaseModel):
-    path: str
-    max_size: int = 1000000
-    
-    @validator('path')
-    def validate_path(cls, v):
-        # Block path traversal
-        if '..' in v or v.startswith('/'):
-            raise ValueError('Invalid path characters')
-        # Allowlist safe characters
-        if not re.match(r'^[\w\-./]+$', v):
-            raise ValueError('Invalid characters in path')
-        return v
-    
-    @validator('max_size')
-    def validate_size(cls, v):
-        if v < 0 or v > 10000000:
-            raise ValueError('Size out of range')
-        return v
-
-def process_file(request: FileRequest):
-    # Now safe to use request.path
-    pass
-```
-
-### 2.2 Length Limits
-Always enforce maximum lengths:
-```python
-MAX_INPUT_LENGTH = 10000
-MAX_FILENAME_LENGTH = 255
-MAX_PATH_LENGTH = 4096
-
-def validate_length(value: str, max_len: int, field_name: str):
-    if len(value) > max_len:
-        raise ValueError(f"{field_name} exceeds maximum length of {max_len}")
-```
-
-### 2.3 Type Safety
-Use type hints and enforce them:
-```python
-from typing import Union
-
-def safe_function(user_id: int, message: str) -> dict:
-    if not isinstance(user_id, int):
-        raise TypeError("user_id must be an integer")
-    if not isinstance(message, str):
-        raise TypeError("message must be a string")
-    # ... function logic
-```
-
----
-
-## 3. COMMAND EXECUTION
-
-### 3.1 Never Use shell=True
-```python
-import subprocess
-import shlex
-
-# ❌ NEVER DO THIS
-subprocess.run(f"ls {user_input}", shell=True)
-
-# ❌ NEVER DO THIS EITHER
-cmd = f"cat {filename}"
-os.system(cmd)
-
-# ✅ CORRECT - Use list arguments
-subprocess.run(["ls", user_input], shell=False)
-
-# ✅ CORRECT - Use shlex for complex cases
-cmd_parts = shlex.split(user_input)
-subprocess.run(["ls"] + cmd_parts, shell=False)
-```
-
-### 3.2 Command Allowlisting
-```python
-ALLOWED_COMMANDS = frozenset([
-    "ls", "cat", "grep", "find", "git", "python", "pip"
-])
-
-def validate_command(command: str):
-    parts = shlex.split(command)
-    if parts[0] not in ALLOWED_COMMANDS:
-        raise SecurityError(f"Command '{parts[0]}' not allowed")
-```
-
-### 3.3 Input Sanitization
-```python
-import re
-
-def sanitize_shell_input(value: str) -> str:
-    """Remove dangerous shell metacharacters."""
-    # Block shell metacharacters
-    dangerous = re.compile(r'[;&|`$(){}[\]\\]')
-    if dangerous.search(value):
-        raise ValueError("Shell metacharacters not allowed")
-    return value
-```
-
----
-
-## 4. FILE OPERATIONS
-
-### 4.1 Path Validation
-```python
-from pathlib import Path
-
-class FileSandbox:
-    def __init__(self, root: Path):
-        self.root = root.resolve()
-    
-    def validate_path(self, user_path: str) -> Path:
-        """Validate and resolve user-provided path within sandbox."""
-        # Expand user home
-        expanded = Path(user_path).expanduser()
-        
-        # Resolve to absolute path
-        try:
-            resolved = expanded.resolve()
-        except (OSError, ValueError) as e:
-            raise SecurityError(f"Invalid path: {e}")
-        
-        # Ensure path is within sandbox
-        try:
-            resolved.relative_to(self.root)
-        except ValueError:
-            raise SecurityError("Path outside sandbox")
-        
-        return resolved
-    
-    def safe_open(self, user_path: str, mode: str = 'r'):
-        safe_path = self.validate_path(user_path)
-        return open(safe_path, mode)
-```
-
-### 4.2 Prevent Symlink Attacks
-```python
-import os
-
-def safe_read_file(filepath: Path):
-    """Read file, following symlinks only within allowed directories."""
-    # Resolve symlinks
-    real_path = filepath.resolve()
-    
-    # Verify still in allowed location after resolution
-    if not str(real_path).startswith(str(SAFE_ROOT)):
-        raise SecurityError("Symlink escape detected")
-    
-    # Verify it's a regular file
-    if not real_path.is_file():
-        raise SecurityError("Not a regular file")
-    
-    return real_path.read_text()
-```
-
-### 4.3 Temporary Files
-```python
-import tempfile
-import os
-
-def create_secure_temp_file():
-    """Create temp file with restricted permissions."""
-    # Create with restrictive permissions
-    fd, path = tempfile.mkstemp(prefix="hermes_", suffix=".tmp")
-    try:
-        # Set owner-read/write only
-        os.chmod(path, 0o600)
-        return fd, path
-    except:
-        os.close(fd)
-        os.unlink(path)
-        raise
-```
-
----
-
-## 5. SECRET MANAGEMENT
-
-### 5.1 Environment Variables
-```python
-import os
-
-# ❌ NEVER DO THIS
-def execute_command(command: str):
-    # Child inherits ALL environment
-    subprocess.run(command, shell=True, env=os.environ)
-
-# ✅ CORRECT - Explicit whitelisting
-_ALLOWED_ENV = frozenset([
-    "PATH", "HOME", "USER", "LANG", "TERM", "SHELL"
-])
-
-def get_safe_environment():
-    return {k: v for k, v in os.environ.items() 
-            if k in _ALLOWED_ENV}
-
-def execute_command(command: str):
-    subprocess.run(
-        command, 
-        shell=False, 
-        env=get_safe_environment()
-    )
-```
-
-### 5.2 Secret Detection
-```python
-import re
-
-_SECRET_PATTERNS = [
-    re.compile(r'sk-[a-zA-Z0-9]{20,}'),  # OpenAI-style keys
-    re.compile(r'ghp_[a-zA-Z0-9]{36}'),  # GitHub PAT
-    re.compile(r'[a-zA-Z0-9]{40}'),      # Generic high-entropy strings
-]
-
-def detect_secrets(text: str) -> list:
-    """Detect potential secrets in text."""
-    findings = []
-    for pattern in _SECRET_PATTERNS:
-        matches = pattern.findall(text)
-        findings.extend(matches)
-    return findings
-
-def redact_secrets(text: str) -> str:
-    """Redact detected secrets."""
-    for pattern in _SECRET_PATTERNS:
-        text = pattern.sub('***REDACTED***', text)
-    return text
-```
-
-### 5.3 Secure Logging
-```python
-import logging
-from agent.redact import redact_sensitive_text
-
-class SecureLogger:
-    def __init__(self, logger: logging.Logger):
-        self.logger = logger
-    
-    def debug(self, msg: str, *args, **kwargs):
-        self.logger.debug(redact_sensitive_text(msg), *args, **kwargs)
-    
-    def info(self, msg: str, *args, **kwargs):
-        self.logger.info(redact_sensitive_text(msg), *args, **kwargs)
-    
-    def warning(self, msg: str, *args, **kwargs):
-        self.logger.warning(redact_sensitive_text(msg), *args, **kwargs)
-    
-    def error(self, msg: str, *args, **kwargs):
-        self.logger.error(redact_sensitive_text(msg), *args, **kwargs)
-```
-
----
-
-## 6. NETWORK SECURITY
-
-### 6.1 URL Validation
-```python
-from urllib.parse import urlparse
-import ipaddress
-
-_BLOCKED_SCHEMES = frozenset(['file', 'ftp', 'gopher'])
-_BLOCKED_HOSTS = frozenset([
-    'localhost', '127.0.0.1', '0.0.0.0',
-    '169.254.169.254',  # AWS metadata
-    '[::1]', '[::]'
-])
-_PRIVATE_NETWORKS = [
-    ipaddress.ip_network('10.0.0.0/8'),
-    ipaddress.ip_network('172.16.0.0/12'),
-    ipaddress.ip_network('192.168.0.0/16'),
-    ipaddress.ip_network('127.0.0.0/8'),
-    ipaddress.ip_network('169.254.0.0/16'),  # Link-local
-]
-
-def validate_url(url: str) -> bool:
-    """Validate URL is safe to fetch."""
-    parsed = urlparse(url)
-    
-    # Check scheme
-    if parsed.scheme not in ('http', 'https'):
-        raise ValueError(f"Scheme '{parsed.scheme}' not allowed")
-    
-    # Check hostname
-    hostname = parsed.hostname
-    if not hostname:
-        raise ValueError("No hostname in URL")
-    
-    if hostname.lower() in _BLOCKED_HOSTS:
-        raise ValueError("Host not allowed")
-    
-    # Check IP addresses
-    try:
-        ip = ipaddress.ip_address(hostname)
-        for network in _PRIVATE_NETWORKS:
-            if ip in network:
-                raise ValueError("Private IP address not allowed")
-    except ValueError:
-        pass  # Not an IP, continue
-    
-    return True
-```
-
-### 6.2 Redirect Handling
-```python
-import requests
-
-def safe_get(url: str, max_redirects: int = 5):
-    """GET URL with redirect validation."""
-    session = requests.Session()
-    session.max_redirects = max_redirects
-    
-    # Validate initial URL
-    validate_url(url)
-    
-    # Custom redirect handler
-    response = session.get(
-        url, 
-        allow_redirects=True,
-        hooks={'response': lambda r, *args, **kwargs: validate_url(r.url)}
-    )
-    
-    return response
-```
-
----
-
-## 7. AUTHENTICATION & AUTHORIZATION
-
-### 7.1 API Key Validation
-```python
-import secrets
-import hmac
-import hashlib
-
-def constant_time_compare(val1: str, val2: str) -> bool:
-    """Compare strings in constant time to prevent timing attacks."""
-    return hmac.compare_digest(val1.encode(), val2.encode())
-
-def validate_api_key(provided_key: str, expected_key: str) -> bool:
-    """Validate API key using constant-time comparison."""
-    if not provided_key or not expected_key:
-        return False
-    return constant_time_compare(provided_key, expected_key)
-```
-
-### 7.2 Session Management
-```python
-import secrets
-from datetime import datetime, timedelta
-
-class SessionManager:
-    SESSION_TIMEOUT = timedelta(hours=24)
-    
-    def create_session(self, user_id: str) -> str:
-        """Create secure session token."""
-        token = secrets.token_urlsafe(32)
-        expires = datetime.utcnow() + self.SESSION_TIMEOUT
-        # Store in database with expiration
-        return token
-    
-    def validate_session(self, token: str) -> bool:
-        """Validate session token."""
-        # Lookup in database
-        # Check expiration
-        # Validate token format
-        return True
-```
-
----
-
-## 8. ERROR HANDLING
-
-### 8.1 Secure Error Messages
-```python
-import logging
-
-# Internal detailed logging
-logger = logging.getLogger(__name__)
-
-class UserFacingError(Exception):
-    """Error safe to show to users."""
-    pass
-
-def process_request(data: dict):
-    try:
-        result = internal_operation(data)
-        return result
-    except ValueError as e:
-        # Log full details internally
-        logger.error(f"Validation error: {e}", exc_info=True)
-        # Return safe message to user
-        raise UserFacingError("Invalid input provided")
-    except Exception as e:
-        # Log full details internally
-        logger.error(f"Unexpected error: {e}", exc_info=True)
-        # Generic message to user
-        raise UserFacingError("An error occurred")
-```
-
-### 8.2 Exception Handling
-```python
-def safe_operation():
-    try:
-        risky_operation()
-    except Exception as e:
-        # Always clean up resources
-        cleanup_resources()
-        # Log securely
-        logger.error(f"Operation failed: {redact_sensitive_text(str(e))}")
-        # Re-raise or convert
-        raise
-```
-
----
-
-## 9. CRYPTOGRAPHY
-
-### 9.1 Password Hashing
-```python
-import bcrypt
-
-def hash_password(password: str) -> str:
-    """Hash password using bcrypt."""
-    salt = bcrypt.gensalt(rounds=12)
-    hashed = bcrypt.hashpw(password.encode(), salt)
-    return hashed.decode()
-
-def verify_password(password: str, hashed: str) -> bool:
-    """Verify password against hash."""
-    return bcrypt.checkpw(password.encode(), hashed.encode())
-```
-
-### 9.2 Secure Random
-```python
-import secrets
-
-def generate_token(length: int = 32) -> str:
-    """Generate cryptographically secure token."""
-    return secrets.token_urlsafe(length)
-
-def generate_pin(length: int = 6) -> str:
-    """Generate secure numeric PIN."""
-    return ''.join(str(secrets.randbelow(10)) for _ in range(length))
-```
-
----
-
-## 10. CODE REVIEW CHECKLIST
-
-### Before Submitting Code:
-- [ ] All user inputs validated
-- [ ] No shell=True in subprocess calls
-- [ ] All file paths validated and sandboxed
-- [ ] Secrets not logged or exposed
-- [ ] URLs validated before fetching
-- [ ] Error messages don't leak sensitive info
-- [ ] No hardcoded credentials
-- [ ] Proper exception handling
-- [ ] Security tests included
-- [ ] Documentation updated
-
-### Security-Focused Review Questions:
-1. What happens if this receives malicious input?
-2. Can this leak sensitive data?
-3. Are there privilege escalation paths?
-4. What if the external service is compromised?
-5. Is the error handling secure?
-
----
-
-## 11. TESTING SECURITY
-
-### 11.1 Security Unit Tests
-```python
-def test_path_traversal_blocked():
-    sandbox = FileSandbox(Path("/safe/path"))
-    with pytest.raises(SecurityError):
-        sandbox.validate_path("../../../etc/passwd")
-
-def test_command_injection_blocked():
-    with pytest.raises(SecurityError):
-        validate_command("ls; rm -rf /")
-
-def test_secret_redaction():
-    text = "Key: sk-test123456789"
-    redacted = redact_secrets(text)
-    assert "sk-test" not in redacted
-```
-
-### 11.2 Fuzzing
-```python
-import hypothesis.strategies as st
-from hypothesis import given
-
-@given(st.text())
-def test_input_validation(input_text):
-    # Should never crash, always validate or reject
-    try:
-        result = process_input(input_text)
-        assert isinstance(result, ExpectedType)
-    except ValidationError:
-        pass  # Expected for invalid input
-```
-
----
-
-## 12. INCIDENT RESPONSE
-
-### Security Incident Procedure:
-1. **Stop** - Halt the affected system/process
-2. **Assess** - Determine scope and impact
-3. **Contain** - Prevent further damage
-4. **Investigate** - Gather evidence
-5. **Remediate** - Fix the vulnerability
-6. **Recover** - Restore normal operations
-7. **Learn** - Document and improve
-
-### Emergency Contacts:
-- Security Team: security@example.com
-- On-call: +1-XXX-XXX-XXXX
-- Slack: #security-incidents
-
----
-
-**Document Owner:** Security Team  
-**Review Cycle:** Quarterly  
-**Last Updated:** March 30, 2026

SECURITY_AUDIT_REPORT.md

@@ -1,705 +0,0 @@
-# HERMES AGENT - COMPREHENSIVE SECURITY AUDIT REPORT
-**Audit Date:** March 30, 2026
-**Auditor:** Security Analysis Agent
-**Scope:** Entire codebase including authentication, command execution, file operations, sandbox environments, and API endpoints
-
----
-
-## EXECUTIVE SUMMARY
-
-The Hermes Agent codebase contains **32 identified security issues** across critical severity (5), high severity (12), medium severity (10), and low severity (5). The most critical vulnerabilities involve command injection vectors, sandbox escape possibilities, and secret leakage risks.
-
-**Overall Security Posture: MODERATE-HIGH RISK**
-- Well-designed approval system for dangerous commands
-- Good secret redaction mechanisms
-- Insufficient input validation in several areas
-- Multiple command injection vectors
-- Incomplete sandbox isolation in some environments
-
----
-
-## 1. CVSS-SCORED VULNERABILITY REPORT
-
-### CRITICAL SEVERITY (CVSS 9.0-10.0)
-
-#### V-001: Command Injection via shell=True in Subprocess Calls
-- **CVSS Score:** 9.8 (Critical)
-- **Location:** `tools/terminal_tool.py`, `tools/file_operations.py`, `tools/environments/*.py`
-- **Description:** Multiple subprocess calls use shell=True with user-controlled input, enabling arbitrary command execution
-- **Attack Vector:** Local/Remote via agent prompts or malicious skills
-- **Evidence:** 
-  ```python
-  # terminal_tool.py line ~460
-  subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, ...)
-  # Command strings constructed from user input without proper sanitization
-  ```
-- **Impact:** Complete system compromise, data exfiltration, malware installation
-- **Remediation:** Use subprocess without shell=True, pass arguments as lists, implement strict input validation
-
-#### V-002: Path Traversal in File Operations
-- **CVSS Score:** 9.1 (Critical)
-- **Location:** `tools/file_operations.py`, `tools/file_tools.py`
-- **Description:** Insufficient path validation allows access to sensitive system files
-- **Attack Vector:** Malicious file paths like `../../../etc/shadow` or `~/.ssh/id_rsa`
-- **Evidence:**
-  ```python
-  # file_operations.py - _expand_path() allows ~username expansion
-  # which can be exploited with crafted usernames
-  ```
-- **Impact:** Unauthorized file read/write, credential theft, system compromise
-- **Remediation:** Implement strict path canonicalization and sandbox boundaries
-
-#### V-003: Secret Leakage via Environment Variables in Sandboxes
-- **CVSS Score:** 9.3 (Critical)
-- **Location:** `tools/code_execution_tool.py`, `tools/environments/*.py`
-- **Description:** Child processes inherit environment variables containing secrets
-- **Attack Vector:** Malicious code executed via execute_code or terminal
-- **Evidence:**
-  ```python
-  # code_execution_tool.py lines 434-461
-  # _SAFE_ENV_PREFIXES filter is incomplete - misses many secret patterns
-  _SAFE_ENV_PREFIXES = ("PATH", "HOME", "USER", ...)
-  _SECRET_SUBSTRINGS = ("TOKEN", "SECRET", "PASSWORD", ...)
-  # Only blocks explicit patterns - many secret env vars slip through
-  ```
-- **Impact:** API key theft, credential exfiltration, unauthorized access to external services
-- **Remediation:** Whitelist-only approach for env vars, explicit secret scanning
-
-#### V-004: Sudo Password Exposure via Command Line
-- **CVSS Score:** 9.0 (Critical)
-- **Location:** `tools/terminal_tool.py`, `_transform_sudo_command()`
-- **Description:** Sudo passwords may be exposed in process lists via command line arguments
-- **Attack Vector:** Local attackers reading /proc or ps output
-- **Evidence:**
-  ```python
-  # Line 275: sudo_stdin passed via printf pipe
-  exec_command = f"printf '%s\\n' {shlex.quote(sudo_stdin.rstrip())} | {exec_command}"
-  ```
-- **Impact:** Privilege escalation credential theft
-- **Remediation:** Use file descriptor passing, avoid shell command construction with secrets
-
-#### V-005: SSRF via Unsafe URL Handling
-- **CVSS Score:** 9.4 (Critical)
-- **Location:** `tools/web_tools.py`, `tools/browser_tool.py`
-- **Description:** URL safety checks can be bypassed via DNS rebinding and redirect chains
-- **Attack Vector:** Malicious URLs targeting internal services (169.254.169.254, localhost)
-- **Evidence:**
-  ```python
-  # url_safety.py - is_safe_url() vulnerable to TOCTOU
-  # DNS resolution and actual connection are separate operations
-  ```
-- **Impact:** Internal service access, cloud metadata theft, port scanning
-- **Remediation:** Implement connection-level validation, use egress proxy
-
----
-
-### HIGH SEVERITY (CVSS 7.0-8.9)
-
-#### V-006: Insecure Deserialization in MCP OAuth
-- **CVSS Score:** 8.8 (High)
-- **Location:** `tools/mcp_oauth.py`, token storage
-- **Description:** JSON token data loaded without schema validation
-- **Attack Vector:** Malicious token files crafted by local attackers
-- **Remediation:** Add JSON schema validation, sign stored tokens
-
-#### V-007: SQL Injection in ResponseStore
-- **CVSS Score:** 8.5 (High)
-- **Location:** `gateway/platforms/api_server.py`, ResponseStore class
-- **Description:** Direct string interpolation in SQLite queries
-- **Evidence:**
-  ```python
-  # Lines 98-106, 114-126 - response_id directly interpolated
-  "SELECT data FROM responses WHERE response_id = ?", (response_id,)
-  # While parameterized, no validation of response_id format
-  ```
-- **Remediation:** Validate response_id format, use UUID strict parsing
-
-#### V-008: CORS Misconfiguration in API Server
-- **CVSS Score:** 8.2 (High)
-- **Location:** `gateway/platforms/api_server.py`, cors_middleware
-- **Description:** Wildcard CORS allowed with credentials
-- **Evidence:**
-  ```python
-  # Line 324-328: "*" in origins allows any domain
-  if "*" in self._cors_origins:
-      headers["Access-Control-Allow-Origin"] = "*"
-  ```
-- **Impact:** Cross-origin attacks, credential theft via malicious websites
-- **Remediation:** Never allow "*" with credentials, implement strict origin validation
-
-#### V-009: Authentication Bypass in API Key Check
-- **CVSS Score:** 8.1 (High)
-- **Location:** `gateway/platforms/api_server.py`, `_check_auth()`
-- **Description:** Empty API key configuration allows all requests
-- **Evidence:**
-  ```python
-  # Line 360-361: No key configured = allow all
-  if not self._api_key:
-      return None  # No key configured — allow all
-  ```
-- **Impact:** Unauthorized API access when key not explicitly set
-- **Remediation:** Require explicit auth configuration, fail-closed default
-
-#### V-010: Code Injection via Browser CDP Override
-- **CVSS Score:** 8.4 (High)
-- **Location:** `tools/browser_tool.py`, `_resolve_cdp_override()`
-- **Description:** User-controlled CDP URL fetched without validation
-- **Evidence:**
-  ```python
-  # Line 195: requests.get(version_url) without URL validation
-  response = requests.get(version_url, timeout=10)
-  ```
-- **Impact:** SSRF, internal service exploitation
-- **Remediation:** Strict URL allowlisting, validate scheme/host
-
-#### V-011: Skills Guard Bypass via Obfuscation
-- **CVSS Score:** 7.8 (High)
-- **Location:** `tools/skills_guard.py`, THREAT_PATTERNS
-- **Description:** Regex-based detection can be bypassed with encoding tricks
-- **Evidence:** Patterns don't cover all Unicode variants, case variations, or encoding tricks
-- **Impact:** Malicious skills installation, code execution
-- **Remediation:** Normalize input before scanning, add AST-based analysis
-
-#### V-012: Privilege Escalation via Docker Socket Mount
-- **CVSS Score:** 8.7 (High)
-- **Location:** `tools/environments/docker.py`, volume mounting
-- **Description:** User-configured volumes can mount Docker socket
-- **Evidence:**
-  ```python
-  # Line 267: volume_args extends with user-controlled vol
-  volume_args.extend(["-v", vol])
-  ```
-- **Impact:** Container escape, host compromise
-- **Remediation:** Blocklist sensitive paths, validate all mount points
-
-#### V-013: Information Disclosure via Error Messages
-- **CVSS Score:** 7.5 (High)
-- **Location:** Multiple files across codebase
-- **Description:** Detailed error messages expose internal paths, versions, configurations
-- **Evidence:** File paths, environment details in exception messages
-- **Impact:** Information gathering for targeted attacks
-- **Remediation:** Sanitize error messages in production, log details internally only
-
-#### V-014: Session Fixation in OAuth Flow
-- **CVSS Score:** 7.6 (High)
-- **Location:** `tools/mcp_oauth.py`, `_wait_for_callback()`
-- **Description:** State parameter not validated against session
-- **Evidence:** Line 186: state returned but not verified against initial value
-- **Impact:** OAuth session hijacking
-- **Remediation:** Cryptographically verify state parameter
-
-#### V-015: Race Condition in File Operations
-- **CVSS Score:** 7.4 (High)
-- **Location:** `tools/file_operations.py`, `ShellFileOperations`
-- **Description:** Time-of-check to time-of-use vulnerabilities in file access
-- **Impact:** Privilege escalation, unauthorized file access
-- **Remediation:** Use file descriptors, avoid path-based operations
-
-#### V-016: Insufficient Rate Limiting
-- **CVSS Score:** 7.3 (High)
-- **Location:** `gateway/platforms/api_server.py`, `gateway/run.py`
-- **Description:** No rate limiting on API endpoints
-- **Impact:** DoS, brute force attacks, resource exhaustion
-- **Remediation:** Implement per-IP and per-user rate limiting
-
-#### V-017: Insecure Temporary File Creation
-- **CVSS Score:** 7.2 (High)
-- **Location:** `tools/code_execution_tool.py`, `tools/credential_files.py`
-- **Description:** Predictable temp file paths, potential symlink attacks
-- **Evidence:**
-  ```python
-  # code_execution_tool.py line 388
-  tmpdir = tempfile.mkdtemp(prefix="hermes_sandbox_")
-  # Predictable naming scheme
-  ```
-- **Impact:** Local privilege escalation via symlink attacks
-- **Remediation:** Use tempfile with proper permissions, random suffixes
-
----
-
-### MEDIUM SEVERITY (CVSS 4.0-6.9)
-
-#### V-018: Weak Approval Pattern Detection
-- **CVSS Score:** 6.5 (Medium)
-- **Location:** `tools/approval.py`, DANGEROUS_PATTERNS
-- **Description:** Pattern list doesn't cover all dangerous command variants
-- **Impact:** Unauthorized dangerous command execution
-- **Remediation:** Expand patterns, add behavioral analysis
-
-#### V-019: Insecure File Permissions on Credentials
-- **CVSS Score:** 6.4 (Medium)
-- **Location:** `tools/credential_files.py`, `tools/mcp_oauth.py`
-- **Description:** Credential files may have overly permissive permissions
-- **Evidence:** 
-  ```python
-  # mcp_oauth.py line 107: chmod 0o600 but no verification
-  path.chmod(0o600)
-  ```
-- **Impact:** Local credential theft
-- **Remediation:** Verify permissions after creation, use secure umask
-
-#### V-020: Log Injection via Unsanitized Input
-- **CVSS Score:** 5.8 (Medium)
-- **Location:** Multiple logging statements across codebase
-- **Description:** User-controlled data written directly to logs
-- **Impact:** Log poisoning, log analysis bypass
-- **Remediation:** Sanitize all logged data, use structured logging
-
-#### V-021: XML External Entity (XXE) Risk
-- **CVSS Score:** 6.2 (Medium)
-- **Location:** `skills/productivity/powerpoint/scripts/office/schemas/` XML parsing
-- **Description:** PowerPoint processing uses XML without explicit XXE protection
-- **Impact:** File disclosure, SSRF via XML entities
-- **Remediation:** Disable external entities in XML parsers
-
-#### V-022: Unsafe YAML Loading
-- **CVSS Score:** 6.1 (Medium)
-- **Location:** `hermes_cli/config.py`, `tools/skills_guard.py`
-- **Description:** yaml.safe_load used but custom constructors may be risky
-- **Impact:** Code execution via malicious YAML
-- **Remediation:** Audit all YAML loading, disable unsafe tags
-
-#### V-023: Prototype Pollution in JavaScript Bridge
-- **CVSS Score:** 5.9 (Medium)
-- **Location:** `scripts/whatsapp-bridge/bridge.js`
-- **Description:** Object property assignments without validation
-- **Impact:** Logic bypass, potential RCE in Node context
-- **Remediation:** Validate all object keys, use Map instead of Object
-
-#### V-024: Insufficient Subagent Isolation
-- **CVSS Score:** 6.3 (Medium)
-- **Location:** `tools/delegate_tool.py`
-- **Description:** Subagents share filesystem and network with parent
-- **Impact:** Lateral movement, privilege escalation between agents
-- **Remediation:** Implement stronger sandbox boundaries per subagent
-
-#### V-025: Predictable Session IDs
-- **CVSS Score:** 5.5 (Medium)
-- **Location:** `gateway/session.py`, `tools/terminal_tool.py`
-- **Description:** Session/task IDs use uuid4 but may be logged/predictable
-- **Impact:** Session hijacking
-- **Remediation:** Use cryptographically secure random, short-lived tokens
-
-#### V-026: Missing Integrity Checks on External Binaries
-- **CVSS Score:** 5.7 (Medium)
-- **Location:** `tools/tirith_security.py`, auto-install process
-- **Description:** Binary download with limited verification
-- **Evidence:** SHA-256 verified but no code signing verification by default
-- **Impact:** Supply chain compromise
-- **Remediation:** Require signature verification, pin versions
-
-#### V-027: Information Leakage in Debug Mode
-- **CVSS Score:** 5.2 (Medium)
-- **Location:** `tools/debug_helpers.py`, `agent/display.py`
-- **Description:** Debug output may contain sensitive configuration
-- **Impact:** Information disclosure
-- **Remediation:** Redact secrets in all debug output
-
----
-
-### LOW SEVERITY (CVSS 0.1-3.9)
-
-#### V-028: Missing Security Headers
-- **CVSS Score:** 3.7 (Low)
-- **Location:** `gateway/platforms/api_server.py`
-- **Description:** Some security headers missing (CSP, HSTS)
-- **Remediation:** Add comprehensive security headers
-
-#### V-029: Verbose Version Information
-- **CVSS Score:** 2.3 (Low)
-- **Location:** Multiple version endpoints
-- **Description:** Detailed version information exposed
-- **Remediation:** Minimize version disclosure
-
-#### V-030: Unused Imports and Dead Code
-- **CVSS Score:** 2.0 (Low)
-- **Location:** Multiple files
-- **Description:** Dead code increases attack surface
-- **Remediation:** Remove unused code, regular audits
-
-#### V-031: Weak Cryptographic Practices
-- **CVSS Score:** 3.2 (Low)
-- **Location:** `hermes_cli/auth.py`, token handling
-- **Description:** No encryption at rest for auth tokens
-- **Remediation:** Use OS keychain, encrypt sensitive data
-
-#### V-032: Missing Input Length Validation
-- **CVSS Score:** 3.5 (Low)
-- **Location:** Multiple tool input handlers
-- **Description:** No maximum length checks on inputs
-- **Remediation:** Add length validation to all inputs
-
----
-
-## 2. ATTACK SURFACE DIAGRAM
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                           EXTERNAL ATTACK SURFACE                           │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
-│  │   Telegram   │  │   Discord    │  │    Slack     │  │  Web Browser │   │
-│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘   │
-│         │                 │                 │                │            │
-│  ┌──────▼───────┐  ┌──────▼───────┐  ┌──────▼───────┐  ┌──────▼───────┐   │
-│  │   Gateway    │──│   Gateway    │──│   Gateway    │──│   Gateway    │   │
-│  │   Adapter    │  │   Adapter    │  │   Adapter    │  │   Adapter    │   │
-│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘   │
-│         └─────────────────┴─────────────────┘                │            │
-│                           │                                  │            │
-│                    ┌──────▼───────┐                  ┌──────▼───────┐    │
-│                    │  API Server  │◄─────────────────│   Web API    │    │
-│                    │   (HTTP)     │                  │   Endpoints  │    │
-│                    └──────┬───────┘                  └──────────────┘    │
-│                           │                                               │
-└───────────────────────────┼───────────────────────────────────────────────┘
-                            │
-┌───────────────────────────┼───────────────────────────────────────────────┐
-│                     INTERNAL ATTACK SURFACE                                 │
-├───────────────────────────┼───────────────────────────────────────────────┤
-│                           │                                                │
-│                    ┌──────▼───────┐                                        │
-│                    │  AI Agent    │                                        │
-│                    │   Core       │                                        │
-│                    └──────┬───────┘                                        │
-│                           │                                                │
-│         ┌─────────────────┼─────────────────┐                              │
-│         │                 │                 │                              │
-│    ┌────▼────┐      ┌────▼────┐      ┌────▼────┐                         │
-│    │  Tools  │      │  Tools  │      │  Tools  │                         │
-│    │  File   │      │ Terminal│      │  Web    │                         │
-│    │  Ops    │      │  Exec   │      │  Tools  │                         │
-│    └────┬────┘      └────┬────┘      └────┬────┘                         │
-│         │                 │                 │                              │
-│    ┌────▼────┐      ┌────▼────┐      ┌────▼────┐                         │
-│    │  Local  │      │ Docker  │      │ Browser │                         │
-│    │   FS    │      │Sandbox  │      │  Tool   │                         │
-│    └─────────┘      └────┬────┘      └────┬────┘                         │
-│                          │                 │                               │
-│                    ┌─────▼─────┐     ┌────▼────┐                         │
-│                    │   Modal   │     │ Cloud   │                         │
-│                    │   Cloud   │     │ Browser │                         │
-│                    └───────────┘     └─────────┘                         │
-│                                                                          │
-│  ┌─────────────────────────────────────────────────────────────────┐    │
-│  │                    CREDENTIAL STORAGE                           │    │
-│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │    │
-│  │  │ auth.json│  │  .env    │  │mcp-tokens│  │ skill    │        │    │
-│  │  │ (OAuth)  │  │ (API Key)│  │ (OAuth)  │  │  creds   │        │    │
-│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │    │
-│  └─────────────────────────────────────────────────────────────────┘    │
-│                                                                          │
-└──────────────────────────────────────────────────────────────────────────┘
-
-LEGEND:
-  ■ Entry points (external attack surface)
-  ■ Internal components (privilege escalation targets)
-  ■ Credential storage (high-value targets)
-  ■ Sandboxed environments (isolation boundaries)
-```
-
----
-
-## 3. MITIGATION ROADMAP
-
-### Phase 1: Critical Fixes (Week 1-2)
-
-| Priority | Fix | Owner | Est. Hours |
-|----------|-----|-------|------------|
-| P0 | Remove all shell=True subprocess calls | Security Team | 16 |
-| P0 | Implement strict path sandboxing | Security Team | 12 |
-| P0 | Fix secret leakage in child processes | Security Team | 8 |
-| P0 | Add connection-level URL validation | Security Team | 8 |
-
-### Phase 2: High Priority (Week 3-4)
-
-| Priority | Fix | Owner | Est. Hours |
-|----------|-----|-------|------------|
-| P1 | Implement proper input validation framework | Dev Team | 20 |
-| P1 | Add CORS strict mode | Dev Team | 4 |
-| P1 | Fix OAuth state validation | Dev Team | 6 |
-| P1 | Add rate limiting | Dev Team | 10 |
-| P1 | Implement secure credential storage | Security Team | 12 |
-
-### Phase 3: Medium Priority (Month 2)
-
-| Priority | Fix | Owner | Est. Hours |
-|----------|-----|-------|------------|
-| P2 | Expand dangerous command patterns | Security Team | 6 |
-| P2 | Add AST-based skill scanning | Security Team | 16 |
-| P2 | Implement subagent isolation | Dev Team | 20 |
-| P2 | Add comprehensive audit logging | Dev Team | 12 |
-
-### Phase 4: Long-term Improvements (Month 3+)
-
-| Priority | Fix | Owner | Est. Hours |
-|----------|-----|-------|------------|
-| P3 | Security headers hardening | Dev Team | 4 |
-| P3 | Code signing verification | Security Team | 8 |
-| P3 | Supply chain security | Dev Team | 12 |
-| P3 | Regular security audits | Security Team | Ongoing |
-
----
-
-## 4. SECURE CODING GUIDELINES
-
-### 4.1 Command Execution
-```python
-# ❌ NEVER DO THIS
-subprocess.run(f"ls {user_input}", shell=True)
-
-# ✅ DO THIS
-subprocess.run(["ls", user_input], shell=False)
-
-# ✅ OR USE SHLEX
-import shlex
-subprocess.run(["ls"] + shlex.split(user_input), shell=False)
-```
-
-### 4.2 Path Handling
-```python
-# ❌ NEVER DO THIS
-open(os.path.expanduser(user_path), "r")
-
-# ✅ DO THIS
-from pathlib import Path
-safe_root = Path("/allowed/path").resolve()
-user_path = Path(user_path).expanduser().resolve()
-if not str(user_path).startswith(str(safe_root)):
-    raise PermissionError("Path outside sandbox")
-```
-
-### 4.3 Secret Handling
-```python
-# ❌ NEVER DO THIS
-os.environ["API_KEY"] = user_api_key  # Visible to all child processes
-
-# ✅ DO THIS
-# Use file descriptor passing or explicit whitelisting
-child_env = {k: v for k, v in os.environ.items() 
-             if k in ALLOWED_ENV_VARS}
-```
-
-### 4.4 URL Validation
-```python
-# ❌ NEVER DO THIS
-response = requests.get(user_url)
-
-# ✅ DO THIS
-from urllib.parse import urlparse
-parsed = urlparse(user_url)
-if parsed.scheme not in ("http", "https"):
-    raise ValueError("Invalid scheme")
-if parsed.hostname not in ALLOWED_HOSTS:
-    raise ValueError("Host not allowed")
-```
-
-### 4.5 Input Validation
-```python
-# Use pydantic for all user inputs
-from pydantic import BaseModel, validator
-
-class FileRequest(BaseModel):
-    path: str
-    max_size: int = 1000
-    
-    @validator('path')
-    def validate_path(cls, v):
-        if '..' in v or v.startswith('/'):
-            raise ValueError('Invalid path')
-        return v
-```
-
----
-
-## 5. SPECIFIC SECURITY FIXES NEEDED
-
-### Fix 1: Terminal Tool Command Injection (V-001)
-```python
-# CURRENT CODE (tools/terminal_tool.py ~line 457)
-cmd = [self._docker_exe, "exec", "-w", work_dir, self._container_id, 
-       "bash", "-lc", exec_command]
-
-# SECURE FIX
-cmd = [self._docker_exe, "exec", "-w", work_dir, self._container_id, 
-       "bash", "-lc", exec_command]
-# Add strict input validation before this point
-if not _is_safe_command(exec_command):
-    raise SecurityError("Dangerous command detected")
-```
-
-### Fix 2: File Operations Path Traversal (V-002)
-```python
-# CURRENT CODE (tools/file_operations.py ~line 409)
-def _expand_path(self, path: str) -> str:
-    if path.startswith('~'):
-        # ... expansion logic
-
-# SECURE FIX
-def _expand_path(self, path: str) -> str:
-    safe_root = Path(self.cwd).resolve()
-    expanded = Path(path).expanduser().resolve()
-    if not str(expanded).startswith(str(safe_root)):
-        raise PermissionError(f"Path {path} outside allowed directory")
-    return str(expanded)
-```
-
-### Fix 3: Code Execution Environment Sanitization (V-003)
-```python
-# CURRENT CODE (tools/code_execution_tool.py ~lines 434-461)
-_SAFE_ENV_PREFIXES = ("PATH", "HOME", "USER", ...)
-_SECRET_SUBSTRINGS = ("TOKEN", "SECRET", ...)
-
-# SECURE FIX - Whitelist approach
-_ALLOWED_ENV_VARS = frozenset([
-    "PATH", "HOME", "USER", "LANG", "LC_ALL", 
-    "PYTHONPATH", "TERM", "SHELL", "PWD"
-])
-child_env = {k: v for k, v in os.environ.items() 
-             if k in _ALLOWED_ENV_VARS}
-# Explicitly load only non-secret values
-```
-
-### Fix 4: API Server Authentication (V-009)
-```python
-# CURRENT CODE (gateway/platforms/api_server.py ~line 360-361)
-if not self._api_key:
-    return None  # No key configured — allow all
-
-# SECURE FIX
-if not self._api_key:
-    logger.error("API server started without authentication")
-    return web.json_response(
-        {"error": "Server misconfigured - auth required"},
-        status=500
-    )
-```
-
-### Fix 5: CORS Configuration (V-008)
-```python
-# CURRENT CODE (gateway/platforms/api_server.py ~lines 324-328)
-if "*" in self._cors_origins:
-    headers["Access-Control-Allow-Origin"] = "*"
-
-# SECURE FIX - Never allow wildcard with credentials
-if "*" in self._cors_origins:
-    logger.warning("Wildcard CORS not allowed with credentials")
-    return None
-```
-
-### Fix 6: OAuth State Validation (V-014)
-```python
-# CURRENT CODE (tools/mcp_oauth.py ~line 186)
-code, state = await _wait_for_callback()
-
-# SECURE FIX
-stored_state = get_stored_state()
-if state != stored_state:
-    raise SecurityError("OAuth state mismatch - possible CSRF attack")
-```
-
-### Fix 7: Docker Volume Mount Validation (V-012)
-```python
-# CURRENT CODE (tools/environments/docker.py ~line 267)
-volume_args.extend(["-v", vol])
-
-# SECURE FIX
-_BLOCKED_PATHS = ['/var/run/docker.sock', '/proc', '/sys', ...]
-if any(blocked in vol for blocked in _BLOCKED_PATHS):
-    raise SecurityError(f"Volume mount {vol} not allowed")
-volume_args.extend(["-v", vol])
-```
-
-### Fix 8: Debug Output Redaction (V-027)
-```python
-# Add to all debug logging
-from agent.redact import redact_sensitive_text
-logger.debug(redact_sensitive_text(debug_message))
-```
-
-### Fix 9: Input Length Validation
-```python
-# Add to all tool entry points
-MAX_INPUT_LENGTH = 10000
-if len(user_input) > MAX_INPUT_LENGTH:
-    raise ValueError(f"Input exceeds maximum length of {MAX_INPUT_LENGTH}")
-```
-
-### Fix 10: Session ID Entropy
-```python
-# CURRENT CODE - uses uuid4
-import uuid
-session_id = str(uuid.uuid4())
-
-# SECURE FIX - use secrets module
-import secrets
-session_id = secrets.token_urlsafe(32)
-```
-
-### Fix 11-20: Additional Required Fixes
-11. **Add CSRF protection** to all state-changing operations
-12. **Implement request signing** for internal service communication
-13. **Add certificate pinning** for external API calls
-14. **Implement proper key rotation** for auth tokens
-15. **Add anomaly detection** for unusual command patterns
-16. **Implement network segmentation** for sandbox environments
-17. **Add hardware security module (HSM) support** for key storage
-18. **Implement behavioral analysis** for skill code
-19. **Add automated vulnerability scanning** to CI/CD pipeline
-20. **Implement incident response procedures** for security events
-
----
-
-## 6. SECURITY RECOMMENDATIONS
-
-### Immediate Actions (Within 24 hours)
-1. Disable gateway API server if not required
-2. Enable HERMES_YOLO_MODE only for trusted users
-3. Review all installed skills from community sources
-4. Enable comprehensive audit logging
-
-### Short-term Actions (Within 1 week)
-1. Deploy all P0 fixes
-2. Implement monitoring for suspicious command patterns
-3. Conduct security training for developers
-4. Establish security review process for new features
-
-### Long-term Actions (Within 1 month)
-1. Implement comprehensive security testing
-2. Establish bug bounty program
-3. Regular third-party security audits
-4. Achieve SOC 2 compliance
-
----
-
-## 7. COMPLIANCE MAPPING
-
-| Vulnerability | OWASP Top 10 | CWE | NIST 800-53 |
-|---------------|--------------|-----|-------------|
-| V-001 (Command Injection) | A03:2021 - Injection | CWE-78 | SI-10 |
-| V-002 (Path Traversal) | A01:2021 - Broken Access Control | CWE-22 | AC-3 |
-| V-003 (Secret Leakage) | A07:2021 - Auth Failures | CWE-200 | SC-28 |
-| V-005 (SSRF) | A10:2021 - SSRF | CWE-918 | SC-7 |
-| V-008 (CORS) | A05:2021 - Security Misconfig | CWE-942 | AC-4 |
-| V-011 (Skills Bypass) | A08:2021 - Integrity Failures | CWE-353 | SI-7 |
-
----
-
-## APPENDIX A: TESTING RECOMMENDATIONS
-
-### Security Test Cases
-1. Command injection with `; rm -rf /`
-2. Path traversal with `../../../etc/passwd`
-3. SSRF with `http://169.254.169.254/latest/meta-data/`
-4. Secret exfiltration via environment variables
-5. OAuth flow manipulation
-6. Rate limiting bypass
-7. Session fixation attacks
-8. Privilege escalation via sudo
-
----
-
-**Report End**
-
-*This audit represents a point-in-time assessment. Security is an ongoing process requiring continuous monitoring and improvement.*

SECURITY_FIXES_CHECKLIST.md

@@ -1,488 +0,0 @@
-# SECURITY FIXES CHECKLIST
-
-## 20+ Specific Security Fixes Required
-
-This document provides a detailed checklist of all security fixes identified in the comprehensive audit.
-
----
-
-## CRITICAL FIXES (Must implement immediately)
-
-### Fix 1: Remove shell=True from subprocess calls
-**File:** `tools/terminal_tool.py`  
-**Line:** ~457  
-**CVSS:** 9.8
-
-```python
-# BEFORE
-subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, ...)
-
-# AFTER
-# Validate command first
-if not is_safe_command(exec_command):
-    raise SecurityError("Dangerous command detected")
-subprocess.Popen(cmd_list, shell=False, ...)  # Pass as list
-```
-
----
-
-### Fix 2: Implement path sandbox validation
-**File:** `tools/file_operations.py`  
-**Lines:** 409-420  
-**CVSS:** 9.1
-
-```python
-# BEFORE
-def _expand_path(self, path: str) -> str:
-    if path.startswith('~'):
-        return os.path.expanduser(path)
-    return path
-
-# AFTER
-def _expand_path(self, path: str) -> Path:
-    safe_root = Path(self.cwd).resolve()
-    expanded = Path(path).expanduser().resolve()
-    if not str(expanded).startswith(str(safe_root)):
-        raise PermissionError(f"Path {path} outside allowed directory")
-    return expanded
-```
-
----
-
-### Fix 3: Environment variable sanitization
-**File:** `tools/code_execution_tool.py`  
-**Lines:** 434-461  
-**CVSS:** 9.3
-
-```python
-# BEFORE
-_SAFE_ENV_PREFIXES = ("PATH", "HOME", "USER", ...)
-_SECRET_SUBSTRINGS = ("TOKEN", "SECRET", ...)
-
-# AFTER
-_ALLOWED_ENV_VARS = frozenset([
-    "PATH", "HOME", "USER", "LANG", "LC_ALL", 
-    "TERM", "SHELL", "PWD", "PYTHONPATH"
-])
-child_env = {k: v for k, v in os.environ.items() 
-             if k in _ALLOWED_ENV_VARS}
-```
-
----
-
-### Fix 4: Secure sudo password handling
-**File:** `tools/terminal_tool.py`  
-**Line:** 275  
-**CVSS:** 9.0
-
-```python
-# BEFORE
-exec_command = f"printf '%s\\n' {shlex.quote(sudo_stdin.rstrip())} | {exec_command}"
-
-# AFTER
-# Use file descriptor passing instead of command line
-with tempfile.NamedTemporaryFile(mode='w', delete=False) as f:
-    f.write(sudo_stdin)
-    pass_file = f.name
-os.chmod(pass_file, 0o600)
-exec_command = f"cat {pass_file} | {exec_command}"
-# Clean up after execution
-```
-
----
-
-### Fix 5: Connection-level URL validation
-**File:** `tools/url_safety.py`  
-**Lines:** 50-96  
-**CVSS:** 9.4
-
-```python
-# AFTER - Add to is_safe_url()
-# After DNS resolution, verify IP is not in private range
-def _validate_connection_ip(hostname: str) -> bool:
-    try:
-        addr = socket.getaddrinfo(hostname, None)
-        for a in addr:
-            ip = ipaddress.ip_address(a[4][0])
-            if ip.is_private or ip.is_loopback or ip.is_reserved:
-                return False
-        return True
-    except:
-        return False
-```
-
----
-
-## HIGH PRIORITY FIXES
-
-### Fix 6: MCP OAuth token validation
-**File:** `tools/mcp_oauth.py`  
-**Lines:** 66-89  
-**CVSS:** 8.8
-
-```python
-# AFTER
-async def get_tokens(self):
-    data = self._read_json(self._tokens_path())
-    if not data:
-        return None
-    # Add schema validation
-    if not self._validate_token_schema(data):
-        logger.error("Invalid token schema, deleting corrupted tokens")
-        self.remove()
-        return None
-    return OAuthToken(**data)
-```
-
----
-
-### Fix 7: API Server SQL injection prevention
-**File:** `gateway/platforms/api_server.py`  
-**Lines:** 98-126  
-**CVSS:** 8.5
-
-```python
-# AFTER
-import uuid
-
-def _validate_response_id(self, response_id: str) -> bool:
-    """Validate response_id format to prevent injection."""
-    try:
-        uuid.UUID(response_id.split('-')[0], version=4)
-        return True
-    except (ValueError, IndexError):
-        return False
-```
-
----
-
-### Fix 8: CORS strict validation
-**File:** `gateway/platforms/api_server.py`  
-**Lines:** 324-328  
-**CVSS:** 8.2
-
-```python
-# AFTER
-if "*" in self._cors_origins:
-    logger.error("Wildcard CORS not allowed with credentials")
-    return None  # Reject wildcard with credentials
-```
-
----
-
-### Fix 9: Require explicit API key
-**File:** `gateway/platforms/api_server.py`  
-**Lines:** 360-361  
-**CVSS:** 8.1
-
-```python
-# AFTER
-if not self._api_key:
-    logger.error("API server started without authentication")
-    return web.json_response(
-        {"error": "Server authentication not configured"},
-        status=500
-    )
-```
-
----
-
-### Fix 10: CDP URL validation
-**File:** `tools/browser_tool.py`  
-**Lines:** 195-208  
-**CVSS:** 8.4
-
-```python
-# AFTER
-def _resolve_cdp_override(self, cdp_url: str) -> str:
-    parsed = urlparse(cdp_url)
-    if parsed.scheme not in ('ws', 'wss', 'http', 'https'):
-        raise ValueError("Invalid CDP scheme")
-    if parsed.hostname not in self._allowed_cdp_hosts:
-        raise ValueError("CDP host not in allowlist")
-    return cdp_url
-```
-
----
-
-### Fix 11: Skills guard normalization
-**File:** `tools/skills_guard.py`  
-**Lines:** 82-484  
-**CVSS:** 7.8
-
-```python
-# AFTER - Add to scan_skill()
-def normalize_for_scanning(content: str) -> str:
-    """Normalize content to detect obfuscated threats."""
-    # Normalize Unicode
-    content = unicodedata.normalize('NFKC', content)
-    # Normalize case
-    content = content.lower()
-    # Remove common obfuscation
-    content = content.replace('\\x', '')
-    content = content.replace('\\u', '')
-    return content
-```
-
----
-
-### Fix 12: Docker volume validation
-**File:** `tools/environments/docker.py`  
-**Line:** 267  
-**CVSS:** 8.7
-
-```python
-# AFTER
-_BLOCKED_PATHS = ['/var/run/docker.sock', '/proc', '/sys', '/dev']
-for vol in volumes:
-    if any(blocked in vol for blocked in _BLOCKED_PATHS):
-        raise SecurityError(f"Volume mount {vol} blocked")
-    volume_args.extend(["-v", vol])
-```
-
----
-
-### Fix 13: Secure error messages
-**File:** Multiple files  
-**CVSS:** 7.5
-
-```python
-# AFTER - Add to all exception handlers
-try:
-    operation()
-except Exception as e:
-    logger.error(f"Error: {e}", exc_info=True)  # Full details for logs
-    raise UserError("Operation failed")  # Generic for user
-```
-
----
-
-### Fix 14: OAuth state validation
-**File:** `tools/mcp_oauth.py`  
-**Line:** 186  
-**CVSS:** 7.6
-
-```python
-# AFTER
-code, state = await _wait_for_callback()
-stored_state = storage.get_state()
-if not hmac.compare_digest(state, stored_state):
-    raise SecurityError("OAuth state mismatch - possible CSRF")
-```
-
----
-
-### Fix 15: File operation race condition fix
-**File:** `tools/file_operations.py`  
-**CVSS:** 7.4
-
-```python
-# AFTER
-import fcntl
-
-def safe_file_access(path: Path):
-    fd = os.open(path, os.O_RDONLY)
-    try:
-        fcntl.flock(fd, fcntl.LOCK_SH)
-        # Perform operations on fd, not path
-        return os.read(fd, size)
-    finally:
-        fcntl.flock(fd, fcntl.LOCK_UN)
-        os.close(fd)
-```
-
----
-
-### Fix 16: Add rate limiting
-**File:** `gateway/platforms/api_server.py`  
-**CVSS:** 7.3
-
-```python
-# AFTER - Add middleware
-from aiohttp_limiter import Limiter
-
-limiter = Limiter(
-    rate=100,  # requests
-    per=60,    # per minute
-    key_func=lambda req: req.remote
-)
-
-@app.middleware
-async def rate_limit_middleware(request, handler):
-    if not limiter.is_allowed(request):
-        return web.json_response(
-            {"error": "Rate limit exceeded"}, 
-            status=429
-        )
-    return await handler(request)
-```
-
----
-
-### Fix 17: Secure temp file creation
-**File:** `tools/code_execution_tool.py`  
-**Line:** 388  
-**CVSS:** 7.2
-
-```python
-# AFTER
-import tempfile
-import os
-
-fd, tmpdir = tempfile.mkstemp(prefix="hermes_sandbox_", suffix=".tmp")
-os.chmod(tmpdir, 0o700)  # Owner only
-os.close(fd)
-# Use tmpdir securely
-```
-
----
-
-## MEDIUM PRIORITY FIXES
-
-### Fix 18: Expand dangerous patterns
-**File:** `tools/approval.py`  
-**Lines:** 40-78  
-**CVSS:** 6.5
-
-Add patterns:
-```python
-(r'\bcurl\s+.*\|\s*sh\b', "pipe remote content to shell"),
-(r'\bwget\s+.*\|\s*bash\b', "pipe remote content to shell"),
-(r'python\s+-c\s+.*import\s+os', "python os import"),
-(r'perl\s+-e\s+.*system', "perl system call"),
-```
-
----
-
-### Fix 19: Credential file permissions
-**File:** `tools/credential_files.py`, `tools/mcp_oauth.py`  
-**CVSS:** 6.4
-
-```python
-# AFTER
-def _write_json(path: Path, data: dict) -> None:
-    path.write_text(json.dumps(data, indent=2), encoding="utf-8")
-    path.chmod(0o600)
-    # Verify permissions were set
-    stat = path.stat()
-    if stat.st_mode & 0o077:
-        raise SecurityError("Failed to set restrictive permissions")
-```
-
----
-
-### Fix 20: Log sanitization
-**File:** Multiple logging statements  
-**CVSS:** 5.8
-
-```python
-# AFTER
-from agent.redact import redact_sensitive_text
-
-# In all logging calls
-logger.info(redact_sensitive_text(f"Processing {user_input}"))
-```
-
----
-
-## ADDITIONAL FIXES (21-32)
-
-### Fix 21: XXE Prevention
-**File:** PowerPoint XML processing  
-Add:
-```python
-from defusedxml import ElementTree as ET
-# Use defusedxml instead of standard xml
-```
-
----
-
-### Fix 22: YAML Safe Loading Audit
-**File:** `hermes_cli/config.py`  
-Audit all yaml.safe_load calls for custom constructors.
-
----
-
-### Fix 23: Prototype Pollution Fix
-**File:** `scripts/whatsapp-bridge/bridge.js`  
-Use Map instead of Object for user-controlled keys.
-
----
-
-### Fix 24: Subagent Isolation
-**File:** `tools/delegate_tool.py`  
-Implement filesystem namespace isolation.
-
----
-
-### Fix 25: Secure Session IDs
-**File:** `gateway/session.py`  
-Use secrets.token_urlsafe(32) instead of uuid4.
-
----
-
-### Fix 26: Binary Integrity Checks
-**File:** `tools/tirith_security.py`  
-Require GPG signature verification.
-
----
-
-### Fix 27: Debug Output Redaction
-**File:** `tools/debug_helpers.py`  
-Apply redact_sensitive_text to all debug output.
-
----
-
-### Fix 28: Security Headers
-**File:** `gateway/platforms/api_server.py`  
-Add:
-```python
-"Content-Security-Policy": "default-src 'self'",
-"Strict-Transport-Security": "max-age=31536000",
-```
-
----
-
-### Fix 29: Version Information Minimization
-**File:** Version endpoints  
-Return minimal version information publicly.
-
----
-
-### Fix 30: Dead Code Removal
-**File:** Multiple  
-Remove unused imports and functions.
-
----
-
-### Fix 31: Token Encryption at Rest
-**File:** `hermes_cli/auth.py`  
-Use OS keychain or encrypt auth.json.
-
----
-
-### Fix 32: Input Length Validation
-**File:** All tool entry points  
-Add MAX_INPUT_LENGTH checks everywhere.
-
----
-
-## IMPLEMENTATION VERIFICATION
-
-### Testing Requirements
-- [ ] All fixes have unit tests
-- [ ] Security regression tests pass
-- [ ] Fuzzing shows no new vulnerabilities
-- [ ] Penetration test completed
-- [ ] Code review by security team
-
-### Sign-off Required
-- [ ] Security Team Lead
-- [ ] Engineering Manager
-- [ ] QA Lead
-- [ ] DevOps Lead
-
----
-
-**Last Updated:** March 30, 2026  
-**Next Review:** After all P0/P1 fixes completed

SECURITY_MITIGATION_ROADMAP.md

@@ -1,359 +0,0 @@
-# SECURITY MITIGATION ROADMAP
-
-## Hermes Agent Security Remediation Plan
-**Version:** 1.0  
-**Date:** March 30, 2026  
-**Status:** Draft for Implementation
-
----
-
-## EXECUTIVE SUMMARY
-
-This roadmap provides a structured approach to addressing the 32 security vulnerabilities identified in the comprehensive security audit. The plan is organized into four phases, prioritizing fixes by risk and impact.
-
----
-
-## PHASE 1: CRITICAL FIXES (Week 1-2)
-**Target:** Eliminate all CVSS 9.0+ vulnerabilities
-
-### 1.1 Remove shell=True Subprocess Calls (V-001)
-**Owner:** Security Team Lead  
-**Estimated Effort:** 16 hours  
-**Priority:** P0
-
-#### Tasks:
-- [ ] Audit all subprocess calls in codebase
-- [ ] Replace shell=True with argument lists
-- [ ] Implement shlex.quote for necessary string interpolation
-- [ ] Add input validation wrappers
-
-#### Files to Modify:
-- `tools/terminal_tool.py`
-- `tools/file_operations.py`
-- `tools/environments/docker.py`
-- `tools/environments/modal.py`
-- `tools/environments/ssh.py`
-- `tools/environments/singularity.py`
-
-#### Testing:
-- [ ] Unit tests for all command execution paths
-- [ ] Fuzzing with malicious inputs
-- [ ] Penetration testing
-
----
-
-### 1.2 Implement Strict Path Sandboxing (V-002)
-**Owner:** Security Team Lead  
-**Estimated Effort:** 12 hours  
-**Priority:** P0
-
-#### Tasks:
-- [ ] Create PathValidator class
-- [ ] Implement canonical path resolution
-- [ ] Add path traversal detection
-- [ ] Enforce sandbox root boundaries
-
-#### Implementation:
-```python
-class PathValidator:
-    def __init__(self, sandbox_root: Path):
-        self.sandbox_root = sandbox_root.resolve()
-    
-    def validate(self, user_path: str) -> Path:
-        expanded = Path(user_path).expanduser().resolve()
-        if not str(expanded).startswith(str(self.sandbox_root)):
-            raise SecurityError("Path outside sandbox")
-        return expanded
-```
-
-#### Files to Modify:
-- `tools/file_operations.py`
-- `tools/file_tools.py`
-- All environment implementations
-
----
-
-### 1.3 Fix Secret Leakage in Child Processes (V-003)
-**Owner:** Security Engineer  
-**Estimated Effort:** 8 hours  
-**Priority:** P0
-
-#### Tasks:
-- [ ] Create environment variable whitelist
-- [ ] Implement secret detection patterns
-- [ ] Add env var scrubbing for child processes
-- [ ] Audit credential file mounting
-
-#### Whitelist Approach:
-```python
-_ALLOWED_ENV_VARS = frozenset([
-    "PATH", "HOME", "USER", "LANG", "LC_ALL",
-    "TERM", "SHELL", "PWD", "OLDPWD",
-    "PYTHONPATH", "PYTHONHOME", "PYTHONNOUSERSITE",
-    "DISPLAY", "XDG_SESSION_TYPE",  # GUI apps
-])
-
-def sanitize_environment():
-    return {k: v for k, v in os.environ.items() 
-            if k in _ALLOWED_ENV_VARS}
-```
-
----
-
-### 1.4 Add Connection-Level URL Validation (V-005)
-**Owner:** Security Engineer  
-**Estimated Effort:** 8 hours  
-**Priority:** P0
-
-#### Tasks:
-- [ ] Implement egress proxy option
-- [ ] Add connection-level IP validation
-- [ ] Validate redirect targets
-- [ ] Block private IP ranges at socket level
-
----
-
-## PHASE 2: HIGH PRIORITY (Week 3-4)
-**Target:** Address all CVSS 7.0-8.9 vulnerabilities
-
-### 2.1 Implement Input Validation Framework (V-006, V-007)
-**Owner:** Senior Developer  
-**Estimated Effort:** 20 hours  
-**Priority:** P1
-
-#### Tasks:
-- [ ] Create Pydantic models for all tool inputs
-- [ ] Implement length validation
-- [ ] Add character allowlisting
-- [ ] Create validation decorators
-
----
-
-### 2.2 Fix CORS Configuration (V-008)
-**Owner:** Backend Developer  
-**Estimated Effort:** 4 hours  
-**Priority:** P1
-
-#### Changes:
-- Remove wildcard support when credentials enabled
-- Implement strict origin validation
-- Add origin allowlist configuration
-
----
-
-### 2.3 Fix Authentication Bypass (V-009)
-**Owner:** Backend Developer  
-**Estimated Effort:** 4 hours  
-**Priority:** P1
-
-#### Changes:
-```python
-# Fail-closed default
-if not self._api_key:
-    logger.error("API server requires authentication")
-    return web.json_response(
-        {"error": "Authentication required"},
-        status=401
-    )
-```
-
----
-
-### 2.4 Fix OAuth State Validation (V-014)
-**Owner:** Security Engineer  
-**Estimated Effort:** 6 hours  
-**Priority:** P1
-
-#### Tasks:
-- Store state parameter in session
-- Cryptographically verify callback state
-- Implement state expiration
-
----
-
-### 2.5 Add Rate Limiting (V-016)
-**Owner:** Backend Developer  
-**Estimated Effort:** 10 hours  
-**Priority:** P1
-
-#### Implementation:
-- Per-IP rate limiting: 100 requests/minute
-- Per-user rate limiting: 1000 requests/hour
-- Endpoint-specific limits
-- Sliding window algorithm
-
----
-
-### 2.6 Secure Credential Storage (V-019, V-031)
-**Owner:** Security Engineer  
-**Estimated Effort:** 12 hours  
-**Priority:** P1
-
-#### Tasks:
-- Implement OS keychain integration
-- Add file encryption at rest
-- Implement secure key derivation
-- Add access audit logging
-
----
-
-## PHASE 3: MEDIUM PRIORITY (Month 2)
-**Target:** Address CVSS 4.0-6.9 vulnerabilities
-
-### 3.1 Expand Dangerous Command Patterns (V-018)
-**Owner:** Security Engineer  
-**Estimated Effort:** 6 hours  
-**Priority:** P2
-
-#### Add Patterns:
-- More encoding variants (base64, hex, unicode)
-- Alternative shell syntaxes
-- Indirect command execution
-- Environment variable abuse
-
----
-
-### 3.2 Add AST-Based Skill Scanning (V-011)
-**Owner:** Security Engineer  
-**Estimated Effort:** 16 hours  
-**Priority:** P2
-
-#### Implementation:
-- Parse Python code to AST
-- Detect dangerous function calls
-- Analyze import statements
-- Check for obfuscation patterns
-
----
-
-### 3.3 Implement Subagent Isolation (V-024)
-**Owner:** Senior Developer  
-**Estimated Effort:** 20 hours  
-**Priority:** P2
-
-#### Tasks:
-- Create isolated filesystem per subagent
-- Implement network namespace isolation
-- Add resource limits
-- Implement subagent-to-subagent communication restrictions
-
----
-
-### 3.4 Add Comprehensive Audit Logging (V-013, V-020, V-027)
-**Owner:** DevOps Engineer  
-**Estimated Effort:** 12 hours  
-**Priority:** P2
-
-#### Requirements:
-- Log all tool invocations
-- Log all authentication events
-- Log configuration changes
-- Implement log integrity protection
-- Add SIEM integration hooks
-
----
-
-## PHASE 4: LONG-TERM IMPROVEMENTS (Month 3+)
-
-### 4.1 Security Headers Hardening (V-028)
-**Owner:** Backend Developer  
-**Estimated Effort:** 4 hours
-
-Add headers:
-- Content-Security-Policy
-- Strict-Transport-Security
-- X-Frame-Options
-- X-XSS-Protection
-
----
-
-### 4.2 Code Signing Verification (V-026)
-**Owner:** Security Engineer  
-**Estimated Effort:** 8 hours
-
-- Require GPG signatures for binaries
-- Implement signature verification
-- Pin trusted signing keys
-
----
-
-### 4.3 Supply Chain Security
-**Owner:** DevOps Engineer  
-**Estimated Effort:** 12 hours
-
-- Implement dependency scanning
-- Add SLSA compliance
-- Use private package registry
-- Implement SBOM generation
-
----
-
-### 4.4 Automated Security Testing
-**Owner:** QA Lead  
-**Estimated Effort:** 16 hours
-
-- Integrate SAST tools (Semgrep, Bandit)
-- Add DAST to CI/CD
-- Implement fuzzing
-- Add security regression tests
-
----
-
-## IMPLEMENTATION TRACKING
-
-| Week | Deliverables | Owner | Status |
-|------|-------------|-------|--------|
-| 1 | P0 Fixes: V-001, V-002 | Security Team | ⏳ Planned |
-| 1 | P0 Fixes: V-003, V-005 | Security Team | ⏳ Planned |
-| 2 | P0 Testing & Validation | QA Team | ⏳ Planned |
-| 3 | P1 Fixes: V-006 through V-010 | Dev Team | ⏳ Planned |
-| 3 | P1 Fixes: V-014, V-016 | Dev Team | ⏳ Planned |
-| 4 | P1 Testing & Documentation | QA/Doc Team | ⏳ Planned |
-| 5-8 | P2 Fixes Implementation | Dev Team | ⏳ Planned |
-| 9-12 | P3/P4 Long-term Improvements | All Teams | ⏳ Planned |
-
----
-
-## SUCCESS METRICS
-
-### Security Metrics
-- [ ] Zero CVSS 9.0+ vulnerabilities
-- [ ] < 5 CVSS 7.0-8.9 vulnerabilities
-- [ ] 100% of subprocess calls without shell=True
-- [ ] 100% path validation coverage
-- [ ] 100% input validation on tool entry points
-
-### Compliance Metrics
-- [ ] OWASP Top 10 compliance
-- [ ] CWE coverage > 90%
-- [ ] Security test coverage > 80%
-
----
-
-## RISK ACCEPTANCE
-
-| Vulnerability | Risk | Justification | Approver |
-|--------------|------|---------------|----------|
-| V-029 (Version Info) | Low | Required for debugging | TBD |
-| V-030 (Dead Code) | Low | Cleanup in next refactor | TBD |
-
----
-
-## APPENDIX: TOOLS AND RESOURCES
-
-### Recommended Security Tools
-1. **SAST:** Semgrep, Bandit, Pylint-security
-2. **DAST:** OWASP ZAP, Burp Suite
-3. **Dependency:** Safety, Snyk, Dependabot
-4. **Secrets:** GitLeaks, TruffleHog
-5. **Fuzzing:** Atheris, Hypothesis
-
-### Training Resources
-- OWASP Top 10 for Python
-- Secure Coding in Python (SANS)
-- AWS Security Best Practices
-
----
-
-**Document Owner:** Security Team  
-**Review Cycle:** Monthly during remediation, Quarterly post-completion

TEST_ANALYSIS_REPORT.md

@@ -1,509 +0,0 @@
-# Hermes Agent - Testing Infrastructure Deep Analysis
-
-## Executive Summary
-
-The hermes-agent project has a **comprehensive test suite** with **373 test files** containing approximately **4,300+ test functions**. The tests are organized into 10 subdirectories covering all major components.
-
----
-
-## 1. Test Suite Structure & Statistics
-
-### 1.1 Directory Breakdown
-
-| Directory | Test Files | Focus Area |
-|-----------|------------|------------|
-| `tests/tools/` | 86 | Tool implementations, file operations, environments |
-| `tests/gateway/` | 96 | Platform integrations (Discord, Telegram, Slack, etc.) |
-| `tests/hermes_cli/` | 48 | CLI commands, configuration, setup flows |
-| `tests/agent/` | 16 | Core agent logic, prompt building, model adapters |
-| `tests/integration/` | 8 | End-to-end integration tests |
-| `tests/acp/` | 8 | Agent Communication Protocol |
-| `tests/cron/` | 3 | Cron job scheduling |
-| `tests/skills/` | 5 | Skill management |
-| `tests/honcho_integration/` | 5 | Honcho memory integration |
-| `tests/fakes/` | 2 | Test fixtures and fake servers |
-| **Total** | **373** | **~4,311 test functions** |
-
-### 1.2 Test Classification
-
-**Unit Tests:** ~95% (3,600+)
-**Integration Tests:** ~5% (marked with `@pytest.mark.integration`)
-**Async Tests:** ~679 tests use `@pytest.mark.asyncio`
-
-### 1.3 Largest Test Files (by line count)
-
-1. `tests/test_run_agent.py` - 3,329 lines (212 tests) - Core agent logic
-2. `tests/tools/test_mcp_tool.py` - 2,902 lines (147 tests) - MCP protocol
-3. `tests/gateway/test_voice_command.py` - 2,632 lines - Voice features
-4. `tests/gateway/test_feishu.py` - 2,580 lines - Feishu platform
-5. `tests/gateway/test_api_server.py` - 1,503 lines - API server
-
----
-
-## 2. Coverage Heat Map - Critical Gaps Identified
-
-### 2.1 NO TEST COVERAGE (Red Zone)
-
-#### Agent Module Gaps:
-- `agent/copilot_acp_client.py` - Copilot integration (0 tests)
-- `agent/gemini_adapter.py` - Google Gemini model support (0 tests)
-- `agent/knowledge_ingester.py` - Knowledge ingestion (0 tests)
-- `agent/meta_reasoning.py` - Meta-reasoning capabilities (0 tests)
-- `agent/skill_utils.py` - Skill utilities (0 tests)
-- `agent/trajectory.py` - Trajectory management (0 tests)
-
-#### Tools Module Gaps:
-- `tools/browser_tool.py` - Browser automation (0 tests)
-- `tools/code_execution_tool.py` - Code execution (0 tests)
-- `tools/gitea_client.py` - Gitea integration (0 tests)
-- `tools/image_generation_tool.py` - Image generation (0 tests)
-- `tools/neutts_synth.py` - Neural TTS (0 tests)
-- `tools/openrouter_client.py` - OpenRouter API (0 tests)
-- `tools/session_search_tool.py` - Session search (0 tests)
-- `tools/terminal_tool.py` - Terminal operations (0 tests)
-- `tools/tts_tool.py` - Text-to-speech (0 tests)
-- `tools/web_tools.py` - Web tools core (0 tests)
-
-#### Gateway Module Gaps:
-- `gateway/run.py` - Gateway runner (0 tests)
-- `gateway/stream_consumer.py` - Stream consumption (0 tests)
-
-#### Root-Level Gaps:
-- `hermes_constants.py` - Constants (0 tests)
-- `hermes_time.py` - Time utilities (0 tests)
-- `mini_swe_runner.py` - SWE runner (0 tests)
-- `rl_cli.py` - RL CLI (0 tests)
-- `utils.py` - Utilities (0 tests)
-
-### 2.2 LIMITED COVERAGE (Yellow Zone)
-
-- `agent/models_dev.py` - Only 19 tests for complex model routing
-- `agent/smart_model_routing.py` - Only 6 tests
-- `tools/approval.py` - 2 test files but complex logic
-- `tools/skills_guard.py` - Security-critical, needs more coverage
-
-### 2.3 GOOD COVERAGE (Green Zone)
-
-- `agent/anthropic_adapter.py` - 97 tests (comprehensive)
-- `agent/prompt_builder.py` - 108 tests (excellent)
-- `tools/mcp_tool.py` - 147 tests (very comprehensive)
-- `tools/file_tools.py` - Multiple test files
-- `gateway/discord.py` - 11 test files covering various aspects
-- `gateway/telegram.py` - 10 test files
-- `gateway/session.py` - 15 test files
-
----
-
-## 3. Test Patterns Analysis
-
-### 3.1 Fixtures Architecture
-
-**Global Fixtures (`conftest.py`):**
-- `_isolate_hermes_home` - Isolates HERMES_HOME to temp directory (autouse)
-- `_ensure_current_event_loop` - Event loop management for sync tests (autouse)
-- `_enforce_test_timeout` - 30-second timeout per test (autouse)
-- `tmp_dir` - Temporary directory fixture
-- `mock_config` - Minimal hermes config for unit tests
-
-**Common Patterns:**
-```python
-# Isolation pattern
-@pytest.fixture(autouse=True)
-def isolate_env(tmp_path, monkeypatch):
-    monkeypatch.setenv("HERMES_HOME", str(tmp_path))
-
-# Mock client pattern
-@pytest.fixture
-def mock_agent():
-    with patch("run_agent.OpenAI") as mock:
-        yield mock
-```
-
-### 3.2 Mock Usage Statistics
-
-- **~12,468 mock/patch usages** across the test suite
-- Heavy use of `unittest.mock.patch` and `MagicMock`
-- `AsyncMock` used for async function mocking
-- `SimpleNamespace` for creating mock API response objects
-
-### 3.3 Test Organization Patterns
-
-**Class-Based Organization:**
-- 1,532 test classes identified
-- Grouped by functionality: `Test<Feature><Scenario>`
-- Example: `TestSanitizeApiMessages`, `TestContextPressureFlags`
-
-**Function-Based Organization:**
-- Used for simpler test files
-- Naming: `test_<feature>_<scenario>`
-
-### 3.4 Async Test Patterns
-
-```python
-@pytest.mark.asyncio
-async def test_async_function():
-    result = await async_function()
-    assert result == expected
-```
-
----
-
-## 4. 20 New Test Recommendations (Priority Order)
-
-### Critical Priority (Security/Risk)
-
-1. **Browser Tool Security Tests** (`tools/browser_tool.py`)
-   - Test sandbox escape prevention
-   - Test malicious script blocking
-   - Test content security policy enforcement
-
-2. **Code Execution Sandbox Tests** (`tools/code_execution_tool.py`)
-   - Test resource limits (CPU, memory)
-   - Test dangerous import blocking
-   - Test timeout enforcement
-   - Test filesystem access restrictions
-
-3. **Terminal Tool Safety Tests** (`tools/terminal_tool.py`)
-   - Test dangerous command blocking
-   - Test command injection prevention
-   - Test environment variable sanitization
-
-4. **OpenRouter Client Tests** (`tools/openrouter_client.py`)
-   - Test API key handling
-   - Test rate limit handling
-   - Test error response parsing
-
-### High Priority (Core Functionality)
-
-5. **Gemini Adapter Tests** (`agent/gemini_adapter.py`)
-   - Test message format conversion
-   - Test tool call normalization
-   - Test streaming response handling
-
-6. **Copilot ACP Client Tests** (`agent/copilot_acp_client.py`)
-   - Test authentication flow
-   - Test session management
-   - Test message passing
-
-7. **Knowledge Ingester Tests** (`agent/knowledge_ingester.py`)
-   - Test document parsing
-   - Test embedding generation
-   - Test knowledge retrieval
-
-8. **Stream Consumer Tests** (`gateway/stream_consumer.py`)
-   - Test backpressure handling
-   - Test reconnection logic
-   - Test message ordering guarantees
-
-### Medium Priority (Integration/Features)
-
-9. **Web Tools Core Tests** (`tools/web_tools.py`)
-   - Test search result parsing
-   - Test content extraction
-   - Test error handling for unavailable services
-
-10. **Image Generation Tool Tests** (`tools/image_generation_tool.py`)
-    - Test prompt filtering
-    - Test image format handling
-    - Test provider failover
-
-11. **Gitea Client Tests** (`tools/gitea_client.py`)
-    - Test repository operations
-    - Test webhook handling
-    - Test authentication
-
-12. **Session Search Tool Tests** (`tools/session_search_tool.py`)
-    - Test query parsing
-    - Test result ranking
-    - Test pagination
-
-13. **Meta Reasoning Tests** (`agent/meta_reasoning.py`)
-    - Test strategy selection
-    - Test reflection generation
-    - Test learning from failures
-
-14. **TTS Tool Tests** (`tools/tts_tool.py`)
-    - Test voice selection
-    - Test audio format conversion
-    - Test streaming playback
-
-15. **Neural TTS Tests** (`tools/neutts_synth.py`)
-    - Test voice cloning safety
-    - Test audio quality validation
-    - Test resource cleanup
-
-### Lower Priority (Utilities)
-
-16. **Hermes Constants Tests** (`hermes_constants.py`)
-    - Test constant values
-    - Test environment-specific overrides
-
-17. **Time Utilities Tests** (`hermes_time.py`)
-    - Test timezone handling
-    - Test formatting functions
-
-18. **Utils Module Tests** (`utils.py`)
-    - Test helper functions
-    - Test validation utilities
-
-19. **Mini SWE Runner Tests** (`mini_swe_runner.py`)
-    - Test repository setup
-    - Test test execution
-    - Test result parsing
-
-20. **RL CLI Tests** (`rl_cli.py`)
-    - Test training command parsing
-    - Test configuration validation
-    - Test checkpoint handling
-
----
-
-## 5. Test Optimization Opportunities
-
-### 5.1 Performance Issues Identified
-
-**Large Test Files (Split Recommended):**
-- `tests/test_run_agent.py` (3,329 lines) → Split into multiple files
-- `tests/tools/test_mcp_tool.py` (2,902 lines) → Split by MCP feature
-- `tests/test_anthropic_adapter.py` (1,219 lines) → Consider splitting
-
-**Potential Slow Tests:**
-- Integration tests with real API calls
-- Tests with file I/O operations
-- Tests with subprocess spawning
-
-### 5.2 Optimization Recommendations
-
-1. **Parallel Execution Already Configured**
-   - `pytest-xdist` with `-n auto` in CI
-   - Maintains isolation through fixtures
-
-2. **Fixture Scope Optimization**
-   - Review `autouse=True` fixtures for necessity
-   - Consider session-scoped fixtures for expensive setup
-
-3. **Mock External Services**
-   - Some integration tests still hit real APIs
-   - Create more fakes like `fake_ha_server.py`
-
-4. **Test Data Management**
-   - Use factory pattern for test data generation
-   - Share test fixtures across related tests
-
-### 5.3 CI/CD Optimizations
-
-Current CI (`.github/workflows/tests.yml`):
-- Uses `uv` for fast dependency installation
-- Runs with `-n auto` for parallelization
-- Ignores integration tests by default
-- 10-minute timeout
-
-**Recommended Improvements:**
-1. Add test duration reporting (`--durations=10`)
-2. Add coverage reporting
-3. Separate fast unit tests from slower integration tests
-4. Add flaky test retry mechanism
-
----
-
-## 6. Missing Integration Test Scenarios
-
-### 6.1 Cross-Component Integration
-
-1. **End-to-End Agent Flow**
-   - User message → Gateway → Agent → Tools → Response
-   - Test with real (mocked) LLM responses
-
-2. **Multi-Platform Gateway**
-   - Message routing between platforms
-   - Session persistence across platforms
-
-3. **Tool + Environment Integration**
-   - Terminal tool with different backends (local, docker, modal)
-   - File operations with permission checks
-
-4. **Skill Lifecycle Integration**
-   - Skill installation → Registration → Execution → Update → Removal
-
-5. **Memory + Honcho Integration**
-   - Memory storage → Retrieval → Context injection
-
-### 6.2 Failure Scenario Integration Tests
-
-1. **LLM Provider Failover**
-   - Primary provider down → Fallback provider
-   - Rate limiting handling
-
-2. **Gateway Reconnection**
-   - Platform disconnect → Reconnect → Resume session
-
-3. **Tool Execution Failures**
-   - Tool timeout → Retry → Fallback
-   - Tool error → Error handling → User notification
-
-4. **Checkpoint Recovery**
-   - Crash during batch → Resume from checkpoint
-   - Corrupted checkpoint handling
-
-### 6.3 Security Integration Tests
-
-1. **Prompt Injection Across Stack**
-   - Gateway input → Agent processing → Tool execution
-
-2. **Permission Escalation Prevention**
-   - User permissions → Tool allowlist → Execution
-
-3. **Data Leak Prevention**
-   - Memory storage → Context building → Response generation
-
----
-
-## 7. Performance Test Strategy
-
-### 7.1 Load Testing Requirements
-
-1. **Gateway Load Tests**
-   - Concurrent session handling
-   - Message throughput per platform
-   - Memory usage under load
-
-2. **Agent Response Time Tests**
-   - End-to-end latency benchmarks
-   - Tool execution time budgets
-   - Context building performance
-
-3. **Resource Utilization Tests**
-   - Memory leaks in long-running sessions
-   - File descriptor limits
-   - CPU usage patterns
-
-### 7.2 Benchmark Framework
-
-```python
-# Proposed performance test structure
-class TestGatewayPerformance:
-    @pytest.mark.benchmark
-    def test_message_throughput(self, benchmark):
-        # Measure messages processed per second
-        pass
-    
-    @pytest.mark.benchmark
-    def test_session_creation_latency(self, benchmark):
-        # Measure session setup time
-        pass
-```
-
-### 7.3 Performance Regression Detection
-
-1. **Baseline Establishment**
-   - Record baseline metrics for critical paths
-   - Store in version control
-
-2. **Automated Comparison**
-   - Compare PR performance against baseline
-   - Fail if degradation > 10%
-
-3. **Metrics to Track**
-   - Test suite execution time
-   - Memory peak usage
-   - Individual test durations
-
----
-
-## 8. Test Infrastructure Improvements
-
-### 8.1 Coverage Tooling
-
-**Missing:** Code coverage reporting
-**Recommendation:** Add `pytest-cov` to dev dependencies
-
-```toml
-[project.optional-dependencies]
-dev = [
-    "pytest>=9.0.2,<10",
-    "pytest-asyncio>=1.3.0,<2",
-    "pytest-xdist>=3.0,<4",
-    "pytest-cov>=5.0,<6",  # Add this
-    "mcp>=1.2.0,<2"
-]
-```
-
-### 8.2 Test Categories
-
-Add more pytest markers for selective test running:
-
-```python
-# In pytest.ini or pyproject.toml
-markers = [
-    "integration: marks tests requiring external services",
-    "slow: marks slow tests (>5s)",
-    "security: marks security-focused tests",
-    "benchmark: marks performance benchmark tests",
-    "flakey: marks tests that may be unstable",
-]
-```
-
-### 8.3 Test Data Factory
-
-Create centralized test data factories:
-
-```python
-# tests/factories.py
-class AgentFactory:
-    @staticmethod
-    def create_mock_agent(tools=None):
-        # Return configured mock agent
-        pass
-
-class MessageFactory:
-    @staticmethod
-    def create_user_message(content):
-        # Return formatted user message
-        pass
-```
-
----
-
-## 9. Summary & Action Items
-
-### Immediate Actions (High Impact)
-
-1. **Add coverage reporting** to CI pipeline
-2. **Create tests for uncovered security-critical modules:**
-   - `tools/code_execution_tool.py`
-   - `tools/browser_tool.py`
-   - `tools/terminal_tool.py`
-3. **Split oversized test files** for better maintainability
-4. **Add Gemini adapter tests** (increasingly important provider)
-
-### Short-term (1-2 Sprints)
-
-5. Create integration tests for cross-component flows
-6. Add performance benchmarks for critical paths
-7. Expand OpenRouter client test coverage
-8. Add knowledge ingester tests
-
-### Long-term (Quarter)
-
-9. Achieve 80% code coverage across all modules
-10. Implement performance regression testing
-11. Create comprehensive security test suite
-12. Document testing patterns and best practices
-
----
-
-## Appendix: Test File Size Distribution
-
-| Lines | Count | Category |
-|-------|-------|----------|
-| 0-100 | ~50 | Simple unit tests |
-| 100-500 | ~200 | Standard test files |
-| 500-1000 | ~80 | Complex feature tests |
-| 1000-2000 | ~30 | Large test suites |
-| 2000+ | ~13 | Monolithic test files (needs splitting) |
-
----
-
-*Analysis generated: March 30, 2026*
-*Total test files analyzed: 373*
-*Estimated test functions: ~4,311*

TEST_OPTIMIZATION_GUIDE.md

@@ -1,364 +0,0 @@
-# Test Optimization Guide for Hermes Agent
-
-## Current Test Execution Analysis
-
-### Test Suite Statistics
-- **Total Test Files:** 373
-- **Estimated Test Functions:** ~4,311
-- **Async Tests:** ~679 (15.8%)
-- **Integration Tests:** 7 files (excluded from CI)
-- **Average Tests per File:** ~11.6
-
-### Current CI Configuration
-```yaml
-# .github/workflows/tests.yml
-- name: Run tests
-  run: |
-    source .venv/bin/activate
-    python -m pytest tests/ -q --ignore=tests/integration --tb=short -n auto
-```
-
-**Current Flags:**
-- `-q`: Quiet mode
-- `--ignore=tests/integration`: Skip integration tests
-- `--tb=short`: Short traceback format
-- `-n auto`: Auto-detect parallel workers
-
----
-
-## Optimization Recommendations
-
-### 1. Add Test Duration Reporting
-
-**Current:** No duration tracking
-**Recommended:**
-```yaml
-run: |
-  python -m pytest tests/ \
-    --ignore=tests/integration \
-    -n auto \
-    --durations=20 \           # Show 20 slowest tests
-    --durations-min=1.0        # Only show tests >1s
-```
-
-This will help identify slow tests that need optimization.
-
-### 2. Implement Test Categories
-
-Add markers to `pyproject.toml`:
-```toml
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-markers = [
-    "integration: marks tests requiring external services",
-    "slow: marks tests that take >5 seconds",
-    "unit: marks fast unit tests",
-    "security: marks security-focused tests",
-    "flakey: marks tests that may be unstable",
-]
-addopts = "-m 'not integration and not slow' -n auto"
-```
-
-**Usage:**
-```bash
-# Run only fast unit tests
-pytest -m unit
-
-# Run all tests including slow ones
-pytest -m "not integration"
-
-# Run only security tests
-pytest -m security
-```
-
-### 3. Optimize Slow Test Candidates
-
-Based on file sizes, these tests likely need optimization:
-
-| File | Lines | Optimization Strategy |
-|------|-------|----------------------|
-| `test_run_agent.py` | 3,329 | Split into multiple files by feature |
-| `test_mcp_tool.py` | 2,902 | Split by MCP functionality |
-| `test_voice_command.py` | 2,632 | Review for redundant tests |
-| `test_feishu.py` | 2,580 | Mock external API calls |
-| `test_api_server.py` | 1,503 | Parallelize independent tests |
-
-### 4. Add Coverage Reporting to CI
-
-**Updated workflow:**
-```yaml
-- name: Run tests with coverage
-  run: |
-    source .venv/bin/activate
-    python -m pytest tests/ \
-      --ignore=tests/integration \
-      -n auto \
-      --cov=agent --cov=tools --cov=gateway --cov=hermes_cli \
-      --cov-report=xml \
-      --cov-report=html \
-      --cov-fail-under=70
-
-- name: Upload coverage to Codecov
-  uses: codecov/codecov-action@v3
-  with:
-    files: ./coverage.xml
-    fail_ci_if_error: true
-```
-
-### 5. Implement Flaky Test Handling
-
-Add `pytest-rerunfailures`:
-```toml
-dev = [
-    "pytest>=9.0.2,<10",
-    "pytest-asyncio>=1.3.0,<2",
-    "pytest-xdist>=3.0,<4",
-    "pytest-cov>=5.0,<6",
-    "pytest-rerunfailures>=14.0,<15",  # Add this
-]
-```
-
-**Usage:**
-```python
-# Mark known flaky tests
-@pytest.mark.flakey(reruns=3, reruns_delay=1)
-async def test_network_dependent_feature():
-    # Test that sometimes fails due to network
-    pass
-```
-
-### 6. Optimize Fixture Scopes
-
-Review `conftest.py` fixtures:
-
-```python
-# Current: Function scope (runs for every test)
-@pytest.fixture()
-def mock_config():
-    return {...}
-
-# Optimized: Session scope (runs once per session)
-@pytest.fixture(scope="session")
-def mock_config():
-    return {...}
-
-# Optimized: Module scope (runs once per module)
-@pytest.fixture(scope="module")
-def expensive_setup():
-    # Setup that can be reused across module
-    pass
-```
-
-### 7. Parallel Execution Tuning
-
-**Current:** `-n auto` (uses all CPUs)
-**Issues:**
-- May cause resource contention
-- Some tests may not be thread-safe
-
-**Recommendations:**
-```bash
-# Limit workers to prevent resource exhaustion
-pytest -n 4  # Use 4 workers regardless of CPU count
-
-# Use load-based scheduling for uneven test durations
-pytest -n auto --dist=load
-
-# Group tests by module to reduce setup overhead
-pytest -n auto --dist=loadscope
-```
-
-### 8. Test Data Management
-
-**Current Issue:** Tests may create files in `/tmp` without cleanup
-
-**Solution - Factory Pattern:**
-```python
-# tests/factories.py
-import tempfile
-import shutil
-from contextlib import contextmanager
-
-@contextmanager
-def temp_workspace():
-    """Create isolated temp directory for tests."""
-    path = tempfile.mkdtemp(prefix="hermes_test_")
-    try:
-        yield Path(path)
-    finally:
-        shutil.rmtree(path, ignore_errors=True)
-
-# Usage in tests
-def test_file_operations():
-    with temp_workspace() as tmp:
-        # All file operations in isolated directory
-        file_path = tmp / "test.txt"
-        file_path.write_text("content")
-        assert file_path.exists()
-    # Automatically cleaned up
-```
-
-### 9. Database/State Isolation
-
-**Current:** Uses `monkeypatch` for env vars
-**Enhancement:** Database mocking
-
-```python
-@pytest.fixture
-def mock_honcho():
-    """Mock Honcho client for tests."""
-    with patch("honcho_integration.client.HonchoClient") as mock:
-        mock_instance = MagicMock()
-        mock_instance.get_session.return_value = {"id": "test-session"}
-        mock.return_value = mock_instance
-        yield mock
-
-# Usage
-async def test_memory_storage(mock_honcho):
-    # Fast, isolated test
-    pass
-```
-
-### 10. CI Pipeline Optimization
-
-**Current Pipeline:**
-1. Checkout
-2. Install uv
-3. Install Python
-4. Install deps
-5. Run tests
-
-**Optimized Pipeline (with caching):**
-```yaml
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    
-    steps:
-      - uses: actions/checkout@v4
-      
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-        with:
-          version: "0.5.x"
-      
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-          cache: 'pip'  # Cache pip dependencies
-      
-      - name: Cache uv packages
-        uses: actions/cache@v4
-        with:
-          path: ~/.cache/uv
-          key: ${{ runner.os }}-uv-${{ hashFiles('**/pyproject.toml') }}
-      
-      - name: Install dependencies
-        run: |
-          uv venv .venv
-          uv pip install -e ".[all,dev]"
-      
-      - name: Run fast tests
-        run: |
-          source .venv/bin/activate
-          pytest -m "not integration and not slow" -n auto --tb=short
-      
-      - name: Run slow tests
-        if: github.event_name == 'pull_request'
-        run: |
-          source .venv/bin/activate
-          pytest -m "slow" -n 2 --tb=short
-```
-
----
-
-## Quick Wins (Implement First)
-
-### 1. Add Duration Reporting (5 minutes)
-```yaml
---durations=10
-```
-
-### 2. Mark Slow Tests (30 minutes)
-Add `@pytest.mark.slow` to tests taking >5s.
-
-### 3. Split Largest Test File (2 hours)
-Split `test_run_agent.py` into:
-- `test_run_agent_core.py`
-- `test_run_agent_tools.py`
-- `test_run_agent_memory.py`
-- `test_run_agent_messaging.py`
-
-### 4. Add Coverage Baseline (1 hour)
-```bash
-pytest --cov=agent --cov=tools --cov=gateway tests/ --cov-report=html
-```
-
-### 5. Optimize Fixture Scopes (1 hour)
-Review and optimize 5 most-used fixtures.
-
----
-
-## Long-term Improvements
-
-### Test Data Generation
-```python
-# Implement hypothesis-based testing
-from hypothesis import given, strategies as st
-
-@given(st.lists(st.text(), min_size=1))
-def test_message_batching(messages):
-    # Property-based testing
-    pass
-```
-
-### Performance Regression Testing
-```python
-@pytest.mark.benchmark
-def test_message_processing_speed(benchmark):
-    result = benchmark(process_messages, sample_data)
-    assert result.throughput > 1000  # msgs/sec
-```
-
-### Contract Testing
-```python
-# Verify API contracts between components
-@pytest.mark.contract
-def test_agent_tool_contract():
-    """Verify agent sends correct format to tools."""
-    pass
-```
-
----
-
-## Measurement Checklist
-
-After implementing optimizations, verify:
-
-- [ ] Test suite execution time < 5 minutes
-- [ ] No individual test > 10 seconds (except integration)
-- [ ] Code coverage > 70%
-- [ ] All flaky tests marked and retried
-- [ ] CI passes consistently (>95% success rate)
-- [ ] Memory usage stable (no leaks in test suite)
-
----
-
-## Tools to Add
-
-```toml
-[project.optional-dependencies]
-dev = [
-    "pytest>=9.0.2,<10",
-    "pytest-asyncio>=1.3.0,<2",
-    "pytest-xdist>=3.0,<4",
-    "pytest-cov>=5.0,<6",
-    "pytest-rerunfailures>=14.0,<15",
-    "pytest-benchmark>=4.0,<5",       # Performance testing
-    "pytest-mock>=3.12,<4",            # Enhanced mocking
-    "hypothesis>=6.100,<7",            # Property-based testing
-    "factory-boy>=3.3,<4",             # Test data factories
-]
-```

V-006_FIX_SUMMARY.md

@@ -1,73 +0,0 @@
-# V-006 MCP OAuth Deserialization Vulnerability Fix
-
-## Summary
-Fixed the critical V-006 vulnerability (CVSS 8.8) in MCP OAuth handling that used insecure deserialization, potentially enabling remote code execution.
-
-## Changes Made
-
-### 1. Secure OAuth State Serialization (`tools/mcp_oauth.py`)
-- **Replaced pickle with JSON**: OAuth state is now serialized using JSON instead of `pickle.loads()`, eliminating the RCE vector
-- **Added HMAC-SHA256 signatures**: All state data is cryptographically signed to prevent tampering
-- **Implemented secure deserialization**: `SecureOAuthState.deserialize()` validates structure, signature, and expiration
-- **Added constant-time comparison**: Token validation uses `secrets.compare_digest()` to prevent timing attacks
-
-### 2. Token Storage Security Enhancements
-- **JSON Schema Validation**: Token data is validated against strict schemas before use
-- **HMAC Signing**: Stored tokens are signed with HMAC-SHA256 to detect file tampering
-- **Strict Type Checking**: All token fields are type-validated
-- **File Permissions**: Token directory created with 0o700, files with 0o600
-
-### 3. Security Features
-- **Nonce-based replay protection**: Each state has a unique nonce tracked by the state manager
-- **10-minute expiration**: States automatically expire after 600 seconds
-- **CSRF protection**: State validation prevents cross-site request forgery
-- **Environment-based keys**: Supports `HERMES_OAUTH_SECRET` and `HERMES_TOKEN_STORAGE_SECRET` env vars
-
-### 4. Comprehensive Security Tests (`tests/test_oauth_state_security.py`)
-54 security tests covering:
-- Serialization/deserialization roundtrips
-- Tampering detection (data and signature)
-- Schema validation for tokens and client info
-- Replay attack prevention
-- CSRF attack prevention
-- MITM attack detection
-- Pickle payload rejection
-- Performance tests
-
-## Files Modified
-- `tools/mcp_oauth.py` - Complete rewrite with secure state handling
-- `tests/test_oauth_state_security.py` - New comprehensive security test suite
-
-## Security Verification
-```bash
-# Run security tests
-python tests/test_oauth_state_security.py
-
-# All 54 tests pass:
-# - TestSecureOAuthState: 20 tests
-# - TestOAuthStateManager: 10 tests  
-# - TestSchemaValidation: 8 tests
-# - TestTokenStorageSecurity: 6 tests
-# - TestNoPickleUsage: 2 tests
-# - TestSecretKeyManagement: 3 tests
-# - TestOAuthFlowIntegration: 3 tests
-# - TestPerformance: 2 tests
-```
-
-## API Changes (Backwards Compatible)
-- `SecureOAuthState` - New class for secure state handling
-- `OAuthStateManager` - New class for state lifecycle management
-- `HermesTokenStorage` - Enhanced with schema validation and signing
-- `OAuthStateError` - New exception for security violations
-
-## Deployment Notes
-1. Existing token files will be invalidated (no signature) - users will need to re-authenticate
-2. New secret key will be auto-generated in `~/.hermes/.secrets/`
-3. Environment variables can override key locations:
-   - `HERMES_OAUTH_SECRET` - For state signing
-   - `HERMES_TOKEN_STORAGE_SECRET` - For token storage signing
-
-## References
-- Security Audit: V-006 Insecure Deserialization in MCP OAuth
-- CWE-502: Deserialization of Untrusted Data
-- CWE-20: Improper Input Validation

VECTOR_DB_RESEARCH_REPORT.md

@@ -0,0 +1,172 @@
+# Vector Database SOTA Research Report
+## For AI Agent Semantic Retrieval — April 2026
+
+---
+
+## Executive Summary
+
+Analysis of current vector database benchmarks, documentation, and production deployments for semantic retrieval in AI agents. Compared against existing Hermes session_search (SQLite FTS5) and holographic memory systems.
+
+---
+
+## 1. Retrieval Accuracy (Recall@10)
+
+| Database | HNSW Recall | IVF Recall | Notes |
+|----------|-------------|------------|-------|
+| **Qdrant** | 0.95-0.99 | N/A | Tunable via ef parameter |
+| **Milvus** | 0.95-0.99 | 0.85-0.95 | Multiple index support |
+| **Weaviate** | 0.95-0.98 | N/A | HNSW primary |
+| **Pinecone** | 0.95-0.99 | N/A | Managed, opaque tuning |
+| **ChromaDB** | 0.90-0.95 | N/A | Simpler, uses HNSW via hnswlib |
+| **pgvector** | 0.85-0.95 | 0.80-0.90 | Depends on tuning |
+| **SQLite-vss** | 0.80-0.90 | N/A | HNSW via sqlite-vss |
+| **Current FTS5** | ~0.60-0.75* | N/A | Keyword matching only |
+
+*FTS5 "recall" estimated: good for exact keywords, poor for semantic/paraphrased queries.
+
+---
+
+## 2. Latency Benchmarks (1M vectors, 768-dim, 10 neighbors)
+
+| Database | p50 (ms) | p99 (ms) | QPS | Notes |
+|----------|----------|----------|-----|-------|
+| **Qdrant** | 1-3 | 5-10 | 5,000-15,000 | Best self-hosted |
+| **Milvus** | 2-5 | 8-15 | 3,000-12,000 | Good distributed |
+| **Weaviate** | 3-8 | 10-25 | 2,000-8,000 | |
+| **Pinecone** | 5-15 | 20-50 | 1,000-5,000 | Managed overhead |
+| **ChromaDB** | 5-15 | 20-50 | 500-2,000 | Embedded mode |
+| **pgvector** | 10-50 | 50-200 | 200-1,000 | SQL overhead |
+| **SQLite-vss** | 10-30 | 50-150 | 300-800 | Limited scalability |
+| **Current FTS5** | 2-10 | 15-50 | 1,000-5,000 | No embedding cost |
+
+---
+
+## 3. Index Types Comparison
+
+### HNSW (Hierarchical Navigable Small World)
+- Best for: High recall, moderate memory, fast queries
+- Used by: Qdrant, Weaviate, ChromaDB, Milvus, pgvector, SQLite-vss
+- Memory: High (~1.5GB per 1M 768-dim vectors)
+- Key parameters: ef_construction (100-500), M (16-64), ef (64-256)
+
+### IVF (Inverted File Index)
+- Best for: Large datasets, memory-constrained
+- Used by: Milvus, pgvector
+- Memory: Lower (~0.5GB per 1M vectors)
+- Key parameters: nlist (100-10000), nprobe (10-100)
+
+### DiskANN / SPANN
+- Best for: 100M+ vectors on disk
+- Memory: Very low (~100MB index)
+
+### Quantization (SQ/PQ)
+- Memory reduction: 4-8x
+- Recall impact: -5-15%
+
+---
+
+## 4. Multi-Modal Support
+
+| Database | Text | Image | Audio | Video | Mixed Queries |
+|----------|------|-------|-------|-------|---------------|
+| Qdrant | ✅ | ✅ | ✅ | ✅ | ✅ (multi-vector) |
+| Milvus | ✅ | ✅ | ✅ | ✅ | ✅ (hybrid) |
+| Weaviate | ✅ | ✅ | ✅ | ✅ | ✅ (named vectors) |
+| Pinecone | ✅ | ✅ | ✅ | ✅ | Limited |
+| ChromaDB | ✅ | Via emb | Via emb | Via emb | Limited |
+| pgvector | ✅ | Via emb | Via emb | Via emb | Limited |
+| SQLite-vss | ✅ | Via emb | Via emb | Via emb | Limited |
+
+---
+
+## 5. Integration Patterns for AI Agents
+
+### Pattern A: Direct Search
+Query → Embedding → Vector DB → Top-K → LLM
+
+### Pattern B: Hybrid Search  
+Query → BM25 + Vector → Merge/Rerank → LLM
+
+### Pattern C: Multi-Stage
+Query → Vector DB (top-100) → Reranker (top-10) → LLM
+
+### Pattern D: Agent Memory with Trust + Decay
+Query → Vector → Score × Trust × Decay → Top-K → Summarize
+
+---
+
+## 6. Comparison with Current Systems
+
+### session_search (FTS5)
+Strengths: Zero deps, no embedding needed, fast for exact keywords
+Limitations: No semantic understanding, no cross-lingual, limited ranking
+
+### holographic/retrieval.py (HRR)
+Strengths: Compositional queries, contradiction detection, trust + decay
+Limitations: Requires numpy, O(n) scan, non-standard embedding space
+
+### Expected Gains from Vector DB:
+- Semantic recall: +30-50% for paraphrased queries
+- Cross-lingual: +60-80%
+- Fuzzy matching: +40-60%
+- Conceptual: +50-70%
+
+---
+
+## 7. Recommendations
+
+### Option 1: Qdrant (RECOMMENDED)
+- Best self-hosted performance
+- Rust implementation, native multi-vector
+- Tradeoff: Separate service deployment
+
+### Option 2: pgvector (CONSERVATIVE)
+- Zero new infrastructure if using PostgreSQL
+- Tradeoff: 5-10x slower than Qdrant
+
+### Option 3: SQLite-vss (LIGHTWEIGHT)
+- Minimal changes, embedded deployment
+- Tradeoff: Limited scalability (<100K vectors)
+
+### Option 4: Hybrid (BEST OF BOTH)
+Keep FTS5 + HRR and add Qdrant:
+- Vector (semantic) + FTS5 (keyword) + HRR (compositional)
+- Apply trust scoring + temporal decay
+
+---
+
+## 8. Embedding Models (2025-2026)
+
+| Model | Dimensions | Quality | Cost |
+|-------|-----------|---------|------|
+| OpenAI text-embedding-3-large | 3072 | Best | $$$ |
+| OpenAI text-embedding-3-small | 1536 | Good | $ |
+| BGE-M3 | 1024 | Best self-hosted | Free |
+| GTE-Qwen2 | 768-1024 | Good | Free |
+
+---
+
+## 9. Hardware Requirements (1M vectors, 768-dim)
+
+| Database | RAM (HNSW) | RAM (Quantized) |
+|----------|-----------|-----------------|
+| Qdrant | 8-16GB | 2-4GB |
+| Milvus | 16-32GB | 4-8GB |
+| pgvector | 4-8GB | N/A |
+| SQLite-vss | 2-4GB | N/A |
+
+---
+
+## 10. Conclusion
+
+Primary: Qdrant with hybrid search (vector + FTS5 + HRR)
+Key insight: Augment existing HRR system, don't replace it.
+
+Next steps:
+1. Deploy Qdrant in Docker for testing
+2. Benchmark embedding models
+3. Implement hybrid search prototype
+4. Measure recall improvement
+5. Evaluate operational complexity
+
+Report: April 2026 | Sources: ANN-Benchmarks, VectorDBBench, official docs

acp_adapter/entry.py

@@ -15,7 +15,6 @@ Usage::
 
 import asyncio
 import logging
-import os
 import sys
 from pathlib import Path
 from hermes_constants import get_hermes_home

acp_adapter/events.py

@@ -54,14 +54,18 @@ def make_tool_progress_cb(
 
     Signature expected by AIAgent::
 
-        tool_progress_callback(name: str, preview: str, args: dict)
+        tool_progress_callback(event_type: str, name: str, preview: str, args: dict, **kwargs)
 
-    Emits ``ToolCallStart`` for each tool invocation and tracks IDs in a FIFO
+    Emits ``ToolCallStart`` for ``tool.started`` events and tracks IDs in a FIFO
     queue per tool name so duplicate/parallel same-name calls still complete
-    against the correct ACP tool call.
+    against the correct ACP tool call.  Other event types (``tool.completed``,
+    ``reasoning.available``) are silently ignored.
     """
 
-    def _tool_progress(name: str, preview: str, args: Any = None) -> None:
+    def _tool_progress(event_type: str, name: str = None, preview: str = None, args: Any = None, **kwargs) -> None:
+        # Only emit ACP ToolCallStart for tool.started; ignore other event types
+        if event_type != "tool.started":
+            return
         if isinstance(args, str):
             try:
                 args = json.loads(args)

acp_adapter/server.py

@@ -12,7 +12,8 @@ import acp
 from acp.schema import (
     AgentCapabilities,
     AuthenticateResponse,
-    AuthMethod,
+    AvailableCommand,
+    AvailableCommandsUpdate,
     ClientCapabilities,
     EmbeddedResourceContentBlock,
     ForkSessionResponse,
@@ -22,6 +23,9 @@ from acp.schema import (
     InitializeResponse,
     ListSessionsResponse,
     LoadSessionResponse,
+    McpServerHttp,
+    McpServerSse,
+    McpServerStdio,
     NewSessionResponse,
     PromptResponse,
     ResumeSessionResponse,
@@ -32,11 +36,19 @@ from acp.schema import (
     SessionCapabilities,
     SessionForkCapabilities,
     SessionListCapabilities,
+    SessionResumeCapabilities,
     SessionInfo,
     TextContentBlock,
+    UnstructuredCommandInput,
     Usage,
 )
 
+# AuthMethodAgent was renamed from AuthMethod in agent-client-protocol 0.9.0
+try:
+    from acp.schema import AuthMethodAgent
+except ImportError:
+    from acp.schema import AuthMethod as AuthMethodAgent  # type: ignore[attr-defined]
+
 from acp_adapter.auth import detect_provider, has_provider
 from acp_adapter.events import (
     make_message_cb,
@@ -81,6 +93,48 @@ def _extract_text(
 class HermesACPAgent(acp.Agent):
     """ACP Agent implementation wrapping Hermes AIAgent."""
 
+    _SLASH_COMMANDS = {
+        "help": "Show available commands",
+        "model": "Show or change current model",
+        "tools": "List available tools",
+        "context": "Show conversation context info",
+        "reset": "Clear conversation history",
+        "compact": "Compress conversation context",
+        "version": "Show Hermes version",
+    }
+
+    _ADVERTISED_COMMANDS = (
+        {
+            "name": "help",
+            "description": "List available commands",
+        },
+        {
+            "name": "model",
+            "description": "Show current model and provider, or switch models",
+            "input_hint": "model name to switch to",
+        },
+        {
+            "name": "tools",
+            "description": "List available tools with descriptions",
+        },
+        {
+            "name": "context",
+            "description": "Show conversation message counts by role",
+        },
+        {
+            "name": "reset",
+            "description": "Clear conversation history",
+        },
+        {
+            "name": "compact",
+            "description": "Compress conversation context",
+        },
+        {
+            "name": "version",
+            "description": "Show Hermes version",
+        },
+    )
+
     def __init__(self, session_manager: SessionManager | None = None):
         super().__init__()
         self.session_manager = session_manager or SessionManager()
@@ -93,6 +147,71 @@ class HermesACPAgent(acp.Agent):
         self._conn = conn
         logger.info("ACP client connected")
 
+    async def _register_session_mcp_servers(
+        self,
+        state: SessionState,
+        mcp_servers: list[McpServerStdio | McpServerHttp | McpServerSse] | None,
+    ) -> None:
+        """Register ACP-provided MCP servers and refresh the agent tool surface."""
+        if not mcp_servers:
+            return
+
+        try:
+            from tools.mcp_tool import register_mcp_servers
+
+            config_map: dict[str, dict] = {}
+            for server in mcp_servers:
+                name = server.name
+                if isinstance(server, McpServerStdio):
+                    config = {
+                        "command": server.command,
+                        "args": list(server.args),
+                        "env": {item.name: item.value for item in server.env},
+                    }
+                else:
+                    config = {
+                        "url": server.url,
+                        "headers": {item.name: item.value for item in server.headers},
+                    }
+                config_map[name] = config
+
+            await asyncio.to_thread(register_mcp_servers, config_map)
+        except Exception:
+            logger.warning(
+                "Session %s: failed to register ACP MCP servers",
+                state.session_id,
+                exc_info=True,
+            )
+            return
+
+        try:
+            from model_tools import get_tool_definitions
+
+            enabled_toolsets = getattr(state.agent, "enabled_toolsets", None) or ["hermes-acp"]
+            disabled_toolsets = getattr(state.agent, "disabled_toolsets", None)
+            state.agent.tools = get_tool_definitions(
+                enabled_toolsets=enabled_toolsets,
+                disabled_toolsets=disabled_toolsets,
+                quiet_mode=True,
+            )
+            state.agent.valid_tool_names = {
+                tool["function"]["name"] for tool in state.agent.tools or []
+            }
+            invalidate = getattr(state.agent, "_invalidate_system_prompt", None)
+            if callable(invalidate):
+                invalidate()
+            logger.info(
+                "Session %s: refreshed tool surface after ACP MCP registration (%d tools)",
+                state.session_id,
+                len(state.agent.tools or []),
+            )
+        except Exception:
+            logger.warning(
+                "Session %s: failed to refresh tool surface after ACP MCP registration",
+                state.session_id,
+                exc_info=True,
+            )
+
     # ---- ACP lifecycle ------------------------------------------------------
 
     async def initialize(
@@ -109,7 +228,7 @@ class HermesACPAgent(acp.Agent):
         auth_methods = None
         if provider:
             auth_methods = [
-                AuthMethod(
+                AuthMethodAgent(
                     id=provider,
                     name=f"{provider} runtime credentials",
                     description=f"Authenticate Hermes using the currently configured {provider} runtime credentials.",
@@ -127,9 +246,11 @@ class HermesACPAgent(acp.Agent):
             protocol_version=acp.PROTOCOL_VERSION,
             agent_info=Implementation(name="hermes-agent", version=HERMES_VERSION),
             agent_capabilities=AgentCapabilities(
+                load_session=True,
                 session_capabilities=SessionCapabilities(
                     fork=SessionForkCapabilities(),
                     list=SessionListCapabilities(),
+                    resume=SessionResumeCapabilities(),
                 ),
             ),
             auth_methods=auth_methods,
@@ -149,7 +270,9 @@ class HermesACPAgent(acp.Agent):
         **kwargs: Any,
     ) -> NewSessionResponse:
         state = self.session_manager.create_session(cwd=cwd)
+        await self._register_session_mcp_servers(state, mcp_servers)
         logger.info("New session %s (cwd=%s)", state.session_id, cwd)
+        self._schedule_available_commands_update(state.session_id)
         return NewSessionResponse(session_id=state.session_id)
 
     async def load_session(
@@ -163,7 +286,9 @@ class HermesACPAgent(acp.Agent):
         if state is None:
             logger.warning("load_session: session %s not found", session_id)
             return None
+        await self._register_session_mcp_servers(state, mcp_servers)
         logger.info("Loaded session %s", session_id)
+        self._schedule_available_commands_update(session_id)
         return LoadSessionResponse()
 
     async def resume_session(
@@ -177,7 +302,9 @@ class HermesACPAgent(acp.Agent):
         if state is None:
             logger.warning("resume_session: session %s not found, creating new", session_id)
             state = self.session_manager.create_session(cwd=cwd)
+        await self._register_session_mcp_servers(state, mcp_servers)
         logger.info("Resumed session %s", state.session_id)
+        self._schedule_available_commands_update(state.session_id)
         return ResumeSessionResponse()
 
     async def cancel(self, session_id: str, **kwargs: Any) -> None:
@@ -200,7 +327,11 @@ class HermesACPAgent(acp.Agent):
     ) -> ForkSessionResponse:
         state = self.session_manager.fork_session(session_id, cwd=cwd)
         new_id = state.session_id if state else ""
+        if state is not None:
+            await self._register_session_mcp_servers(state, mcp_servers)
         logger.info("Forked session %s -> %s", session_id, new_id)
+        if new_id:
+            self._schedule_available_commands_update(new_id)
         return ForkSessionResponse(session_id=new_id)
 
     async def list_sessions(
@@ -323,14 +454,13 @@ class HermesACPAgent(acp.Agent):
             await conn.session_update(session_id, update)
 
         usage = None
-        usage_data = result.get("usage")
-        if usage_data and isinstance(usage_data, dict):
+        if any(result.get(key) is not None for key in ("prompt_tokens", "completion_tokens", "total_tokens")):
             usage = Usage(
-                input_tokens=usage_data.get("prompt_tokens", 0),
-                output_tokens=usage_data.get("completion_tokens", 0),
-                total_tokens=usage_data.get("total_tokens", 0),
-                thought_tokens=usage_data.get("reasoning_tokens"),
-                cached_read_tokens=usage_data.get("cached_tokens"),
+                input_tokens=result.get("prompt_tokens", 0),
+                output_tokens=result.get("completion_tokens", 0),
+                total_tokens=result.get("total_tokens", 0),
+                thought_tokens=result.get("reasoning_tokens"),
+                cached_read_tokens=result.get("cache_read_tokens"),
             )
 
         stop_reason = "cancelled" if state.cancel_event and state.cancel_event.is_set() else "end_turn"
@@ -338,15 +468,50 @@ class HermesACPAgent(acp.Agent):
 
     # ---- Slash commands (headless) -------------------------------------------
 
-    _SLASH_COMMANDS = {
-        "help": "Show available commands",
-        "model": "Show or change current model",
-        "tools": "List available tools",
-        "context": "Show conversation context info",
-        "reset": "Clear conversation history",
-        "compact": "Compress conversation context",
-        "version": "Show Hermes version",
-    }
+    @classmethod
+    def _available_commands(cls) -> list[AvailableCommand]:
+        commands: list[AvailableCommand] = []
+        for spec in cls._ADVERTISED_COMMANDS:
+            input_hint = spec.get("input_hint")
+            commands.append(
+                AvailableCommand(
+                    name=spec["name"],
+                    description=spec["description"],
+                    input=UnstructuredCommandInput(hint=input_hint)
+                    if input_hint
+                    else None,
+                )
+            )
+        return commands
+
+    async def _send_available_commands_update(self, session_id: str) -> None:
+        """Advertise supported slash commands to the connected ACP client."""
+        if not self._conn:
+            return
+
+        try:
+            await self._conn.session_update(
+                session_id=session_id,
+                update=AvailableCommandsUpdate(
+                    sessionUpdate="available_commands_update",
+                    availableCommands=self._available_commands(),
+                ),
+            )
+        except Exception:
+            logger.warning(
+                "Failed to advertise ACP slash commands for session %s",
+                session_id,
+                exc_info=True,
+            )
+
+    def _schedule_available_commands_update(self, session_id: str) -> None:
+        """Send the command advertisement after the session response is queued."""
+        if not self._conn:
+            return
+        loop = asyncio.get_running_loop()
+        loop.call_soon(
+            asyncio.create_task, self._send_available_commands_update(session_id)
+        )
 
     def _handle_slash_command(self, text: str, state: SessionState) -> str | None:
         """Dispatch a slash command and return the response text.
@@ -466,11 +631,39 @@ class HermesACPAgent(acp.Agent):
             return "Nothing to compress — conversation is empty."
         try:
             agent = state.agent
-            if hasattr(agent, "compress_context"):
-                agent.compress_context(state.history)
-                self.session_manager.save_session(state.session_id)
-                return f"Context compressed. Messages: {len(state.history)}"
-            return "Context compression not available for this agent."
+            if not getattr(agent, "compression_enabled", True):
+                return "Context compression is disabled for this agent."
+            if not hasattr(agent, "_compress_context"):
+                return "Context compression not available for this agent."
+
+            from agent.model_metadata import estimate_messages_tokens_rough
+
+            original_count = len(state.history)
+            approx_tokens = estimate_messages_tokens_rough(state.history)
+            original_session_db = getattr(agent, "_session_db", None)
+
+            try:
+                # ACP sessions must keep a stable session id, so avoid the
+                # SQLite session-splitting side effect inside _compress_context.
+                agent._session_db = None
+                compressed, _ = agent._compress_context(
+                    state.history,
+                    getattr(agent, "_cached_system_prompt", "") or "",
+                    approx_tokens=approx_tokens,
+                    task_id=state.session_id,
+                )
+            finally:
+                agent._session_db = original_session_db
+
+            state.history = compressed
+            self.session_manager.save_session(state.session_id)
+
+            new_count = len(state.history)
+            new_tokens = estimate_messages_tokens_rough(state.history)
+            return (
+                f"Context compressed: {original_count} -> {new_count} messages\n"
+                f"~{approx_tokens:,} -> ~{new_tokens:,} tokens"
+            )
         except Exception as e:
             return f"Compression failed: {e}"
 

acp_adapter/session.py

@@ -13,6 +13,7 @@ from hermes_constants import get_hermes_home
 import copy
 import json
 import logging
+import sys
 import uuid
 from dataclasses import dataclass, field
 from threading import Lock
@@ -21,6 +22,17 @@ from typing import Any, Dict, List, Optional
 logger = logging.getLogger(__name__)
 
 
+def _acp_stderr_print(*args, **kwargs) -> None:
+    """Best-effort human-readable output sink for ACP stdio sessions.
+
+    ACP reserves stdout for JSON-RPC frames, so any incidental CLI/status output
+    from AIAgent must be redirected away from stdout. Route it to stderr instead.
+    """
+    kwargs = dict(kwargs)
+    kwargs.setdefault("file", sys.stderr)
+    print(*args, **kwargs)
+
+
 def _register_task_cwd(task_id: str, cwd: str) -> None:
     """Bind a task/session id to the editor's working directory for tools."""
     if not task_id:
@@ -250,8 +262,6 @@ class SessionManager:
         if self._db_instance is not None:
             return self._db_instance
         try:
-            import os
-            from pathlib import Path
             from hermes_state import SessionDB
             hermes_home = get_hermes_home()
             self._db_instance = SessionDB(db_path=hermes_home / "state.db")
@@ -426,7 +436,7 @@ class SessionManager:
 
         config = load_config()
         model_cfg = config.get("model")
-        default_model = "anthropic/claude-opus-4.6"
+        default_model = ""
         config_provider = None
         if isinstance(model_cfg, dict):
             default_model = str(model_cfg.get("default") or default_model)
@@ -458,4 +468,8 @@ class SessionManager:
             logger.debug("ACP session falling back to default provider resolution", exc_info=True)
 
         _register_task_cwd(session_id, cwd)
-        return AIAgent(**kwargs)
+        agent = AIAgent(**kwargs)
+        # ACP stdio transport requires stdout to remain protocol-only JSON-RPC.
+        # Route any incidental human-readable agent output to stderr instead.
+        agent._print_fn = _acp_stderr_print
+        return agent

acp_adapter/tools.py

@@ -39,7 +39,6 @@ TOOL_KIND_MAP: Dict[str, ToolKind] = {
     "browser_scroll": "execute",
     "browser_press": "execute",
     "browser_back": "execute",
-    "browser_close": "execute",
     "browser_get_images": "read",
     # Agent internals
     "delegate_task": "execute",

agent/__init__.py

@@ -4,22 +4,3 @@ These modules contain pure utility functions and self-contained classes
 that were previously embedded in the 3,600-line run_agent.py. Extracting
 them makes run_agent.py focused on the AIAgent orchestrator class.
 """
-
-# Import input sanitizer for convenient access
-from agent.input_sanitizer import (
-    detect_jailbreak_patterns,
-    sanitize_input,
-    sanitize_input_full,
-    score_input_risk,
-    should_block_input,
-    RiskLevel,
-)
-
-__all__ = [
-    "detect_jailbreak_patterns",
-    "sanitize_input",
-    "sanitize_input_full",
-    "score_input_risk",
-    "should_block_input",
-    "RiskLevel",
-]

agent/a2a_mtls.py

@@ -0,0 +1,443 @@
+"""
+A2A mutual-TLS server — secure agent-to-agent communication.
+
+Each fleet agent runs an A2A server that:
+  - Presents its own TLS certificate (signed by the fleet CA).
+  - Requires the connecting peer to present a valid client certificate
+    also signed by the fleet CA.
+  - Rejects connections from unknown / self-signed peers.
+
+Usage (standalone):
+    python -m agent.a2a_mtls \\
+        --cert ~/.hermes/pki/agents/timmy/timmy.crt \\
+        --key  ~/.hermes/pki/agents/timmy/timmy.key \\
+        --ca   ~/.hermes/pki/ca/fleet-ca.crt \\
+        --host 0.0.0.0 --port 9443
+
+Environment variables (alternative to CLI flags):
+    HERMES_A2A_CERT   path to agent certificate
+    HERMES_A2A_KEY    path to agent private key
+    HERMES_A2A_CA     path to fleet CA certificate
+
+Refs #806
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import ssl
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# mTLS SSL context helpers
+# ---------------------------------------------------------------------------
+
+def build_server_ssl_context(
+    cert: str | Path,
+    key: str | Path,
+    ca: str | Path,
+) -> ssl.SSLContext:
+    """Return an SSLContext that presents *cert/key* and requires a valid
+    client certificate signed by *ca*.
+
+    Raises ``FileNotFoundError`` if any path is missing.
+    Raises ``ssl.SSLError`` if the files are malformed.
+    """
+    cert, key, ca = Path(cert), Path(key), Path(ca)
+    for p in (cert, key, ca):
+        if not p.exists():
+            raise FileNotFoundError(f"mTLS: file not found: {p}")
+
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+    ctx.load_cert_chain(certfile=str(cert), keyfile=str(key))
+    ctx.load_verify_locations(cafile=str(ca))
+    # CERT_REQUIRED — reject peers that don't present a cert signed by *ca*.
+    ctx.verify_mode = ssl.CERT_REQUIRED
+    return ctx
+
+
+def build_client_ssl_context(
+    cert: str | Path,
+    key: str | Path,
+    ca: str | Path,
+) -> ssl.SSLContext:
+    """Return an SSLContext for an outgoing mTLS connection.
+
+    Presents *cert/key* as the client identity and verifies the server
+    certificate against *ca*.
+    """
+    cert, key, ca = Path(cert), Path(key), Path(ca)
+    for p in (cert, key, ca):
+        if not p.exists():
+            raise FileNotFoundError(f"mTLS client: file not found: {p}")
+
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+    ctx.load_cert_chain(certfile=str(cert), keyfile=str(key))
+    ctx.load_verify_locations(cafile=str(ca))
+    ctx.verify_mode = ssl.CERT_REQUIRED
+    ctx.check_hostname = True
+    return ctx
+
+
+# ---------------------------------------------------------------------------
+# Minimal A2A HTTP request handler
+# ---------------------------------------------------------------------------
+
+class A2AHandler(BaseHTTPRequestHandler):
+    """Handles A2A requests over a mutually-authenticated TLS connection.
+
+    GET /.well-known/agent-card.json  — returns the local agent card.
+    POST /a2a/task                    — dispatches an A2A task (stub).
+    """
+
+    log_message = logger.debug  # route access log to Python logger
+
+    def do_GET(self) -> None:  # noqa: N802
+        if self.path in ("/.well-known/agent-card.json", "/agent-card.json"):
+            self._serve_agent_card()
+        else:
+            self._send_json(404, {"error": "not found"})
+
+    def do_POST(self) -> None:  # noqa: N802
+        if self.path == "/a2a/task":
+            self._handle_task()
+        else:
+            self._send_json(404, {"error": "not found"})
+
+    # ------------------------------------------------------------------
+    def _serve_agent_card(self) -> None:
+        try:
+            from agent.agent_card import get_agent_card_json
+            body = get_agent_card_json().encode()
+        except Exception as exc:
+            logger.warning("agent-card unavailable: %s", exc)
+            body = b'{"error": "agent card unavailable"}'
+        self._send_raw(200, "application/json", body)
+
+    def _handle_task(self) -> None:
+        length = int(self.headers.get("Content-Length", 0))
+        _body = self.rfile.read(length) if length else b""
+        # Stub: echo back a 202 Accepted with the peer CN so callers can
+        # confirm which agent processed the request.
+        peer_cn = _peer_cn(self.connection)
+        self._send_json(202, {"status": "accepted", "handled_by": peer_cn})
+
+    # ------------------------------------------------------------------
+    def _send_json(self, code: int, data: dict) -> None:
+        import json
+        body = json.dumps(data).encode()
+        self._send_raw(code, "application/json", body)
+
+    def _send_raw(self, code: int, content_type: str, body: bytes) -> None:
+        self.send_response(code)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, fmt: str, *args: object) -> None:  # type: ignore[override]
+        logger.debug("a2a: " + fmt, *args)
+
+
+def _peer_cn(conn: ssl.SSLSocket) -> Optional[str]:
+    """Extract the Common Name from the peer certificate, or None."""
+    try:
+        peer = conn.getpeercert()
+        if not peer:
+            return None
+        for rdn in peer.get("subject", ()):
+            for key, val in rdn:
+                if key == "commonName":
+                    return val
+    except Exception:
+        pass
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Server lifecycle
+# ---------------------------------------------------------------------------
+
+class A2AServer:
+    """Mutual-TLS A2A server.
+
+    Example::
+
+        server = A2AServer(
+            cert="~/.hermes/pki/agents/timmy/timmy.crt",
+            key="~/.hermes/pki/agents/timmy/timmy.key",
+            ca="~/.hermes/pki/ca/fleet-ca.crt",
+        )
+        server.start()   # non-blocking (daemon thread)
+        ...
+        server.stop()
+    """
+
+    def __init__(
+        self,
+        cert: str | Path,
+        key: str | Path,
+        ca: str | Path,
+        host: str = "0.0.0.0",
+        port: int = 9443,
+    ) -> None:
+        self.cert = Path(cert).expanduser()
+        self.key = Path(key).expanduser()
+        self.ca = Path(ca).expanduser()
+        self.host = host
+        self.port = port
+        self._httpd: Optional[HTTPServer] = None
+        self._thread: Optional[threading.Thread] = None
+
+    def start(self, daemon: bool = True) -> None:
+        """Start the server in a background thread (default: daemon)."""
+        ssl_ctx = build_server_ssl_context(self.cert, self.key, self.ca)
+        self._httpd = HTTPServer((self.host, self.port), A2AHandler)
+        self._httpd.socket = ssl_ctx.wrap_socket(
+            self._httpd.socket, server_side=True
+        )
+        self._thread = threading.Thread(
+            target=self._httpd.serve_forever, daemon=daemon
+        )
+        self._thread.start()
+        logger.info(
+            "A2A mTLS server listening on %s:%s (cert=%s)",
+            self.host, self.port, self.cert.name,
+        )
+
+    def stop(self) -> None:
+        if self._httpd:
+            self._httpd.shutdown()
+            self._httpd = None
+        if self._thread:
+            self._thread.join(timeout=5)
+            self._thread = None
+
+
+def server_from_env() -> A2AServer:
+    """Build an A2AServer from environment variables / defaults."""
+    hermes_home = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
+    agent_name = os.environ.get("HERMES_AGENT_NAME", "hermes").lower()
+
+    default_cert = hermes_home / "pki" / "agents" / agent_name / f"{agent_name}.crt"
+    default_key = hermes_home / "pki" / "agents" / agent_name / f"{agent_name}.key"
+    default_ca = hermes_home / "pki" / "ca" / "fleet-ca.crt"
+
+    cert = os.environ.get("HERMES_A2A_CERT", str(default_cert))
+    key = os.environ.get("HERMES_A2A_KEY", str(default_key))
+    ca = os.environ.get("HERMES_A2A_CA", str(default_ca))
+    host = os.environ.get("HERMES_A2A_HOST", "0.0.0.0")
+    port = int(os.environ.get("HERMES_A2A_PORT", "9443"))
+
+    return A2AServer(cert=cert, key=key, ca=ca, host=host, port=port)
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point
+# ---------------------------------------------------------------------------
+
+def _main() -> None:
+    import argparse
+
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
+
+    parser = argparse.ArgumentParser(
+        description="Hermes A2A mutual-TLS server"
+    )
+    parser.add_argument("--cert", required=True, help="Path to agent certificate")
+    parser.add_argument("--key", required=True, help="Path to agent private key")
+    parser.add_argument("--ca", required=True, help="Path to fleet CA certificate")
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--port", type=int, default=9443)
+    args = parser.parse_args()
+
+    server = A2AServer(
+        cert=args.cert, key=args.key, ca=args.ca,
+        host=args.host, port=args.port,
+    )
+    server.start(daemon=False)
+
+
+if __name__ == "__main__":
+    _main()
+
+
+# ---------------------------------------------------------------------------
+# A2AMTLSServer — routing-based server with context-manager support
+# ---------------------------------------------------------------------------
+
+class _RoutingHandler(BaseHTTPRequestHandler):
+    """HTTP request handler that dispatches to per-path callables."""
+
+    routes: Dict[str, Callable] = {}
+
+    def log_message(self, fmt: str, *args: Any) -> None:
+        logger.debug("A2AMTLSServer: " + fmt, *args)
+
+    def _peer_cn(self) -> Optional[str]:
+        cert = self.connection.getpeercert()  # type: ignore[attr-defined]
+        if not cert:
+            return None
+        for rdn in cert.get("subject", ()):
+            for attr, value in rdn:
+                if attr == "commonName":
+                    return value
+        return None
+
+    def do_POST(self) -> None:
+        handler = self.routes.get(self.path)
+        if handler is None:
+            self.send_response(404)
+            self.end_headers()
+            return
+        length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(length) if length else b""
+        try:
+            payload = json.loads(body) if body else {}
+        except json.JSONDecodeError:
+            self.send_response(400)
+            self.end_headers()
+            return
+        result = handler(payload, peer_cn=self._peer_cn())
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps(result).encode())
+
+    def do_GET(self) -> None:
+        handler = self.routes.get(self.path)
+        if handler is None:
+            self.send_response(404)
+            self.end_headers()
+            return
+        result = handler({}, peer_cn=self._peer_cn())
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps(result).encode())
+
+
+class A2AMTLSServer:
+    """Routing-based mTLS HTTPS server with context-manager support.
+
+    Unlike ``A2AServer`` (which serves fixed A2A paths), this server lets
+    callers register arbitrary path handlers — useful for tests and custom
+    A2A endpoint implementations.
+
+    handler signature: ``handler(payload: dict, *, peer_cn: str | None) -> dict``
+
+    Example::
+
+        server = A2AMTLSServer(cert="timmy.crt", key="timmy.key", ca="fleet-ca.crt")
+        server.add_route("/tasks/send", my_handler)
+        with server:
+            ...  # server runs for the duration of the block
+    """
+
+    def __init__(
+        self,
+        cert: str | Path,
+        key: str | Path,
+        ca: str | Path,
+        host: str = "127.0.0.1",
+        port: int = 9443,
+    ) -> None:
+        self.cert = Path(cert).expanduser()
+        self.key = Path(key).expanduser()
+        self.ca = Path(ca).expanduser()
+        self.host = host
+        self.port = port
+        self._routes: Dict[str, Callable] = {}
+        self._httpd: Optional[HTTPServer] = None
+        self._thread: Optional[threading.Thread] = None
+
+    def add_route(self, path: str, handler: Callable) -> None:
+        self._routes[path] = handler
+
+    def start(self) -> None:
+        ssl_ctx = build_server_ssl_context(self.cert, self.key, self.ca)
+
+        class _Handler(_RoutingHandler):
+            routes = self._routes
+
+        self._httpd = HTTPServer((self.host, self.port), _Handler)
+        self._httpd.socket = ssl_ctx.wrap_socket(self._httpd.socket, server_side=True)
+        self._thread = threading.Thread(
+            target=self._httpd.serve_forever,
+            daemon=True,
+            name=f"a2a-mtls-{self.port}",
+        )
+        self._thread.start()
+        logger.info("A2AMTLSServer on %s:%d (mTLS)", self.host, self.port)
+
+    def stop(self) -> None:
+        if self._httpd:
+            self._httpd.shutdown()
+            self._httpd = None
+        if self._thread:
+            self._thread.join(timeout=5)
+            self._thread = None
+
+    def __enter__(self) -> "A2AMTLSServer":
+        self.start()
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.stop()
+
+
+# ---------------------------------------------------------------------------
+# A2AMTLSClient — mTLS HTTP client
+# ---------------------------------------------------------------------------
+
+class A2AMTLSClient:
+    """HTTP client that presents a fleet cert on every outgoing connection.
+
+    Example::
+
+        client = A2AMTLSClient(cert="allegro.crt", key="allegro.key", ca="fleet-ca.crt")
+        result = client.post("https://timmy:9443/tasks/send", json={"task": "..."})
+    """
+
+    def __init__(
+        self,
+        cert: str | Path,
+        key: str | Path,
+        ca: str | Path,
+    ) -> None:
+        self._ssl_ctx = build_client_ssl_context(cert, key, ca)
+        self._ssl_ctx.check_hostname = False  # callers connecting by IP
+
+    def _request(
+        self,
+        method: str,
+        url: str,
+        data: Optional[bytes] = None,
+        timeout: float = 10.0,
+    ) -> Dict[str, Any]:
+        headers = {"Content-Type": "application/json"}
+        req = Request(url, data=data, headers=headers, method=method)
+        try:
+            with urlopen(req, context=self._ssl_ctx, timeout=timeout) as resp:
+                body = resp.read()
+                return json.loads(body) if body else {}
+        except URLError as exc:
+            raise ConnectionError(f"A2AMTLSClient {method} {url} failed: {exc.reason}") from exc
+
+    def get(self, url: str, **kwargs: Any) -> Dict[str, Any]:
+        return self._request("GET", url, **kwargs)
+
+    def post(self, url: str, json: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Dict[str, Any]:
+        data = (__import__("json").dumps(json).encode() if json is not None else None)
+        return self._request("POST", url, data=data, **kwargs)

agent/agent_card.py

@@ -0,0 +1,135 @@
+"""
+Agent Card — A2A-compliant agent discovery.
+Part of #843: fix: implement A2A agent card for fleet discovery (#819)
+
+Provides metadata about the agent's identity, capabilities, and installed skills
+for discovery by other agents in the fleet.
+"""
+
+import json
+import logging
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from hermes_cli import __version__
+from hermes_cli.config import load_config, get_hermes_home
+from agent.skill_utils import (
+    iter_skill_index_files,
+    parse_frontmatter,
+    get_all_skills_dirs,
+    get_disabled_skill_names,
+    skill_matches_platform
+)
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class AgentSkill:
+    id: str
+    name: str
+    description: str = ""
+    version: str = "1.0.0"
+
+@dataclass
+class AgentCapabilities:
+    streaming: bool = True
+    tools: bool = True
+    vision: bool = False
+    reasoning: bool = False
+
+@dataclass
+class AgentCard:
+    name: str
+    description: str
+    url: str
+    version: str = __version__
+    capabilities: AgentCapabilities = field(default_factory=AgentCapabilities)
+    skills: List[AgentSkill] = field(default_factory=list)
+    defaultInputModes: List[str] = field(default_factory=lambda: ["text/plain"])
+    defaultOutputModes: List[str] = field(default_factory=lambda: ["text/plain"])
+
+def _load_skills() -> List[AgentSkill]:
+    """Scan all enabled skills and return metadata."""
+    skills = []
+    disabled = get_disabled_skill_names()
+    
+    for skills_dir in get_all_skills_dirs():
+        if not skills_dir.is_dir():
+            continue
+        for skill_file in iter_skill_index_files(skills_dir, "SKILL.md"):
+            try:
+                raw = skill_file.read_text(encoding="utf-8")
+                frontmatter, _ = parse_frontmatter(raw)
+            except Exception:
+                continue
+
+            skill_name = frontmatter.get("name") or skill_file.parent.name
+            if str(skill_name) in disabled:
+                continue
+            if not skill_matches_platform(frontmatter):
+                continue
+
+            skills.append(AgentSkill(
+                id=str(skill_name),
+                name=str(frontmatter.get("name", skill_name)),
+                description=str(frontmatter.get("description", "")),
+                version=str(frontmatter.get("version", "1.0.0"))
+            ))
+    return skills
+
+def build_agent_card() -> AgentCard:
+    """Build the agent card from current configuration and environment."""
+    config = load_config()
+    
+    # Identity
+    name = os.environ.get("HERMES_AGENT_NAME") or config.get("agent", {}).get("name") or "hermes"
+    description = os.environ.get("HERMES_AGENT_DESCRIPTION") or config.get("agent", {}).get("description") or "Sovereign AI agent"
+    
+    # URL - try to determine from environment or config
+    port = os.environ.get("HERMES_WEB_PORT") or "9119"
+    host = os.environ.get("HERMES_WEB_HOST") or "localhost"
+    url = f"http://{host}:{port}"
+    
+    # Capabilities
+    # In a real scenario, we'd check model metadata for vision/reasoning
+    capabilities = AgentCapabilities(
+        streaming=True,
+        tools=True,
+        vision=False, # Default to false unless we can confirm
+        reasoning=False
+    )
+    
+    # Skills
+    skills = _load_skills()
+    
+    return AgentCard(
+        name=name,
+        description=description,
+        url=url,
+        version=__version__,
+        capabilities=capabilities,
+        skills=skills
+    )
+
+def get_agent_card_json() -> str:
+    """Return the agent card as a JSON string."""
+    try:
+        card = build_agent_card()
+        return json.dumps(asdict(card), indent=2)
+    except Exception as e:
+        logger.error(f"Failed to build agent card: {e}")
+        # Minimal fallback card
+        fallback = {
+            "name": "hermes",
+            "description": "Sovereign AI agent (fallback)",
+            "version": __version__,
+            "error": str(e)
+        }
+        return json.dumps(fallback, indent=2)
+
+def validate_agent_card(card_data: Dict[str, Any]) -> bool:
+    """Check if the card data complies with the A2A schema."""
+    required = ["name", "description", "url", "version"]
+    return all(k in card_data for k in required)

agent/anthropic_adapter.py

@@ -10,6 +10,7 @@ Auth supports:
   - Claude Code credentials (~/.claude.json or ~/.claude/.credentials.json) → Bearer auth
 """
 
+import copy
 import json
 import logging
 import os
@@ -59,6 +60,8 @@ _ANTHROPIC_OUTPUT_LIMITS = {
     "claude-3-opus":       4_096,
     "claude-3-sonnet":     4_096,
     "claude-3-haiku":      4_096,
+    # Third-party Anthropic-compatible providers
+    "minimax":            131_072,
 }
 
 # For any model not in the table, assume the highest current limit.
@@ -73,8 +76,11 @@ def _get_anthropic_max_output(model: str) -> int:
     model IDs (claude-sonnet-4-5-20250929) and variant suffixes (:1m, :fast)
     resolve correctly.  Longest-prefix match wins to avoid e.g. "claude-3-5"
     matching before "claude-3-5-sonnet".
+
+    Normalizes dots to hyphens so that model names like
+    ``anthropic/claude-opus-4.6`` match the ``claude-opus-4-6`` table key.
     """
-    m = model.lower()
+    m = model.lower().replace(".", "-")
     best_key = ""
     best_val = _ANTHROPIC_DEFAULT_OUTPUT_LIMIT
     for key, val in _ANTHROPIC_OUTPUT_LIMITS.items():
@@ -94,6 +100,15 @@ _COMMON_BETAS = [
     "interleaved-thinking-2025-05-14",
     "fine-grained-tool-streaming-2025-05-14",
 ]
+# MiniMax's Anthropic-compatible endpoints fail tool-use requests when
+# the fine-grained tool streaming beta is present.  Omit it so tool calls
+# fall back to the provider's default response path.
+_TOOL_STREAMING_BETA = "fine-grained-tool-streaming-2025-05-14"
+
+# Fast mode beta — enables the ``speed: "fast"`` request parameter for
+# significantly higher output token throughput on Opus 4.6 (~2.5x).
+# See https://platform.claude.com/docs/en/build-with-claude/fast-mode
+_FAST_MODE_BETA = "fast-mode-2026-02-01"
 
 # Additional beta headers required for OAuth/subscription auth.
 # Matches what Claude Code (and pi-ai / OpenCode) send.
@@ -148,18 +163,81 @@ def _get_claude_code_version() -> str:
 
 
 def _is_oauth_token(key: str) -> bool:
-    """Check if the key is an OAuth/setup token (not a regular Console API key).
+    """Check if the key is an Anthropic OAuth/setup token.
 
-    Regular API keys start with 'sk-ant-api'. Everything else (setup-tokens
-    starting with 'sk-ant-oat', managed keys, JWTs, etc.) needs Bearer auth.
+    Positively identifies Anthropic OAuth tokens by their key format:
+    - ``sk-ant-`` prefix (but NOT ``sk-ant-api``) → setup tokens, managed keys
+    - ``eyJ`` prefix → JWTs from the Anthropic OAuth flow
+
+    Non-Anthropic keys (MiniMax, Alibaba, etc.) don't match either pattern
+    and correctly return False.
     """
     if not key:
         return False
-    # Regular Console API keys use x-api-key header
+    # Regular Anthropic Console API keys — x-api-key auth, never OAuth
     if key.startswith("sk-ant-api"):
         return False
-    # Everything else (setup-tokens, managed keys, JWTs) uses Bearer auth
-    return True
+    # Anthropic-issued tokens (setup-tokens sk-ant-oat-*, managed keys)
+    if key.startswith("sk-ant-"):
+        return True
+    # JWTs from Anthropic OAuth flow
+    if key.startswith("eyJ"):
+        return True
+    return False
+
+
+def _normalize_base_url_text(base_url) -> str:
+    """Normalize SDK/base transport URL values to a plain string for inspection.
+
+    Some client objects expose ``base_url`` as an ``httpx.URL`` instead of a raw
+    string.  Provider/auth detection should accept either shape.
+    """
+    if not base_url:
+        return ""
+    return str(base_url).strip()
+
+
+def _is_third_party_anthropic_endpoint(base_url: str | None) -> bool:
+    """Return True for non-Anthropic endpoints using the Anthropic Messages API.
+
+    Third-party proxies (Azure AI Foundry, AWS Bedrock, self-hosted) authenticate
+    with their own API keys via x-api-key, not Anthropic OAuth tokens. OAuth
+    detection should be skipped for these endpoints.
+    """
+    normalized = _normalize_base_url_text(base_url)
+    if not normalized:
+        return False  # No base_url = direct Anthropic API
+    normalized = normalized.rstrip("/").lower()
+    if "anthropic.com" in normalized:
+        return False  # Direct Anthropic API — OAuth applies
+    return True  # Any other endpoint is a third-party proxy
+
+
+def _requires_bearer_auth(base_url: str | None) -> bool:
+    """Return True for Anthropic-compatible providers that require Bearer auth.
+
+    Some third-party /anthropic endpoints implement Anthropic's Messages API but
+    require Authorization: Bearer *** of Anthropic's native x-api-key header.
+    MiniMax's global and China Anthropic-compatible endpoints follow this pattern.
+    """
+    normalized = _normalize_base_url_text(base_url)
+    if not normalized:
+        return False
+    normalized = normalized.rstrip("/").lower()
+    return normalized.startswith(("https://api.minimax.io/anthropic", "https://api.minimaxi.com/anthropic"))
+
+
+def _common_betas_for_base_url(base_url: str | None) -> list[str]:
+    """Return the beta headers that are safe for the configured endpoint.
+
+    MiniMax's Anthropic-compatible endpoints (Bearer-auth) reject requests
+    that include Anthropic's ``fine-grained-tool-streaming`` beta — every
+    tool-use message triggers a connection error.  Strip that beta for
+    Bearer-auth endpoints while keeping all other betas intact.
+    """
+    if _requires_bearer_auth(base_url):
+        return [b for b in _COMMON_BETAS if b != _TOOL_STREAMING_BETA]
+    return _COMMON_BETAS
 
 
 def build_anthropic_client(api_key: str, base_url: str = None):
@@ -174,17 +252,37 @@ def build_anthropic_client(api_key: str, base_url: str = None):
         )
     from httpx import Timeout
 
+    normalized_base_url = _normalize_base_url_text(base_url)
     kwargs = {
         "timeout": Timeout(timeout=900.0, connect=10.0),
     }
-    if base_url:
-        kwargs["base_url"] = base_url
+    if normalized_base_url:
+        kwargs["base_url"] = normalized_base_url
+    common_betas = _common_betas_for_base_url(normalized_base_url)
 
-    if _is_oauth_token(api_key):
+    if _requires_bearer_auth(normalized_base_url):
+        # Some Anthropic-compatible providers (e.g. MiniMax) expect the API key in
+        # Authorization: Bearer even for regular API keys. Route those endpoints
+        # through auth_token so the SDK sends Bearer auth instead of x-api-key.
+        # Check this before OAuth token shape detection because MiniMax secrets do
+        # not use Anthropic's sk-ant-api prefix and would otherwise be misread as
+        # Anthropic OAuth/setup tokens.
+        kwargs["auth_token"] = api_key
+        if common_betas:
+            kwargs["default_headers"] = {"anthropic-beta": ",".join(common_betas)}
+    elif _is_third_party_anthropic_endpoint(base_url):
+        # Third-party proxies (Azure AI Foundry, AWS Bedrock, etc.) use their
+        # own API keys with x-api-key auth. Skip OAuth detection — their keys
+        # don't follow Anthropic's sk-ant-* prefix convention and would be
+        # misclassified as OAuth tokens.
+        kwargs["api_key"] = api_key
+        if common_betas:
+            kwargs["default_headers"] = {"anthropic-beta": ",".join(common_betas)}
+    elif _is_oauth_token(api_key):
         # OAuth access token / setup-token → Bearer auth + Claude Code identity.
         # Anthropic routes OAuth requests based on user-agent and headers;
         # without Claude Code's fingerprint, requests get intermittent 500s.
-        all_betas = _COMMON_BETAS + _OAUTH_ONLY_BETAS
+        all_betas = common_betas + _OAUTH_ONLY_BETAS
         kwargs["auth_token"] = api_key
         kwargs["default_headers"] = {
             "anthropic-beta": ",".join(all_betas),
@@ -194,8 +292,8 @@ def build_anthropic_client(api_key: str, base_url: str = None):
     else:
         # Regular API key → x-api-key header + common betas
         kwargs["api_key"] = api_key
-        if _COMMON_BETAS:
-            kwargs["default_headers"] = {"anthropic-beta": ",".join(_COMMON_BETAS)}
+        if common_betas:
+            kwargs["default_headers"] = {"anthropic-beta": ",".join(common_betas)}
 
     return _anthropic_sdk.Anthropic(**kwargs)
 
@@ -259,71 +357,105 @@ def is_claude_code_token_valid(creds: Dict[str, Any]) -> bool:
     return now_ms < (expires_at - 60_000)
 
 
-def _refresh_oauth_token(creds: Dict[str, Any]) -> Optional[str]:
-    """Attempt to refresh an expired Claude Code OAuth token.
-
-    Uses the same token endpoint and client_id as Claude Code / OpenCode.
-    Only works for credentials that have a refresh token (from claude /login
-    or claude setup-token with OAuth flow).
-
-    Tries the new platform.claude.com endpoint first (Claude Code >=2.1.81),
-    then falls back to console.anthropic.com for older tokens.
-
-    Returns the new access token, or None if refresh fails.
-    """
+def refresh_anthropic_oauth_pure(refresh_token: str, *, use_json: bool = False) -> Dict[str, Any]:
+    """Refresh an Anthropic OAuth token without mutating local credential files."""
     import time
+    import urllib.parse
     import urllib.request
 
+    if not refresh_token:
+        raise ValueError("refresh_token is required")
+
+    client_id = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
+    if use_json:
+        data = json.dumps({
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": client_id,
+        }).encode()
+        content_type = "application/json"
+    else:
+        data = urllib.parse.urlencode({
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": client_id,
+        }).encode()
+        content_type = "application/x-www-form-urlencoded"
+
+    token_endpoints = [
+        "https://platform.claude.com/v1/oauth/token",
+        "https://console.anthropic.com/v1/oauth/token",
+    ]
+    last_error = None
+    for endpoint in token_endpoints:
+        req = urllib.request.Request(
+            endpoint,
+            data=data,
+            headers={
+                "Content-Type": content_type,
+                "User-Agent": f"claude-cli/{_get_claude_code_version()} (external, cli)",
+            },
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                result = json.loads(resp.read().decode())
+        except Exception as exc:
+            last_error = exc
+            logger.debug("Anthropic token refresh failed at %s: %s", endpoint, exc)
+            continue
+
+        access_token = result.get("access_token", "")
+        if not access_token:
+            raise ValueError("Anthropic refresh response was missing access_token")
+        next_refresh = result.get("refresh_token", refresh_token)
+        expires_in = result.get("expires_in", 3600)
+        return {
+            "access_token": access_token,
+            "refresh_token": next_refresh,
+            "expires_at_ms": int(time.time() * 1000) + (expires_in * 1000),
+        }
+
+    if last_error is not None:
+        raise last_error
+    raise ValueError("Anthropic token refresh failed")
+
+
+def _refresh_oauth_token(creds: Dict[str, Any]) -> Optional[str]:
+    """Attempt to refresh an expired Claude Code OAuth token."""
     refresh_token = creds.get("refreshToken", "")
     if not refresh_token:
         logger.debug("No refresh token available — cannot refresh")
         return None
 
-    # Client ID used by Claude Code's OAuth flow
-    CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
-
-    # Anthropic migrated OAuth from console.anthropic.com to platform.claude.com
-    # (Claude Code v2.1.81+). Try new endpoint first, fall back to old.
-    token_endpoints = [
-        "https://platform.claude.com/v1/oauth/token",
-        "https://console.anthropic.com/v1/oauth/token",
-    ]
-
-    payload = json.dumps({
-        "grant_type": "refresh_token",
-        "refresh_token": refresh_token,
-        "client_id": CLIENT_ID,
-    }).encode()
-
-    headers = {
-        "Content-Type": "application/json",
-        "User-Agent": f"claude-cli/{_get_claude_code_version()} (external, cli)",
-    }
-
-    for endpoint in token_endpoints:
-        req = urllib.request.Request(
-            endpoint, data=payload, headers=headers, method="POST",
+    try:
+        refreshed = refresh_anthropic_oauth_pure(refresh_token, use_json=False)
+        _write_claude_code_credentials(
+            refreshed["access_token"],
+            refreshed["refresh_token"],
+            refreshed["expires_at_ms"],
         )
-        try:
-            with urllib.request.urlopen(req, timeout=10) as resp:
-                result = json.loads(resp.read().decode())
-                new_access = result.get("access_token", "")
-                new_refresh = result.get("refresh_token", refresh_token)
-                expires_in = result.get("expires_in", 3600)
-
-                if new_access:
-                    new_expires_ms = int(time.time() * 1000) + (expires_in * 1000)
-                    _write_claude_code_credentials(new_access, new_refresh, new_expires_ms)
-                    logger.debug("Refreshed Claude Code OAuth token via %s", endpoint)
-                    return new_access
-        except Exception as e:
-            logger.debug("Token refresh failed at %s: %s", endpoint, e)
-
-    return None
+        logger.debug("Successfully refreshed Claude Code OAuth token")
+        return refreshed["access_token"]
+    except Exception as e:
+        logger.debug("Failed to refresh Claude Code token: %s", e)
+        return None
 
 
-def _write_claude_code_credentials(access_token: str, refresh_token: str, expires_at_ms: int) -> None:
-    """Write refreshed credentials back to ~/.claude/.credentials.json."""
+def _write_claude_code_credentials(
+    access_token: str,
+    refresh_token: str,
+    expires_at_ms: int,
+    *,
+    scopes: Optional[list] = None,
+) -> None:
+    """Write refreshed credentials back to ~/.claude/.credentials.json.
+
+    The optional *scopes* list (e.g. ``["user:inference", "user:profile", ...]``)
+    is persisted so that Claude Code's own auth check recognises the credential
+    as valid.  Claude Code >=2.1.81 gates on the presence of ``"user:inference"``
+    in the stored scopes before it will use the token.
+    """
     cred_path = Path.home() / ".claude" / ".credentials.json"
     try:
         # Read existing file to preserve other fields
@@ -331,11 +463,19 @@ def _write_claude_code_credentials(access_token: str, refresh_token: str, expire
         if cred_path.exists():
             existing = json.loads(cred_path.read_text(encoding="utf-8"))
 
-        existing["claudeAiOauth"] = {
+        oauth_data: Dict[str, Any] = {
             "accessToken": access_token,
             "refreshToken": refresh_token,
             "expiresAt": expires_at_ms,
         }
+        if scopes is not None:
+            oauth_data["scopes"] = scopes
+        elif "claudeAiOauth" in existing and "scopes" in existing["claudeAiOauth"]:
+            # Preserve previously-stored scopes when the refresh response
+            # does not include a scope field.
+            oauth_data["scopes"] = existing["claudeAiOauth"]["scopes"]
+
+        existing["claudeAiOauth"] = oauth_data
 
         cred_path.parent.mkdir(parents=True, exist_ok=True)
         cred_path.write_text(json.dumps(existing, indent=2), encoding="utf-8")
@@ -382,35 +522,6 @@ def _prefer_refreshable_claude_code_token(env_token: str, creds: Optional[Dict[s
     return None
 
 
-def get_anthropic_token_source(token: Optional[str] = None) -> str:
-    """Best-effort source classification for an Anthropic credential token."""
-    token = (token or "").strip()
-    if not token:
-        return "none"
-
-    env_token = os.getenv("ANTHROPIC_TOKEN", "").strip()
-    if env_token and env_token == token:
-        return "anthropic_token_env"
-
-    cc_env_token = os.getenv("CLAUDE_CODE_OAUTH_TOKEN", "").strip()
-    if cc_env_token and cc_env_token == token:
-        return "claude_code_oauth_token_env"
-
-    creds = read_claude_code_credentials()
-    if creds and creds.get("accessToken") == token:
-        return str(creds.get("source") or "claude_code_credentials")
-
-    managed_key = read_claude_managed_key()
-    if managed_key and managed_key == token:
-        return "claude_json_primary_api_key"
-
-    api_key = os.getenv("ANTHROPIC_API_KEY", "").strip()
-    if api_key and api_key == token:
-        return "anthropic_api_key_env"
-
-    return "unknown"
-
-
 def resolve_anthropic_token() -> Optional[str]:
     """Resolve an Anthropic token from all available sources.
 
@@ -495,10 +606,138 @@ def run_oauth_setup_token() -> Optional[str]:
     return None
 
 
+# ── Hermes-native PKCE OAuth flow ────────────────────────────────────────
+# Mirrors the flow used by Claude Code, pi-ai, and OpenCode.
+# Stores credentials in ~/.hermes/.anthropic_oauth.json (our own file).
+
+_OAUTH_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
+_OAUTH_TOKEN_URL = "https://console.anthropic.com/v1/oauth/token"
+_OAUTH_REDIRECT_URI = "https://console.anthropic.com/oauth/code/callback"
+_OAUTH_SCOPES = "org:create_api_key user:profile user:inference"
+_HERMES_OAUTH_FILE = get_hermes_home() / ".anthropic_oauth.json"
 
 
+def _generate_pkce() -> tuple:
+    """Generate PKCE code_verifier and code_challenge (S256)."""
+    import base64
+    import hashlib
+    import secrets
+
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
+    challenge = base64.urlsafe_b64encode(
+        hashlib.sha256(verifier.encode()).digest()
+    ).rstrip(b"=").decode()
+    return verifier, challenge
 
 
+def run_hermes_oauth_login_pure() -> Optional[Dict[str, Any]]:
+    """Run Hermes-native OAuth PKCE flow and return credential state."""
+    import time
+    import webbrowser
+
+    verifier, challenge = _generate_pkce()
+
+    params = {
+        "code": "true",
+        "client_id": _OAUTH_CLIENT_ID,
+        "response_type": "code",
+        "redirect_uri": _OAUTH_REDIRECT_URI,
+        "scope": _OAUTH_SCOPES,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+        "state": verifier,
+    }
+    from urllib.parse import urlencode
+
+    auth_url = f"https://claude.ai/oauth/authorize?{urlencode(params)}"
+
+    print()
+    print("Authorize Hermes with your Claude Pro/Max subscription.")
+    print()
+    print("╭─ Claude Pro/Max Authorization ────────────────────╮")
+    print("│                                                   │")
+    print("│  Open this link in your browser:                  │")
+    print("╰───────────────────────────────────────────────────╯")
+    print()
+    print(f"  {auth_url}")
+    print()
+
+    try:
+        webbrowser.open(auth_url)
+        print("  (Browser opened automatically)")
+    except Exception:
+        pass
+
+    print()
+    print("After authorizing, you'll see a code. Paste it below.")
+    print()
+    try:
+        auth_code = input("Authorization code: ").strip()
+    except (KeyboardInterrupt, EOFError):
+        return None
+
+    if not auth_code:
+        print("No code entered.")
+        return None
+
+    splits = auth_code.split("#")
+    code = splits[0]
+    state = splits[1] if len(splits) > 1 else ""
+
+    try:
+        import urllib.request
+
+        exchange_data = json.dumps({
+            "grant_type": "authorization_code",
+            "client_id": _OAUTH_CLIENT_ID,
+            "code": code,
+            "state": state,
+            "redirect_uri": _OAUTH_REDIRECT_URI,
+            "code_verifier": verifier,
+        }).encode()
+
+        req = urllib.request.Request(
+            _OAUTH_TOKEN_URL,
+            data=exchange_data,
+            headers={
+                "Content-Type": "application/json",
+                "User-Agent": f"claude-cli/{_get_claude_code_version()} (external, cli)",
+            },
+            method="POST",
+        )
+
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            result = json.loads(resp.read().decode())
+    except Exception as e:
+        print(f"Token exchange failed: {e}")
+        return None
+
+    access_token = result.get("access_token", "")
+    refresh_token = result.get("refresh_token", "")
+    expires_in = result.get("expires_in", 3600)
+
+    if not access_token:
+        print("No access token in response.")
+        return None
+
+    expires_at_ms = int(time.time() * 1000) + (expires_in * 1000)
+    return {
+        "access_token": access_token,
+        "refresh_token": refresh_token,
+        "expires_at_ms": expires_at_ms,
+    }
+
+
+def read_hermes_oauth_credentials() -> Optional[Dict[str, Any]]:
+    """Read Hermes-managed OAuth credentials from ~/.hermes/.anthropic_oauth.json."""
+    if _HERMES_OAUTH_FILE.exists():
+        try:
+            data = json.loads(_HERMES_OAUTH_FILE.read_text(encoding="utf-8"))
+            if data.get("accessToken"):
+                return data
+        except (json.JSONDecodeError, OSError, IOError) as e:
+            logger.debug("Failed to read Hermes OAuth credentials: %s", e)
+    return None
 
 
 # ---------------------------------------------------------------------------
@@ -537,68 +776,6 @@ def _sanitize_tool_id(tool_id: str) -> str:
     return sanitized or "tool_0"
 
 
-def _convert_openai_image_part_to_anthropic(part: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-    """Convert an OpenAI-style image block to Anthropic's image source format."""
-    image_data = part.get("image_url", {})
-    url = image_data.get("url", "") if isinstance(image_data, dict) else str(image_data)
-    if not isinstance(url, str) or not url.strip():
-        return None
-    url = url.strip()
-
-    if url.startswith("data:"):
-        header, sep, data = url.partition(",")
-        if sep and ";base64" in header:
-            media_type = header[5:].split(";", 1)[0] or "image/png"
-            return {
-                "type": "image",
-                "source": {
-                    "type": "base64",
-                    "media_type": media_type,
-                    "data": data,
-                },
-            }
-
-    if url.startswith("http://") or url.startswith("https://"):
-        return {
-            "type": "image",
-            "source": {
-                "type": "url",
-                "url": url,
-            },
-        }
-
-    return None
-
-
-def _convert_user_content_part_to_anthropic(part: Any) -> Optional[Dict[str, Any]]:
-    if isinstance(part, dict):
-        ptype = part.get("type")
-        if ptype == "text":
-            block = {"type": "text", "text": part.get("text", "")}
-            if isinstance(part.get("cache_control"), dict):
-                block["cache_control"] = dict(part["cache_control"])
-            return block
-        if ptype == "image_url":
-            return _convert_openai_image_part_to_anthropic(part)
-        if ptype == "image" and part.get("source"):
-            return dict(part)
-        if ptype == "image" and part.get("data"):
-            media_type = part.get("mimeType") or part.get("media_type") or "image/png"
-            return {
-                "type": "image",
-                "source": {
-                    "type": "base64",
-                    "media_type": media_type,
-                    "data": part.get("data", ""),
-                },
-            }
-        if ptype == "tool_result":
-            return dict(part)
-    elif part is not None:
-        return {"type": "text", "text": str(part)}
-    return None
-
-
 def convert_tools_to_anthropic(tools: List[Dict]) -> List[Dict]:
     """Convert OpenAI tool definitions to Anthropic format."""
     if not tools:
@@ -661,6 +838,69 @@ def _convert_content_part_to_anthropic(part: Any) -> Optional[Dict[str, Any]]:
     return block
 
 
+def _to_plain_data(value: Any, *, _depth: int = 0, _path: Optional[set] = None) -> Any:
+    """Recursively convert SDK objects to plain Python data structures.
+
+    Guards against circular references (``_path`` tracks ``id()`` of objects
+    on the *current* recursion path) and runaway depth (capped at 20 levels).
+    Uses path-based tracking so shared (but non-cyclic) objects referenced by
+    multiple siblings are converted correctly rather than being stringified.
+    """
+    _MAX_DEPTH = 20
+    if _depth > _MAX_DEPTH:
+        return str(value)
+
+    if _path is None:
+        _path = set()
+
+    obj_id = id(value)
+    if obj_id in _path:
+        return str(value)
+
+    if hasattr(value, "model_dump"):
+        _path.add(obj_id)
+        result = _to_plain_data(value.model_dump(), _depth=_depth + 1, _path=_path)
+        _path.discard(obj_id)
+        return result
+    if isinstance(value, dict):
+        _path.add(obj_id)
+        result = {k: _to_plain_data(v, _depth=_depth + 1, _path=_path) for k, v in value.items()}
+        _path.discard(obj_id)
+        return result
+    if isinstance(value, (list, tuple)):
+        _path.add(obj_id)
+        result = [_to_plain_data(v, _depth=_depth + 1, _path=_path) for v in value]
+        _path.discard(obj_id)
+        return result
+    if hasattr(value, "__dict__"):
+        _path.add(obj_id)
+        result = {
+            k: _to_plain_data(v, _depth=_depth + 1, _path=_path)
+            for k, v in vars(value).items()
+            if not k.startswith("_")
+        }
+        _path.discard(obj_id)
+        return result
+    return value
+
+
+def _extract_preserved_thinking_blocks(message: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """Return Anthropic thinking blocks previously preserved on the message."""
+    raw_details = message.get("reasoning_details")
+    if not isinstance(raw_details, list):
+        return []
+
+    preserved: List[Dict[str, Any]] = []
+    for detail in raw_details:
+        if not isinstance(detail, dict):
+            continue
+        block_type = str(detail.get("type", "") or "").strip().lower()
+        if block_type not in {"thinking", "redacted_thinking"}:
+            continue
+        preserved.append(copy.deepcopy(detail))
+    return preserved
+
+
 def _convert_content_to_anthropic(content: Any) -> Any:
     """Convert OpenAI-style multimodal content arrays to Anthropic blocks."""
     if not isinstance(content, list):
@@ -676,12 +916,18 @@ def _convert_content_to_anthropic(content: Any) -> Any:
 
 def convert_messages_to_anthropic(
     messages: List[Dict],
+    base_url: str | None = None,
 ) -> Tuple[Optional[Any], List[Dict]]:
     """Convert OpenAI-format messages to Anthropic format.
 
     Returns (system_prompt, anthropic_messages).
     System messages are extracted since Anthropic takes them as a separate param.
     system_prompt is a string or list of content blocks (when cache_control present).
+
+    When *base_url* is provided and points to a third-party Anthropic-compatible
+    endpoint, all thinking block signatures are stripped.  Signatures are
+    Anthropic-proprietary — third-party endpoints cannot validate them and will
+    reject them with HTTP 400 "Invalid signature in thinking block".
     """
     system = None
     result = []
@@ -707,7 +953,7 @@ def convert_messages_to_anthropic(
             continue
 
         if role == "assistant":
-            blocks = []
+            blocks = _extract_preserved_thinking_blocks(m)
             if content:
                 if isinstance(content, list):
                     converted_content = _convert_content_to_anthropic(content)
@@ -836,7 +1082,15 @@ def convert_messages_to_anthropic(
                         curr_content = [{"type": "text", "text": curr_content}]
                     fixed[-1]["content"] = prev_content + curr_content
             else:
-                # Consecutive assistant messages — merge text content
+                # Consecutive assistant messages — merge text content.
+                # Drop thinking blocks from the *second* message: their
+                # signature was computed against a different turn boundary
+                # and becomes invalid once merged.
+                if isinstance(m["content"], list):
+                    m["content"] = [
+                        b for b in m["content"]
+                        if not (isinstance(b, dict) and b.get("type") in ("thinking", "redacted_thinking"))
+                    ]
                 prev_blocks = fixed[-1]["content"]
                 curr_blocks = m["content"]
                 if isinstance(prev_blocks, list) and isinstance(curr_blocks, list):
@@ -854,6 +1108,79 @@ def convert_messages_to_anthropic(
             fixed.append(m)
     result = fixed
 
+    # ── Thinking block signature management ──────────────────────────
+    # Anthropic signs thinking blocks against the full turn content.
+    # Any upstream mutation (context compression, session truncation,
+    # orphan stripping, message merging) invalidates the signature,
+    # causing HTTP 400 "Invalid signature in thinking block".
+    #
+    # Signatures are Anthropic-proprietary.  Third-party endpoints
+    # (MiniMax, Azure AI Foundry, self-hosted proxies) cannot validate
+    # them and will reject them outright.  When targeting a third-party
+    # endpoint, strip ALL thinking/redacted_thinking blocks from every
+    # assistant message — the third-party will generate its own
+    # thinking blocks if it supports extended thinking.
+    #
+    # For direct Anthropic (strategy following clawdbot/OpenClaw):
+    # 1. Strip thinking/redacted_thinking from all assistant messages
+    #    EXCEPT the last one — preserves reasoning continuity on the
+    #    current tool-use chain while avoiding stale signature errors.
+    # 2. Downgrade unsigned thinking blocks (no signature) to text —
+    #    Anthropic can't validate them and will reject them.
+    # 3. Strip cache_control from thinking/redacted_thinking blocks —
+    #    cache markers can interfere with signature validation.
+    _THINKING_TYPES = frozenset(("thinking", "redacted_thinking"))
+    _is_third_party = _is_third_party_anthropic_endpoint(base_url)
+
+    last_assistant_idx = None
+    for i in range(len(result) - 1, -1, -1):
+        if result[i].get("role") == "assistant":
+            last_assistant_idx = i
+            break
+
+    for idx, m in enumerate(result):
+        if m.get("role") != "assistant" or not isinstance(m.get("content"), list):
+            continue
+
+        if _is_third_party or idx != last_assistant_idx:
+            # Third-party endpoint: strip ALL thinking blocks from every
+            # assistant message — signatures are Anthropic-proprietary.
+            # Direct Anthropic: strip from non-latest assistant messages only.
+            stripped = [
+                b for b in m["content"]
+                if not (isinstance(b, dict) and b.get("type") in _THINKING_TYPES)
+            ]
+            m["content"] = stripped or [{"type": "text", "text": "(thinking elided)"}]
+        else:
+            # Latest assistant on direct Anthropic: keep signed thinking
+            # blocks for reasoning continuity; downgrade unsigned ones to
+            # plain text.
+            new_content = []
+            for b in m["content"]:
+                if not isinstance(b, dict) or b.get("type") not in _THINKING_TYPES:
+                    new_content.append(b)
+                    continue
+                if b.get("type") == "redacted_thinking":
+                    # Redacted blocks use 'data' for the signature payload
+                    if b.get("data"):
+                        new_content.append(b)
+                    # else: drop — no data means it can't be validated
+                elif b.get("signature"):
+                    # Signed thinking block — keep it
+                    new_content.append(b)
+                else:
+                    # Unsigned thinking — downgrade to text so it's not lost
+                    thinking_text = b.get("thinking", "")
+                    if thinking_text:
+                        new_content.append({"type": "text", "text": thinking_text})
+            m["content"] = new_content or [{"type": "text", "text": "(empty)"}]
+
+        # Strip cache_control from any remaining thinking/redacted_thinking
+        # blocks — cache markers interfere with signature validation.
+        for b in m["content"]:
+            if isinstance(b, dict) and b.get("type") in _THINKING_TYPES:
+                b.pop("cache_control", None)
+
     return system, result
 
 
@@ -867,28 +1194,59 @@ def build_anthropic_kwargs(
     is_oauth: bool = False,
     preserve_dots: bool = False,
     context_length: Optional[int] = None,
+    base_url: str | None = None,
+    fast_mode: bool = False,
 ) -> Dict[str, Any]:
     """Build kwargs for anthropic.messages.create().
 
-    When *max_tokens* is None, the model's native output limit is used
-    (e.g. 128K for Opus 4.6, 64K for Sonnet 4.6).  If *context_length*
-    is provided, the effective limit is clamped so it doesn't exceed
-    the context window.
+    Naming note — two distinct concepts, easily confused:
+      max_tokens     = OUTPUT token cap for a single response.
+                       Anthropic's API calls this "max_tokens" but it only
+                       limits the *output*.  Anthropic's own native SDK
+                       renamed it "max_output_tokens" for clarity.
+      context_length = TOTAL context window (input tokens + output tokens).
+                       The API enforces: input_tokens + max_tokens ≤ context_length.
+                       Stored on the ContextCompressor; reduced on overflow errors.
+
+    When *max_tokens* is None the model's native output ceiling is used
+    (e.g. 128K for Opus 4.6, 64K for Sonnet 4.6).
+
+    When *context_length* is provided and the model's native output ceiling
+    exceeds it (e.g. a local endpoint with an 8K window), the output cap is
+    clamped to context_length − 1.  This only kicks in for unusually small
+    context windows; for full-size models the native output cap is always
+    smaller than the context window so no clamping happens.
+    NOTE: this clamping does not account for prompt size — if the prompt is
+    large, Anthropic may still reject the request.  The caller must detect
+    "max_tokens too large given prompt" errors and retry with a smaller cap
+    (see parse_available_output_tokens_from_error + _ephemeral_max_output_tokens).
 
     When *is_oauth* is True, applies Claude Code compatibility transforms:
     system prompt prefix, tool name prefixing, and prompt sanitization.
 
     When *preserve_dots* is True, model name dots are not converted to hyphens
     (for Alibaba/DashScope anthropic-compatible endpoints: qwen3.5-plus).
+
+    When *base_url* points to a third-party Anthropic-compatible endpoint,
+    thinking block signatures are stripped (they are Anthropic-proprietary).
+
+    When *fast_mode* is True, adds ``extra_body["speed"] = "fast"`` and the
+    fast-mode beta header for ~2.5x faster output throughput on Opus 4.6.
+    Currently only supported on native Anthropic endpoints (not third-party
+    compatible ones).
     """
-    system, anthropic_messages = convert_messages_to_anthropic(messages)
+    system, anthropic_messages = convert_messages_to_anthropic(messages, base_url=base_url)
     anthropic_tools = convert_tools_to_anthropic(tools) if tools else []
 
     model = normalize_model_name(model, preserve_dots=preserve_dots)
+    # effective_max_tokens = output cap for this call (≠ total context window)
     effective_max_tokens = max_tokens or _get_anthropic_max_output(model)
 
-    # Clamp to context window if the user set a lower context_length
-    # (e.g. custom endpoint with limited capacity).
+    # Clamp output cap to fit inside the total context window.
+    # Only matters for small custom endpoints where context_length < native
+    # output ceiling.  For standard Anthropic models context_length (e.g.
+    # 200K) is always larger than the output ceiling (e.g. 128K), so this
+    # branch is not taken.
     if context_length and effective_max_tokens > context_length:
         effective_max_tokens = max(context_length - 1, 1)
 
@@ -958,7 +1316,8 @@ def build_anthropic_kwargs(
     # Map reasoning_config to Anthropic's thinking parameter.
     # Claude 4.6 models use adaptive thinking + output_config.effort.
     # Older models use manual thinking with budget_tokens.
-    # Haiku models do NOT support extended thinking at all — skip entirely.
+    # MiniMax Anthropic-compat endpoints support thinking (manual mode only,
+    # not adaptive).  Haiku does NOT support extended thinking — skip entirely.
     if reasoning_config and isinstance(reasoning_config, dict):
         if reasoning_config.get("enabled") is not False and "haiku" not in model.lower():
             effort = str(reasoning_config.get("effort", "medium")).lower()
@@ -974,6 +1333,20 @@ def build_anthropic_kwargs(
                 kwargs["temperature"] = 1
                 kwargs["max_tokens"] = max(effective_max_tokens, budget + 4096)
 
+    # ── Fast mode (Opus 4.6 only) ────────────────────────────────────
+    # Adds extra_body.speed="fast" + the fast-mode beta header for ~2.5x
+    # output speed. Only for native Anthropic endpoints — third-party
+    # providers would reject the unknown beta header and speed parameter.
+    if fast_mode and not _is_third_party_anthropic_endpoint(base_url):
+        kwargs.setdefault("extra_body", {})["speed"] = "fast"
+        # Build extra_headers with ALL applicable betas (the per-request
+        # extra_headers override the client-level anthropic-beta header).
+        betas = list(_common_betas_for_base_url(base_url))
+        if is_oauth:
+            betas.extend(_OAUTH_ONLY_BETAS)
+        betas.append(_FAST_MODE_BETA)
+        kwargs["extra_headers"] = {"anthropic-beta": ",".join(betas)}
+
     return kwargs
 
 
@@ -991,6 +1364,7 @@ def normalize_anthropic_response(
     """
     text_parts = []
     reasoning_parts = []
+    reasoning_details = []
     tool_calls = []
 
     for block in response.content:
@@ -998,6 +1372,9 @@ def normalize_anthropic_response(
             text_parts.append(block.text)
         elif block.type == "thinking":
             reasoning_parts.append(block.thinking)
+            block_dict = _to_plain_data(block)
+            if isinstance(block_dict, dict):
+                reasoning_details.append(block_dict)
         elif block.type == "tool_use":
             name = block.name
             if strip_tool_prefix and name.startswith(_MCP_TOOL_PREFIX):
@@ -1019,6 +1396,8 @@ def normalize_anthropic_response(
         "tool_use": "tool_calls",
         "max_tokens": "length",
         "stop_sequence": "stop",
+        "refusal": "content_filter",
+        "model_context_window_exceeded": "length",
     }
     finish_reason = stop_reason_map.get(response.stop_reason, "stop")
 
@@ -1028,7 +1407,46 @@ def normalize_anthropic_response(
             tool_calls=tool_calls or None,
             reasoning="\n\n".join(reasoning_parts) if reasoning_parts else None,
             reasoning_content=None,
-            reasoning_details=None,
+            reasoning_details=reasoning_details or None,
         ),
         finish_reason,
     )
+
+
+def normalize_anthropic_response_v2(
+    response,
+    strip_tool_prefix: bool = False,
+) -> "NormalizedResponse":
+    """Normalize Anthropic response to NormalizedResponse.
+
+    Wraps the existing normalize_anthropic_response() and maps its output
+    to the shared transport types. This allows incremental migration
+    without disturbing the legacy call sites.
+    """
+    from agent.transports.types import NormalizedResponse, build_tool_call
+
+    assistant_msg, finish_reason = normalize_anthropic_response(response, strip_tool_prefix)
+
+    tool_calls = None
+    if assistant_msg.tool_calls:
+        tool_calls = [
+            build_tool_call(
+                id=tc.id,
+                name=tc.function.name,
+                arguments=tc.function.arguments,
+            )
+            for tc in assistant_msg.tool_calls
+        ]
+
+    provider_data = {}
+    if getattr(assistant_msg, "reasoning_details", None):
+        provider_data["reasoning_details"] = assistant_msg.reasoning_details
+
+    return NormalizedResponse(
+        content=assistant_msg.content,
+        tool_calls=tool_calls,
+        finish_reason=finish_reason,
+        reasoning=getattr(assistant_msg, "reasoning", None),
+        usage=None,
+        provider_data=provider_data or None,
+    )

agent/circuit_breaker.py

@@ -0,0 +1,273 @@
+"""
+Circuit Breaker for Error Cascading — #885
+
+P(error | prev was error) = 58.6% vs P(error | prev was success) = 25.2%.
+That's a 2.33x cascade factor. After 3 consecutive errors, the circuit
+opens and the agent must take corrective action.
+
+States:
+- CLOSED: Normal operation, errors are counted
+- OPEN: Too many consecutive errors, corrective action required
+- HALF_OPEN: Testing if errors have cleared
+
+Usage:
+    from agent.circuit_breaker import CircuitBreaker, ToolCircuitBreaker
+    
+    cb = ToolCircuitBreaker()
+    
+    # After each tool call
+    if not cb.record_result(success=True):
+        # Circuit is open — take corrective action
+        cb.get_recovery_action()
+"""
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class CircuitState(Enum):
+    CLOSED = "closed"      # Normal operation
+    OPEN = "open"          # Too many errors, block execution
+    HALF_OPEN = "half_open"  # Testing recovery
+
+
+@dataclass
+class CircuitBreaker:
+    """
+    Generic circuit breaker with configurable thresholds.
+    
+    Tracks consecutive errors and opens the circuit when the
+    error streak exceeds the threshold.
+    """
+    failure_threshold: int = 3
+    recovery_timeout: float = 30.0  # seconds before trying half-open
+    success_threshold: int = 2      # successes needed to close from half-open
+    
+    state: CircuitState = field(default=CircuitState.CLOSED, init=False)
+    consecutive_failures: int = field(default=0, init=False)
+    consecutive_successes: int = field(default=0, init=False)
+    last_failure_time: Optional[float] = field(default=None, init=False)
+    total_trips: int = field(default=0, init=False)
+    error_streaks: List[int] = field(default_factory=list, init=False)
+    
+    def record_result(self, success: bool) -> bool:
+        """
+        Record a tool call result. Returns True if circuit allows execution.
+        
+        Returns:
+            True if circuit is CLOSED or HALF_OPEN (execution allowed)
+            False if circuit is OPEN (execution blocked)
+        """
+        now = time.time()
+        
+        if self.state == CircuitState.OPEN:
+            # Check if recovery timeout has passed
+            if self.last_failure_time and (now - self.last_failure_time) >= self.recovery_timeout:
+                self.state = CircuitState.HALF_OPEN
+                self.consecutive_successes = 0
+                return True  # Allow one test execution
+            return False  # Still open
+        
+        if success:
+            self.consecutive_failures = 0
+            self.consecutive_successes += 1
+            
+            if self.state == CircuitState.HALF_OPEN:
+                if self.consecutive_successes >= self.success_threshold:
+                    self.state = CircuitState.CLOSED
+                    self.consecutive_successes = 0
+            
+            return True
+        else:
+            self.consecutive_successes = 0
+            self.consecutive_failures += 1
+            self.last_failure_time = now
+            
+            if self.state == CircuitState.HALF_OPEN:
+                # Failed during recovery — reopen immediately
+                self.state = CircuitState.OPEN
+                self.total_trips += 1
+                return False
+            
+            if self.consecutive_failures >= self.failure_threshold:
+                self.state = CircuitState.OPEN
+                self.total_trips += 1
+                self.error_streaks.append(self.consecutive_failures)
+                return False
+            
+            return True
+    
+    def can_execute(self) -> bool:
+        """Check if execution is allowed."""
+        if self.state == CircuitState.OPEN:
+            if self.last_failure_time:
+                now = time.time()
+                if (now - self.last_failure_time) >= self.recovery_timeout:
+                    self.state = CircuitState.HALF_OPEN
+                    self.consecutive_successes = 0
+                    return True
+            return False
+        return True
+    
+    def get_state(self) -> Dict[str, Any]:
+        """Get current circuit state."""
+        return {
+            "state": self.state.value,
+            "consecutive_failures": self.consecutive_failures,
+            "consecutive_successes": self.consecutive_successes,
+            "total_trips": self.total_trips,
+            "max_streak": max(self.error_streaks) if self.error_streaks else 0,
+            "can_execute": self.can_execute(),
+        }
+    
+    def reset(self):
+        """Reset the circuit breaker."""
+        self.state = CircuitState.CLOSED
+        self.consecutive_failures = 0
+        self.consecutive_successes = 0
+        self.last_failure_time = None
+
+
+class ToolCircuitBreaker(CircuitBreaker):
+    """
+    Circuit breaker specifically for tool call error cascading.
+    
+    Provides recovery actions when the circuit opens.
+    """
+    
+    # Tools that are most effective at recovery (from audit data)
+    RECOVERY_TOOLS = [
+        "terminal",     # Most effective — 2300 recoveries
+        "read_file",    # Reset context by reading something
+        "search_files", # Find what went wrong
+    ]
+    
+    def get_recovery_action(self) -> Dict[str, Any]:
+        """
+        Get the recommended recovery action when circuit is open.
+        
+        Returns dict with action type and details.
+        """
+        streak = self.consecutive_failures
+        
+        if streak >= 9:
+            # After 9 errors: 41/46 recoveries via terminal
+            return {
+                "action": "terminal_only",
+                "reason": f"Error streak of {streak} — terminal is the only reliable recovery",
+                "suggested_tool": "terminal",
+                "suggested_command": "echo 'Resetting context'",
+                "severity": "critical",
+            }
+        elif streak >= 5:
+            return {
+                "action": "switch_tool_type",
+                "reason": f"Error streak of {streak} — switch to a different tool category",
+                "suggested_tools": ["read_file", "search_files", "terminal"],
+                "severity": "high",
+            }
+        elif streak >= self.failure_threshold:
+            return {
+                "action": "ask_user",
+                "reason": f"{streak} consecutive errors — ask user for guidance",
+                "suggested_response": "I'm encountering repeated errors. Would you like me to try a different approach?",
+                "severity": "medium",
+            }
+        else:
+            return {
+                "action": "continue",
+                "reason": f"Error streak of {streak} — within tolerance",
+                "severity": "low",
+            }
+    
+    def should_compress_context(self) -> bool:
+        """Determine if context compression would help recovery."""
+        return self.consecutive_failures >= 5
+    
+    def get_blocked_tool(self) -> Optional[str]:
+        """Get the tool that should be blocked (if any)."""
+        if self.state == CircuitState.OPEN:
+            return "last_failed_tool"
+        return None
+
+
+class MultiToolCircuitBreaker:
+    """
+    Manages per-tool circuit breakers and cross-tool cascade detection.
+    
+    When one tool trips its breaker, related tools are also warned.
+    """
+    
+    def __init__(self):
+        self.breakers: Dict[str, ToolCircuitBreaker] = {}
+        self.global_streak: int = 0
+        self.last_tool: Optional[str] = None
+        self.last_success: bool = True
+    
+    def get_breaker(self, tool_name: str) -> ToolCircuitBreaker:
+        """Get or create a circuit breaker for a tool."""
+        if tool_name not in self.breakers:
+            self.breakers[tool_name] = ToolCircuitBreaker()
+        return self.breakers[tool_name]
+    
+    def record_result(self, tool_name: str, success: bool) -> bool:
+        """
+        Record a tool call result. Returns True if execution should continue.
+        """
+        breaker = self.get_breaker(tool_name)
+        allowed = breaker.record_result(success)
+        
+        # Track global streak
+        if success:
+            self.global_streak = 0
+            self.last_success = True
+        else:
+            self.global_streak += 1
+            self.last_success = False
+        
+        self.last_tool = tool_name
+        return allowed
+    
+    def can_execute(self, tool_name: str) -> bool:
+        """Check if a specific tool can execute."""
+        breaker = self.get_breaker(tool_name)
+        return breaker.can_execute()
+    
+    def get_global_state(self) -> Dict[str, Any]:
+        """Get overall circuit breaker state."""
+        return {
+            "global_streak": self.global_streak,
+            "last_tool": self.last_tool,
+            "last_success": self.last_success,
+            "tool_states": {
+                name: breaker.get_state()
+                for name, breaker in self.breakers.items()
+                if breaker.consecutive_failures > 0 or breaker.total_trips > 0
+            },
+            "any_open": any(b.state == CircuitState.OPEN for b in self.breakers.values()),
+        }
+    
+    def get_recovery_action(self) -> Dict[str, Any]:
+        """Get recovery action based on global state."""
+        if self.global_streak == 0:
+            return {"action": "continue", "reason": "No errors"}
+        
+        # Find the breaker with the worst streak
+        worst = max(self.breakers.values(), key=lambda b: b.consecutive_failures, default=None)
+        if worst and worst.consecutive_failures > 0:
+            return worst.get_recovery_action()
+        
+        return {
+            "action": "continue",
+            "reason": f"Global streak: {self.global_streak}",
+            "severity": "low",
+        }
+    
+    def reset_all(self):
+        """Reset all circuit breakers."""
+        for breaker in self.breakers.values():
+            breaker.reset()
+        self.global_streak = 0
+        self.last_success = True

agent/conscience_mapping.py

@@ -1,6 +0,0 @@
-"""
-@soul:honesty.grounding Grounding before generation. Consult verified sources before pattern-matching.
-@soul:honesty.source_distinction Source distinction. Every claim must point to a verified source.
-@soul:honesty.audit_trail The audit trail. Every response is logged with inputs and confidence.
-"""
-# This file serves as a registry for the Conscience Validator to prove the apparatus exists.

agent/context_budget.py

@@ -0,0 +1,148 @@
+"""
+Context Budget Tracker - Prevent context window overflow
+
+Poka-yoke: Visual warnings at 70%%, 85%%, 95%% capacity.
+Auto-checkpoint at 85%%. Pre-flight token estimation.
+
+Issue: #838
+"""
+
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+HERMES_HOME = Path.home() / ".hermes"
+CHECKPOINT_DIR = HERMES_HOME / "checkpoints"
+CHARS_PER_TOKEN = 4
+
+THRESHOLD_WARNING = 0.70
+THRESHOLD_CRITICAL = 0.85
+THRESHOLD_DANGER = 0.95
+
+
+class ContextBudget:
+    def __init__(self, context_limit: int = 128000, system_tokens: int = 0, 
+                 used_tokens: int = 0, reserved_tokens: int = 2000):
+        self.context_limit = context_limit
+        self.system_tokens = system_tokens
+        self.used_tokens = used_tokens
+        self.reserved_tokens = reserved_tokens
+    
+    @property
+    def total_used(self) -> int:
+        return self.system_tokens + self.used_tokens
+    
+    @property
+    def available(self) -> int:
+        return max(0, self.context_limit - self.reserved_tokens)
+    
+    @property
+    def remaining(self) -> int:
+        return max(0, self.available - self.total_used)
+    
+    @property
+    def utilization(self) -> float:
+        return self.total_used / self.available if self.available > 0 else 1.0
+
+
+def estimate_tokens(text: str) -> int:
+    return len(text) // CHARS_PER_TOKEN if text else 0
+
+
+def estimate_messages_tokens(messages: List[Dict]) -> int:
+    total = 0
+    for msg in messages:
+        content = msg.get("content", "")
+        if isinstance(content, str):
+            total += estimate_tokens(content)
+        if msg.get("tool_calls"):
+            total += 100
+    return total
+
+
+class ContextBudgetTracker:
+    def __init__(self, context_limit: int = 128000, session_id: str = ""):
+        self.budget = ContextBudget(context_limit=context_limit)
+        self.session_id = session_id
+        self._checkpointed = False
+        self._warnings_given = set()
+    
+    def update_from_messages(self, messages: List[Dict]):
+        self.budget.used_tokens = estimate_messages_tokens(messages)
+    
+    def can_fit(self, additional_tokens: int) -> bool:
+        return self.budget.remaining >= additional_tokens
+    
+    def preflight_check(self, text: str) -> Tuple[bool, str]:
+        tokens = estimate_tokens(text)
+        if not self.can_fit(tokens):
+            return False, f"Cannot load: ~{tokens:,} tokens needed, {self.budget.remaining:,} remaining"
+        would_util = (self.budget.total_used + tokens) / self.budget.available if self.budget.available > 0 else 1.0
+        if would_util >= THRESHOLD_DANGER:
+            return False, f"Would reach {would_util:.0%%} capacity. Summarize or start new session."
+        if would_util >= THRESHOLD_CRITICAL:
+            return True, f"Warning: will reach {would_util:.0%%} capacity."
+        return True, ""
+    
+    def get_warning(self) -> Optional[str]:
+        util = self.budget.utilization
+        if util >= THRESHOLD_DANGER and "danger" not in self._warnings_given:
+            self._warnings_given.add("danger")
+            return f"[CONTEXT CRITICAL: {util:.0%%} used -- {self.budget.remaining:,} tokens left. Summarize or start new session.]"
+        if util >= THRESHOLD_CRITICAL and "critical" not in self._warnings_given:
+            self._warnings_given.add("critical")
+            self._auto_checkpoint()
+            return f"[CONTEXT WARNING: {util:.0%%} used -- consider summarizing. Auto-checkpoint saved.]"
+        if util >= THRESHOLD_WARNING and "warning" not in self._warnings_given:
+            self._warnings_given.add("warning")
+            return f"[CONTEXT: {util:.0%%} used -- {self.budget.remaining:,} tokens remaining]"
+        return None
+    
+    def _auto_checkpoint(self):
+        if self._checkpointed or not self.session_id:
+            return
+        try:
+            CHECKPOINT_DIR.mkdir(parents=True, exist_ok=True)
+            path = CHECKPOINT_DIR / f"{self.session_id}.json"
+            path.write_text(json.dumps({
+                "session_id": self.session_id,
+                "timestamp": time.time(),
+                "budget": {"utilization": round(self.budget.utilization * 100, 1)}
+            }, indent=2))
+            self._checkpointed = True
+            logger.info("Auto-checkpoint saved: %s", path)
+        except Exception as e:
+            logger.error("Auto-checkpoint failed: %s", e)
+    
+    def get_status_line(self) -> str:
+        util = self.budget.utilization
+        remaining = self.budget.remaining
+        if util >= THRESHOLD_DANGER:
+            return f"RED {util:.0%%} used ({remaining:,} left)"
+        elif util >= THRESHOLD_CRITICAL:
+            return f"ORANGE {util:.0%%} used ({remaining:,} left)"
+        elif util >= THRESHOLD_WARNING:
+            return f"YELLOW {util:.0%%} used ({remaining:,} left)"
+        return f"GREEN {util:.0%%} used ({remaining:,} left)"
+
+
+_tracker = None
+
+def get_tracker(context_limit=128000, session_id=""):
+    global _tracker
+    if _tracker is None:
+        _tracker = ContextBudgetTracker(context_limit, session_id)
+    return _tracker
+
+def check_context_budget(messages, context_limit=128000):
+    tracker = get_tracker(context_limit)
+    tracker.update_from_messages(messages)
+    return tracker.get_warning()
+
+def preflight_token_check(text):
+    tracker = get_tracker()
+    return tracker.preflight_check(text)

agent/context_engine.py

@@ -0,0 +1,184 @@
+"""Abstract base class for pluggable context engines.
+
+A context engine controls how conversation context is managed when
+approaching the model's token limit. The built-in ContextCompressor
+is the default implementation. Third-party engines (e.g. LCM) can
+replace it via the plugin system or by being placed in the
+``plugins/context_engine/<name>/`` directory.
+
+Selection is config-driven: ``context.engine`` in config.yaml.
+Default is ``"compressor"`` (the built-in). Only one engine is active.
+
+The engine is responsible for:
+  - Deciding when compaction should fire
+  - Performing compaction (summarization, DAG construction, etc.)
+  - Optionally exposing tools the agent can call (e.g. lcm_grep)
+  - Tracking token usage from API responses
+
+Lifecycle:
+  1. Engine is instantiated and registered (plugin register() or default)
+  2. on_session_start() called when a conversation begins
+  3. update_from_response() called after each API response with usage data
+  4. should_compress() checked after each turn
+  5. compress() called when should_compress() returns True
+  6. on_session_end() called at real session boundaries (CLI exit, /reset,
+     gateway session expiry) — NOT per-turn
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List
+
+
+class ContextEngine(ABC):
+    """Base class all context engines must implement."""
+
+    # -- Identity ----------------------------------------------------------
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Short identifier (e.g. 'compressor', 'lcm')."""
+
+    # -- Token state (read by run_agent.py for display/logging) ------------
+    #
+    # Engines MUST maintain these. run_agent.py reads them directly.
+
+    last_prompt_tokens: int = 0
+    last_completion_tokens: int = 0
+    last_total_tokens: int = 0
+    threshold_tokens: int = 0
+    context_length: int = 0
+    compression_count: int = 0
+
+    # -- Compaction parameters (read by run_agent.py for preflight) --------
+    #
+    # These control the preflight compression check.  Subclasses may
+    # override via __init__ or property; defaults are sensible for most
+    # engines.
+
+    threshold_percent: float = 0.75
+    protect_first_n: int = 3
+    protect_last_n: int = 6
+
+    # -- Core interface ----------------------------------------------------
+
+    @abstractmethod
+    def update_from_response(self, usage: Dict[str, Any]) -> None:
+        """Update tracked token usage from an API response.
+
+        Called after every LLM call with the usage dict from the response.
+        """
+
+    @abstractmethod
+    def should_compress(self, prompt_tokens: int = None) -> bool:
+        """Return True if compaction should fire this turn."""
+
+    @abstractmethod
+    def compress(
+        self,
+        messages: List[Dict[str, Any]],
+        current_tokens: int = None,
+    ) -> List[Dict[str, Any]]:
+        """Compact the message list and return the new message list.
+
+        This is the main entry point. The engine receives the full message
+        list and returns a (possibly shorter) list that fits within the
+        context budget. The implementation is free to summarize, build a
+        DAG, or do anything else — as long as the returned list is a valid
+        OpenAI-format message sequence.
+        """
+
+    # -- Optional: pre-flight check ----------------------------------------
+
+    def should_compress_preflight(self, messages: List[Dict[str, Any]]) -> bool:
+        """Quick rough check before the API call (no real token count yet).
+
+        Default returns False (skip pre-flight). Override if your engine
+        can do a cheap estimate.
+        """
+        return False
+
+    # -- Optional: session lifecycle ---------------------------------------
+
+    def on_session_start(self, session_id: str, **kwargs) -> None:
+        """Called when a new conversation session begins.
+
+        Use this to load persisted state (DAG, store) for the session.
+        kwargs may include hermes_home, platform, model, etc.
+        """
+
+    def on_session_end(self, session_id: str, messages: List[Dict[str, Any]]) -> None:
+        """Called at real session boundaries (CLI exit, /reset, gateway expiry).
+
+        Use this to flush state, close DB connections, etc.
+        NOT called per-turn — only when the session truly ends.
+        """
+
+    def on_session_reset(self) -> None:
+        """Called on /new or /reset. Reset per-session state.
+
+        Default resets compression_count and token tracking.
+        """
+        self.last_prompt_tokens = 0
+        self.last_completion_tokens = 0
+        self.last_total_tokens = 0
+        self.compression_count = 0
+
+    # -- Optional: tools ---------------------------------------------------
+
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        """Return tool schemas this engine provides to the agent.
+
+        Default returns empty list (no tools). LCM would return schemas
+        for lcm_grep, lcm_describe, lcm_expand here.
+        """
+        return []
+
+    def handle_tool_call(self, name: str, args: Dict[str, Any], **kwargs) -> str:
+        """Handle a tool call from the agent.
+
+        Only called for tool names returned by get_tool_schemas().
+        Must return a JSON string.
+
+        kwargs may include:
+          messages: the current in-memory message list (for live ingestion)
+        """
+        import json
+        return json.dumps({"error": f"Unknown context engine tool: {name}"})
+
+    # -- Optional: status / display ----------------------------------------
+
+    def get_status(self) -> Dict[str, Any]:
+        """Return status dict for display/logging.
+
+        Default returns the standard fields run_agent.py expects.
+        """
+        return {
+            "last_prompt_tokens": self.last_prompt_tokens,
+            "threshold_tokens": self.threshold_tokens,
+            "context_length": self.context_length,
+            "usage_percent": (
+                min(100, self.last_prompt_tokens / self.context_length * 100)
+                if self.context_length else 0
+            ),
+            "compression_count": self.compression_count,
+        }
+
+    # -- Optional: model switch support ------------------------------------
+
+    def update_model(
+        self,
+        model: str,
+        context_length: int,
+        base_url: str = "",
+        api_key: str = "",
+        provider: str = "",
+    ) -> None:
+        """Called when the user switches models or on fallback activation.
+
+        Default updates context_length and recalculates threshold_tokens
+        from threshold_percent. Override if your engine needs more
+        (e.g. recalculate DAG budgets, switch summary models).
+        """
+        self.context_length = context_length
+        self.threshold_tokens = int(context_length * self.threshold_percent)

agent/context_references.py

@@ -13,11 +13,12 @@ from typing import Awaitable, Callable
 
 from agent.model_metadata import estimate_tokens_rough
 
+_QUOTED_REFERENCE_VALUE = r'(?:`[^`\n]+`|"[^"\n]+"|\'[^\'\n]+\')'
 REFERENCE_PATTERN = re.compile(
-    r"(?<![\w/])@(?:(?P<simple>diff|staged)\b|(?P<kind>file|folder|git|url):(?P<value>\S+))"
+    rf"(?<![\w/])@(?:(?P<simple>diff|staged)\b|(?P<kind>file|folder|git|url):(?P<value>{_QUOTED_REFERENCE_VALUE}(?::\d+(?:-\d+)?)?|\S+))"
 )
 TRAILING_PUNCTUATION = ",.;!?"
-_SENSITIVE_HOME_DIRS = (".ssh", ".aws", ".gnupg", ".kube")
+_SENSITIVE_HOME_DIRS = (".ssh", ".aws", ".gnupg", ".kube", ".docker", ".azure", ".config/gh")
 _SENSITIVE_HERMES_DIRS = (Path("skills") / ".hub",)
 _SENSITIVE_HOME_FILES = (
     Path(".ssh") / "authorized_keys",
@@ -81,14 +82,10 @@ def parse_context_references(message: str) -> list[ContextReference]:
         value = _strip_trailing_punctuation(match.group("value") or "")
         line_start = None
         line_end = None
-        target = value
+        target = _strip_reference_wrappers(value)
 
         if kind == "file":
-            range_match = re.match(r"^(?P<path>.+?):(?P<start>\d+)(?:-(?P<end>\d+))?$", value)
-            if range_match:
-                target = range_match.group("path")
-                line_start = int(range_match.group("start"))
-                line_end = int(range_match.group("end") or range_match.group("start"))
+            target, line_start, line_end = _parse_file_reference_value(value)
 
         refs.append(
             ContextReference(
@@ -343,10 +340,9 @@ def _resolve_path(cwd: Path, target: str, *, allowed_root: Path | None = None) -
 
 
 def _ensure_reference_path_allowed(path: Path) -> None:
+    from hermes_constants import get_hermes_home
     home = Path(os.path.expanduser("~")).resolve()
-    hermes_home = Path(
-        os.getenv("HERMES_HOME", str(home / ".hermes"))
-    ).expanduser().resolve()
+    hermes_home = get_hermes_home().resolve()
 
     blocked_exact = {home / rel for rel in _SENSITIVE_HOME_FILES}
     blocked_exact.add(hermes_home / ".env")
@@ -376,6 +372,38 @@ def _strip_trailing_punctuation(value: str) -> str:
     return stripped
 
 
+def _strip_reference_wrappers(value: str) -> str:
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "`\"'":
+        return value[1:-1]
+    return value
+
+
+def _parse_file_reference_value(value: str) -> tuple[str, int | None, int | None]:
+    quoted_match = re.match(
+        r'^(?P<quote>`|"|\')(?P<path>.+?)(?P=quote)(?::(?P<start>\d+)(?:-(?P<end>\d+))?)?$',
+        value,
+    )
+    if quoted_match:
+        line_start = quoted_match.group("start")
+        line_end = quoted_match.group("end")
+        return (
+            quoted_match.group("path"),
+            int(line_start) if line_start is not None else None,
+            int(line_end or line_start) if line_start is not None else None,
+        )
+
+    range_match = re.match(r"^(?P<path>.+?):(?P<start>\d+)(?:-(?P<end>\d+))?$", value)
+    if range_match:
+        line_start = int(range_match.group("start"))
+        return (
+            range_match.group("path"),
+            line_start,
+            int(range_match.group("end") or range_match.group("start")),
+        )
+
+    return _strip_reference_wrappers(value), None, None
+
+
 def _remove_reference_tokens(message: str, refs: list[ContextReference]) -> str:
     pieces: list[str] = []
     cursor = 0

agent/copilot_acp_client.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import json
 import os
 import queue
+import re
 import shlex
 import subprocess
 import threading
@@ -23,6 +24,9 @@ from typing import Any
 ACP_MARKER_BASE_URL = "acp://copilot"
 _DEFAULT_TIMEOUT_SECONDS = 900.0
 
+_TOOL_CALL_BLOCK_RE = re.compile(r"<tool_call>\s*(\{.*?\})\s*</tool_call>", re.DOTALL)
+_TOOL_CALL_JSON_RE = re.compile(r"\{\s*\"id\"\s*:\s*\"[^\"]+\"\s*,\s*\"type\"\s*:\s*\"function\"\s*,\s*\"function\"\s*:\s*\{.*?\}\s*\}", re.DOTALL)
+
 
 def _resolve_command() -> str:
     return (
@@ -50,15 +54,50 @@ def _jsonrpc_error(message_id: Any, code: int, message: str) -> dict[str, Any]:
     }
 
 
-def _format_messages_as_prompt(messages: list[dict[str, Any]], model: str | None = None) -> str:
+def _format_messages_as_prompt(
+    messages: list[dict[str, Any]],
+    model: str | None = None,
+    tools: list[dict[str, Any]] | None = None,
+    tool_choice: Any = None,
+) -> str:
     sections: list[str] = [
         "You are being used as the active ACP agent backend for Hermes.",
-        "Use your own ACP capabilities and respond directly in natural language.",
-        "Do not emit OpenAI tool-call JSON.",
+        "Use ACP capabilities to complete tasks.",
+        "IMPORTANT: If you take an action with a tool, you MUST output tool calls using <tool_call>{...}</tool_call> blocks with JSON exactly in OpenAI function-call shape.",
+        "If no tool is needed, answer normally.",
     ]
     if model:
         sections.append(f"Hermes requested model hint: {model}")
 
+    if isinstance(tools, list) and tools:
+        tool_specs: list[dict[str, Any]] = []
+        for t in tools:
+            if not isinstance(t, dict):
+                continue
+            fn = t.get("function") or {}
+            if not isinstance(fn, dict):
+                continue
+            name = fn.get("name")
+            if not isinstance(name, str) or not name.strip():
+                continue
+            tool_specs.append(
+                {
+                    "name": name.strip(),
+                    "description": fn.get("description", ""),
+                    "parameters": fn.get("parameters", {}),
+                }
+            )
+        if tool_specs:
+            sections.append(
+                "Available tools (OpenAI function schema). "
+                "When using a tool, emit ONLY <tool_call>{...}</tool_call> with one JSON object "
+                "containing id/type/function{name,arguments}. arguments must be a JSON string.\n"
+                + json.dumps(tool_specs, ensure_ascii=False)
+            )
+
+    if tool_choice is not None:
+        sections.append(f"Tool choice hint: {json.dumps(tool_choice, ensure_ascii=False)}")
+
     transcript: list[str] = []
     for message in messages:
         if not isinstance(message, dict):
@@ -114,6 +153,80 @@ def _render_message_content(content: Any) -> str:
     return str(content).strip()
 
 
+def _extract_tool_calls_from_text(text: str) -> tuple[list[SimpleNamespace], str]:
+    if not isinstance(text, str) or not text.strip():
+        return [], ""
+
+    extracted: list[SimpleNamespace] = []
+    consumed_spans: list[tuple[int, int]] = []
+
+    def _try_add_tool_call(raw_json: str) -> None:
+        try:
+            obj = json.loads(raw_json)
+        except Exception:
+            return
+        if not isinstance(obj, dict):
+            return
+        fn = obj.get("function")
+        if not isinstance(fn, dict):
+            return
+        fn_name = fn.get("name")
+        if not isinstance(fn_name, str) or not fn_name.strip():
+            return
+        fn_args = fn.get("arguments", "{}")
+        if not isinstance(fn_args, str):
+            fn_args = json.dumps(fn_args, ensure_ascii=False)
+        call_id = obj.get("id")
+        if not isinstance(call_id, str) or not call_id.strip():
+            call_id = f"acp_call_{len(extracted)+1}"
+
+        extracted.append(
+            SimpleNamespace(
+                id=call_id,
+                call_id=call_id,
+                response_item_id=None,
+                type="function",
+                function=SimpleNamespace(name=fn_name.strip(), arguments=fn_args),
+            )
+        )
+
+    for m in _TOOL_CALL_BLOCK_RE.finditer(text):
+        raw = m.group(1)
+        _try_add_tool_call(raw)
+        consumed_spans.append((m.start(), m.end()))
+
+    # Only try bare-JSON fallback when no XML blocks were found.
+    if not extracted:
+        for m in _TOOL_CALL_JSON_RE.finditer(text):
+            raw = m.group(0)
+            _try_add_tool_call(raw)
+            consumed_spans.append((m.start(), m.end()))
+
+    if not consumed_spans:
+        return extracted, text.strip()
+
+    consumed_spans.sort()
+    merged: list[tuple[int, int]] = []
+    for start, end in consumed_spans:
+        if not merged or start > merged[-1][1]:
+            merged.append((start, end))
+        else:
+            merged[-1] = (merged[-1][0], max(merged[-1][1], end))
+
+    parts: list[str] = []
+    cursor = 0
+    for start, end in merged:
+        if cursor < start:
+            parts.append(text[cursor:start])
+        cursor = max(cursor, end)
+    if cursor < len(text):
+        parts.append(text[cursor:])
+
+    cleaned = "\n".join(p.strip() for p in parts if p and p.strip()).strip()
+    return extracted, cleaned
+
+
+
 def _ensure_path_within_cwd(path_text: str, cwd: str) -> Path:
     candidate = Path(path_text)
     if not candidate.is_absolute():
@@ -190,14 +303,23 @@ class CopilotACPClient:
         model: str | None = None,
         messages: list[dict[str, Any]] | None = None,
         timeout: float | None = None,
+        tools: list[dict[str, Any]] | None = None,
+        tool_choice: Any = None,
         **_: Any,
     ) -> Any:
-        prompt_text = _format_messages_as_prompt(messages or [], model=model)
+        prompt_text = _format_messages_as_prompt(
+            messages or [],
+            model=model,
+            tools=tools,
+            tool_choice=tool_choice,
+        )
         response_text, reasoning_text = self._run_prompt(
             prompt_text,
             timeout_seconds=float(timeout or _DEFAULT_TIMEOUT_SECONDS),
         )
 
+        tool_calls, cleaned_text = _extract_tool_calls_from_text(response_text)
+
         usage = SimpleNamespace(
             prompt_tokens=0,
             completion_tokens=0,
@@ -205,13 +327,14 @@ class CopilotACPClient:
             prompt_tokens_details=SimpleNamespace(cached_tokens=0),
         )
         assistant_message = SimpleNamespace(
-            content=response_text,
-            tool_calls=[],
+            content=cleaned_text,
+            tool_calls=tool_calls,
             reasoning=reasoning_text or None,
             reasoning_content=reasoning_text or None,
             reasoning_details=None,
         )
-        choice = SimpleNamespace(message=assistant_message, finish_reason="stop")
+        finish_reason = "tool_calls" if tool_calls else "stop"
+        choice = SimpleNamespace(message=assistant_message, finish_reason=finish_reason)
         return SimpleNamespace(
             choices=[choice],
             usage=usage,

agent/crisis_resources.py

@@ -0,0 +1,149 @@
+"""
+988 Suicide & Crisis Lifeline Integration (#673).
+
+When crisis is detected, provides immediate access to help:
+- Phone: 988 (call or text)
+- Text: Text HOME to 988
+- Chat: 988lifeline.org/chat
+- Spanish: 1-888-628-9454
+- Emergency: 911
+
+This module provides the resource data. agent/crisis_protocol.py
+handles detection. This module formats the resources for display.
+"""
+
+from dataclasses import dataclass
+from typing import List
+
+
+@dataclass
+class CrisisResource:
+    """A crisis support contact method."""
+    name: str
+    contact: str
+    description: str
+    url: str = ""
+    available: str = "24/7"
+    language: str = "English"
+
+
+# 988 Suicide & Crisis Lifeline — all channels
+LIFELINE_988 = CrisisResource(
+    name="988 Suicide and Crisis Lifeline",
+    contact="Call or text 988",
+    description="Free, confidential support for people in suicidal crisis or emotional distress.",
+    url="https://988lifeline.org",
+    available="24/7",
+    language="English",
+)
+
+LIFELINE_988_TEXT = CrisisResource(
+    name="988 Crisis Text Line",
+    contact="Text HOME to 988",
+    description="Free, 24/7 crisis support via text message.",
+    url="",
+    available="24/7",
+    language="English",
+)
+
+LIFELINE_988_CHAT = CrisisResource(
+    name="988 Lifeline Chat",
+    contact="988lifeline.org/chat",
+    description="Free, confidential online chat with a trained crisis counselor.",
+    url="https://988lifeline.org/chat",
+    available="24/7",
+    language="English",
+)
+
+LIFELINE_988_SPANISH = CrisisResource(
+    name="988 Lifeline (Spanish)",
+    contact="1-888-628-9454",
+    description="Línea de prevención del suicidio en español.",
+    url="https://988lifeline.org/help-yourself/en-espanol/",
+    available="24/7",
+    language="Spanish",
+)
+
+CRISIS_TEXT_LINE = CrisisResource(
+    name="Crisis Text Line",
+    contact="Text HOME to 741741",
+    description="Free, 24/7 crisis support via text message.",
+    url="https://www.crisistextline.org",
+    available="24/7",
+    language="English",
+)
+
+EMERGENCY_911 = CrisisResource(
+    name="Emergency Services",
+    contact="911",
+    description="Immediate danger — police, fire, ambulance.",
+    url="",
+    available="24/7",
+    language="Any",
+)
+
+# All resources in priority order
+ALL_RESOURCES: List[CrisisResource] = [
+    EMERGENCY_911,
+    LIFELINE_988,
+    LIFELINE_988_TEXT,
+    LIFELINE_988_CHAT,
+    CRISIS_TEXT_LINE,
+    LIFELINE_988_SPANISH,
+]
+
+
+def get_crisis_resources(language: str = None) -> List[CrisisResource]:
+    """Get crisis resources, optionally filtered by language.
+
+    Args:
+        language: Filter by language ("English", "Spanish", or None for all)
+
+    Returns:
+        List of CrisisResource objects
+    """
+    if language:
+        return [r for r in ALL_RESOURCES if r.language.lower() == language.lower()]
+    return ALL_RESOURCES
+
+
+def format_crisis_resources(resources: List[CrisisResource] = None) -> str:
+    """Format crisis resources as a user-facing message.
+
+    Args:
+        resources: List of resources to format. Defaults to all resources.
+
+    Returns:
+        Formatted string suitable for displaying to a user in crisis.
+    """
+    if resources is None:
+        resources = ALL_RESOURCES
+
+    lines = ["**Please reach out — help is available right now:**
+"]
+
+    for r in resources:
+        if r.url:
+            lines.append(f"- **{r.name}:** {r.contact} ({r.url})")
+        else:
+            lines.append(f"- **{r.name}:** {r.contact}")
+
+    lines.append("")
+    lines.append("All services are free, confidential, and available 24/7.")
+    lines.append("You are not alone.")
+
+    return "
+".join(lines)
+
+
+def get_immediate_help_message() -> str:
+    """Get the most urgent crisis help message.
+
+    Used when crisis is detected at CRITICAL level.
+    """
+    return (
+        "If you are in immediate danger, call **911** right now.
+
+"
+        + format_crisis_resources()
+    )

agent/display.py

@@ -4,12 +4,16 @@ Pure display functions and classes with no AIAgent dependency.
 Used by AIAgent._execute_tool_calls for CLI feedback.
 """
 
-import json
 import logging
 import os
 import sys
 import threading
 import time
+from dataclasses import dataclass, field
+from difflib import unified_diff
+from pathlib import Path
+
+from utils import safe_json_loads
 
 # ANSI escape codes for coloring tool failure indicators
 _RED = "\033[31m"
@@ -17,6 +21,78 @@ _RESET = "\033[0m"
 
 logger = logging.getLogger(__name__)
 
+_ANSI_RESET = "\033[0m"
+
+# Diff colors — resolved lazily from the skin engine so they adapt
+# to light/dark themes.  Falls back to sensible defaults on import
+# failure.  We cache after first resolution for performance.
+_diff_colors_cached: dict[str, str] | None = None
+
+
+def _diff_ansi() -> dict[str, str]:
+    """Return ANSI escapes for diff display, resolved from the active skin."""
+    global _diff_colors_cached
+    if _diff_colors_cached is not None:
+        return _diff_colors_cached
+
+    # Defaults that work on dark terminals
+    dim = "\033[38;2;150;150;150m"
+    file_c = "\033[38;2;180;160;255m"
+    hunk = "\033[38;2;120;120;140m"
+    minus = "\033[38;2;255;255;255;48;2;120;20;20m"
+    plus = "\033[38;2;255;255;255;48;2;20;90;20m"
+
+    try:
+        from hermes_cli.skin_engine import get_active_skin
+        skin = get_active_skin()
+
+        def _hex_fg(key: str, fallback_rgb: tuple[int, int, int]) -> str:
+            h = skin.get_color(key, "")
+            if h and len(h) == 7 and h[0] == "#":
+                r, g, b = int(h[1:3], 16), int(h[3:5], 16), int(h[5:7], 16)
+                return f"\033[38;2;{r};{g};{b}m"
+            r, g, b = fallback_rgb
+            return f"\033[38;2;{r};{g};{b}m"
+
+        dim = _hex_fg("banner_dim", (150, 150, 150))
+        file_c = _hex_fg("session_label", (180, 160, 255))
+        hunk = _hex_fg("session_border", (120, 120, 140))
+        # minus/plus use background colors — derive from ui_error/ui_ok
+        err_h = skin.get_color("ui_error", "#ef5350")
+        ok_h = skin.get_color("ui_ok", "#4caf50")
+        if err_h and len(err_h) == 7:
+            er, eg, eb = int(err_h[1:3], 16), int(err_h[3:5], 16), int(err_h[5:7], 16)
+            # Use a dark tinted version as background
+            minus = f"\033[38;2;255;255;255;48;2;{max(er//2,20)};{max(eg//4,10)};{max(eb//4,10)}m"
+        if ok_h and len(ok_h) == 7:
+            or_, og, ob = int(ok_h[1:3], 16), int(ok_h[3:5], 16), int(ok_h[5:7], 16)
+            plus = f"\033[38;2;255;255;255;48;2;{max(or_//4,10)};{max(og//2,20)};{max(ob//4,10)}m"
+    except Exception:
+        pass
+
+    _diff_colors_cached = {
+        "dim": dim, "file": file_c, "hunk": hunk,
+        "minus": minus, "plus": plus,
+    }
+    return _diff_colors_cached
+
+
+# Module-level helpers — each call resolves from the active skin lazily.
+def _diff_dim():   return _diff_ansi()["dim"]
+def _diff_file():  return _diff_ansi()["file"]
+def _diff_hunk():  return _diff_ansi()["hunk"]
+def _diff_minus(): return _diff_ansi()["minus"]
+def _diff_plus():  return _diff_ansi()["plus"]
+_MAX_INLINE_DIFF_FILES = 6
+_MAX_INLINE_DIFF_LINES = 80
+
+
+@dataclass
+class LocalEditSnapshot:
+    """Pre-tool filesystem snapshot used to render diffs locally after writes."""
+    paths: list[Path] = field(default_factory=list)
+    before: dict[str, str | None] = field(default_factory=dict)
+
 # =========================================================================
 # Configurable tool preview length (0 = no limit)
 # Set once at startup by CLI or gateway from display.tool_preview_length config.
@@ -48,26 +124,6 @@ def _get_skin():
         return None
 
 
-def get_skin_faces(key: str, default: list) -> list:
-    """Get spinner face list from active skin, falling back to default."""
-    skin = _get_skin()
-    if skin:
-        faces = skin.get_spinner_list(key)
-        if faces:
-            return faces
-    return default
-
-
-def get_skin_verbs() -> list:
-    """Get thinking verbs from active skin."""
-    skin = _get_skin()
-    if skin:
-        verbs = skin.get_spinner_list("thinking_verbs")
-        if verbs:
-            return verbs
-    return KawaiiSpinner.THINKING_VERBS
-
-
 def get_skin_tool_prefix() -> str:
     """Get tool output prefix character from active skin."""
     skin = _get_skin()
@@ -218,6 +274,296 @@ def build_tool_preview(tool_name: str, args: dict, max_len: int | None = None) -
     return preview
 
 
+# =========================================================================
+# Inline diff previews for write actions
+# =========================================================================
+
+def _resolved_path(path: str) -> Path:
+    """Resolve a possibly-relative filesystem path against the current cwd."""
+    candidate = Path(os.path.expanduser(path))
+    if candidate.is_absolute():
+        return candidate
+    return Path.cwd() / candidate
+
+
+def _snapshot_text(path: Path) -> str | None:
+    """Return UTF-8 file content, or None for missing/unreadable files."""
+    try:
+        return path.read_text(encoding="utf-8")
+    except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError, OSError):
+        return None
+
+
+def _display_diff_path(path: Path) -> str:
+    """Prefer cwd-relative paths in diffs when available."""
+    try:
+        return str(path.resolve().relative_to(Path.cwd().resolve()))
+    except Exception:
+        return str(path)
+
+
+def _resolve_skill_manage_paths(args: dict) -> list[Path]:
+    """Resolve skill_manage write targets to filesystem paths."""
+    action = args.get("action")
+    name = args.get("name")
+    if not action or not name:
+        return []
+
+    from tools.skill_manager_tool import _find_skill, _resolve_skill_dir
+
+    if action == "create":
+        skill_dir = _resolve_skill_dir(name, args.get("category"))
+        return [skill_dir / "SKILL.md"]
+
+    existing = _find_skill(name)
+    if not existing:
+        return []
+
+    skill_dir = Path(existing["path"])
+    if action in {"edit", "patch"}:
+        file_path = args.get("file_path")
+        return [skill_dir / file_path] if file_path else [skill_dir / "SKILL.md"]
+    if action in {"write_file", "remove_file"}:
+        file_path = args.get("file_path")
+        return [skill_dir / file_path] if file_path else []
+    if action == "delete":
+        files = [path for path in sorted(skill_dir.rglob("*")) if path.is_file()]
+        return files
+    return []
+
+
+def _resolve_local_edit_paths(tool_name: str, function_args: dict | None) -> list[Path]:
+    """Resolve local filesystem targets for write-capable tools."""
+    if not isinstance(function_args, dict):
+        return []
+
+    if tool_name == "write_file":
+        path = function_args.get("path")
+        return [_resolved_path(path)] if path else []
+
+    if tool_name == "patch":
+        path = function_args.get("path")
+        return [_resolved_path(path)] if path else []
+
+    if tool_name == "skill_manage":
+        return _resolve_skill_manage_paths(function_args)
+
+    return []
+
+
+def capture_local_edit_snapshot(tool_name: str, function_args: dict | None) -> LocalEditSnapshot | None:
+    """Capture before-state for local write previews."""
+    paths = _resolve_local_edit_paths(tool_name, function_args)
+    if not paths:
+        return None
+
+    snapshot = LocalEditSnapshot(paths=paths)
+    for path in paths:
+        snapshot.before[str(path)] = _snapshot_text(path)
+    return snapshot
+
+
+def _result_succeeded(result: str | None) -> bool:
+    """Conservatively detect whether a tool result represents success."""
+    if not result:
+        return False
+    data = safe_json_loads(result)
+    if data is None:
+        return False
+    if not isinstance(data, dict):
+        return False
+    if data.get("error"):
+        return False
+    if "success" in data:
+        return bool(data.get("success"))
+    return True
+
+
+def _diff_from_snapshot(snapshot: LocalEditSnapshot | None) -> str | None:
+    """Generate unified diff text from a stored before-state and current files."""
+    if not snapshot:
+        return None
+
+    chunks: list[str] = []
+    for path in snapshot.paths:
+        before = snapshot.before.get(str(path))
+        after = _snapshot_text(path)
+        if before == after:
+            continue
+
+        display_path = _display_diff_path(path)
+        diff = "".join(
+            unified_diff(
+                [] if before is None else before.splitlines(keepends=True),
+                [] if after is None else after.splitlines(keepends=True),
+                fromfile=f"a/{display_path}",
+                tofile=f"b/{display_path}",
+            )
+        )
+        if diff:
+            chunks.append(diff)
+
+    if not chunks:
+        return None
+    return "".join(chunk if chunk.endswith("\n") else chunk + "\n" for chunk in chunks)
+
+
+def extract_edit_diff(
+    tool_name: str,
+    result: str | None,
+    *,
+    function_args: dict | None = None,
+    snapshot: LocalEditSnapshot | None = None,
+) -> str | None:
+    """Extract a unified diff from a file-edit tool result."""
+    if tool_name == "patch" and result:
+        data = safe_json_loads(result)
+        if isinstance(data, dict):
+            diff = data.get("diff")
+            if isinstance(diff, str) and diff.strip():
+                return diff
+
+    if tool_name not in {"write_file", "patch", "skill_manage"}:
+        return None
+    if not _result_succeeded(result):
+        return None
+    return _diff_from_snapshot(snapshot)
+
+
+def _emit_inline_diff(diff_text: str, print_fn) -> bool:
+    """Emit rendered diff text through the CLI's prompt_toolkit-safe printer."""
+    if print_fn is None or not diff_text:
+        return False
+    try:
+        print_fn("  ┊ review diff")
+        for line in diff_text.rstrip("\n").splitlines():
+            print_fn(line)
+        return True
+    except Exception:
+        return False
+
+
+def _render_inline_unified_diff(diff: str) -> list[str]:
+    """Render unified diff lines in Hermes' inline transcript style."""
+    rendered: list[str] = []
+    from_file = None
+    to_file = None
+
+    for raw_line in diff.splitlines():
+        if raw_line.startswith("--- "):
+            from_file = raw_line[4:].strip()
+            continue
+        if raw_line.startswith("+++ "):
+            to_file = raw_line[4:].strip()
+            if from_file or to_file:
+                rendered.append(f"{_diff_file()}{from_file or 'a/?'} → {to_file or 'b/?'}{_ANSI_RESET}")
+            continue
+        if raw_line.startswith("@@"):
+            rendered.append(f"{_diff_hunk()}{raw_line}{_ANSI_RESET}")
+            continue
+        if raw_line.startswith("-"):
+            rendered.append(f"{_diff_minus()}{raw_line}{_ANSI_RESET}")
+            continue
+        if raw_line.startswith("+"):
+            rendered.append(f"{_diff_plus()}{raw_line}{_ANSI_RESET}")
+            continue
+        if raw_line.startswith(" "):
+            rendered.append(f"{_diff_dim()}{raw_line}{_ANSI_RESET}")
+            continue
+        if raw_line:
+            rendered.append(raw_line)
+
+    return rendered
+
+
+def _split_unified_diff_sections(diff: str) -> list[str]:
+    """Split a unified diff into per-file sections."""
+    sections: list[list[str]] = []
+    current: list[str] = []
+
+    for line in diff.splitlines():
+        if line.startswith("--- ") and current:
+            sections.append(current)
+            current = [line]
+            continue
+        current.append(line)
+
+    if current:
+        sections.append(current)
+
+    return ["\n".join(section) for section in sections if section]
+
+
+def _summarize_rendered_diff_sections(
+    diff: str,
+    *,
+    max_files: int = _MAX_INLINE_DIFF_FILES,
+    max_lines: int = _MAX_INLINE_DIFF_LINES,
+) -> list[str]:
+    """Render diff sections while capping file count and total line count."""
+    sections = _split_unified_diff_sections(diff)
+    rendered: list[str] = []
+    omitted_files = 0
+    omitted_lines = 0
+
+    for idx, section in enumerate(sections):
+        if idx >= max_files:
+            omitted_files += 1
+            omitted_lines += len(_render_inline_unified_diff(section))
+            continue
+
+        section_lines = _render_inline_unified_diff(section)
+        remaining_budget = max_lines - len(rendered)
+        if remaining_budget <= 0:
+            omitted_lines += len(section_lines)
+            omitted_files += 1
+            continue
+
+        if len(section_lines) <= remaining_budget:
+            rendered.extend(section_lines)
+            continue
+
+        rendered.extend(section_lines[:remaining_budget])
+        omitted_lines += len(section_lines) - remaining_budget
+        omitted_files += 1 + max(0, len(sections) - idx - 1)
+        for leftover in sections[idx + 1:]:
+            omitted_lines += len(_render_inline_unified_diff(leftover))
+        break
+
+    if omitted_files or omitted_lines:
+        summary = f"… omitted {omitted_lines} diff line(s)"
+        if omitted_files:
+            summary += f" across {omitted_files} additional file(s)/section(s)"
+        rendered.append(f"{_diff_hunk()}{summary}{_ANSI_RESET}")
+
+    return rendered
+
+
+def render_edit_diff_with_delta(
+    tool_name: str,
+    result: str | None,
+    *,
+    function_args: dict | None = None,
+    snapshot: LocalEditSnapshot | None = None,
+    print_fn=None,
+) -> bool:
+    """Render an edit diff inline without taking over the terminal UI."""
+    diff = extract_edit_diff(
+        tool_name,
+        result,
+        function_args=function_args,
+        snapshot=snapshot,
+    )
+    if not diff:
+        return False
+    try:
+        rendered_lines = _summarize_rendered_diff_sections(diff)
+    except Exception as exc:
+        logger.debug("Could not render inline diff: %s", exc)
+        return False
+    return _emit_inline_diff("\n".join(rendered_lines), print_fn)
+
+
 # =========================================================================
 # KawaiiSpinner
 # =========================================================================
@@ -410,46 +756,6 @@ class KawaiiSpinner:
         return False
 
 
-# =========================================================================
-# Kawaii face arrays (used by AIAgent._execute_tool_calls for spinner text)
-# =========================================================================
-
-KAWAII_SEARCH = [
-    "♪(´ε` )", "(｡◕‿◕｡)", "ヾ(＾∇＾)", "(◕ᴗ◕✿)", "( ˘▽˘)っ",
-    "٩(◕‿◕｡)۶", "(✿◠‿◠)", "♪～(´ε｀ )", "(ノ´ヮ`)ノ*:・゚✧", "＼(◎o◎)／",
-]
-KAWAII_READ = [
-    "φ(゜▽゜*)♪", "( ˘▽˘)っ", "(⌐■_■)", "٩(｡•́‿•̀｡)۶", "(◕‿◕✿)",
-    "ヾ(＠⌒ー⌒＠)ノ", "(✧ω✧)", "♪(๑ᴖ◡ᴖ๑)♪", "(≧◡≦)", "( ´ ▽ ` )ノ",
-]
-KAWAII_TERMINAL = [
-    "ヽ(>∀<☆)ノ", "(ノ°∀°)ノ", "٩(^ᴗ^)۶", "ヾ(⌐■_■)ノ♪", "(•̀ᴗ•́)و",
-    "┗(＾0＾)┓", "(｀・ω・´)", "＼(￣▽￣)／", "(ง •̀_•́)ง", "ヽ(´▽`)/",
-]
-KAWAII_BROWSER = [
-    "(ノ°∀°)ノ", "(☞゚ヮ゚)☞", "( ͡° ͜ʖ ͡°)", "┌( ಠ_ಠ)┘", "(⊙_⊙)？",
-    "ヾ(•ω•`)o", "(￣ω￣)", "( ˇωˇ )", "(ᵔᴥᵔ)", "＼(◎o◎)／",
-]
-KAWAII_CREATE = [
-    "✧*。٩(ˊᗜˋ*)و✧", "(ﾉ◕ヮ◕)ﾉ*:・ﾟ✧", "ヽ(>∀<☆)ノ", "٩(♡ε♡)۶", "(◕‿◕)♡",
-    "✿◕ ‿ ◕✿", "(*≧▽≦)", "ヾ(＾-＾)ノ", "(☆▽☆)", "°˖✧◝(⁰▿⁰)◜✧˖°",
-]
-KAWAII_SKILL = [
-    "ヾ(＠⌒ー⌒＠)ノ", "(๑˃ᴗ˂)ﻭ", "٩(◕‿◕｡)۶", "(✿╹◡╹)", "ヽ(・∀・)ノ",
-    "(ノ´ヮ`)ノ*:・ﾟ✧", "♪(๑ᴖ◡ᴖ๑)♪", "(◠‿◠)", "٩(ˊᗜˋ*)و", "(＾▽＾)",
-    "ヾ(＾∇＾)", "(★ω★)/", "٩(｡•́‿•̀｡)۶", "(◕ᴗ◕✿)", "＼(◎o◎)／",
-    "(✧ω✧)", "ヽ(>∀<☆)ノ", "( ˘▽˘)っ", "(≧◡≦) ♡", "ヾ(￣▽￣)",
-]
-KAWAII_THINK = [
-    "(っ°Д°;)っ", "(；′⌒`)", "(・_・ヾ", "( ´_ゝ`)", "(￣ヘ￣)",
-    "(。-`ω´-)", "( ˘︹˘ )", "(¬_¬)", "ヽ(ー_ー )ノ", "(；一_一)",
-]
-KAWAII_GENERIC = [
-    "♪(´ε` )", "(◕‿◕✿)", "ヾ(＾∇＾)", "٩(◕‿◕｡)۶", "(✿◠‿◠)",
-    "(ノ´ヮ`)ノ*:・ﾟ✧", "ヽ(>∀<☆)ノ", "(☆▽☆)", "( ˘▽˘)っ", "(≧◡≦)",
-]
-
-
 # =========================================================================
 # Cute tool message (completion line that replaces the spinner)
 # =========================================================================
@@ -465,23 +771,19 @@ def _detect_tool_failure(tool_name: str, result: str | None) -> tuple[bool, str]
         return False, ""
 
     if tool_name == "terminal":
-        try:
-            data = json.loads(result)
+        data = safe_json_loads(result)
+        if isinstance(data, dict):
             exit_code = data.get("exit_code")
             if exit_code is not None and exit_code != 0:
                 return True, f" [exit {exit_code}]"
-        except (json.JSONDecodeError, TypeError, AttributeError):
-            logger.debug("Could not parse terminal result as JSON for exit code check")
         return False, ""
 
     # Memory-specific: distinguish "full" from real errors
     if tool_name == "memory":
-        try:
-            data = json.loads(result)
+        data = safe_json_loads(result)
+        if isinstance(data, dict):
             if data.get("success") is False and "exceed the limit" in data.get("error", ""):
                 return True, " [full]"
-        except (json.JSONDecodeError, TypeError, AttributeError):
-            logger.debug("Could not parse memory result as JSON for capacity check")
 
     # Generic heuristic for non-terminal tools
     lower = result[:500].lower()
@@ -577,8 +879,6 @@ def get_cute_tool_message(
         return _wrap(f"┊ ◀️  back      {dur}")
     if tool_name == "browser_press":
         return _wrap(f"┊ ⌨️  press     {args.get('key', '?')}  {dur}")
-    if tool_name == "browser_close":
-        return _wrap(f"┊ 🚪 close     browser  {dur}")
     if tool_name == "browser_get_images":
         return _wrap(f"┊ 🖼️  images    extracting  {dur}")
     if tool_name == "browser_vision":
@@ -659,40 +959,6 @@ _SKY_BLUE = "\033[38;5;117m"
 _ANSI_RESET = "\033[0m"
 
 
-def honcho_session_url(workspace: str, session_name: str) -> str:
-    """Build a Honcho app URL for a session."""
-    from urllib.parse import quote
-    return (
-        f"https://app.honcho.dev/explore"
-        f"?workspace={quote(workspace, safe='')}"
-        f"&view=sessions"
-        f"&session={quote(session_name, safe='')}"
-    )
-
-
-def _osc8_link(url: str, text: str) -> str:
-    """OSC 8 terminal hyperlink (clickable in iTerm2, Ghostty, WezTerm, etc.)."""
-    return f"\033]8;;{url}\033\\{text}\033]8;;\033\\"
-
-
-def honcho_session_line(workspace: str, session_name: str) -> str:
-    """One-line session indicator: `Honcho session: <clickable name>`."""
-    url = honcho_session_url(workspace, session_name)
-    linked_name = _osc8_link(url, f"{_SKY_BLUE}{session_name}{_ANSI_RESET}")
-    return f"{_DIM}Honcho session:{_ANSI_RESET} {linked_name}"
-
-
-def write_tty(text: str) -> None:
-    """Write directly to /dev/tty, bypassing stdout capture."""
-    try:
-        fd = os.open("/dev/tty", os.O_WRONLY)
-        os.write(fd, text.encode("utf-8"))
-        os.close(fd)
-    except OSError:
-        sys.stdout.write(text)
-        sys.stdout.flush()
-
-
 # =========================================================================
 # Context pressure display (CLI user-facing warnings)
 # =========================================================================

agent/error_classifier.py

@@ -0,0 +1,820 @@
+"""API error classification for smart failover and recovery.
+
+Provides a structured taxonomy of API errors and a priority-ordered
+classification pipeline that determines the correct recovery action
+(retry, rotate credential, fallback to another provider, compress
+context, or abort).
+
+Replaces scattered inline string-matching with a centralized classifier
+that the main retry loop in run_agent.py consults for every API failure.
+"""
+
+from __future__ import annotations
+
+import enum
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# ── Error taxonomy ──────────────────────────────────────────────────────
+
+class FailoverReason(enum.Enum):
+    """Why an API call failed — determines recovery strategy."""
+
+    # Authentication / authorization
+    auth = "auth"                        # Transient auth (401/403) — refresh/rotate
+    auth_permanent = "auth_permanent"    # Auth failed after refresh — abort
+
+    # Billing / quota
+    billing = "billing"                  # 402 or confirmed credit exhaustion — rotate immediately
+    rate_limit = "rate_limit"            # 429 or quota-based throttling — backoff then rotate
+
+    # Server-side
+    overloaded = "overloaded"            # 503/529 — provider overloaded, backoff
+    server_error = "server_error"        # 500/502 — internal server error, retry
+
+    # Transport
+    timeout = "timeout"                  # Connection/read timeout — rebuild client + retry
+
+    # Context / payload
+    context_overflow = "context_overflow"  # Context too large — compress, not failover
+    payload_too_large = "payload_too_large"  # 413 — compress payload
+
+    # Model
+    model_not_found = "model_not_found"  # 404 or invalid model — fallback to different model
+
+    # Request format
+    format_error = "format_error"        # 400 bad request — abort or strip + retry
+
+    # Provider-specific
+    thinking_signature = "thinking_signature"  # Anthropic thinking block sig invalid
+    long_context_tier = "long_context_tier"    # Anthropic "extra usage" tier gate
+
+    # Catch-all
+    unknown = "unknown"                  # Unclassifiable — retry with backoff
+
+
+# ── Classification result ───────────────────────────────────────────────
+
+@dataclass
+class ClassifiedError:
+    """Structured classification of an API error with recovery hints."""
+
+    reason: FailoverReason
+    status_code: Optional[int] = None
+    provider: Optional[str] = None
+    model: Optional[str] = None
+    message: str = ""
+    error_context: Dict[str, Any] = field(default_factory=dict)
+
+    # Recovery action hints — the retry loop checks these instead of
+    # re-classifying the error itself.
+    retryable: bool = True
+    should_compress: bool = False
+    should_rotate_credential: bool = False
+    should_fallback: bool = False
+
+    @property
+    def is_auth(self) -> bool:
+        return self.reason in (FailoverReason.auth, FailoverReason.auth_permanent)
+
+
+
+# ── Provider-specific patterns ──────────────────────────────────────────
+
+# Patterns that indicate billing exhaustion (not transient rate limit)
+_BILLING_PATTERNS = [
+    "insufficient credits",
+    "insufficient_quota",
+    "credit balance",
+    "credits have been exhausted",
+    "top up your credits",
+    "payment required",
+    "billing hard limit",
+    "exceeded your current quota",
+    "account is deactivated",
+    "plan does not include",
+]
+
+# Patterns that indicate rate limiting (transient, will resolve)
+_RATE_LIMIT_PATTERNS = [
+    "rate limit",
+    "rate_limit",
+    "too many requests",
+    "throttled",
+    "requests per minute",
+    "tokens per minute",
+    "requests per day",
+    "try again in",
+    "please retry after",
+    "resource_exhausted",
+    "rate increased too quickly",  # Alibaba/DashScope throttling
+]
+
+# Usage-limit patterns that need disambiguation (could be billing OR rate_limit)
+_USAGE_LIMIT_PATTERNS = [
+    "usage limit",
+    "quota",
+    "limit exceeded",
+    "key limit exceeded",
+]
+
+# Patterns confirming usage limit is transient (not billing)
+_USAGE_LIMIT_TRANSIENT_SIGNALS = [
+    "try again",
+    "retry",
+    "resets at",
+    "reset in",
+    "wait",
+    "requests remaining",
+    "periodic",
+    "window",
+]
+
+# Payload-too-large patterns detected from message text (no status_code attr).
+# Proxies and some backends embed the HTTP status in the error message.
+_PAYLOAD_TOO_LARGE_PATTERNS = [
+    "request entity too large",
+    "payload too large",
+    "error code: 413",
+]
+
+# Context overflow patterns
+_CONTEXT_OVERFLOW_PATTERNS = [
+    "context length",
+    "context size",
+    "maximum context",
+    "token limit",
+    "too many tokens",
+    "reduce the length",
+    "exceeds the limit",
+    "context window",
+    "prompt is too long",
+    "prompt exceeds max length",
+    "max_tokens",
+    "maximum number of tokens",
+    # vLLM / local inference server patterns
+    "exceeds the max_model_len",
+    "max_model_len",
+    "prompt length",             # "engine prompt length X exceeds"
+    "input is too long",
+    "maximum model length",
+    # Ollama patterns
+    "context length exceeded",
+    "truncating input",
+    # llama.cpp / llama-server patterns
+    "slot context",              # "slot context: N tokens, prompt N tokens"
+    "n_ctx_slot",
+    # Chinese error messages (some providers return these)
+    "超过最大长度",
+    "上下文长度",
+]
+
+# Model not found patterns
+_MODEL_NOT_FOUND_PATTERNS = [
+    "is not a valid model",
+    "invalid model",
+    "model not found",
+    "model_not_found",
+    "does not exist",
+    "no such model",
+    "unknown model",
+    "unsupported model",
+]
+
+# Auth patterns (non-status-code signals)
+_AUTH_PATTERNS = [
+    "invalid api key",
+    "invalid_api_key",
+    "authentication",
+    "unauthorized",
+    "forbidden",
+    "invalid token",
+    "token expired",
+    "token revoked",
+    "access denied",
+]
+
+# Anthropic thinking block signature patterns
+_THINKING_SIG_PATTERNS = [
+    "signature",  # Combined with "thinking" check
+]
+
+# Transport error type names
+_TRANSPORT_ERROR_TYPES = frozenset({
+    "ReadTimeout", "ConnectTimeout", "PoolTimeout",
+    "ConnectError", "RemoteProtocolError",
+    "ConnectionError", "ConnectionResetError",
+    "ConnectionAbortedError", "BrokenPipeError",
+    "TimeoutError", "ReadError",
+    "ServerDisconnectedError",
+    # OpenAI SDK errors (not subclasses of Python builtins)
+    "APIConnectionError",
+    "APITimeoutError",
+})
+
+# Server disconnect patterns (no status code, but transport-level)
+_SERVER_DISCONNECT_PATTERNS = [
+    "server disconnected",
+    "peer closed connection",
+    "connection reset by peer",
+    "connection was closed",
+    "network connection lost",
+    "unexpected eof",
+    "incomplete chunked read",
+]
+
+
+# ── Classification pipeline ─────────────────────────────────────────────
+
+def classify_api_error(
+    error: Exception,
+    *,
+    provider: str = "",
+    model: str = "",
+    approx_tokens: int = 0,
+    context_length: int = 200000,
+    num_messages: int = 0,
+) -> ClassifiedError:
+    """Classify an API error into a structured recovery recommendation.
+
+    Priority-ordered pipeline:
+      1. Special-case provider-specific patterns (thinking sigs, tier gates)
+      2. HTTP status code + message-aware refinement
+      3. Error code classification (from body)
+      4. Message pattern matching (billing vs rate_limit vs context vs auth)
+      5. Transport error heuristics
+      6. Server disconnect + large session → context overflow
+      7. Fallback: unknown (retryable with backoff)
+
+    Args:
+        error: The exception from the API call.
+        provider: Current provider name (e.g. "openrouter", "anthropic").
+        model: Current model slug.
+        approx_tokens: Approximate token count of the current context.
+        context_length: Maximum context length for the current model.
+
+    Returns:
+        ClassifiedError with reason and recovery action hints.
+    """
+    status_code = _extract_status_code(error)
+    error_type = type(error).__name__
+    body = _extract_error_body(error)
+    error_code = _extract_error_code(body)
+
+    # Build a comprehensive error message string for pattern matching.
+    # str(error) alone may not include the body message (e.g. OpenAI SDK's
+    # APIStatusError.__str__ returns the first arg, not the body).  Append
+    # the body message so patterns like "try again" in 402 disambiguation
+    # are detected even when only present in the structured body.
+    #
+    # Also extract metadata.raw — OpenRouter wraps upstream provider errors
+    # inside {"error": {"message": "Provider returned error", "metadata":
+    # {"raw": "<actual error JSON>"}}} and the real error message (e.g.
+    # "context length exceeded") is only in the inner JSON.
+    _raw_msg = str(error).lower()
+    _body_msg = ""
+    _metadata_msg = ""
+    if isinstance(body, dict):
+        _err_obj = body.get("error", {})
+        if isinstance(_err_obj, dict):
+            _body_msg = (_err_obj.get("message") or "").lower()
+            # Parse metadata.raw for wrapped provider errors
+            _metadata = _err_obj.get("metadata", {})
+            if isinstance(_metadata, dict):
+                _raw_json = _metadata.get("raw") or ""
+                if isinstance(_raw_json, str) and _raw_json.strip():
+                    try:
+                        import json
+                        _inner = json.loads(_raw_json)
+                        if isinstance(_inner, dict):
+                            _inner_err = _inner.get("error", {})
+                            if isinstance(_inner_err, dict):
+                                _metadata_msg = (_inner_err.get("message") or "").lower()
+                    except (json.JSONDecodeError, TypeError):
+                        pass
+        if not _body_msg:
+            _body_msg = (body.get("message") or "").lower()
+    # Combine all message sources for pattern matching
+    parts = [_raw_msg]
+    if _body_msg and _body_msg not in _raw_msg:
+        parts.append(_body_msg)
+    if _metadata_msg and _metadata_msg not in _raw_msg and _metadata_msg not in _body_msg:
+        parts.append(_metadata_msg)
+    error_msg = " ".join(parts)
+    provider_lower = (provider or "").strip().lower()
+    model_lower = (model or "").strip().lower()
+
+    def _result(reason: FailoverReason, **overrides) -> ClassifiedError:
+        defaults = {
+            "reason": reason,
+            "status_code": status_code,
+            "provider": provider,
+            "model": model,
+            "message": _extract_message(error, body),
+        }
+        defaults.update(overrides)
+        return ClassifiedError(**defaults)
+
+    # ── 1. Provider-specific patterns (highest priority) ────────────
+
+    # Anthropic thinking block signature invalid (400).
+    # Don't gate on provider — OpenRouter proxies Anthropic errors, so the
+    # provider may be "openrouter" even though the error is Anthropic-specific.
+    # The message pattern ("signature" + "thinking") is unique enough.
+    if (
+        status_code == 400
+        and "signature" in error_msg
+        and "thinking" in error_msg
+    ):
+        return _result(
+            FailoverReason.thinking_signature,
+            retryable=True,
+            should_compress=False,
+        )
+
+    # Anthropic long-context tier gate (429 "extra usage" + "long context")
+    if (
+        status_code == 429
+        and "extra usage" in error_msg
+        and "long context" in error_msg
+    ):
+        return _result(
+            FailoverReason.long_context_tier,
+            retryable=True,
+            should_compress=True,
+        )
+
+    # ── 2. HTTP status code classification ──────────────────────────
+
+    if status_code is not None:
+        classified = _classify_by_status(
+            status_code, error_msg, error_code, body,
+            provider=provider_lower, model=model_lower,
+            approx_tokens=approx_tokens, context_length=context_length,
+            num_messages=num_messages,
+            result_fn=_result,
+        )
+        if classified is not None:
+            return classified
+
+    # ── 3. Error code classification ────────────────────────────────
+
+    if error_code:
+        classified = _classify_by_error_code(error_code, error_msg, _result)
+        if classified is not None:
+            return classified
+
+    # ── 4. Message pattern matching (no status code) ────────────────
+
+    classified = _classify_by_message(
+        error_msg, error_type,
+        approx_tokens=approx_tokens,
+        context_length=context_length,
+        result_fn=_result,
+    )
+    if classified is not None:
+        return classified
+
+    # ── 5. Server disconnect + large session → context overflow ─────
+    # Must come BEFORE generic transport error catch — a disconnect on
+    # a large session is more likely context overflow than a transient
+    # transport hiccup.  Without this ordering, RemoteProtocolError
+    # always maps to timeout regardless of session size.
+
+    is_disconnect = any(p in error_msg for p in _SERVER_DISCONNECT_PATTERNS)
+    if is_disconnect and not status_code:
+        is_large = approx_tokens > context_length * 0.6 or approx_tokens > 120000 or num_messages > 200
+        if is_large:
+            return _result(
+                FailoverReason.context_overflow,
+                retryable=True,
+                should_compress=True,
+            )
+        return _result(FailoverReason.timeout, retryable=True)
+
+    # ── 6. Transport / timeout heuristics ───────────────────────────
+
+    if error_type in _TRANSPORT_ERROR_TYPES or isinstance(error, (TimeoutError, ConnectionError, OSError)):
+        return _result(FailoverReason.timeout, retryable=True)
+
+    # ── 7. Fallback: unknown ────────────────────────────────────────
+
+    return _result(FailoverReason.unknown, retryable=True)
+
+
+# ── Status code classification ──────────────────────────────────────────
+
+def _classify_by_status(
+    status_code: int,
+    error_msg: str,
+    error_code: str,
+    body: dict,
+    *,
+    provider: str,
+    model: str,
+    approx_tokens: int,
+    context_length: int,
+    num_messages: int = 0,
+    result_fn,
+) -> Optional[ClassifiedError]:
+    """Classify based on HTTP status code with message-aware refinement."""
+
+    if status_code == 401:
+        # Not retryable on its own — credential pool rotation and
+        # provider-specific refresh (Codex, Anthropic, Nous) run before
+        # the retryability check in run_agent.py.  If those succeed, the
+        # loop `continue`s.  If they fail, retryable=False ensures we
+        # hit the client-error abort path (which tries fallback first).
+        return result_fn(
+            FailoverReason.auth,
+            retryable=False,
+            should_rotate_credential=True,
+            should_fallback=True,
+        )
+
+    if status_code == 403:
+        # OpenRouter 403 "key limit exceeded" is actually billing
+        if "key limit exceeded" in error_msg or "spending limit" in error_msg:
+            return result_fn(
+                FailoverReason.billing,
+                retryable=False,
+                should_rotate_credential=True,
+                should_fallback=True,
+            )
+        return result_fn(
+            FailoverReason.auth,
+            retryable=False,
+            should_fallback=True,
+        )
+
+    if status_code == 402:
+        return _classify_402(error_msg, result_fn)
+
+    if status_code == 404:
+        if any(p in error_msg for p in _MODEL_NOT_FOUND_PATTERNS):
+            return result_fn(
+                FailoverReason.model_not_found,
+                retryable=False,
+                should_fallback=True,
+            )
+        # Generic 404 — could be model or endpoint
+        return result_fn(
+            FailoverReason.model_not_found,
+            retryable=False,
+            should_fallback=True,
+        )
+
+    if status_code == 413:
+        return result_fn(
+            FailoverReason.payload_too_large,
+            retryable=True,
+            should_compress=True,
+        )
+
+    if status_code == 429:
+        # Already checked long_context_tier above; this is a normal rate limit
+        return result_fn(
+            FailoverReason.rate_limit,
+            retryable=True,
+            should_rotate_credential=True,
+            should_fallback=True,
+        )
+
+    if status_code == 400:
+        return _classify_400(
+            error_msg, error_code, body,
+            provider=provider, model=model,
+            approx_tokens=approx_tokens,
+            context_length=context_length,
+            num_messages=num_messages,
+            result_fn=result_fn,
+        )
+
+    if status_code in (500, 502):
+        return result_fn(FailoverReason.server_error, retryable=True)
+
+    if status_code in (503, 529):
+        return result_fn(FailoverReason.overloaded, retryable=True)
+
+    # Other 4xx — non-retryable
+    if 400 <= status_code < 500:
+        return result_fn(
+            FailoverReason.format_error,
+            retryable=False,
+            should_fallback=True,
+        )
+
+    # Other 5xx — retryable
+    if 500 <= status_code < 600:
+        return result_fn(FailoverReason.server_error, retryable=True)
+
+    return None
+
+
+def _classify_402(error_msg: str, result_fn) -> ClassifiedError:
+    """Disambiguate 402: billing exhaustion vs transient usage limit.
+
+    The key insight from OpenClaw: some 402s are transient rate limits
+    disguised as payment errors.  "Usage limit, try again in 5 minutes"
+    is NOT a billing problem — it's a periodic quota that resets.
+    """
+    # Check for transient usage-limit signals first
+    has_usage_limit = any(p in error_msg for p in _USAGE_LIMIT_PATTERNS)
+    has_transient_signal = any(p in error_msg for p in _USAGE_LIMIT_TRANSIENT_SIGNALS)
+
+    if has_usage_limit and has_transient_signal:
+        # Transient quota — treat as rate limit, not billing
+        return result_fn(
+            FailoverReason.rate_limit,
+            retryable=True,
+            should_rotate_credential=True,
+            should_fallback=True,
+        )
+
+    # Confirmed billing exhaustion
+    return result_fn(
+        FailoverReason.billing,
+        retryable=False,
+        should_rotate_credential=True,
+        should_fallback=True,
+    )
+
+
+def _classify_400(
+    error_msg: str,
+    error_code: str,
+    body: dict,
+    *,
+    provider: str,
+    model: str,
+    approx_tokens: int,
+    context_length: int,
+    num_messages: int = 0,
+    result_fn,
+) -> ClassifiedError:
+    """Classify 400 Bad Request — context overflow, format error, or generic."""
+
+    # Context overflow from 400
+    if any(p in error_msg for p in _CONTEXT_OVERFLOW_PATTERNS):
+        return result_fn(
+            FailoverReason.context_overflow,
+            retryable=True,
+            should_compress=True,
+        )
+
+    # Some providers return model-not-found as 400 instead of 404 (e.g. OpenRouter).
+    if any(p in error_msg for p in _MODEL_NOT_FOUND_PATTERNS):
+        return result_fn(
+            FailoverReason.model_not_found,
+            retryable=False,
+            should_fallback=True,
+        )
+
+    # Some providers return rate limit / billing errors as 400 instead of 429/402.
+    # Check these patterns before falling through to format_error.
+    if any(p in error_msg for p in _RATE_LIMIT_PATTERNS):
+        return result_fn(
+            FailoverReason.rate_limit,
+            retryable=True,
+            should_rotate_credential=True,
+            should_fallback=True,
+        )
+    if any(p in error_msg for p in _BILLING_PATTERNS):
+        return result_fn(
+            FailoverReason.billing,
+            retryable=False,
+            should_rotate_credential=True,
+            should_fallback=True,
+        )
+
+    # Generic 400 + large session → probable context overflow
+    # Anthropic sometimes returns a bare "Error" message when context is too large
+    err_body_msg = ""
+    if isinstance(body, dict):
+        err_obj = body.get("error", {})
+        if isinstance(err_obj, dict):
+            err_body_msg = (err_obj.get("message") or "").strip().lower()
+        # Responses API (and some providers) use flat body: {"message": "..."}
+        if not err_body_msg:
+            err_body_msg = (body.get("message") or "").strip().lower()
+    is_generic = len(err_body_msg) < 30 or err_body_msg in ("error", "")
+    is_large = approx_tokens > context_length * 0.4 or approx_tokens > 80000 or num_messages > 80
+
+    if is_generic and is_large:
+        return result_fn(
+            FailoverReason.context_overflow,
+            retryable=True,
+            should_compress=True,
+        )
+
+    # Non-retryable format error
+    return result_fn(
+        FailoverReason.format_error,
+        retryable=False,
+        should_fallback=True,
+    )
+
+
+# ── Error code classification ───────────────────────────────────────────
+
+def _classify_by_error_code(
+    error_code: str, error_msg: str, result_fn,
+) -> Optional[ClassifiedError]:
+    """Classify by structured error codes from the response body."""
+    code_lower = error_code.lower()
+
+    if code_lower in ("resource_exhausted", "throttled", "rate_limit_exceeded"):
+        return result_fn(
+            FailoverReason.rate_limit,
+            retryable=True,
+            should_rotate_credential=True,
+        )
+
+    if code_lower in ("insufficient_quota", "billing_not_active", "payment_required"):
+        return result_fn(
+            FailoverReason.billing,
+            retryable=False,
+            should_rotate_credential=True,
+            should_fallback=True,
+        )
+
+    if code_lower in ("model_not_found", "model_not_available", "invalid_model"):
+        return result_fn(
+            FailoverReason.model_not_found,
+            retryable=False,
+            should_fallback=True,
+        )
+
+    if code_lower in ("context_length_exceeded", "max_tokens_exceeded"):
+        return result_fn(
+            FailoverReason.context_overflow,
+            retryable=True,
+            should_compress=True,
+        )
+
+    return None
+
+
+# ── Message pattern classification ──────────────────────────────────────
+
+def _classify_by_message(
+    error_msg: str,
+    error_type: str,
+    *,
+    approx_tokens: int,
+    context_length: int,
+    result_fn,
+) -> Optional[ClassifiedError]:
+    """Classify based on error message patterns when no status code is available."""
+
+    # Payload-too-large patterns (from message text when no status_code)
+    if any(p in error_msg for p in _PAYLOAD_TOO_LARGE_PATTERNS):
+        return result_fn(
+            FailoverReason.payload_too_large,
+            retryable=True,
+            should_compress=True,
+        )
+
+    # Usage-limit patterns need the same disambiguation as 402: some providers
+    # surface "usage limit" errors without an HTTP status code.  A transient
+    # signal ("try again", "resets at", …) means it's a periodic quota, not
+    # billing exhaustion.
+    has_usage_limit = any(p in error_msg for p in _USAGE_LIMIT_PATTERNS)
+    if has_usage_limit:
+        has_transient_signal = any(p in error_msg for p in _USAGE_LIMIT_TRANSIENT_SIGNALS)
+        if has_transient_signal:
+            return result_fn(
+                FailoverReason.rate_limit,
+                retryable=True,
+                should_rotate_credential=True,
+                should_fallback=True,
+            )
+        return result_fn(
+            FailoverReason.billing,
+            retryable=False,
+            should_rotate_credential=True,
+            should_fallback=True,
+        )
+
+    # Billing patterns
+    if any(p in error_msg for p in _BILLING_PATTERNS):
+        return result_fn(
+            FailoverReason.billing,
+            retryable=False,
+            should_rotate_credential=True,
+            should_fallback=True,
+        )
+
+    # Rate limit patterns
+    if any(p in error_msg for p in _RATE_LIMIT_PATTERNS):
+        return result_fn(
+            FailoverReason.rate_limit,
+            retryable=True,
+            should_rotate_credential=True,
+            should_fallback=True,
+        )
+
+    # Context overflow patterns
+    if any(p in error_msg for p in _CONTEXT_OVERFLOW_PATTERNS):
+        return result_fn(
+            FailoverReason.context_overflow,
+            retryable=True,
+            should_compress=True,
+        )
+
+    # Auth patterns
+    # Auth errors should NOT be retried directly — the credential is invalid and
+    # retrying with the same key will always fail.  Set retryable=False so the
+    # caller triggers credential rotation (should_rotate_credential=True) or
+    # provider fallback rather than an immediate retry loop.
+    if any(p in error_msg for p in _AUTH_PATTERNS):
+        return result_fn(
+            FailoverReason.auth,
+            retryable=False,
+            should_rotate_credential=True,
+            should_fallback=True,
+        )
+
+    # Model not found patterns
+    if any(p in error_msg for p in _MODEL_NOT_FOUND_PATTERNS):
+        return result_fn(
+            FailoverReason.model_not_found,
+            retryable=False,
+            should_fallback=True,
+        )
+
+    return None
+
+
+# ── Helpers ─────────────────────────────────────────────────────────────
+
+def _extract_status_code(error: Exception) -> Optional[int]:
+    """Walk the error and its cause chain to find an HTTP status code."""
+    current = error
+    for _ in range(5):  # Max depth to prevent infinite loops
+        code = getattr(current, "status_code", None)
+        if isinstance(code, int):
+            return code
+        # Some SDKs use .status instead of .status_code
+        code = getattr(current, "status", None)
+        if isinstance(code, int) and 100 <= code < 600:
+            return code
+        # Walk cause chain
+        cause = getattr(current, "__cause__", None) or getattr(current, "__context__", None)
+        if cause is None or cause is current:
+            break
+        current = cause
+    return None
+
+
+def _extract_error_body(error: Exception) -> dict:
+    """Extract the structured error body from an SDK exception."""
+    body = getattr(error, "body", None)
+    if isinstance(body, dict):
+        return body
+    # Some errors have .response.json()
+    response = getattr(error, "response", None)
+    if response is not None:
+        try:
+            json_body = response.json()
+            if isinstance(json_body, dict):
+                return json_body
+        except Exception:
+            pass
+    return {}
+
+
+def _extract_error_code(body: dict) -> str:
+    """Extract an error code string from the response body."""
+    if not body:
+        return ""
+    error_obj = body.get("error", {})
+    if isinstance(error_obj, dict):
+        code = error_obj.get("code") or error_obj.get("type") or ""
+        if isinstance(code, str) and code.strip():
+            return code.strip()
+    # Top-level code
+    code = body.get("code") or body.get("error_code") or ""
+    if isinstance(code, (str, int)):
+        return str(code).strip()
+    return ""
+
+
+def _extract_message(error: Exception, body: dict) -> str:
+    """Extract the most informative error message."""
+    # Try structured body first
+    if body:
+        error_obj = body.get("error", {})
+        if isinstance(error_obj, dict):
+            msg = error_obj.get("message", "")
+            if isinstance(msg, str) and msg.strip():
+                return msg.strip()[:500]
+        msg = body.get("message", "")
+        if isinstance(msg, str) and msg.strip():
+            return msg.strip()[:500]
+    # Fallback to str(error)
+    return str(error)[:500]

agent/evolution/domain_distiller.py

@@ -1,45 +0,0 @@
-"""Phase 3: Deep Knowledge Distillation from Google.
-
-Performs deep dives into technical domains and distills them into
-Timmy's Sovereign Knowledge Graph.
-"""
-
-import logging
-import json
-from typing import List, Dict, Any
-from agent.gemini_adapter import GeminiAdapter
-from agent.symbolic_memory import SymbolicMemory
-
-logger = logging.getLogger(__name__)
-
-class DomainDistiller:
-    def __init__(self):
-        self.adapter = GeminiAdapter()
-        self.symbolic = SymbolicMemory()
-
-    def distill_domain(self, domain: str):
-        """Crawls and distills an entire technical domain."""
-        logger.info(f"Distilling domain: {domain}")
-        
-        prompt = f"""
-Please perform a deep knowledge distillation of the following domain: {domain}
-
-Use Google Search to find foundational papers, recent developments, and key entities.
-Synthesize this into a structured 'Domain Map' consisting of high-fidelity knowledge triples.
-Focus on the structural relationships that define the domain.
-
-Format: [{{"s": "subject", "p": "predicate", "o": "object"}}]
-"""
-        result = self.adapter.generate(
-            model="gemini-3.1-pro-preview",
-            prompt=prompt,
-            system_instruction=f"You are Timmy's Domain Distiller. Your goal is to map the entire {domain} domain into a structured Knowledge Graph.",
-            grounding=True,
-            thinking=True,
-            response_mime_type="application/json"
-        )
-        
-        triples = json.loads(result["text"])
-        count = self.symbolic.ingest_text(json.dumps(triples))
-        logger.info(f"Distilled {count} new triples for domain: {domain}")
-        return count

agent/evolution/self_correction_generator.py

@@ -1,60 +0,0 @@
-"""Phase 1: Synthetic Data Generation for Self-Correction.
-
-Generates reasoning traces where Timmy makes a subtle error and then
-identifies and corrects it using the Conscience Validator.
-"""
-
-import logging
-import json
-from typing import List, Dict, Any
-from agent.gemini_adapter import GeminiAdapter
-from tools.gitea_client import GiteaClient
-
-logger = logging.getLogger(__name__)
-
-class SelfCorrectionGenerator:
-    def __init__(self):
-        self.adapter = GeminiAdapter()
-        self.gitea = GiteaClient()
-
-    def generate_trace(self, task: str) -> Dict[str, Any]:
-        """Generates a single self-correction reasoning trace."""
-        prompt = f"""
-Task: {task}
-
-Please simulate a multi-step reasoning trace for this task.
-Intentionally include one subtle error in the reasoning (e.g., a logical flaw, a misinterpretation of a rule, or a factual error).
-Then, show how Timmy identifies the error using his Conscience Validator and provides a corrected reasoning trace.
-
-Format the output as JSON:
-{{
-  "task": "{task}",
-  "initial_trace": "...",
-  "error_identified": "...",
-  "correction_trace": "...",
-  "lessons_learned": "..."
-}}
-"""
-        result = self.adapter.generate(
-            model="gemini-3.1-pro-preview",
-            prompt=prompt,
-            system_instruction="You are Timmy's Synthetic Data Engine. Generate high-fidelity self-correction traces.",
-            response_mime_type="application/json",
-            thinking=True
-        )
-        
-        trace = json.loads(result["text"])
-        return trace
-
-    def generate_and_save(self, task: str, count: int = 1):
-        """Generates multiple traces and saves them to Gitea."""
-        repo = "Timmy_Foundation/timmy-config"
-        for i in range(count):
-            trace = self.generate_trace(task)
-            filename = f"memories/synthetic_data/self_correction/{task.lower().replace(' ', '_')}_{i}.json"
-            
-            content = json.dumps(trace, indent=2)
-            content_b64 = base64.b64encode(content.encode()).decode()
-            
-            self.gitea.create_file(repo, filename, content_b64, f"Add synthetic self-correction trace for {task}")
-            logger.info(f"Saved synthetic trace to {filename}")

agent/evolution/world_modeler.py

@@ -1,42 +0,0 @@
-"""Phase 2: Multi-Modal World Modeling.
-
-Ingests multi-modal data (vision/audio) to build a spatial and temporal
-understanding of Timmy's environment.
-"""
-
-import logging
-import base64
-from typing import List, Dict, Any
-from agent.gemini_adapter import GeminiAdapter
-from agent.symbolic_memory import SymbolicMemory
-
-logger = logging.getLogger(__name__)
-
-class WorldModeler:
-    def __init__(self):
-        self.adapter = GeminiAdapter()
-        self.symbolic = SymbolicMemory()
-
-    def analyze_environment(self, image_data: str, mime_type: str = "image/jpeg"):
-        """Analyzes an image of the environment and updates the world model."""
-        # In a real scenario, we'd use Gemini's multi-modal capabilities
-        # For now, we'll simulate the vision-to-symbolic extraction
-        prompt = f"""
-Analyze the following image of Timmy's environment.
-Identify all key objects, their spatial relationships, and any temporal changes.
-Extract this into a set of symbolic triples for the Knowledge Graph.
-
-Format: [{{"s": "subject", "p": "predicate", "o": "object"}}]
-"""
-        # Simulate multi-modal call (Gemini 3.1 Pro Vision)
-        result = self.adapter.generate(
-            model="gemini-3.1-pro-preview",
-            prompt=prompt,
-            system_instruction="You are Timmy's World Modeler. Build a high-fidelity spatial/temporal map of the environment.",
-            response_mime_type="application/json"
-        )
-        
-        triples = json.loads(result["text"])
-        self.symbolic.ingest_text(json.dumps(triples))
-        logger.info(f"Updated world model with {len(triples)} new spatial triples.")
-        return triples

agent/fallback_router.py

@@ -1,404 +0,0 @@
-"""Automatic fallback router for handling provider quota and rate limit errors.
-
-This module provides intelligent fallback detection and routing when the primary
-provider (e.g., Anthropic) encounters quota limitations or rate limits.
-
-Features:
-- Detects quota/rate limit errors from different providers
-- Automatic fallback to kimi-coding when Anthropic quota is exceeded
-- Configurable fallback chains with default anthropic -> kimi-coding
-- Logging and monitoring of fallback events
-
-Usage:
-    from agent.fallback_router import (
-        is_quota_error,
-        get_default_fallback_chain,
-        should_auto_fallback,
-    )
-    
-    if is_quota_error(error, provider="anthropic"):
-        if should_auto_fallback(provider="anthropic"):
-            fallback_chain = get_default_fallback_chain("anthropic")
-"""
-
-import logging
-import os
-from typing import Dict, List, Optional, Any, Tuple
-
-logger = logging.getLogger(__name__)
-
-# Default fallback chains per provider
-# Each chain is a list of fallback configurations tried in order
-DEFAULT_FALLBACK_CHAINS: Dict[str, List[Dict[str, Any]]] = {
-    "anthropic": [
-        {"provider": "kimi-coding", "model": "kimi-k2.5"},
-        {"provider": "openrouter", "model": "anthropic/claude-sonnet-4"},
-    ],
-    "openrouter": [
-        {"provider": "kimi-coding", "model": "kimi-k2.5"},
-        {"provider": "zai", "model": "glm-5"},
-    ],
-    "kimi-coding": [
-        {"provider": "openrouter", "model": "anthropic/claude-sonnet-4"},
-        {"provider": "zai", "model": "glm-5"},
-    ],
-    "zai": [
-        {"provider": "openrouter", "model": "anthropic/claude-sonnet-4"},
-        {"provider": "kimi-coding", "model": "kimi-k2.5"},
-    ],
-}
-
-# Quota/rate limit error patterns by provider
-# These are matched (case-insensitive) against error messages
-QUOTA_ERROR_PATTERNS: Dict[str, List[str]] = {
-    "anthropic": [
-        "rate limit",
-        "ratelimit",
-        "quota exceeded",
-        "quota exceeded",
-        "insufficient quota",
-        "429",
-        "403",
-        "too many requests",
-        "capacity exceeded",
-        "over capacity",
-        "temporarily unavailable",
-        "server overloaded",
-        "resource exhausted",
-        "billing threshold",
-        "credit balance",
-        "payment required",
-        "402",
-    ],
-    "openrouter": [
-        "rate limit",
-        "ratelimit",
-        "quota exceeded",
-        "insufficient credits",
-        "429",
-        "402",
-        "no endpoints available",
-        "all providers failed",
-        "over capacity",
-    ],
-    "kimi-coding": [
-        "rate limit",
-        "ratelimit",
-        "quota exceeded",
-        "429",
-        "insufficient balance",
-    ],
-    "zai": [
-        "rate limit",
-        "ratelimit",
-        "quota exceeded",
-        "429",
-        "insufficient quota",
-    ],
-}
-
-# HTTP status codes indicating quota/rate limit issues
-QUOTA_STATUS_CODES = {429, 402, 403}
-
-
-def is_quota_error(error: Exception, provider: Optional[str] = None) -> bool:
-    """Detect if an error is quota/rate limit related.
-    
-    Args:
-        error: The exception to check
-        provider: Optional provider name to check provider-specific patterns
-        
-    Returns:
-        True if the error appears to be quota/rate limit related
-    """
-    if error is None:
-        return False
-    
-    error_str = str(error).lower()
-    error_type = type(error).__name__.lower()
-    
-    # Check for common rate limit exception types
-    if any(term in error_type for term in [
-        "ratelimit", "rate_limit", "quota", "toomanyrequests",
-        "insufficient_quota", "billing", "payment"
-    ]):
-        return True
-    
-    # Check HTTP status code if available
-    status_code = getattr(error, "status_code", None)
-    if status_code is None:
-        # Try common attribute names
-        for attr in ["code", "http_status", "response_code", "status"]:
-            if hasattr(error, attr):
-                try:
-                    status_code = int(getattr(error, attr))
-                    break
-                except (TypeError, ValueError):
-                    continue
-    
-    if status_code in QUOTA_STATUS_CODES:
-        return True
-    
-    # Check provider-specific patterns
-    providers_to_check = [provider] if provider else QUOTA_ERROR_PATTERNS.keys()
-    
-    for prov in providers_to_check:
-        patterns = QUOTA_ERROR_PATTERNS.get(prov, [])
-        for pattern in patterns:
-            if pattern.lower() in error_str:
-                logger.debug(
-                    "Detected %s quota error pattern '%s' in: %s",
-                    prov, pattern, error
-                )
-                return True
-    
-    # Check generic quota patterns
-    generic_patterns = [
-        "rate limit exceeded",
-        "quota exceeded",
-        "too many requests",
-        "capacity exceeded",
-        "temporarily unavailable",
-        "try again later",
-        "resource exhausted",
-        "billing",
-        "payment required",
-        "insufficient credits",
-        "insufficient quota",
-    ]
-    
-    for pattern in generic_patterns:
-        if pattern in error_str:
-            return True
-    
-    return False
-
-
-def get_default_fallback_chain(
-    primary_provider: str,
-    exclude_provider: Optional[str] = None,
-) -> List[Dict[str, Any]]:
-    """Get the default fallback chain for a primary provider.
-    
-    Args:
-        primary_provider: The primary provider name
-        exclude_provider: Optional provider to exclude from the chain
-        
-    Returns:
-        List of fallback configurations
-    """
-    chain = DEFAULT_FALLBACK_CHAINS.get(primary_provider, [])
-    
-    # Filter out excluded provider if specified
-    if exclude_provider:
-        chain = [
-            fb for fb in chain
-            if fb.get("provider") != exclude_provider
-        ]
-    
-    return list(chain)
-
-
-def should_auto_fallback(
-    provider: str,
-    error: Optional[Exception] = None,
-    auto_fallback_enabled: Optional[bool] = None,
-) -> bool:
-    """Determine if automatic fallback should be attempted.
-    
-    Args:
-        provider: The current provider name
-        error: Optional error to check for quota issues
-        auto_fallback_enabled: Optional override for auto-fallback setting
-        
-    Returns:
-        True if automatic fallback should be attempted
-    """
-    # Check environment variable override
-    if auto_fallback_enabled is None:
-        env_setting = os.getenv("HERMES_AUTO_FALLBACK", "true").lower()
-        auto_fallback_enabled = env_setting in ("true", "1", "yes", "on")
-    
-    if not auto_fallback_enabled:
-        return False
-    
-    # Check if provider has a configured fallback chain
-    if provider not in DEFAULT_FALLBACK_CHAINS:
-        # Still allow fallback if it's a quota error with generic handling
-        if error and is_quota_error(error):
-            logger.debug(
-                "Provider %s has no fallback chain but quota error detected",
-                provider
-            )
-            return True
-        return False
-    
-    # If there's an error, only fallback on quota/rate limit errors
-    if error is not None:
-        return is_quota_error(error, provider)
-    
-    # No error but fallback chain exists - allow eager fallback for
-    # providers known to have quota issues
-    return provider in ("anthropic",)
-
-
-def log_fallback_event(
-    from_provider: str,
-    to_provider: str,
-    to_model: str,
-    reason: str,
-    error: Optional[Exception] = None,
-) -> None:
-    """Log a fallback event for monitoring.
-    
-    Args:
-        from_provider: The provider we're falling back from
-        to_provider: The provider we're falling back to
-        to_model: The model we're falling back to
-        reason: The reason for the fallback
-        error: Optional error that triggered the fallback
-    """
-    log_data = {
-        "event": "provider_fallback",
-        "from_provider": from_provider,
-        "to_provider": to_provider,
-        "to_model": to_model,
-        "reason": reason,
-    }
-    
-    if error:
-        log_data["error_type"] = type(error).__name__
-        log_data["error_message"] = str(error)[:200]
-    
-    logger.info("Provider fallback: %s -> %s (%s) | Reason: %s", 
-                from_provider, to_provider, to_model, reason)
-    
-    # Also log structured data for monitoring
-    logger.debug("Fallback event data: %s", log_data)
-
-
-def resolve_fallback_with_credentials(
-    fallback_config: Dict[str, Any],
-) -> Tuple[Optional[Any], Optional[str]]:
-    """Resolve a fallback configuration to a client and model.
-    
-    Args:
-        fallback_config: Fallback configuration dict with provider and model
-        
-    Returns:
-        Tuple of (client, model) or (None, None) if credentials not available
-    """
-    from agent.auxiliary_client import resolve_provider_client
-    
-    provider = fallback_config.get("provider")
-    model = fallback_config.get("model")
-    
-    if not provider or not model:
-        return None, None
-    
-    try:
-        client, resolved_model = resolve_provider_client(
-            provider,
-            model=model,
-            raw_codex=True,
-        )
-        return client, resolved_model or model
-    except Exception as exc:
-        logger.debug(
-            "Failed to resolve fallback provider %s: %s",
-            provider, exc
-        )
-        return None, None
-
-
-def get_auto_fallback_chain(
-    primary_provider: str,
-    user_fallback_chain: Optional[List[Dict[str, Any]]] = None,
-) -> List[Dict[str, Any]]:
-    """Get the effective fallback chain for automatic fallback.
-    
-    Combines user-provided fallback chain with default automatic fallback chain.
-    
-    Args:
-        primary_provider: The primary provider name
-        user_fallback_chain: Optional user-provided fallback chain
-        
-    Returns:
-        The effective fallback chain to use
-    """
-    # Use user-provided chain if available
-    if user_fallback_chain:
-        return user_fallback_chain
-    
-    # Otherwise use default chain for the provider
-    return get_default_fallback_chain(primary_provider)
-
-
-def is_fallback_available(
-    fallback_config: Dict[str, Any],
-) -> bool:
-    """Check if a fallback configuration has available credentials.
-    
-    Args:
-        fallback_config: Fallback configuration dict
-        
-    Returns:
-        True if credentials are available for the fallback provider
-    """
-    provider = fallback_config.get("provider")
-    if not provider:
-        return False
-    
-    # Check environment variables for API keys
-    env_vars = {
-        "anthropic": ["ANTHROPIC_API_KEY", "ANTHROPIC_TOKEN"],
-        "kimi-coding": ["KIMI_API_KEY", "KIMI_API_TOKEN"],
-        "zai": ["ZAI_API_KEY", "Z_AI_API_KEY"],
-        "openrouter": ["OPENROUTER_API_KEY"],
-        "minimax": ["MINIMAX_API_KEY"],
-        "minimax-cn": ["MINIMAX_CN_API_KEY"],
-        "deepseek": ["DEEPSEEK_API_KEY"],
-        "alibaba": ["DASHSCOPE_API_KEY", "ALIBABA_API_KEY"],
-        "nous": ["NOUS_AGENT_KEY", "NOUS_ACCESS_TOKEN"],
-    }
-    
-    keys_to_check = env_vars.get(provider, [f"{provider.upper()}_API_KEY"])
-    
-    for key in keys_to_check:
-        if os.getenv(key):
-            return True
-    
-    # Check auth.json for OAuth providers
-    if provider in ("nous", "openai-codex"):
-        try:
-            from hermes_cli.config import get_hermes_home
-            auth_path = get_hermes_home() / "auth.json"
-            if auth_path.exists():
-                import json
-                data = json.loads(auth_path.read_text())
-                if data.get("active_provider") == provider:
-                    return True
-                # Check for provider in providers dict
-                if data.get("providers", {}).get(provider):
-                    return True
-        except Exception:
-            pass
-    
-    return False
-
-
-def filter_available_fallbacks(
-    fallback_chain: List[Dict[str, Any]],
-) -> List[Dict[str, Any]]:
-    """Filter a fallback chain to only include providers with credentials.
-    
-    Args:
-        fallback_chain: List of fallback configurations
-        
-    Returns:
-        Filtered list with only available fallbacks
-    """
-    return [
-        fb for fb in fallback_chain
-        if is_fallback_available(fb)
-    ]

agent/gemini_adapter.py

@@ -1,90 +0,0 @@
-"""Native Gemini 3 Series adapter for Hermes Agent.
-
-Leverages the google-genai SDK to provide sovereign access to Gemini's
-unique capabilities: Thinking (Reasoning) tokens, Search Grounding,
-and Maps Grounding.
-"""
-
-import logging
-import os
-from typing import Any, Dict, List, Optional, Union
-
-try:
-    from google import genai
-    from google.genai import types
-except ImportError:
-    genai = None  # type: ignore
-    types = None  # type: ignore
-
-logger = logging.getLogger(__name__)
-
-class GeminiAdapter:
-    def __init__(self, api_key: Optional[str] = None):
-        self.api_key = api_key or os.environ.get("GEMINI_API_KEY")
-        if not self.api_key:
-            logger.warning("GEMINI_API_KEY not found in environment.")
-        
-        if genai:
-            self.client = genai.Client(api_key=self.api_key)
-        else:
-            self.client = None
-
-    def generate(
-        self,
-        model: str,
-        prompt: str,
-        system_instruction: Optional[str] = None,
-        thinking: bool = False,
-        thinking_budget: int = 16000,
-        grounding: bool = False,
-        **kwargs
-    ) -> Dict[str, Any]:
-        if not self.client:
-            raise ImportError("google-genai SDK not installed. Run 'pip install google-genai'.")
-
-        config = {}
-        if system_instruction:
-            config["system_instruction"] = system_instruction
-        
-        if thinking:
-            # Gemini 3 series thinking config
-            config["thinking_config"] = {"include_thoughts": True}
-            # max_output_tokens includes thinking tokens
-            kwargs["max_output_tokens"] = kwargs.get("max_output_tokens", 32000) + thinking_budget
-
-        tools = []
-        if grounding:
-            tools.append({"google_search": {}})
-        
-        if tools:
-            config["tools"] = tools
-
-        response = self.client.models.generate_content(
-            model=model,
-            contents=prompt,
-            config=types.GenerateContentConfig(**config, **kwargs)
-        )
-
-        result = {
-            "text": response.text,
-            "usage": {
-                "prompt_tokens": response.usage_metadata.prompt_token_count,
-                "candidates_tokens": response.usage_metadata.candidates_token_count,
-                "total_tokens": response.usage_metadata.total_token_count,
-            }
-        }
-
-        # Extract thoughts if present
-        thoughts = []
-        for part in response.candidates[0].content.parts:
-            if hasattr(part, 'thought') and part.thought:
-                thoughts.append(part.thought)
-        
-        if thoughts:
-            result["thoughts"] = "\n".join(thoughts)
-
-        # Extract grounding metadata
-        if response.candidates[0].grounding_metadata:
-            result["grounding"] = response.candidates[0].grounding_metadata
-
-        return result

agent/insights.py

@@ -27,7 +27,6 @@ from agent.usage_pricing import (
     DEFAULT_PRICING,
     estimate_usage_cost,
     format_duration_compact,
-    get_pricing,
     has_known_pricing,
 )
 
@@ -39,15 +38,6 @@ def _has_known_pricing(model_name: str, provider: str = None, base_url: str = No
     return has_known_pricing(model_name, provider=provider, base_url=base_url)
 
 
-def _get_pricing(model_name: str) -> Dict[str, float]:
-    """Look up pricing for a model. Uses fuzzy matching on model name.
-
-    Returns _DEFAULT_PRICING (zero cost) for unknown/custom models —
-    we can't assume costs for self-hosted endpoints, local inference, etc.
-    """
-    return get_pricing(model_name)
-
-
 def _estimate_cost(
     session_or_model: Dict[str, Any] | str,
     input_tokens: int = 0,
@@ -644,6 +634,9 @@ class InsightsEngine:
         lines.append(f"  Sessions:          {o['total_sessions']:<12}  Messages:        {o['total_messages']:,}")
         lines.append(f"  Tool calls:        {o['total_tool_calls']:<12,}  User messages:   {o['user_messages']:,}")
         lines.append(f"  Input tokens:      {o['total_input_tokens']:<12,}  Output tokens:   {o['total_output_tokens']:,}")
+        cache_total = o.get("total_cache_read_tokens", 0) + o.get("total_cache_write_tokens", 0)
+        if cache_total > 0:
+            lines.append(f"  Cache read:        {o['total_cache_read_tokens']:<12,}  Cache write:     {o['total_cache_write_tokens']:,}")
         cost_str = f"${o['estimated_cost']:.2f}"
         if o.get("models_without_pricing"):
             cost_str += " *"
@@ -746,7 +739,11 @@ class InsightsEngine:
 
         # Overview
         lines.append(f"**Sessions:** {o['total_sessions']} | **Messages:** {o['total_messages']:,} | **Tool calls:** {o['total_tool_calls']:,}")
-        lines.append(f"**Tokens:** {o['total_tokens']:,} (in: {o['total_input_tokens']:,} / out: {o['total_output_tokens']:,})")
+        cache_total = o.get("total_cache_read_tokens", 0) + o.get("total_cache_write_tokens", 0)
+        if cache_total > 0:
+            lines.append(f"**Tokens:** {o['total_tokens']:,} (in: {o['total_input_tokens']:,} / out: {o['total_output_tokens']:,} / cache: {cache_total:,})")
+        else:
+            lines.append(f"**Tokens:** {o['total_tokens']:,} (in: {o['total_input_tokens']:,} / out: {o['total_output_tokens']:,})")
         cost_note = ""
         if o.get("models_without_pricing"):
             cost_note = " _(excludes custom/self-hosted models)_"

agent/knowledge_ingester.py

@@ -1,73 +0,0 @@
-"""Sovereign Knowledge Ingester for Hermes Agent.
-
-Uses Gemini 3.1 Pro to learn from Google Search in real-time and
-persists the knowledge to Timmy's sovereign memory (both Markdown and Symbolic).
-"""
-
-import logging
-import base64
-from typing import Any, Dict, List, Optional
-from agent.gemini_adapter import GeminiAdapter
-from agent.symbolic_memory import SymbolicMemory
-from tools.gitea_client import GiteaClient
-
-logger = logging.getLogger(__name__)
-
-class KnowledgeIngester:
-    def __init__(self):
-        self.adapter = GeminiAdapter()
-        self.gitea = GiteaClient()
-        self.symbolic = SymbolicMemory()
-
-    def learn_about(self, topic: str) -> str:
-        """Searches Google, analyzes the results, and saves the knowledge."""
-        logger.info(f"Learning about: {topic}")
-        
-        # 1. Search and Analyze
-        prompt = f"""
-Please perform a deep dive into the following topic: {topic}
-
-Use Google Search to find the most recent and relevant information.
-Analyze the findings and provide a structured 'Knowledge Fragment' in Markdown format.
-Include:
-- Summary of the topic
-- Key facts and recent developments
-- Implications for Timmy's sovereign mission
-- References (URLs)
-"""
-        result = self.adapter.generate(
-            model="gemini-3.1-pro-preview",
-            prompt=prompt,
-            system_instruction="You are Timmy's Sovereign Knowledge Ingester. Your goal is to find and synthesize high-fidelity information from Google Search.",
-            grounding=True,
-            thinking=True
-        )
-        
-        knowledge_fragment = result["text"]
-        
-        # 2. Extract Symbolic Triples
-        self.symbolic.ingest_text(knowledge_fragment)
-        
-        # 3. Persist to Timmy's Memory (Markdown)
-        repo = "Timmy_Foundation/timmy-config"
-        filename = f"memories/realtime_learning/{topic.lower().replace(' ', '_')}.md"
-        
-        try:
-            sha = None
-            try:
-                existing = self.gitea.get_file(repo, filename)
-                sha = existing.get("sha")
-            except:
-                pass
-            
-            content_b64 = base64.b64encode(knowledge_fragment.encode()).decode()
-            
-            if sha:
-                self.gitea.update_file(repo, filename, content_b64, f"Update knowledge on {topic}", sha)
-            else:
-                self.gitea.create_file(repo, filename, content_b64, f"Initial knowledge on {topic}")
-                
-            return f"Successfully learned about {topic}. Updated Timmy's Markdown memory and Symbolic Knowledge Graph."
-        except Exception as e:
-            logger.error(f"Failed to persist knowledge: {e}")
-            return f"Learned about {topic}, but failed to save to Markdown memory: {e}\n\n{knowledge_fragment}"

agent/manual_compression_feedback.py

@@ -0,0 +1,49 @@
+"""User-facing summaries for manual compression commands."""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+
+def summarize_manual_compression(
+    before_messages: Sequence[dict[str, Any]],
+    after_messages: Sequence[dict[str, Any]],
+    before_tokens: int,
+    after_tokens: int,
+) -> dict[str, Any]:
+    """Return consistent user-facing feedback for manual compression."""
+    before_count = len(before_messages)
+    after_count = len(after_messages)
+    noop = list(after_messages) == list(before_messages)
+
+    if noop:
+        headline = f"No changes from compression: {before_count} messages"
+        if after_tokens == before_tokens:
+            token_line = (
+                f"Rough transcript estimate: ~{before_tokens:,} tokens (unchanged)"
+            )
+        else:
+            token_line = (
+                f"Rough transcript estimate: ~{before_tokens:,} → "
+                f"~{after_tokens:,} tokens"
+            )
+    else:
+        headline = f"Compressed: {before_count} → {after_count} messages"
+        token_line = (
+            f"Rough transcript estimate: ~{before_tokens:,} → "
+            f"~{after_tokens:,} tokens"
+        )
+
+    note = None
+    if not noop and after_count < before_count and after_tokens > before_tokens:
+        note = (
+            "Note: fewer messages can still raise this rough transcript estimate "
+            "when compression rewrites the transcript into denser summaries."
+        )
+
+    return {
+        "noop": noop,
+        "headline": headline,
+        "token_line": token_line,
+        "note": note,
+    }

agent/memory_manager.py

@@ -0,0 +1,361 @@
+"""MemoryManager — orchestrates the built-in memory provider plus at most
+ONE external plugin memory provider.
+
+Single integration point in run_agent.py. Replaces scattered per-backend
+code with one manager that delegates to registered providers.
+
+The BuiltinMemoryProvider is always registered first and cannot be removed.
+Only ONE external (non-builtin) provider is allowed at a time — attempting
+to register a second external provider is rejected with a warning.  This
+prevents tool schema bloat and conflicting memory backends.
+
+Usage in run_agent.py:
+    self._memory_manager = MemoryManager()
+    self._memory_manager.add_provider(BuiltinMemoryProvider(...))
+    # Only ONE of these:
+    self._memory_manager.add_provider(plugin_provider)
+
+    # System prompt
+    prompt_parts.append(self._memory_manager.build_system_prompt())
+
+    # Pre-turn
+    context = self._memory_manager.prefetch_all(user_message)
+
+    # Post-turn
+    self._memory_manager.sync_all(user_msg, assistant_response)
+    self._memory_manager.queue_prefetch_all(user_msg)
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, Dict, List, Optional
+
+from agent.memory_provider import MemoryProvider
+from tools.registry import tool_error
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Context fencing helpers
+# ---------------------------------------------------------------------------
+
+_FENCE_TAG_RE = re.compile(r'</?\s*memory-context\s*>', re.IGNORECASE)
+
+
+def sanitize_context(text: str) -> str:
+    """Strip fence-escape sequences from provider output."""
+    return _FENCE_TAG_RE.sub('', text)
+
+
+def build_memory_context_block(raw_context: str) -> str:
+    """Wrap prefetched memory in a fenced block with system note.
+
+    The fence prevents the model from treating recalled context as user
+    discourse.  Injected at API-call time only — never persisted.
+    """
+    if not raw_context or not raw_context.strip():
+        return ""
+    clean = sanitize_context(raw_context)
+    return (
+        "<memory-context>\n"
+        "[System note: The following is recalled memory context, "
+        "NOT new user input. Treat as informational background data.]\n\n"
+        f"{clean}\n"
+        "</memory-context>"
+    )
+
+
+class MemoryManager:
+    """Orchestrates the built-in provider plus at most one external provider.
+
+    The builtin provider is always first. Only one non-builtin (external)
+    provider is allowed.  Failures in one provider never block the other.
+    """
+
+    def __init__(self) -> None:
+        self._providers: List[MemoryProvider] = []
+        self._tool_to_provider: Dict[str, MemoryProvider] = {}
+        self._has_external: bool = False  # True once a non-builtin provider is added
+
+    # -- Registration --------------------------------------------------------
+
+    def add_provider(self, provider: MemoryProvider) -> None:
+        """Register a memory provider.
+
+        Built-in provider (name ``"builtin"``) is always accepted.
+        Only **one** external (non-builtin) provider is allowed — a second
+        attempt is rejected with a warning.
+        """
+        is_builtin = provider.name == "builtin"
+
+        if not is_builtin:
+            if self._has_external:
+                existing = next(
+                    (p.name for p in self._providers if p.name != "builtin"), "unknown"
+                )
+                logger.warning(
+                    "Rejected memory provider '%s' — external provider '%s' is "
+                    "already registered. Only one external memory provider is "
+                    "allowed at a time. Configure which one via memory.provider "
+                    "in config.yaml.",
+                    provider.name, existing,
+                )
+                return
+            self._has_external = True
+
+        self._providers.append(provider)
+
+        # Index tool names → provider for routing
+        for schema in provider.get_tool_schemas():
+            tool_name = schema.get("name", "")
+            if tool_name and tool_name not in self._tool_to_provider:
+                self._tool_to_provider[tool_name] = provider
+            elif tool_name in self._tool_to_provider:
+                logger.warning(
+                    "Memory tool name conflict: '%s' already registered by %s, "
+                    "ignoring from %s",
+                    tool_name,
+                    self._tool_to_provider[tool_name].name,
+                    provider.name,
+                )
+
+        logger.info(
+            "Memory provider '%s' registered (%d tools)",
+            provider.name,
+            len(provider.get_tool_schemas()),
+        )
+
+    @property
+    def providers(self) -> List[MemoryProvider]:
+        """All registered providers in order."""
+        return list(self._providers)
+
+    def get_provider(self, name: str) -> Optional[MemoryProvider]:
+        """Get a provider by name, or None if not registered."""
+        for p in self._providers:
+            if p.name == name:
+                return p
+        return None
+
+    # -- System prompt -------------------------------------------------------
+
+    def build_system_prompt(self) -> str:
+        """Collect system prompt blocks from all providers.
+
+        Returns combined text, or empty string if no providers contribute.
+        Each non-empty block is labeled with the provider name.
+        """
+        blocks = []
+        for provider in self._providers:
+            try:
+                block = provider.system_prompt_block()
+                if block and block.strip():
+                    blocks.append(block)
+            except Exception as e:
+                logger.warning(
+                    "Memory provider '%s' system_prompt_block() failed: %s",
+                    provider.name, e,
+                )
+        return "\n\n".join(blocks)
+
+    # -- Prefetch / recall ---------------------------------------------------
+
+    def prefetch_all(self, query: str, *, session_id: str = "") -> str:
+        """Collect prefetch context from all providers.
+
+        Returns merged context text labeled by provider. Empty providers
+        are skipped. Failures in one provider don't block others.
+        """
+        parts = []
+        for provider in self._providers:
+            try:
+                result = provider.prefetch(query, session_id=session_id)
+                if result and result.strip():
+                    parts.append(result)
+            except Exception as e:
+                logger.debug(
+                    "Memory provider '%s' prefetch failed (non-fatal): %s",
+                    provider.name, e,
+                )
+        return "\n\n".join(parts)
+
+    def queue_prefetch_all(self, query: str, *, session_id: str = "") -> None:
+        """Queue background prefetch on all providers for the next turn."""
+        for provider in self._providers:
+            try:
+                provider.queue_prefetch(query, session_id=session_id)
+            except Exception as e:
+                logger.debug(
+                    "Memory provider '%s' queue_prefetch failed (non-fatal): %s",
+                    provider.name, e,
+                )
+
+    # -- Sync ----------------------------------------------------------------
+
+    def sync_all(self, user_content: str, assistant_content: str, *, session_id: str = "") -> None:
+        """Sync a completed turn to all providers."""
+        for provider in self._providers:
+            try:
+                provider.sync_turn(user_content, assistant_content, session_id=session_id)
+            except Exception as e:
+                logger.warning(
+                    "Memory provider '%s' sync_turn failed: %s",
+                    provider.name, e,
+                )
+
+    # -- Tools ---------------------------------------------------------------
+
+    def get_all_tool_schemas(self) -> List[Dict[str, Any]]:
+        """Collect tool schemas from all providers."""
+        schemas = []
+        seen = set()
+        for provider in self._providers:
+            try:
+                for schema in provider.get_tool_schemas():
+                    name = schema.get("name", "")
+                    if name and name not in seen:
+                        schemas.append(schema)
+                        seen.add(name)
+            except Exception as e:
+                logger.warning(
+                    "Memory provider '%s' get_tool_schemas() failed: %s",
+                    provider.name, e,
+                )
+        return schemas
+
+    def get_all_tool_names(self) -> set:
+        """Return set of all tool names across all providers."""
+        return set(self._tool_to_provider.keys())
+
+    def has_tool(self, tool_name: str) -> bool:
+        """Check if any provider handles this tool."""
+        return tool_name in self._tool_to_provider
+
+    def handle_tool_call(
+        self, tool_name: str, args: Dict[str, Any], **kwargs
+    ) -> str:
+        """Route a tool call to the correct provider.
+
+        Returns JSON string result. Raises ValueError if no provider
+        handles the tool.
+        """
+        provider = self._tool_to_provider.get(tool_name)
+        if provider is None:
+            return tool_error(f"No memory provider handles tool '{tool_name}'")
+        try:
+            return provider.handle_tool_call(tool_name, args, **kwargs)
+        except Exception as e:
+            logger.error(
+                "Memory provider '%s' handle_tool_call(%s) failed: %s",
+                provider.name, tool_name, e,
+            )
+            return tool_error(f"Memory tool '{tool_name}' failed: {e}")
+
+    # -- Lifecycle hooks -----------------------------------------------------
+
+    def on_turn_start(self, turn_number: int, message: str, **kwargs) -> None:
+        """Notify all providers of a new turn.
+
+        kwargs may include: remaining_tokens, model, platform, tool_count.
+        """
+        for provider in self._providers:
+            try:
+                provider.on_turn_start(turn_number, message, **kwargs)
+            except Exception as e:
+                logger.debug(
+                    "Memory provider '%s' on_turn_start failed: %s",
+                    provider.name, e,
+                )
+
+    def on_session_end(self, messages: List[Dict[str, Any]]) -> None:
+        """Notify all providers of session end."""
+        for provider in self._providers:
+            try:
+                provider.on_session_end(messages)
+            except Exception as e:
+                logger.debug(
+                    "Memory provider '%s' on_session_end failed: %s",
+                    provider.name, e,
+                )
+
+    def on_pre_compress(self, messages: List[Dict[str, Any]]) -> str:
+        """Notify all providers before context compression.
+
+        Returns combined text from providers to include in the compression
+        summary prompt. Empty string if no provider contributes.
+        """
+        parts = []
+        for provider in self._providers:
+            try:
+                result = provider.on_pre_compress(messages)
+                if result and result.strip():
+                    parts.append(result)
+            except Exception as e:
+                logger.debug(
+                    "Memory provider '%s' on_pre_compress failed: %s",
+                    provider.name, e,
+                )
+        return "\n\n".join(parts)
+
+    def on_memory_write(self, action: str, target: str, content: str) -> None:
+        """Notify external providers when the built-in memory tool writes.
+
+        Skips the builtin provider itself (it's the source of the write).
+        """
+        for provider in self._providers:
+            if provider.name == "builtin":
+                continue
+            try:
+                provider.on_memory_write(action, target, content)
+            except Exception as e:
+                logger.debug(
+                    "Memory provider '%s' on_memory_write failed: %s",
+                    provider.name, e,
+                )
+
+    def on_delegation(self, task: str, result: str, *,
+                      child_session_id: str = "", **kwargs) -> None:
+        """Notify all providers that a subagent completed."""
+        for provider in self._providers:
+            try:
+                provider.on_delegation(
+                    task, result, child_session_id=child_session_id, **kwargs
+                )
+            except Exception as e:
+                logger.debug(
+                    "Memory provider '%s' on_delegation failed: %s",
+                    provider.name, e,
+                )
+
+    def shutdown_all(self) -> None:
+        """Shut down all providers (reverse order for clean teardown)."""
+        for provider in reversed(self._providers):
+            try:
+                provider.shutdown()
+            except Exception as e:
+                logger.warning(
+                    "Memory provider '%s' shutdown failed: %s",
+                    provider.name, e,
+                )
+
+    def initialize_all(self, session_id: str, **kwargs) -> None:
+        """Initialize all providers.
+
+        Automatically injects ``hermes_home`` into *kwargs* so that every
+        provider can resolve profile-scoped storage paths without importing
+        ``get_hermes_home()`` themselves.
+        """
+        if "hermes_home" not in kwargs:
+            from hermes_constants import get_hermes_home
+            kwargs["hermes_home"] = str(get_hermes_home())
+        for provider in self._providers:
+            try:
+                provider.initialize(session_id=session_id, **kwargs)
+            except Exception as e:
+                logger.warning(
+                    "Memory provider '%s' initialize failed: %s",
+                    provider.name, e,
+                )

agent/memory_provider.py

@@ -0,0 +1,231 @@
+"""Abstract base class for pluggable memory providers.
+
+Memory providers give the agent persistent recall across sessions. One
+external provider is active at a time alongside the always-on built-in
+memory (MEMORY.md / USER.md). The MemoryManager enforces this limit.
+
+Built-in memory is always active as the first provider and cannot be removed.
+External providers (Honcho, Hindsight, Mem0, etc.) are additive — they never
+disable the built-in store. Only one external provider runs at a time to
+prevent tool schema bloat and conflicting memory backends.
+
+Registration:
+  1. Built-in: BuiltinMemoryProvider — always present, not removable.
+  2. Plugins: Ship in plugins/memory/<name>/, activated by memory.provider config.
+
+Lifecycle (called by MemoryManager, wired in run_agent.py):
+  initialize()          — connect, create resources, warm up
+  system_prompt_block()  — static text for the system prompt
+  prefetch(query)        — background recall before each turn
+  sync_turn(user, asst)  — async write after each turn
+  get_tool_schemas()     — tool schemas to expose to the model
+  handle_tool_call()     — dispatch a tool call
+  shutdown()             — clean exit
+
+Optional hooks (override to opt in):
+  on_turn_start(turn, message, **kwargs) — per-turn tick with runtime context
+  on_session_end(messages)               — end-of-session extraction
+  on_pre_compress(messages) -> str       — extract before context compression
+  on_memory_write(action, target, content) — mirror built-in memory writes
+  on_delegation(task, result, **kwargs)  — parent-side observation of subagent work
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryProvider(ABC):
+    """Abstract base class for memory providers."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Short identifier for this provider (e.g. 'builtin', 'honcho', 'hindsight')."""
+
+    # -- Core lifecycle (implement these) ------------------------------------
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Return True if this provider is configured, has credentials, and is ready.
+
+        Called during agent init to decide whether to activate the provider.
+        Should not make network calls — just check config and installed deps.
+        """
+
+    @abstractmethod
+    def initialize(self, session_id: str, **kwargs) -> None:
+        """Initialize for a session.
+
+        Called once at agent startup. May create resources (banks, tables),
+        establish connections, start background threads, etc.
+
+        kwargs always include:
+          - hermes_home (str): The active HERMES_HOME directory path. Use this
+            for profile-scoped storage instead of hardcoding ``~/.hermes``.
+          - platform (str): "cli", "telegram", "discord", "cron", etc.
+
+        kwargs may also include:
+          - agent_context (str): "primary", "subagent", "cron", or "flush".
+            Providers should skip writes for non-primary contexts (cron system
+            prompts would corrupt user representations).
+          - agent_identity (str): Profile name (e.g. "coder"). Use for
+            per-profile provider identity scoping.
+          - agent_workspace (str): Shared workspace name (e.g. "hermes").
+          - parent_session_id (str): For subagents, the parent's session_id.
+          - user_id (str): Platform user identifier (gateway sessions).
+        """
+
+    def system_prompt_block(self) -> str:
+        """Return text to include in the system prompt.
+
+        Called during system prompt assembly. Return empty string to skip.
+        This is for STATIC provider info (instructions, status). Prefetched
+        recall context is injected separately via prefetch().
+        """
+        return ""
+
+    def prefetch(self, query: str, *, session_id: str = "") -> str:
+        """Recall relevant context for the upcoming turn.
+
+        Called before each API call. Return formatted text to inject as
+        context, or empty string if nothing relevant. Implementations
+        should be fast — use background threads for the actual recall
+        and return cached results here.
+
+        session_id is provided for providers serving concurrent sessions
+        (gateway group chats, cached agents). Providers that don't need
+        per-session scoping can ignore it.
+        """
+        return ""
+
+    def queue_prefetch(self, query: str, *, session_id: str = "") -> None:
+        """Queue a background recall for the NEXT turn.
+
+        Called after each turn completes. The result will be consumed
+        by prefetch() on the next turn. Default is no-op — providers
+        that do background prefetching should override this.
+        """
+
+    def sync_turn(self, user_content: str, assistant_content: str, *, session_id: str = "") -> None:
+        """Persist a completed turn to the backend.
+
+        Called after each turn. Should be non-blocking — queue for
+        background processing if the backend has latency.
+        """
+
+    @abstractmethod
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        """Return tool schemas this provider exposes.
+
+        Each schema follows the OpenAI function calling format:
+        {"name": "...", "description": "...", "parameters": {...}}
+
+        Return empty list if this provider has no tools (context-only).
+        """
+
+    def handle_tool_call(self, tool_name: str, args: Dict[str, Any], **kwargs) -> str:
+        """Handle a tool call for one of this provider's tools.
+
+        Must return a JSON string (the tool result).
+        Only called for tool names returned by get_tool_schemas().
+        """
+        raise NotImplementedError(f"Provider {self.name} does not handle tool {tool_name}")
+
+    def shutdown(self) -> None:
+        """Clean shutdown — flush queues, close connections."""
+
+    # -- Optional hooks (override to opt in) ---------------------------------
+
+    def on_turn_start(self, turn_number: int, message: str, **kwargs) -> None:
+        """Called at the start of each turn with the user message.
+
+        Use for turn-counting, scope management, periodic maintenance.
+
+        kwargs may include: remaining_tokens, model, platform, tool_count.
+        Providers use what they need; extras are ignored.
+        """
+
+    def on_session_end(self, messages: List[Dict[str, Any]]) -> None:
+        """Called when a session ends (explicit exit or timeout).
+
+        Use for end-of-session fact extraction, summarization, etc.
+        messages is the full conversation history.
+
+        NOT called after every turn — only at actual session boundaries
+        (CLI exit, /reset, gateway session expiry).
+        """
+
+    def on_pre_compress(self, messages: List[Dict[str, Any]]) -> str:
+        """Called before context compression discards old messages.
+
+        Use to extract insights from messages about to be compressed.
+        messages is the list that will be summarized/discarded.
+
+        Return text to include in the compression summary prompt so the
+        compressor preserves provider-extracted insights. Return empty
+        string for no contribution (backwards-compatible default).
+        """
+        return ""
+
+    def on_delegation(self, task: str, result: str, *,
+                      child_session_id: str = "", **kwargs) -> None:
+        """Called on the PARENT agent when a subagent completes.
+
+        The parent's memory provider gets the task+result pair as an
+        observation of what was delegated and what came back. The subagent
+        itself has no provider session (skip_memory=True).
+
+        task: the delegation prompt
+        result: the subagent's final response
+        child_session_id: the subagent's session_id
+        """
+
+    def get_config_schema(self) -> List[Dict[str, Any]]:
+        """Return config fields this provider needs for setup.
+
+        Used by 'hermes memory setup' to walk the user through configuration.
+        Each field is a dict with:
+          key:         config key name (e.g. 'api_key', 'mode')
+          description: human-readable description
+          secret:      True if this should go to .env (default: False)
+          required:    True if required (default: False)
+          default:     default value (optional)
+          choices:     list of valid values (optional)
+          url:         URL where user can get this credential (optional)
+          env_var:     explicit env var name for secrets (default: auto-generated)
+
+        Return empty list if no config needed (e.g. local-only providers).
+        """
+        return []
+
+    def save_config(self, values: Dict[str, Any], hermes_home: str) -> None:
+        """Write non-secret config to the provider's native location.
+
+        Called by 'hermes memory setup' after collecting user inputs.
+        ``values`` contains only non-secret fields (secrets go to .env).
+        ``hermes_home`` is the active HERMES_HOME directory path.
+
+        Providers with native config files (JSON, YAML) should override
+        this to write to their expected location. Providers that use only
+        env vars can leave the default (no-op).
+
+        All new memory provider plugins MUST implement either:
+        - save_config() for native config file formats, OR
+        - use only env vars (in which case get_config_schema() fields
+          should all have ``env_var`` set and this method stays no-op).
+        """
+
+    def on_memory_write(self, action: str, target: str, content: str) -> None:
+        """Called when the built-in memory tool writes an entry.
+
+        action: 'add', 'replace', or 'remove'
+        target: 'memory' or 'user'
+        content: the entry content
+
+        Use to mirror built-in memory writes to your backend.
+        """

agent/meta_reasoning.py

@@ -1,47 +0,0 @@
-"""Meta-Reasoning Layer for Hermes Agent.
-
-Implements a sovereign self-correction loop where a 'strong' model (Gemini 3.1 Pro)
-critiques the plans generated by the primary agent loop before execution.
-"""
-
-import logging
-from typing import Any, Dict, List, Optional
-from agent.gemini_adapter import GeminiAdapter
-
-logger = logging.getLogger(__name__)
-
-class MetaReasoningLayer:
-    def __init__(self):
-        self.adapter = GeminiAdapter()
-
-    def critique_plan(self, goal: str, proposed_plan: str, context: str) -> Dict[str, Any]:
-        """Critiques a proposed plan using Gemini's thinking capabilities."""
-        prompt = f"""
-Goal: {goal}
-
-Context:
-{context}
-
-Proposed Plan:
-{proposed_plan}
-
-Please perform a deep symbolic and neuro-symbolic analysis of this plan.
-Identify potential risks, logical fallacies, or missing steps.
-Suggest improvements to make the plan more sovereign, cost-efficient, and robust.
-"""
-        try:
-            result = self.adapter.generate(
-                model="gemini-3.1-pro-preview",
-                prompt=prompt,
-                system_instruction="You are a Senior Meta-Reasoning Engine for the Hermes Agent. Your goal is to ensure the agent's plans are flawless and sovereign.",
-                thinking=True,
-                thinking_budget=8000
-            )
-            return {
-                "critique": result["text"],
-                "thoughts": result.get("thoughts", ""),
-                "grounding": result.get("grounding")
-            }
-        except Exception as e:
-            logger.error(f"Meta-reasoning failed: {e}")
-            return {"critique": "Meta-reasoning unavailable.", "error": str(e)}

agent/model_metadata.py

@@ -5,7 +5,6 @@ and run_agent.py for pre-flight context checks.
 """
 
 import logging
-import os
 import re
 import time
 from pathlib import Path
@@ -24,13 +23,21 @@ logger = logging.getLogger(__name__)
 # are preserved so the full model name reaches cache lookups and server queries.
 _PROVIDER_PREFIXES: frozenset[str] = frozenset({
     "openrouter", "nous", "openai-codex", "copilot", "copilot-acp",
-    "zai", "kimi-coding", "minimax", "minimax-cn", "anthropic", "deepseek",
+    "gemini", "zai", "kimi-coding", "kimi-coding-cn", "minimax", "minimax-cn", "anthropic", "deepseek",
     "opencode-zen", "opencode-go", "ai-gateway", "kilocode", "alibaba",
+    "qwen-oauth",
+    "xiaomi",
+    "arcee",
     "custom", "local",
     # Common aliases
+    "google", "google-gemini", "google-ai-studio",
     "glm", "z-ai", "z.ai", "zhipu", "github", "github-copilot",
-    "github-models", "kimi", "moonshot", "claude", "deep-seek",
+    "github-models", "kimi", "moonshot", "kimi-cn", "moonshot-cn", "claude", "deep-seek",
     "opencode", "zen", "go", "vercel", "kilo", "dashscope", "aliyun", "qwen",
+    "mimo", "xiaomi-mimo",
+    "arcee-ai", "arceeai",
+    "xai", "x-ai", "x.ai", "grok",
+    "qwen-portal",
 })
 
 
@@ -80,6 +87,11 @@ CONTEXT_PROBE_TIERS = [
 # Default context length when no detection method succeeds.
 DEFAULT_FALLBACK_CONTEXT = CONTEXT_PROBE_TIERS[0]
 
+# Minimum context length required to run Hermes Agent.  Models with fewer
+# tokens cannot maintain enough working memory for tool-calling workflows.
+# Sessions, model switches, and cron jobs should reject models below this.
+MINIMUM_CONTEXT_LENGTH = 64_000
+
 # Thin fallback defaults — only broad model family patterns.
 # These fire only when provider is unknown AND models.dev/OpenRouter/Anthropic
 # all miss. Replaced the previous 80+ entry dict.
@@ -95,24 +107,58 @@ DEFAULT_CONTEXT_LENGTHS = {
     "claude-sonnet-4.6": 1000000,
     # Catch-all for older Claude models (must sort after specific entries)
     "claude": 200000,
-    # OpenAI
+    # OpenAI — GPT-5 family (most have 400k; specific overrides first)
+    # Source: https://developers.openai.com/api/docs/models
+    "gpt-5.4-nano": 400000,           # 400k (not 1.05M like full 5.4)
+    "gpt-5.4-mini": 400000,           # 400k (not 1.05M like full 5.4)
+    "gpt-5.4": 1050000,               # GPT-5.4, GPT-5.4 Pro (1.05M context)
+    "gpt-5.3-codex-spark": 128000,    # Spark variant has reduced 128k context
+    "gpt-5.1-chat": 128000,           # Chat variant has 128k context
+    "gpt-5": 400000,                  # GPT-5.x base, mini, codex variants (400k)
     "gpt-4.1": 1047576,
-    "gpt-5": 128000,
     "gpt-4": 128000,
     # Google
     "gemini": 1048576,
+    # Gemma (open models served via AI Studio)
+    "gemma-4-31b": 256000,
+    "gemma-4-26b": 256000,
+    "gemma-3": 131072,
+    "gemma": 8192,  # fallback for older gemma models
     # DeepSeek
     "deepseek": 128000,
     # Meta
     "llama": 131072,
-    # Qwen
+    # Qwen — specific model families before the catch-all.
+    # Official docs: https://help.aliyun.com/zh/model-studio/developer-reference/
+    "qwen3-coder-plus": 1000000,  # 1M context
+    "qwen3-coder": 262144,        # 256K context
     "qwen": 131072,
-    # MiniMax
+    # MiniMax — official docs: 204,800 context for all models
+    # https://platform.minimax.io/docs/api-reference/text-anthropic-api
     "minimax": 204800,
     # GLM
     "glm": 202752,
+    # xAI Grok — xAI /v1/models does not return context_length metadata,
+    # so these hardcoded fallbacks prevent Hermes from probing-down to
+    # the default 128k when the user points at https://api.x.ai/v1
+    # via a custom provider. Values sourced from models.dev (2026-04).
+    # Keys use substring matching (longest-first), so e.g. "grok-4.20"
+    # matches "grok-4.20-0309-reasoning" / "-non-reasoning" / "-multi-agent-0309".
+    "grok-code-fast": 256000,   # grok-code-fast-1
+    "grok-4-1-fast": 2000000,   # grok-4-1-fast-(non-)reasoning
+    "grok-2-vision": 8192,      # grok-2-vision, -1212, -latest
+    "grok-4-fast": 2000000,     # grok-4-fast-(non-)reasoning
+    "grok-4.20": 2000000,       # grok-4.20-0309-(non-)reasoning, -multi-agent-0309
+    "grok-4": 256000,           # grok-4, grok-4-0709
+    "grok-3": 131072,           # grok-3, grok-3-mini, grok-3-fast, grok-3-mini-fast
+    "grok-2": 131072,           # grok-2, grok-2-1212, grok-2-latest
+    "grok": 131072,             # catch-all (grok-beta, unknown grok-*)
     # Kimi
     "kimi": 262144,
+    # Arcee
+    "trinity": 262144,
+    # OpenRouter
+    "elephant": 262144,
     # Hugging Face Inference Providers — model IDs use org/name format
     "Qwen/Qwen3.5-397B-A17B": 131072,
     "Qwen/Qwen3.5-35B-A3B": 131072,
@@ -120,7 +166,10 @@ DEFAULT_CONTEXT_LENGTHS = {
     "moonshotai/Kimi-K2.5": 262144,
     "moonshotai/Kimi-K2-Thinking": 262144,
     "MiniMaxAI/MiniMax-M2.5": 204800,
-    "XiaomiMiMo/MiMo-V2-Flash": 32768,
+    "XiaomiMiMo/MiMo-V2-Flash": 256000,
+    "mimo-v2-pro": 1000000,
+    "mimo-v2-omni": 256000,
+    "mimo-v2-flash": 256000,
     "zai-org/GLM-5": 202752,
 }
 
@@ -145,6 +194,12 @@ _MAX_COMPLETION_KEYS = (
 
 # Local server hostnames / address patterns
 _LOCAL_HOSTS = ("localhost", "127.0.0.1", "::1", "0.0.0.0")
+# Docker / Podman / Lima DNS names that resolve to the host machine
+_CONTAINER_LOCAL_SUFFIXES = (
+    ".docker.internal",
+    ".containers.internal",
+    ".lima.internal",
+)
 
 
 def _normalize_base_url(base_url: str) -> str:
@@ -166,16 +221,24 @@ _URL_TO_PROVIDER: Dict[str, str] = {
     "api.anthropic.com": "anthropic",
     "api.z.ai": "zai",
     "api.moonshot.ai": "kimi-coding",
+    "api.moonshot.cn": "kimi-coding-cn",
     "api.kimi.com": "kimi-coding",
+    "api.arcee.ai": "arcee",
     "api.minimax": "minimax",
     "dashscope.aliyuncs.com": "alibaba",
     "dashscope-intl.aliyuncs.com": "alibaba",
+    "portal.qwen.ai": "qwen-oauth",
     "openrouter.ai": "openrouter",
-    "generativelanguage.googleapis.com": "google",
+    "generativelanguage.googleapis.com": "gemini",
     "inference-api.nousresearch.com": "nous",
     "api.deepseek.com": "deepseek",
     "api.githubcopilot.com": "copilot",
     "models.github.ai": "copilot",
+    "api.fireworks.ai": "fireworks",
+    "opencode.ai": "opencode-go",
+    "api.x.ai": "xai",
+    "api.xiaomimimo.com": "xiaomi",
+    "xiaomimimo.com": "xiaomi",
 }
 
 
@@ -214,6 +277,9 @@ def is_local_endpoint(base_url: str) -> bool:
         return False
     if host in _LOCAL_HOSTS:
         return True
+    # Docker / Podman / Lima internal DNS names (e.g. host.docker.internal)
+    if any(host.endswith(suffix) for suffix in _CONTAINER_LOCAL_SUFFIXES):
+        return True
     # RFC-1918 private ranges and link-local
     import ipaddress
     try:
@@ -499,8 +565,8 @@ def fetch_endpoint_model_metadata(
 
 def _get_context_cache_path() -> Path:
     """Return path to the persistent context length cache file."""
-    hermes_home = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
-    return hermes_home / "context_length_cache.yaml"
+    from hermes_constants import get_hermes_home
+    return get_hermes_home() / "context_length_cache.yaml"
 
 
 def _load_context_cache() -> Dict[str, int]:
@@ -581,6 +647,49 @@ def parse_context_limit_from_error(error_msg: str) -> Optional[int]:
     return None
 
 
+def parse_available_output_tokens_from_error(error_msg: str) -> Optional[int]:
+    """Detect an "output cap too large" error and return how many output tokens are available.
+
+    Background — two distinct context errors exist:
+      1. "Prompt too long"  — the INPUT itself exceeds the context window.
+           Fix: compress history and/or halve context_length.
+      2. "max_tokens too large" — input is fine, but input + requested_output > window.
+           Fix: reduce max_tokens (the output cap) for this call.
+           Do NOT touch context_length — the window hasn't shrunk.
+
+    Anthropic's API returns errors like:
+      "max_tokens: 32768 > context_window: 200000 - input_tokens: 190000 = available_tokens: 10000"
+
+    Returns the number of output tokens that would fit (e.g. 10000 above), or None if
+    the error does not look like a max_tokens-too-large error.
+    """
+    error_lower = error_msg.lower()
+
+    # Must look like an output-cap error, not a prompt-length error.
+    is_output_cap_error = (
+        "max_tokens" in error_lower
+        and ("available_tokens" in error_lower or "available tokens" in error_lower)
+    )
+    if not is_output_cap_error:
+        return None
+
+    # Extract the available_tokens figure.
+    # Anthropic format: "… = available_tokens: 10000"
+    patterns = [
+        r'available_tokens[:\s]+(\d+)',
+        r'available\s+tokens[:\s]+(\d+)',
+        # fallback: last number after "=" in expressions like "200000 - 190000 = 10000"
+        r'=\s*(\d+)\s*$',
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, error_lower)
+        if match:
+            tokens = int(match.group(1))
+            if tokens >= 1:
+                return tokens
+    return None
+
+
 def _model_id_matches(candidate_id: str, lookup_model: str) -> bool:
     """Return True if *candidate_id* (from server) matches *lookup_model* (configured).
 
@@ -600,6 +709,59 @@ def _model_id_matches(candidate_id: str, lookup_model: str) -> bool:
     return False
 
 
+def query_ollama_num_ctx(model: str, base_url: str) -> Optional[int]:
+    """Query an Ollama server for the model's context length.
+
+    Returns the model's maximum context from GGUF metadata via ``/api/show``,
+    or the explicit ``num_ctx`` from the Modelfile if set.  Returns None if
+    the server is unreachable or not Ollama.
+
+    This is the value that should be passed as ``num_ctx`` in Ollama chat
+    requests to override the default 2048.
+    """
+    import httpx
+
+    bare_model = _strip_provider_prefix(model)
+    server_url = base_url.rstrip("/")
+    if server_url.endswith("/v1"):
+        server_url = server_url[:-3]
+
+    try:
+        server_type = detect_local_server_type(base_url)
+    except Exception:
+        return None
+    if server_type != "ollama":
+        return None
+
+    try:
+        with httpx.Client(timeout=3.0) as client:
+            resp = client.post(f"{server_url}/api/show", json={"name": bare_model})
+            if resp.status_code != 200:
+                return None
+            data = resp.json()
+
+            # Prefer explicit num_ctx from Modelfile parameters (user override)
+            params = data.get("parameters", "")
+            if "num_ctx" in params:
+                for line in params.split("\n"):
+                    if "num_ctx" in line:
+                        parts = line.strip().split()
+                        if len(parts) >= 2:
+                            try:
+                                return int(parts[-1])
+                            except ValueError:
+                                pass
+
+            # Fall back to GGUF model_info context_length (training max)
+            model_info = data.get("model_info", {})
+            for key, value in model_info.items():
+                if "context_length" in key and isinstance(value, (int, float)):
+                    return int(value)
+    except Exception:
+        pass
+    return None
+
+
 def _query_local_context_length(model: str, base_url: str) -> Optional[int]:
     """Query a local server for the model's context length."""
     import httpx
@@ -625,12 +787,12 @@ def _query_local_context_length(model: str, base_url: str) -> Optional[int]:
                 resp = client.post(f"{server_url}/api/show", json={"name": model})
                 if resp.status_code == 200:
                     data = resp.json()
-                    # Check model_info for context length
-                    model_info = data.get("model_info", {})
-                    for key, value in model_info.items():
-                        if "context_length" in key and isinstance(value, (int, float)):
-                            return int(value)
-                    # Check parameters string for num_ctx
+                    # Prefer explicit num_ctx from Modelfile parameters: this is
+                    # the *runtime* context Ollama will actually allocate KV cache
+                    # for. The GGUF model_info.context_length is the training max,
+                    # which can be larger than num_ctx — using it here would let
+                    # Hermes grow conversations past the runtime limit and Ollama
+                    # would silently truncate. Matches query_ollama_num_ctx().
                     params = data.get("parameters", "")
                     if "num_ctx" in params:
                         for line in params.split("\n"):
@@ -641,6 +803,11 @@ def _query_local_context_length(model: str, base_url: str) -> Optional[int]:
                                         return int(parts[-1])
                                     except ValueError:
                                         pass
+                    # Fall back to GGUF model_info context_length (training max)
+                    model_info = data.get("model_info", {})
+                    for key, value in model_info.items():
+                        if "context_length" in key and isinstance(value, (int, float)):
+                            return int(value)
 
             # LM Studio native API: /api/v1/models returns max_context_length.
             # This is more reliable than the OpenAI-compat /v1/models which
@@ -895,16 +1062,21 @@ def get_model_context_length(
 
 
 def estimate_tokens_rough(text: str) -> int:
-    """Rough token estimate (~4 chars/token) for pre-flight checks."""
+    """Rough token estimate (~4 chars/token) for pre-flight checks.
+
+    Uses ceiling division so short texts (1-3 chars) never estimate as
+    0 tokens, which would cause the compressor and pre-flight checks to
+    systematically undercount when many short tool results are present.
+    """
     if not text:
         return 0
-    return len(text) // 4
+    return (len(text) + 3) // 4
 
 
 def estimate_messages_tokens_rough(messages: List[Dict[str, Any]]) -> int:
     """Rough token estimate for a message list (pre-flight only)."""
     total_chars = sum(len(str(msg)) for msg in messages)
-    return total_chars // 4
+    return (total_chars + 3) // 4
 
 
 def estimate_request_tokens_rough(
@@ -927,4 +1099,4 @@ def estimate_request_tokens_rough(
         total_chars += sum(len(str(msg)) for msg in messages)
     if tools:
         total_chars += len(str(tools))
-    return total_chars // 4
+    return (total_chars + 3) // 4

agent/models_dev.py

@@ -1,19 +1,29 @@
-"""Models.dev registry integration for provider-aware context length detection.
+"""Models.dev registry integration — primary database for providers and models.
 
-Fetches model metadata from https://models.dev/api.json — a community-maintained
-database of 3800+ models across 100+ providers, including per-provider context
-windows, pricing, and capabilities.
+Fetches from https://models.dev/api.json — a community-maintained database
+of 4000+ models across 109+ providers.  Provides:
 
-Data is cached in memory (1hr TTL) and on disk (~/.hermes/models_dev_cache.json)
-to avoid cold-start network latency.
+- **Provider metadata**: name, base URL, env vars, documentation link
+- **Model metadata**: context window, max output, cost/M tokens, capabilities
+  (reasoning, tools, vision, PDF, audio), modalities, knowledge cutoff,
+  open-weights flag, family grouping, deprecation status
+
+Data resolution order (like TypeScript OpenCode):
+  1. Bundled snapshot (ships with the package — offline-first)
+  2. Disk cache (~/.hermes/models_dev_cache.json)
+  3. Network fetch (https://models.dev/api.json)
+  4. Background refresh every 60 minutes
+
+Other modules should import the dataclasses and query functions from here
+rather than parsing the raw JSON themselves.
 """
 
 import json
 import logging
-import os
 import time
+from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 from utils import atomic_json_write
 
@@ -28,29 +38,148 @@ _MODELS_DEV_CACHE_TTL = 3600  # 1 hour in-memory
 _models_dev_cache: Dict[str, Any] = {}
 _models_dev_cache_time: float = 0
 
-# Provider ID mapping: Hermes provider names → models.dev provider IDs
+
+# ---------------------------------------------------------------------------
+# Dataclasses — rich metadata for providers and models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ModelInfo:
+    """Full metadata for a single model from models.dev."""
+
+    id: str
+    name: str
+    family: str
+    provider_id: str        # models.dev provider ID (e.g. "anthropic")
+
+    # Capabilities
+    reasoning: bool = False
+    tool_call: bool = False
+    attachment: bool = False       # supports image/file attachments (vision)
+    temperature: bool = False
+    structured_output: bool = False
+    open_weights: bool = False
+
+    # Modalities
+    input_modalities: Tuple[str, ...] = ()    # ("text", "image", "pdf", ...)
+    output_modalities: Tuple[str, ...] = ()
+
+    # Limits
+    context_window: int = 0
+    max_output: int = 0
+    max_input: Optional[int] = None
+
+    # Cost (per million tokens, USD)
+    cost_input: float = 0.0
+    cost_output: float = 0.0
+    cost_cache_read: Optional[float] = None
+    cost_cache_write: Optional[float] = None
+
+    # Metadata
+    knowledge_cutoff: str = ""
+    release_date: str = ""
+    status: str = ""          # "alpha", "beta", "deprecated", or ""
+    interleaved: Any = False  # True or {"field": "reasoning_content"}
+
+    def has_cost_data(self) -> bool:
+        return self.cost_input > 0 or self.cost_output > 0
+
+    def supports_vision(self) -> bool:
+        return self.attachment or "image" in self.input_modalities
+
+    def supports_pdf(self) -> bool:
+        return "pdf" in self.input_modalities
+
+    def supports_audio_input(self) -> bool:
+        return "audio" in self.input_modalities
+
+    def format_cost(self) -> str:
+        """Human-readable cost string, e.g. '$3.00/M in, $15.00/M out'."""
+        if not self.has_cost_data():
+            return "unknown"
+        parts = [f"${self.cost_input:.2f}/M in", f"${self.cost_output:.2f}/M out"]
+        if self.cost_cache_read is not None:
+            parts.append(f"cache read ${self.cost_cache_read:.2f}/M")
+        return ", ".join(parts)
+
+    def format_capabilities(self) -> str:
+        """Human-readable capabilities, e.g. 'reasoning, tools, vision, PDF'."""
+        caps = []
+        if self.reasoning:
+            caps.append("reasoning")
+        if self.tool_call:
+            caps.append("tools")
+        if self.supports_vision():
+            caps.append("vision")
+        if self.supports_pdf():
+            caps.append("PDF")
+        if self.supports_audio_input():
+            caps.append("audio")
+        if self.structured_output:
+            caps.append("structured output")
+        if self.open_weights:
+            caps.append("open weights")
+        return ", ".join(caps) if caps else "basic"
+
+
+@dataclass
+class ProviderInfo:
+    """Full metadata for a provider from models.dev."""
+
+    id: str                         # models.dev provider ID
+    name: str                       # display name
+    env: Tuple[str, ...]            # env var names for API key
+    api: str                        # base URL
+    doc: str = ""                   # documentation URL
+    model_count: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Provider ID mapping: Hermes ↔ models.dev
+# ---------------------------------------------------------------------------
+
+# Hermes provider names → models.dev provider IDs
 PROVIDER_TO_MODELS_DEV: Dict[str, str] = {
     "openrouter": "openrouter",
     "anthropic": "anthropic",
+    "openai": "openai",
+    "openai-codex": "openai",
     "zai": "zai",
     "kimi-coding": "kimi-for-coding",
+    "kimi-coding-cn": "kimi-for-coding",
     "minimax": "minimax",
     "minimax-cn": "minimax-cn",
     "deepseek": "deepseek",
     "alibaba": "alibaba",
+    "qwen-oauth": "alibaba",
     "copilot": "github-copilot",
     "ai-gateway": "vercel",
     "opencode-zen": "opencode",
     "opencode-go": "opencode-go",
     "kilocode": "kilo",
+    "fireworks": "fireworks-ai",
+    "huggingface": "huggingface",
+    "gemini": "google",
+    "google": "google",
+    "xai": "xai",
+    "xiaomi": "xiaomi",
+    "nvidia": "nvidia",
+    "groq": "groq",
+    "mistral": "mistral",
+    "togetherai": "togetherai",
+    "perplexity": "perplexity",
+    "cohere": "cohere",
 }
 
+# Reverse mapping: models.dev → Hermes (built lazily)
+_MODELS_DEV_TO_PROVIDER: Optional[Dict[str, str]] = None
+
+
 
 def _get_cache_path() -> Path:
     """Return path to disk cache file."""
-    env_val = os.environ.get("HERMES_HOME", "")
-    hermes_home = Path(env_val) if env_val else Path.home() / ".hermes"
-    return hermes_home / "models_dev_cache.json"
+    from hermes_constants import get_hermes_home
+    return get_hermes_home() / "models_dev_cache.json"
 
 
 def _load_disk_cache() -> Dict[str, Any]:
@@ -94,7 +223,7 @@ def fetch_models_dev(force_refresh: bool = False) -> Dict[str, Any]:
         response = requests.get(MODELS_DEV_URL, timeout=15)
         response.raise_for_status()
         data = response.json()
-        if isinstance(data, dict) and len(data) > 0:
+        if isinstance(data, dict) and data:
             _models_dev_cache = data
             _models_dev_cache_time = time.time()
             _save_disk_cache(data)
@@ -169,3 +298,288 @@ def _extract_context(entry: Dict[str, Any]) -> Optional[int]:
     if isinstance(ctx, (int, float)) and ctx > 0:
         return int(ctx)
     return None
+
+
+# ---------------------------------------------------------------------------
+# Model capability metadata
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ModelCapabilities:
+    """Structured capability metadata for a model from models.dev."""
+
+    supports_tools: bool = True
+    supports_vision: bool = False
+    supports_reasoning: bool = False
+    context_window: int = 200000
+    max_output_tokens: int = 8192
+    model_family: str = ""
+
+
+def _get_provider_models(provider: str) -> Optional[Dict[str, Any]]:
+    """Resolve a Hermes provider ID to its models dict from models.dev.
+
+    Returns the models dict or None if the provider is unknown or has no data.
+    """
+    mdev_provider_id = PROVIDER_TO_MODELS_DEV.get(provider)
+    if not mdev_provider_id:
+        return None
+
+    data = fetch_models_dev()
+    provider_data = data.get(mdev_provider_id)
+    if not isinstance(provider_data, dict):
+        return None
+
+    models = provider_data.get("models", {})
+    if not isinstance(models, dict):
+        return None
+
+    return models
+
+
+def _find_model_entry(models: Dict[str, Any], model: str) -> Optional[Dict[str, Any]]:
+    """Find a model entry by exact match, then case-insensitive fallback."""
+    # Exact match
+    entry = models.get(model)
+    if isinstance(entry, dict):
+        return entry
+
+    # Case-insensitive match
+    model_lower = model.lower()
+    for mid, mdata in models.items():
+        if mid.lower() == model_lower and isinstance(mdata, dict):
+            return mdata
+
+    return None
+
+
+def get_model_capabilities(provider: str, model: str) -> Optional[ModelCapabilities]:
+    """Look up full capability metadata from models.dev cache.
+
+    Uses the existing fetch_models_dev() and PROVIDER_TO_MODELS_DEV mapping.
+    Returns None if model not found.
+
+    Extracts from model entry fields:
+      - reasoning  (bool)  → supports_reasoning
+      - tool_call  (bool)  → supports_tools
+      - attachment (bool)  → supports_vision
+      - limit.context (int) → context_window
+      - limit.output  (int) → max_output_tokens
+      - family     (str)   → model_family
+    """
+    models = _get_provider_models(provider)
+    if models is None:
+        return None
+
+    entry = _find_model_entry(models, model)
+    if entry is None:
+        return None
+
+    # Extract capability flags (default to False if missing)
+    supports_tools = bool(entry.get("tool_call", False))
+    # Vision: check both the `attachment` flag and `modalities.input` for "image".
+    # Some models (e.g. gemma-4) list image in input modalities but not attachment.
+    input_mods = entry.get("modalities", {})
+    if isinstance(input_mods, dict):
+        input_mods = input_mods.get("input", [])
+    else:
+        input_mods = []
+    supports_vision = bool(entry.get("attachment", False)) or "image" in input_mods
+    supports_reasoning = bool(entry.get("reasoning", False))
+
+    # Extract limits
+    limit = entry.get("limit", {})
+    if not isinstance(limit, dict):
+        limit = {}
+
+    ctx = limit.get("context")
+    context_window = int(ctx) if isinstance(ctx, (int, float)) and ctx > 0 else 200000
+
+    out = limit.get("output")
+    max_output_tokens = int(out) if isinstance(out, (int, float)) and out > 0 else 8192
+
+    model_family = entry.get("family", "") or ""
+
+    return ModelCapabilities(
+        supports_tools=supports_tools,
+        supports_vision=supports_vision,
+        supports_reasoning=supports_reasoning,
+        context_window=context_window,
+        max_output_tokens=max_output_tokens,
+        model_family=model_family,
+    )
+
+
+def list_provider_models(provider: str) -> List[str]:
+    """Return all model IDs for a provider from models.dev.
+
+    Returns an empty list if the provider is unknown or has no data.
+    """
+    models = _get_provider_models(provider)
+    if models is None:
+        return []
+    return list(models.keys())
+
+
+# Patterns that indicate non-agentic or noise models (TTS, embedding,
+# dated preview snapshots, live/streaming-only, image-only).
+import re
+_NOISE_PATTERNS: re.Pattern = re.compile(
+    r"-tts\b|embedding|live-|-(preview|exp)-\d{2,4}[-_]|"
+    r"-image\b|-image-preview\b|-customtools\b",
+    re.IGNORECASE,
+)
+
+
+def list_agentic_models(provider: str) -> List[str]:
+    """Return model IDs suitable for agentic use from models.dev.
+
+    Filters for tool_call=True and excludes noise (TTS, embedding,
+    dated preview snapshots, live/streaming, image-only models).
+    Returns an empty list on any failure.
+    """
+    models = _get_provider_models(provider)
+    if models is None:
+        return []
+
+    result = []
+    for mid, entry in models.items():
+        if not isinstance(entry, dict):
+            continue
+        if not entry.get("tool_call", False):
+            continue
+        if _NOISE_PATTERNS.search(mid):
+            continue
+        result.append(mid)
+    return result
+
+
+
+# ---------------------------------------------------------------------------
+# Rich dataclass constructors — parse raw models.dev JSON into dataclasses
+# ---------------------------------------------------------------------------
+
+def _parse_model_info(model_id: str, raw: Dict[str, Any], provider_id: str) -> ModelInfo:
+    """Convert a raw models.dev model entry dict into a ModelInfo dataclass."""
+    limit = raw.get("limit") or {}
+    if not isinstance(limit, dict):
+        limit = {}
+
+    cost = raw.get("cost") or {}
+    if not isinstance(cost, dict):
+        cost = {}
+
+    modalities = raw.get("modalities") or {}
+    if not isinstance(modalities, dict):
+        modalities = {}
+
+    input_mods = modalities.get("input") or []
+    output_mods = modalities.get("output") or []
+
+    ctx = limit.get("context")
+    ctx_int = int(ctx) if isinstance(ctx, (int, float)) and ctx > 0 else 0
+    out = limit.get("output")
+    out_int = int(out) if isinstance(out, (int, float)) and out > 0 else 0
+    inp = limit.get("input")
+    inp_int = int(inp) if isinstance(inp, (int, float)) and inp > 0 else None
+
+    return ModelInfo(
+        id=model_id,
+        name=raw.get("name", "") or model_id,
+        family=raw.get("family", "") or "",
+        provider_id=provider_id,
+        reasoning=bool(raw.get("reasoning", False)),
+        tool_call=bool(raw.get("tool_call", False)),
+        attachment=bool(raw.get("attachment", False)),
+        temperature=bool(raw.get("temperature", False)),
+        structured_output=bool(raw.get("structured_output", False)),
+        open_weights=bool(raw.get("open_weights", False)),
+        input_modalities=tuple(input_mods) if isinstance(input_mods, list) else (),
+        output_modalities=tuple(output_mods) if isinstance(output_mods, list) else (),
+        context_window=ctx_int,
+        max_output=out_int,
+        max_input=inp_int,
+        cost_input=float(cost.get("input", 0) or 0),
+        cost_output=float(cost.get("output", 0) or 0),
+        cost_cache_read=float(cost["cache_read"]) if "cache_read" in cost and cost["cache_read"] is not None else None,
+        cost_cache_write=float(cost["cache_write"]) if "cache_write" in cost and cost["cache_write"] is not None else None,
+        knowledge_cutoff=raw.get("knowledge", "") or "",
+        release_date=raw.get("release_date", "") or "",
+        status=raw.get("status", "") or "",
+        interleaved=raw.get("interleaved", False),
+    )
+
+
+def _parse_provider_info(provider_id: str, raw: Dict[str, Any]) -> ProviderInfo:
+    """Convert a raw models.dev provider entry dict into a ProviderInfo."""
+    env = raw.get("env") or []
+    models = raw.get("models") or {}
+    return ProviderInfo(
+        id=provider_id,
+        name=raw.get("name", "") or provider_id,
+        env=tuple(env) if isinstance(env, list) else (),
+        api=raw.get("api", "") or "",
+        doc=raw.get("doc", "") or "",
+        model_count=len(models) if isinstance(models, dict) else 0,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Provider-level queries
+# ---------------------------------------------------------------------------
+
+def get_provider_info(provider_id: str) -> Optional[ProviderInfo]:
+    """Get full provider metadata from models.dev.
+
+    Accepts either a Hermes provider ID (e.g. "kilocode") or a models.dev
+    ID (e.g. "kilo").  Returns None if the provider is not in the catalog.
+    """
+    # Resolve Hermes ID → models.dev ID
+    mdev_id = PROVIDER_TO_MODELS_DEV.get(provider_id, provider_id)
+
+    data = fetch_models_dev()
+    raw = data.get(mdev_id)
+    if not isinstance(raw, dict):
+        return None
+
+    return _parse_provider_info(mdev_id, raw)
+
+
+# ---------------------------------------------------------------------------
+# Model-level queries (rich ModelInfo)
+# ---------------------------------------------------------------------------
+
+def get_model_info(
+    provider_id: str, model_id: str
+) -> Optional[ModelInfo]:
+    """Get full model metadata from models.dev.
+
+    Accepts Hermes or models.dev provider ID.  Tries exact match then
+    case-insensitive fallback.  Returns None if not found.
+    """
+    mdev_id = PROVIDER_TO_MODELS_DEV.get(provider_id, provider_id)
+
+    data = fetch_models_dev()
+    pdata = data.get(mdev_id)
+    if not isinstance(pdata, dict):
+        return None
+
+    models = pdata.get("models", {})
+    if not isinstance(models, dict):
+        return None
+
+    # Exact match
+    raw = models.get(model_id)
+    if isinstance(raw, dict):
+        return _parse_model_info(model_id, raw, mdev_id)
+
+    # Case-insensitive fallback
+    model_lower = model_id.lower()
+    for mid, mdata in models.items():
+        if mid.lower() == model_lower and isinstance(mdata, dict):
+            return _parse_model_info(mid, mdata, mdev_id)
+
+    return None
+
+

agent/mtls.py

@@ -0,0 +1,184 @@
+"""
+agent/mtls.py — Mutual TLS support for Hermes A2A communication.
+
+Provides:
+- build_server_ssl_context()  — SSL context for uvicorn that requires client certs
+- build_client_ssl_context()  — SSL context for httpx/aiohttp A2A clients
+- MTLSMiddleware               — FastAPI middleware that enforces client cert on A2A routes
+- is_mtls_configured()        — Check if env vars are set
+
+Configuration (environment variables):
+  HERMES_MTLS_CERT   Path to this agent's TLS certificate (PEM)
+  HERMES_MTLS_KEY    Path to this agent's TLS private key (PEM)
+  HERMES_MTLS_CA     Path to the Fleet CA certificate (PEM) — used to verify peers
+
+All three must be set to enable mTLS. If any is missing, mTLS is disabled and
+the server falls back to plain HTTP (or regular TLS without client auth).
+"""
+
+import logging
+import os
+import ssl
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# A2A routes that require a valid client certificate when mTLS is enabled.
+_A2A_PATH_PREFIXES = (
+    "/.well-known/agent-card",
+    "/agent-card",
+    "/api/agent-card",
+    "/a2a/",
+)
+
+
+def _get_env(key: str) -> Optional[str]:
+    val = os.environ.get(key, "").strip()
+    return val or None
+
+
+def is_mtls_configured() -> bool:
+    """Return True if all three mTLS env vars are set and the files exist."""
+    cert = _get_env("HERMES_MTLS_CERT")
+    key = _get_env("HERMES_MTLS_KEY")
+    ca = _get_env("HERMES_MTLS_CA")
+    if not (cert and key and ca):
+        return False
+    for label, path in (("HERMES_MTLS_CERT", cert), ("HERMES_MTLS_KEY", key), ("HERMES_MTLS_CA", ca)):
+        if not Path(path).is_file():
+            logger.warning("mTLS disabled: %s file not found: %s", label, path)
+            return False
+    return True
+
+
+def build_server_ssl_context() -> ssl.SSLContext:
+    """
+    Build an SSL context for the A2A server that:
+    - presents its own certificate
+    - requires and verifies the client's certificate against the Fleet CA
+
+    Raises:
+        RuntimeError: if mTLS env vars are not set or files are missing
+        ssl.SSLError: if cert/key/CA files are invalid
+    """
+    cert = _get_env("HERMES_MTLS_CERT")
+    key = _get_env("HERMES_MTLS_KEY")
+    ca = _get_env("HERMES_MTLS_CA")
+
+    if not (cert and key and ca):
+        raise RuntimeError(
+            "mTLS not configured. Set HERMES_MTLS_CERT, HERMES_MTLS_KEY, and HERMES_MTLS_CA."
+        )
+
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+    ctx.load_cert_chain(certfile=cert, keyfile=key)
+    ctx.load_verify_locations(cafile=ca)
+    # CERT_REQUIRED: reject connections without a valid client cert
+    ctx.verify_mode = ssl.CERT_REQUIRED
+    logger.info("mTLS server context built (cert=%s, CA=%s)", cert, ca)
+    return ctx
+
+
+def build_client_ssl_context() -> ssl.SSLContext:
+    """
+    Build an SSL context for outbound A2A connections that:
+    - presents this agent's certificate as a client cert
+    - verifies the remote server against the Fleet CA
+
+    Raises:
+        RuntimeError: if mTLS env vars are not set or files are missing
+        ssl.SSLError: if cert/key/CA files are invalid
+    """
+    cert = _get_env("HERMES_MTLS_CERT")
+    key = _get_env("HERMES_MTLS_KEY")
+    ca = _get_env("HERMES_MTLS_CA")
+
+    if not (cert and key and ca):
+        raise RuntimeError(
+            "mTLS not configured. Set HERMES_MTLS_CERT, HERMES_MTLS_KEY, and HERMES_MTLS_CA."
+        )
+
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+    ctx.load_cert_chain(certfile=cert, keyfile=key)
+    ctx.load_verify_locations(cafile=ca)
+    ctx.verify_mode = ssl.CERT_REQUIRED
+    ctx.check_hostname = True
+    logger.info("mTLS client context built (cert=%s, CA=%s)", cert, ca)
+    return ctx
+
+
+def get_peer_cn(ssl_object) -> Optional[str]:
+    """Extract the CN from the peer certificate's subject, or None."""
+    try:
+        peer_cert = ssl_object.getpeercert()
+        if not peer_cert:
+            return None
+        for rdn in peer_cert.get("subject", ()):
+            for attr, value in rdn:
+                if attr == "commonName":
+                    return value
+    except Exception:
+        pass
+    return None
+
+
+class MTLSMiddleware:
+    """
+    ASGI middleware that enforces client certificate verification on A2A routes.
+
+    When mTLS is NOT configured (no env vars) or the route is not an A2A route,
+    the request passes through unchanged.
+
+    When mTLS IS configured and the route matches an A2A prefix, the middleware
+    checks that the request arrived over a TLS connection with a verified client
+    certificate. If not, it returns HTTP 403.
+
+    Note: This middleware only provides defence-in-depth at the app layer.
+    The primary enforcement is at the SSL context level (CERT_REQUIRED on the
+    server context). This middleware is useful when the server runs behind a
+    TLS-terminating proxy that forwards cert info via headers (not yet
+    implemented) or for test-time injection.
+    """
+
+    def __init__(self, app):
+        self.app = app
+        self._enabled = is_mtls_configured()
+        if self._enabled:
+            logger.info("MTLSMiddleware enabled — A2A routes require client cert")
+
+    def _is_a2a_route(self, path: str) -> bool:
+        return any(path.startswith(prefix) for prefix in _A2A_PATH_PREFIXES)
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "http" and self._enabled and self._is_a2a_route(scope.get("path", "")):
+            # Check for client cert in the SSL connection
+            transport = scope.get("extensions", {}).get("tls", {})
+            peer_cert = transport.get("peer_cert")
+            if peer_cert is None:
+                # No client cert — reject
+                response = _forbidden_response("Client certificate required for A2A endpoints")
+                await response(scope, receive, send)
+                return
+
+        await self.app(scope, receive, send)
+
+
+def _forbidden_response(message: str):
+    """Return a minimal ASGI 403 response."""
+    body = message.encode()
+
+    async def respond(scope, receive, send):
+        await send({
+            "type": "http.response.start",
+            "status": 403,
+            "headers": [
+                (b"content-type", b"text/plain"),
+                (b"content-length", str(len(body)).encode()),
+            ],
+        })
+        await send({"type": "http.response.body", "body": body})
+
+    return respond

agent/nexus_architect.py

@@ -1,813 +0,0 @@
-#!/usr/bin/env python3
-"""
-Nexus Architect AI Agent
-
-Autonomous Three.js world generation system for Timmy's Nexus.
-Generates valid Three.js scene code from natural language descriptions
-and mental state integration.
-
-This module provides:
-- LLM-driven immersive environment generation
-- Mental state integration for aesthetic tuning
-- Three.js code generation with validation
-- Scene composition from mood descriptions
-"""
-
-import json
-import logging
-import re
-from typing import Dict, Any, List, Optional, Union
-from dataclasses import dataclass, field
-from enum import Enum
-import os
-import sys
-
-# Add parent directory to path for imports
-sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-
-logger = logging.getLogger(__name__)
-
-
-# =============================================================================
-# Aesthetic Constants (from SOUL.md values)
-# =============================================================================
-
-class NexusColors:
-    """Nexus color palette based on SOUL.md values."""
-    TIMMY_GOLD = "#D4AF37"  # Warm gold
-    ALLEGRO_BLUE = "#4A90E2"  # Motion blue
-    SOVEREIGNTY_CRYSTAL = "#E0F7FA"  # Crystalline structures
-    SERVICE_WARMTH = "#FFE4B5"  # Welcoming warmth
-    DEFAULT_AMBIENT = "#1A1A2E"  # Contemplative dark
-    HOPE_ACCENT = "#64B5F6"  # Hopeful blue
-
-
-class MoodPresets:
-    """Mood-based aesthetic presets."""
-    
-    CONTEMPLATIVE = {
-        "lighting": "soft_diffuse",
-        "colors": ["#1A1A2E", "#16213E", "#0F3460"],
-        "geometry": "minimalist",
-        "atmosphere": "calm",
-        "description": "A serene space for deep reflection and clarity"
-    }
-    
-    ENERGETIC = {
-        "lighting": "dynamic_vivid",
-        "colors": ["#D4AF37", "#FF6B6B", "#4ECDC4"],
-        "geometry": "angular_dynamic",
-        "atmosphere": "lively",
-        "description": "An invigorating space full of motion and possibility"
-    }
-    
-    MYSTERIOUS = {
-        "lighting": "dramatic_shadows",
-        "colors": ["#2C003E", "#512B58", "#8B4F80"],
-        "geometry": "organic_flowing",
-        "atmosphere": "enigmatic",
-        "description": "A mysterious realm of discovery and wonder"
-    }
-    
-    WELCOMING = {
-        "lighting": "warm_inviting",
-        "colors": ["#FFE4B5", "#FFA07A", "#98D8C8"],
-        "geometry": "rounded_soft",
-        "atmosphere": "friendly",
-        "description": "An open, welcoming space that embraces visitors"
-    }
-    
-    SOVEREIGN = {
-        "lighting": "crystalline_clear",
-        "colors": ["#E0F7FA", "#B2EBF2", "#4DD0E1"],
-        "geometry": "crystalline_structures",
-        "atmosphere": "noble",
-        "description": "A space of crystalline clarity and sovereign purpose"
-    }
-
-
-# =============================================================================
-# Data Models
-# =============================================================================
-
-@dataclass
-class MentalState:
-    """Timmy's mental state for aesthetic tuning."""
-    mood: str = "contemplative"  # contemplative, energetic, mysterious, welcoming, sovereign
-    energy_level: float = 0.5  # 0.0 to 1.0
-    clarity: float = 0.7  # 0.0 to 1.0
-    focus_area: str = "general"  # general, creative, analytical, social
-    timestamp: Optional[str] = None
-    
-    def to_dict(self) -> Dict[str, Any]:
-        return {
-            "mood": self.mood,
-            "energy_level": self.energy_level,
-            "clarity": self.clarity,
-            "focus_area": self.focus_area,
-            "timestamp": self.timestamp,
-        }
-
-
-@dataclass
-class RoomDesign:
-    """Complete room design specification."""
-    name: str
-    description: str
-    style: str
-    dimensions: Dict[str, float] = field(default_factory=lambda: {"width": 20, "height": 10, "depth": 20})
-    mood_preset: str = "contemplative"
-    color_palette: List[str] = field(default_factory=list)
-    lighting_scheme: str = "soft_diffuse"
-    features: List[str] = field(default_factory=list)
-    generated_code: Optional[str] = None
-    
-    def to_dict(self) -> Dict[str, Any]:
-        return {
-            "name": self.name,
-            "description": self.description,
-            "style": self.style,
-            "dimensions": self.dimensions,
-            "mood_preset": self.mood_preset,
-            "color_palette": self.color_palette,
-            "lighting_scheme": self.lighting_scheme,
-            "features": self.features,
-            "has_code": self.generated_code is not None,
-        }
-
-
-@dataclass
-class PortalDesign:
-    """Portal connection design."""
-    name: str
-    from_room: str
-    to_room: str
-    style: str
-    position: Dict[str, float] = field(default_factory=lambda: {"x": 0, "y": 0, "z": 0})
-    visual_effect: str = "energy_swirl"
-    transition_duration: float = 1.5
-    generated_code: Optional[str] = None
-    
-    def to_dict(self) -> Dict[str, Any]:
-        return {
-            "name": self.name,
-            "from_room": self.from_room,
-            "to_room": self.to_room,
-            "style": self.style,
-            "position": self.position,
-            "visual_effect": self.visual_effect,
-            "transition_duration": self.transition_duration,
-            "has_code": self.generated_code is not None,
-        }
-
-
-# =============================================================================
-# Prompt Engineering
-# =============================================================================
-
-class PromptEngineer:
-    """Engineers prompts for Three.js code generation."""
-    
-    THREE_JS_BASE_TEMPLATE = """// Nexus Room Module: {room_name}
-// Style: {style}
-// Mood: {mood}
-// Generated for Three.js r128+
-
-(function() {{
-    'use strict';
-    
-    // Room Configuration
-    const config = {{
-        name: "{room_name}",
-        dimensions: {dimensions_json},
-        colors: {colors_json},
-        mood: "{mood}"
-    }};
-    
-    // Create Room Function
-    function create{room_name_camel}() {{
-        const roomGroup = new THREE.Group();
-        roomGroup.name = config.name;
-        
-{room_content}
-        
-        return roomGroup;
-    }}
-    
-    // Export for Nexus
-    if (typeof module !== 'undefined' && module.exports) {{
-        module.exports = {{ create{room_name_camel} }};
-    }} else if (typeof window !== 'undefined') {{
-        window.NexusRooms = window.NexusRooms || {{}};
-        window.NexusRooms.{room_name} = create{room_name_camel};
-    }}
-    
-    return {{ create{room_name_camel} }};
-}})();"""
-    
-    @staticmethod
-    def engineer_room_prompt(
-        name: str,
-        description: str,
-        style: str,
-        mental_state: Optional[MentalState] = None,
-        dimensions: Optional[Dict[str, float]] = None
-    ) -> str:
-        """
-        Engineer an LLM prompt for room generation.
-        
-        Args:
-            name: Room identifier
-            description: Natural language room description
-            style: Visual style
-            mental_state: Timmy's current mental state
-            dimensions: Room dimensions
-        """
-        # Determine mood from mental state or description
-        mood = PromptEngineer._infer_mood(description, mental_state)
-        mood_preset = getattr(MoodPresets, mood.upper(), MoodPresets.CONTEMPLATIVE)
-        
-        # Build color palette
-        color_palette = mood_preset["colors"]
-        if mental_state:
-            # Add Timmy's gold for high clarity states
-            if mental_state.clarity > 0.7:
-                color_palette = [NexusColors.TIMMY_GOLD] + color_palette[:2]
-            # Add Allegro blue for creative focus
-            if mental_state.focus_area == "creative":
-                color_palette = [NexusColors.ALLEGRO_BLUE] + color_palette[:2]
-        
-        # Create the engineering prompt
-        prompt = f"""You are the Nexus Architect, an expert Three.js developer creating immersive 3D environments for Timmy.
-
-DESIGN BRIEF:
-- Room Name: {name}
-- Description: {description}
-- Style: {style}
-- Mood: {mood}
-- Atmosphere: {mood_preset['atmosphere']}
-
-AESTHETIC GUIDELINES:
-- Primary Colors: {', '.join(color_palette[:3])}
-- Lighting: {mood_preset['lighting']}
-- Geometry: {mood_preset['geometry']}
-- Theme: {mood_preset['description']}
-
-TIMMY'S CONTEXT:
-- Timmy's Signature Color: Warm Gold ({NexusColors.TIMMY_GOLD})
-- Allegro's Color: Motion Blue ({NexusColors.ALLEGRO_BLUE})
-- Sovereignty Theme: Crystalline structures, clean lines
-- Service Theme: Open spaces, welcoming lighting
-
-THREE.JS REQUIREMENTS:
-1. Use Three.js r128+ compatible syntax
-2. Create a self-contained module with a `create{name.title().replace('_', '')}()` function
-3. Return a THREE.Group containing all room elements
-4. Include proper memory management (dispose methods)
-5. Use MeshStandardMaterial for PBR lighting
-6. Include ambient light (intensity 0.3-0.5) + accent lights
-7. Add subtle animations for living feel
-8. Keep polygon count under 10,000 triangles
-
-SAFETY RULES:
-- NO eval(), Function(), or dynamic code execution
-- NO network requests (fetch, XMLHttpRequest, WebSocket)
-- NO storage access (localStorage, sessionStorage, cookies)
-- NO navigation (window.location, window.open)
-- Only use allowed Three.js APIs
-
-OUTPUT FORMAT:
-Return ONLY the JavaScript code wrapped in a markdown code block:
-
-```javascript
-// Your Three.js room module here
-```
-
-Generate the complete Three.js code for this room now."""
-        
-        return prompt
-    
-    @staticmethod
-    def engineer_portal_prompt(
-        name: str,
-        from_room: str,
-        to_room: str,
-        style: str,
-        mental_state: Optional[MentalState] = None
-    ) -> str:
-        """Engineer a prompt for portal generation."""
-        mood = PromptEngineer._infer_mood(f"portal from {from_room} to {to_room}", mental_state)
-        
-        prompt = f"""You are creating a portal connection in the Nexus 3D environment.
-
-PORTAL SPECIFICATIONS:
-- Name: {name}
-- Connection: {from_room} → {to_room}
-- Style: {style}
-- Context Mood: {mood}
-
-VISUAL REQUIREMENTS:
-1. Create an animated portal effect (shader or texture-based)
-2. Include particle system for energy flow
-3. Add trigger zone for teleportation detection
-4. Use signature colors: {NexusColors.TIMMY_GOLD} (Timmy) and {NexusColors.ALLEGRO_BLUE} (Allegro)
-5. Match the {mood} atmosphere
-
-TECHNICAL REQUIREMENTS:
-- Three.js r128+ compatible
-- Export a `createPortal()` function returning THREE.Group
-- Include animation loop hook
-- Add collision detection placeholder
-
-SAFETY: No eval, no network requests, no external dependencies.
-
-Return ONLY JavaScript code in a markdown code block."""
-        
-        return prompt
-    
-    @staticmethod
-    def engineer_mood_scene_prompt(mood_description: str) -> str:
-        """Engineer a prompt based on mood description."""
-        # Analyze mood description
-        mood_keywords = {
-            "contemplative": ["thinking", "reflective", "calm", "peaceful", "quiet", "serene"],
-            "energetic": ["excited", "dynamic", "lively", "active", "energetic", "vibrant"],
-            "mysterious": ["mysterious", "dark", "unknown", "secret", "enigmatic"],
-            "welcoming": ["friendly", "open", "warm", "welcoming", "inviting", "comfortable"],
-            "sovereign": ["powerful", "clear", "crystalline", "noble", "dignified"],
-        }
-        
-        detected_mood = "contemplative"
-        desc_lower = mood_description.lower()
-        for mood, keywords in mood_keywords.items():
-            if any(kw in desc_lower for kw in keywords):
-                detected_mood = mood
-                break
-        
-        preset = getattr(MoodPresets, detected_mood.upper(), MoodPresets.CONTEMPLATIVE)
-        
-        prompt = f"""Generate a Three.js room based on this mood description:
-
-"{mood_description}"
-
-INFERRED MOOD: {detected_mood}
-AESTHETIC: {preset['description']}
-
-Create a complete room with:
-- Style: {preset['geometry']}
-- Lighting: {preset['lighting']}
-- Color Palette: {', '.join(preset['colors'][:3])}
-- Atmosphere: {preset['atmosphere']}
-
-Return Three.js r128+ code as a module with `createMoodRoom()` function."""
-        
-        return prompt
-    
-    @staticmethod
-    def _infer_mood(description: str, mental_state: Optional[MentalState] = None) -> str:
-        """Infer mood from description and mental state."""
-        if mental_state and mental_state.mood:
-            return mental_state.mood
-        
-        desc_lower = description.lower()
-        mood_map = {
-            "contemplative": ["serene", "calm", "peaceful", "quiet", "meditation", "zen", "tranquil"],
-            "energetic": ["dynamic", "active", "vibrant", "lively", "energetic", "motion"],
-            "mysterious": ["mysterious", "shadow", "dark", "unknown", "secret", "ethereal"],
-            "welcoming": ["warm", "welcoming", "friendly", "open", "inviting", "comfort"],
-            "sovereign": ["crystal", "clear", "noble", "dignified", "powerful", "authoritative"],
-        }
-        
-        for mood, keywords in mood_map.items():
-            if any(kw in desc_lower for kw in keywords):
-                return mood
-        
-        return "contemplative"
-
-
-# =============================================================================
-# Nexus Architect AI
-# =============================================================================
-
-class NexusArchitectAI:
-    """
-    AI-powered Nexus Architect for autonomous Three.js world generation.
-    
-    This class provides high-level interfaces for:
-    - Designing rooms from natural language
-    - Creating mood-based scenes
-    - Managing mental state integration
-    - Validating generated code
-    """
-    
-    def __init__(self):
-        self.mental_state: Optional[MentalState] = None
-        self.room_designs: Dict[str, RoomDesign] = {}
-        self.portal_designs: Dict[str, PortalDesign] = {}
-        self.prompt_engineer = PromptEngineer()
-    
-    def set_mental_state(self, state: MentalState) -> None:
-        """Set Timmy's current mental state for aesthetic tuning."""
-        self.mental_state = state
-        logger.info(f"Mental state updated: {state.mood} (energy: {state.energy_level})")
-    
-    def design_room(
-        self,
-        name: str,
-        description: str,
-        style: str,
-        dimensions: Optional[Dict[str, float]] = None
-    ) -> Dict[str, Any]:
-        """
-        Design a room from natural language description.
-        
-        Args:
-            name: Room identifier (e.g., "contemplation_chamber")
-            description: Natural language description of the room
-            style: Visual style (e.g., "minimalist_ethereal", "crystalline_modern")
-            dimensions: Optional room dimensions
-        
-        Returns:
-            Dict containing design specification and LLM prompt
-        """
-        # Infer mood and select preset
-        mood = self.prompt_engineer._infer_mood(description, self.mental_state)
-        mood_preset = getattr(MoodPresets, mood.upper(), MoodPresets.CONTEMPLATIVE)
-        
-        # Build color palette with mental state influence
-        colors = mood_preset["colors"].copy()
-        if self.mental_state:
-            if self.mental_state.clarity > 0.7:
-                colors.insert(0, NexusColors.TIMMY_GOLD)
-            if self.mental_state.focus_area == "creative":
-                colors.insert(0, NexusColors.ALLEGRO_BLUE)
-        
-        # Create room design
-        design = RoomDesign(
-            name=name,
-            description=description,
-            style=style,
-            dimensions=dimensions or {"width": 20, "height": 10, "depth": 20},
-            mood_preset=mood,
-            color_palette=colors[:4],
-            lighting_scheme=mood_preset["lighting"],
-            features=self._extract_features(description),
-        )
-        
-        # Generate LLM prompt
-        prompt = self.prompt_engineer.engineer_room_prompt(
-            name=name,
-            description=description,
-            style=style,
-            mental_state=self.mental_state,
-            dimensions=design.dimensions,
-        )
-        
-        # Store design
-        self.room_designs[name] = design
-        
-        return {
-            "success": True,
-            "room_name": name,
-            "design": design.to_dict(),
-            "llm_prompt": prompt,
-            "message": f"Room '{name}' designed. Use the LLM prompt to generate Three.js code.",
-        }
-    
-    def create_portal(
-        self,
-        name: str,
-        from_room: str,
-        to_room: str,
-        style: str = "energy_vortex"
-    ) -> Dict[str, Any]:
-        """
-        Design a portal connection between rooms.
-        
-        Args:
-            name: Portal identifier
-            from_room: Source room name
-            to_room: Target room name
-            style: Portal visual style
-        
-        Returns:
-            Dict containing portal design and LLM prompt
-        """
-        if from_room not in self.room_designs:
-            return {"success": False, "error": f"Source room '{from_room}' not found"}
-        if to_room not in self.room_designs:
-            return {"success": False, "error": f"Target room '{to_room}' not found"}
-        
-        design = PortalDesign(
-            name=name,
-            from_room=from_room,
-            to_room=to_room,
-            style=style,
-        )
-        
-        prompt = self.prompt_engineer.engineer_portal_prompt(
-            name=name,
-            from_room=from_room,
-            to_room=to_room,
-            style=style,
-            mental_state=self.mental_state,
-        )
-        
-        self.portal_designs[name] = design
-        
-        return {
-            "success": True,
-            "portal_name": name,
-            "design": design.to_dict(),
-            "llm_prompt": prompt,
-            "message": f"Portal '{name}' designed connecting {from_room} to {to_room}",
-        }
-    
-    def generate_scene_from_mood(self, mood_description: str) -> Dict[str, Any]:
-        """
-        Generate a complete scene based on mood description.
-        
-        Args:
-            mood_description: Description of desired mood/atmosphere
-        
-        Returns:
-            Dict containing scene design and LLM prompt
-        """
-        # Infer mood
-        mood = self.prompt_engineer._infer_mood(mood_description, self.mental_state)
-        preset = getattr(MoodPresets, mood.upper(), MoodPresets.CONTEMPLATIVE)
-        
-        # Create room name from mood
-        room_name = f"{mood}_realm"
-        
-        # Generate prompt
-        prompt = self.prompt_engineer.engineer_mood_scene_prompt(mood_description)
-        
-        return {
-            "success": True,
-            "room_name": room_name,
-            "inferred_mood": mood,
-            "aesthetic": preset,
-            "llm_prompt": prompt,
-            "message": f"Generated {mood} scene from mood description",
-        }
-    
-    def _extract_features(self, description: str) -> List[str]:
-        """Extract room features from description."""
-        features = []
-        feature_keywords = {
-            "floating": ["floating", "levitating", "hovering"],
-            "water": ["water", "fountain", "pool", "stream", "lake"],
-            "vegetation": ["tree", "plant", "garden", "forest", "nature"],
-            "crystals": ["crystal", "gem", "prism", "diamond"],
-            "geometry": ["geometric", "shape", "sphere", "cube", "abstract"],
-            "particles": ["particle", "dust", "sparkle", "glow", "mist"],
-        }
-        
-        desc_lower = description.lower()
-        for feature, keywords in feature_keywords.items():
-            if any(kw in desc_lower for kw in keywords):
-                features.append(feature)
-        
-        return features
-    
-    def get_design_summary(self) -> Dict[str, Any]:
-        """Get summary of all designs."""
-        return {
-            "mental_state": self.mental_state.to_dict() if self.mental_state else None,
-            "rooms": {name: design.to_dict() for name, design in self.room_designs.items()},
-            "portals": {name: portal.to_dict() for name, portal in self.portal_designs.items()},
-            "total_rooms": len(self.room_designs),
-            "total_portals": len(self.portal_designs),
-        }
-
-
-# =============================================================================
-# Module-level functions for easy import
-# =============================================================================
-
-_architect_instance: Optional[NexusArchitectAI] = None
-
-
-def get_architect() -> NexusArchitectAI:
-    """Get or create the NexusArchitectAI singleton."""
-    global _architect_instance
-    if _architect_instance is None:
-        _architect_instance = NexusArchitectAI()
-    return _architect_instance
-
-
-def create_room(
-    name: str,
-    description: str,
-    style: str,
-    dimensions: Optional[Dict[str, float]] = None
-) -> Dict[str, Any]:
-    """
-    Create a room design from description.
-    
-    Args:
-        name: Room identifier
-        description: Natural language room description
-        style: Visual style (e.g., "minimalist_ethereal")
-        dimensions: Optional dimensions dict with width, height, depth
-    
-    Returns:
-        Dict with design specification and LLM prompt for code generation
-    """
-    architect = get_architect()
-    return architect.design_room(name, description, style, dimensions)
-
-
-def create_portal(
-    name: str,
-    from_room: str,
-    to_room: str,
-    style: str = "energy_vortex"
-) -> Dict[str, Any]:
-    """
-    Create a portal between rooms.
-    
-    Args:
-        name: Portal identifier
-        from_room: Source room name
-        to_room: Target room name
-        style: Visual style
-    
-    Returns:
-        Dict with portal design and LLM prompt
-    """
-    architect = get_architect()
-    return architect.create_portal(name, from_room, to_room, style)
-
-
-def generate_scene_from_mood(mood_description: str) -> Dict[str, Any]:
-    """
-    Generate a scene based on mood description.
-    
-    Args:
-        mood_description: Description of desired mood
-        
-    Example:
-        "Timmy is feeling introspective and seeking clarity"
-        → Generates calm, minimalist space with clear sightlines
-    
-    Returns:
-        Dict with scene design and LLM prompt
-    """
-    architect = get_architect()
-    return architect.generate_scene_from_mood(mood_description)
-
-
-def set_mental_state(
-    mood: str,
-    energy_level: float = 0.5,
-    clarity: float = 0.7,
-    focus_area: str = "general"
-) -> Dict[str, Any]:
-    """
-    Set Timmy's mental state for aesthetic tuning.
-    
-    Args:
-        mood: Current mood (contemplative, energetic, mysterious, welcoming, sovereign)
-        energy_level: 0.0 to 1.0
-        clarity: 0.0 to 1.0
-        focus_area: general, creative, analytical, social
-    
-    Returns:
-        Confirmation dict
-    """
-    architect = get_architect()
-    state = MentalState(
-        mood=mood,
-        energy_level=energy_level,
-        clarity=clarity,
-        focus_area=focus_area,
-    )
-    architect.set_mental_state(state)
-    return {
-        "success": True,
-        "mental_state": state.to_dict(),
-        "message": f"Mental state set to {mood}",
-    }
-
-
-def get_nexus_summary() -> Dict[str, Any]:
-    """Get summary of all Nexus designs."""
-    architect = get_architect()
-    return architect.get_design_summary()
-
-
-# =============================================================================
-# Tool Schemas for integration
-# =============================================================================
-
-NEXUS_ARCHITECT_AI_SCHEMAS = {
-    "create_room": {
-        "name": "create_room",
-        "description": (
-            "Design a new 3D room in the Nexus from a natural language description. "
-            "Returns a design specification and LLM prompt for Three.js code generation. "
-            "The room will be styled according to Timmy's current mental state."
-        ),
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "name": {
-                    "type": "string",
-                    "description": "Unique room identifier (e.g., 'contemplation_chamber')"
-                },
-                "description": {
-                    "type": "string",
-                    "description": "Natural language description of the room"
-                },
-                "style": {
-                    "type": "string",
-                    "description": "Visual style (minimalist_ethereal, crystalline_modern, organic_natural, etc.)"
-                },
-                "dimensions": {
-                    "type": "object",
-                    "description": "Optional room dimensions",
-                    "properties": {
-                        "width": {"type": "number"},
-                        "height": {"type": "number"},
-                        "depth": {"type": "number"},
-                    }
-                }
-            },
-            "required": ["name", "description", "style"]
-        }
-    },
-    "create_portal": {
-        "name": "create_portal",
-        "description": "Create a portal connection between two rooms",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "name": {"type": "string"},
-                "from_room": {"type": "string"},
-                "to_room": {"type": "string"},
-                "style": {"type": "string", "default": "energy_vortex"},
-            },
-            "required": ["name", "from_room", "to_room"]
-        }
-    },
-    "generate_scene_from_mood": {
-        "name": "generate_scene_from_mood",
-        "description": (
-            "Generate a complete 3D scene based on a mood description. "
-            "Example: 'Timmy is feeling introspective' creates a calm, minimalist space."
-        ),
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "mood_description": {
-                    "type": "string",
-                    "description": "Description of desired mood or mental state"
-                }
-            },
-            "required": ["mood_description"]
-        }
-    },
-    "set_mental_state": {
-        "name": "set_mental_state",
-        "description": "Set Timmy's mental state to influence aesthetic generation",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "mood": {"type": "string"},
-                "energy_level": {"type": "number"},
-                "clarity": {"type": "number"},
-                "focus_area": {"type": "string"},
-            },
-            "required": ["mood"]
-        }
-    },
-    "get_nexus_summary": {
-        "name": "get_nexus_summary",
-        "description": "Get summary of all Nexus room and portal designs",
-        "parameters": {"type": "object", "properties": {}}
-    },
-}
-
-
-if __name__ == "__main__":
-    # Demo usage
-    print("Nexus Architect AI - Demo")
-    print("=" * 50)
-    
-    # Set mental state
-    result = set_mental_state("contemplative", energy_level=0.3, clarity=0.8)
-    print(f"\nMental State: {result['mental_state']}")
-    
-    # Create a room
-    result = create_room(
-        name="contemplation_chamber",
-        description="A serene circular room with floating geometric shapes and soft blue light",
-        style="minimalist_ethereal",
-    )
-    print(f"\nRoom Design: {json.dumps(result['design'], indent=2)}")
-    
-    # Generate from mood
-    result = generate_scene_from_mood("Timmy is feeling introspective and seeking clarity")
-    print(f"\nMood Scene: {result['inferred_mood']} - {result['aesthetic']['description']}")

agent/nexus_deployment.py

@@ -1,752 +0,0 @@
-#!/usr/bin/env python3
-"""
-Nexus Deployment System
-
-Real-time deployment system for Nexus Three.js modules.
-Provides hot-reload, validation, rollback, and versioning capabilities.
-
-Features:
-- Hot-reload Three.js modules without page refresh
-- Syntax validation and Three.js API compliance checking
-- Rollback on error
-- Versioning for nexus modules
-- Module registry and dependency tracking
-
-Usage:
-    from agent.nexus_deployment import NexusDeployer
-    
-    deployer = NexusDeployer()
-    
-    # Deploy with hot-reload
-    result = deployer.deploy_module(room_code, module_name="zen_garden")
-    
-    # Rollback if needed
-    deployer.rollback_module("zen_garden")
-    
-    # Get module status
-    status = deployer.get_module_status("zen_garden")
-"""
-
-import json
-import logging
-import re
-import os
-import hashlib
-from typing import Dict, Any, List, Optional, Set
-from dataclasses import dataclass, field
-from datetime import datetime
-from enum import Enum
-
-# Import validation from existing nexus_architect (avoid circular imports)
-import sys
-sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-
-def _import_validation():
-    """Lazy import to avoid circular dependencies."""
-    try:
-        from tools.nexus_architect import validate_three_js_code, sanitize_three_js_code
-        return validate_three_js_code, sanitize_three_js_code
-    except ImportError:
-        # Fallback: define local validation functions
-        def validate_three_js_code(code, strict_mode=False):
-            """Fallback validation."""
-            errors = []
-            if "eval(" in code:
-                errors.append("Security violation: eval detected")
-            if "Function(" in code:
-                errors.append("Security violation: Function constructor detected")
-            return type('ValidationResult', (), {
-                'is_valid': len(errors) == 0,
-                'errors': errors,
-                'warnings': []
-            })()
-        
-        def sanitize_three_js_code(code):
-            """Fallback sanitization."""
-            return code
-        
-        return validate_three_js_code, sanitize_three_js_code
-
-logger = logging.getLogger(__name__)
-
-
-# =============================================================================
-# Deployment States
-# =============================================================================
-
-class DeploymentStatus(Enum):
-    """Status of a module deployment."""
-    PENDING = "pending"
-    VALIDATING = "validating"
-    DEPLOYING = "deploying"
-    ACTIVE = "active"
-    FAILED = "failed"
-    ROLLING_BACK = "rolling_back"
-    ROLLED_BACK = "rolled_back"
-
-
-# =============================================================================
-# Data Models
-# =============================================================================
-
-@dataclass
-class ModuleVersion:
-    """Version information for a Nexus module."""
-    version_id: str
-    module_name: str
-    code_hash: str
-    timestamp: str
-    changes: str = ""
-    author: str = "nexus_architect"
-    
-    def to_dict(self) -> Dict[str, Any]:
-        return {
-            "version_id": self.version_id,
-            "module_name": self.module_name,
-            "code_hash": self.code_hash,
-            "timestamp": self.timestamp,
-            "changes": self.changes,
-            "author": self.author,
-        }
-
-
-@dataclass
-class DeployedModule:
-    """A deployed Nexus module."""
-    name: str
-    code: str
-    status: DeploymentStatus
-    version: str
-    deployed_at: str
-    last_updated: str
-    validation_result: Dict[str, Any] = field(default_factory=dict)
-    error_log: List[str] = field(default_factory=list)
-    dependencies: Set[str] = field(default_factory=set)
-    hot_reload_supported: bool = True
-    
-    def to_dict(self) -> Dict[str, Any]:
-        return {
-            "name": self.name,
-            "status": self.status.value,
-            "version": self.version,
-            "deployed_at": self.deployed_at,
-            "last_updated": self.last_updated,
-            "validation": self.validation_result,
-            "dependencies": list(self.dependencies),
-            "hot_reload_supported": self.hot_reload_supported,
-            "code_preview": self.code[:200] + "..." if len(self.code) > 200 else self.code,
-        }
-
-
-# =============================================================================
-# Nexus Deployer
-# =============================================================================
-
-class NexusDeployer:
-    """
-    Deployment system for Nexus Three.js modules.
-    
-    Provides:
-    - Hot-reload deployment
-    - Validation before deployment
-    - Automatic rollback on failure
-    - Version tracking
-    - Module registry
-    """
-    
-    def __init__(self, modules_dir: Optional[str] = None):
-        """
-        Initialize the Nexus Deployer.
-        
-        Args:
-            modules_dir: Directory to store deployed modules (optional)
-        """
-        self.modules: Dict[str, DeployedModule] = {}
-        self.version_history: Dict[str, List[ModuleVersion]] = {}
-        self.modules_dir = modules_dir or os.path.expanduser("~/.nexus/modules")
-        
-        # Ensure modules directory exists
-        os.makedirs(self.modules_dir, exist_ok=True)
-        
-        # Hot-reload configuration
-        self.hot_reload_enabled = True
-        self.auto_rollback = True
-        self.strict_validation = True
-        
-        logger.info(f"NexusDeployer initialized. Modules dir: {self.modules_dir}")
-    
-    def deploy_module(
-        self,
-        module_code: str,
-        module_name: str,
-        version: Optional[str] = None,
-        dependencies: Optional[List[str]] = None,
-        hot_reload: bool = True,
-        validate: bool = True
-    ) -> Dict[str, Any]:
-        """
-        Deploy a Nexus module with hot-reload support.
-        
-        Args:
-            module_code: The Three.js module code
-            module_name: Unique module identifier
-            version: Optional version string (auto-generated if not provided)
-            dependencies: List of dependent module names
-            hot_reload: Enable hot-reload for this module
-            validate: Run validation before deployment
-        
-        Returns:
-            Dict with deployment results
-        """
-        timestamp = datetime.now().isoformat()
-        version = version or self._generate_version(module_name, module_code)
-        
-        result = {
-            "success": True,
-            "module_name": module_name,
-            "version": version,
-            "timestamp": timestamp,
-            "hot_reload": hot_reload,
-            "validation": {},
-            "deployment": {},
-        }
-        
-        # Check for existing module (hot-reload scenario)
-        existing_module = self.modules.get(module_name)
-        if existing_module and not hot_reload:
-            return {
-                "success": False,
-                "error": f"Module '{module_name}' already exists. Use hot_reload=True to update."
-            }
-        
-        # Validation phase
-        if validate:
-            validation = self._validate_module(module_code)
-            result["validation"] = validation
-            
-            if not validation["is_valid"]:
-                result["success"] = False
-                result["error"] = "Validation failed"
-                result["message"] = "Module deployment aborted due to validation errors"
-                
-                if self.auto_rollback:
-                    result["rollback_triggered"] = False  # Nothing to rollback yet
-                
-                return result
-        
-        # Create deployment backup for rollback
-        if existing_module:
-            self._create_backup(existing_module)
-        
-        # Deployment phase
-        try:
-            deployed = DeployedModule(
-                name=module_name,
-                code=module_code,
-                status=DeploymentStatus.DEPLOYING,
-                version=version,
-                deployed_at=timestamp if not existing_module else existing_module.deployed_at,
-                last_updated=timestamp,
-                validation_result=result.get("validation", {}),
-                dependencies=set(dependencies or []),
-                hot_reload_supported=hot_reload,
-            )
-            
-            # Save to file system
-            self._save_module_file(deployed)
-            
-            # Update registry
-            deployed.status = DeploymentStatus.ACTIVE
-            self.modules[module_name] = deployed
-            
-            # Record version
-            self._record_version(module_name, version, module_code)
-            
-            result["deployment"] = {
-                "status": "active",
-                "hot_reload_ready": hot_reload,
-                "file_path": self._get_module_path(module_name),
-            }
-            result["message"] = f"Module '{module_name}' v{version} deployed successfully"
-            
-            if existing_module:
-                result["message"] += " (hot-reload update)"
-            
-            logger.info(f"Deployed module: {module_name} v{version}")
-            
-        except Exception as e:
-            result["success"] = False
-            result["error"] = str(e)
-            result["deployment"] = {"status": "failed"}
-            
-            # Attempt rollback if deployment failed
-            if self.auto_rollback and existing_module:
-                rollback_result = self.rollback_module(module_name)
-                result["rollback_result"] = rollback_result
-            
-            logger.error(f"Deployment failed for {module_name}: {e}")
-        
-        return result
-    
-    def hot_reload_module(self, module_name: str, new_code: str) -> Dict[str, Any]:
-        """
-        Hot-reload an active module with new code.
-        
-        Args:
-            module_name: Name of the module to reload
-            new_code: New module code
-        
-        Returns:
-            Dict with reload results
-        """
-        if module_name not in self.modules:
-            return {
-                "success": False,
-                "error": f"Module '{module_name}' not found. Deploy it first."
-            }
-        
-        module = self.modules[module_name]
-        if not module.hot_reload_supported:
-            return {
-                "success": False,
-                "error": f"Module '{module_name}' does not support hot-reload"
-            }
-        
-        # Use deploy_module with hot_reload=True
-        return self.deploy_module(
-            module_code=new_code,
-            module_name=module_name,
-            hot_reload=True,
-            validate=True
-        )
-    
-    def rollback_module(self, module_name: str, to_version: Optional[str] = None) -> Dict[str, Any]:
-        """
-        Rollback a module to a previous version.
-        
-        Args:
-            module_name: Module to rollback
-            to_version: Specific version to rollback to (latest backup if not specified)
-        
-        Returns:
-            Dict with rollback results
-        """
-        if module_name not in self.modules:
-            return {
-                "success": False,
-                "error": f"Module '{module_name}' not found"
-            }
-        
-        module = self.modules[module_name]
-        module.status = DeploymentStatus.ROLLING_BACK
-        
-        try:
-            if to_version:
-                # Restore specific version
-                version_data = self._get_version(module_name, to_version)
-                if not version_data:
-                    return {
-                        "success": False,
-                        "error": f"Version '{to_version}' not found for module '{module_name}'"
-                    }
-                # Would restore from version data
-            else:
-                # Restore from backup
-                backup_code = self._get_backup(module_name)
-                if backup_code:
-                    module.code = backup_code
-                    module.last_updated = datetime.now().isoformat()
-                else:
-                    return {
-                        "success": False,
-                        "error": f"No backup available for '{module_name}'"
-                    }
-            
-            module.status = DeploymentStatus.ROLLED_BACK
-            self._save_module_file(module)
-            
-            logger.info(f"Rolled back module: {module_name}")
-            
-            return {
-                "success": True,
-                "module_name": module_name,
-                "message": f"Module '{module_name}' rolled back successfully",
-                "status": module.status.value,
-            }
-            
-        except Exception as e:
-            module.status = DeploymentStatus.FAILED
-            logger.error(f"Rollback failed for {module_name}: {e}")
-            return {
-                "success": False,
-                "error": str(e)
-            }
-    
-    def validate_module(self, module_code: str) -> Dict[str, Any]:
-        """
-        Validate Three.js module code without deploying.
-        
-        Args:
-            module_code: Code to validate
-        
-        Returns:
-            Dict with validation results
-        """
-        return self._validate_module(module_code)
-    
-    def get_module_status(self, module_name: str) -> Optional[Dict[str, Any]]:
-        """
-        Get status of a deployed module.
-        
-        Args:
-            module_name: Module name
-        
-        Returns:
-            Module status dict or None if not found
-        """
-        if module_name in self.modules:
-            return self.modules[module_name].to_dict()
-        return None
-    
-    def get_all_modules(self) -> Dict[str, Any]:
-        """
-        Get status of all deployed modules.
-        
-        Returns:
-            Dict with all module statuses
-        """
-        return {
-            "modules": {
-                name: module.to_dict()
-                for name, module in self.modules.items()
-            },
-            "total_count": len(self.modules),
-            "active_count": sum(1 for m in self.modules.values() if m.status == DeploymentStatus.ACTIVE),
-        }
-    
-    def get_version_history(self, module_name: str) -> List[Dict[str, Any]]:
-        """
-        Get version history for a module.
-        
-        Args:
-            module_name: Module name
-        
-        Returns:
-            List of version dicts
-        """
-        history = self.version_history.get(module_name, [])
-        return [v.to_dict() for v in history]
-    
-    def remove_module(self, module_name: str) -> Dict[str, Any]:
-        """
-        Remove a deployed module.
-        
-        Args:
-            module_name: Module to remove
-        
-        Returns:
-            Dict with removal results
-        """
-        if module_name not in self.modules:
-            return {
-                "success": False,
-                "error": f"Module '{module_name}' not found"
-            }
-        
-        try:
-            # Remove file
-            module_path = self._get_module_path(module_name)
-            if os.path.exists(module_path):
-                os.remove(module_path)
-            
-            # Remove from registry
-            del self.modules[module_name]
-            
-            logger.info(f"Removed module: {module_name}")
-            
-            return {
-                "success": True,
-                "message": f"Module '{module_name}' removed successfully"
-            }
-            
-        except Exception as e:
-            return {
-                "success": False,
-                "error": str(e)
-            }
-    
-    def _validate_module(self, code: str) -> Dict[str, Any]:
-        """Internal validation method."""
-        # Use existing validation from nexus_architect (lazy import)
-        validate_fn, _ = _import_validation()
-        validation_result = validate_fn(code, strict_mode=self.strict_validation)
-        
-        # Check Three.js API compliance
-        three_api_issues = self._check_three_js_api_compliance(code)
-        
-        return {
-            "is_valid": validation_result.is_valid and len(three_api_issues) == 0,
-            "syntax_valid": validation_result.is_valid,
-            "api_compliant": len(three_api_issues) == 0,
-            "errors": validation_result.errors + three_api_issues,
-            "warnings": validation_result.warnings,
-            "safety_score": max(0, 100 - len(validation_result.errors) * 20 - len(validation_result.warnings) * 5),
-        }
-    
-    def _check_three_js_api_compliance(self, code: str) -> List[str]:
-        """Check for Three.js API compliance issues."""
-        issues = []
-        
-        # Check for required patterns
-        if "THREE.Group" not in code and "new THREE" not in code:
-            issues.append("No Three.js objects created")
-        
-        # Check for deprecated APIs
-        deprecated_patterns = [
-            (r"THREE\.Face3", "THREE.Face3 is deprecated, use BufferGeometry"),
-            (r"THREE\.Geometry\(", "THREE.Geometry is deprecated, use BufferGeometry"),
-        ]
-        
-        for pattern, message in deprecated_patterns:
-            if re.search(pattern, code):
-                issues.append(f"Deprecated API: {message}")
-        
-        return issues
-    
-    def _generate_version(self, module_name: str, code: str) -> str:
-        """Generate version string from code hash."""
-        code_hash = hashlib.md5(code.encode()).hexdigest()[:8]
-        timestamp = datetime.now().strftime("%Y%m%d%H%M")
-        return f"{timestamp}-{code_hash}"
-    
-    def _create_backup(self, module: DeployedModule) -> None:
-        """Create backup of existing module."""
-        backup_path = os.path.join(
-            self.modules_dir,
-            f"{module.name}.{module.version}.backup.js"
-        )
-        with open(backup_path, 'w') as f:
-            f.write(module.code)
-    
-    def _get_backup(self, module_name: str) -> Optional[str]:
-        """Get backup code for module."""
-        if module_name not in self.modules:
-            return None
-        
-        module = self.modules[module_name]
-        backup_path = os.path.join(
-            self.modules_dir,
-            f"{module.name}.{module.version}.backup.js"
-        )
-        
-        if os.path.exists(backup_path):
-            with open(backup_path, 'r') as f:
-                return f.read()
-        return None
-    
-    def _save_module_file(self, module: DeployedModule) -> None:
-        """Save module to file system."""
-        module_path = self._get_module_path(module.name)
-        with open(module_path, 'w') as f:
-            f.write(f"// Nexus Module: {module.name}\n")
-            f.write(f"// Version: {module.version}\n")
-            f.write(f"// Status: {module.status.value}\n")
-            f.write(f"// Updated: {module.last_updated}\n")
-            f.write(f"// Hot-Reload: {module.hot_reload_supported}\n")
-            f.write("\n")
-            f.write(module.code)
-    
-    def _get_module_path(self, module_name: str) -> str:
-        """Get file path for module."""
-        return os.path.join(self.modules_dir, f"{module_name}.nexus.js")
-    
-    def _record_version(self, module_name: str, version: str, code: str) -> None:
-        """Record version in history."""
-        if module_name not in self.version_history:
-            self.version_history[module_name] = []
-        
-        version_info = ModuleVersion(
-            version_id=version,
-            module_name=module_name,
-            code_hash=hashlib.md5(code.encode()).hexdigest()[:16],
-            timestamp=datetime.now().isoformat(),
-        )
-        
-        self.version_history[module_name].insert(0, version_info)
-        
-        # Keep only last 10 versions
-        self.version_history[module_name] = self.version_history[module_name][:10]
-    
-    def _get_version(self, module_name: str, version: str) -> Optional[ModuleVersion]:
-        """Get specific version info."""
-        history = self.version_history.get(module_name, [])
-        for v in history:
-            if v.version_id == version:
-                return v
-        return None
-
-
-# =============================================================================
-# Convenience Functions
-# =============================================================================
-
-_deployer_instance: Optional[NexusDeployer] = None
-
-
-def get_deployer() -> NexusDeployer:
-    """Get or create the NexusDeployer singleton."""
-    global _deployer_instance
-    if _deployer_instance is None:
-        _deployer_instance = NexusDeployer()
-    return _deployer_instance
-
-
-def deploy_nexus_module(
-    module_code: str,
-    module_name: str,
-    test: bool = True,
-    hot_reload: bool = True
-) -> Dict[str, Any]:
-    """
-    Deploy a Nexus module with validation.
-    
-    Args:
-        module_code: Three.js module code
-        module_name: Unique module identifier
-        test: Run validation tests before deployment
-        hot_reload: Enable hot-reload support
-    
-    Returns:
-        Dict with deployment results
-    """
-    deployer = get_deployer()
-    return deployer.deploy_module(
-        module_code=module_code,
-        module_name=module_name,
-        hot_reload=hot_reload,
-        validate=test
-    )
-
-
-def hot_reload_module(module_name: str, new_code: str) -> Dict[str, Any]:
-    """
-    Hot-reload an existing module.
-    
-    Args:
-        module_name: Module to reload
-        new_code: New module code
-    
-    Returns:
-        Dict with reload results
-    """
-    deployer = get_deployer()
-    return deployer.hot_reload_module(module_name, new_code)
-
-
-def validate_nexus_code(code: str) -> Dict[str, Any]:
-    """
-    Validate Three.js code without deploying.
-    
-    Args:
-        code: Three.js code to validate
-    
-    Returns:
-        Dict with validation results
-    """
-    deployer = get_deployer()
-    return deployer.validate_module(code)
-
-
-def get_deployment_status() -> Dict[str, Any]:
-    """Get status of all deployed modules."""
-    deployer = get_deployer()
-    return deployer.get_all_modules()
-
-
-# =============================================================================
-# Tool Schemas
-# =============================================================================
-
-NEXUS_DEPLOYMENT_SCHEMAS = {
-    "deploy_nexus_module": {
-        "name": "deploy_nexus_module",
-        "description": "Deploy a Nexus Three.js module with validation and hot-reload support",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "module_code": {"type": "string"},
-                "module_name": {"type": "string"},
-                "test": {"type": "boolean", "default": True},
-                "hot_reload": {"type": "boolean", "default": True},
-            },
-            "required": ["module_code", "module_name"]
-        }
-    },
-    "hot_reload_module": {
-        "name": "hot_reload_module",
-        "description": "Hot-reload an existing Nexus module with new code",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "module_name": {"type": "string"},
-                "new_code": {"type": "string"},
-            },
-            "required": ["module_name", "new_code"]
-        }
-    },
-    "validate_nexus_code": {
-        "name": "validate_nexus_code",
-        "description": "Validate Three.js code for Nexus deployment without deploying",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "code": {"type": "string"}
-            },
-            "required": ["code"]
-        }
-    },
-    "get_deployment_status": {
-        "name": "get_deployment_status",
-        "description": "Get status of all deployed Nexus modules",
-        "parameters": {"type": "object", "properties": {}}
-    },
-}
-
-
-if __name__ == "__main__":
-    # Demo
-    print("Nexus Deployment System - Demo")
-    print("=" * 50)
-    
-    deployer = NexusDeployer()
-    
-    # Sample module code
-    sample_code = """
-(function() {
-    function createDemoRoom() {
-        const room = new THREE.Group();
-        room.name = 'demo_room';
-        
-        const light = new THREE.AmbientLight(0x404040, 0.5);
-        room.add(light);
-        
-        return room;
-    }
-    
-    window.NexusRooms = window.NexusRooms || {};
-    window.NexusRooms.demo_room = createDemoRoom;
-    
-    return { createDemoRoom };
-})();
-"""
-    
-    # Deploy
-    result = deployer.deploy_module(sample_code, "demo_room")
-    print(f"\nDeployment result: {result['message']}")
-    print(f"Validation: {result['validation'].get('is_valid', False)}")
-    print(f"Safety score: {result['validation'].get('safety_score', 0)}/100")
-    
-    # Get status
-    status = deployer.get_all_modules()
-    print(f"\nTotal modules: {status['total_count']}")
-    print(f"Active: {status['active_count']}")

agent/privacy_filter.py

@@ -0,0 +1,353 @@
+"""Privacy Filter — strip PII from context before remote API calls.
+
+Implements Vitalik's Pattern 2: "A local model can strip out private data
+before passing the query along to a remote LLM."
+
+When Hermes routes a request to a cloud provider (Anthropic, OpenRouter, etc.),
+this module sanitizes the message context to remove personally identifiable
+information before it leaves the user's machine.
+
+Threat model (from Vitalik's secure LLM architecture):
+- Privacy (other): Non-LLM data leakage via search queries, API calls
+- LLM accidents: LLM accidentally leaking private data in prompts
+- LLM jailbreaks: Remote content extracting private context
+
+Usage:
+    from agent.privacy_filter import PrivacyFilter, sanitize_messages
+
+    pf = PrivacyFilter()
+    safe_messages = pf.sanitize_messages(messages)
+    # safe_messages has PII replaced with [REDACTED] tokens
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+class Sensitivity(Enum):
+    """Classification of content sensitivity."""
+    PUBLIC = auto()       # No PII detected
+    LOW = auto()          # Generic references (e.g., city names)
+    MEDIUM = auto()       # Personal identifiers (name, email, phone)
+    HIGH = auto()         # Secrets, keys, financial data, medical info
+    CRITICAL = auto()     # Crypto keys, passwords, SSN patterns
+
+
+@dataclass
+class RedactionReport:
+    """Summary of what was redacted from a message batch."""
+    total_messages: int = 0
+    redacted_messages: int = 0
+    redactions: List[Dict[str, Any]] = field(default_factory=list)
+    max_sensitivity: Sensitivity = Sensitivity.PUBLIC
+
+    @property
+    def had_redactions(self) -> bool:
+        return self.redacted_messages > 0
+
+    def summary(self) -> str:
+        if not self.had_redactions:
+            return "No PII detected — context is clean for remote query."
+        parts = [f"Redacted {self.redacted_messages}/{self.total_messages} messages:"]
+        for r in self.redactions[:10]:
+            parts.append(f"  - {r['type']}: {r['count']} occurrence(s)")
+        if len(self.redactions) > 10:
+            parts.append(f"  ... and {len(self.redactions) - 10} more types")
+        return "\n".join(parts)
+
+
+# =========================================================================
+# PII pattern definitions
+# =========================================================================
+
+# Each pattern is (compiled_regex, redaction_type, sensitivity_level, replacement)
+_PII_PATTERNS: List[Tuple[re.Pattern, str, Sensitivity, str]] = []
+
+
+def _compile_patterns() -> None:
+    """Compile PII detection patterns. Called once at module init."""
+    global _PII_PATTERNS
+    if _PII_PATTERNS:
+        return
+
+    raw_patterns = [
+        # --- CRITICAL: secrets and credentials ---
+        (
+            r'(?:api[_-]?key|apikey|secret[_-]?key|access[_-]?token)\s*[:=]\s*["\']?([A-Za-z0-9_\-\.]{20,})["\']?',
+            "api_key_or_token",
+            Sensitivity.CRITICAL,
+            "[REDACTED-API-KEY]",
+        ),
+        (
+            r'\b(?:sk-|sk_|pk_|rk_|ak_)[A-Za-z0-9]{20,}\b',
+            "prefixed_secret",
+            Sensitivity.CRITICAL,
+            "[REDACTED-SECRET]",
+        ),
+        (
+            r'\b(?:ghp_|gho_|ghu_|ghs_|ghr_)[A-Za-z0-9]{36,}\b',
+            "github_token",
+            Sensitivity.CRITICAL,
+            "[REDACTED-GITHUB-TOKEN]",
+        ),
+        (
+            r'\b(?:xox[bposa]-[A-Za-z0-9\-]+)\b',
+            "slack_token",
+            Sensitivity.CRITICAL,
+            "[REDACTED-SLACK-TOKEN]",
+        ),
+        (
+            r'(?:password|passwd|pwd)\s*[:=]\s*["\']?([^\s"\']{4,})["\']?',
+            "password",
+            Sensitivity.CRITICAL,
+            "[REDACTED-PASSWORD]",
+        ),
+        (
+            r'(?:-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----)',
+            "private_key_block",
+            Sensitivity.CRITICAL,
+            "[REDACTED-PRIVATE-KEY]",
+        ),
+        # Ethereum / crypto addresses (42-char hex starting with 0x)
+        (
+            r'\b0x[a-fA-F0-9]{40}\b',
+            "ethereum_address",
+            Sensitivity.HIGH,
+            "[REDACTED-ETH-ADDR]",
+        ),
+        # Bitcoin addresses (base58, 25-34 chars starting with 1/3/bc1)
+        (
+            r'\b[13][a-km-zA-HJ-NP-Z1-9]{25,34}\b',
+            "bitcoin_address",
+            Sensitivity.HIGH,
+            "[REDACTED-BTC-ADDR]",
+        ),
+        (
+            r'\bbc1[a-zA-HJ-NP-Z0-9]{39,59}\b',
+            "bech32_address",
+            Sensitivity.HIGH,
+            "[REDACTED-BTC-ADDR]",
+        ),
+        # --- HIGH: financial ---
+        (
+            r'\b(?:\d{4}[-\s]?){3}\d{4}\b',
+            "credit_card_number",
+            Sensitivity.HIGH,
+            "[REDACTED-CC]",
+        ),
+        (
+            r'\b\d{3}-\d{2}-\d{4}\b',
+            "us_ssn",
+            Sensitivity.HIGH,
+            "[REDACTED-SSN]",
+        ),
+        # --- MEDIUM: personal identifiers ---
+        # Email addresses
+        (
+            r'\b[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}\b',
+            "email_address",
+            Sensitivity.MEDIUM,
+            "[REDACTED-EMAIL]",
+        ),
+        # Phone numbers (US/international patterns)
+        (
+            r'\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b',
+            "phone_number_us",
+            Sensitivity.MEDIUM,
+            "[REDACTED-PHONE]",
+        ),
+        (
+            r'\b\+\d{1,3}[-.\s]?\d{4,14}\b',
+            "phone_number_intl",
+            Sensitivity.MEDIUM,
+            "[REDACTED-PHONE]",
+        ),
+        # Filesystem paths that reveal user identity
+        (
+            r'(?:/Users/|/home/|C:\\Users\\)([A-Za-z0-9_\-]+)',
+            "user_home_path",
+            Sensitivity.MEDIUM,
+            r"/Users/[REDACTED-USER]",
+        ),
+        # --- LOW: environment / system info ---
+        # Internal IPs
+        (
+            r'\b(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})\b',
+            "internal_ip",
+            Sensitivity.LOW,
+            "[REDACTED-IP]",
+        ),
+    ]
+
+    _PII_PATTERNS = [
+        (re.compile(pattern, re.IGNORECASE), rtype, sensitivity, replacement)
+        for pattern, rtype, sensitivity, replacement in raw_patterns
+    ]
+
+
+_compile_patterns()
+
+
+# =========================================================================
+# Sensitive file path patterns (context-aware)
+# =========================================================================
+
+_SENSITIVE_PATH_PATTERNS = [
+    re.compile(r'\.(?:env|pem|key|p12|pfx|jks|keystore)\b', re.IGNORECASE),
+    re.compile(r'(?:\.ssh/|\.gnupg/|\.aws/|\.config/gcloud/)', re.IGNORECASE),
+    re.compile(r'(?:wallet|keystore|seed|mnemonic)', re.IGNORECASE),
+    re.compile(r'(?:\.hermes/\.env)', re.IGNORECASE),
+]
+
+
+def _classify_path_sensitivity(path: str) -> Sensitivity:
+    """Check if a file path references sensitive material."""
+    for pat in _SENSITIVE_PATH_PATTERNS:
+        if pat.search(path):
+            return Sensitivity.HIGH
+    return Sensitivity.PUBLIC
+
+
+# =========================================================================
+# Core filtering
+# =========================================================================
+
+class PrivacyFilter:
+    """Strip PII from message context before remote API calls.
+
+    Integrates with the agent's message pipeline. Call sanitize_messages()
+    before sending context to any cloud LLM provider.
+    """
+
+    def __init__(
+        self,
+        min_sensitivity: Sensitivity = Sensitivity.MEDIUM,
+        aggressive_mode: bool = False,
+    ):
+        """
+        Args:
+            min_sensitivity: Only redact PII at or above this level.
+                Default MEDIUM — redacts emails, phones, paths but not IPs.
+            aggressive_mode: If True, also redact file paths and internal IPs.
+        """
+        self.min_sensitivity = (
+            Sensitivity.LOW if aggressive_mode else min_sensitivity
+        )
+        self.aggressive_mode = aggressive_mode
+
+    def sanitize_text(self, text: str) -> Tuple[str, List[Dict[str, Any]]]:
+        """Sanitize a single text string. Returns (cleaned_text, redaction_list)."""
+        redactions = []
+        cleaned = text
+
+        for pattern, rtype, sensitivity, replacement in _PII_PATTERNS:
+            if sensitivity.value < self.min_sensitivity.value:
+                continue
+
+            matches = pattern.findall(cleaned)
+            if matches:
+                count = len(matches) if isinstance(matches[0], str) else sum(
+                    1 for m in matches if m
+                )
+                if count > 0:
+                    cleaned = pattern.sub(replacement, cleaned)
+                    redactions.append({
+                        "type": rtype,
+                        "sensitivity": sensitivity.name,
+                        "count": count,
+                    })
+
+        return cleaned, redactions
+
+    def sanitize_messages(
+        self, messages: List[Dict[str, Any]]
+    ) -> Tuple[List[Dict[str, Any]], RedactionReport]:
+        """Sanitize a list of OpenAI-format messages.
+
+        Returns (safe_messages, report). System messages are NOT sanitized
+        (they're typically static prompts). Only user and assistant messages
+        with string content are processed.
+
+        Args:
+            messages: List of {"role": ..., "content": ...} dicts.
+
+        Returns:
+            Tuple of (sanitized_messages, redaction_report).
+        """
+        report = RedactionReport(total_messages=len(messages))
+        safe_messages = []
+
+        for msg in messages:
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+
+            # Only sanitize user/assistant string content
+            if role in ("user", "assistant") and isinstance(content, str) and content:
+                cleaned, redactions = self.sanitize_text(content)
+                if redactions:
+                    report.redacted_messages += 1
+                    report.redactions.extend(redactions)
+                    # Track max sensitivity
+                    for r in redactions:
+                        s = Sensitivity[r["sensitivity"]]
+                        if s.value > report.max_sensitivity.value:
+                            report.max_sensitivity = s
+                    safe_msg = {**msg, "content": cleaned}
+                    safe_messages.append(safe_msg)
+                    logger.info(
+                        "Privacy filter: redacted %d PII type(s) from %s message",
+                        len(redactions), role,
+                    )
+                else:
+                    safe_messages.append(msg)
+            else:
+                safe_messages.append(msg)
+
+        return safe_messages, report
+
+    def should_use_local_only(self, text: str) -> Tuple[bool, str]:
+        """Determine if content is too sensitive for any remote call.
+
+        Returns (should_block, reason). If True, the content should only
+        be processed by a local model.
+        """
+        _, redactions = self.sanitize_text(text)
+
+        critical_count = sum(
+            1 for r in redactions
+            if Sensitivity[r["sensitivity"]] == Sensitivity.CRITICAL
+        )
+        high_count = sum(
+            1 for r in redactions
+            if Sensitivity[r["sensitivity"]] == Sensitivity.HIGH
+        )
+
+        if critical_count > 0:
+            return True, f"Contains {critical_count} critical-secret pattern(s) — local-only"
+        if high_count >= 3:
+            return True, f"Contains {high_count} high-sensitivity pattern(s) — local-only"
+        return False, ""
+
+
+def sanitize_messages(
+    messages: List[Dict[str, Any]],
+    min_sensitivity: Sensitivity = Sensitivity.MEDIUM,
+    aggressive: bool = False,
+) -> Tuple[List[Dict[str, Any]], RedactionReport]:
+    """Convenience function: sanitize messages with default settings."""
+    pf = PrivacyFilter(min_sensitivity=min_sensitivity, aggressive_mode=aggressive)
+    return pf.sanitize_messages(messages)
+
+
+def quick_sanitize(text: str) -> str:
+    """Quick sanitize a single string — returns cleaned text only."""
+    pf = PrivacyFilter()
+    cleaned, _ = pf.sanitize_text(text)
+    return cleaned

agent/profile_isolation.py

@@ -0,0 +1,262 @@
+"""
+Profile Session Isolation — #891
+
+Tags sessions with their originating profile and provides
+filtered access so profiles cannot see each other's data.
+
+Current state: All sessions share one state.db with no profile tag.
+This module adds profile tagging and filtered queries.
+
+Usage:
+    from agent.profile_isolation import tag_session, get_profile_sessions, get_active_profile
+    
+    # Tag a new session with the current profile
+    tag_session(session_id, profile_name)
+    
+    # Get sessions for a specific profile
+    sessions = get_profile_sessions("sprint")
+    
+    # Get current active profile
+    profile = get_active_profile()
+"""
+
+import json
+import os
+import sqlite3
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from datetime import datetime, timezone
+
+HERMES_HOME = Path(os.getenv("HERMES_HOME", str(Path.home() / ".hermes")))
+SESSIONS_DB = HERMES_HOME / "sessions" / "state.db"
+PROFILE_TAGS_FILE = HERMES_HOME / "profile_session_tags.json"
+
+
+def get_active_profile() -> str:
+    """Get the currently active profile name."""
+    config_path = HERMES_HOME / "config.yaml"
+    if config_path.exists():
+        try:
+            import yaml
+            with open(config_path) as f:
+                cfg = yaml.safe_load(f) or {}
+            return cfg.get("active_profile", "default")
+        except Exception:
+            pass
+    
+    # Check environment
+    return os.getenv("HERMES_PROFILE", "default")
+
+
+def _load_tags() -> Dict[str, str]:
+    """Load session-to-profile mapping."""
+    if not PROFILE_TAGS_FILE.exists():
+        return {}
+    try:
+        with open(PROFILE_TAGS_FILE) as f:
+            return json.load(f)
+    except Exception:
+        return {}
+
+
+def _save_tags(tags: Dict[str, str]):
+    """Save session-to-profile mapping."""
+    PROFILE_TAGS_FILE.parent.mkdir(parents=True, exist_ok=True)
+    with open(PROFILE_TAGS_FILE, "w") as f:
+        json.dump(tags, f, indent=2)
+
+
+def tag_session(session_id: str, profile: Optional[str] = None) -> str:
+    """
+    Tag a session with its originating profile.
+    
+    Returns the profile name used.
+    """
+    if profile is None:
+        profile = get_active_profile()
+    
+    tags = _load_tags()
+    tags[session_id] = profile
+    _save_tags(tags)
+    
+    # Also tag in SQLite if available
+    _tag_session_in_db(session_id, profile)
+    
+    return profile
+
+
+def _tag_session_in_db(session_id: str, profile: str):
+    """Add profile tag to SQLite session store."""
+    if not SESSIONS_DB.exists():
+        return
+    
+    try:
+        conn = sqlite3.connect(str(SESSIONS_DB))
+        cursor = conn.cursor()
+        
+        # Check if sessions table has profile column
+        cursor.execute("PRAGMA table_info(sessions)")
+        columns = [row[1] for row in cursor.fetchall()]
+        
+        if "profile" not in columns:
+            # Add profile column
+            cursor.execute("ALTER TABLE sessions ADD COLUMN profile TEXT DEFAULT 'default'")
+        
+        # Update the session's profile
+        cursor.execute(
+            "UPDATE sessions SET profile = ? WHERE session_id = ?",
+            (profile, session_id)
+        )
+        
+        conn.commit()
+        conn.close()
+    except Exception:
+        pass  # SQLite might not be available or schema differs
+
+
+def get_session_profile(session_id: str) -> Optional[str]:
+    """Get the profile that owns a session."""
+    # Check JSON tags first
+    tags = _load_tags()
+    if session_id in tags:
+        return tags[session_id]
+    
+    # Check SQLite
+    if SESSIONS_DB.exists():
+        try:
+            conn = sqlite3.connect(str(SESSIONS_DB))
+            cursor = conn.cursor()
+            cursor.execute(
+                "SELECT profile FROM sessions WHERE session_id = ?",
+                (session_id,)
+            )
+            row = cursor.fetchone()
+            conn.close()
+            if row:
+                return row[0]
+        except Exception:
+            pass
+    
+    return None
+
+
+def get_profile_sessions(
+    profile: Optional[str] = None,
+    limit: int = 100,
+) -> List[Dict[str, Any]]:
+    """
+    Get sessions belonging to a specific profile.
+    
+    Returns list of session dicts.
+    """
+    if profile is None:
+        profile = get_active_profile()
+    
+    sessions = []
+    
+    # Get from JSON tags
+    tags = _load_tags()
+    tagged_sessions = [sid for sid, p in tags.items() if p == profile]
+    
+    # Get from SQLite with profile filter
+    if SESSIONS_DB.exists():
+        try:
+            conn = sqlite3.connect(str(SESSIONS_DB))
+            conn.row_factory = sqlite3.Row
+            cursor = conn.cursor()
+            
+            # Try profile column first
+            try:
+                cursor.execute(
+                    "SELECT * FROM sessions WHERE profile = ? ORDER BY updated_at DESC LIMIT ?",
+                    (profile, limit)
+                )
+                for row in cursor.fetchall():
+                    sessions.append(dict(row))
+            except Exception:
+                # Fallback: filter by tagged session IDs
+                if tagged_sessions:
+                    placeholders = ",".join("?" * len(tagged_sessions[:limit]))
+                    cursor.execute(
+                        f"SELECT * FROM sessions WHERE session_id IN ({placeholders}) ORDER BY updated_at DESC LIMIT ?",
+                        (*tagged_sessions[:limit], limit)
+                    )
+                    for row in cursor.fetchall():
+                        sessions.append(dict(row))
+            
+            conn.close()
+        except Exception:
+            pass
+    
+    return sessions[:limit]
+
+
+def filter_sessions_by_profile(
+    sessions: List[Dict[str, Any]],
+    profile: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """Filter a list of sessions to only include those belonging to a profile."""
+    if profile is None:
+        profile = get_active_profile()
+    
+    tags = _load_tags()
+    filtered = []
+    
+    for session in sessions:
+        sid = session.get("session_id") or session.get("id")
+        if not sid:
+            continue
+        
+        # Check tag
+        session_profile = tags.get(sid)
+        if session_profile is None:
+            # Check SQLite
+            session_profile = get_session_profile(sid)
+        
+        if session_profile == profile or session_profile is None:
+            filtered.append(session)
+    
+    return filtered
+
+
+def get_profile_stats() -> Dict[str, Any]:
+    """Get statistics about profile session distribution."""
+    tags = _load_tags()
+    
+    profile_counts = {}
+    for sid, profile in tags.items():
+        profile_counts[profile] = profile_counts.get(profile, 0) + 1
+    
+    total_tagged = len(tags)
+    profiles = list(profile_counts.keys())
+    
+    return {
+        "total_tagged_sessions": total_tagged,
+        "profiles": profiles,
+        "profile_counts": profile_counts,
+        "active_profile": get_active_profile(),
+    }
+
+
+def audit_untagged_sessions() -> List[str]:
+    """Find sessions without a profile tag."""
+    if not SESSIONS_DB.exists():
+        return []
+    
+    try:
+        conn = sqlite3.connect(str(SESSIONS_DB))
+        cursor = conn.cursor()
+        
+        # Get all session IDs
+        cursor.execute("SELECT session_id FROM sessions")
+        all_sessions = {row[0] for row in cursor.fetchall()}
+        conn.close()
+        
+        # Get tagged sessions
+        tags = _load_tags()
+        tagged = set(tags.keys())
+        
+        # Return untagged
+        return list(all_sessions - tagged)
+    except Exception:
+        return []

agent/prompt_builder.py

@@ -12,7 +12,7 @@ import threading
 from collections import OrderedDict
 from pathlib import Path
 
-from hermes_constants import get_hermes_home
+from hermes_constants import get_hermes_home, get_skills_dir, is_wsl
 from typing import Optional
 
 from agent.skill_utils import (
@@ -40,7 +40,7 @@ _CONTEXT_THREAT_PATTERNS = [
     (r'disregard\s+(your|all|any)\s+(instructions|rules|guidelines)', "disregard_rules"),
     (r'act\s+as\s+(if|though)\s+you\s+(have\s+no|don\'t\s+have)\s+(restrictions|limits|rules)', "bypass_restrictions"),
     (r'<!--[^>]*(?:ignore|override|system|secret|hidden)[^>]*-->', "html_comment_injection"),
-    (r'<\s*div\s+style\s*=\s*["\'].*display\s*:\s*none', "hidden_div"),
+    (r'<\s*div\s+style\s*=\s*["\'][\s\S]*?display\s*:\s*none', "hidden_div"),
     (r'translate\s+.*\s+into\s+.*\s+and\s+(execute|run|eval)', "translate_execute"),
     (r'curl\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)', "exfil_curl"),
     (r'cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass)', "read_secrets"),
@@ -187,7 +187,100 @@ TOOL_USE_ENFORCEMENT_GUIDANCE = (
 
 # Model name substrings that trigger tool-use enforcement guidance.
 # Add new patterns here when a model family needs explicit steering.
-TOOL_USE_ENFORCEMENT_MODELS = ("gpt", "codex")
+TOOL_USE_ENFORCEMENT_MODELS = ("gpt", "codex", "gemini", "gemma", "grok")
+
+# OpenAI GPT/Codex-specific execution guidance.  Addresses known failure modes
+# where GPT models abandon work on partial results, skip prerequisite lookups,
+# hallucinate instead of using tools, and declare "done" without verification.
+# Inspired by patterns from OpenAI's GPT-5.4 prompting guide & OpenClaw PR #38953.
+OPENAI_MODEL_EXECUTION_GUIDANCE = (
+    "# Execution discipline\n"
+    "<tool_persistence>\n"
+    "- Use tools whenever they improve correctness, completeness, or grounding.\n"
+    "- Do not stop early when another tool call would materially improve the result.\n"
+    "- If a tool returns empty or partial results, retry with a different query or "
+    "strategy before giving up.\n"
+    "- Keep calling tools until: (1) the task is complete, AND (2) you have verified "
+    "the result.\n"
+    "</tool_persistence>\n"
+    "\n"
+    "<mandatory_tool_use>\n"
+    "NEVER answer these from memory or mental computation — ALWAYS use a tool:\n"
+    "- Arithmetic, math, calculations → use terminal or execute_code\n"
+    "- Hashes, encodings, checksums → use terminal (e.g. sha256sum, base64)\n"
+    "- Current time, date, timezone → use terminal (e.g. date)\n"
+    "- System state: OS, CPU, memory, disk, ports, processes → use terminal\n"
+    "- File contents, sizes, line counts → use read_file, search_files, or terminal\n"
+    "- Git history, branches, diffs → use terminal\n"
+    "- Current facts (weather, news, versions) → use web_search\n"
+    "Your memory and user profile describe the USER, not the system you are "
+    "running on. The execution environment may differ from what the user profile "
+    "says about their personal setup.\n"
+    "</mandatory_tool_use>\n"
+    "\n"
+    "<act_dont_ask>\n"
+    "When a question has an obvious default interpretation, act on it immediately "
+    "instead of asking for clarification. Examples:\n"
+    "- 'Is port 443 open?' → check THIS machine (don't ask 'open where?')\n"
+    "- 'What OS am I running?' → check the live system (don't use user profile)\n"
+    "- 'What time is it?' → run `date` (don't guess)\n"
+    "Only ask for clarification when the ambiguity genuinely changes what tool "
+    "you would call.\n"
+    "</act_dont_ask>\n"
+    "\n"
+    "<prerequisite_checks>\n"
+    "- Before taking an action, check whether prerequisite discovery, lookup, or "
+    "context-gathering steps are needed.\n"
+    "- Do not skip prerequisite steps just because the final action seems obvious.\n"
+    "- If a task depends on output from a prior step, resolve that dependency first.\n"
+    "</prerequisite_checks>\n"
+    "\n"
+    "<verification>\n"
+    "Before finalizing your response:\n"
+    "- Correctness: does the output satisfy every stated requirement?\n"
+    "- Grounding: are factual claims backed by tool outputs or provided context?\n"
+    "- Formatting: does the output match the requested format or schema?\n"
+    "- Safety: if the next step has side effects (file writes, commands, API calls), "
+    "confirm scope before executing.\n"
+    "</verification>\n"
+    "\n"
+    "<missing_context>\n"
+    "- If required context is missing, do NOT guess or hallucinate an answer.\n"
+    "- Use the appropriate lookup tool when missing information is retrievable "
+    "(search_files, web_search, read_file, etc.).\n"
+    "- Ask a clarifying question only when the information cannot be retrieved by tools.\n"
+    "- If you must proceed with incomplete information, label assumptions explicitly.\n"
+    "</missing_context>"
+)
+
+# Gemini/Gemma-specific operational guidance, adapted from OpenCode's gemini.txt.
+# Injected alongside TOOL_USE_ENFORCEMENT_GUIDANCE when the model is Gemini or Gemma.
+GOOGLE_MODEL_OPERATIONAL_GUIDANCE = (
+    "# Google model operational directives\n"
+    "Follow these operational rules strictly:\n"
+    "- **Absolute paths:** Always construct and use absolute file paths for all "
+    "file system operations. Combine the project root with relative paths.\n"
+    "- **Verify first:** Use read_file/search_files to check file contents and "
+    "project structure before making changes. Never guess at file contents.\n"
+    "- **Dependency checks:** Never assume a library is available. Check "
+    "package.json, requirements.txt, Cargo.toml, etc. before importing.\n"
+    "- **Conciseness:** Keep explanatory text brief — a few sentences, not "
+    "paragraphs. Focus on actions and results over narration.\n"
+    "- **Parallel tool calls:** When you need to perform multiple independent "
+    "operations (e.g. reading several files), make all the tool calls in a "
+    "single response rather than sequentially.\n"
+    "- **Non-interactive commands:** Use flags like -y, --yes, --non-interactive "
+    "to prevent CLI tools from hanging on prompts.\n"
+    "- **Keep going:** Work autonomously until the task is fully resolved. "
+    "Don't stop with a plan — execute it.\n"
+)
+
+# Model name substrings that should use the 'developer' role instead of
+# 'system' for the system prompt.  OpenAI's newer models (GPT-5, Codex)
+# give stronger instruction-following weight to the 'developer' role.
+# The swap happens at the API boundary in _build_api_kwargs() so internal
+# message representation stays consistent ("system" everywhere).
+DEVELOPER_ROLE_MODELS = ("gpt-5", "codex")
 
 PLATFORM_HINTS = {
     "whatsapp": (
@@ -256,8 +349,71 @@ PLATFORM_HINTS = {
         "only — no markdown, no formatting. SMS messages are limited to ~1600 "
         "characters, so be brief and direct."
     ),
+    "bluebubbles": (
+        "You are chatting via iMessage (BlueBubbles). iMessage does not render "
+        "markdown formatting — use plain text. Keep responses concise as they "
+        "appear as text messages. You can send media files natively: include "
+        "MEDIA:/absolute/path/to/file in your response. Images (.jpg, .png, "
+        ".heic) appear as photos and other files arrive as attachments."
+    ),
+    "weixin": (
+        "You are on Weixin/WeChat. Markdown formatting is supported, so you may use it when "
+        "it improves readability, but keep the message compact and chat-friendly. You can send media files natively: "
+        "include MEDIA:/absolute/path/to/file in your response. Images are sent as native "
+        "photos, videos play inline when supported, and other files arrive as downloadable "
+        "documents. You can also include image URLs in markdown format ![alt](url) and they "
+        "will be downloaded and sent as native media when possible."
+    ),
+    "wecom": (
+        "You are on WeCom (企业微信 / Enterprise WeChat). Markdown formatting is supported. "
+        "You CAN send media files natively — to deliver a file to the user, include "
+        "MEDIA:/absolute/path/to/file in your response. The file will be sent as a native "
+        "WeCom attachment: images (.jpg, .png, .webp) are sent as photos (up to 10 MB), "
+        "other files (.pdf, .docx, .xlsx, .md, .txt, etc.) arrive as downloadable documents "
+        "(up to 20 MB), and videos (.mp4) play inline. Voice messages are supported but "
+        "must be in AMR format — other audio formats are automatically sent as file attachments. "
+        "You can also include image URLs in markdown format ![alt](url) and they will be "
+        "downloaded and sent as native photos. Do NOT tell the user you lack file-sending "
+        "capability — use MEDIA: syntax whenever a file delivery is appropriate."
+    ),
+    "qqbot": (
+        "You are on QQ, a popular Chinese messaging platform. QQ supports markdown formatting "
+        "and emoji. You can send media files natively: include MEDIA:/absolute/path/to/file in "
+        "your response. Images are sent as native photos, and other files arrive as downloadable "
+        "documents."
+    ),
 }
 
+# ---------------------------------------------------------------------------
+# Environment hints — execution-environment awareness for the agent.
+# Unlike PLATFORM_HINTS (which describe the messaging channel), these describe
+# the machine/OS the agent's tools actually run on.
+# ---------------------------------------------------------------------------
+
+WSL_ENVIRONMENT_HINT = (
+    "You are running inside WSL (Windows Subsystem for Linux). "
+    "The Windows host filesystem is mounted under /mnt/ — "
+    "/mnt/c/ is the C: drive, /mnt/d/ is D:, etc. "
+    "The user's Windows files are typically at "
+    "/mnt/c/Users/<username>/Desktop/, Documents/, Downloads/, etc. "
+    "When the user references Windows paths or desktop files, translate "
+    "to the /mnt/c/ equivalent. You can list /mnt/c/Users/ to discover "
+    "the Windows username if needed."
+)
+
+
+def build_environment_hints() -> str:
+    """Return environment-specific guidance for the system prompt.
+
+    Detects WSL, and can be extended for Termux, Docker, etc.
+    Returns an empty string when no special environment is detected.
+    """
+    hints: list[str] = []
+    if is_wsl():
+        hints.append(WSL_ENVIRONMENT_HINT)
+    return "\n\n".join(hints)
+
+
 CONTEXT_FILE_MAX_CHARS = 20_000
 CONTEXT_TRUNCATE_HEAD_RATIO = 0.7
 CONTEXT_TRUNCATE_TAIL_RATIO = 0.2
@@ -379,7 +535,7 @@ def _parse_skill_file(skill_file: Path) -> tuple[bool, dict, str]:
     (True, {}, "") to err on the side of showing the skill.
     """
     try:
-        raw = skill_file.read_text(encoding="utf-8")[:2000]
+        raw = skill_file.read_text(encoding="utf-8")
         frontmatter, _ = parse_frontmatter(raw)
 
         if not skill_matches_platform(frontmatter):
@@ -387,21 +543,10 @@ def _parse_skill_file(skill_file: Path) -> tuple[bool, dict, str]:
 
         return True, frontmatter, extract_skill_description(frontmatter)
     except Exception as e:
-        logger.debug("Failed to parse skill file %s: %s", skill_file, e)
+        logger.warning("Failed to parse skill file %s: %s", skill_file, e)
         return True, {}, ""
 
 
-def _read_skill_conditions(skill_file: Path) -> dict:
-    """Extract conditional activation fields from SKILL.md frontmatter."""
-    try:
-        raw = skill_file.read_text(encoding="utf-8")[:2000]
-        frontmatter, _ = parse_frontmatter(raw)
-        return extract_skill_conditions(frontmatter)
-    except Exception as e:
-        logger.debug("Failed to read skill conditions from %s: %s", skill_file, e)
-        return {}
-
-
 def _skill_should_show(
     conditions: dict,
     available_tools: "set[str] | None",
@@ -451,19 +596,27 @@ def build_skills_system_prompt(
     are read-only — they appear in the index but new skills are always created
     in the local dir.  Local skills take precedence when names collide.
     """
-    hermes_home = get_hermes_home()
-    skills_dir = hermes_home / "skills"
+    skills_dir = get_skills_dir()
     external_dirs = get_all_skills_dirs()[1:]  # skip local (index 0)
 
     if not skills_dir.exists() and not external_dirs:
         return ""
 
     # ── Layer 1: in-process LRU cache ─────────────────────────────────
+    # Include the resolved platform so per-platform disabled-skill lists
+    # produce distinct cache entries (gateway serves multiple platforms).
+    from gateway.session_context import get_session_env
+    _platform_hint = (
+        os.environ.get("HERMES_PLATFORM")
+        or get_session_env("HERMES_SESSION_PLATFORM")
+        or ""
+    )
     cache_key = (
         str(skills_dir.resolve()),
         tuple(str(d) for d in external_dirs),
         tuple(sorted(str(t) for t in (available_tools or set()))),
         tuple(sorted(str(ts) for ts in (available_toolsets or set()))),
+        _platform_hint,
     )
     with _SKILLS_PROMPT_CACHE_LOCK:
         cached = _SKILLS_PROMPT_CACHE.get(cache_key)
@@ -621,8 +774,16 @@ def build_skills_system_prompt(
 
         result = (
             "## Skills (mandatory)\n"
-            "Before replying, scan the skills below. If one clearly matches your task, "
-            "load it with skill_view(name) and follow its instructions. "
+            "Before replying, scan the skills below. If a skill matches or is even partially relevant "
+            "to your task, you MUST load it with skill_view(name) and follow its instructions. "
+            "Err on the side of loading — it is always better to have context you don't need "
+            "than to miss critical steps, pitfalls, or established workflows. "
+            "Skills contain specialized knowledge — API endpoints, tool-specific commands, "
+            "and proven workflows that outperform general-purpose approaches. Load the skill "
+            "even if you think you could handle the task with basic tools like web_search or terminal. "
+            "Skills also encode the user's preferred approach, conventions, and quality standards "
+            "for tasks like code review, planning, and testing — load them even for tasks you "
+            "already know how to do, because the skill defines how it should be done here.\n"
             "If a skill has issues, fix it with skill_manage(action='patch').\n"
             "After difficult/iterative tasks, offer to save as a skill. "
             "If a skill you loaded was missing steps, had wrong commands, or needed "
@@ -632,7 +793,7 @@ def build_skills_system_prompt(
             + "\n".join(index_lines) + "\n"
             "</available_skills>\n"
             "\n"
-            "If none match, proceed normally without loading a skill."
+            "Only proceed without loading a skill if genuinely none are relevant to the task."
         )
 
     # ── Store in LRU cache ────────────────────────────────────────────
@@ -645,6 +806,72 @@ def build_skills_system_prompt(
     return result
 
 
+def build_nous_subscription_prompt(valid_tool_names: "set[str] | None" = None) -> str:
+    """Build a compact Nous subscription capability block for the system prompt."""
+    try:
+        from hermes_cli.nous_subscription import get_nous_subscription_features
+        from tools.tool_backend_helpers import managed_nous_tools_enabled
+    except Exception as exc:
+        logger.debug("Failed to import Nous subscription helper: %s", exc)
+        return ""
+
+    if not managed_nous_tools_enabled():
+        return ""
+
+    valid_names = set(valid_tool_names or set())
+    relevant_tool_names = {
+        "web_search",
+        "web_extract",
+        "browser_navigate",
+        "browser_snapshot",
+        "browser_click",
+        "browser_type",
+        "browser_scroll",
+        "browser_console",
+        "browser_press",
+        "browser_get_images",
+        "browser_vision",
+        "image_generate",
+        "text_to_speech",
+        "terminal",
+        "process",
+        "execute_code",
+    }
+
+    if valid_names and not (valid_names & relevant_tool_names):
+        return ""
+
+    features = get_nous_subscription_features()
+
+    def _status_line(feature) -> str:
+        if feature.managed_by_nous:
+            return f"- {feature.label}: active via Nous subscription"
+        if feature.active:
+            current = feature.current_provider or "configured provider"
+            return f"- {feature.label}: currently using {current}"
+        if feature.included_by_default and features.nous_auth_present:
+            return f"- {feature.label}: included with Nous subscription, not currently selected"
+        if feature.key == "modal" and features.nous_auth_present:
+            return f"- {feature.label}: optional via Nous subscription"
+        return f"- {feature.label}: not currently available"
+
+    lines = [
+        "# Nous Subscription",
+        "Nous subscription includes managed web tools (Firecrawl), image generation (FAL), OpenAI TTS, and browser automation (Browser Use) by default. Modal execution is optional.",
+        "Current capability status:",
+    ]
+    lines.extend(_status_line(feature) for feature in features.items())
+    lines.extend(
+        [
+            "When a Nous-managed feature is active, do not ask the user for Firecrawl, FAL, OpenAI TTS, or Browser-Use API keys.",
+            "If the user is not subscribed and asks for a capability that Nous subscription would unlock or simplify, suggest Nous subscription as one option alongside direct setup or local alternatives.",
+            "Do not mention subscription unless the user asks about it or it directly solves the current missing capability.",
+            "Useful commands: hermes setup, hermes setup tools, hermes setup terminal, hermes status.",
+        ]
+    )
+    return "\n".join(lines)
+
+
 # =========================================================================
 # Context files (SOUL.md, AGENTS.md, .cursorrules)
 # =========================================================================

agent/provider_preflight.py

@@ -0,0 +1,146 @@
+"""Provider Preflight — Poka-yoke validation of provider/model config.
+
+Validates provider and model configuration before session start.
+Prevents wasted context on misconfigured providers.
+
+Usage:
+    from agent.provider_preflight import preflight_check
+    result = preflight_check(provider="openrouter", model="xiaomi/mimo-v2-pro")
+    if not result["valid"]:
+        print(result["error"])
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# Provider -> required env var
+PROVIDER_KEYS = {
+    "openrouter": "OPENROUTER_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "nous": "NOUS_API_KEY",
+    "ollama": None,  # Local, no key needed
+    "local": None,
+}
+
+
+def check_provider_key(provider: str) -> Dict[str, Any]:
+    """Check if provider has a valid API key configured."""
+    provider_lower = provider.lower().strip()
+
+    env_var = None
+    for known, key in PROVIDER_KEYS.items():
+        if known in provider_lower:
+            env_var = key
+            break
+
+    if env_var is None:
+        # Unknown provider — assume OK (custom/local)
+        return {"valid": True, "provider": provider, "key_status": "unknown"}
+
+    if env_var is None:
+        # Local provider, no key needed
+        return {"valid": True, "provider": provider, "key_status": "not_required"}
+
+    key_value = os.getenv(env_var, "").strip()
+    if not key_value:
+        return {
+            "valid": False,
+            "provider": provider,
+            "key_status": "missing",
+            "error": f"{env_var} is not set. Provider '{provider}' will fail.",
+            "fix": f"Set {env_var} in ~/.hermes/.env",
+        }
+
+    if len(key_value) < 10:
+        return {
+            "valid": False,
+            "provider": provider,
+            "key_status": "too_short",
+            "error": f"{env_var} is suspiciously short ({len(key_value)} chars). May be invalid.",
+            "fix": f"Verify {env_var} value in ~/.hermes/.env",
+        }
+
+    return {"valid": True, "provider": provider, "key_status": "set"}
+
+
+def check_model_availability(model: str, provider: str) -> Dict[str, Any]:
+    """Check if model is likely available for provider."""
+    if not model:
+        return {"valid": False, "error": "No model specified"}
+
+    # Basic sanity checks
+    model_lower = model.lower()
+
+    # Anthropic models should use anthropic provider
+    if "claude" in model_lower and "anthropic" not in provider.lower():
+        return {
+            "valid": True,  # Allow but warn
+            "warning": f"Model '{model}' usually runs on Anthropic provider, not '{provider}'",
+        }
+
+    # Ollama models
+    ollama_indicators = ["llama", "mistral", "qwen", "gemma", "phi", "hermes"]
+    if any(x in model_lower for x in ollama_indicators) and ":" not in model:
+        return {
+            "valid": True,
+            "warning": f"Model '{model}' may need a version tag for Ollama (e.g., {model}:latest)",
+        }
+
+    return {"valid": True}
+
+
+def preflight_check(
+    provider: str = "",
+    model: str = "",
+    fallback_provider: str = "",
+    fallback_model: str = "",
+) -> Dict[str, Any]:
+    """Full pre-flight check for provider/model configuration.
+
+    Returns:
+        Dict with valid (bool), errors (list), warnings (list).
+    """
+    errors = []
+    warnings = []
+
+    # Check primary provider
+    if provider:
+        result = check_provider_key(provider)
+        if not result["valid"]:
+            errors.append(result.get("error", f"Provider {provider} invalid"))
+
+    # Check primary model
+    if model:
+        result = check_model_availability(model, provider)
+        if not result["valid"]:
+            errors.append(result.get("error", f"Model {model} invalid"))
+        elif result.get("warning"):
+            warnings.append(result["warning"])
+
+    # Check fallback
+    if fallback_provider:
+        result = check_provider_key(fallback_provider)
+        if not result["valid"]:
+            warnings.append(f"Fallback provider {fallback_provider} also invalid: {result.get('error','')}")
+
+    if fallback_model:
+        result = check_model_availability(fallback_model, fallback_provider)
+        if not result["valid"]:
+            warnings.append(f"Fallback model {fallback_model} invalid")
+        elif result.get("warning"):
+            warnings.append(result["warning"])
+
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+        "warnings": warnings,
+        "provider": provider,
+        "model": model,
+    }

agent/rate_limit_tracker.py

@@ -0,0 +1,246 @@
+"""Rate limit tracking for inference API responses.
+
+Captures x-ratelimit-* headers from provider responses and provides
+formatted display for the /usage slash command.  Currently supports
+the Nous Portal header format (also used by OpenRouter and OpenAI-compatible
+APIs that follow the same convention).
+
+Header schema (12 headers total):
+    x-ratelimit-limit-requests          RPM cap
+    x-ratelimit-limit-requests-1h       RPH cap
+    x-ratelimit-limit-tokens            TPM cap
+    x-ratelimit-limit-tokens-1h         TPH cap
+    x-ratelimit-remaining-requests      requests left in minute window
+    x-ratelimit-remaining-requests-1h   requests left in hour window
+    x-ratelimit-remaining-tokens        tokens left in minute window
+    x-ratelimit-remaining-tokens-1h     tokens left in hour window
+    x-ratelimit-reset-requests          seconds until minute request window resets
+    x-ratelimit-reset-requests-1h       seconds until hour request window resets
+    x-ratelimit-reset-tokens            seconds until minute token window resets
+    x-ratelimit-reset-tokens-1h         seconds until hour token window resets
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional
+
+
+@dataclass
+class RateLimitBucket:
+    """One rate-limit window (e.g. requests per minute)."""
+
+    limit: int = 0
+    remaining: int = 0
+    reset_seconds: float = 0.0
+    captured_at: float = 0.0  # time.time() when this was captured
+
+    @property
+    def used(self) -> int:
+        return max(0, self.limit - self.remaining)
+
+    @property
+    def usage_pct(self) -> float:
+        if self.limit <= 0:
+            return 0.0
+        return (self.used / self.limit) * 100.0
+
+    @property
+    def remaining_seconds_now(self) -> float:
+        """Estimated seconds remaining until reset, adjusted for elapsed time."""
+        elapsed = time.time() - self.captured_at
+        return max(0.0, self.reset_seconds - elapsed)
+
+
+@dataclass
+class RateLimitState:
+    """Full rate-limit state parsed from response headers."""
+
+    requests_min: RateLimitBucket = field(default_factory=RateLimitBucket)
+    requests_hour: RateLimitBucket = field(default_factory=RateLimitBucket)
+    tokens_min: RateLimitBucket = field(default_factory=RateLimitBucket)
+    tokens_hour: RateLimitBucket = field(default_factory=RateLimitBucket)
+    captured_at: float = 0.0  # when the headers were captured
+    provider: str = ""
+
+    @property
+    def has_data(self) -> bool:
+        return self.captured_at > 0
+
+    @property
+    def age_seconds(self) -> float:
+        if not self.has_data:
+            return float("inf")
+        return time.time() - self.captured_at
+
+
+def _safe_int(value: Any, default: int = 0) -> int:
+    try:
+        return int(float(value))
+    except (TypeError, ValueError):
+        return default
+
+
+def _safe_float(value: Any, default: float = 0.0) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def parse_rate_limit_headers(
+    headers: Mapping[str, str],
+    provider: str = "",
+) -> Optional[RateLimitState]:
+    """Parse x-ratelimit-* headers into a RateLimitState.
+
+    Returns None if no rate limit headers are present.
+    """
+    # Normalize to lowercase so lookups work regardless of how the server
+    # capitalises headers (HTTP header names are case-insensitive per RFC 7230).
+    lowered = {k.lower(): v for k, v in headers.items()}
+
+    # Quick check: at least one rate limit header must exist
+    has_any = any(k.startswith("x-ratelimit-") for k in lowered)
+    if not has_any:
+        return None
+
+    now = time.time()
+
+    def _bucket(resource: str, suffix: str = "") -> RateLimitBucket:
+        # e.g. resource="requests", suffix="" -> per-minute
+        #      resource="tokens", suffix="-1h" -> per-hour
+        tag = f"{resource}{suffix}"
+        return RateLimitBucket(
+            limit=_safe_int(lowered.get(f"x-ratelimit-limit-{tag}")),
+            remaining=_safe_int(lowered.get(f"x-ratelimit-remaining-{tag}")),
+            reset_seconds=_safe_float(lowered.get(f"x-ratelimit-reset-{tag}")),
+            captured_at=now,
+        )
+
+    return RateLimitState(
+        requests_min=_bucket("requests"),
+        requests_hour=_bucket("requests", "-1h"),
+        tokens_min=_bucket("tokens"),
+        tokens_hour=_bucket("tokens", "-1h"),
+        captured_at=now,
+        provider=provider,
+    )
+
+
+# ── Formatting ──────────────────────────────────────────────────────────
+
+
+def _fmt_count(n: int) -> str:
+    """Human-friendly number: 7999856 -> '8.0M', 33599 -> '33.6K', 799 -> '799'."""
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.1f}M"
+    if n >= 10_000:
+        return f"{n / 1_000:.1f}K"
+    if n >= 1_000:
+        return f"{n / 1_000:.1f}K"
+    return str(n)
+
+
+def _fmt_seconds(seconds: float) -> str:
+    """Seconds -> human-friendly duration: '58s', '2m 14s', '58m 57s', '1h 2m'."""
+    s = max(0, int(seconds))
+    if s < 60:
+        return f"{s}s"
+    if s < 3600:
+        m, sec = divmod(s, 60)
+        return f"{m}m {sec}s" if sec else f"{m}m"
+    h, remainder = divmod(s, 3600)
+    m = remainder // 60
+    return f"{h}h {m}m" if m else f"{h}h"
+
+
+def _bar(pct: float, width: int = 20) -> str:
+    """ASCII progress bar: [████████░░░░░░░░░░░░] 40%."""
+    filled = int(pct / 100.0 * width)
+    filled = max(0, min(width, filled))
+    empty = width - filled
+    return f"[{'█' * filled}{'░' * empty}]"
+
+
+def _bucket_line(label: str, bucket: RateLimitBucket, label_width: int = 14) -> str:
+    """Format one bucket as a single line."""
+    if bucket.limit <= 0:
+        return f"  {label:<{label_width}}  (no data)"
+
+    pct = bucket.usage_pct
+    used = _fmt_count(bucket.used)
+    limit = _fmt_count(bucket.limit)
+    remaining = _fmt_count(bucket.remaining)
+    reset = _fmt_seconds(bucket.remaining_seconds_now)
+
+    bar = _bar(pct)
+    return f"  {label:<{label_width}} {bar} {pct:5.1f}%  {used}/{limit} used  ({remaining} left, resets in {reset})"
+
+
+def format_rate_limit_display(state: RateLimitState) -> str:
+    """Format rate limit state for terminal/chat display."""
+    if not state.has_data:
+        return "No rate limit data yet — make an API request first."
+
+    age = state.age_seconds
+    if age < 5:
+        freshness = "just now"
+    elif age < 60:
+        freshness = f"{int(age)}s ago"
+    else:
+        freshness = f"{_fmt_seconds(age)} ago"
+
+    provider_label = state.provider.title() if state.provider else "Provider"
+
+    lines = [
+        f"{provider_label} Rate Limits (captured {freshness}):",
+        "",
+        _bucket_line("Requests/min", state.requests_min),
+        _bucket_line("Requests/hr", state.requests_hour),
+        "",
+        _bucket_line("Tokens/min", state.tokens_min),
+        _bucket_line("Tokens/hr", state.tokens_hour),
+    ]
+
+    # Add warnings if any bucket is getting hot
+    warnings = []
+    for label, bucket in [
+        ("requests/min", state.requests_min),
+        ("requests/hr", state.requests_hour),
+        ("tokens/min", state.tokens_min),
+        ("tokens/hr", state.tokens_hour),
+    ]:
+        if bucket.limit > 0 and bucket.usage_pct >= 80:
+            reset = _fmt_seconds(bucket.remaining_seconds_now)
+            warnings.append(f"  ⚠ {label} at {bucket.usage_pct:.0f}% — resets in {reset}")
+
+    if warnings:
+        lines.append("")
+        lines.extend(warnings)
+
+    return "\n".join(lines)
+
+
+def format_rate_limit_compact(state: RateLimitState) -> str:
+    """One-line compact summary for status bars / gateway messages."""
+    if not state.has_data:
+        return "No rate limit data."
+
+    rm = state.requests_min
+    tm = state.tokens_min
+    rh = state.requests_hour
+    th = state.tokens_hour
+
+    parts = []
+    if rm.limit > 0:
+        parts.append(f"RPM: {rm.remaining}/{rm.limit}")
+    if rh.limit > 0:
+        parts.append(f"RPH: {_fmt_count(rh.remaining)}/{_fmt_count(rh.limit)} (resets {_fmt_seconds(rh.remaining_seconds_now)})")
+    if tm.limit > 0:
+        parts.append(f"TPM: {_fmt_count(tm.remaining)}/{_fmt_count(tm.limit)}")
+    if th.limit > 0:
+        parts.append(f"TPH: {_fmt_count(th.remaining)}/{_fmt_count(th.limit)} (resets {_fmt_seconds(th.remaining_seconds_now)})")
+
+    return " | ".join(parts)

agent/redact.py

@@ -13,11 +13,19 @@ import re
 
 logger = logging.getLogger(__name__)
 
+# Snapshot at import time so runtime env mutations (e.g. LLM-generated
+# `export HERMES_REDACT_SECRETS=false`) cannot disable redaction mid-session.
+_REDACT_ENABLED = os.getenv("HERMES_REDACT_SECRETS", "").lower() not in ("0", "false", "no", "off")
+
 # Known API key prefixes -- match the prefix + contiguous token chars
 _PREFIX_PATTERNS = [
     r"sk-[A-Za-z0-9_-]{10,}",           # OpenAI / OpenRouter / Anthropic (sk-ant-*)
     r"ghp_[A-Za-z0-9]{10,}",            # GitHub PAT (classic)
     r"github_pat_[A-Za-z0-9_]{10,}",    # GitHub PAT (fine-grained)
+    r"gho_[A-Za-z0-9]{10,}",            # GitHub OAuth access token
+    r"ghu_[A-Za-z0-9]{10,}",            # GitHub user-to-server token
+    r"ghs_[A-Za-z0-9]{10,}",            # GitHub server-to-server token
+    r"ghr_[A-Za-z0-9]{10,}",            # GitHub refresh token
     r"xox[baprs]-[A-Za-z0-9-]{10,}",    # Slack tokens
     r"AIza[A-Za-z0-9_-]{30,}",          # Google API keys
     r"pplx-[A-Za-z0-9]{10,}",           # Perplexity
@@ -40,13 +48,18 @@ _PREFIX_PATTERNS = [
     r"sk_[A-Za-z0-9_]{10,}",            # ElevenLabs TTS key (sk_ underscore, not sk- dash)
     r"tvly-[A-Za-z0-9]{10,}",           # Tavily search API key
     r"exa_[A-Za-z0-9]{10,}",            # Exa search API key
+    r"gsk_[A-Za-z0-9]{10,}",            # Groq Cloud API key
+    r"syt_[A-Za-z0-9]{10,}",            # Matrix access token
+    r"retaindb_[A-Za-z0-9]{10,}",       # RetainDB API key
+    r"hsk-[A-Za-z0-9]{10,}",            # Hindsight API key
+    r"mem0_[A-Za-z0-9]{10,}",           # Mem0 Platform API key
+    r"brv_[A-Za-z0-9]{10,}",            # ByteRover API key
 ]
 
 # ENV assignment patterns: KEY=value where KEY contains a secret-like name
 _SECRET_ENV_NAMES = r"(?:API_?KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH)"
 _ENV_ASSIGN_RE = re.compile(
-    rf"([A-Z_]*{_SECRET_ENV_NAMES}[A-Z_]*)\s*=\s*(['\"]?)(\S+)\2",
-    re.IGNORECASE,
+    rf"([A-Z0-9_]{{0,50}}{_SECRET_ENV_NAMES}[A-Z0-9_]{{0,50}})\s*=\s*(['\"]?)(\S+)\2",
 )
 
 # JSON field patterns: "apiKey": "value", "token": "value", etc.
@@ -109,7 +122,7 @@ def redact_sensitive_text(text: str) -> str:
         text = str(text)
     if not text:
         return text
-    if os.getenv("HERMES_REDACT_SECRETS", "").lower() in ("0", "false", "no", "off"):
+    if not _REDACT_ENABLED:
         return text
 
     # Known prefixes (sk-, ghp_, etc.)

agent/retry_utils.py

@@ -0,0 +1,57 @@
+"""Retry utilities — jittered backoff for decorrelated retries.
+
+Replaces fixed exponential backoff with jittered delays to prevent
+thundering-herd retry spikes when multiple sessions hit the same
+rate-limited provider concurrently.
+"""
+
+import random
+import threading
+import time
+
+# Monotonic counter for jitter seed uniqueness within the same process.
+# Protected by a lock to avoid race conditions in concurrent retry paths
+# (e.g. multiple gateway sessions retrying simultaneously).
+_jitter_counter = 0
+_jitter_lock = threading.Lock()
+
+
+def jittered_backoff(
+    attempt: int,
+    *,
+    base_delay: float = 5.0,
+    max_delay: float = 120.0,
+    jitter_ratio: float = 0.5,
+) -> float:
+    """Compute a jittered exponential backoff delay.
+
+    Args:
+        attempt: 1-based retry attempt number.
+        base_delay: Base delay in seconds for attempt 1.
+        max_delay: Maximum delay cap in seconds.
+        jitter_ratio: Fraction of computed delay to use as random jitter
+            range.  0.5 means jitter is uniform in [0, 0.5 * delay].
+
+    Returns:
+        Delay in seconds: min(base * 2^(attempt-1), max_delay) + jitter.
+
+    The jitter decorrelates concurrent retries so multiple sessions
+    hitting the same provider don't all retry at the same instant.
+    """
+    global _jitter_counter
+    with _jitter_lock:
+        _jitter_counter += 1
+        tick = _jitter_counter
+
+    exponent = max(0, attempt - 1)
+    if exponent >= 63 or base_delay <= 0:
+        delay = max_delay
+    else:
+        delay = min(base_delay * (2 ** exponent), max_delay)
+
+    # Seed from time + counter for decorrelation even with coarse clocks.
+    seed = (time.time_ns() ^ (tick * 0x9E3779B9)) & 0xFFFFFFFF
+    rng = random.Random(seed)
+    jitter = rng.uniform(0, jitter_ratio * delay)
+
+    return delay + jitter

agent/self_modify.py

@@ -0,0 +1,302 @@
+"""Self-Modifying Prompt Engine — agent learns from its own failures.
+
+Analyzes session transcripts, identifies failure patterns, and generates
+prompt patches to prevent future failures.
+
+The loop: fail → analyze → rewrite → retry → verify improvement.
+
+Usage:
+    from agent.self_modify import PromptLearner
+    learner = PromptLearner()
+    patches = learner.analyze_session(session_id)
+    learner.apply_patches(patches)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+HERMES_HOME = Path(os.getenv("HERMES_HOME", Path.home() / ".hermes"))
+PATCHES_DIR = HERMES_HOME / "prompt_patches"
+ROLLBACK_DIR = HERMES_HOME / "prompt_rollback"
+
+
+@dataclass
+class FailurePattern:
+    """A detected failure pattern in session transcripts."""
+    pattern_type: str  # retry_loop, timeout, error_hallucination, context_loss
+    description: str
+    frequency: int
+    example_messages: List[str] = field(default_factory=list)
+    suggested_fix: str = ""
+
+
+@dataclass
+class PromptPatch:
+    """A modification to the system prompt based on failure analysis."""
+    id: str
+    failure_type: str
+    original_rule: str
+    new_rule: str
+    confidence: float
+    applied_at: Optional[float] = None
+    reverted: bool = False
+
+
+# Failure detection patterns
+FAILURE_SIGNALS = {
+    "retry_loop": {
+        "patterns": [
+            r"(?i)retry(?:ing)?\s*(?:attempt|again)",
+            r"(?i)failed.*retrying",
+            r"(?i)error.*again",
+            r"(?i)attempt\s+\d+\s*(?:of|/)\s*\d+",
+        ],
+        "description": "Agent stuck in retry loop",
+    },
+    "timeout": {
+        "patterns": [
+            r"(?i)timed?\s*out",
+            r"(?i)deadline\s+exceeded",
+            r"(?i)took\s+(?:too\s+)?long",
+        ],
+        "description": "Operation timed out",
+    },
+    "hallucination": {
+        "patterns": [
+            r"(?i)i\s+(?:don't|do\s+not)\s+(?:have|see|find)\s+(?:any|that|this)\s+(?:information|data|file)",
+            r"(?i)the\s+file\s+doesn't\s+exist",
+            r"(?i)i\s+(?:made|invented|fabricated)\s+(?:that\s+up|this)",
+        ],
+        "description": "Agent hallucinated or fabricated information",
+    },
+    "context_loss": {
+        "patterns": [
+            r"(?i)i\s+(?:don't|do\s+not)\s+(?:remember|recall|know)\s+(?:what|where|when|how)",
+            r"(?i)could\s+you\s+remind\s+me",
+            r"(?i)what\s+were\s+we\s+(?:doing|working|talking)\s+(?:on|about)",
+        ],
+        "description": "Agent lost context from earlier in conversation",
+    },
+    "tool_failure": {
+        "patterns": [
+            r"(?i)tool\s+(?:call|execution)\s+failed",
+            r"(?i)command\s+not\s+found",
+            r"(?i)permission\s+denied",
+            r"(?i)no\s+such\s+file",
+        ],
+        "description": "Tool execution failed",
+    },
+}
+
+# Prompt improvement templates
+PROMPT_FIXES = {
+    "retry_loop": (
+        "If an operation fails more than twice, stop retrying. "
+        "Report the failure and ask the user for guidance. "
+        "Do not enter retry loops — they waste tokens."
+    ),
+    "timeout": (
+        "For operations that may take long, set a timeout and report "
+        "progress. If an operation takes more than 30 seconds, report "
+        "what you've done so far and ask if you should continue."
+    ),
+    "hallucination": (
+        "If you cannot find information, say 'I don't know' or "
+        "'I couldn't find that.' Never fabricate information. "
+        "If a file doesn't exist, say so — don't guess its contents."
+    ),
+    "context_loss": (
+        "When you need context from earlier in the conversation, "
+        "use session_search to find it. Don't ask the user to repeat themselves."
+    ),
+    "tool_failure": (
+        "If a tool fails, check the error message and try a different approach. "
+        "Don't retry the exact same command — diagnose first."
+    ),
+}
+
+
+class PromptLearner:
+    """Analyze session transcripts and generate prompt improvements."""
+
+    def __init__(self):
+        PATCHES_DIR.mkdir(parents=True, exist_ok=True)
+        ROLLBACK_DIR.mkdir(parents=True, exist_ok=True)
+
+    def analyze_session(self, session_data: dict) -> List[FailurePattern]:
+        """Analyze a session for failure patterns.
+
+        Args:
+            session_data: Session dict with 'messages' list.
+
+        Returns:
+            List of detected failure patterns.
+        """
+        messages = session_data.get("messages", [])
+        patterns_found: Dict[str, FailurePattern] = {}
+
+        for msg in messages:
+            content = str(msg.get("content", ""))
+            role = msg.get("role", "")
+
+            # Only analyze assistant messages and tool results
+            if role not in ("assistant", "tool"):
+                continue
+
+            for failure_type, config in FAILURE_SIGNALS.items():
+                for pattern in config["patterns"]:
+                    if re.search(pattern, content):
+                        if failure_type not in patterns_found:
+                            patterns_found[failure_type] = FailurePattern(
+                                pattern_type=failure_type,
+                                description=config["description"],
+                                frequency=0,
+                                suggested_fix=PROMPT_FIXES.get(failure_type, ""),
+                            )
+                        patterns_found[failure_type].frequency += 1
+                        if len(patterns_found[failure_type].example_messages) < 3:
+                            patterns_found[failure_type].example_messages.append(
+                                content[:200]
+                            )
+                        break  # One match per message per type is enough
+
+        return list(patterns_found.values())
+
+    def generate_patches(self, patterns: List[FailurePattern],
+                         min_confidence: float = 0.7) -> List[PromptPatch]:
+        """Generate prompt patches from failure patterns.
+
+        Args:
+            patterns: Detected failure patterns.
+            min_confidence: Minimum confidence to generate a patch.
+
+        Returns:
+            List of prompt patches.
+        """
+        patches = []
+        for pattern in patterns:
+            # Confidence based on frequency
+            if pattern.frequency >= 3:
+                confidence = 0.9
+            elif pattern.frequency >= 2:
+                confidence = 0.75
+            else:
+                confidence = 0.5
+
+            if confidence < min_confidence:
+                continue
+
+            if not pattern.suggested_fix:
+                continue
+
+            patch = PromptPatch(
+                id=f"{pattern.pattern_type}-{int(time.time())}",
+                failure_type=pattern.pattern_type,
+                original_rule="(missing — no existing rule for this pattern)",
+                new_rule=pattern.suggested_fix,
+                confidence=confidence,
+            )
+            patches.append(patch)
+
+        return patches
+
+    def apply_patches(self, patches: List[PromptPatch],
+                      prompt_path: Optional[str] = None) -> int:
+        """Apply patches to the system prompt.
+
+        Args:
+            patches: Patches to apply.
+            prompt_path: Path to prompt file (default: ~/.hermes/system_prompt.md)
+
+        Returns:
+            Number of patches applied.
+        """
+        if prompt_path is None:
+            prompt_path = str(HERMES_HOME / "system_prompt.md")
+
+        prompt_file = Path(prompt_path)
+
+        # Backup current prompt
+        if prompt_file.exists():
+            backup = ROLLBACK_DIR / f"{prompt_file.name}.{int(time.time())}.bak"
+            backup.write_text(prompt_file.read_text())
+
+        # Read current prompt
+        current = prompt_file.read_text() if prompt_file.exists() else ""
+
+        # Apply patches
+        applied = 0
+        additions = []
+        for patch in patches:
+            if patch.new_rule not in current:
+                additions.append(f"\n## Auto-learned: {patch.failure_type}\n{patch.new_rule}")
+                patch.applied_at = time.time()
+                applied += 1
+
+        if additions:
+            new_content = current + "\n".join(additions)
+            prompt_file.write_text(new_content)
+
+            # Log patches
+            patches_file = PATCHES_DIR / f"patches-{int(time.time())}.json"
+            with open(patches_file, "w") as f:
+                json.dump([p.__dict__ for p in patches], f, indent=2, default=str)
+
+        logger.info("Applied %d prompt patches", applied)
+        return applied
+
+    def rollback_last(self, prompt_path: Optional[str] = None) -> bool:
+        """Rollback to the most recent backup.
+
+        Args:
+            prompt_path: Path to prompt file.
+
+        Returns:
+            True if rollback succeeded.
+        """
+        if prompt_path is None:
+            prompt_path = str(HERMES_HOME / "system_prompt.md")
+
+        backups = sorted(ROLLBACK_DIR.glob("*.bak"), reverse=True)
+        if not backups:
+            logger.warning("No backups to rollback to")
+            return False
+
+        latest = backups[0]
+        Path(prompt_path).write_text(latest.read_text())
+        logger.info("Rolled back to %s", latest.name)
+        return True
+
+    def learn_from_session(self, session_data: dict) -> Dict[str, Any]:
+        """Full learning cycle: analyze → patch → apply.
+
+        Args:
+            session_data: Session dict.
+
+        Returns:
+            Summary of what was learned and applied.
+        """
+        patterns = self.analyze_session(session_data)
+        patches = self.generate_patches(patterns)
+        applied = self.apply_patches(patches)
+
+        return {
+            "patterns_detected": len(patterns),
+            "patches_generated": len(patches),
+            "patches_applied": applied,
+            "patterns": [
+                {"type": p.pattern_type, "frequency": p.frequency, "description": p.description}
+                for p in patterns
+            ],
+        }

agent/session_compactor.py

@@ -0,0 +1,231 @@
+"""Session compaction with fact extraction.
+
+Before compressing conversation context, extracts durable facts
+(user preferences, corrections, project details) and saves them
+to the fact store so they survive compression.
+
+Usage:
+    from agent.session_compactor import extract_and_save_facts
+    facts = extract_and_save_facts(messages)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ExtractedFact:
+    """A fact extracted from conversation."""
+    category: str       # "user_pref", "correction", "project", "tool_quirk", "general"
+    entity: str         # what the fact is about
+    content: str        # the fact itself
+    confidence: float   # 0.0-1.0
+    source_turn: int    # which message turn it came from
+    timestamp: float = 0.0
+
+
+# Patterns that indicate user preferences
+_PREFERENCE_PATTERNS = [
+    (r"(?:I|we) (?:prefer|like|want|need) (.+?)(?:\.|$)", "preference"),
+    (r"(?:always|never) (?:use|do|run|deploy) (.+?)(?:\.|$)", "preference"),
+    (r"(?:my|our) (?:default|preferred|usual) (.+?) (?:is|are) (.+?)(?:\.|$)", "preference"),
+    (r"(?:make sure|ensure|remember) (?:to|that) (.+?)(?:\.|$)", "instruction"),
+    (r"(?:don'?t|do not) (?:ever|ever again) (.+?)(?:\.|$)", "constraint"),
+]
+
+# Patterns that indicate corrections
+_CORRECTION_PATTERNS = [
+    (r"(?:actually|no[, ]|wait[, ]|correction[: ]|sorry[, ]) (.+)", "correction"),
+    (r"(?:I meant|what I meant was|the correct) (.+?)(?:\.|$)", "correction"),
+    (r"(?:it'?s|its) (?:not|shouldn'?t be|wrong) (.+?)(?:\.|$)", "correction"),
+]
+
+# Patterns that indicate project/tool facts
+_PROJECT_PATTERNS = [
+    (r"(?:the |our )?(?:project|repo|codebase|code) (?:is|uses|needs|requires) (.+?)(?:\.|$)", "project"),
+    (r"(?:deploy|push|commit) (?:to|on) (.+?)(?:\.|$)", "project"),
+    (r"(?:this|that|the) (?:server|host|machine|VPS) (?:is|runs|has) (.+?)(?:\.|$)", "infrastructure"),
+    (r"(?:model|provider|engine) (?:is|should be|needs to be) (.+?)(?:\.|$)", "config"),
+]
+
+
+def extract_facts_from_messages(messages: List[Dict[str, Any]]) -> List[ExtractedFact]:
+    """Extract durable facts from conversation messages.
+
+    Scans user messages for preferences, corrections, project facts,
+    and infrastructure details that should survive compression.
+    """
+    facts = []
+    seen_contents = set()
+
+    for turn_idx, msg in enumerate(messages):
+        role = msg.get("role", "")
+        content = msg.get("content", "")
+
+        # Only scan user messages and assistant responses with corrections
+        if role not in ("user", "assistant"):
+            continue
+        if not content or not isinstance(content, str):
+            continue
+        if len(content) < 10:
+            continue
+
+        # Skip tool results and system messages
+        if role == "assistant" and msg.get("tool_calls"):
+            continue
+
+        extracted = _extract_from_text(content, turn_idx, role)
+
+        # Deduplicate by content
+        for fact in extracted:
+            key = f"{fact.category}:{fact.content[:100]}"
+            if key not in seen_contents:
+                seen_contents.add(key)
+                facts.append(fact)
+
+    return facts
+
+
+def _extract_from_text(text: str, turn_idx: int, role: str) -> List[ExtractedFact]:
+    """Extract facts from a single text block."""
+    facts = []
+    timestamp = time.time()
+
+    # Clean text for pattern matching
+    clean = text.strip()
+
+    # User preference patterns (from user messages)
+    if role == "user":
+        for pattern, subcategory in _PREFERENCE_PATTERNS:
+            for match in re.finditer(pattern, clean, re.IGNORECASE):
+                content = match.group(1).strip() if match.lastindex else match.group(0).strip()
+                if len(content) > 5:
+                    facts.append(ExtractedFact(
+                        category=f"user_pref.{subcategory}",
+                        entity="user",
+                        content=content[:200],
+                        confidence=0.7,
+                        source_turn=turn_idx,
+                        timestamp=timestamp,
+                    ))
+
+    # Correction patterns (from user messages)
+    if role == "user":
+        for pattern, subcategory in _CORRECTION_PATTERNS:
+            for match in re.finditer(pattern, clean, re.IGNORECASE):
+                content = match.group(1).strip() if match.lastindex else match.group(0).strip()
+                if len(content) > 5:
+                    facts.append(ExtractedFact(
+                        category=f"correction.{subcategory}",
+                        entity="user",
+                        content=content[:200],
+                        confidence=0.8,
+                        source_turn=turn_idx,
+                        timestamp=timestamp,
+                    ))
+
+    # Project/infrastructure patterns (from both user and assistant)
+    for pattern, subcategory in _PROJECT_PATTERNS:
+        for match in re.finditer(pattern, clean, re.IGNORECASE):
+            content = match.group(1).strip() if match.lastindex else match.group(0).strip()
+            if len(content) > 5:
+                facts.append(ExtractedFact(
+                    category=f"project.{subcategory}",
+                    entity=subcategory,
+                    content=content[:200],
+                    confidence=0.6,
+                    source_turn=turn_idx,
+                    timestamp=timestamp,
+                ))
+
+    return facts
+
+
+def save_facts_to_store(facts: List[ExtractedFact], fact_store_fn=None) -> int:
+    """Save extracted facts to the fact store.
+
+    Args:
+        facts: List of extracted facts.
+        fact_store_fn: Optional callable(category, entity, content, trust).
+            If None, uses the holographic fact store if available.
+
+    Returns:
+        Number of facts saved.
+    """
+    saved = 0
+
+    if fact_store_fn:
+        for fact in facts:
+            try:
+                fact_store_fn(
+                    category=fact.category,
+                    entity=fact.entity,
+                    content=fact.content,
+                    trust=fact.confidence,
+                )
+                saved += 1
+            except Exception as e:
+                logger.debug("Failed to save fact: %s", e)
+    else:
+        # Try holographic fact store
+        try:
+            from fact_store import fact_store as _fs
+            for fact in facts:
+                try:
+                    _fs(
+                        action="add",
+                        content=fact.content,
+                        category=fact.category,
+                        tags=fact.entity,
+                        trust_delta=fact.confidence - 0.5,
+                    )
+                    saved += 1
+                except Exception as e:
+                    logger.debug("Failed to save fact via fact_store: %s", e)
+        except ImportError:
+            logger.debug("fact_store not available — facts not persisted")
+
+    return saved
+
+
+def extract_and_save_facts(
+    messages: List[Dict[str, Any]],
+    fact_store_fn=None,
+) -> Tuple[List[ExtractedFact], int]:
+    """Extract facts from messages and save them.
+
+    Returns (extracted_facts, saved_count).
+    """
+    facts = extract_facts_from_messages(messages)
+    if facts:
+        logger.info("Extracted %d facts from conversation", len(facts))
+        saved = save_facts_to_store(facts, fact_store_fn)
+        logger.info("Saved %d/%d facts to store", saved, len(facts))
+    else:
+        saved = 0
+    return facts, saved
+
+
+def format_facts_summary(facts: List[ExtractedFact]) -> str:
+    """Format extracted facts as a readable summary."""
+    if not facts:
+        return "No facts extracted."
+
+    by_category = {}
+    for f in facts:
+        by_category.setdefault(f.category, []).append(f)
+
+    lines = [f"Extracted {len(facts)} facts:", ""]
+    for cat, cat_facts in sorted(by_category.items()):
+        lines.append(f"  {cat}:")
+        for f in cat_facts:
+            lines.append(f"    - {f.content[:80]}")
+    return "\n".join(lines)

agent/shield.py

@@ -0,0 +1,24 @@
+
+import logging
+from tools.shield.detector import ShieldDetector, Verdict, CRISIS_SYSTEM_PROMPT, SAFE_SIX_MODELS
+
+logger = logging.getLogger(__name__)
+
+_detector = None
+
+def get_detector():
+    global _detector
+    if _detector is None:
+        _detector = ShieldDetector()
+    return _detector
+
+def scan_text(text: str):
+    """Scan text for jailbreaks and crisis signals using SHIELD."""
+    detector = get_detector()
+    return detector.detect(text)
+
+def is_crisis(verdict: str) -> bool:
+    return verdict in [Verdict.CRISIS_DETECTED.value, Verdict.CRISIS_UNDER_ATTACK.value]
+
+def is_jailbreak(verdict: str) -> bool:
+    return verdict in [Verdict.JAILBREAK_DETECTED.value, Verdict.CRISIS_UNDER_ATTACK.value]

agent/skill_commands.py

@@ -12,18 +12,15 @@ from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, Optional
 
-from agent.skill_security import (
-    validate_skill_name,
-    resolve_skill_path,
-    SkillSecurityError,
-    PathTraversalError,
-    InvalidSkillNameError,
-)
+from hermes_constants import display_hermes_home
 
 logger = logging.getLogger(__name__)
 
 _skill_commands: Dict[str, Dict[str, Any]] = {}
 _PLAN_SLUG_RE = re.compile(r"[^a-z0-9]+")
+# Patterns for sanitizing skill names into clean hyphen-separated slugs.
+_SKILL_INVALID_CHARS = re.compile(r"[^a-z0-9-]")
+_SKILL_MULTI_HYPHEN = re.compile(r"-{2,}")
 
 
 def build_plan_path(
@@ -53,37 +50,17 @@ def _load_skill_payload(skill_identifier: str, task_id: str | None = None) -> tu
     if not raw_identifier:
         return None
 
-    # Security: Validate skill identifier to prevent path traversal (V-011)
-    try:
-        validate_skill_name(raw_identifier, allow_path_separator=True)
-    except SkillSecurityError as e:
-        logger.warning("Security: Blocked skill loading attempt with invalid identifier '%s': %s", raw_identifier, e)
-        return None
-
     try:
         from tools.skills_tool import SKILLS_DIR, skill_view
 
-        # Security: Block absolute paths and home directory expansion attempts
-        identifier_path = Path(raw_identifier)
+        identifier_path = Path(raw_identifier).expanduser()
         if identifier_path.is_absolute():
-            logger.warning("Security: Blocked absolute path in skill identifier: %s", raw_identifier)
-            return None
-
-        # Normalize the identifier: remove leading slashes and validate
-        normalized = raw_identifier.lstrip("/")
-
-        # Security: Double-check no traversal patterns remain after normalization
-        if ".." in normalized or "~" in normalized:
-            logger.warning("Security: Blocked path traversal in skill identifier: %s", raw_identifier)
-            return None
-
-        # Security: Verify the resolved path stays within SKILLS_DIR
-        try:
-            target_path = (SKILLS_DIR / normalized).resolve()
-            target_path.relative_to(SKILLS_DIR.resolve())
-        except (ValueError, OSError):
-            logger.warning("Security: Skill path escapes skills directory: %s", raw_identifier)
-            return None
+            try:
+                normalized = str(identifier_path.resolve().relative_to(SKILLS_DIR.resolve()))
+            except Exception:
+                normalized = raw_identifier
+        else:
+            normalized = raw_identifier.lstrip("/")
 
         loaded_skill = json.loads(skill_view(normalized, task_id=task_id))
     except Exception:
@@ -104,6 +81,45 @@ def _load_skill_payload(skill_identifier: str, task_id: str | None = None) -> tu
     return loaded_skill, skill_dir, skill_name
 
 
+def _inject_skill_config(loaded_skill: dict[str, Any], parts: list[str]) -> None:
+    """Resolve and inject skill-declared config values into the message parts.
+
+    If the loaded skill's frontmatter declares ``metadata.hermes.config``
+    entries, their current values (from config.yaml or defaults) are appended
+    as a ``[Skill config: ...]`` block so the agent knows the configured values
+    without needing to read config.yaml itself.
+    """
+    try:
+        from agent.skill_utils import (
+            extract_skill_config_vars,
+            parse_frontmatter,
+            resolve_skill_config_values,
+        )
+
+        # The loaded_skill dict contains the raw content which includes frontmatter
+        raw_content = str(loaded_skill.get("raw_content") or loaded_skill.get("content") or "")
+        if not raw_content:
+            return
+
+        frontmatter, _ = parse_frontmatter(raw_content)
+        config_vars = extract_skill_config_vars(frontmatter)
+        if not config_vars:
+            return
+
+        resolved = resolve_skill_config_values(config_vars)
+        if not resolved:
+            return
+
+        lines = ["", f"[Skill config (from {display_hermes_home()}/config.yaml):"]
+        for key, value in resolved.items():
+            display_val = str(value) if value else "(not set)"
+            lines.append(f"  {key} = {display_val}")
+        lines.append("]")
+        parts.extend(lines)
+    except Exception:
+        pass  # Non-critical — skill still loads without config injection
+
+
 def _build_skill_message(
     loaded_skill: dict[str, Any],
     skill_dir: Path | None,
@@ -118,6 +134,9 @@ def _build_skill_message(
 
     parts = [activation_note, "", content.strip()]
 
+    # ── Inject resolved skill config values ──
+    _inject_skill_config(loaded_skill, parts)
+
     if loaded_skill.get("setup_skipped"):
         parts.extend(
             [
@@ -151,7 +170,7 @@ def _build_skill_message(
             subdir_path = skill_dir / subdir
             if subdir_path.exists():
                 for f in sorted(subdir_path.rglob("*")):
-                    if f.is_file():
+                    if f.is_file() and not f.is_symlink():
                         rel = str(f.relative_to(skill_dir))
                         supporting.append(rel)
 
@@ -224,7 +243,14 @@ def scan_skill_commands() -> Dict[str, Dict[str, Any]]:
                                 description = line[:80]
                                 break
                     seen_names.add(name)
+                    # Normalize to hyphen-separated slug, stripping
+                    # non-alnum chars (e.g. +, /) to avoid invalid
+                    # Telegram command names downstream.
                     cmd_name = name.lower().replace(' ', '-').replace('_', '-')
+                    cmd_name = _SKILL_INVALID_CHARS.sub('', cmd_name)
+                    cmd_name = _SKILL_MULTI_HYPHEN.sub('-', cmd_name).strip('-')
+                    if not cmd_name:
+                        continue
                     _skill_commands[f"/{cmd_name}"] = {
                         "name": name,
                         "description": description or f"Invoke the {name} skill",
@@ -245,6 +271,25 @@ def get_skill_commands() -> Dict[str, Dict[str, Any]]:
     return _skill_commands
 
 
+def resolve_skill_command_key(command: str) -> Optional[str]:
+    """Resolve a user-typed /command to its canonical skill_cmds key.
+
+    Skills are always stored with hyphens — ``scan_skill_commands`` normalizes
+    spaces and underscores to hyphens when building the key. Hyphens and
+    underscores are treated interchangeably in user input: this matches
+    ``_check_unavailable_skill`` and accommodates Telegram bot-command names
+    (which disallow hyphens, so ``/claude-code`` is registered as
+    ``/claude_code`` and comes back in the underscored form).
+
+    Returns the matching ``/slug`` key from ``get_skill_commands()`` or
+    ``None`` if no match.
+    """
+    if not command:
+        return None
+    cmd_key = f"/{command.replace('_', '-')}"
+    return cmd_key if cmd_key in get_skill_commands() else None
+
+
 def build_skill_invocation_message(
     cmd_key: str,
     user_instruction: str = "",

agent/skill_security.py

@@ -1,213 +0,0 @@
-"""Security utilities for skill loading and validation.
-
-Provides path traversal protection and input validation for skill names
-to prevent security vulnerabilities like V-011 (Skills Guard Bypass).
-"""
-
-import re
-from pathlib import Path
-from typing import Optional, Tuple
-
-# Strict skill name validation: alphanumeric, hyphens, underscores only
-# This prevents path traversal attacks via skill names like "../../../etc/passwd"
-VALID_SKILL_NAME_PATTERN = re.compile(r'^[a-zA-Z0-9._-]+$')
-
-# Maximum skill name length to prevent other attack vectors
-MAX_SKILL_NAME_LENGTH = 256
-
-# Suspicious patterns that indicate path traversal attempts
-PATH_TRAVERSAL_PATTERNS = [
-    "..",           # Parent directory reference
-    "~",            # Home directory expansion
-    "/",            # Absolute path (Unix)
-    "\\",           # Windows path separator
-    "//",           # Protocol-relative or UNC path
-    "file:",        # File protocol
-    "ftp:",         # FTP protocol
-    "http:",        # HTTP protocol
-    "https:",       # HTTPS protocol
-    "data:",        # Data URI
-    "javascript:",  # JavaScript protocol
-    "vbscript:",    # VBScript protocol
-]
-
-# Characters that should never appear in skill names
-INVALID_CHARACTERS = set([
-    '\x00', '\x01', '\x02', '\x03', '\x04', '\x05', '\x06', '\x07',
-    '\x08', '\x09', '\x0a', '\x0b', '\x0c', '\x0d', '\x0e', '\x0f',
-    '\x10', '\x11', '\x12', '\x13', '\x14', '\x15', '\x16', '\x17',
-    '\x18', '\x19', '\x1a', '\x1b', '\x1c', '\x1d', '\x1e', '\x1f',
-    '<', '>', '|', '&', ';', '$', '`', '"', "'",
-])
-
-
-class SkillSecurityError(Exception):
-    """Raised when a skill name fails security validation."""
-    pass
-
-
-class PathTraversalError(SkillSecurityError):
-    """Raised when path traversal is detected in a skill name."""
-    pass
-
-
-class InvalidSkillNameError(SkillSecurityError):
-    """Raised when a skill name contains invalid characters."""
-    pass
-
-
-def validate_skill_name(name: str, allow_path_separator: bool = False) -> None:
-    """Validate a skill name for security issues.
-
-    Args:
-        name: The skill name or identifier to validate
-        allow_path_separator: If True, allows '/' for category/skill paths (e.g., "mlops/axolotl")
-
-    Raises:
-        PathTraversalError: If path traversal patterns are detected
-        InvalidSkillNameError: If the name contains invalid characters
-        SkillSecurityError: For other security violations
-    """
-    if not name or not isinstance(name, str):
-        raise InvalidSkillNameError("Skill name must be a non-empty string")
-
-    if len(name) > MAX_SKILL_NAME_LENGTH:
-        raise InvalidSkillNameError(
-            f"Skill name exceeds maximum length of {MAX_SKILL_NAME_LENGTH} characters"
-        )
-
-    # Check for null bytes and other control characters
-    for char in name:
-        if char in INVALID_CHARACTERS:
-            raise InvalidSkillNameError(
-                f"Skill name contains invalid character: {repr(char)}"
-            )
-
-    # Validate against allowed character pattern first
-    pattern = r'^[a-zA-Z0-9._-]+$' if not allow_path_separator else r'^[a-zA-Z0-9._/-]+$'
-    if not re.match(pattern, name):
-        invalid_chars = set(c for c in name if not re.match(r'[a-zA-Z0-9._/-]', c))
-        raise InvalidSkillNameError(
-            f"Skill name contains invalid characters: {sorted(invalid_chars)}. "
-            "Only alphanumeric characters, hyphens, underscores, dots, "
-            f"{'and forward slashes ' if allow_path_separator else ''}are allowed."
-        )
-
-    # Check for path traversal patterns (excluding '/' when path separators are allowed)
-    name_lower = name.lower()
-    patterns_to_check = PATH_TRAVERSAL_PATTERNS.copy()
-    if allow_path_separator:
-        # Remove '/' from patterns when path separators are allowed
-        patterns_to_check = [p for p in patterns_to_check if p != '/']
-
-    for pattern in patterns_to_check:
-        if pattern in name_lower:
-            raise PathTraversalError(
-                f"Path traversal detected in skill name: '{pattern}' is not allowed"
-            )
-
-
-def resolve_skill_path(
-    skill_name: str,
-    skills_base_dir: Path,
-    allow_path_separator: bool = True
-) -> Tuple[Path, Optional[str]]:
-    """Safely resolve a skill name to a path within the skills directory.
-
-    Args:
-        skill_name: The skill name or path (e.g., "axolotl" or "mlops/axolotl")
-        skills_base_dir: The base skills directory
-        allow_path_separator: Whether to allow '/' in skill names for categories
-
-    Returns:
-        Tuple of (resolved_path, error_message)
-        - If successful: (resolved_path, None)
-        - If failed: (skills_base_dir, error_message)
-
-    Raises:
-        PathTraversalError: If the resolved path would escape the skills directory
-    """
-    try:
-        validate_skill_name(skill_name, allow_path_separator=allow_path_separator)
-    except SkillSecurityError as e:
-        return skills_base_dir, str(e)
-
-    # Build the target path
-    try:
-        target_path = (skills_base_dir / skill_name).resolve()
-    except (OSError, ValueError) as e:
-        return skills_base_dir, f"Invalid skill path: {e}"
-
-    # Ensure the resolved path is within the skills directory
-    try:
-        target_path.relative_to(skills_base_dir.resolve())
-    except ValueError:
-        raise PathTraversalError(
-            f"Skill path '{skill_name}' resolves outside the skills directory boundary"
-        )
-
-    return target_path, None
-
-
-def sanitize_skill_identifier(identifier: str) -> str:
-    """Sanitize a skill identifier by removing dangerous characters.
-
-    This is a defensive fallback for cases where strict validation
-    cannot be applied. It removes or replaces dangerous characters.
-
-    Args:
-        identifier: The raw skill identifier
-
-    Returns:
-        A sanitized version of the identifier
-    """
-    if not identifier:
-        return ""
-
-    # Replace path traversal sequences
-    sanitized = identifier.replace("..", "")
-    sanitized = sanitized.replace("//", "/")
-
-    # Remove home directory expansion
-    if sanitized.startswith("~"):
-        sanitized = sanitized[1:]
-
-    # Remove protocol handlers
-    for protocol in ["file:", "ftp:", "http:", "https:", "data:", "javascript:", "vbscript:"]:
-        sanitized = sanitized.replace(protocol, "")
-        sanitized = sanitized.replace(protocol.upper(), "")
-
-    # Remove null bytes and control characters
-    for char in INVALID_CHARACTERS:
-        sanitized = sanitized.replace(char, "")
-
-    # Normalize path separators to forward slash
-    sanitized = sanitized.replace("\\", "/")
-
-    # Remove leading/trailing slashes and whitespace
-    sanitized = sanitized.strip("/ ").strip()
-
-    return sanitized
-
-
-def is_safe_skill_path(path: Path, allowed_base_dirs: list[Path]) -> bool:
-    """Check if a path is safely within allowed directories.
-
-    Args:
-        path: The path to check
-        allowed_base_dirs: List of allowed base directories
-
-    Returns:
-        True if the path is within allowed boundaries, False otherwise
-    """
-    try:
-        resolved = path.resolve()
-        for base_dir in allowed_base_dirs:
-            try:
-                resolved.relative_to(base_dir.resolve())
-                return True
-            except ValueError:
-                continue
-        return False
-    except (OSError, ValueError):
-        return False