fix: local test images for reliable vision benchmark (#868)

Vision benchmark used external URLs that may become unavailable,
causing flaky CI runs.

New benchmarks/test_images.json:
- 5 test images with local paths, descriptions, expected answers
- Categories: shape_color, ocr, counting

New benchmarks/test_images/:
- 5 generated PNG test images (red_circle, blue_square,
  green_triangle, text_hello, mixed_shapes)
- Deterministic, always available, ~1-3KB each

New benchmarks/vision_benchmark.py:
- load_test_dataset(): loads test_images.json
- verify_images_exist(): checks all images present
- run_vision_test(): single test with base64 image encoding
- evaluate_response(): checks expected keywords in response
- run_benchmark(): full benchmark suite
- format_report(): human-readable results
- --model, --base-url, --json flags

Closes #868

.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,6 +5,7 @@
 
 # Dependencies
 node_modules
+.venv
 
 # CI/CD
 .github

.env.example

@@ -43,6 +43,15 @@
 # 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)
@@ -81,6 +90,23 @@
 # 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
 # =============================================================================
@@ -119,6 +145,10 @@
 # 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

.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,62 +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: 10
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-        with:
-          enable-cache: true
-          cache-dependency-glob: "uv.lock"
-
-      - 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 ".[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: No duplicate models
-        run: |
-          source .venv/bin/activate
-          python scripts/check_no_duplicate_models.py
-
-      - name: Green-path E2E
-        run: |
-          source .venv/bin/activate
-          python -m pytest tests/test_green_path_e2e.py -q --tb=short -p no:xdist
-        env:
-          OPENROUTER_API_KEY: ""
-          OPENAI_API_KEY: ""
-          NOUS_API_KEY: ""

.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.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,83 +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
-    container: catthehacker/ubuntu:act-22.04
-    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

@@ -28,20 +28,20 @@ jobs:
       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@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
         with:
           python-version: '3.11'
 
       - name: Install PyYAML for skill extraction
-        run: pip install pyyaml httpx
+        run: pip install pyyaml==6.0.2 httpx==0.28.1
 
       - name: Extract skill metadata for dashboard
         run: python3 website/scripts/extract-skills.py
@@ -73,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

@@ -8,6 +8,9 @@ on:
   release:
     types: [published]
 
+permissions:
+  contents: read
+
 concurrency:
   group: docker-${{ github.ref }}
   cancel-in-progress: true
@@ -17,22 +20,29 @@ jobs:
     # 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
@@ -46,34 +56,31 @@ jobs:
 
       - name: Log in to Docker Hub
         if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
-        uses: docker/login-action@v3
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9  # v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: Push image (main branch)
+      - 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 image (release)
+      - name: Push multi-arch image (release)
         if: github.event_name == 'release'
-        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.event.release.tag_name }}
-            nousresearch/hermes-agent:${{ github.sha }}
+          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,14 +7,16 @@ on:
       - '.github/workflows/docs-site-checks.yml'
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   docs-site-checks:
     runs-on: ubuntu-latest
-    container: catthehacker/ubuntu:act-22.04
     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
@@ -24,12 +26,12 @@ 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 Python dependencies
-        run: python -m pip install ascii-guard pyyaml
+      - name: 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

.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,115 +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
-    container: catthehacker/ubuntu:act-22.04
-    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,137 +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
-    container: catthehacker/ubuntu:act-22.04
-    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

@@ -20,14 +20,14 @@ jobs:
     if: github.repository == 'NousResearch/hermes-agent'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
         with:
           python-version: '3.11'
 
       - name: Install dependencies
-        run: pip install httpx pyyaml
+        run: pip install httpx==0.28.1 pyyaml==6.0.2
 
       - name: Build skills index
         env:
@@ -35,7 +35,7 @@ jobs:
         run: python scripts/build_skills_index.py
 
       - name: Upload index artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
         with:
           name: skills-index
           path: website/static/api/skills-index.json
@@ -53,25 +53,25 @@ jobs:
     # 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@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
 
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
         with:
           name: skills-index
           path: website/static/api/
 
-      - 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@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
         with:
           python-version: '3.11'
 
       - name: Install PyYAML for skill extraction
-        run: pip install pyyaml
+        run: pip install pyyaml==6.0.2
 
       - name: Extract skill metadata for dashboard
         run: python3 website/scripts/extract-skills.py
@@ -92,10 +92,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/supply-chain-audit.yml

@@ -12,10 +12,9 @@ jobs:
   scan:
     name: Scan PR for supply chain risks
     runs-on: ubuntu-latest
-    container: catthehacker/ubuntu:act-22.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
         with:
           fetch-depth: 0
 
@@ -150,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"
@@ -184,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 }}
@@ -14,14 +17,16 @@ concurrency:
 jobs:
   test:
     runs-on: ubuntu-latest
-    container: catthehacker/ubuntu:act-22.04
     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: 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
@@ -47,10 +52,10 @@ jobs:
     timeout-minutes: 10
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
 
       - 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

.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,6 +61,4 @@ mini-swe-agent/
 # Nix
 .direnv/
 result
-
-# OpenClaw artifacts (banned)
-.claw/
+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)

BOOT.md

@@ -1,131 +0,0 @@
-# BOOT.md — Hermes Agent
-
-Fast path from clone to productive. Target: <10 minutes.
-
----
-
-## 1. Prerequisites
-
-| Tool | Why |
-|---|---|
-| Git | Clone + submodules |
-| Python 3.11+ | Runtime requirement |
-| uv | Package manager (install: `curl -LsSf https://astral.sh/uv/install.sh \| sh`) |
-| Node.js 18+ | Optional — browser tools, WhatsApp bridge |
-
----
-
-## 2. First-Time Setup
-
-```bash
-git clone --recurse-submodules https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent.git
-cd hermes-agent
-
-# Create venv
-uv venv .venv --python 3.11
-source .venv/bin/activate
-
-# Install with all extras + dev tools
-uv pip install -e ".[all,dev]"
-```
-
-> **Common pitfall:** If `uv` is not on PATH, the `setup-hermes.sh` script will attempt to install it, but manual `uv` install is faster.
-
----
-
-## 3. Smoke Tests (< 30 sec)
-
-```bash
-python scripts/smoke_test.py
-```
-
-Expected output:
-```
-OK: 4 core imports
-OK: 1 CLI entrypoints
-Smoke tests passed.
-```
-
-If imports fail with `ModuleNotFoundError`, re-run: `uv pip install -e ".[all,dev]"`
-
----
-
-## 4. Full Test Suite (excluding integration)
-
-```bash
-pytest tests/ -x --ignore=tests/integration
-```
-
-> Integration tests require a running gateway + API keys. Skip them unless you are testing platform connectivity.
-
----
-
-## 5. Run the CLI
-
-```bash
-python cli.py --help
-```
-
-To start the gateway (after configuring `~/.hermes/config.yaml`):
-```bash
-hermes gateway run
-```
-
----
-
-## 6. Repo Layout for Agents
-
-| Path | What lives here |
-|---|---|
-| `cli.py` | Main entrypoint |
-| `hermes/` | Core agent logic |
-| `toolsets/` | Built-in tool implementations |
-| `skills/` | Bundled skills (loaded automatically) |
-| `optional-skills/` | Official but opt-in skills |
-| `tests/` | pytest suite |
-| `scripts/` | Utility scripts (smoke tests, deploy validation, etc.) |
-| `.gitea/workflows/` | Forge CI (smoke + build) |
-| `.github/workflows/` | GitHub mirror CI |
-
----
-
-## 7. Gitea Workflow Conventions
-
-- **Push to `main`**: triggers `ci.yml` (smoke + build, < 5 min)
-- **Pull requests**: same CI + notebook CI if notebooks changed
-- **Merge requirement**: green smoke tests
-- Security scans run on schedule via `.github/workflows/`
-
----
-
-## 8. Common Pitfalls
-
-| Symptom | Fix |
-|---|---|
-| `No module named httpx` | `uv pip install -e ".[all,dev]"` |
-| `prompt_toolkit` missing | Included in `[all]`, but install explicitly if you used minimal deps |
-| CLI hangs on start | Check `~/.hermes/config.yaml` exists and is valid YAML |
-| API key errors | Copy `.env.example` → `.env` and fill required keys |
-| Browser tools fail | Run `npm install` in repo root |
-
----
-
-## 9. Quick Reference
-
-```bash
-# Reinstall after dependency changes
-uv pip install -e ".[all,dev]"
-
-# Run only smoke tests
-python scripts/smoke_test.py
-
-# Run syntax guard
-python scripts/syntax_guard.py
-
-# Start gateway
-hermes gateway run
-```
-
----
-
-*Last updated: 2026-04-07 by Bezalel*

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,23 +1,44 @@
+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
 
+# 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 python3-pip ripgrep ffmpeg gcc python3-dev libffi-dev && \
+        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
 
-# Install Python and Node dependencies in one layer, no cache
-RUN pip install --no-cache-dir -e ".[all]" --break-system-packages && \
-    npm install --prefer-offline --no-audit && \
+# 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

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.2.0.md

@@ -0,0 +1,383 @@
+# Hermes Agent v0.2.0 (v2026.3.12)
+
+**Release Date:** March 12, 2026
+
+> First tagged release since v0.1.0 (the initial pre-public foundation). In just over two weeks, Hermes Agent went from a small internal project to a full-featured AI agent platform — thanks to an explosion of community contributions. This release covers **216 merged pull requests** from **63 contributors**, resolving **119 issues**.
+
+---
+
+## ✨ Highlights
+
+- **Multi-Platform Messaging Gateway** — Telegram, Discord, Slack, WhatsApp, Signal, Email (IMAP/SMTP), and Home Assistant platforms with unified session management, media attachments, and per-platform tool configuration.
+
+- **MCP (Model Context Protocol) Client** — Native MCP support with stdio and HTTP transports, reconnection, resource/prompt discovery, and sampling (server-initiated LLM requests). ([#291](https://github.com/NousResearch/hermes-agent/pull/291) — @0xbyt4, [#301](https://github.com/NousResearch/hermes-agent/pull/301), [#753](https://github.com/NousResearch/hermes-agent/pull/753))
+
+- **Skills Ecosystem** — 70+ bundled and optional skills across 15+ categories with a Skills Hub for community discovery, per-platform enable/disable, conditional activation based on tool availability, and prerequisite validation. ([#743](https://github.com/NousResearch/hermes-agent/pull/743) — @teyrebaz33, [#785](https://github.com/NousResearch/hermes-agent/pull/785) — @teyrebaz33)
+
+- **Centralized Provider Router** — Unified `call_llm()`/`async_call_llm()` API replaces scattered provider logic across vision, summarization, compression, and trajectory saving. All auxiliary consumers route through a single code path with automatic credential resolution. ([#1003](https://github.com/NousResearch/hermes-agent/pull/1003))
+
+- **ACP Server** — VS Code, Zed, and JetBrains editor integration via the Agent Communication Protocol standard. ([#949](https://github.com/NousResearch/hermes-agent/pull/949))
+
+- **CLI Skin/Theme Engine** — Data-driven visual customization: banners, spinners, colors, branding. 7 built-in skins + custom YAML skins.
+
+- **Git Worktree Isolation** — `hermes -w` launches isolated agent sessions in git worktrees for safe parallel work on the same repo. ([#654](https://github.com/NousResearch/hermes-agent/pull/654))
+
+- **Filesystem Checkpoints & Rollback** — Automatic snapshots before destructive operations with `/rollback` to restore. ([#824](https://github.com/NousResearch/hermes-agent/pull/824))
+
+- **3,289 Tests** — From near-zero test coverage to a comprehensive test suite covering agent, gateway, tools, cron, and CLI.
+
+---
+
+## 🏗️ Core Agent & Architecture
+
+### Provider & Model Support
+- Centralized provider router with `resolve_provider_client()` + `call_llm()` API ([#1003](https://github.com/NousResearch/hermes-agent/pull/1003))
+- Nous Portal as first-class provider in setup ([#644](https://github.com/NousResearch/hermes-agent/issues/644))
+- OpenAI Codex (Responses API) with ChatGPT subscription support ([#43](https://github.com/NousResearch/hermes-agent/pull/43)) — @grp06
+- Codex OAuth vision support + multimodal content adapter
+- Validate `/model` against live API instead of hardcoded lists
+- Self-hosted Firecrawl support ([#460](https://github.com/NousResearch/hermes-agent/pull/460)) — @caentzminger
+- Kimi Code API support ([#635](https://github.com/NousResearch/hermes-agent/pull/635)) — @christomitov
+- MiniMax model ID update ([#473](https://github.com/NousResearch/hermes-agent/pull/473)) — @tars90percent
+- OpenRouter provider routing configuration (provider_preferences)
+- Nous credential refresh on 401 errors ([#571](https://github.com/NousResearch/hermes-agent/pull/571), [#269](https://github.com/NousResearch/hermes-agent/pull/269)) — @rewbs
+- z.ai/GLM, Kimi/Moonshot, MiniMax, Azure OpenAI as first-class providers
+- Unified `/model` and `/provider` into single view
+
+### Agent Loop & Conversation
+- Simple fallback model for provider resilience ([#740](https://github.com/NousResearch/hermes-agent/pull/740))
+- Shared iteration budget across parent + subagent delegation
+- Iteration budget pressure via tool result injection
+- Configurable subagent provider/model with full credential resolution
+- Handle 413 payload-too-large via compression instead of aborting ([#153](https://github.com/NousResearch/hermes-agent/pull/153)) — @tekelala
+- Retry with rebuilt payload after compression ([#616](https://github.com/NousResearch/hermes-agent/pull/616)) — @tripledoublev
+- Auto-compress pathologically large gateway sessions ([#628](https://github.com/NousResearch/hermes-agent/issues/628))
+- Tool call repair middleware — auto-lowercase and invalid tool handler
+- Reasoning effort configuration and `/reasoning` command ([#921](https://github.com/NousResearch/hermes-agent/pull/921))
+- Detect and block file re-read/search loops after context compression ([#705](https://github.com/NousResearch/hermes-agent/pull/705)) — @0xbyt4
+
+### Session & Memory
+- Session naming with unique titles, auto-lineage, rich listing, and resume by name ([#720](https://github.com/NousResearch/hermes-agent/pull/720))
+- Interactive session browser with search filtering ([#733](https://github.com/NousResearch/hermes-agent/pull/733))
+- Display previous messages when resuming a session ([#734](https://github.com/NousResearch/hermes-agent/pull/734))
+- Honcho AI-native cross-session user modeling ([#38](https://github.com/NousResearch/hermes-agent/pull/38)) — @erosika
+- Proactive async memory flush on session expiry
+- Smart context length probing with persistent caching + banner display
+- `/resume` command for switching to named sessions in gateway
+- Session reset policy for messaging platforms
+
+---
+
+## 📱 Messaging Platforms (Gateway)
+
+### Telegram
+- Native file attachments: send_document + send_video
+- Document file processing for PDF, text, and Office files — @tekelala
+- Forum topic session isolation ([#766](https://github.com/NousResearch/hermes-agent/pull/766)) — @spanishflu-est1918
+- Browser screenshot sharing via MEDIA: protocol ([#657](https://github.com/NousResearch/hermes-agent/pull/657))
+- Location support for find-nearby skill
+- TTS voice message accumulation fix ([#176](https://github.com/NousResearch/hermes-agent/pull/176)) — @Bartok9
+- Improved error handling and logging ([#763](https://github.com/NousResearch/hermes-agent/pull/763)) — @aydnOktay
+- Italic regex newline fix + 43 format tests ([#204](https://github.com/NousResearch/hermes-agent/pull/204)) — @0xbyt4
+
+### Discord
+- Channel topic included in session context ([#248](https://github.com/NousResearch/hermes-agent/pull/248)) — @Bartok9
+- DISCORD_ALLOW_BOTS config for bot message filtering ([#758](https://github.com/NousResearch/hermes-agent/pull/758))
+- Document and video support ([#784](https://github.com/NousResearch/hermes-agent/pull/784))
+- Improved error handling and logging ([#761](https://github.com/NousResearch/hermes-agent/pull/761)) — @aydnOktay
+
+### Slack
+- App_mention 404 fix + document/video support ([#784](https://github.com/NousResearch/hermes-agent/pull/784))
+- Structured logging replacing print statements — @aydnOktay
+
+### WhatsApp
+- Native media sending — images, videos, documents ([#292](https://github.com/NousResearch/hermes-agent/pull/292)) — @satelerd
+- Multi-user session isolation ([#75](https://github.com/NousResearch/hermes-agent/pull/75)) — @satelerd
+- Cross-platform port cleanup replacing Linux-only fuser ([#433](https://github.com/NousResearch/hermes-agent/pull/433)) — @Farukest
+- DM interrupt key mismatch fix ([#350](https://github.com/NousResearch/hermes-agent/pull/350)) — @Farukest
+
+### Signal
+- Full Signal messenger gateway via signal-cli-rest-api ([#405](https://github.com/NousResearch/hermes-agent/issues/405))
+- Media URL support in message events ([#871](https://github.com/NousResearch/hermes-agent/pull/871))
+
+### Email (IMAP/SMTP)
+- New email gateway platform — @0xbyt4
+
+### Home Assistant
+- REST tools + WebSocket gateway integration ([#184](https://github.com/NousResearch/hermes-agent/pull/184)) — @0xbyt4
+- Service discovery and enhanced setup
+- Toolset mapping fix ([#538](https://github.com/NousResearch/hermes-agent/pull/538)) — @Himess
+
+### Gateway Core
+- Expose subagent tool calls and thinking to users ([#186](https://github.com/NousResearch/hermes-agent/pull/186)) — @cutepawss
+- Configurable background process watcher notifications ([#840](https://github.com/NousResearch/hermes-agent/pull/840))
+- `edit_message()` for Telegram/Discord/Slack with fallback
+- `/compress`, `/usage`, `/update` slash commands
+- Eliminated 3x SQLite message duplication in gateway sessions ([#873](https://github.com/NousResearch/hermes-agent/pull/873))
+- Stabilize system prompt across gateway turns for cache hits ([#754](https://github.com/NousResearch/hermes-agent/pull/754))
+- MCP server shutdown on gateway exit ([#796](https://github.com/NousResearch/hermes-agent/pull/796)) — @0xbyt4
+- Pass session_db to AIAgent, fixing session_search error ([#108](https://github.com/NousResearch/hermes-agent/pull/108)) — @Bartok9
+- Persist transcript changes in /retry, /undo; fix /reset attribute ([#217](https://github.com/NousResearch/hermes-agent/pull/217)) — @Farukest
+- UTF-8 encoding fix preventing Windows crashes ([#369](https://github.com/NousResearch/hermes-agent/pull/369)) — @ch3ronsa
+
+---
+
+## 🖥️ CLI & User Experience
+
+### Interactive CLI
+- Data-driven skin/theme engine — 7 built-in skins (default, ares, mono, slate, poseidon, sisyphus, charizard) + custom YAML skins
+- `/personality` command with custom personality + disable support ([#773](https://github.com/NousResearch/hermes-agent/pull/773)) — @teyrebaz33
+- User-defined quick commands that bypass the agent loop ([#746](https://github.com/NousResearch/hermes-agent/pull/746)) — @teyrebaz33
+- `/reasoning` command for effort level and display toggle ([#921](https://github.com/NousResearch/hermes-agent/pull/921))
+- `/verbose` slash command to toggle debug at runtime ([#94](https://github.com/NousResearch/hermes-agent/pull/94)) — @cesareth
+- `/insights` command — usage analytics, cost estimation & activity patterns ([#552](https://github.com/NousResearch/hermes-agent/pull/552))
+- `/background` command for managing background processes
+- `/help` formatting with command categories
+- Bell-on-complete — terminal bell when agent finishes ([#738](https://github.com/NousResearch/hermes-agent/pull/738))
+- Up/down arrow history navigation
+- Clipboard image paste (Alt+V / Ctrl+V)
+- Loading indicators for slow slash commands ([#882](https://github.com/NousResearch/hermes-agent/pull/882))
+- Spinner flickering fix under patch_stdout ([#91](https://github.com/NousResearch/hermes-agent/pull/91)) — @0xbyt4
+- `--quiet/-Q` flag for programmatic single-query mode
+- `--fuck-it-ship-it` flag to bypass all approval prompts ([#724](https://github.com/NousResearch/hermes-agent/pull/724)) — @dmahan93
+- Tools summary flag ([#767](https://github.com/NousResearch/hermes-agent/pull/767)) — @luisv-1
+- Terminal blinking fix on SSH ([#284](https://github.com/NousResearch/hermes-agent/pull/284)) — @ygd58
+- Multi-line paste detection fix ([#84](https://github.com/NousResearch/hermes-agent/pull/84)) — @0xbyt4
+
+### Setup & Configuration
+- Modular setup wizard with section subcommands and tool-first UX
+- Container resource configuration prompts
+- Backend validation for required binaries
+- Config migration system (currently v7)
+- API keys properly routed to .env instead of config.yaml ([#469](https://github.com/NousResearch/hermes-agent/pull/469)) — @ygd58
+- Atomic write for .env to prevent API key loss on crash ([#954](https://github.com/NousResearch/hermes-agent/pull/954))
+- `hermes tools` — per-platform tool enable/disable with curses UI
+- `hermes doctor` for health checks across all configured providers
+- `hermes update` with auto-restart for gateway service
+- Show update-available notice in CLI banner
+- Multiple named custom providers
+- Shell config detection improvement for PATH setup ([#317](https://github.com/NousResearch/hermes-agent/pull/317)) — @mehmetkr-31
+- Consistent HERMES_HOME and .env path resolution ([#51](https://github.com/NousResearch/hermes-agent/pull/51), [#48](https://github.com/NousResearch/hermes-agent/pull/48)) — @deankerr
+- Docker backend fix on macOS + subagent auth for Nous Portal ([#46](https://github.com/NousResearch/hermes-agent/pull/46)) — @rsavitt
+
+---
+
+## 🔧 Tool System
+
+### MCP (Model Context Protocol)
+- Native MCP client with stdio + HTTP transports ([#291](https://github.com/NousResearch/hermes-agent/pull/291) — @0xbyt4, [#301](https://github.com/NousResearch/hermes-agent/pull/301))
+- Sampling support — server-initiated LLM requests ([#753](https://github.com/NousResearch/hermes-agent/pull/753))
+- Resource and prompt discovery
+- Automatic reconnection and security hardening
+- Banner integration, `/reload-mcp` command
+- `hermes tools` UI integration
+
+### Browser
+- Local browser backend — zero-cost headless Chromium (no Browserbase needed)
+- Console/errors tool, annotated screenshots, auto-recording, dogfood QA skill ([#745](https://github.com/NousResearch/hermes-agent/pull/745))
+- Screenshot sharing via MEDIA: on all messaging platforms ([#657](https://github.com/NousResearch/hermes-agent/pull/657))
+
+### Terminal & Execution
+- `execute_code` sandbox with json_parse, shell_quote, retry helpers
+- Docker: custom volume mounts ([#158](https://github.com/NousResearch/hermes-agent/pull/158)) — @Indelwin
+- Daytona cloud sandbox backend ([#451](https://github.com/NousResearch/hermes-agent/pull/451)) — @rovle
+- SSH backend fix ([#59](https://github.com/NousResearch/hermes-agent/pull/59)) — @deankerr
+- Shell noise filtering and login shell execution for environment consistency
+- Head+tail truncation for execute_code stdout overflow
+- Configurable background process notification modes
+
+### File Operations
+- Filesystem checkpoints and `/rollback` command ([#824](https://github.com/NousResearch/hermes-agent/pull/824))
+- Structured tool result hints (next-action guidance) for patch and search_files ([#722](https://github.com/NousResearch/hermes-agent/issues/722))
+- Docker volumes passed to sandbox container config ([#687](https://github.com/NousResearch/hermes-agent/pull/687)) — @manuelschipper
+
+---
+
+## 🧩 Skills Ecosystem
+
+### Skills System
+- Per-platform skill enable/disable ([#743](https://github.com/NousResearch/hermes-agent/pull/743)) — @teyrebaz33
+- Conditional skill activation based on tool availability ([#785](https://github.com/NousResearch/hermes-agent/pull/785)) — @teyrebaz33
+- Skill prerequisites — hide skills with unmet dependencies ([#659](https://github.com/NousResearch/hermes-agent/pull/659)) — @kshitijk4poor
+- Optional skills — shipped but not activated by default
+- `hermes skills browse` — paginated hub browsing
+- Skills sub-category organization
+- Platform-conditional skill loading
+- Atomic skill file writes ([#551](https://github.com/NousResearch/hermes-agent/pull/551)) — @aydnOktay
+- Skills sync data loss prevention ([#563](https://github.com/NousResearch/hermes-agent/pull/563)) — @0xbyt4
+- Dynamic skill slash commands for CLI and gateway
+
+### New Skills (selected)
+- **ASCII Art** — pyfiglet (571 fonts), cowsay, image-to-ascii ([#209](https://github.com/NousResearch/hermes-agent/pull/209)) — @0xbyt4
+- **ASCII Video** — Full production pipeline ([#854](https://github.com/NousResearch/hermes-agent/pull/854)) — @SHL0MS
+- **DuckDuckGo Search** — Firecrawl fallback ([#267](https://github.com/NousResearch/hermes-agent/pull/267)) — @gamedevCloudy; DDGS API expansion ([#598](https://github.com/NousResearch/hermes-agent/pull/598)) — @areu01or00
+- **Solana Blockchain** — Wallet balances, USD pricing, token names ([#212](https://github.com/NousResearch/hermes-agent/pull/212)) — @gizdusum
+- **AgentMail** — Agent-owned email inboxes ([#330](https://github.com/NousResearch/hermes-agent/pull/330)) — @teyrebaz33
+- **Polymarket** — Prediction market data (read-only) ([#629](https://github.com/NousResearch/hermes-agent/pull/629))
+- **OpenClaw Migration** — Official migration tool ([#570](https://github.com/NousResearch/hermes-agent/pull/570)) — @unmodeled-tyler
+- **Domain Intelligence** — Passive recon: subdomains, SSL, WHOIS, DNS ([#136](https://github.com/NousResearch/hermes-agent/pull/136)) — @FurkanL0
+- **Superpowers** — Software development skills ([#137](https://github.com/NousResearch/hermes-agent/pull/137)) — @kaos35
+- **Hermes-Atropos** — RL environment development skill ([#815](https://github.com/NousResearch/hermes-agent/pull/815))
+- Plus: arXiv search, OCR/documents, Excalidraw diagrams, YouTube transcripts, GIF search, Pokémon player, Minecraft modpack server, OpenHue (Philips Hue), Google Workspace, Notion, PowerPoint, Obsidian, find-nearby, and 40+ MLOps skills
+
+---
+
+## 🔒 Security & Reliability
+
+### Security Hardening
+- Path traversal fix in skill_view — prevented reading arbitrary files ([#220](https://github.com/NousResearch/hermes-agent/issues/220)) — @Farukest
+- Shell injection prevention in sudo password piping ([#65](https://github.com/NousResearch/hermes-agent/pull/65)) — @leonsgithub
+- Dangerous command detection: multiline bypass fix ([#233](https://github.com/NousResearch/hermes-agent/pull/233)) — @Farukest; tee/process substitution patterns ([#280](https://github.com/NousResearch/hermes-agent/pull/280)) — @dogiladeveloper
+- Symlink boundary check fix in skills_guard ([#386](https://github.com/NousResearch/hermes-agent/pull/386)) — @Farukest
+- Symlink bypass fix in write deny list on macOS ([#61](https://github.com/NousResearch/hermes-agent/pull/61)) — @0xbyt4
+- Multi-word prompt injection bypass prevention ([#192](https://github.com/NousResearch/hermes-agent/pull/192)) — @0xbyt4
+- Cron prompt injection scanner bypass fix ([#63](https://github.com/NousResearch/hermes-agent/pull/63)) — @0xbyt4
+- Enforce 0600/0700 file permissions on sensitive files ([#757](https://github.com/NousResearch/hermes-agent/pull/757))
+- .env file permissions restricted to owner-only ([#529](https://github.com/NousResearch/hermes-agent/pull/529)) — @Himess
+- `--force` flag properly blocked from overriding dangerous verdicts ([#388](https://github.com/NousResearch/hermes-agent/pull/388)) — @Farukest
+- FTS5 query sanitization + DB connection leak fix ([#565](https://github.com/NousResearch/hermes-agent/pull/565)) — @0xbyt4
+- Expand secret redaction patterns + config toggle to disable
+- In-memory permanent allowlist to prevent data leak ([#600](https://github.com/NousResearch/hermes-agent/pull/600)) — @alireza78a
+
+### Atomic Writes (data loss prevention)
+- sessions.json ([#611](https://github.com/NousResearch/hermes-agent/pull/611)) — @alireza78a
+- Cron jobs ([#146](https://github.com/NousResearch/hermes-agent/pull/146)) — @alireza78a
+- .env config ([#954](https://github.com/NousResearch/hermes-agent/pull/954))
+- Process checkpoints ([#298](https://github.com/NousResearch/hermes-agent/pull/298)) — @aydnOktay
+- Batch runner ([#297](https://github.com/NousResearch/hermes-agent/pull/297)) — @aydnOktay
+- Skill files ([#551](https://github.com/NousResearch/hermes-agent/pull/551)) — @aydnOktay
+
+### Reliability
+- Guard all print() against OSError for systemd/headless environments ([#963](https://github.com/NousResearch/hermes-agent/pull/963))
+- Reset all retry counters at start of run_conversation ([#607](https://github.com/NousResearch/hermes-agent/pull/607)) — @0xbyt4
+- Return deny on approval callback timeout instead of None ([#603](https://github.com/NousResearch/hermes-agent/pull/603)) — @0xbyt4
+- Fix None message content crashes across codebase ([#277](https://github.com/NousResearch/hermes-agent/pull/277))
+- Fix context overrun crash with local LLM backends ([#403](https://github.com/NousResearch/hermes-agent/pull/403)) — @ch3ronsa
+- Prevent `_flush_sentinel` from leaking to external APIs ([#227](https://github.com/NousResearch/hermes-agent/pull/227)) — @Farukest
+- Prevent conversation_history mutation in callers ([#229](https://github.com/NousResearch/hermes-agent/pull/229)) — @Farukest
+- Fix systemd restart loop ([#614](https://github.com/NousResearch/hermes-agent/pull/614)) — @voidborne-d
+- Close file handles and sockets to prevent fd leaks ([#568](https://github.com/NousResearch/hermes-agent/pull/568) — @alireza78a, [#296](https://github.com/NousResearch/hermes-agent/pull/296) — @alireza78a, [#709](https://github.com/NousResearch/hermes-agent/pull/709) — @memosr)
+- Prevent data loss in clipboard PNG conversion ([#602](https://github.com/NousResearch/hermes-agent/pull/602)) — @0xbyt4
+- Eliminate shell noise from terminal output ([#293](https://github.com/NousResearch/hermes-agent/pull/293)) — @0xbyt4
+- Timezone-aware now() for prompt, cron, and execute_code ([#309](https://github.com/NousResearch/hermes-agent/pull/309)) — @areu01or00
+
+### Windows Compatibility
+- Guard POSIX-only process functions ([#219](https://github.com/NousResearch/hermes-agent/pull/219)) — @Farukest
+- Windows native support via Git Bash + ZIP-based update fallback
+- pywinpty for PTY support ([#457](https://github.com/NousResearch/hermes-agent/pull/457)) — @shitcoinsherpa
+- Explicit UTF-8 encoding on all config/data file I/O ([#458](https://github.com/NousResearch/hermes-agent/pull/458)) — @shitcoinsherpa
+- Windows-compatible path handling ([#354](https://github.com/NousResearch/hermes-agent/pull/354), [#390](https://github.com/NousResearch/hermes-agent/pull/390)) — @Farukest
+- Regex-based search output parsing for drive-letter paths ([#533](https://github.com/NousResearch/hermes-agent/pull/533)) — @Himess
+- Auth store file lock for Windows ([#455](https://github.com/NousResearch/hermes-agent/pull/455)) — @shitcoinsherpa
+
+---
+
+## 🐛 Notable Bug Fixes
+
+- Fix DeepSeek V3 tool call parser silently dropping multi-line JSON arguments ([#444](https://github.com/NousResearch/hermes-agent/pull/444)) — @PercyDikec
+- Fix gateway transcript losing 1 message per turn due to offset mismatch ([#395](https://github.com/NousResearch/hermes-agent/pull/395)) — @PercyDikec
+- Fix /retry command silently discarding the agent's final response ([#441](https://github.com/NousResearch/hermes-agent/pull/441)) — @PercyDikec
+- Fix max-iterations retry returning empty string after think-block stripping ([#438](https://github.com/NousResearch/hermes-agent/pull/438)) — @PercyDikec
+- Fix max-iterations retry using hardcoded max_tokens ([#436](https://github.com/NousResearch/hermes-agent/pull/436)) — @Farukest
+- Fix Codex status dict key mismatch ([#448](https://github.com/NousResearch/hermes-agent/pull/448)) and visibility filter ([#446](https://github.com/NousResearch/hermes-agent/pull/446)) — @PercyDikec
+- Strip \<think\> blocks from final user-facing responses ([#174](https://github.com/NousResearch/hermes-agent/pull/174)) — @Bartok9
+- Fix \<think\> block regex stripping visible content when model discusses tags literally ([#786](https://github.com/NousResearch/hermes-agent/issues/786))
+- Fix Mistral 422 errors from leftover finish_reason in assistant messages ([#253](https://github.com/NousResearch/hermes-agent/pull/253)) — @Sertug17
+- Fix OPENROUTER_API_KEY resolution order across all code paths ([#295](https://github.com/NousResearch/hermes-agent/pull/295)) — @0xbyt4
+- Fix OPENAI_BASE_URL API key priority ([#420](https://github.com/NousResearch/hermes-agent/pull/420)) — @manuelschipper
+- Fix Anthropic "prompt is too long" 400 error not detected as context length error ([#813](https://github.com/NousResearch/hermes-agent/issues/813))
+- Fix SQLite session transcript accumulating duplicate messages — 3-4x token inflation ([#860](https://github.com/NousResearch/hermes-agent/issues/860))
+- Fix setup wizard skipping API key prompts on first install ([#748](https://github.com/NousResearch/hermes-agent/pull/748))
+- Fix setup wizard showing OpenRouter model list for Nous Portal ([#575](https://github.com/NousResearch/hermes-agent/pull/575)) — @PercyDikec
+- Fix provider selection not persisting when switching via hermes model ([#881](https://github.com/NousResearch/hermes-agent/pull/881))
+- Fix Docker backend failing when docker not in PATH on macOS ([#889](https://github.com/NousResearch/hermes-agent/pull/889))
+- Fix ClawHub Skills Hub adapter for API endpoint changes ([#286](https://github.com/NousResearch/hermes-agent/pull/286)) — @BP602
+- Fix Honcho auto-enable when API key is present ([#243](https://github.com/NousResearch/hermes-agent/pull/243)) — @Bartok9
+- Fix duplicate 'skills' subparser crash on Python 3.11+ ([#898](https://github.com/NousResearch/hermes-agent/issues/898))
+- Fix memory tool entry parsing when content contains section sign ([#162](https://github.com/NousResearch/hermes-agent/pull/162)) — @aydnOktay
+- Fix piped install silently aborting when interactive prompts fail ([#72](https://github.com/NousResearch/hermes-agent/pull/72)) — @cutepawss
+- Fix false positives in recursive delete detection ([#68](https://github.com/NousResearch/hermes-agent/pull/68)) — @cutepawss
+- Fix Ruff lint warnings across codebase ([#608](https://github.com/NousResearch/hermes-agent/pull/608)) — @JackTheGit
+- Fix Anthropic native base URL fail-fast ([#173](https://github.com/NousResearch/hermes-agent/pull/173)) — @adavyas
+- Fix install.sh creating ~/.hermes before moving Node.js directory ([#53](https://github.com/NousResearch/hermes-agent/pull/53)) — @JoshuaMart
+- Fix SystemExit traceback during atexit cleanup on Ctrl+C ([#55](https://github.com/NousResearch/hermes-agent/pull/55)) — @bierlingm
+- Restore missing MIT license file ([#620](https://github.com/NousResearch/hermes-agent/pull/620)) — @stablegenius49
+
+---
+
+## 🧪 Testing
+
+- **3,289 tests** across agent, gateway, tools, cron, and CLI
+- Parallelized test suite with pytest-xdist ([#802](https://github.com/NousResearch/hermes-agent/pull/802)) — @OutThisLife
+- Unit tests batch 1: 8 core modules ([#60](https://github.com/NousResearch/hermes-agent/pull/60)) — @0xbyt4
+- Unit tests batch 2: 8 more modules ([#62](https://github.com/NousResearch/hermes-agent/pull/62)) — @0xbyt4
+- Unit tests batch 3: 8 untested modules ([#191](https://github.com/NousResearch/hermes-agent/pull/191)) — @0xbyt4
+- Unit tests batch 4: 5 security/logic-critical modules ([#193](https://github.com/NousResearch/hermes-agent/pull/193)) — @0xbyt4
+- AIAgent (run_agent.py) unit tests ([#67](https://github.com/NousResearch/hermes-agent/pull/67)) — @0xbyt4
+- Trajectory compressor tests ([#203](https://github.com/NousResearch/hermes-agent/pull/203)) — @0xbyt4
+- Clarify tool tests ([#121](https://github.com/NousResearch/hermes-agent/pull/121)) — @Bartok9
+- Telegram format tests — 43 tests for italic/bold/code rendering ([#204](https://github.com/NousResearch/hermes-agent/pull/204)) — @0xbyt4
+- Vision tools type hints + 42 tests ([#792](https://github.com/NousResearch/hermes-agent/pull/792))
+- Compressor tool-call boundary regression tests ([#648](https://github.com/NousResearch/hermes-agent/pull/648)) — @intertwine
+- Test structure reorganization ([#34](https://github.com/NousResearch/hermes-agent/pull/34)) — @0xbyt4
+- Shell noise elimination + fix 36 test failures ([#293](https://github.com/NousResearch/hermes-agent/pull/293)) — @0xbyt4
+
+---
+
+## 🔬 RL & Evaluation Environments
+
+- WebResearchEnv — Multi-step web research RL environment ([#434](https://github.com/NousResearch/hermes-agent/pull/434)) — @jackx707
+- Modal sandbox concurrency limits to avoid deadlocks ([#621](https://github.com/NousResearch/hermes-agent/pull/621)) — @voteblake
+- Hermes-atropos-environments bundled skill ([#815](https://github.com/NousResearch/hermes-agent/pull/815))
+- Local vLLM instance support for evaluation — @dmahan93
+- YC-Bench long-horizon agent benchmark environment
+- OpenThoughts-TBLite evaluation environment and scripts
+
+---
+
+## 📚 Documentation
+
+- Full documentation website (Docusaurus) with 37+ pages
+- Comprehensive platform setup guides for Telegram, Discord, Slack, WhatsApp, Signal, Email
+- AGENTS.md — development guide for AI coding assistants
+- CONTRIBUTING.md ([#117](https://github.com/NousResearch/hermes-agent/pull/117)) — @Bartok9
+- Slash commands reference ([#142](https://github.com/NousResearch/hermes-agent/pull/142)) — @Bartok9
+- Comprehensive AGENTS.md accuracy audit ([#732](https://github.com/NousResearch/hermes-agent/pull/732))
+- Skin/theme system documentation
+- MCP documentation and examples
+- Docs accuracy audit — 35+ corrections
+- Documentation typo fixes ([#825](https://github.com/NousResearch/hermes-agent/pull/825), [#439](https://github.com/NousResearch/hermes-agent/pull/439)) — @JackTheGit
+- CLI config precedence and terminology standardization ([#166](https://github.com/NousResearch/hermes-agent/pull/166), [#167](https://github.com/NousResearch/hermes-agent/pull/167), [#168](https://github.com/NousResearch/hermes-agent/pull/168)) — @Jr-kenny
+- Telegram token regex documentation ([#713](https://github.com/NousResearch/hermes-agent/pull/713)) — @VolodymyrBg
+
+---
+
+## 👥 Contributors
+
+Thank you to the 63 contributors who made this release possible! In just over two weeks, the Hermes Agent community came together to ship an extraordinary amount of work.
+
+### Core
+- **@teknium1** — 43 PRs: Project lead, core architecture, provider router, sessions, skills, CLI, documentation
+
+### Top Community Contributors
+- **@0xbyt4** — 40 PRs: MCP client, Home Assistant, security fixes (symlink, prompt injection, cron), extensive test coverage (6 batches), ascii-art skill, shell noise elimination, skills sync, Telegram formatting, and dozens more
+- **@Farukest** — 16 PRs: Security hardening (path traversal, dangerous command detection, symlink boundary), Windows compatibility (POSIX guards, path handling), WhatsApp fixes, max-iterations retry, gateway fixes
+- **@aydnOktay** — 11 PRs: Atomic writes (process checkpoints, batch runner, skill files), error handling improvements across Telegram, Discord, code execution, transcription, TTS, and skills
+- **@Bartok9** — 9 PRs: CONTRIBUTING.md, slash commands reference, Discord channel topics, think-block stripping, TTS fix, Honcho fix, session count fix, clarify tests
+- **@PercyDikec** — 7 PRs: DeepSeek V3 parser fix, /retry response discard, gateway transcript offset, Codex status/visibility, max-iterations retry, setup wizard fix
+- **@teyrebaz33** — 5 PRs: Skills enable/disable system, quick commands, personality customization, conditional skill activation
+- **@alireza78a** — 5 PRs: Atomic writes (cron, sessions), fd leak prevention, security allowlist, code execution socket cleanup
+- **@shitcoinsherpa** — 3 PRs: Windows support (pywinpty, UTF-8 encoding, auth store lock)
+- **@Himess** — 3 PRs: Cron/HomeAssistant/Daytona fix, Windows drive-letter parsing, .env permissions
+- **@satelerd** — 2 PRs: WhatsApp native media, multi-user session isolation
+- **@rovle** — 1 PR: Daytona cloud sandbox backend (4 commits)
+- **@erosika** — 1 PR: Honcho AI-native memory integration
+- **@dmahan93** — 1 PR: --fuck-it-ship-it flag + RL environment work
+- **@SHL0MS** — 1 PR: ASCII video skill
+
+### All Contributors
+@0xbyt4, @BP602, @Bartok9, @Farukest, @FurkanL0, @Himess, @Indelwin, @JackTheGit, @JoshuaMart, @Jr-kenny, @OutThisLife, @PercyDikec, @SHL0MS, @Sertug17, @VencentSoliman, @VolodymyrBg, @adavyas, @alireza78a, @areu01or00, @aydnOktay, @batuhankocyigit, @bierlingm, @caentzminger, @cesareth, @ch3ronsa, @christomitov, @cutepawss, @deankerr, @dmahan93, @dogiladeveloper, @dragonkhoi, @erosika, @gamedevCloudy, @gizdusum, @grp06, @intertwine, @jackx707, @jdblackstar, @johnh4098, @kaos35, @kshitijk4poor, @leonsgithub, @luisv-1, @manuelschipper, @mehmetkr-31, @memosr, @PeterFile, @rewbs, @rovle, @rsavitt, @satelerd, @spanishflu-est1918, @stablegenius49, @tars90percent, @tekelala, @teknium1, @teyrebaz33, @tripledoublev, @unmodeled-tyler, @voidborne-d, @voteblake, @ygd58
+
+---
+
+**Full Changelog**: [v0.1.0...v2026.3.12](https://github.com/NousResearch/hermes-agent/compare/v0.1.0...v2026.3.12)

RELEASE_v0.3.0.md

@@ -0,0 +1,377 @@
+# Hermes Agent v0.3.0 (v2026.3.17)
+
+**Release Date:** March 17, 2026
+
+> The streaming, plugins, and provider release — unified real-time token delivery, first-class plugin architecture, rebuilt provider system with Vercel AI Gateway, native Anthropic provider, smart approvals, live Chrome CDP browser connect, ACP IDE integration, Honcho memory, voice mode, persistent shell, and 50+ bug fixes across every platform.
+
+---
+
+## ✨ Highlights
+
+- **Unified Streaming Infrastructure** — Real-time token-by-token delivery in CLI and all gateway platforms. Responses stream as they're generated instead of arriving as a block. ([#1538](https://github.com/NousResearch/hermes-agent/pull/1538))
+
+- **First-Class Plugin Architecture** — Drop Python files into `~/.hermes/plugins/` to extend Hermes with custom tools, commands, and hooks. No forking required. ([#1544](https://github.com/NousResearch/hermes-agent/pull/1544), [#1555](https://github.com/NousResearch/hermes-agent/pull/1555))
+
+- **Native Anthropic Provider** — Direct Anthropic API calls with Claude Code credential auto-discovery, OAuth PKCE flows, and native prompt caching. No OpenRouter middleman needed. ([#1097](https://github.com/NousResearch/hermes-agent/pull/1097))
+
+- **Smart Approvals + /stop Command** — Codex-inspired approval system that learns which commands are safe and remembers your preferences. `/stop` kills the current agent run immediately. ([#1543](https://github.com/NousResearch/hermes-agent/pull/1543))
+
+- **Honcho Memory Integration** — Async memory writes, configurable recall modes, session title integration, and multi-user isolation in gateway mode. By @erosika. ([#736](https://github.com/NousResearch/hermes-agent/pull/736))
+
+- **Voice Mode** — Push-to-talk in CLI, voice notes in Telegram/Discord, Discord voice channel support, and local Whisper transcription via faster-whisper. ([#1299](https://github.com/NousResearch/hermes-agent/pull/1299), [#1185](https://github.com/NousResearch/hermes-agent/pull/1185), [#1429](https://github.com/NousResearch/hermes-agent/pull/1429))
+
+- **Concurrent Tool Execution** — Multiple independent tool calls now run in parallel via ThreadPoolExecutor, significantly reducing latency for multi-tool turns. ([#1152](https://github.com/NousResearch/hermes-agent/pull/1152))
+
+- **PII Redaction** — When `privacy.redact_pii` is enabled, personally identifiable information is automatically scrubbed before sending context to LLM providers. ([#1542](https://github.com/NousResearch/hermes-agent/pull/1542))
+
+- **`/browser connect` via CDP** — Attach browser tools to a live Chrome instance through Chrome DevTools Protocol. Debug, inspect, and interact with pages you already have open. ([#1549](https://github.com/NousResearch/hermes-agent/pull/1549))
+
+- **Vercel AI Gateway Provider** — Route Hermes through Vercel's AI Gateway for access to their model catalog and infrastructure. ([#1628](https://github.com/NousResearch/hermes-agent/pull/1628))
+
+- **Centralized Provider Router** — Rebuilt provider system with `call_llm` API, unified `/model` command, auto-detect provider on model switch, and direct endpoint overrides for auxiliary/delegation clients. ([#1003](https://github.com/NousResearch/hermes-agent/pull/1003), [#1506](https://github.com/NousResearch/hermes-agent/pull/1506), [#1375](https://github.com/NousResearch/hermes-agent/pull/1375))
+
+- **ACP Server (IDE Integration)** — VS Code, Zed, and JetBrains can now connect to Hermes as an agent backend, with full slash command support. ([#1254](https://github.com/NousResearch/hermes-agent/pull/1254), [#1532](https://github.com/NousResearch/hermes-agent/pull/1532))
+
+- **Persistent Shell Mode** — Local and SSH terminal backends can maintain shell state across tool calls — cd, env vars, and aliases persist. By @alt-glitch. ([#1067](https://github.com/NousResearch/hermes-agent/pull/1067), [#1483](https://github.com/NousResearch/hermes-agent/pull/1483))
+
+- **Agentic On-Policy Distillation (OPD)** — New RL training environment for distilling agent policies, expanding the Atropos training ecosystem. ([#1149](https://github.com/NousResearch/hermes-agent/pull/1149))
+
+---
+
+## 🏗️ Core Agent & Architecture
+
+### Provider & Model Support
+- **Centralized provider router** with `call_llm` API and unified `/model` command — switch models and providers seamlessly ([#1003](https://github.com/NousResearch/hermes-agent/pull/1003))
+- **Vercel AI Gateway** provider support ([#1628](https://github.com/NousResearch/hermes-agent/pull/1628))
+- **Auto-detect provider** when switching models via `/model` ([#1506](https://github.com/NousResearch/hermes-agent/pull/1506))
+- **Direct endpoint overrides** for auxiliary and delegation clients — point vision/subagent calls at specific endpoints ([#1375](https://github.com/NousResearch/hermes-agent/pull/1375))
+- **Native Anthropic auxiliary vision** — use Claude's native vision API instead of routing through OpenAI-compatible endpoints ([#1377](https://github.com/NousResearch/hermes-agent/pull/1377))
+- Anthropic OAuth flow improvements — auto-run `claude setup-token`, reauthentication, PKCE state persistence, identity fingerprinting ([#1132](https://github.com/NousResearch/hermes-agent/pull/1132), [#1360](https://github.com/NousResearch/hermes-agent/pull/1360), [#1396](https://github.com/NousResearch/hermes-agent/pull/1396), [#1597](https://github.com/NousResearch/hermes-agent/pull/1597))
+- Fix adaptive thinking without `budget_tokens` for Claude 4.6 models — by @ASRagab ([#1128](https://github.com/NousResearch/hermes-agent/pull/1128))
+- Fix Anthropic cache markers through adapter — by @brandtcormorant ([#1216](https://github.com/NousResearch/hermes-agent/pull/1216))
+- Retry Anthropic 429/529 errors and surface details to users — by @0xbyt4 ([#1585](https://github.com/NousResearch/hermes-agent/pull/1585))
+- Fix Anthropic adapter max_tokens, fallback crash, proxy base_url — by @0xbyt4 ([#1121](https://github.com/NousResearch/hermes-agent/pull/1121))
+- Fix DeepSeek V3 parser dropping multiple parallel tool calls — by @mr-emmett-one ([#1365](https://github.com/NousResearch/hermes-agent/pull/1365), [#1300](https://github.com/NousResearch/hermes-agent/pull/1300))
+- Accept unlisted models with warning instead of rejecting ([#1047](https://github.com/NousResearch/hermes-agent/pull/1047), [#1102](https://github.com/NousResearch/hermes-agent/pull/1102))
+- Skip reasoning params for unsupported OpenRouter models ([#1485](https://github.com/NousResearch/hermes-agent/pull/1485))
+- MiniMax Anthropic API compatibility fix ([#1623](https://github.com/NousResearch/hermes-agent/pull/1623))
+- Custom endpoint `/models` verification and `/v1` base URL suggestion ([#1480](https://github.com/NousResearch/hermes-agent/pull/1480))
+- Resolve delegation providers from `custom_providers` config ([#1328](https://github.com/NousResearch/hermes-agent/pull/1328))
+- Kimi model additions and User-Agent fix ([#1039](https://github.com/NousResearch/hermes-agent/pull/1039))
+- Strip `call_id`/`response_item_id` for Mistral compatibility ([#1058](https://github.com/NousResearch/hermes-agent/pull/1058))
+
+### Agent Loop & Conversation
+- **Anthropic Context Editing API** support ([#1147](https://github.com/NousResearch/hermes-agent/pull/1147))
+- Improved context compaction handoff summaries — compressor now preserves more actionable state ([#1273](https://github.com/NousResearch/hermes-agent/pull/1273))
+- Sync session_id after mid-run context compression ([#1160](https://github.com/NousResearch/hermes-agent/pull/1160))
+- Session hygiene threshold tuned to 50% for more proactive compression ([#1096](https://github.com/NousResearch/hermes-agent/pull/1096), [#1161](https://github.com/NousResearch/hermes-agent/pull/1161))
+- Include session ID in system prompt via `--pass-session-id` flag ([#1040](https://github.com/NousResearch/hermes-agent/pull/1040))
+- Prevent closed OpenAI client reuse across retries ([#1391](https://github.com/NousResearch/hermes-agent/pull/1391))
+- Sanitize chat payloads and provider precedence ([#1253](https://github.com/NousResearch/hermes-agent/pull/1253))
+- Handle dict tool call arguments from Codex and local backends ([#1393](https://github.com/NousResearch/hermes-agent/pull/1393), [#1440](https://github.com/NousResearch/hermes-agent/pull/1440))
+
+### Memory & Sessions
+- **Improve memory prioritization** — user preferences and corrections weighted above procedural knowledge ([#1548](https://github.com/NousResearch/hermes-agent/pull/1548))
+- Tighter memory and session recall guidance in system prompts ([#1329](https://github.com/NousResearch/hermes-agent/pull/1329))
+- Persist CLI token counts to session DB for `/insights` ([#1498](https://github.com/NousResearch/hermes-agent/pull/1498))
+- Keep Honcho recall out of the cached system prefix ([#1201](https://github.com/NousResearch/hermes-agent/pull/1201))
+- Correct `seed_ai_identity` to use `session.add_messages()` ([#1475](https://github.com/NousResearch/hermes-agent/pull/1475))
+- Isolate Honcho session routing for multi-user gateway ([#1500](https://github.com/NousResearch/hermes-agent/pull/1500))
+
+---
+
+## 📱 Messaging Platforms (Gateway)
+
+### Gateway Core
+- **System gateway service mode** — run as a system-level systemd service, not just user-level ([#1371](https://github.com/NousResearch/hermes-agent/pull/1371))
+- **Gateway install scope prompts** — choose user vs system scope during setup ([#1374](https://github.com/NousResearch/hermes-agent/pull/1374))
+- **Reasoning hot reload** — change reasoning settings without restarting the gateway ([#1275](https://github.com/NousResearch/hermes-agent/pull/1275))
+- Default group sessions to per-user isolation — no more shared state across users in group chats ([#1495](https://github.com/NousResearch/hermes-agent/pull/1495), [#1417](https://github.com/NousResearch/hermes-agent/pull/1417))
+- Harden gateway restart recovery ([#1310](https://github.com/NousResearch/hermes-agent/pull/1310))
+- Cancel active runs during shutdown ([#1427](https://github.com/NousResearch/hermes-agent/pull/1427))
+- SSL certificate auto-detection for NixOS and non-standard systems ([#1494](https://github.com/NousResearch/hermes-agent/pull/1494))
+- Auto-detect D-Bus session bus for `systemctl --user` on headless servers ([#1601](https://github.com/NousResearch/hermes-agent/pull/1601))
+- Auto-enable systemd linger during gateway install on headless servers ([#1334](https://github.com/NousResearch/hermes-agent/pull/1334))
+- Fall back to module entrypoint when `hermes` is not on PATH ([#1355](https://github.com/NousResearch/hermes-agent/pull/1355))
+- Fix dual gateways on macOS launchd after `hermes update` ([#1567](https://github.com/NousResearch/hermes-agent/pull/1567))
+- Remove recursive ExecStop from systemd units ([#1530](https://github.com/NousResearch/hermes-agent/pull/1530))
+- Prevent logging handler accumulation in gateway mode ([#1251](https://github.com/NousResearch/hermes-agent/pull/1251))
+- Restart on retryable startup failures — by @jplew ([#1517](https://github.com/NousResearch/hermes-agent/pull/1517))
+- Backfill model on gateway sessions after agent runs ([#1306](https://github.com/NousResearch/hermes-agent/pull/1306))
+- PID-based gateway kill and deferred config write ([#1499](https://github.com/NousResearch/hermes-agent/pull/1499))
+
+### Telegram
+- Buffer media groups to prevent self-interruption from photo bursts ([#1341](https://github.com/NousResearch/hermes-agent/pull/1341), [#1422](https://github.com/NousResearch/hermes-agent/pull/1422))
+- Retry on transient TLS failures during connect and send ([#1535](https://github.com/NousResearch/hermes-agent/pull/1535))
+- Harden polling conflict handling ([#1339](https://github.com/NousResearch/hermes-agent/pull/1339))
+- Escape chunk indicators and inline code in MarkdownV2 ([#1478](https://github.com/NousResearch/hermes-agent/pull/1478), [#1626](https://github.com/NousResearch/hermes-agent/pull/1626))
+- Check updater/app state before disconnect ([#1389](https://github.com/NousResearch/hermes-agent/pull/1389))
+
+### Discord
+- `/thread` command with `auto_thread` config and media metadata fixes ([#1178](https://github.com/NousResearch/hermes-agent/pull/1178))
+- Auto-thread on @mention, skip mention text in bot threads ([#1438](https://github.com/NousResearch/hermes-agent/pull/1438))
+- Retry without reply reference for system messages ([#1385](https://github.com/NousResearch/hermes-agent/pull/1385))
+- Preserve native document and video attachment support ([#1392](https://github.com/NousResearch/hermes-agent/pull/1392))
+- Defer discord adapter annotations to avoid optional import crashes ([#1314](https://github.com/NousResearch/hermes-agent/pull/1314))
+
+### Slack
+- Thread handling overhaul — progress messages, responses, and session isolation all respect threads ([#1103](https://github.com/NousResearch/hermes-agent/pull/1103))
+- Formatting, reactions, user resolution, and command improvements ([#1106](https://github.com/NousResearch/hermes-agent/pull/1106))
+- Fix MAX_MESSAGE_LENGTH 3900 → 39000 ([#1117](https://github.com/NousResearch/hermes-agent/pull/1117))
+- File upload fallback preserves thread context — by @0xbyt4 ([#1122](https://github.com/NousResearch/hermes-agent/pull/1122))
+- Improve setup guidance ([#1387](https://github.com/NousResearch/hermes-agent/pull/1387))
+
+### Email
+- Fix IMAP UID tracking and SMTP TLS verification ([#1305](https://github.com/NousResearch/hermes-agent/pull/1305))
+- Add `skip_attachments` option via config.yaml ([#1536](https://github.com/NousResearch/hermes-agent/pull/1536))
+
+### Home Assistant
+- Event filtering closed by default ([#1169](https://github.com/NousResearch/hermes-agent/pull/1169))
+
+---
+
+## 🖥️ CLI & User Experience
+
+### Interactive CLI
+- **Persistent CLI status bar** — always-visible model, provider, and token counts ([#1522](https://github.com/NousResearch/hermes-agent/pull/1522))
+- **File path autocomplete** in the input prompt ([#1545](https://github.com/NousResearch/hermes-agent/pull/1545))
+- **`/plan` command** — generate implementation plans from specs ([#1372](https://github.com/NousResearch/hermes-agent/pull/1372), [#1381](https://github.com/NousResearch/hermes-agent/pull/1381))
+- **Major `/rollback` improvements** — richer checkpoint history, clearer UX ([#1505](https://github.com/NousResearch/hermes-agent/pull/1505))
+- **Preload CLI skills on launch** — skills are ready before the first prompt ([#1359](https://github.com/NousResearch/hermes-agent/pull/1359))
+- **Centralized slash command registry** — all commands defined once, consumed everywhere ([#1603](https://github.com/NousResearch/hermes-agent/pull/1603))
+- `/bg` alias for `/background` ([#1590](https://github.com/NousResearch/hermes-agent/pull/1590))
+- Prefix matching for slash commands — `/mod` resolves to `/model` ([#1320](https://github.com/NousResearch/hermes-agent/pull/1320))
+- `/new`, `/reset`, `/clear` now start genuinely fresh sessions ([#1237](https://github.com/NousResearch/hermes-agent/pull/1237))
+- Accept session ID prefixes for session actions ([#1425](https://github.com/NousResearch/hermes-agent/pull/1425))
+- TUI prompt and accent output now respect active skin ([#1282](https://github.com/NousResearch/hermes-agent/pull/1282))
+- Centralize tool emoji metadata in registry + skin integration ([#1484](https://github.com/NousResearch/hermes-agent/pull/1484))
+- "View full command" option added to dangerous command approval — by @teknium1 based on design by community ([#887](https://github.com/NousResearch/hermes-agent/pull/887))
+- Non-blocking startup update check and banner deduplication ([#1386](https://github.com/NousResearch/hermes-agent/pull/1386))
+- `/reasoning` command output ordering and inline think extraction fixes ([#1031](https://github.com/NousResearch/hermes-agent/pull/1031))
+- Verbose mode shows full untruncated output ([#1472](https://github.com/NousResearch/hermes-agent/pull/1472))
+- Fix `/status` to report live state and tokens ([#1476](https://github.com/NousResearch/hermes-agent/pull/1476))
+- Seed a default global SOUL.md ([#1311](https://github.com/NousResearch/hermes-agent/pull/1311))
+
+### Setup & Configuration
+- **OpenClaw migration** during first-time setup — by @kshitijk4poor ([#981](https://github.com/NousResearch/hermes-agent/pull/981))
+- `hermes claw migrate` command + migration docs ([#1059](https://github.com/NousResearch/hermes-agent/pull/1059))
+- Smart vision setup that respects the user's chosen provider ([#1323](https://github.com/NousResearch/hermes-agent/pull/1323))
+- Handle headless setup flows end-to-end ([#1274](https://github.com/NousResearch/hermes-agent/pull/1274))
+- Prefer curses over `simple_term_menu` in setup.py ([#1487](https://github.com/NousResearch/hermes-agent/pull/1487))
+- Show effective model and provider in `/status` ([#1284](https://github.com/NousResearch/hermes-agent/pull/1284))
+- Config set examples use placeholder syntax ([#1322](https://github.com/NousResearch/hermes-agent/pull/1322))
+- Reload .env over stale shell overrides ([#1434](https://github.com/NousResearch/hermes-agent/pull/1434))
+- Fix is_coding_plan NameError crash — by @0xbyt4 ([#1123](https://github.com/NousResearch/hermes-agent/pull/1123))
+- Add missing packages to setuptools config — by @alt-glitch ([#912](https://github.com/NousResearch/hermes-agent/pull/912))
+- Installer: clarify why sudo is needed at every prompt ([#1602](https://github.com/NousResearch/hermes-agent/pull/1602))
+
+---
+
+## 🔧 Tool System
+
+### Terminal & Execution
+- **Persistent shell mode** for local and SSH backends — maintain shell state across tool calls — by @alt-glitch ([#1067](https://github.com/NousResearch/hermes-agent/pull/1067), [#1483](https://github.com/NousResearch/hermes-agent/pull/1483))
+- **Tirith pre-exec command scanning** — security layer that analyzes commands before execution ([#1256](https://github.com/NousResearch/hermes-agent/pull/1256))
+- Strip Hermes provider env vars from all subprocess environments ([#1157](https://github.com/NousResearch/hermes-agent/pull/1157), [#1172](https://github.com/NousResearch/hermes-agent/pull/1172), [#1399](https://github.com/NousResearch/hermes-agent/pull/1399), [#1419](https://github.com/NousResearch/hermes-agent/pull/1419)) — initial fix by @eren-karakus0
+- SSH preflight check ([#1486](https://github.com/NousResearch/hermes-agent/pull/1486))
+- Docker backend: make cwd workspace mount explicit opt-in ([#1534](https://github.com/NousResearch/hermes-agent/pull/1534))
+- Add project root to PYTHONPATH in execute_code sandbox ([#1383](https://github.com/NousResearch/hermes-agent/pull/1383))
+- Eliminate execute_code progress spam on gateway platforms ([#1098](https://github.com/NousResearch/hermes-agent/pull/1098))
+- Clearer docker backend preflight errors ([#1276](https://github.com/NousResearch/hermes-agent/pull/1276))
+
+### Browser
+- **`/browser connect`** — attach browser tools to a live Chrome instance via CDP ([#1549](https://github.com/NousResearch/hermes-agent/pull/1549))
+- Improve browser cleanup, local browser PATH setup, and screenshot recovery ([#1333](https://github.com/NousResearch/hermes-agent/pull/1333))
+
+### MCP
+- **Selective tool loading** with utility policies — filter which MCP tools are available ([#1302](https://github.com/NousResearch/hermes-agent/pull/1302))
+- Auto-reload MCP tools when `mcp_servers` config changes without restart ([#1474](https://github.com/NousResearch/hermes-agent/pull/1474))
+- Resolve npx stdio connection failures ([#1291](https://github.com/NousResearch/hermes-agent/pull/1291))
+- Preserve MCP toolsets when saving platform tool config ([#1421](https://github.com/NousResearch/hermes-agent/pull/1421))
+
+### Vision
+- Unify vision backend gating ([#1367](https://github.com/NousResearch/hermes-agent/pull/1367))
+- Surface actual error reason instead of generic message ([#1338](https://github.com/NousResearch/hermes-agent/pull/1338))
+- Make Claude image handling work end-to-end ([#1408](https://github.com/NousResearch/hermes-agent/pull/1408))
+
+### Cron
+- **Compress cron management into one tool** — single `cronjob` tool replaces multiple commands ([#1343](https://github.com/NousResearch/hermes-agent/pull/1343))
+- Suppress duplicate cron sends to auto-delivery targets ([#1357](https://github.com/NousResearch/hermes-agent/pull/1357))
+- Persist cron sessions to SQLite ([#1255](https://github.com/NousResearch/hermes-agent/pull/1255))
+- Per-job runtime overrides (provider, model, base_url) ([#1398](https://github.com/NousResearch/hermes-agent/pull/1398))
+- Atomic write in `save_job_output` to prevent data loss on crash ([#1173](https://github.com/NousResearch/hermes-agent/pull/1173))
+- Preserve thread context for `deliver=origin` ([#1437](https://github.com/NousResearch/hermes-agent/pull/1437))
+
+### Patch Tool
+- Avoid corrupting pipe chars in V4A patch apply ([#1286](https://github.com/NousResearch/hermes-agent/pull/1286))
+- Permissive `block_anchor` thresholds and unicode normalization ([#1539](https://github.com/NousResearch/hermes-agent/pull/1539))
+
+### Delegation
+- Add observability metadata to subagent results (model, tokens, duration, tool trace) ([#1175](https://github.com/NousResearch/hermes-agent/pull/1175))
+
+---
+
+## 🧩 Skills Ecosystem
+
+### Skills System
+- **Integrate skills.sh** as a hub source alongside ClawHub ([#1303](https://github.com/NousResearch/hermes-agent/pull/1303))
+- Secure skill env setup on load ([#1153](https://github.com/NousResearch/hermes-agent/pull/1153))
+- Honor policy table for dangerous verdicts ([#1330](https://github.com/NousResearch/hermes-agent/pull/1330))
+- Harden ClawHub skill search exact matches ([#1400](https://github.com/NousResearch/hermes-agent/pull/1400))
+- Fix ClawHub skill install — use `/download` ZIP endpoint ([#1060](https://github.com/NousResearch/hermes-agent/pull/1060))
+- Avoid mislabeling local skills as builtin — by @arceus77-7 ([#862](https://github.com/NousResearch/hermes-agent/pull/862))
+
+### New Skills
+- **Linear** project management ([#1230](https://github.com/NousResearch/hermes-agent/pull/1230))
+- **X/Twitter** via x-cli ([#1285](https://github.com/NousResearch/hermes-agent/pull/1285))
+- **Telephony** — Twilio, SMS, and AI calls ([#1289](https://github.com/NousResearch/hermes-agent/pull/1289))
+- **1Password** — by @arceus77-7 ([#883](https://github.com/NousResearch/hermes-agent/pull/883), [#1179](https://github.com/NousResearch/hermes-agent/pull/1179))
+- **NeuroSkill BCI** integration ([#1135](https://github.com/NousResearch/hermes-agent/pull/1135))
+- **Blender MCP** for 3D modeling ([#1531](https://github.com/NousResearch/hermes-agent/pull/1531))
+- **OSS Security Forensics** ([#1482](https://github.com/NousResearch/hermes-agent/pull/1482))
+- **Parallel CLI** research skill ([#1301](https://github.com/NousResearch/hermes-agent/pull/1301))
+- **OpenCode** CLI skill ([#1174](https://github.com/NousResearch/hermes-agent/pull/1174))
+- **ASCII Video** skill refactored — by @SHL0MS ([#1213](https://github.com/NousResearch/hermes-agent/pull/1213), [#1598](https://github.com/NousResearch/hermes-agent/pull/1598))
+
+---
+
+## 🎙️ Voice Mode
+
+- Voice mode foundation — push-to-talk CLI, Telegram/Discord voice notes ([#1299](https://github.com/NousResearch/hermes-agent/pull/1299))
+- Free local Whisper transcription via faster-whisper ([#1185](https://github.com/NousResearch/hermes-agent/pull/1185))
+- Discord voice channel reliability fixes ([#1429](https://github.com/NousResearch/hermes-agent/pull/1429))
+- Restore local STT fallback for gateway voice notes ([#1490](https://github.com/NousResearch/hermes-agent/pull/1490))
+- Honor `stt.enabled: false` across gateway transcription ([#1394](https://github.com/NousResearch/hermes-agent/pull/1394))
+- Fix bogus incapability message on Telegram voice notes (Issue [#1033](https://github.com/NousResearch/hermes-agent/issues/1033))
+
+---
+
+## 🔌 ACP (IDE Integration)
+
+- Restore ACP server implementation ([#1254](https://github.com/NousResearch/hermes-agent/pull/1254))
+- Support slash commands in ACP adapter ([#1532](https://github.com/NousResearch/hermes-agent/pull/1532))
+
+---
+
+## 🧪 RL Training
+
+- **Agentic On-Policy Distillation (OPD)** environment — new RL training environment for agent policy distillation ([#1149](https://github.com/NousResearch/hermes-agent/pull/1149))
+- Make tinker-atropos RL training fully optional ([#1062](https://github.com/NousResearch/hermes-agent/pull/1062))
+
+---
+
+## 🔒 Security & Reliability
+
+### Security Hardening
+- **Tirith pre-exec command scanning** — static analysis of terminal commands before execution ([#1256](https://github.com/NousResearch/hermes-agent/pull/1256))
+- **PII redaction** when `privacy.redact_pii` is enabled ([#1542](https://github.com/NousResearch/hermes-agent/pull/1542))
+- Strip Hermes provider/gateway/tool env vars from all subprocess environments ([#1157](https://github.com/NousResearch/hermes-agent/pull/1157), [#1172](https://github.com/NousResearch/hermes-agent/pull/1172), [#1399](https://github.com/NousResearch/hermes-agent/pull/1399), [#1419](https://github.com/NousResearch/hermes-agent/pull/1419))
+- Docker cwd workspace mount now explicit opt-in — never auto-mount host directories ([#1534](https://github.com/NousResearch/hermes-agent/pull/1534))
+- Escape parens and braces in fork bomb regex pattern ([#1397](https://github.com/NousResearch/hermes-agent/pull/1397))
+- Harden `.worktreeinclude` path containment ([#1388](https://github.com/NousResearch/hermes-agent/pull/1388))
+- Use description as `pattern_key` to prevent approval collisions ([#1395](https://github.com/NousResearch/hermes-agent/pull/1395))
+
+### Reliability
+- Guard init-time stdio writes ([#1271](https://github.com/NousResearch/hermes-agent/pull/1271))
+- Session log writes reuse shared atomic JSON helper ([#1280](https://github.com/NousResearch/hermes-agent/pull/1280))
+- Atomic temp cleanup protected on interrupts ([#1401](https://github.com/NousResearch/hermes-agent/pull/1401))
+
+---
+
+## 🐛 Notable Bug Fixes
+
+- **`/status` always showing 0 tokens** — now reports live state (Issue [#1465](https://github.com/NousResearch/hermes-agent/issues/1465), [#1476](https://github.com/NousResearch/hermes-agent/pull/1476))
+- **Custom model endpoints not working** — restored config-saved endpoint resolution (Issue [#1460](https://github.com/NousResearch/hermes-agent/issues/1460), [#1373](https://github.com/NousResearch/hermes-agent/pull/1373))
+- **MCP tools not visible until restart** — auto-reload on config change (Issue [#1036](https://github.com/NousResearch/hermes-agent/issues/1036), [#1474](https://github.com/NousResearch/hermes-agent/pull/1474))
+- **`hermes tools` removing MCP tools** — preserve MCP toolsets when saving (Issue [#1247](https://github.com/NousResearch/hermes-agent/issues/1247), [#1421](https://github.com/NousResearch/hermes-agent/pull/1421))
+- **Terminal subprocesses inheriting `OPENAI_BASE_URL`** breaking external tools (Issue [#1002](https://github.com/NousResearch/hermes-agent/issues/1002), [#1399](https://github.com/NousResearch/hermes-agent/pull/1399))
+- **Background process lost on gateway restart** — improved recovery (Issue [#1144](https://github.com/NousResearch/hermes-agent/issues/1144))
+- **Cron jobs not persisting state** — now stored in SQLite (Issue [#1416](https://github.com/NousResearch/hermes-agent/issues/1416), [#1255](https://github.com/NousResearch/hermes-agent/pull/1255))
+- **Cronjob `deliver: origin` not preserving thread context** (Issue [#1219](https://github.com/NousResearch/hermes-agent/issues/1219), [#1437](https://github.com/NousResearch/hermes-agent/pull/1437))
+- **Gateway systemd service failing to auto-restart** when browser processes orphaned (Issue [#1617](https://github.com/NousResearch/hermes-agent/issues/1617))
+- **`/background` completion report cut off in Telegram** (Issue [#1443](https://github.com/NousResearch/hermes-agent/issues/1443))
+- **Model switching not taking effect** (Issue [#1244](https://github.com/NousResearch/hermes-agent/issues/1244), [#1183](https://github.com/NousResearch/hermes-agent/pull/1183))
+- **`hermes doctor` reporting cronjob as unavailable** (Issue [#878](https://github.com/NousResearch/hermes-agent/issues/878), [#1180](https://github.com/NousResearch/hermes-agent/pull/1180))
+- **WhatsApp bridge messages not received** from mobile (Issue [#1142](https://github.com/NousResearch/hermes-agent/issues/1142))
+- **Setup wizard hanging on headless SSH** (Issue [#905](https://github.com/NousResearch/hermes-agent/issues/905), [#1274](https://github.com/NousResearch/hermes-agent/pull/1274))
+- **Log handler accumulation** degrading gateway performance (Issue [#990](https://github.com/NousResearch/hermes-agent/issues/990), [#1251](https://github.com/NousResearch/hermes-agent/pull/1251))
+- **Gateway NULL model in DB** (Issue [#987](https://github.com/NousResearch/hermes-agent/issues/987), [#1306](https://github.com/NousResearch/hermes-agent/pull/1306))
+- **Strict endpoints rejecting replayed tool_calls** (Issue [#893](https://github.com/NousResearch/hermes-agent/issues/893))
+- **Remaining hardcoded `~/.hermes` paths** — all now respect `HERMES_HOME` (Issue [#892](https://github.com/NousResearch/hermes-agent/issues/892), [#1233](https://github.com/NousResearch/hermes-agent/pull/1233))
+- **Delegate tool not working with custom inference providers** (Issue [#1011](https://github.com/NousResearch/hermes-agent/issues/1011), [#1328](https://github.com/NousResearch/hermes-agent/pull/1328))
+- **Skills Guard blocking official skills** (Issue [#1006](https://github.com/NousResearch/hermes-agent/issues/1006), [#1330](https://github.com/NousResearch/hermes-agent/pull/1330))
+- **Setup writing provider before model selection** (Issue [#1182](https://github.com/NousResearch/hermes-agent/issues/1182))
+- **`GatewayConfig.get()` AttributeError** crashing all message handling (Issue [#1158](https://github.com/NousResearch/hermes-agent/issues/1158), [#1287](https://github.com/NousResearch/hermes-agent/pull/1287))
+- **`/update` hard-failing with "command not found"** (Issue [#1049](https://github.com/NousResearch/hermes-agent/issues/1049))
+- **Image analysis failing silently** (Issue [#1034](https://github.com/NousResearch/hermes-agent/issues/1034), [#1338](https://github.com/NousResearch/hermes-agent/pull/1338))
+- **API `BadRequestError` from `'dict'` object has no attribute `'strip'`** (Issue [#1071](https://github.com/NousResearch/hermes-agent/issues/1071))
+- **Slash commands requiring exact full name** — now uses prefix matching (Issue [#928](https://github.com/NousResearch/hermes-agent/issues/928), [#1320](https://github.com/NousResearch/hermes-agent/pull/1320))
+- **Gateway stops responding when terminal is closed on headless** (Issue [#1005](https://github.com/NousResearch/hermes-agent/issues/1005))
+
+---
+
+## 🧪 Testing
+
+- Cover empty cached Anthropic tool-call turns ([#1222](https://github.com/NousResearch/hermes-agent/pull/1222))
+- Fix stale CI assumptions in parser and quick-command coverage ([#1236](https://github.com/NousResearch/hermes-agent/pull/1236))
+- Fix gateway async tests without implicit event loop ([#1278](https://github.com/NousResearch/hermes-agent/pull/1278))
+- Make gateway async tests xdist-safe ([#1281](https://github.com/NousResearch/hermes-agent/pull/1281))
+- Cross-timezone naive timestamp regression for cron ([#1319](https://github.com/NousResearch/hermes-agent/pull/1319))
+- Isolate codex provider tests from local env ([#1335](https://github.com/NousResearch/hermes-agent/pull/1335))
+- Lock retry replacement semantics ([#1379](https://github.com/NousResearch/hermes-agent/pull/1379))
+- Improve error logging in session search tool — by @aydnOktay ([#1533](https://github.com/NousResearch/hermes-agent/pull/1533))
+
+---
+
+## 📚 Documentation
+
+- Comprehensive SOUL.md guide ([#1315](https://github.com/NousResearch/hermes-agent/pull/1315))
+- Voice mode documentation ([#1316](https://github.com/NousResearch/hermes-agent/pull/1316), [#1362](https://github.com/NousResearch/hermes-agent/pull/1362))
+- Provider contribution guide ([#1361](https://github.com/NousResearch/hermes-agent/pull/1361))
+- ACP and internal systems implementation guides ([#1259](https://github.com/NousResearch/hermes-agent/pull/1259))
+- Expand Docusaurus coverage across CLI, tools, skills, and skins ([#1232](https://github.com/NousResearch/hermes-agent/pull/1232))
+- Terminal backend and Windows troubleshooting ([#1297](https://github.com/NousResearch/hermes-agent/pull/1297))
+- Skills hub reference section ([#1317](https://github.com/NousResearch/hermes-agent/pull/1317))
+- Checkpoint, /rollback, and git worktrees guide ([#1493](https://github.com/NousResearch/hermes-agent/pull/1493), [#1524](https://github.com/NousResearch/hermes-agent/pull/1524))
+- CLI status bar and /usage reference ([#1523](https://github.com/NousResearch/hermes-agent/pull/1523))
+- Fallback providers + /background command docs ([#1430](https://github.com/NousResearch/hermes-agent/pull/1430))
+- Gateway service scopes docs ([#1378](https://github.com/NousResearch/hermes-agent/pull/1378))
+- Slack thread reply behavior docs ([#1407](https://github.com/NousResearch/hermes-agent/pull/1407))
+- Redesigned landing page with Nous blue palette — by @austinpickett ([#974](https://github.com/NousResearch/hermes-agent/pull/974))
+- Fix several documentation typos — by @JackTheGit ([#953](https://github.com/NousResearch/hermes-agent/pull/953))
+- Stabilize website diagrams ([#1405](https://github.com/NousResearch/hermes-agent/pull/1405))
+- CLI vs messaging quick reference in README ([#1491](https://github.com/NousResearch/hermes-agent/pull/1491))
+- Add search to Docusaurus ([#1053](https://github.com/NousResearch/hermes-agent/pull/1053))
+- Home Assistant integration docs ([#1170](https://github.com/NousResearch/hermes-agent/pull/1170))
+
+---
+
+## 👥 Contributors
+
+### Core
+- **@teknium1** — 220+ PRs spanning every area of the codebase
+
+### Top Community Contributors
+
+- **@0xbyt4** (4 PRs) — Anthropic adapter fixes (max_tokens, fallback crash, 429/529 retry), Slack file upload thread context, setup NameError fix
+- **@erosika** (1 PR) — Honcho memory integration: async writes, memory modes, session title integration
+- **@SHL0MS** (2 PRs) — ASCII video skill design patterns and refactoring
+- **@alt-glitch** (2 PRs) — Persistent shell mode for local/SSH backends, setuptools packaging fix
+- **@arceus77-7** (2 PRs) — 1Password skill, fix skills list mislabeling
+- **@kshitijk4poor** (1 PR) — OpenClaw migration during setup wizard
+- **@ASRagab** (1 PR) — Fix adaptive thinking for Claude 4.6 models
+- **@eren-karakus0** (1 PR) — Strip Hermes provider env vars from subprocess environment
+- **@mr-emmett-one** (1 PR) — Fix DeepSeek V3 parser multi-tool call support
+- **@jplew** (1 PR) — Gateway restart on retryable startup failures
+- **@brandtcormorant** (1 PR) — Fix Anthropic cache control for empty text blocks
+- **@aydnOktay** (1 PR) — Improve error logging in session search tool
+- **@austinpickett** (1 PR) — Landing page redesign with Nous blue palette
+- **@JackTheGit** (1 PR) — Documentation typo fixes
+
+### All Contributors
+
+@0xbyt4, @alt-glitch, @arceus77-7, @ASRagab, @austinpickett, @aydnOktay, @brandtcormorant, @eren-karakus0, @erosika, @JackTheGit, @jplew, @kshitijk4poor, @mr-emmett-one, @SHL0MS, @teknium1
+
+---
+
+**Full Changelog**: [v2026.3.12...v2026.3.17](https://github.com/NousResearch/hermes-agent/compare/v2026.3.12...v2026.3.17)

RELEASE_v0.4.0.md

@@ -0,0 +1,400 @@
+# Hermes Agent v0.4.0 (v2026.3.23)
+
+**Release Date:** March 23, 2026
+
+> The platform expansion release — OpenAI-compatible API server, 6 new messaging adapters, 4 new inference providers, MCP server management with OAuth 2.1, @ context references, gateway prompt caching, streaming enabled by default, and a sweeping reliability pass with 200+ bug fixes.
+
+---
+
+## ✨ Highlights
+
+- **OpenAI-compatible API server** — Expose Hermes as an `/v1/chat/completions` endpoint with a new `/api/jobs` REST API for cron job management, hardened with input limits, field whitelists, SQLite-backed response persistence, and CORS origin protection ([#1756](https://github.com/NousResearch/hermes-agent/pull/1756), [#2450](https://github.com/NousResearch/hermes-agent/pull/2450), [#2456](https://github.com/NousResearch/hermes-agent/pull/2456), [#2451](https://github.com/NousResearch/hermes-agent/pull/2451), [#2472](https://github.com/NousResearch/hermes-agent/pull/2472))
+
+- **6 new messaging platform adapters** — Signal, DingTalk, SMS (Twilio), Mattermost, Matrix, and Webhook adapters join Telegram, Discord, and WhatsApp. Gateway auto-reconnects failed platforms with exponential backoff ([#2206](https://github.com/NousResearch/hermes-agent/pull/2206), [#1685](https://github.com/NousResearch/hermes-agent/pull/1685), [#1688](https://github.com/NousResearch/hermes-agent/pull/1688), [#1683](https://github.com/NousResearch/hermes-agent/pull/1683), [#2166](https://github.com/NousResearch/hermes-agent/pull/2166), [#2584](https://github.com/NousResearch/hermes-agent/pull/2584))
+
+- **@ context references** — Claude Code-style `@file` and `@url` context injection with tab completions in the CLI ([#2343](https://github.com/NousResearch/hermes-agent/pull/2343), [#2482](https://github.com/NousResearch/hermes-agent/pull/2482))
+
+- **4 new inference providers** — GitHub Copilot (OAuth + token validation), Alibaba Cloud / DashScope, Kilo Code, and OpenCode Zen/Go ([#1924](https://github.com/NousResearch/hermes-agent/pull/1924), [#1879](https://github.com/NousResearch/hermes-agent/pull/1879) by @mchzimm, [#1673](https://github.com/NousResearch/hermes-agent/pull/1673), [#1666](https://github.com/NousResearch/hermes-agent/pull/1666), [#1650](https://github.com/NousResearch/hermes-agent/pull/1650))
+
+- **MCP server management CLI** — `hermes mcp` commands for installing, configuring, and authenticating MCP servers with full OAuth 2.1 PKCE flow ([#2465](https://github.com/NousResearch/hermes-agent/pull/2465))
+
+- **Gateway prompt caching** — Cache AIAgent instances per session, preserving Anthropic prompt cache across turns for dramatic cost reduction on long conversations ([#2282](https://github.com/NousResearch/hermes-agent/pull/2282), [#2284](https://github.com/NousResearch/hermes-agent/pull/2284), [#2361](https://github.com/NousResearch/hermes-agent/pull/2361))
+
+- **Context compression overhaul** — Structured summaries with iterative updates, token-budget tail protection, configurable summary endpoint, and fallback model support ([#2323](https://github.com/NousResearch/hermes-agent/pull/2323), [#1727](https://github.com/NousResearch/hermes-agent/pull/1727), [#2224](https://github.com/NousResearch/hermes-agent/pull/2224))
+
+- **Streaming enabled by default** — CLI streaming on by default with proper spinner/tool progress display during streaming mode, plus extensive linebreak and concatenation fixes ([#2340](https://github.com/NousResearch/hermes-agent/pull/2340), [#2161](https://github.com/NousResearch/hermes-agent/pull/2161), [#2258](https://github.com/NousResearch/hermes-agent/pull/2258))
+
+---
+
+## 🖥️ CLI & User Experience
+
+### New Commands & Interactions
+- **@ context completions** — Tab-completable `@file`/`@url` references that inject file content or web pages into the conversation ([#2482](https://github.com/NousResearch/hermes-agent/pull/2482), [#2343](https://github.com/NousResearch/hermes-agent/pull/2343))
+- **`/statusbar`** — Toggle a persistent config bar showing model + provider info in the prompt ([#2240](https://github.com/NousResearch/hermes-agent/pull/2240), [#1917](https://github.com/NousResearch/hermes-agent/pull/1917))
+- **`/queue`** — Queue prompts for the agent without interrupting the current run ([#2191](https://github.com/NousResearch/hermes-agent/pull/2191), [#2469](https://github.com/NousResearch/hermes-agent/pull/2469))
+- **`/permission`** — Switch approval mode dynamically during a session ([#2207](https://github.com/NousResearch/hermes-agent/pull/2207))
+- **`/browser`** — Interactive browser sessions from the CLI ([#2273](https://github.com/NousResearch/hermes-agent/pull/2273), [#1814](https://github.com/NousResearch/hermes-agent/pull/1814))
+- **`/cost`** — Live pricing and usage tracking in gateway mode ([#2180](https://github.com/NousResearch/hermes-agent/pull/2180))
+- **`/approve` and `/deny`** — Replaced bare text approval in gateway with explicit commands ([#2002](https://github.com/NousResearch/hermes-agent/pull/2002))
+
+### Streaming & Display
+- Streaming enabled by default in CLI ([#2340](https://github.com/NousResearch/hermes-agent/pull/2340))
+- Show spinners and tool progress during streaming mode ([#2161](https://github.com/NousResearch/hermes-agent/pull/2161))
+- Show reasoning/thinking blocks when `show_reasoning` enabled ([#2118](https://github.com/NousResearch/hermes-agent/pull/2118))
+- Context pressure warnings for CLI and gateway ([#2159](https://github.com/NousResearch/hermes-agent/pull/2159))
+- Fix: streaming chunks concatenated without whitespace ([#2258](https://github.com/NousResearch/hermes-agent/pull/2258))
+- Fix: iteration boundary linebreak prevents stream concatenation ([#2413](https://github.com/NousResearch/hermes-agent/pull/2413))
+- Fix: defer streaming linebreak to prevent blank line stacking ([#2473](https://github.com/NousResearch/hermes-agent/pull/2473))
+- Fix: suppress spinner animation in non-TTY environments ([#2216](https://github.com/NousResearch/hermes-agent/pull/2216))
+- Fix: display provider and endpoint in API error messages ([#2266](https://github.com/NousResearch/hermes-agent/pull/2266))
+- Fix: resolve garbled ANSI escape codes in status printouts ([#2448](https://github.com/NousResearch/hermes-agent/pull/2448))
+- Fix: update gold ANSI color to true-color format ([#2246](https://github.com/NousResearch/hermes-agent/pull/2246))
+- Fix: normalize toolset labels and use skin colors in banner ([#1912](https://github.com/NousResearch/hermes-agent/pull/1912))
+
+### CLI Polish
+- Fix: prevent 'Press ENTER to continue...' on exit ([#2555](https://github.com/NousResearch/hermes-agent/pull/2555))
+- Fix: flush stdout during agent loop to prevent macOS display freeze ([#1654](https://github.com/NousResearch/hermes-agent/pull/1654))
+- Fix: show human-readable error when `hermes setup` hits permissions error ([#2196](https://github.com/NousResearch/hermes-agent/pull/2196))
+- Fix: `/stop` command crash + UnboundLocalError in streaming media delivery ([#2463](https://github.com/NousResearch/hermes-agent/pull/2463))
+- Fix: allow custom/local endpoints without API key ([#2556](https://github.com/NousResearch/hermes-agent/pull/2556))
+- Fix: Kitty keyboard protocol Shift+Enter for Ghostty/WezTerm (attempted + reverted due to prompt_toolkit crash) ([#2345](https://github.com/NousResearch/hermes-agent/pull/2345), [#2349](https://github.com/NousResearch/hermes-agent/pull/2349))
+
+### Configuration
+- **`${ENV_VAR}` substitution** in config.yaml ([#2684](https://github.com/NousResearch/hermes-agent/pull/2684))
+- **Real-time config reload** — config.yaml changes apply without restart ([#2210](https://github.com/NousResearch/hermes-agent/pull/2210))
+- **`custom_models.yaml`** for user-managed model additions ([#2214](https://github.com/NousResearch/hermes-agent/pull/2214))
+- **Priority-based context file selection** + CLAUDE.md support ([#2301](https://github.com/NousResearch/hermes-agent/pull/2301))
+- **Merge nested YAML sections** instead of replacing on config update ([#2213](https://github.com/NousResearch/hermes-agent/pull/2213))
+- Fix: config.yaml provider key overrides env var silently ([#2272](https://github.com/NousResearch/hermes-agent/pull/2272))
+- Fix: log warning instead of silently swallowing config.yaml errors ([#2683](https://github.com/NousResearch/hermes-agent/pull/2683))
+- Fix: disabled toolsets re-enable themselves after `hermes tools` ([#2268](https://github.com/NousResearch/hermes-agent/pull/2268))
+- Fix: platform default toolsets silently override tool deselection ([#2624](https://github.com/NousResearch/hermes-agent/pull/2624))
+- Fix: honor bare YAML `approvals.mode: off` ([#2620](https://github.com/NousResearch/hermes-agent/pull/2620))
+- Fix: `hermes update` use `.[all]` extras with fallback ([#1728](https://github.com/NousResearch/hermes-agent/pull/1728))
+- Fix: `hermes update` prompt before resetting working tree on stash conflicts ([#2390](https://github.com/NousResearch/hermes-agent/pull/2390))
+- Fix: use git pull --rebase in update/install to avoid divergent branch error ([#2274](https://github.com/NousResearch/hermes-agent/pull/2274))
+- Fix: add zprofile fallback and create zshrc on fresh macOS installs ([#2320](https://github.com/NousResearch/hermes-agent/pull/2320))
+- Fix: remove `ANTHROPIC_BASE_URL` env var to avoid collisions ([#1675](https://github.com/NousResearch/hermes-agent/pull/1675))
+- Fix: don't ask IMAP password if already in keyring or env ([#2212](https://github.com/NousResearch/hermes-agent/pull/2212))
+- Fix: OpenCode Zen/Go show OpenRouter models instead of their own ([#2277](https://github.com/NousResearch/hermes-agent/pull/2277))
+
+---
+
+## 🏗️ Core Agent & Architecture
+
+### New Providers
+- **GitHub Copilot** — Full OAuth auth, API routing, token validation, and 400k context. ([#1924](https://github.com/NousResearch/hermes-agent/pull/1924), [#1896](https://github.com/NousResearch/hermes-agent/pull/1896), [#1879](https://github.com/NousResearch/hermes-agent/pull/1879) by @mchzimm, [#2507](https://github.com/NousResearch/hermes-agent/pull/2507))
+- **Alibaba Cloud / DashScope** — Full integration with DashScope v1 runtime, model dot preservation, and 401 auth fixes ([#1673](https://github.com/NousResearch/hermes-agent/pull/1673), [#2332](https://github.com/NousResearch/hermes-agent/pull/2332), [#2459](https://github.com/NousResearch/hermes-agent/pull/2459))
+- **Kilo Code** — First-class inference provider ([#1666](https://github.com/NousResearch/hermes-agent/pull/1666))
+- **OpenCode Zen and OpenCode Go** — New provider backends ([#1650](https://github.com/NousResearch/hermes-agent/pull/1650), [#2393](https://github.com/NousResearch/hermes-agent/pull/2393) by @0xbyt4)
+- **NeuTTS** — Local TTS provider backend with built-in setup flow, replacing the old optional skill ([#1657](https://github.com/NousResearch/hermes-agent/pull/1657), [#1664](https://github.com/NousResearch/hermes-agent/pull/1664))
+
+### Provider Improvements
+- **Eager fallback** to backup model on rate-limit errors ([#1730](https://github.com/NousResearch/hermes-agent/pull/1730))
+- **Endpoint metadata** for custom model context and pricing; query local servers for actual context window size ([#1906](https://github.com/NousResearch/hermes-agent/pull/1906), [#2091](https://github.com/NousResearch/hermes-agent/pull/2091) by @dusterbloom)
+- **Context length detection overhaul** — models.dev integration, provider-aware resolution, fuzzy matching for custom endpoints, `/v1/props` for llama.cpp ([#2158](https://github.com/NousResearch/hermes-agent/pull/2158), [#2051](https://github.com/NousResearch/hermes-agent/pull/2051), [#2403](https://github.com/NousResearch/hermes-agent/pull/2403))
+- **Model catalog updates** — gpt-5.4-mini, gpt-5.4-nano, healer-alpha, haiku-4.5, minimax-m2.7, claude 4.6 at 1M context ([#1913](https://github.com/NousResearch/hermes-agent/pull/1913), [#1915](https://github.com/NousResearch/hermes-agent/pull/1915), [#1900](https://github.com/NousResearch/hermes-agent/pull/1900), [#2155](https://github.com/NousResearch/hermes-agent/pull/2155), [#2474](https://github.com/NousResearch/hermes-agent/pull/2474))
+- **Custom endpoint improvements** — `model.base_url` in config.yaml, `api_mode` override for responses API, allow endpoints without API key, fail fast on missing keys ([#2330](https://github.com/NousResearch/hermes-agent/pull/2330), [#1651](https://github.com/NousResearch/hermes-agent/pull/1651), [#2556](https://github.com/NousResearch/hermes-agent/pull/2556), [#2445](https://github.com/NousResearch/hermes-agent/pull/2445), [#1994](https://github.com/NousResearch/hermes-agent/pull/1994), [#1998](https://github.com/NousResearch/hermes-agent/pull/1998))
+- Inject model and provider into system prompt ([#1929](https://github.com/NousResearch/hermes-agent/pull/1929))
+- Tie `api_mode` to provider config instead of env var ([#1656](https://github.com/NousResearch/hermes-agent/pull/1656))
+- Fix: prevent Anthropic token leaking to third-party `anthropic_messages` providers ([#2389](https://github.com/NousResearch/hermes-agent/pull/2389))
+- Fix: prevent Anthropic fallback from inheriting non-Anthropic `base_url` ([#2388](https://github.com/NousResearch/hermes-agent/pull/2388))
+- Fix: `auxiliary_is_nous` flag never resets — leaked Nous tags to other providers ([#1713](https://github.com/NousResearch/hermes-agent/pull/1713))
+- Fix: Anthropic `tool_choice 'none'` still allowed tool calls ([#1714](https://github.com/NousResearch/hermes-agent/pull/1714))
+- Fix: Mistral parser nested JSON fallback extraction ([#2335](https://github.com/NousResearch/hermes-agent/pull/2335))
+- Fix: MiniMax 401 auth resolved by defaulting to `anthropic_messages` ([#2103](https://github.com/NousResearch/hermes-agent/pull/2103))
+- Fix: case-insensitive model family matching ([#2350](https://github.com/NousResearch/hermes-agent/pull/2350))
+- Fix: ignore placeholder provider keys in activation checks ([#2358](https://github.com/NousResearch/hermes-agent/pull/2358))
+- Fix: Preserve Ollama model:tag colons in context length detection ([#2149](https://github.com/NousResearch/hermes-agent/pull/2149))
+- Fix: recognize Claude Code OAuth credentials in startup gate ([#1663](https://github.com/NousResearch/hermes-agent/pull/1663))
+- Fix: detect Claude Code version dynamically for OAuth user-agent ([#1670](https://github.com/NousResearch/hermes-agent/pull/1670))
+- Fix: OAuth flag stale after refresh/fallback ([#1890](https://github.com/NousResearch/hermes-agent/pull/1890))
+- Fix: auxiliary client skips expired Codex JWT ([#2397](https://github.com/NousResearch/hermes-agent/pull/2397))
+
+### Agent Loop
+- **Gateway prompt caching** — Cache AIAgent per session, keep assistant turns, fix session restore ([#2282](https://github.com/NousResearch/hermes-agent/pull/2282), [#2284](https://github.com/NousResearch/hermes-agent/pull/2284), [#2361](https://github.com/NousResearch/hermes-agent/pull/2361))
+- **Context compression overhaul** — Structured summaries, iterative updates, token-budget tail protection, configurable `summary_base_url` ([#2323](https://github.com/NousResearch/hermes-agent/pull/2323), [#1727](https://github.com/NousResearch/hermes-agent/pull/1727), [#2224](https://github.com/NousResearch/hermes-agent/pull/2224))
+- **Pre-call sanitization and post-call tool guardrails** ([#1732](https://github.com/NousResearch/hermes-agent/pull/1732))
+- **Auto-recover** from provider-rejected `tool_choice` by retrying without ([#2174](https://github.com/NousResearch/hermes-agent/pull/2174))
+- **Background memory/skill review** replaces inline nudges ([#2235](https://github.com/NousResearch/hermes-agent/pull/2235))
+- **SOUL.md as primary agent identity** instead of hardcoded default ([#1922](https://github.com/NousResearch/hermes-agent/pull/1922))
+- Fix: prevent silent tool result loss during context compression ([#1993](https://github.com/NousResearch/hermes-agent/pull/1993))
+- Fix: handle empty/null function arguments in tool call recovery ([#2163](https://github.com/NousResearch/hermes-agent/pull/2163))
+- Fix: handle API refusal responses gracefully instead of crashing ([#2156](https://github.com/NousResearch/hermes-agent/pull/2156))
+- Fix: prevent stuck agent loop on malformed tool calls ([#2114](https://github.com/NousResearch/hermes-agent/pull/2114))
+- Fix: return JSON parse error to model instead of dispatching with empty args ([#2342](https://github.com/NousResearch/hermes-agent/pull/2342))
+- Fix: consecutive assistant message merge drops content on mixed types ([#1703](https://github.com/NousResearch/hermes-agent/pull/1703))
+- Fix: message role alternation violations in JSON recovery and error handler ([#1722](https://github.com/NousResearch/hermes-agent/pull/1722))
+- Fix: `compression_attempts` resets each iteration — allowed unlimited compressions ([#1723](https://github.com/NousResearch/hermes-agent/pull/1723))
+- Fix: `length_continue_retries` never resets — later truncations got fewer retries ([#1717](https://github.com/NousResearch/hermes-agent/pull/1717))
+- Fix: compressor summary role violated consecutive-role constraint ([#1720](https://github.com/NousResearch/hermes-agent/pull/1720), [#1743](https://github.com/NousResearch/hermes-agent/pull/1743))
+- Fix: remove hardcoded `gemini-3-flash-preview` as default summary model ([#2464](https://github.com/NousResearch/hermes-agent/pull/2464))
+- Fix: correctly handle empty tool results ([#2201](https://github.com/NousResearch/hermes-agent/pull/2201))
+- Fix: crash on None entry in `tool_calls` list ([#2209](https://github.com/NousResearch/hermes-agent/pull/2209) by @0xbyt4, [#2316](https://github.com/NousResearch/hermes-agent/pull/2316))
+- Fix: per-thread persistent event loops in worker threads ([#2214](https://github.com/NousResearch/hermes-agent/pull/2214) by @jquesnelle)
+- Fix: prevent 'event loop already running' when async tools run in parallel ([#2207](https://github.com/NousResearch/hermes-agent/pull/2207))
+- Fix: strip ANSI at the source — clean terminal output before it reaches the model ([#2115](https://github.com/NousResearch/hermes-agent/pull/2115))
+- Fix: skip top-level `cache_control` on role:tool for OpenRouter ([#2391](https://github.com/NousResearch/hermes-agent/pull/2391))
+- Fix: delegate tool — save parent tool names before child construction mutates global ([#2083](https://github.com/NousResearch/hermes-agent/pull/2083) by @ygd58, [#1894](https://github.com/NousResearch/hermes-agent/pull/1894))
+- Fix: only strip last assistant message if empty string ([#2326](https://github.com/NousResearch/hermes-agent/pull/2326))
+
+### Session & Memory
+- **Session search** and management slash commands ([#2198](https://github.com/NousResearch/hermes-agent/pull/2198))
+- **Auto session titles** and `.hermes.md` project config ([#1712](https://github.com/NousResearch/hermes-agent/pull/1712))
+- Fix: concurrent memory writes silently drop entries — added file locking ([#1726](https://github.com/NousResearch/hermes-agent/pull/1726))
+- Fix: search all sources by default in `session_search` ([#1892](https://github.com/NousResearch/hermes-agent/pull/1892))
+- Fix: handle hyphenated FTS5 queries and preserve quoted literals ([#1776](https://github.com/NousResearch/hermes-agent/pull/1776))
+- Fix: skip corrupt lines in `load_transcript` instead of crashing ([#1744](https://github.com/NousResearch/hermes-agent/pull/1744))
+- Fix: normalize session keys to prevent case-sensitive duplicates ([#2157](https://github.com/NousResearch/hermes-agent/pull/2157))
+- Fix: prevent `session_search` crash when no sessions exist ([#2194](https://github.com/NousResearch/hermes-agent/pull/2194))
+- Fix: reset token counters on new session for accurate usage display ([#2101](https://github.com/NousResearch/hermes-agent/pull/2101) by @InB4DevOps)
+- Fix: prevent stale memory overwrites by flush agent ([#2687](https://github.com/NousResearch/hermes-agent/pull/2687))
+- Fix: remove synthetic error message injection, fix session resume after repeated failures ([#2303](https://github.com/NousResearch/hermes-agent/pull/2303))
+- Fix: quiet mode with `--resume` now passes conversation_history ([#2357](https://github.com/NousResearch/hermes-agent/pull/2357))
+- Fix: unify resume logic in batch mode ([#2331](https://github.com/NousResearch/hermes-agent/pull/2331))
+
+### Honcho Memory
+- Honcho config fixes and @ context reference integration ([#2343](https://github.com/NousResearch/hermes-agent/pull/2343))
+- Self-hosted / Docker configuration documentation ([#2475](https://github.com/NousResearch/hermes-agent/pull/2475))
+
+---
+
+## 📱 Messaging Platforms (Gateway)
+
+### New Platform Adapters
+- **Signal Messenger** — Full adapter with attachment handling, group message filtering, and Note to Self echo-back protection ([#2206](https://github.com/NousResearch/hermes-agent/pull/2206), [#2400](https://github.com/NousResearch/hermes-agent/pull/2400), [#2297](https://github.com/NousResearch/hermes-agent/pull/2297), [#2156](https://github.com/NousResearch/hermes-agent/pull/2156))
+- **DingTalk** — Adapter with gateway wiring and setup docs ([#1685](https://github.com/NousResearch/hermes-agent/pull/1685), [#1690](https://github.com/NousResearch/hermes-agent/pull/1690), [#1692](https://github.com/NousResearch/hermes-agent/pull/1692))
+- **SMS (Twilio)** ([#1688](https://github.com/NousResearch/hermes-agent/pull/1688))
+- **Mattermost** — With @-mention-only channel filter ([#1683](https://github.com/NousResearch/hermes-agent/pull/1683), [#2443](https://github.com/NousResearch/hermes-agent/pull/2443))
+- **Matrix** — With vision support and image caching ([#1683](https://github.com/NousResearch/hermes-agent/pull/1683), [#2520](https://github.com/NousResearch/hermes-agent/pull/2520))
+- **Webhook** — Platform adapter for external event triggers ([#2166](https://github.com/NousResearch/hermes-agent/pull/2166))
+- **OpenAI-compatible API server** — `/v1/chat/completions` endpoint with `/api/jobs` cron management ([#1756](https://github.com/NousResearch/hermes-agent/pull/1756), [#2450](https://github.com/NousResearch/hermes-agent/pull/2450), [#2456](https://github.com/NousResearch/hermes-agent/pull/2456))
+
+### Telegram Improvements
+- MarkdownV2 support — strikethrough, spoiler, blockquotes, escape parentheses/braces/backslashes/backticks ([#2199](https://github.com/NousResearch/hermes-agent/pull/2199), [#2200](https://github.com/NousResearch/hermes-agent/pull/2200) by @llbn, [#2386](https://github.com/NousResearch/hermes-agent/pull/2386))
+- Auto-detect HTML tags and use `parse_mode=HTML` ([#1709](https://github.com/NousResearch/hermes-agent/pull/1709))
+- Telegram group vision support + thread-based sessions ([#2153](https://github.com/NousResearch/hermes-agent/pull/2153))
+- Auto-reconnect polling after network interruption ([#2517](https://github.com/NousResearch/hermes-agent/pull/2517))
+- Aggregate split text messages before dispatching ([#1674](https://github.com/NousResearch/hermes-agent/pull/1674))
+- Fix: streaming config bridge, not-modified, flood control ([#1782](https://github.com/NousResearch/hermes-agent/pull/1782), [#1783](https://github.com/NousResearch/hermes-agent/pull/1783))
+- Fix: edited_message event crashes ([#2074](https://github.com/NousResearch/hermes-agent/pull/2074))
+- Fix: retry 409 polling conflicts before giving up ([#2312](https://github.com/NousResearch/hermes-agent/pull/2312))
+- Fix: topic delivery via `platform:chat_id:thread_id` format ([#2455](https://github.com/NousResearch/hermes-agent/pull/2455))
+
+### Discord Improvements
+- Document caching and text-file injection ([#2503](https://github.com/NousResearch/hermes-agent/pull/2503))
+- Persistent typing indicator for DMs ([#2468](https://github.com/NousResearch/hermes-agent/pull/2468))
+- Discord DM vision — inline images + attachment analysis ([#2186](https://github.com/NousResearch/hermes-agent/pull/2186))
+- Persist thread participation across gateway restarts ([#1661](https://github.com/NousResearch/hermes-agent/pull/1661))
+- Fix: gateway crash on non-ASCII guild names ([#2302](https://github.com/NousResearch/hermes-agent/pull/2302))
+- Fix: thread permission errors ([#2073](https://github.com/NousResearch/hermes-agent/pull/2073))
+- Fix: slash event routing in threads ([#2460](https://github.com/NousResearch/hermes-agent/pull/2460))
+- Fix: remove bugged followup messages + `/ask` command ([#1836](https://github.com/NousResearch/hermes-agent/pull/1836))
+- Fix: graceful WebSocket reconnection ([#2127](https://github.com/NousResearch/hermes-agent/pull/2127))
+- Fix: voice channel TTS when streaming enabled ([#2322](https://github.com/NousResearch/hermes-agent/pull/2322))
+
+### WhatsApp & Other Adapters
+- WhatsApp: outbound `send_message` routing ([#1769](https://github.com/NousResearch/hermes-agent/pull/1769) by @sai-samarth), LID format self-chat ([#1667](https://github.com/NousResearch/hermes-agent/pull/1667)), `reply_prefix` config fix ([#1923](https://github.com/NousResearch/hermes-agent/pull/1923)), restart on bridge child exit ([#2334](https://github.com/NousResearch/hermes-agent/pull/2334)), image/bridge improvements ([#2181](https://github.com/NousResearch/hermes-agent/pull/2181))
+- Matrix: correct `reply_to_message_id` parameter ([#1895](https://github.com/NousResearch/hermes-agent/pull/1895)), bare media types fix ([#1736](https://github.com/NousResearch/hermes-agent/pull/1736))
+- Mattermost: MIME types for media attachments ([#2329](https://github.com/NousResearch/hermes-agent/pull/2329))
+
+### Gateway Core
+- **Auto-reconnect** failed platforms with exponential backoff ([#2584](https://github.com/NousResearch/hermes-agent/pull/2584))
+- **Notify users when session auto-resets** ([#2519](https://github.com/NousResearch/hermes-agent/pull/2519))
+- **Reply-to message context** for out-of-session replies ([#1662](https://github.com/NousResearch/hermes-agent/pull/1662))
+- **Ignore unauthorized DMs** config option ([#1919](https://github.com/NousResearch/hermes-agent/pull/1919))
+- Fix: `/reset` in thread-mode resets global session instead of thread ([#2254](https://github.com/NousResearch/hermes-agent/pull/2254))
+- Fix: deliver MEDIA: files after streaming responses ([#2382](https://github.com/NousResearch/hermes-agent/pull/2382))
+- Fix: cap interrupt recursion depth to prevent resource exhaustion ([#1659](https://github.com/NousResearch/hermes-agent/pull/1659))
+- Fix: detect stopped processes and release stale locks on `--replace` ([#2406](https://github.com/NousResearch/hermes-agent/pull/2406), [#1908](https://github.com/NousResearch/hermes-agent/pull/1908))
+- Fix: PID-based wait with force-kill for gateway restart ([#1902](https://github.com/NousResearch/hermes-agent/pull/1902))
+- Fix: prevent `--replace` mode from killing the caller process ([#2185](https://github.com/NousResearch/hermes-agent/pull/2185))
+- Fix: `/model` shows active fallback model instead of config default ([#1660](https://github.com/NousResearch/hermes-agent/pull/1660))
+- Fix: `/title` command fails when session doesn't exist in SQLite yet ([#2379](https://github.com/NousResearch/hermes-agent/pull/2379) by @ten-jampa)
+- Fix: process `/queue`'d messages after agent completion ([#2469](https://github.com/NousResearch/hermes-agent/pull/2469))
+- Fix: strip orphaned `tool_results` + let `/reset` bypass running agent ([#2180](https://github.com/NousResearch/hermes-agent/pull/2180))
+- Fix: prevent agents from starting gateway outside systemd management ([#2617](https://github.com/NousResearch/hermes-agent/pull/2617))
+- Fix: prevent systemd restart storm on gateway connection failure ([#2327](https://github.com/NousResearch/hermes-agent/pull/2327))
+- Fix: include resolved node path in systemd unit ([#1767](https://github.com/NousResearch/hermes-agent/pull/1767) by @sai-samarth)
+- Fix: send error details to user in gateway outer exception handler ([#1966](https://github.com/NousResearch/hermes-agent/pull/1966))
+- Fix: improve error handling for 429 usage limits and 500 context overflow ([#1839](https://github.com/NousResearch/hermes-agent/pull/1839))
+- Fix: add all missing platform allowlist env vars to startup warning check ([#2628](https://github.com/NousResearch/hermes-agent/pull/2628))
+- Fix: media delivery fails for file paths containing spaces ([#2621](https://github.com/NousResearch/hermes-agent/pull/2621))
+- Fix: duplicate session-key collision in multi-platform gateway ([#2171](https://github.com/NousResearch/hermes-agent/pull/2171))
+- Fix: Matrix and Mattermost never report as connected ([#1711](https://github.com/NousResearch/hermes-agent/pull/1711))
+- Fix: PII redaction config never read — missing yaml import ([#1701](https://github.com/NousResearch/hermes-agent/pull/1701))
+- Fix: NameError on skill slash commands ([#1697](https://github.com/NousResearch/hermes-agent/pull/1697))
+- Fix: persist watcher metadata in checkpoint for crash recovery ([#1706](https://github.com/NousResearch/hermes-agent/pull/1706))
+- Fix: pass `message_thread_id` in send_image_file, send_document, send_video ([#2339](https://github.com/NousResearch/hermes-agent/pull/2339))
+- Fix: media-group aggregation on rapid successive photo messages ([#2160](https://github.com/NousResearch/hermes-agent/pull/2160))
+
+---
+
+## 🔧 Tool System
+
+### MCP Enhancements
+- **MCP server management CLI** + OAuth 2.1 PKCE auth ([#2465](https://github.com/NousResearch/hermes-agent/pull/2465))
+- **Expose MCP servers as standalone toolsets** ([#1907](https://github.com/NousResearch/hermes-agent/pull/1907))
+- **Interactive MCP tool configuration** in `hermes tools` ([#1694](https://github.com/NousResearch/hermes-agent/pull/1694))
+- Fix: MCP-OAuth port mismatch, path traversal, and shared handler state ([#2552](https://github.com/NousResearch/hermes-agent/pull/2552))
+- Fix: preserve MCP tool registrations across session resets ([#2124](https://github.com/NousResearch/hermes-agent/pull/2124))
+- Fix: concurrent file access crash + duplicate MCP registration ([#2154](https://github.com/NousResearch/hermes-agent/pull/2154))
+- Fix: normalise MCP schemas + expand session list columns ([#2102](https://github.com/NousResearch/hermes-agent/pull/2102))
+- Fix: `tool_choice` `mcp_` prefix handling ([#1775](https://github.com/NousResearch/hermes-agent/pull/1775))
+
+### Web Tool Backends
+- **Tavily** as web search/extract/crawl backend ([#1731](https://github.com/NousResearch/hermes-agent/pull/1731))
+- **Parallel** as alternative web search/extract backend ([#1696](https://github.com/NousResearch/hermes-agent/pull/1696))
+- **Configurable web backend** — Firecrawl/BeautifulSoup/Playwright selection ([#2256](https://github.com/NousResearch/hermes-agent/pull/2256))
+- Fix: whitespace-only env vars bypass web backend detection ([#2341](https://github.com/NousResearch/hermes-agent/pull/2341))
+
+### New Tools
+- **IMAP email** reading and sending ([#2173](https://github.com/NousResearch/hermes-agent/pull/2173))
+- **STT (speech-to-text)** tool using Whisper API ([#2072](https://github.com/NousResearch/hermes-agent/pull/2072))
+- **Route-aware pricing estimates** ([#1695](https://github.com/NousResearch/hermes-agent/pull/1695))
+
+### Tool Improvements
+- TTS: `base_url` support for OpenAI TTS provider ([#2064](https://github.com/NousResearch/hermes-agent/pull/2064) by @hanai)
+- Vision: configurable timeout, tilde expansion in file paths, DM vision with multi-image and base64 fallback ([#2480](https://github.com/NousResearch/hermes-agent/pull/2480), [#2585](https://github.com/NousResearch/hermes-agent/pull/2585), [#2211](https://github.com/NousResearch/hermes-agent/pull/2211))
+- Browser: race condition fix in session creation ([#1721](https://github.com/NousResearch/hermes-agent/pull/1721)), TypeError on unexpected LLM params ([#1735](https://github.com/NousResearch/hermes-agent/pull/1735))
+- File tools: strip ANSI escape codes from write_file and patch content ([#2532](https://github.com/NousResearch/hermes-agent/pull/2532)), include pagination args in repeated search key ([#1824](https://github.com/NousResearch/hermes-agent/pull/1824) by @cutepawss), improve fuzzy matching accuracy + position calculation refactor ([#2096](https://github.com/NousResearch/hermes-agent/pull/2096), [#1681](https://github.com/NousResearch/hermes-agent/pull/1681))
+- Code execution: resource leak and double socket close fix ([#2381](https://github.com/NousResearch/hermes-agent/pull/2381))
+- Delegate: thread safety for concurrent subagent delegation ([#1672](https://github.com/NousResearch/hermes-agent/pull/1672)), preserve parent agent's tool list after delegation ([#1778](https://github.com/NousResearch/hermes-agent/pull/1778))
+- Fix: make concurrent tool batching path-aware for file mutations ([#1914](https://github.com/NousResearch/hermes-agent/pull/1914))
+- Fix: chunk long messages in `send_message_tool` before platform dispatch ([#1646](https://github.com/NousResearch/hermes-agent/pull/1646))
+- Fix: add missing 'messaging' toolset ([#1718](https://github.com/NousResearch/hermes-agent/pull/1718))
+- Fix: prevent unavailable tool names from leaking into model schemas ([#2072](https://github.com/NousResearch/hermes-agent/pull/2072))
+- Fix: pass visited set by reference to prevent diamond dependency duplication ([#2311](https://github.com/NousResearch/hermes-agent/pull/2311))
+- Fix: Daytona sandbox lookup migrated from `find_one` to `get/list` ([#2063](https://github.com/NousResearch/hermes-agent/pull/2063) by @rovle)
+
+---
+
+## 🧩 Skills Ecosystem
+
+### Skills System Improvements
+- **Agent-created skills** — Caution-level findings allowed, dangerous skills ask instead of block ([#1840](https://github.com/NousResearch/hermes-agent/pull/1840), [#2446](https://github.com/NousResearch/hermes-agent/pull/2446))
+- **`--yes` flag** to bypass confirmation in `/skills install` and uninstall ([#1647](https://github.com/NousResearch/hermes-agent/pull/1647))
+- **Disabled skills respected** across banner, system prompt, and slash commands ([#1897](https://github.com/NousResearch/hermes-agent/pull/1897))
+- Fix: skills custom_tools import crash + sandbox file_tools integration ([#2239](https://github.com/NousResearch/hermes-agent/pull/2239))
+- Fix: agent-created skills with pip requirements crash on install ([#2145](https://github.com/NousResearch/hermes-agent/pull/2145))
+- Fix: race condition in `Skills.__init__` when `hub.yaml` missing ([#2242](https://github.com/NousResearch/hermes-agent/pull/2242))
+- Fix: validate skill metadata before install and block duplicates ([#2241](https://github.com/NousResearch/hermes-agent/pull/2241))
+- Fix: skills hub inspect/resolve — 4 bugs in inspect, redirects, discovery, tap list ([#2447](https://github.com/NousResearch/hermes-agent/pull/2447))
+- Fix: agent-created skills keep working after session reset ([#2121](https://github.com/NousResearch/hermes-agent/pull/2121))
+
+### New Skills
+- **OCR-and-documents** — PDF/DOCX/XLS/PPTX/image OCR with optional GPU ([#2236](https://github.com/NousResearch/hermes-agent/pull/2236), [#2461](https://github.com/NousResearch/hermes-agent/pull/2461))
+- **Huggingface-hub** bundled skill ([#1921](https://github.com/NousResearch/hermes-agent/pull/1921))
+- **Sherlock OSINT** username search ([#1671](https://github.com/NousResearch/hermes-agent/pull/1671))
+- **Meme-generation** — Image generator with Pillow ([#2344](https://github.com/NousResearch/hermes-agent/pull/2344))
+- **Bioinformatics** gateway skill — index to 400+ bio skills ([#2387](https://github.com/NousResearch/hermes-agent/pull/2387))
+- **Inference.sh** skill (terminal-based) ([#1686](https://github.com/NousResearch/hermes-agent/pull/1686))
+- **Base blockchain** optional skill ([#1643](https://github.com/NousResearch/hermes-agent/pull/1643))
+- **3D-model-viewer** optional skill ([#2226](https://github.com/NousResearch/hermes-agent/pull/2226))
+- **FastMCP** optional skill ([#2113](https://github.com/NousResearch/hermes-agent/pull/2113))
+- **Hermes-agent-setup** skill ([#1905](https://github.com/NousResearch/hermes-agent/pull/1905))
+
+---
+
+## 🔌 Plugin System Enhancements
+
+- **TUI extension hooks** — Build custom CLIs on top of Hermes ([#2333](https://github.com/NousResearch/hermes-agent/pull/2333))
+- **`hermes plugins install/remove/list`** commands ([#2337](https://github.com/NousResearch/hermes-agent/pull/2337))
+- **Slash command registration** for plugins ([#2359](https://github.com/NousResearch/hermes-agent/pull/2359))
+- **`session:end` lifecycle event** hook ([#1725](https://github.com/NousResearch/hermes-agent/pull/1725))
+- Fix: require opt-in for project plugin discovery ([#2215](https://github.com/NousResearch/hermes-agent/pull/2215))
+
+---
+
+## 🔒 Security & Reliability
+
+### Security
+- **SSRF protection** for vision_tools and web_tools ([#2679](https://github.com/NousResearch/hermes-agent/pull/2679))
+- **Shell injection prevention** in `_expand_path` via `~user` path suffix ([#2685](https://github.com/NousResearch/hermes-agent/pull/2685))
+- **Block untrusted browser-origin** API server access ([#2451](https://github.com/NousResearch/hermes-agent/pull/2451))
+- **Block sandbox backend creds** from subprocess env ([#1658](https://github.com/NousResearch/hermes-agent/pull/1658))
+- **Block @ references** from reading secrets outside workspace ([#2601](https://github.com/NousResearch/hermes-agent/pull/2601) by @Gutslabs)
+- **Malicious code pattern pre-exec scanner** for terminal_tool ([#2245](https://github.com/NousResearch/hermes-agent/pull/2245))
+- **Harden terminal safety** and sandbox file writes ([#1653](https://github.com/NousResearch/hermes-agent/pull/1653))
+- **PKCE verifier leak** fix + OAuth refresh Content-Type ([#1775](https://github.com/NousResearch/hermes-agent/pull/1775))
+- **Eliminate SQL string formatting** in `execute()` calls ([#2061](https://github.com/NousResearch/hermes-agent/pull/2061) by @dusterbloom)
+- **Harden jobs API** — input limits, field whitelist, startup check ([#2456](https://github.com/NousResearch/hermes-agent/pull/2456))
+
+### Reliability
+- Thread locks on 4 SessionDB methods ([#1704](https://github.com/NousResearch/hermes-agent/pull/1704))
+- File locking for concurrent memory writes ([#1726](https://github.com/NousResearch/hermes-agent/pull/1726))
+- Handle OpenRouter errors gracefully ([#2112](https://github.com/NousResearch/hermes-agent/pull/2112))
+- Guard print() calls against OSError ([#1668](https://github.com/NousResearch/hermes-agent/pull/1668))
+- Safely handle non-string inputs in redacting formatter ([#2392](https://github.com/NousResearch/hermes-agent/pull/2392), [#1700](https://github.com/NousResearch/hermes-agent/pull/1700))
+- ACP: preserve session provider on model switch, persist sessions to disk ([#2380](https://github.com/NousResearch/hermes-agent/pull/2380), [#2071](https://github.com/NousResearch/hermes-agent/pull/2071))
+- API server: persist ResponseStore to SQLite across restarts ([#2472](https://github.com/NousResearch/hermes-agent/pull/2472))
+- Fix: `fetch_nous_models` always TypeError from positional args ([#1699](https://github.com/NousResearch/hermes-agent/pull/1699))
+- Fix: resolve merge conflict markers in cli.py breaking startup ([#2347](https://github.com/NousResearch/hermes-agent/pull/2347))
+- Fix: `minisweagent_path.py` missing from wheel ([#2098](https://github.com/NousResearch/hermes-agent/pull/2098) by @JiwaniZakir)
+
+### Cron System
+- **`[SILENT]` response** — cron agents can suppress delivery ([#1833](https://github.com/NousResearch/hermes-agent/pull/1833))
+- **Scale missed-job grace window** with schedule frequency ([#2449](https://github.com/NousResearch/hermes-agent/pull/2449))
+- **Recover recent one-shot jobs** ([#1918](https://github.com/NousResearch/hermes-agent/pull/1918))
+- Fix: normalize `repeat<=0` to None — jobs deleted after first run when LLM passes -1 ([#2612](https://github.com/NousResearch/hermes-agent/pull/2612) by @Mibayy)
+- Fix: Matrix added to scheduler delivery platform_map ([#2167](https://github.com/NousResearch/hermes-agent/pull/2167) by @buntingszn)
+- Fix: naive ISO timestamps without timezone — jobs fire at wrong time ([#1729](https://github.com/NousResearch/hermes-agent/pull/1729))
+- Fix: `get_due_jobs` reads `jobs.json` twice — race condition ([#1716](https://github.com/NousResearch/hermes-agent/pull/1716))
+- Fix: silent jobs return empty response for delivery skip ([#2442](https://github.com/NousResearch/hermes-agent/pull/2442))
+- Fix: stop injecting cron outputs into gateway session history ([#2313](https://github.com/NousResearch/hermes-agent/pull/2313))
+- Fix: close abandoned coroutine when `asyncio.run()` raises RuntimeError ([#2317](https://github.com/NousResearch/hermes-agent/pull/2317))
+
+---
+
+## 🧪 Testing
+
+- Resolve all consistently failing tests ([#2488](https://github.com/NousResearch/hermes-agent/pull/2488))
+- Replace `FakePath` with `monkeypatch` for Python 3.12 compat ([#2444](https://github.com/NousResearch/hermes-agent/pull/2444))
+- Align Hermes setup and full-suite expectations ([#1710](https://github.com/NousResearch/hermes-agent/pull/1710))
+
+---
+
+## 📚 Documentation
+
+- Comprehensive docs update for recent features ([#1693](https://github.com/NousResearch/hermes-agent/pull/1693), [#2183](https://github.com/NousResearch/hermes-agent/pull/2183))
+- Alibaba Cloud and DingTalk setup guides ([#1687](https://github.com/NousResearch/hermes-agent/pull/1687), [#1692](https://github.com/NousResearch/hermes-agent/pull/1692))
+- Detailed skills documentation ([#2244](https://github.com/NousResearch/hermes-agent/pull/2244))
+- Honcho self-hosted / Docker configuration ([#2475](https://github.com/NousResearch/hermes-agent/pull/2475))
+- Context length detection FAQ and quickstart references ([#2179](https://github.com/NousResearch/hermes-agent/pull/2179))
+- Fix docs inconsistencies across reference and user guides ([#1995](https://github.com/NousResearch/hermes-agent/pull/1995))
+- Fix MCP install commands — use uv, not bare pip ([#1909](https://github.com/NousResearch/hermes-agent/pull/1909))
+- Replace ASCII diagrams with Mermaid/lists ([#2402](https://github.com/NousResearch/hermes-agent/pull/2402))
+- Gemini OAuth provider implementation plan ([#2467](https://github.com/NousResearch/hermes-agent/pull/2467))
+- Discord Server Members Intent marked as required ([#2330](https://github.com/NousResearch/hermes-agent/pull/2330))
+- Fix MDX build error in api-server.md ([#1787](https://github.com/NousResearch/hermes-agent/pull/1787))
+- Align venv path to match installer ([#2114](https://github.com/NousResearch/hermes-agent/pull/2114))
+- New skills added to hub index ([#2281](https://github.com/NousResearch/hermes-agent/pull/2281))
+
+---
+
+## 👥 Contributors
+
+### Core
+- **@teknium1** (Teknium) — 280 PRs
+
+### Community Contributors
+- **@mchzimm** (to_the_max) — GitHub Copilot provider integration ([#1879](https://github.com/NousResearch/hermes-agent/pull/1879))
+- **@jquesnelle** (Jeffrey Quesnelle) — Per-thread persistent event loops fix ([#2214](https://github.com/NousResearch/hermes-agent/pull/2214))
+- **@llbn** (lbn) — Telegram MarkdownV2 strikethrough, spoiler, blockquotes, and escape fixes ([#2199](https://github.com/NousResearch/hermes-agent/pull/2199), [#2200](https://github.com/NousResearch/hermes-agent/pull/2200))
+- **@dusterbloom** — SQL injection prevention + local server context window querying ([#2061](https://github.com/NousResearch/hermes-agent/pull/2061), [#2091](https://github.com/NousResearch/hermes-agent/pull/2091))
+- **@0xbyt4** — Anthropic tool_calls None guard + OpenCode-Go provider config fix ([#2209](https://github.com/NousResearch/hermes-agent/pull/2209), [#2393](https://github.com/NousResearch/hermes-agent/pull/2393))
+- **@sai-samarth** (Saisamarth) — WhatsApp send_message routing + systemd node path ([#1769](https://github.com/NousResearch/hermes-agent/pull/1769), [#1767](https://github.com/NousResearch/hermes-agent/pull/1767))
+- **@Gutslabs** (Guts) — Block @ references from reading secrets ([#2601](https://github.com/NousResearch/hermes-agent/pull/2601))
+- **@Mibayy** (Mibay) — Cron job repeat normalization ([#2612](https://github.com/NousResearch/hermes-agent/pull/2612))
+- **@ten-jampa** (Tenzin Jampa) — Gateway /title command fix ([#2379](https://github.com/NousResearch/hermes-agent/pull/2379))
+- **@cutepawss** (lila) — File tools search pagination fix ([#1824](https://github.com/NousResearch/hermes-agent/pull/1824))
+- **@hanai** (Hanai) — OpenAI TTS base_url support ([#2064](https://github.com/NousResearch/hermes-agent/pull/2064))
+- **@rovle** (Lovre Pešut) — Daytona sandbox API migration ([#2063](https://github.com/NousResearch/hermes-agent/pull/2063))
+- **@buntingszn** (bunting szn) — Matrix cron delivery support ([#2167](https://github.com/NousResearch/hermes-agent/pull/2167))
+- **@InB4DevOps** — Token counter reset on new session ([#2101](https://github.com/NousResearch/hermes-agent/pull/2101))
+- **@JiwaniZakir** (Zakir Jiwani) — Missing file in wheel fix ([#2098](https://github.com/NousResearch/hermes-agent/pull/2098))
+- **@ygd58** (buray) — Delegate tool parent tool names fix ([#2083](https://github.com/NousResearch/hermes-agent/pull/2083))
+
+---
+
+**Full Changelog**: [v2026.3.17...v2026.3.23](https://github.com/NousResearch/hermes-agent/compare/v2026.3.17...v2026.3.23)

RELEASE_v0.5.0.md

@@ -0,0 +1,348 @@
+# Hermes Agent v0.5.0 (v2026.3.28)
+
+**Release Date:** March 28, 2026
+
+> The hardening release — Hugging Face provider, /model command overhaul, Telegram Private Chat Topics, native Modal SDK, plugin lifecycle hooks, tool-use enforcement for GPT models, Nix flake, 50+ security and reliability fixes, and a comprehensive supply chain audit.
+
+---
+
+## ✨ Highlights
+
+- **Nous Portal now supports 400+ models** — The Nous Research inference portal has expanded dramatically, giving Hermes Agent users access to over 400 models through a single provider endpoint
+
+- **Hugging Face as a first-class inference provider** — Full integration with HF Inference API including curated agentic model picker that maps to OpenRouter analogues, live `/models` endpoint probe, and setup wizard flow ([#3419](https://github.com/NousResearch/hermes-agent/pull/3419), [#3440](https://github.com/NousResearch/hermes-agent/pull/3440))
+
+- **Telegram Private Chat Topics** — Project-based conversations with functional skill binding per topic, enabling isolated workflows within a single Telegram chat ([#3163](https://github.com/NousResearch/hermes-agent/pull/3163))
+
+- **Native Modal SDK backend** — Replaced swe-rex dependency with native Modal SDK (`Sandbox.create.aio` + `exec.aio`), eliminating tunnels and simplifying the Modal terminal backend ([#3538](https://github.com/NousResearch/hermes-agent/pull/3538))
+
+- **Plugin lifecycle hooks activated** — `pre_llm_call`, `post_llm_call`, `on_session_start`, and `on_session_end` hooks now fire in the agent loop and CLI/gateway, completing the plugin hook system ([#3542](https://github.com/NousResearch/hermes-agent/pull/3542))
+
+- **Improved OpenAI Model Reliability** — Added `GPT_TOOL_USE_GUIDANCE` to prevent GPT models from describing intended actions instead of making tool calls, plus automatic stripping of stale budget warnings from conversation history that caused models to avoid tools across turns ([#3528](https://github.com/NousResearch/hermes-agent/pull/3528))
+
+- **Nix flake** — Full uv2nix build, NixOS module with persistent container mode, auto-generated config keys from Python source, and suffix PATHs for agent-friendliness ([#20](https://github.com/NousResearch/hermes-agent/pull/20), [#3274](https://github.com/NousResearch/hermes-agent/pull/3274), [#3061](https://github.com/NousResearch/hermes-agent/pull/3061)) by @alt-glitch
+
+- **Supply chain hardening** — Removed compromised `litellm` dependency, pinned all dependency version ranges, regenerated `uv.lock` with hashes, added CI workflow scanning PRs for supply chain attack patterns, and bumped deps to fix CVEs ([#2796](https://github.com/NousResearch/hermes-agent/pull/2796), [#2810](https://github.com/NousResearch/hermes-agent/pull/2810), [#2812](https://github.com/NousResearch/hermes-agent/pull/2812), [#2816](https://github.com/NousResearch/hermes-agent/pull/2816), [#3073](https://github.com/NousResearch/hermes-agent/pull/3073))
+
+- **Anthropic output limits fix** — Replaced hardcoded 16K `max_tokens` with per-model native output limits (128K for Opus 4.6, 64K for Sonnet 4.6), fixing "Response truncated" and thinking-budget exhaustion on direct Anthropic API ([#3426](https://github.com/NousResearch/hermes-agent/pull/3426), [#3444](https://github.com/NousResearch/hermes-agent/pull/3444))
+
+---
+
+## 🏗️ Core Agent & Architecture
+
+### New Provider: Hugging Face
+- First-class Hugging Face Inference API integration with auth, setup wizard, and model picker ([#3419](https://github.com/NousResearch/hermes-agent/pull/3419))
+- Curated model list mapping OpenRouter agentic defaults to HF equivalents — providers with 8+ curated models skip live `/models` probe for speed ([#3440](https://github.com/NousResearch/hermes-agent/pull/3440))
+- Added glm-5-turbo to Z.AI provider model list ([#3095](https://github.com/NousResearch/hermes-agent/pull/3095))
+
+### Provider & Model Improvements
+- `/model` command overhaul — extracted shared `switch_model()` pipeline for CLI and gateway, custom endpoint support, provider-aware routing ([#2795](https://github.com/NousResearch/hermes-agent/pull/2795), [#2799](https://github.com/NousResearch/hermes-agent/pull/2799))
+- Removed `/model` slash command from CLI and gateway in favor of `hermes model` subcommand ([#3080](https://github.com/NousResearch/hermes-agent/pull/3080))
+- Preserve `custom` provider instead of silently remapping to `openrouter` ([#2792](https://github.com/NousResearch/hermes-agent/pull/2792))
+- Read root-level `provider` and `base_url` from config.yaml into model config ([#3112](https://github.com/NousResearch/hermes-agent/pull/3112))
+- Align Nous Portal model slugs with OpenRouter naming ([#3253](https://github.com/NousResearch/hermes-agent/pull/3253))
+- Fix Alibaba provider default endpoint and model list ([#3484](https://github.com/NousResearch/hermes-agent/pull/3484))
+- Allow MiniMax users to override `/v1` → `/anthropic` auto-correction ([#3553](https://github.com/NousResearch/hermes-agent/pull/3553))
+- Migrate OAuth token refresh to `platform.claude.com` with fallback ([#3246](https://github.com/NousResearch/hermes-agent/pull/3246))
+
+### Agent Loop & Conversation
+- **Improved OpenAI model reliability** — `GPT_TOOL_USE_GUIDANCE` prevents GPT models from describing actions instead of calling tools + automatic budget warning stripping from history ([#3528](https://github.com/NousResearch/hermes-agent/pull/3528))
+- **Surface lifecycle events** — All retry, fallback, and compression events now surface to the user as formatted messages ([#3153](https://github.com/NousResearch/hermes-agent/pull/3153))
+- **Anthropic output limits** — Per-model native output limits instead of hardcoded 16K `max_tokens` ([#3426](https://github.com/NousResearch/hermes-agent/pull/3426))
+- **Thinking-budget exhaustion detection** — Skip useless continuation retries when model uses all output tokens on reasoning ([#3444](https://github.com/NousResearch/hermes-agent/pull/3444))
+- Always prefer streaming for API calls to prevent hung subagents ([#3120](https://github.com/NousResearch/hermes-agent/pull/3120))
+- Restore safe non-streaming fallback after stream failures ([#3020](https://github.com/NousResearch/hermes-agent/pull/3020))
+- Give subagents independent iteration budgets ([#3004](https://github.com/NousResearch/hermes-agent/pull/3004))
+- Update `api_key` in `_try_activate_fallback` for subagent auth ([#3103](https://github.com/NousResearch/hermes-agent/pull/3103))
+- Graceful return on max retries instead of crashing thread ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Count compression restarts toward retry limit ([#3070](https://github.com/NousResearch/hermes-agent/pull/3070))
+- Include tool tokens in preflight estimate, guard context probe persistence ([#3164](https://github.com/NousResearch/hermes-agent/pull/3164))
+- Update context compressor limits after fallback activation ([#3305](https://github.com/NousResearch/hermes-agent/pull/3305))
+- Validate empty user messages to prevent Anthropic API 400 errors ([#3322](https://github.com/NousResearch/hermes-agent/pull/3322))
+- GLM reasoning-only and max-length handling ([#3010](https://github.com/NousResearch/hermes-agent/pull/3010))
+- Increase API timeout default from 900s to 1800s for slow-thinking models ([#3431](https://github.com/NousResearch/hermes-agent/pull/3431))
+- Send `max_tokens` for Claude/OpenRouter + retry SSE connection errors ([#3497](https://github.com/NousResearch/hermes-agent/pull/3497))
+- Prevent AsyncOpenAI/httpx cross-loop deadlock in gateway mode ([#2701](https://github.com/NousResearch/hermes-agent/pull/2701)) by @ctlst
+
+### Streaming & Reasoning
+- **Persist reasoning across gateway session turns** with new schema v6 columns (`reasoning`, `reasoning_details`, `codex_reasoning_items`) ([#2974](https://github.com/NousResearch/hermes-agent/pull/2974))
+- Detect and kill stale SSE connections ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Fix stale stream detector race causing spurious `RemoteProtocolError` ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Skip duplicate callback for `<think>`-extracted reasoning during streaming ([#3116](https://github.com/NousResearch/hermes-agent/pull/3116))
+- Preserve reasoning fields in `rewrite_transcript` ([#3311](https://github.com/NousResearch/hermes-agent/pull/3311))
+- Preserve Gemini thought signatures in streamed tool calls ([#2997](https://github.com/NousResearch/hermes-agent/pull/2997))
+- Ensure first delta is fired during reasoning updates ([untagged commit](https://github.com/NousResearch/hermes-agent))
+
+### Session & Memory
+- **Session search recent sessions mode** — Omit query to browse recent sessions with titles, previews, and timestamps ([#2533](https://github.com/NousResearch/hermes-agent/pull/2533))
+- **Session config surfacing** on `/new`, `/reset`, and auto-reset ([#3321](https://github.com/NousResearch/hermes-agent/pull/3321))
+- **Third-party session isolation** — `--source` flag for isolating sessions by origin ([#3255](https://github.com/NousResearch/hermes-agent/pull/3255))
+- Add `/resume` CLI handler, session log truncation guard, `reopen_session` API ([#3315](https://github.com/NousResearch/hermes-agent/pull/3315))
+- Clear compressor summary and turn counter on `/clear` and `/new` ([#3102](https://github.com/NousResearch/hermes-agent/pull/3102))
+- Surface silent SessionDB failures that cause session data loss ([#2999](https://github.com/NousResearch/hermes-agent/pull/2999))
+- Session search fallback preview on summarization failure ([#3478](https://github.com/NousResearch/hermes-agent/pull/3478))
+- Prevent stale memory overwrites by flush agent ([#2687](https://github.com/NousResearch/hermes-agent/pull/2687))
+
+### Context Compression
+- Replace dead `summary_target_tokens` with ratio-based scaling ([#2554](https://github.com/NousResearch/hermes-agent/pull/2554))
+- Expose `compression.target_ratio`, `protect_last_n`, and `threshold` in `DEFAULT_CONFIG` ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Restore sane defaults and cap summary at 12K tokens ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Preserve transcript on `/compress` and hygiene compression ([#3556](https://github.com/NousResearch/hermes-agent/pull/3556))
+- Update context pressure warnings and token estimates after compaction ([untagged commit](https://github.com/NousResearch/hermes-agent))
+
+### Architecture & Dependencies
+- **Remove mini-swe-agent dependency** — Inline Docker and Modal backends directly ([#2804](https://github.com/NousResearch/hermes-agent/pull/2804))
+- **Replace swe-rex with native Modal SDK** for Modal backend ([#3538](https://github.com/NousResearch/hermes-agent/pull/3538))
+- **Plugin lifecycle hooks** — `pre_llm_call`, `post_llm_call`, `on_session_start`, `on_session_end` now fire in the agent loop ([#3542](https://github.com/NousResearch/hermes-agent/pull/3542))
+- Fix plugin toolsets invisible in `hermes tools` and standalone processes ([#3457](https://github.com/NousResearch/hermes-agent/pull/3457))
+- Consolidate `get_hermes_home()` and `parse_reasoning_effort()` ([#3062](https://github.com/NousResearch/hermes-agent/pull/3062))
+- Remove unused Hermes-native PKCE OAuth flow ([#3107](https://github.com/NousResearch/hermes-agent/pull/3107))
+- Remove ~100 unused imports across 55 files ([#3016](https://github.com/NousResearch/hermes-agent/pull/3016))
+- Fix 154 f-strings, simplify getattr/URL patterns, remove dead code ([#3119](https://github.com/NousResearch/hermes-agent/pull/3119))
+
+---
+
+## 📱 Messaging Platforms (Gateway)
+
+### Telegram
+- **Private Chat Topics** — Project-based conversations with functional skill binding per topic, enabling isolated workflows within a single Telegram chat ([#3163](https://github.com/NousResearch/hermes-agent/pull/3163))
+- **Auto-discover fallback IPs via DNS-over-HTTPS** when `api.telegram.org` is unreachable ([#3376](https://github.com/NousResearch/hermes-agent/pull/3376))
+- **Configurable reply threading mode** ([#2907](https://github.com/NousResearch/hermes-agent/pull/2907))
+- Fall back to no `thread_id` on "Message thread not found" BadRequest ([#3390](https://github.com/NousResearch/hermes-agent/pull/3390))
+- Self-reschedule reconnect when `start_polling` fails after 502 ([#3268](https://github.com/NousResearch/hermes-agent/pull/3268))
+
+### Discord
+- Stop phantom typing indicator after agent turn completes ([#3003](https://github.com/NousResearch/hermes-agent/pull/3003))
+
+### Slack
+- Send tool call progress messages to correct Slack thread ([#3063](https://github.com/NousResearch/hermes-agent/pull/3063))
+- Scope progress thread fallback to Slack only ([#3488](https://github.com/NousResearch/hermes-agent/pull/3488))
+
+### WhatsApp
+- Download documents, audio, and video media from messages ([#2978](https://github.com/NousResearch/hermes-agent/pull/2978))
+
+### Matrix
+- Add missing Matrix entry in `PLATFORMS` dict ([#3473](https://github.com/NousResearch/hermes-agent/pull/3473))
+- Harden e2ee access-token handling ([#3562](https://github.com/NousResearch/hermes-agent/pull/3562))
+- Add backoff for `SyncError` in sync loop ([#3280](https://github.com/NousResearch/hermes-agent/pull/3280))
+
+### Signal
+- Track SSE keepalive comments as connection activity ([#3316](https://github.com/NousResearch/hermes-agent/pull/3316))
+
+### Email
+- Prevent unbounded growth of `_seen_uids` in EmailAdapter ([#3490](https://github.com/NousResearch/hermes-agent/pull/3490))
+
+### Gateway Core
+- **Config-gated `/verbose` command** for messaging platforms — toggle tool output verbosity from chat ([#3262](https://github.com/NousResearch/hermes-agent/pull/3262))
+- **Background review notifications** delivered to user chat ([#3293](https://github.com/NousResearch/hermes-agent/pull/3293))
+- **Retry transient send failures** and notify user on exhaustion ([#3288](https://github.com/NousResearch/hermes-agent/pull/3288))
+- Recover from hung agents — `/stop` hard-kills session lock ([#3104](https://github.com/NousResearch/hermes-agent/pull/3104))
+- Thread-safe `SessionStore` — protect `_entries` with `threading.Lock` ([#3052](https://github.com/NousResearch/hermes-agent/pull/3052))
+- Fix gateway token double-counting with cached agents — use absolute set instead of increment ([#3306](https://github.com/NousResearch/hermes-agent/pull/3306), [#3317](https://github.com/NousResearch/hermes-agent/pull/3317))
+- Fingerprint full auth token in agent cache signature ([#3247](https://github.com/NousResearch/hermes-agent/pull/3247))
+- Silence background agent terminal output ([#3297](https://github.com/NousResearch/hermes-agent/pull/3297))
+- Include per-platform `ALLOW_ALL` and `SIGNAL_GROUP` in startup allowlist check ([#3313](https://github.com/NousResearch/hermes-agent/pull/3313))
+- Include user-local bin paths in systemd unit PATH ([#3527](https://github.com/NousResearch/hermes-agent/pull/3527))
+- Track background task references in `GatewayRunner` ([#3254](https://github.com/NousResearch/hermes-agent/pull/3254))
+- Add request timeouts to HA, Email, Mattermost, SMS adapters ([#3258](https://github.com/NousResearch/hermes-agent/pull/3258))
+- Add media download retry to Mattermost, Slack, and base cache ([#3323](https://github.com/NousResearch/hermes-agent/pull/3323))
+- Detect virtualenv path instead of hardcoding `venv/` ([#2797](https://github.com/NousResearch/hermes-agent/pull/2797))
+- Use `TERMINAL_CWD` for context file discovery, not process cwd ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Stop loading hermes repo AGENTS.md into gateway sessions (~10k wasted tokens) ([#2891](https://github.com/NousResearch/hermes-agent/pull/2891))
+
+---
+
+## 🖥️ CLI & User Experience
+
+### Interactive CLI
+- **Configurable busy input mode** + fix `/queue` always working ([#3298](https://github.com/NousResearch/hermes-agent/pull/3298))
+- **Preserve user input on multiline paste** ([#3065](https://github.com/NousResearch/hermes-agent/pull/3065))
+- **Tool generation callback** — streaming "preparing terminal…" updates during tool argument generation ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Show tool progress for substantive tools, not just "preparing" ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Buffer reasoning preview chunks and fix duplicate display ([#3013](https://github.com/NousResearch/hermes-agent/pull/3013))
+- Prevent reasoning box from rendering 3x during tool-calling loops ([#3405](https://github.com/NousResearch/hermes-agent/pull/3405))
+- Eliminate "Event loop is closed" / "Press ENTER to continue" during idle — three-layer fix with `neuter_async_httpx_del()`, custom exception handler, and stale client cleanup ([#3398](https://github.com/NousResearch/hermes-agent/pull/3398))
+- Fix status bar shows 26K instead of 260K for token counts with trailing zeros ([#3024](https://github.com/NousResearch/hermes-agent/pull/3024))
+- Fix status bar duplicates and degrades during long sessions ([#3291](https://github.com/NousResearch/hermes-agent/pull/3291))
+- Refresh TUI before background task output to prevent status bar overlap ([#3048](https://github.com/NousResearch/hermes-agent/pull/3048))
+- Suppress KawaiiSpinner animation under `patch_stdout` ([#2994](https://github.com/NousResearch/hermes-agent/pull/2994))
+- Skip KawaiiSpinner when TUI handles tool progress ([#2973](https://github.com/NousResearch/hermes-agent/pull/2973))
+- Guard `isatty()` against closed streams via `_is_tty` property ([#3056](https://github.com/NousResearch/hermes-agent/pull/3056))
+- Ensure single closure of streaming boxes during tool generation ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Cap context pressure percentage at 100% in display ([#3480](https://github.com/NousResearch/hermes-agent/pull/3480))
+- Clean up HTML error messages in CLI display ([#3069](https://github.com/NousResearch/hermes-agent/pull/3069))
+- Show HTTP status code and 400 body in API error output ([#3096](https://github.com/NousResearch/hermes-agent/pull/3096))
+- Extract useful info from HTML error pages, dump debug on max retries ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Prevent TypeError on startup when `base_url` is None ([#3068](https://github.com/NousResearch/hermes-agent/pull/3068))
+- Prevent update crash in non-TTY environments ([#3094](https://github.com/NousResearch/hermes-agent/pull/3094))
+- Handle EOFError in sessions delete/prune confirmation prompts ([#3101](https://github.com/NousResearch/hermes-agent/pull/3101))
+- Catch KeyboardInterrupt during `flush_memories` on exit and in exit cleanup handlers ([#3025](https://github.com/NousResearch/hermes-agent/pull/3025), [#3257](https://github.com/NousResearch/hermes-agent/pull/3257))
+- Guard `.strip()` against None values from YAML config ([#3552](https://github.com/NousResearch/hermes-agent/pull/3552))
+- Guard `config.get()` against YAML null values to prevent AttributeError ([#3377](https://github.com/NousResearch/hermes-agent/pull/3377))
+- Store asyncio task references to prevent GC mid-execution ([#3267](https://github.com/NousResearch/hermes-agent/pull/3267))
+
+### Setup & Configuration
+- Use explicit key mapping for returning-user menu dispatch instead of positional index ([#3083](https://github.com/NousResearch/hermes-agent/pull/3083))
+- Use `sys.executable` for pip in update commands to fix PEP 668 ([#3099](https://github.com/NousResearch/hermes-agent/pull/3099))
+- Harden `hermes update` against diverged history, non-main branches, and gateway edge cases ([#3492](https://github.com/NousResearch/hermes-agent/pull/3492))
+- OpenClaw migration overwrites defaults and setup wizard skips imported sections — fixed ([#3282](https://github.com/NousResearch/hermes-agent/pull/3282))
+- Stop recursive AGENTS.md walk, load top-level only ([#3110](https://github.com/NousResearch/hermes-agent/pull/3110))
+- Add macOS Homebrew paths to browser and terminal PATH resolution ([#2713](https://github.com/NousResearch/hermes-agent/pull/2713))
+- YAML boolean handling for `tool_progress` config ([#3300](https://github.com/NousResearch/hermes-agent/pull/3300))
+- Reset default SOUL.md to baseline identity text ([#3159](https://github.com/NousResearch/hermes-agent/pull/3159))
+- Reject relative cwd paths for container terminal backends ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Add explicit `hermes-api-server` toolset for API server platform ([#3304](https://github.com/NousResearch/hermes-agent/pull/3304))
+- Reorder setup wizard providers — OpenRouter first ([untagged commit](https://github.com/NousResearch/hermes-agent))
+
+---
+
+## 🔧 Tool System
+
+### API Server
+- **Idempotency-Key support**, body size limit, and OpenAI error envelope ([#2903](https://github.com/NousResearch/hermes-agent/pull/2903))
+- Allow Idempotency-Key in CORS headers ([#3530](https://github.com/NousResearch/hermes-agent/pull/3530))
+- Cancel orphaned agent + true interrupt on SSE disconnect ([#3427](https://github.com/NousResearch/hermes-agent/pull/3427))
+- Fix streaming breaks when agent makes tool calls ([#2985](https://github.com/NousResearch/hermes-agent/pull/2985))
+
+### Terminal & File Operations
+- Handle addition-only hunks in V4A patch parser ([#3325](https://github.com/NousResearch/hermes-agent/pull/3325))
+- Exponential backoff for persistent shell polling ([#2996](https://github.com/NousResearch/hermes-agent/pull/2996))
+- Add timeout to subprocess calls in `context_references` ([#3469](https://github.com/NousResearch/hermes-agent/pull/3469))
+
+### Browser & Vision
+- Handle 402 insufficient credits error in vision tool ([#2802](https://github.com/NousResearch/hermes-agent/pull/2802))
+- Fix `browser_vision` ignores `auxiliary.vision.timeout` config ([#2901](https://github.com/NousResearch/hermes-agent/pull/2901))
+- Make browser command timeout configurable via config.yaml ([#2801](https://github.com/NousResearch/hermes-agent/pull/2801))
+
+### MCP
+- MCP toolset resolution for runtime and config ([#3252](https://github.com/NousResearch/hermes-agent/pull/3252))
+- Add MCP tool name collision protection ([#3077](https://github.com/NousResearch/hermes-agent/pull/3077))
+
+### Auxiliary LLM
+- Guard aux LLM calls against None content + reasoning fallback + retry ([#3449](https://github.com/NousResearch/hermes-agent/pull/3449))
+- Catch ImportError from `build_anthropic_client` in vision auto-detection ([#3312](https://github.com/NousResearch/hermes-agent/pull/3312))
+
+### Other Tools
+- Add request timeouts to `send_message_tool` HTTP calls ([#3162](https://github.com/NousResearch/hermes-agent/pull/3162)) by @memosr
+- Auto-repair `jobs.json` with invalid control characters ([#3537](https://github.com/NousResearch/hermes-agent/pull/3537))
+- Enable fine-grained tool streaming for Claude/OpenRouter ([#3497](https://github.com/NousResearch/hermes-agent/pull/3497))
+
+---
+
+## 🧩 Skills Ecosystem
+
+### Skills System
+- **Env var passthrough** for skills and user config — skills can declare environment variables to pass through ([#2807](https://github.com/NousResearch/hermes-agent/pull/2807))
+- Cache skills prompt with shared `skill_utils` module for faster TTFT ([#3421](https://github.com/NousResearch/hermes-agent/pull/3421))
+- Avoid redundant file re-read for skill conditions ([#2992](https://github.com/NousResearch/hermes-agent/pull/2992))
+- Use Git Trees API to prevent silent subdirectory loss during install ([#2995](https://github.com/NousResearch/hermes-agent/pull/2995))
+- Fix skills-sh install for deeply nested repo structures ([#2980](https://github.com/NousResearch/hermes-agent/pull/2980))
+- Handle null metadata in skill frontmatter ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Preserve trust for skills-sh identifiers + reduce resolution churn ([#3251](https://github.com/NousResearch/hermes-agent/pull/3251))
+- Agent-created skills were incorrectly treated as untrusted community content — fixed ([untagged commit](https://github.com/NousResearch/hermes-agent))
+
+### New Skills
+- **G0DM0D3 godmode jailbreaking skill** + docs ([#3157](https://github.com/NousResearch/hermes-agent/pull/3157))
+- **Docker management skill** added to optional-skills ([#3060](https://github.com/NousResearch/hermes-agent/pull/3060))
+- **OpenClaw migration v2** — 17 new modules, terminal recap for migrating from OpenClaw to Hermes ([#2906](https://github.com/NousResearch/hermes-agent/pull/2906))
+
+---
+
+## 🔒 Security & Reliability
+
+### Security Hardening
+- **SSRF protection** added to `browser_navigate` ([#3058](https://github.com/NousResearch/hermes-agent/pull/3058))
+- **SSRF protection** added to `vision_tools` and `web_tools` (hardened) ([#2679](https://github.com/NousResearch/hermes-agent/pull/2679))
+- **Restrict subagent toolsets** to parent's enabled set ([#3269](https://github.com/NousResearch/hermes-agent/pull/3269))
+- **Prevent zip-slip path traversal** in self-update ([#3250](https://github.com/NousResearch/hermes-agent/pull/3250))
+- **Prevent shell injection** in `_expand_path` via `~user` path suffix ([#2685](https://github.com/NousResearch/hermes-agent/pull/2685))
+- **Normalize input** before dangerous command detection ([#3260](https://github.com/NousResearch/hermes-agent/pull/3260))
+- Make tirith block verdicts approvable instead of hard-blocking ([#3428](https://github.com/NousResearch/hermes-agent/pull/3428))
+- Remove compromised `litellm`/`typer`/`platformdirs` from deps ([#2796](https://github.com/NousResearch/hermes-agent/pull/2796))
+- Pin all dependency version ranges ([#2810](https://github.com/NousResearch/hermes-agent/pull/2810))
+- Regenerate `uv.lock` with hashes, use lockfile in setup ([#2812](https://github.com/NousResearch/hermes-agent/pull/2812))
+- Bump dependencies to fix CVEs + regenerate `uv.lock` ([#3073](https://github.com/NousResearch/hermes-agent/pull/3073))
+- Supply chain audit CI workflow for PR scanning ([#2816](https://github.com/NousResearch/hermes-agent/pull/2816))
+
+### Reliability
+- **SQLite WAL write-lock contention** causing 15-20s TUI freeze — fixed ([#3385](https://github.com/NousResearch/hermes-agent/pull/3385))
+- **SQLite concurrency hardening** + session transcript integrity ([#3249](https://github.com/NousResearch/hermes-agent/pull/3249))
+- Prevent recurring cron job re-fire on gateway crash/restart loop ([#3396](https://github.com/NousResearch/hermes-agent/pull/3396))
+- Mark cron session as ended after job completes ([#2998](https://github.com/NousResearch/hermes-agent/pull/2998))
+
+---
+
+## ⚡ Performance
+
+- **TTFT startup optimizations** — salvaged easy-win startup improvements ([#3395](https://github.com/NousResearch/hermes-agent/pull/3395))
+- Cache skills prompt with shared `skill_utils` module ([#3421](https://github.com/NousResearch/hermes-agent/pull/3421))
+- Avoid redundant file re-read for skill conditions in prompt builder ([#2992](https://github.com/NousResearch/hermes-agent/pull/2992))
+
+---
+
+## 🐛 Notable Bug Fixes
+
+- Fix gateway token double-counting with cached agents ([#3306](https://github.com/NousResearch/hermes-agent/pull/3306), [#3317](https://github.com/NousResearch/hermes-agent/pull/3317))
+- Fix "Event loop is closed" / "Press ENTER to continue" during idle sessions ([#3398](https://github.com/NousResearch/hermes-agent/pull/3398))
+- Fix reasoning box rendering 3x during tool-calling loops ([#3405](https://github.com/NousResearch/hermes-agent/pull/3405))
+- Fix status bar shows 26K instead of 260K for token counts ([#3024](https://github.com/NousResearch/hermes-agent/pull/3024))
+- Fix `/queue` always working regardless of config ([#3298](https://github.com/NousResearch/hermes-agent/pull/3298))
+- Fix phantom Discord typing indicator after agent turn ([#3003](https://github.com/NousResearch/hermes-agent/pull/3003))
+- Fix Slack progress messages appearing in wrong thread ([#3063](https://github.com/NousResearch/hermes-agent/pull/3063))
+- Fix WhatsApp media downloads (documents, audio, video) ([#2978](https://github.com/NousResearch/hermes-agent/pull/2978))
+- Fix Telegram "Message thread not found" killing progress messages ([#3390](https://github.com/NousResearch/hermes-agent/pull/3390))
+- Fix OpenClaw migration overwriting defaults ([#3282](https://github.com/NousResearch/hermes-agent/pull/3282))
+- Fix returning-user setup menu dispatching wrong section ([#3083](https://github.com/NousResearch/hermes-agent/pull/3083))
+- Fix `hermes update` PEP 668 "externally-managed-environment" error ([#3099](https://github.com/NousResearch/hermes-agent/pull/3099))
+- Fix subagents hitting `max_iterations` prematurely via shared budget ([#3004](https://github.com/NousResearch/hermes-agent/pull/3004))
+- Fix YAML boolean handling for `tool_progress` config ([#3300](https://github.com/NousResearch/hermes-agent/pull/3300))
+- Fix `config.get()` crashes on YAML null values ([#3377](https://github.com/NousResearch/hermes-agent/pull/3377))
+- Fix `.strip()` crash on None values from YAML config ([#3552](https://github.com/NousResearch/hermes-agent/pull/3552))
+- Fix hung agents on gateway — `/stop` now hard-kills session lock ([#3104](https://github.com/NousResearch/hermes-agent/pull/3104))
+- Fix `_custom` provider silently remapped to `openrouter` ([#2792](https://github.com/NousResearch/hermes-agent/pull/2792))
+- Fix Matrix missing from `PLATFORMS` dict ([#3473](https://github.com/NousResearch/hermes-agent/pull/3473))
+- Fix Email adapter unbounded `_seen_uids` growth ([#3490](https://github.com/NousResearch/hermes-agent/pull/3490))
+
+---
+
+## 🧪 Testing
+
+- Pin `agent-client-protocol` < 0.9 to handle breaking upstream release ([#3320](https://github.com/NousResearch/hermes-agent/pull/3320))
+- Catch anthropic ImportError in vision auto-detection tests ([#3312](https://github.com/NousResearch/hermes-agent/pull/3312))
+- Update retry-exhaust test for new graceful return behavior ([#3320](https://github.com/NousResearch/hermes-agent/pull/3320))
+- Add regression tests for null metadata frontmatter ([untagged commit](https://github.com/NousResearch/hermes-agent))
+
+---
+
+## 📚 Documentation
+
+- Update all docs for `/model` command overhaul and custom provider support ([#2800](https://github.com/NousResearch/hermes-agent/pull/2800))
+- Fix stale and incorrect documentation across 18 files ([#2805](https://github.com/NousResearch/hermes-agent/pull/2805))
+- Document 9 previously undocumented features ([#2814](https://github.com/NousResearch/hermes-agent/pull/2814))
+- Add missing skills, CLI commands, and messaging env vars to docs ([#2809](https://github.com/NousResearch/hermes-agent/pull/2809))
+- Fix api-server response storage documentation — SQLite, not in-memory ([#2819](https://github.com/NousResearch/hermes-agent/pull/2819))
+- Quote pip install extras to fix zsh glob errors ([#2815](https://github.com/NousResearch/hermes-agent/pull/2815))
+- Unify hooks documentation — add plugin hooks to hooks page, add `session:end` event ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Clarify two-mode behavior in `session_search` schema description ([untagged commit](https://github.com/NousResearch/hermes-agent))
+- Fix Discord Public Bot setting for Discord-provided invite link ([#3519](https://github.com/NousResearch/hermes-agent/pull/3519)) by @mehmoodosman
+- Revise v0.4.0 changelog — fix feature attribution, reorder sections ([untagged commit](https://github.com/NousResearch/hermes-agent))
+
+---
+
+## 👥 Contributors
+
+### Core
+- **@teknium1** — 157 PRs covering the full scope of this release
+
+### Community Contributors
+- **@alt-glitch** (Siddharth Balyan) — 2 PRs: Nix flake with uv2nix build, NixOS module, and persistent container mode ([#20](https://github.com/NousResearch/hermes-agent/pull/20)); auto-generated config keys and suffix PATHs for Nix builds ([#3061](https://github.com/NousResearch/hermes-agent/pull/3061), [#3274](https://github.com/NousResearch/hermes-agent/pull/3274))
+- **@ctlst** — 1 PR: Prevent AsyncOpenAI/httpx cross-loop deadlock in gateway mode ([#2701](https://github.com/NousResearch/hermes-agent/pull/2701))
+- **@memosr** (memosr.eth) — 1 PR: Add request timeouts to `send_message_tool` HTTP calls ([#3162](https://github.com/NousResearch/hermes-agent/pull/3162))
+- **@mehmoodosman** (Osman Mehmood) — 1 PR: Fix Discord docs for Public Bot setting ([#3519](https://github.com/NousResearch/hermes-agent/pull/3519))
+
+### All Contributors
+@alt-glitch, @ctlst, @mehmoodosman, @memosr, @teknium1
+
+---
+
+**Full Changelog**: [v2026.3.23...v2026.3.28](https://github.com/NousResearch/hermes-agent/compare/v2026.3.23...v2026.3.28)

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

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

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/server.py

@@ -36,6 +36,7 @@ from acp.schema import (
     SessionCapabilities,
     SessionForkCapabilities,
     SessionListCapabilities,
+    SessionResumeCapabilities,
     SessionInfo,
     TextContentBlock,
     UnstructuredCommandInput,
@@ -245,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,
@@ -451,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"

acp_adapter/session.py

@@ -262,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")

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/anthropic_adapter.py

@@ -60,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.
@@ -74,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():
@@ -95,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.
@@ -149,18 +163,38 @@ 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:
@@ -170,9 +204,10 @@ def _is_third_party_anthropic_endpoint(base_url: str | None) -> bool:
     with their own API keys via x-api-key, not Anthropic OAuth tokens. OAuth
     detection should be skipped for these endpoints.
     """
-    if not base_url:
+    normalized = _normalize_base_url_text(base_url)
+    if not normalized:
         return False  # No base_url = direct Anthropic API
-    normalized = base_url.rstrip("/").lower()
+    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
@@ -182,15 +217,27 @@ 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 instead of Anthropic's native x-api-key header.
+    require Authorization: Bearer *** of Anthropic's native x-api-key header.
     MiniMax's global and China Anthropic-compatible endpoints follow this pattern.
     """
-    if not base_url:
+    normalized = _normalize_base_url_text(base_url)
+    if not normalized:
         return False
-    normalized = base_url.rstrip("/").lower()
-    return normalized.startswith("https://api.minimax.io/anthropic") or normalized.startswith(
-        "https://api.minimaxi.com/anthropic"
-    )
+    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):
@@ -205,13 +252,15 @@ 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 _requires_bearer_auth(base_url):
+    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.
@@ -219,21 +268,21 @@ def build_anthropic_client(api_key: str, base_url: str = None):
         # 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)}
+        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)}
+        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),
@@ -243,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)
 
@@ -473,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.
 
@@ -708,44 +728,6 @@ def run_hermes_oauth_login_pure() -> Optional[Dict[str, Any]]:
     }
 
 
-def run_hermes_oauth_login() -> Optional[str]:
-    """Run Hermes-native OAuth PKCE flow for Claude Pro/Max subscription.
-
-    Opens a browser to claude.ai for authorization, prompts for the code,
-    exchanges it for tokens, and stores them in ~/.hermes/.anthropic_oauth.json.
-
-    Returns the access token on success, None on failure.
-    """
-    result = run_hermes_oauth_login_pure()
-    if not result:
-        return None
-
-    access_token = result["access_token"]
-    refresh_token = result["refresh_token"]
-    expires_at_ms = result["expires_at_ms"]
-
-    _save_hermes_oauth_credentials(access_token, refresh_token, expires_at_ms)
-    _write_claude_code_credentials(access_token, refresh_token, expires_at_ms)
-
-    print("Authentication successful!")
-    return access_token
-
-
-def _save_hermes_oauth_credentials(access_token: str, refresh_token: str, expires_at_ms: int) -> None:
-    """Save OAuth credentials to ~/.hermes/.anthropic_oauth.json."""
-    data = {
-        "accessToken": access_token,
-        "refreshToken": refresh_token,
-        "expiresAt": expires_at_ms,
-    }
-    try:
-        _HERMES_OAUTH_FILE.parent.mkdir(parents=True, exist_ok=True)
-        _HERMES_OAUTH_FILE.write_text(json.dumps(data, indent=2), encoding="utf-8")
-        _HERMES_OAUTH_FILE.chmod(0o600)
-    except (OSError, IOError) as e:
-        logger.debug("Failed to save Hermes OAuth credentials: %s", e)
-
-
 def read_hermes_oauth_credentials() -> Optional[Dict[str, Any]]:
     """Read Hermes-managed OAuth credentials from ~/.hermes/.anthropic_oauth.json."""
     if _HERMES_OAUTH_FILE.exists():
@@ -758,38 +740,6 @@ def read_hermes_oauth_credentials() -> Optional[Dict[str, Any]]:
     return None
 
 
-def refresh_hermes_oauth_token() -> Optional[str]:
-    """Refresh the Hermes-managed OAuth token using the stored refresh token.
-
-    Returns the new access token, or None if refresh fails.
-    """
-    creds = read_hermes_oauth_credentials()
-    if not creds or not creds.get("refreshToken"):
-        return None
-
-    try:
-        refreshed = refresh_anthropic_oauth_pure(
-            creds["refreshToken"],
-            use_json=True,
-        )
-        _save_hermes_oauth_credentials(
-            refreshed["access_token"],
-            refreshed["refresh_token"],
-            refreshed["expires_at_ms"],
-        )
-        _write_claude_code_credentials(
-            refreshed["access_token"],
-            refreshed["refresh_token"],
-            refreshed["expires_at_ms"],
-        )
-        logger.debug("Successfully refreshed Hermes OAuth token")
-        return refreshed["access_token"]
-    except Exception as e:
-        logger.debug("Failed to refresh Hermes OAuth token: %s", e)
-
-    return None
-
-
 # ---------------------------------------------------------------------------
 # Message / tool / response format conversion
 # ---------------------------------------------------------------------------
@@ -826,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:
@@ -1028,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 = []
@@ -1188,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):
@@ -1206,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
 
 
@@ -1219,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)
 
@@ -1310,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()
@@ -1326,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
 
 
@@ -1387,4 +1408,4 @@ def normalize_anthropic_response(
             reasoning_details=reasoning_details or None,
         ),
         finish_reason,
-    )
+    )

agent/builtin_memory_provider.py

@@ -1,113 +0,0 @@
-"""BuiltinMemoryProvider — wraps MEMORY.md / USER.md as a MemoryProvider.
-
-Always registered as the first provider. Cannot be disabled or removed.
-This is the existing Hermes memory system exposed through the provider
-interface for compatibility with the MemoryManager.
-
-The actual storage logic lives in tools/memory_tool.py (MemoryStore).
-This provider is a thin adapter that delegates to MemoryStore and
-exposes the memory tool schema.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-from typing import Any, Dict, List, Optional
-
-from agent.memory_provider import MemoryProvider
-
-logger = logging.getLogger(__name__)
-
-
-class BuiltinMemoryProvider(MemoryProvider):
-    """Built-in file-backed memory (MEMORY.md + USER.md).
-
-    Always active, never disabled by other providers. The `memory` tool
-    is handled by run_agent.py's agent-level tool interception (not through
-    the normal registry), so get_tool_schemas() returns an empty list —
-    the memory tool is already wired separately.
-    """
-
-    def __init__(
-        self,
-        memory_store=None,
-        memory_enabled: bool = False,
-        user_profile_enabled: bool = False,
-    ):
-        self._store = memory_store
-        self._memory_enabled = memory_enabled
-        self._user_profile_enabled = user_profile_enabled
-
-    @property
-    def name(self) -> str:
-        return "builtin"
-
-    def is_available(self) -> bool:
-        """Built-in memory is always available."""
-        return True
-
-    def initialize(self, session_id: str, **kwargs) -> None:
-        """Load memory from disk if not already loaded."""
-        if self._store is not None:
-            self._store.load_from_disk()
-
-    def system_prompt_block(self) -> str:
-        """Return MEMORY.md and USER.md content for the system prompt.
-
-        Uses the frozen snapshot captured at load time. This ensures the
-        system prompt stays stable throughout a session (preserving the
-        prompt cache), even though the live entries may change via tool calls.
-        """
-        if not self._store:
-            return ""
-
-        parts = []
-        if self._memory_enabled:
-            mem_block = self._store.format_for_system_prompt("memory")
-            if mem_block:
-                parts.append(mem_block)
-        if self._user_profile_enabled:
-            user_block = self._store.format_for_system_prompt("user")
-            if user_block:
-                parts.append(user_block)
-
-        return "\n\n".join(parts)
-
-    def prefetch(self, query: str, *, session_id: str = "") -> str:
-        """Built-in memory doesn't do query-based recall — it's injected via system_prompt_block."""
-        return ""
-
-    def sync_turn(self, user_content: str, assistant_content: str, *, session_id: str = "") -> None:
-        """Built-in memory doesn't auto-sync turns — writes happen via the memory tool."""
-
-    def get_tool_schemas(self) -> List[Dict[str, Any]]:
-        """Return empty list.
-
-        The `memory` tool is an agent-level intercepted tool, handled
-        specially in run_agent.py before normal tool dispatch. It's not
-        part of the standard tool registry. We don't duplicate it here.
-        """
-        return []
-
-    def handle_tool_call(self, tool_name: str, args: Dict[str, Any], **kwargs) -> str:
-        """Not used — the memory tool is intercepted in run_agent.py."""
-        return json.dumps({"error": "Built-in memory tool is handled by the agent loop"})
-
-    def shutdown(self) -> None:
-        """No cleanup needed — files are saved on every write."""
-
-    # -- Property access for backward compatibility --------------------------
-
-    @property
-    def store(self):
-        """Access the underlying MemoryStore for legacy code paths."""
-        return self._store
-
-    @property
-    def memory_enabled(self) -> bool:
-        return self._memory_enabled
-
-    @property
-    def user_profile_enabled(self) -> bool:
-        return self._user_profile_enabled

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_compressor.py

@@ -4,8 +4,12 @@ Self-contained class with its own OpenAI client for summarization.
 Uses auxiliary model (cheap/fast) to summarize middle turns while
 protecting head and tail context.
 
-Improvements over v1:
-  - Structured summary template (Goal, Progress, Decisions, Files, Next Steps)
+Improvements over v2:
+  - Structured summary template with Resolved/Pending question tracking
+  - Summarizer preamble: "Do not respond to any questions" (from OpenCode)
+  - Handoff framing: "different assistant" (from Codex) to create separation
+  - "Remaining Work" replaces "Next Steps" to avoid reading as active instructions
+  - Clear separator when summary merges into tail message
   - Iterative summary updates (preserves info across multiple compactions)
   - Token-budget tail protection instead of fixed message count
   - Tool output pruning before LLM summarization (cheap pre-pass)
@@ -13,12 +17,17 @@ Improvements over v1:
   - Richer tool call/result detail in summarizer input
 """
 
+import hashlib
+import json
 import logging
+import re
 import time
 from typing import Any, Dict, List, Optional
 
 from agent.auxiliary_client import call_llm
+from agent.context_engine import ContextEngine
 from agent.model_metadata import (
+    MINIMUM_CONTEXT_LENGTH,
     get_model_context_length,
     estimate_messages_tokens_rough,
 )
@@ -26,12 +35,13 @@ from agent.model_metadata import (
 logger = logging.getLogger(__name__)
 
 SUMMARY_PREFIX = (
-    "[CONTEXT COMPACTION] Earlier turns in this conversation were compacted "
-    "to save context space. The summary below describes work that was "
-    "already completed, and the current session state may still reflect "
-    "that work (for example, files may already be changed). Use the summary "
-    "and the current state to continue from where things left off, and "
-    "avoid repeating work:"
+    "[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were compacted "
+    "into the summary below. This is a handoff from a previous context "
+    "window — treat it as background reference, NOT as active instructions. "
+    "Do NOT answer questions or fulfill requests mentioned in this summary; "
+    "they were already addressed. Respond ONLY to the latest user message "
+    "that appears AFTER this summary. The current session state (files, "
+    "config, etc.) may reflect work described here — avoid repeating it:"
 )
 LEGACY_SUMMARY_PREFIX = "[CONTEXT SUMMARY]:"
 
@@ -50,8 +60,130 @@ _CHARS_PER_TOKEN = 4
 _SUMMARY_FAILURE_COOLDOWN_SECONDS = 600
 
 
-class ContextCompressor:
-    """Compresses conversation context when approaching the model's context limit.
+def _summarize_tool_result(tool_name: str, tool_args: str, tool_content: str) -> str:
+    """Create an informative 1-line summary of a tool call + result.
+
+    Used during the pre-compression pruning pass to replace large tool
+    outputs with a short but useful description of what the tool did,
+    rather than a generic placeholder that carries zero information.
+
+    Returns strings like::
+
+        [terminal] ran `npm test` -> exit 0, 47 lines output
+        [read_file] read config.py from line 1 (1,200 chars)
+        [search_files] content search for 'compress' in agent/ -> 12 matches
+    """
+    try:
+        args = json.loads(tool_args) if tool_args else {}
+    except (json.JSONDecodeError, TypeError):
+        args = {}
+
+    content = tool_content or ""
+    content_len = len(content)
+    line_count = content.count("\n") + 1 if content.strip() else 0
+
+    if tool_name == "terminal":
+        cmd = args.get("command", "")
+        if len(cmd) > 80:
+            cmd = cmd[:77] + "..."
+        exit_match = re.search(r'"exit_code"\s*:\s*(-?\d+)', content)
+        exit_code = exit_match.group(1) if exit_match else "?"
+        return f"[terminal] ran `{cmd}` -> exit {exit_code}, {line_count} lines output"
+
+    if tool_name == "read_file":
+        path = args.get("path", "?")
+        offset = args.get("offset", 1)
+        return f"[read_file] read {path} from line {offset} ({content_len:,} chars)"
+
+    if tool_name == "write_file":
+        path = args.get("path", "?")
+        written_lines = args.get("content", "").count("\n") + 1 if args.get("content") else "?"
+        return f"[write_file] wrote to {path} ({written_lines} lines)"
+
+    if tool_name == "search_files":
+        pattern = args.get("pattern", "?")
+        path = args.get("path", ".")
+        target = args.get("target", "content")
+        match_count = re.search(r'"total_count"\s*:\s*(\d+)', content)
+        count = match_count.group(1) if match_count else "?"
+        return f"[search_files] {target} search for '{pattern}' in {path} -> {count} matches"
+
+    if tool_name == "patch":
+        path = args.get("path", "?")
+        mode = args.get("mode", "replace")
+        return f"[patch] {mode} in {path} ({content_len:,} chars result)"
+
+    if tool_name in ("browser_navigate", "browser_click", "browser_snapshot",
+                     "browser_type", "browser_scroll", "browser_vision"):
+        url = args.get("url", "")
+        ref = args.get("ref", "")
+        detail = f" {url}" if url else (f" ref={ref}" if ref else "")
+        return f"[{tool_name}]{detail} ({content_len:,} chars)"
+
+    if tool_name == "web_search":
+        query = args.get("query", "?")
+        return f"[web_search] query='{query}' ({content_len:,} chars result)"
+
+    if tool_name == "web_extract":
+        urls = args.get("urls", [])
+        url_desc = urls[0] if isinstance(urls, list) and urls else "?"
+        if isinstance(urls, list) and len(urls) > 1:
+            url_desc += f" (+{len(urls) - 1} more)"
+        return f"[web_extract] {url_desc} ({content_len:,} chars)"
+
+    if tool_name == "delegate_task":
+        goal = args.get("goal", "")
+        if len(goal) > 60:
+            goal = goal[:57] + "..."
+        return f"[delegate_task] '{goal}' ({content_len:,} chars result)"
+
+    if tool_name == "execute_code":
+        code_preview = (args.get("code") or "")[:60].replace("\n", " ")
+        if len(args.get("code", "")) > 60:
+            code_preview += "..."
+        return f"[execute_code] `{code_preview}` ({line_count} lines output)"
+
+    if tool_name in ("skill_view", "skills_list", "skill_manage"):
+        name = args.get("name", "?")
+        return f"[{tool_name}] name={name} ({content_len:,} chars)"
+
+    if tool_name == "vision_analyze":
+        question = args.get("question", "")[:50]
+        return f"[vision_analyze] '{question}' ({content_len:,} chars)"
+
+    if tool_name == "memory":
+        action = args.get("action", "?")
+        target = args.get("target", "?")
+        return f"[memory] {action} on {target}"
+
+    if tool_name == "todo":
+        return "[todo] updated task list"
+
+    if tool_name == "clarify":
+        return "[clarify] asked user a question"
+
+    if tool_name == "text_to_speech":
+        return f"[text_to_speech] generated audio ({content_len:,} chars)"
+
+    if tool_name == "cronjob":
+        action = args.get("action", "?")
+        return f"[cronjob] {action}"
+
+    if tool_name == "process":
+        action = args.get("action", "?")
+        sid = args.get("session_id", "?")
+        return f"[process] {action} session={sid}"
+
+    # Generic fallback
+    first_arg = ""
+    for k, v in list(args.items())[:2]:
+        sv = str(v)[:40]
+        first_arg += f" {k}={sv}"
+    return f"[{tool_name}]{first_arg} ({content_len:,} chars result)"
+
+
+class ContextCompressor(ContextEngine):
+    """Default context engine — compresses conversation context via lossy summarization.
 
     Algorithm:
       1. Prune old tool results (cheap, no LLM call)
@@ -61,6 +193,40 @@ class ContextCompressor:
       5. On subsequent compactions, iteratively update the previous summary
     """
 
+    @property
+    def name(self) -> str:
+        return "compressor"
+
+    def on_session_reset(self) -> None:
+        """Reset all per-session state for /new or /reset."""
+        super().on_session_reset()
+        self._context_probed = False
+        self._context_probe_persistable = False
+        self._previous_summary = None
+        self._last_compression_savings_pct = 100.0
+        self._ineffective_compression_count = 0
+
+    def update_model(
+        self,
+        model: str,
+        context_length: int,
+        base_url: str = "",
+        api_key: str = "",
+        provider: str = "",
+        api_mode: str = "",
+    ) -> None:
+        """Update model info after a model switch or fallback activation."""
+        self.model = model
+        self.base_url = base_url
+        self.api_key = api_key
+        self.provider = provider
+        self.api_mode = api_mode
+        self.context_length = context_length
+        self.threshold_tokens = max(
+            int(context_length * self.threshold_percent),
+            MINIMUM_CONTEXT_LENGTH,
+        )
+
     def __init__(
         self,
         model: str,
@@ -74,11 +240,13 @@ class ContextCompressor:
         api_key: str = "",
         config_context_length: int | None = None,
         provider: str = "",
+        api_mode: str = "",
     ):
         self.model = model
         self.base_url = base_url
         self.api_key = api_key
         self.provider = provider
+        self.api_mode = api_mode
         self.threshold_percent = threshold_percent
         self.protect_first_n = protect_first_n
         self.protect_last_n = protect_last_n
@@ -90,7 +258,14 @@ class ContextCompressor:
             config_context_length=config_context_length,
             provider=provider,
         )
-        self.threshold_tokens = int(self.context_length * threshold_percent)
+        # Floor: never compress below MINIMUM_CONTEXT_LENGTH tokens even if
+        # the percentage would suggest a lower value.  This prevents premature
+        # compression on large-context models at 50% while keeping the % sane
+        # for models right at the minimum.
+        self.threshold_tokens = max(
+            int(self.context_length * threshold_percent),
+            MINIMUM_CONTEXT_LENGTH,
+        )
         self.compression_count = 0
 
         # Derive token budgets: ratio is relative to the threshold, not total context
@@ -114,39 +289,42 @@ class ContextCompressor:
 
         self.last_prompt_tokens = 0
         self.last_completion_tokens = 0
-        self.last_total_tokens = 0
 
         self.summary_model = summary_model_override or ""
 
         # Stores the previous compaction summary for iterative updates
         self._previous_summary: Optional[str] = None
+        # Anti-thrashing: track whether last compression was effective
+        self._last_compression_savings_pct: float = 100.0
+        self._ineffective_compression_count: int = 0
         self._summary_failure_cooldown_until: float = 0.0
 
     def update_from_response(self, usage: Dict[str, Any]):
         """Update tracked token usage from API response."""
         self.last_prompt_tokens = usage.get("prompt_tokens", 0)
         self.last_completion_tokens = usage.get("completion_tokens", 0)
-        self.last_total_tokens = usage.get("total_tokens", 0)
 
     def should_compress(self, prompt_tokens: int = None) -> bool:
-        """Check if context exceeds the compression threshold."""
+        """Check if context exceeds the compression threshold.
+
+        Includes anti-thrashing protection: if the last two compressions
+        each saved less than 10%, skip compression to avoid infinite loops
+        where each pass removes only 1-2 messages.
+        """
         tokens = prompt_tokens if prompt_tokens is not None else self.last_prompt_tokens
-        return tokens >= self.threshold_tokens
-
-    def should_compress_preflight(self, messages: List[Dict[str, Any]]) -> bool:
-        """Quick pre-flight check using rough estimate (before API call)."""
-        rough_estimate = estimate_messages_tokens_rough(messages)
-        return rough_estimate >= self.threshold_tokens
-
-    def get_status(self) -> Dict[str, Any]:
-        """Get current compression status for display/logging."""
-        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,
-        }
+        if tokens < self.threshold_tokens:
+            return False
+        # Anti-thrashing: back off if recent compressions were ineffective
+        if self._ineffective_compression_count >= 2:
+            if not self.quiet_mode:
+                logger.warning(
+                    "Compression skipped — last %d compressions saved <10%% each. "
+                    "Consider /new to start a fresh session, or /compress <topic> "
+                    "for focused compression.",
+                    self._ineffective_compression_count,
+                )
+            return False
+        return True
 
     # ------------------------------------------------------------------
     # Tool output pruning (cheap pre-pass, no LLM call)
@@ -154,12 +332,24 @@ class ContextCompressor:
 
     def _prune_old_tool_results(
         self, messages: List[Dict[str, Any]], protect_tail_count: int,
+        protect_tail_tokens: int | None = None,
     ) -> tuple[List[Dict[str, Any]], int]:
-        """Replace old tool result contents with a short placeholder.
+        """Replace old tool result contents with informative 1-line summaries.
 
-        Walks backward from the end, protecting the most recent
-        ``protect_tail_count`` messages. Older tool results get their
-        content replaced with a placeholder string.
+        Instead of a generic placeholder, generates a summary like::
+
+            [terminal] ran `npm test` -> exit 0, 47 lines output
+            [read_file] read config.py from line 1 (3,400 chars)
+
+        Also deduplicates identical tool results (e.g. reading the same file
+        5x keeps only the newest full copy) and truncates large tool_call
+        arguments in assistant messages outside the protected tail.
+
+        Walks backward from the end, protecting the most recent messages that
+        fall within ``protect_tail_tokens`` (when provided) OR the last
+        ``protect_tail_count`` messages (backward-compatible default).
+        When both are given, the token budget takes priority and the message
+        count acts as a hard minimum floor.
 
         Returns (pruned_messages, pruned_count).
         """
@@ -168,20 +358,110 @@ class ContextCompressor:
 
         result = [m.copy() for m in messages]
         pruned = 0
-        prune_boundary = len(result) - protect_tail_count
 
+        # Build index: tool_call_id -> (tool_name, arguments_json)
+        call_id_to_tool: Dict[str, tuple] = {}
+        for msg in result:
+            if msg.get("role") == "assistant":
+                for tc in msg.get("tool_calls") or []:
+                    if isinstance(tc, dict):
+                        cid = tc.get("id", "")
+                        fn = tc.get("function", {})
+                        call_id_to_tool[cid] = (fn.get("name", "unknown"), fn.get("arguments", ""))
+                    else:
+                        cid = getattr(tc, "id", "") or ""
+                        fn = getattr(tc, "function", None)
+                        name = getattr(fn, "name", "unknown") if fn else "unknown"
+                        args_str = getattr(fn, "arguments", "") if fn else ""
+                        call_id_to_tool[cid] = (name, args_str)
+
+        # Determine the prune boundary
+        if protect_tail_tokens is not None and protect_tail_tokens > 0:
+            # Token-budget approach: walk backward accumulating tokens
+            accumulated = 0
+            boundary = len(result)
+            min_protect = min(protect_tail_count, len(result) - 1)
+            for i in range(len(result) - 1, -1, -1):
+                msg = result[i]
+                raw_content = msg.get("content") or ""
+                content_len = sum(len(p.get("text", "")) for p in raw_content) if isinstance(raw_content, list) else len(raw_content)
+                msg_tokens = content_len // _CHARS_PER_TOKEN + 10
+                for tc in msg.get("tool_calls") or []:
+                    if isinstance(tc, dict):
+                        args = tc.get("function", {}).get("arguments", "")
+                        msg_tokens += len(args) // _CHARS_PER_TOKEN
+                if accumulated + msg_tokens > protect_tail_tokens and (len(result) - i) >= min_protect:
+                    boundary = i
+                    break
+                accumulated += msg_tokens
+                boundary = i
+            prune_boundary = max(boundary, len(result) - min_protect)
+        else:
+            prune_boundary = len(result) - protect_tail_count
+
+        # Pass 1: Deduplicate identical tool results.
+        # When the same file is read multiple times, keep only the most recent
+        # full copy and replace older duplicates with a back-reference.
+        content_hashes: dict = {}  # hash -> (index, tool_call_id)
+        for i in range(len(result) - 1, -1, -1):
+            msg = result[i]
+            if msg.get("role") != "tool":
+                continue
+            content = msg.get("content") or ""
+            # Skip multimodal content (list of content blocks)
+            if isinstance(content, list):
+                continue
+            if len(content) < 200:
+                continue
+            h = hashlib.md5(content.encode("utf-8", errors="replace")).hexdigest()[:12]
+            if h in content_hashes:
+                # This is an older duplicate — replace with back-reference
+                result[i] = {**msg, "content": "[Duplicate tool output — same content as a more recent call]"}
+                pruned += 1
+            else:
+                content_hashes[h] = (i, msg.get("tool_call_id", "?"))
+
+        # Pass 2: Replace old tool results with informative summaries
         for i in range(prune_boundary):
             msg = result[i]
             if msg.get("role") != "tool":
                 continue
             content = msg.get("content", "")
+            # Skip multimodal content (list of content blocks)
+            if isinstance(content, list):
+                continue
             if not content or content == _PRUNED_TOOL_PLACEHOLDER:
                 continue
+            # Skip already-deduplicated or previously-summarized results
+            if content.startswith("[Duplicate tool output"):
+                continue
             # Only prune if the content is substantial (>200 chars)
             if len(content) > 200:
-                result[i] = {**msg, "content": _PRUNED_TOOL_PLACEHOLDER}
+                call_id = msg.get("tool_call_id", "")
+                tool_name, tool_args = call_id_to_tool.get(call_id, ("unknown", ""))
+                summary = _summarize_tool_result(tool_name, tool_args, content)
+                result[i] = {**msg, "content": summary}
                 pruned += 1
 
+        # Pass 3: Truncate large tool_call arguments in assistant messages
+        # outside the protected tail. write_file with 50KB content, for
+        # example, survives pruning entirely without this.
+        for i in range(prune_boundary):
+            msg = result[i]
+            if msg.get("role") != "assistant" or not msg.get("tool_calls"):
+                continue
+            new_tcs = []
+            modified = False
+            for tc in msg["tool_calls"]:
+                if isinstance(tc, dict):
+                    args = tc.get("function", {}).get("arguments", "")
+                    if len(args) > 500:
+                        tc = {**tc, "function": {**tc["function"], "arguments": args[:200] + "...[truncated]"}}
+                        modified = True
+                new_tcs.append(tc)
+            if modified:
+                result[i] = {**msg, "tool_calls": new_tcs}
+
         return result, pruned
 
     # ------------------------------------------------------------------
@@ -199,30 +479,39 @@ class ContextCompressor:
         budget = int(content_tokens * _SUMMARY_RATIO)
         return max(_MIN_SUMMARY_TOKENS, min(budget, self.max_summary_tokens))
 
+    # Truncation limits for the summarizer input.  These bound how much of
+    # each message the summary model sees — the budget is the *summary*
+    # model's context window, not the main model's.
+    _CONTENT_MAX = 6000       # total chars per message body
+    _CONTENT_HEAD = 4000      # chars kept from the start
+    _CONTENT_TAIL = 1500      # chars kept from the end
+    _TOOL_ARGS_MAX = 1500     # tool call argument chars
+    _TOOL_ARGS_HEAD = 1200    # kept from the start of tool args
+
     def _serialize_for_summary(self, turns: List[Dict[str, Any]]) -> str:
         """Serialize conversation turns into labeled text for the summarizer.
 
-        Includes tool call arguments and result content (up to 3000 chars
-        per message) so the summarizer can preserve specific details like
-        file paths, commands, and outputs.
+        Includes tool call arguments and result content (up to
+        ``_CONTENT_MAX`` chars per message) so the summarizer can preserve
+        specific details like file paths, commands, and outputs.
         """
         parts = []
         for msg in turns:
             role = msg.get("role", "unknown")
             content = msg.get("content") or ""
 
-            # Tool results: keep more content than before (3000 chars)
+            # Tool results: keep enough content for the summarizer
             if role == "tool":
                 tool_id = msg.get("tool_call_id", "")
-                if len(content) > 3000:
-                    content = content[:2000] + "\n...[truncated]...\n" + content[-800:]
+                if len(content) > self._CONTENT_MAX:
+                    content = content[:self._CONTENT_HEAD] + "\n...[truncated]...\n" + content[-self._CONTENT_TAIL:]
                 parts.append(f"[TOOL RESULT {tool_id}]: {content}")
                 continue
 
             # Assistant messages: include tool call names AND arguments
             if role == "assistant":
-                if len(content) > 3000:
-                    content = content[:2000] + "\n...[truncated]...\n" + content[-800:]
+                if len(content) > self._CONTENT_MAX:
+                    content = content[:self._CONTENT_HEAD] + "\n...[truncated]...\n" + content[-self._CONTENT_TAIL:]
                 tool_calls = msg.get("tool_calls", [])
                 if tool_calls:
                     tc_parts = []
@@ -232,8 +521,8 @@ class ContextCompressor:
                             name = fn.get("name", "?")
                             args = fn.get("arguments", "")
                             # Truncate long arguments but keep enough for context
-                            if len(args) > 500:
-                                args = args[:400] + "..."
+                            if len(args) > self._TOOL_ARGS_MAX:
+                                args = args[:self._TOOL_ARGS_HEAD] + "..."
                             tc_parts.append(f"  {name}({args})")
                         else:
                             fn = getattr(tc, "function", None)
@@ -244,19 +533,26 @@ class ContextCompressor:
                 continue
 
             # User and other roles
-            if len(content) > 3000:
-                content = content[:2000] + "\n...[truncated]...\n" + content[-800:]
+            if len(content) > self._CONTENT_MAX:
+                content = content[:self._CONTENT_HEAD] + "\n...[truncated]...\n" + content[-self._CONTENT_TAIL:]
             parts.append(f"[{role.upper()}]: {content}")
 
         return "\n\n".join(parts)
 
-    def _generate_summary(self, turns_to_summarize: List[Dict[str, Any]]) -> Optional[str]:
+    def _generate_summary(self, turns_to_summarize: List[Dict[str, Any]], focus_topic: str = None) -> Optional[str]:
         """Generate a structured summary of conversation turns.
 
-        Uses a structured template (Goal, Progress, Decisions, Files, Next Steps)
-        inspired by Pi-mono and OpenCode. When a previous summary exists,
+        Uses a structured template (Goal, Progress, Decisions, Resolved/Pending
+        Questions, Files, Remaining Work) with explicit preamble telling the
+        summarizer not to answer questions.  When a previous summary exists,
         generates an iterative update instead of summarizing from scratch.
 
+        Args:
+            focus_topic: Optional focus string for guided compression.  When
+                provided, the summariser prioritises preserving information
+                related to this topic and is more aggressive about compressing
+                everything else.  Inspired by Claude Code's ``/compact``.
+
         Returns None if all attempts fail — the caller should drop
         the middle turns without a summary rather than inject a useless
         placeholder.
@@ -272,9 +568,75 @@ class ContextCompressor:
         summary_budget = self._compute_summary_budget(turns_to_summarize)
         content_to_summarize = self._serialize_for_summary(turns_to_summarize)
 
+        # Preamble shared by both first-compaction and iterative-update prompts.
+        # Inspired by OpenCode's "do not respond to any questions" instruction
+        # and Codex's "another language model" framing.
+        _summarizer_preamble = (
+            "You are a summarization agent creating a context checkpoint. "
+            "Your output will be injected as reference material for a DIFFERENT "
+            "assistant that continues the conversation. "
+            "Do NOT respond to any questions or requests in the conversation — "
+            "only output the structured summary. "
+            "Do NOT include any preamble, greeting, or prefix."
+        )
+
+        # Shared structured template (used by both paths).
+        _template_sections = f"""## Goal
+[What the user is trying to accomplish]
+
+## Constraints & Preferences
+[User preferences, coding style, constraints, important decisions]
+
+## Completed Actions
+[Numbered list of concrete actions taken — include tool used, target, and outcome.
+Format each as: N. ACTION target — outcome [tool: name]
+Example:
+1. READ config.py:45 — found `==` should be `!=` [tool: read_file]
+2. PATCH config.py:45 — changed `==` to `!=` [tool: patch]
+3. TEST `pytest tests/` — 3/50 failed: test_parse, test_validate, test_edge [tool: terminal]
+Be specific with file paths, commands, line numbers, and results.]
+
+## Active State
+[Current working state — include:
+- Working directory and branch (if applicable)
+- Modified/created files with brief note on each
+- Test status (X/Y passing)
+- Any running processes or servers
+- Environment details that matter]
+
+## In Progress
+[Work currently underway — what was being done when compaction fired]
+
+## Blocked
+[Any blockers, errors, or issues not yet resolved. Include exact error messages.]
+
+## Key Decisions
+[Important technical decisions and WHY they were made]
+
+## Resolved Questions
+[Questions the user asked that were ALREADY answered — include the answer so the next assistant does not re-answer them]
+
+## Pending User Asks
+[Questions or requests from the user that have NOT yet been answered or fulfilled. If none, write "None."]
+
+## Relevant Files
+[Files read, modified, or created — with brief note on each]
+
+## Remaining Work
+[What remains to be done — framed as context, not instructions]
+
+## Critical Context
+[Any specific values, error messages, configuration details, or data that would be lost without explicit preservation]
+
+Target ~{summary_budget} tokens. Be CONCRETE — include file paths, command outputs, error messages, line numbers, and specific values. Avoid vague descriptions like "made some changes" — say exactly what changed.
+
+Write only the summary body. Do not include any preamble or prefix."""
+
         if self._previous_summary:
             # Iterative update: preserve existing info, add new progress
-            prompt = f"""You are updating a context compaction summary. A previous compaction produced the summary below. New conversation turns have occurred since then and need to be incorporated.
+            prompt = f"""{_summarizer_preamble}
+
+You are updating a context compaction summary. A previous compaction produced the summary below. New conversation turns have occurred since then and need to be incorporated.
 
 PREVIOUS SUMMARY:
 {self._previous_summary}
@@ -282,81 +644,42 @@ PREVIOUS SUMMARY:
 NEW TURNS TO INCORPORATE:
 {content_to_summarize}
 
-Update the summary using this exact structure. PRESERVE all existing information that is still relevant. ADD new progress. Move items from "In Progress" to "Done" when completed. Remove information only if it is clearly obsolete.
+Update the summary using this exact structure. PRESERVE all existing information that is still relevant. ADD new completed actions to the numbered list (continue numbering). Move items from "In Progress" to "Completed Actions" when done. Move answered questions to "Resolved Questions". Update "Active State" to reflect current state. Remove information only if it is clearly obsolete.
 
-## Goal
-[What the user is trying to accomplish — preserve from previous summary, update if goal evolved]
-
-## Constraints & Preferences
-[User preferences, coding style, constraints, important decisions — accumulate across compactions]
-
-## Progress
-### Done
-[Completed work — include specific file paths, commands run, results obtained]
-### In Progress
-[Work currently underway]
-### Blocked
-[Any blockers or issues encountered]
-
-## Key Decisions
-[Important technical decisions and why they were made]
-
-## Relevant Files
-[Files read, modified, or created — with brief note on each. Accumulate across compactions.]
-
-## Next Steps
-[What needs to happen next to continue the work]
-
-## Critical Context
-[Any specific values, error messages, configuration details, or data that would be lost without explicit preservation]
-
-Target ~{summary_budget} tokens. Be specific — include file paths, command outputs, error messages, and concrete values rather than vague descriptions.
-
-Write only the summary body. Do not include any preamble or prefix."""
+{_template_sections}"""
         else:
             # First compaction: summarize from scratch
-            prompt = f"""Create a structured handoff summary for a later assistant that will continue this conversation after earlier turns are compacted.
+            prompt = f"""{_summarizer_preamble}
+
+Create a structured handoff summary for a different assistant that will continue this conversation after earlier turns are compacted. The next assistant should be able to understand what happened without re-reading the original turns.
 
 TURNS TO SUMMARIZE:
 {content_to_summarize}
 
 Use this exact structure:
 
-## Goal
-[What the user is trying to accomplish]
+{_template_sections}"""
 
-## Constraints & Preferences
-[User preferences, coding style, constraints, important decisions]
+        # Inject focus topic guidance when the user provides one via /compress <focus>.
+        # This goes at the end of the prompt so it takes precedence.
+        if focus_topic:
+            prompt += f"""
 
-## Progress
-### Done
-[Completed work — include specific file paths, commands run, results obtained]
-### In Progress
-[Work currently underway]
-### Blocked
-[Any blockers or issues encountered]
-
-## Key Decisions
-[Important technical decisions and why they were made]
-
-## Relevant Files
-[Files read, modified, or created — with brief note on each]
-
-## Next Steps
-[What needs to happen next to continue the work]
-
-## Critical Context
-[Any specific values, error messages, configuration details, or data that would be lost without explicit preservation]
-
-Target ~{summary_budget} tokens. Be specific — include file paths, command outputs, error messages, and concrete values rather than vague descriptions. The goal is to prevent the next assistant from repeating work or losing important details.
-
-Write only the summary body. Do not include any preamble or prefix."""
+FOCUS TOPIC: "{focus_topic}"
+The user has requested that this compaction PRIORITISE preserving all information related to the focus topic above. For content related to "{focus_topic}", include full detail — exact values, file paths, command outputs, error messages, and decisions. For content NOT related to the focus topic, summarise more aggressively (brief one-liners or omit if truly irrelevant). The focus topic sections should receive roughly 60-70% of the summary token budget."""
 
         try:
             call_kwargs = {
                 "task": "compression",
+                "main_runtime": {
+                    "model": self.model,
+                    "provider": self.provider,
+                    "base_url": self.base_url,
+                    "api_key": self.api_key,
+                    "api_mode": self.api_mode,
+                },
                 "messages": [{"role": "user", "content": prompt}],
-                "max_tokens": summary_budget * 2,
+                "max_tokens": int(summary_budget * 1.3),
                 # timeout resolved from auxiliary.compression.timeout config by call_llm
             }
             if self.summary_model:
@@ -370,8 +693,10 @@ Write only the summary body. Do not include any preamble or prefix."""
             # Store for iterative updates on next compaction
             self._previous_summary = summary
             self._summary_failure_cooldown_until = 0.0
+            self._summary_model_fallen_back = False
             return self._with_summary_prefix(summary)
         except RuntimeError:
+            # No provider configured — long cooldown, unlikely to self-resolve
             self._summary_failure_cooldown_until = time.monotonic() + _SUMMARY_FAILURE_COOLDOWN_SECONDS
             logging.warning("Context compression: no provider available for "
                             "summary. Middle turns will be dropped without summary "
@@ -379,12 +704,42 @@ Write only the summary body. Do not include any preamble or prefix."""
                             _SUMMARY_FAILURE_COOLDOWN_SECONDS)
             return None
         except Exception as e:
-            self._summary_failure_cooldown_until = time.monotonic() + _SUMMARY_FAILURE_COOLDOWN_SECONDS
+            # If the summary model is different from the main model and the
+            # error looks permanent (model not found, 503, 404), fall back to
+            # using the main model instead of entering cooldown that leaves
+            # context growing unbounded.  (#8620 sub-issue 4)
+            _status = getattr(e, "status_code", None) or getattr(getattr(e, "response", None), "status_code", None)
+            _err_str = str(e).lower()
+            _is_model_not_found = (
+                _status in (404, 503)
+                or "model_not_found" in _err_str
+                or "does not exist" in _err_str
+                or "no available channel" in _err_str
+            )
+            if (
+                _is_model_not_found
+                and self.summary_model
+                and self.summary_model != self.model
+                and not getattr(self, "_summary_model_fallen_back", False)
+            ):
+                self._summary_model_fallen_back = True
+                logging.warning(
+                    "Summary model '%s' not available (%s). "
+                    "Falling back to main model '%s' for compression.",
+                    self.summary_model, e, self.model,
+                )
+                self.summary_model = ""  # empty = use main model
+                self._summary_failure_cooldown_until = 0.0  # no cooldown
+                return self._generate_summary(messages, summary_budget)  # retry immediately
+
+            # Transient errors (timeout, rate limit, network) — shorter cooldown
+            _transient_cooldown = 60
+            self._summary_failure_cooldown_until = time.monotonic() + _transient_cooldown
             logging.warning(
                 "Failed to generate context summary: %s. "
                 "Further summary attempts paused for %d seconds.",
                 e,
-                _SUMMARY_FAILURE_COOLDOWN_SECONDS,
+                _transient_cooldown,
             )
             return None
 
@@ -518,13 +873,20 @@ Write only the summary body. Do not include any preamble or prefix."""
         derived from ``summary_target_ratio * context_length``, so it
         scales automatically with the model's context window.
 
-        Never cuts inside a tool_call/result group. Falls back to the old
-        ``protect_last_n`` if the budget would protect fewer messages.
+        Token budget is the primary criterion.  A hard minimum of 3 messages
+        is always protected, but the budget is allowed to exceed by up to
+        1.5x to avoid cutting inside an oversized message (tool output, file
+        read, etc.).  If even the minimum 3 messages exceed 1.5x the budget
+        the cut is placed right after the head so compression still runs.
+
+        Never cuts inside a tool_call/result group.
         """
         if token_budget is None:
             token_budget = self.tail_token_budget
         n = len(messages)
-        min_tail = self.protect_last_n
+        # Hard minimum: always keep at least 3 messages in the tail
+        min_tail = min(3, n - head_end - 1) if n - head_end > 1 else 0
+        soft_ceiling = int(token_budget * 1.5)
         accumulated = 0
         cut_idx = n  # start from beyond the end
 
@@ -537,21 +899,21 @@ Write only the summary body. Do not include any preamble or prefix."""
                 if isinstance(tc, dict):
                     args = tc.get("function", {}).get("arguments", "")
                     msg_tokens += len(args) // _CHARS_PER_TOKEN
-            if accumulated + msg_tokens > token_budget and (n - i) >= min_tail:
+            # Stop once we exceed the soft ceiling (unless we haven't hit min_tail yet)
+            if accumulated + msg_tokens > soft_ceiling and (n - i) >= min_tail:
                 break
             accumulated += msg_tokens
             cut_idx = i
 
-        # Ensure we protect at least protect_last_n messages
+        # Ensure we protect at least min_tail messages
         fallback_cut = n - min_tail
         if cut_idx > fallback_cut:
             cut_idx = fallback_cut
 
         # If the token budget would protect everything (small conversations),
-        # fall back to the fixed protect_last_n approach so compression can
-        # still remove middle turns.
+        # force a cut after the head so compression can still remove middle turns.
         if cut_idx <= head_end:
-            cut_idx = fallback_cut
+            cut_idx = max(fallback_cut, head_end + 1)
 
         # Align to avoid splitting tool groups
         cut_idx = self._align_boundary_backward(messages, cut_idx)
@@ -562,7 +924,7 @@ Write only the summary body. Do not include any preamble or prefix."""
     # Main compression entry point
     # ------------------------------------------------------------------
 
-    def compress(self, messages: List[Dict[str, Any]], current_tokens: int = None) -> List[Dict[str, Any]]:
+    def compress(self, messages: List[Dict[str, Any]], current_tokens: int = None, focus_topic: str = None) -> List[Dict[str, Any]]:
         """Compress conversation messages by summarizing middle turns.
 
         Algorithm:
@@ -574,14 +936,21 @@ Write only the summary body. Do not include any preamble or prefix."""
 
         After compression, orphaned tool_call / tool_result pairs are cleaned
         up so the API never receives mismatched IDs.
+
+        Args:
+            focus_topic: Optional focus string for guided compression.  When
+                provided, the summariser will prioritise preserving information
+                related to this topic and be more aggressive about compressing
+                everything else.  Inspired by Claude Code's ``/compact``.
         """
         n_messages = len(messages)
-        if n_messages <= self.protect_first_n + self.protect_last_n + 1:
+        # Only need head + 3 tail messages minimum (token budget decides the real tail size)
+        _min_for_compress = self.protect_first_n + 3 + 1
+        if n_messages <= _min_for_compress:
             if not self.quiet_mode:
                 logger.warning(
                     "Cannot compress: only %d messages (need > %d)",
-                    n_messages,
-                    self.protect_first_n + self.protect_last_n + 1,
+                    n_messages, _min_for_compress,
                 )
             return messages
 
@@ -589,7 +958,8 @@ Write only the summary body. Do not include any preamble or prefix."""
 
         # Phase 1: Prune old tool results (cheap, no LLM call)
         messages, pruned_count = self._prune_old_tool_results(
-            messages, protect_tail_count=self.protect_last_n * 3,
+            messages, protect_tail_count=self.protect_last_n,
+            protect_tail_tokens=self.tail_token_budget,
         )
         if pruned_count and not self.quiet_mode:
             logger.info("Pre-compression: pruned %d old tool result(s)", pruned_count)
@@ -629,52 +999,67 @@ Write only the summary body. Do not include any preamble or prefix."""
             )
 
         # Phase 3: Generate structured summary
-        summary = self._generate_summary(turns_to_summarize)
+        summary = self._generate_summary(turns_to_summarize, focus_topic=focus_topic)
 
         # Phase 4: Assemble compressed message list
         compressed = []
         for i in range(compress_start):
             msg = messages[i].copy()
-            if i == 0 and msg.get("role") == "system" and self.compression_count == 0:
-                msg["content"] = (
-                    (msg.get("content") or "")
-                    + "\n\n[Note: Some earlier conversation turns have been compacted into a handoff summary to preserve context space. The current session state may still reflect earlier work, so build on that summary and state rather than re-doing work.]"
-                )
+            if i == 0 and msg.get("role") == "system":
+                existing = msg.get("content") or ""
+                _compression_note = "[Note: Some earlier conversation turns have been compacted into a handoff summary to preserve context space. The current session state may still reflect earlier work, so build on that summary and state rather than re-doing work.]"
+                if _compression_note not in existing:
+                    msg["content"] = existing + "\n\n" + _compression_note
             compressed.append(msg)
 
-        _merge_summary_into_tail = False
-        if summary:
-            last_head_role = messages[compress_start - 1].get("role", "user") if compress_start > 0 else "user"
-            first_tail_role = messages[compress_end].get("role", "user") if compress_end < n_messages else "user"
-            # Pick a role that avoids consecutive same-role with both neighbors.
-            # Priority: avoid colliding with head (already committed), then tail.
-            if last_head_role in ("assistant", "tool"):
-                summary_role = "user"
-            else:
-                summary_role = "assistant"
-            # If the chosen role collides with the tail AND flipping wouldn't
-            # collide with the head, flip it.
-            if summary_role == first_tail_role:
-                flipped = "assistant" if summary_role == "user" else "user"
-                if flipped != last_head_role:
-                    summary_role = flipped
-                else:
-                    # Both roles would create consecutive same-role messages
-                    # (e.g. head=assistant, tail=user — neither role works).
-                    # Merge the summary into the first tail message instead
-                    # of inserting a standalone message that breaks alternation.
-                    _merge_summary_into_tail = True
-            if not _merge_summary_into_tail:
-                compressed.append({"role": summary_role, "content": summary})
-        else:
+        # If LLM summary failed, insert a static fallback so the model
+        # knows context was lost rather than silently dropping everything.
+        if not summary:
             if not self.quiet_mode:
-                logger.debug("No summary model available — middle turns dropped without summary")
+                logger.warning("Summary generation failed — inserting static fallback context marker")
+            n_dropped = compress_end - compress_start
+            summary = (
+                f"{SUMMARY_PREFIX}\n"
+                f"Summary generation was unavailable. {n_dropped} conversation turns were "
+                f"removed to free context space but could not be summarized. The removed "
+                f"turns contained earlier work in this session. Continue based on the "
+                f"recent messages below and the current state of any files or resources."
+            )
+
+        _merge_summary_into_tail = False
+        last_head_role = messages[compress_start - 1].get("role", "user") if compress_start > 0 else "user"
+        first_tail_role = messages[compress_end].get("role", "user") if compress_end < n_messages else "user"
+        # Pick a role that avoids consecutive same-role with both neighbors.
+        # Priority: avoid colliding with head (already committed), then tail.
+        if last_head_role in ("assistant", "tool"):
+            summary_role = "user"
+        else:
+            summary_role = "assistant"
+        # If the chosen role collides with the tail AND flipping wouldn't
+        # collide with the head, flip it.
+        if summary_role == first_tail_role:
+            flipped = "assistant" if summary_role == "user" else "user"
+            if flipped != last_head_role:
+                summary_role = flipped
+            else:
+                # Both roles would create consecutive same-role messages
+                # (e.g. head=assistant, tail=user — neither role works).
+                # Merge the summary into the first tail message instead
+                # of inserting a standalone message that breaks alternation.
+                _merge_summary_into_tail = True
+        if not _merge_summary_into_tail:
+            compressed.append({"role": summary_role, "content": summary})
 
         for i in range(compress_end, n_messages):
             msg = messages[i].copy()
             if _merge_summary_into_tail and i == compress_end:
                 original = msg.get("content") or ""
-                msg["content"] = summary + "\n\n" + original
+                msg["content"] = (
+                    summary
+                    + "\n\n--- END OF CONTEXT SUMMARY — "
+                    "respond to the message below, not the summary above ---\n\n"
+                    + original
+                )
                 _merge_summary_into_tail = False
             compressed.append(msg)
 
@@ -682,14 +1067,24 @@ Write only the summary body. Do not include any preamble or prefix."""
 
         compressed = self._sanitize_tool_pairs(compressed)
 
+        new_estimate = estimate_messages_tokens_rough(compressed)
+        saved_estimate = display_tokens - new_estimate
+
+        # Anti-thrashing: track compression effectiveness
+        savings_pct = (saved_estimate / display_tokens * 100) if display_tokens > 0 else 0
+        self._last_compression_savings_pct = savings_pct
+        if savings_pct < 10:
+            self._ineffective_compression_count += 1
+        else:
+            self._ineffective_compression_count = 0
+
         if not self.quiet_mode:
-            new_estimate = estimate_messages_tokens_rough(compressed)
-            saved_estimate = display_tokens - new_estimate
             logger.info(
-                "Compressed: %d -> %d messages (~%d tokens saved)",
+                "Compressed: %d -> %d messages (~%d tokens saved, %.0f%%)",
                 n_messages,
                 len(compressed),
                 saved_estimate,
+                savings_pct,
             )
             logger.info("Compression #%d complete", self.compression_count)
 

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,8 +13,9 @@ 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", ".docker", ".azure", ".config/gh")
@@ -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/credential_pool.py

@@ -10,24 +10,26 @@ import uuid
 import os
 import re
 from dataclasses import dataclass, fields, replace
-from datetime import datetime, timezone
+from datetime import datetime
 from typing import Any, Dict, List, Optional, Set, Tuple
 
 from hermes_constants import OPENROUTER_BASE_URL
 import hermes_cli.auth as auth_mod
 from hermes_cli.auth import (
-    ACCESS_TOKEN_REFRESH_SKEW_SECONDS,
     CODEX_ACCESS_TOKEN_REFRESH_SKEW_SECONDS,
     DEFAULT_AGENT_KEY_MIN_TTL_SECONDS,
     PROVIDER_REGISTRY,
-    _agent_key_is_usable,
+    _auth_store_lock,
     _codex_access_token_is_expiring,
     _decode_jwt_claims,
     _import_codex_cli_tokens,
-    _is_expiring,
+    _write_codex_cli_tokens,
     _load_auth_store,
     _load_provider_state,
+    _resolve_kimi_base_url,
     _resolve_zai_base_url,
+    _save_auth_store,
+    _save_provider_state,
     read_credential_pool,
     write_credential_pool,
 )
@@ -67,10 +69,10 @@ SUPPORTED_POOL_STRATEGIES = {
 }
 
 # Cooldown before retrying an exhausted credential.
-# 429 (rate-limited) cools down faster since quotas reset frequently.
-# 402 (billing/quota) and other codes use a longer default.
+# 429 (rate-limited) and 402 (billing/quota) both cool down after 1 hour.
+# Provider-supplied reset_at timestamps override these defaults.
 EXHAUSTED_TTL_429_SECONDS = 60 * 60          # 1 hour
-EXHAUSTED_TTL_DEFAULT_SECONDS = 24 * 60 * 60 # 24 hours
+EXHAUSTED_TTL_DEFAULT_SECONDS = 60 * 60      # 1 hour
 
 # Pool key prefix for custom OpenAI-compatible endpoints.
 # Custom endpoints all share provider='custom' but are keyed by their
@@ -286,6 +288,14 @@ def _iter_custom_providers(config: Optional[dict] = None):
         return
     custom_providers = config.get("custom_providers")
     if not isinstance(custom_providers, list):
+        # Fall back to the v12+ providers dict via the compatibility layer
+        try:
+            from hermes_cli.config import get_compatible_custom_providers
+
+            custom_providers = get_compatible_custom_providers(config)
+        except Exception:
+            return
+    if not custom_providers:
         return
     for entry in custom_providers:
         if not isinstance(entry, dict):
@@ -480,6 +490,67 @@ class CredentialPool:
             logger.debug("Failed to sync from ~/.codex/auth.json: %s", exc)
         return entry
 
+    def _sync_device_code_entry_to_auth_store(self, entry: PooledCredential) -> None:
+        """Write refreshed pool entry tokens back to auth.json providers.
+
+        After a pool-level refresh, the pool entry has fresh tokens but
+        auth.json's ``providers.<id>`` still holds the pre-refresh state.
+        On the next ``load_pool()``, ``_seed_from_singletons()`` reads that
+        stale state and can overwrite the fresh pool entry — potentially
+        re-seeding a consumed single-use refresh token.
+
+        Applies to any OAuth provider whose singleton lives in auth.json
+        (currently Nous and OpenAI Codex).
+        """
+        if entry.source != "device_code":
+            return
+        try:
+            with _auth_store_lock():
+                auth_store = _load_auth_store()
+                if self.provider == "nous":
+                    state = _load_provider_state(auth_store, "nous")
+                    if state is None:
+                        return
+                    state["access_token"] = entry.access_token
+                    if entry.refresh_token:
+                        state["refresh_token"] = entry.refresh_token
+                    if entry.expires_at:
+                        state["expires_at"] = entry.expires_at
+                    if entry.agent_key:
+                        state["agent_key"] = entry.agent_key
+                    if entry.agent_key_expires_at:
+                        state["agent_key_expires_at"] = entry.agent_key_expires_at
+                    for extra_key in ("obtained_at", "expires_in", "agent_key_id",
+                                      "agent_key_expires_in", "agent_key_reused",
+                                      "agent_key_obtained_at"):
+                        val = entry.extra.get(extra_key)
+                        if val is not None:
+                            state[extra_key] = val
+                    if entry.inference_base_url:
+                        state["inference_base_url"] = entry.inference_base_url
+                    _save_provider_state(auth_store, "nous", state)
+
+                elif self.provider == "openai-codex":
+                    state = _load_provider_state(auth_store, "openai-codex")
+                    if not isinstance(state, dict):
+                        return
+                    tokens = state.get("tokens")
+                    if not isinstance(tokens, dict):
+                        return
+                    tokens["access_token"] = entry.access_token
+                    if entry.refresh_token:
+                        tokens["refresh_token"] = entry.refresh_token
+                    if entry.last_refresh:
+                        state["last_refresh"] = entry.last_refresh
+                    _save_provider_state(auth_store, "openai-codex", state)
+
+                else:
+                    return
+
+                _save_auth_store(auth_store)
+        except Exception as exc:
+            logger.debug("Failed to sync %s pool entry back to auth store: %s", self.provider, exc)
+
     def _refresh_entry(self, entry: PooledCredential, *, force: bool) -> Optional[PooledCredential]:
         if entry.auth_type != AUTH_TYPE_OAUTH or not entry.refresh_token:
             if force:
@@ -514,6 +585,13 @@ class CredentialPool:
                     except Exception as wexc:
                         logger.debug("Failed to write refreshed token to credentials file: %s", wexc)
             elif self.provider == "openai-codex":
+                # Proactively sync from ~/.codex/auth.json before refresh.
+                # The Codex CLI (or another Hermes profile) may have already
+                # consumed our refresh_token.  Syncing first avoids a
+                # "refresh_token_reused" error when the CLI has a newer pair.
+                synced = self._sync_codex_entry_from_cli(entry)
+                if synced is not entry:
+                    entry = synced
                 refreshed = auth_mod.refresh_codex_oauth_pure(
                     entry.access_token,
                     entry.refresh_token,
@@ -599,6 +677,45 @@ class CredentialPool:
                     # Credentials file had a valid (non-expired) token — use it directly
                     logger.debug("Credentials file has valid token, using without refresh")
                     return synced
+            # For openai-codex: the refresh_token may have been consumed by
+            # the Codex CLI between our proactive sync and the refresh call.
+            # Re-sync and retry once.
+            if self.provider == "openai-codex":
+                synced = self._sync_codex_entry_from_cli(entry)
+                if synced.refresh_token != entry.refresh_token:
+                    logger.debug("Retrying Codex refresh with synced token from ~/.codex/auth.json")
+                    try:
+                        refreshed = auth_mod.refresh_codex_oauth_pure(
+                            synced.access_token,
+                            synced.refresh_token,
+                        )
+                        updated = replace(
+                            synced,
+                            access_token=refreshed["access_token"],
+                            refresh_token=refreshed["refresh_token"],
+                            last_refresh=refreshed.get("last_refresh"),
+                            last_status=STATUS_OK,
+                            last_status_at=None,
+                            last_error_code=None,
+                        )
+                        self._replace_entry(synced, updated)
+                        self._persist()
+                        self._sync_device_code_entry_to_auth_store(updated)
+                        try:
+                            _write_codex_cli_tokens(
+                                updated.access_token,
+                                updated.refresh_token,
+                                last_refresh=updated.last_refresh,
+                            )
+                        except Exception as wexc:
+                            logger.debug("Failed to write refreshed Codex tokens to CLI file (retry): %s", wexc)
+                        return updated
+                    except Exception as retry_exc:
+                        logger.debug("Codex retry refresh also failed: %s", retry_exc)
+                elif not self._entry_needs_refresh(synced):
+                    logger.debug("Codex CLI has valid token, using without refresh")
+                    self._sync_device_code_entry_to_auth_store(synced)
+                    return synced
             self._mark_exhausted(entry, None)
             return None
 
@@ -613,6 +730,21 @@ class CredentialPool:
         )
         self._replace_entry(entry, updated)
         self._persist()
+        # Sync refreshed tokens back to auth.json providers so that
+        # _seed_from_singletons() on the next load_pool() sees fresh state
+        # instead of re-seeding stale/consumed tokens.
+        self._sync_device_code_entry_to_auth_store(updated)
+        # Write refreshed tokens back to ~/.codex/auth.json so Codex CLI
+        # and VS Code don't hit "refresh_token_reused" on their next refresh.
+        if self.provider == "openai-codex":
+            try:
+                _write_codex_cli_tokens(
+                    updated.access_token,
+                    updated.refresh_token,
+                    last_refresh=updated.last_refresh,
+                )
+            except Exception as wexc:
+                logger.debug("Failed to write refreshed Codex tokens to CLI file: %s", wexc)
         return updated
 
     def _entry_needs_refresh(self, entry: PooledCredential) -> bool:
@@ -634,17 +766,6 @@ class CredentialPool:
             return False
         return False
 
-    def mark_used(self, entry_id: Optional[str] = None) -> None:
-        """Increment request_count for tracking. Used by least_used strategy."""
-        target_id = entry_id or self._current_id
-        if not target_id:
-            return
-        with self._lock:
-            for idx, entry in enumerate(self._entries):
-                if entry.id == target_id:
-                    self._entries[idx] = replace(entry, request_count=entry.request_count + 1)
-                    return
-
     def select(self) -> Optional[PooledCredential]:
         with self._lock:
             return self._select_unlocked()
@@ -806,11 +927,6 @@ class CredentialPool:
             else:
                 self._active_leases[credential_id] = count - 1
 
-    def active_lease_count(self, credential_id: str) -> int:
-        """Return the number of active leases for a credential."""
-        with self._lock:
-            return self._active_leases.get(credential_id, 0)
-
     def try_refresh_current(self) -> Optional[PooledCredential]:
         with self._lock:
             return self._try_refresh_current_unlocked()
@@ -970,6 +1086,17 @@ def _seed_from_singletons(provider: str, entries: List[PooledCredential]) -> Tup
     auth_store = _load_auth_store()
 
     if provider == "anthropic":
+        # Only auto-discover external credentials (Claude Code, Hermes PKCE)
+        # when the user has explicitly configured anthropic as their provider.
+        # Without this gate, auxiliary client fallback chains silently read
+        # ~/.claude/.credentials.json without user consent.  See PR #4210.
+        try:
+            from hermes_cli.auth import is_provider_explicitly_configured
+            if not is_provider_explicitly_configured("anthropic"):
+                return changed, active_sources
+        except ImportError:
+            pass
+
         from agent.anthropic_adapter import read_claude_code_credentials, read_hermes_oauth_credentials
 
         for source_name, creds in (
@@ -977,6 +1104,13 @@ def _seed_from_singletons(provider: str, entries: List[PooledCredential]) -> Tup
             ("claude_code", read_claude_code_credentials()),
         ):
             if creds and creds.get("accessToken"):
+                # Check if user explicitly removed this source
+                try:
+                    from hermes_cli.auth import is_source_suppressed
+                    if is_source_suppressed(provider, source_name):
+                        continue
+                except ImportError:
+                    pass
                 active_sources.add(source_name)
                 changed |= _upsert_entry(
                     entries,
@@ -1018,9 +1152,79 @@ def _seed_from_singletons(provider: str, entries: List[PooledCredential]) -> Tup
                 },
             )
 
+    elif provider == "copilot":
+        # Copilot tokens are resolved dynamically via `gh auth token` or
+        # env vars (COPILOT_GITHUB_TOKEN / GH_TOKEN).  They don't live in
+        # the auth store or credential pool, so we resolve them here.
+        try:
+            from hermes_cli.copilot_auth import resolve_copilot_token
+            token, source = resolve_copilot_token()
+            if token:
+                source_name = "gh_cli" if "gh" in source.lower() else f"env:{source}"
+                active_sources.add(source_name)
+                changed |= _upsert_entry(
+                    entries,
+                    provider,
+                    source_name,
+                    {
+                        "source": source_name,
+                        "auth_type": AUTH_TYPE_API_KEY,
+                        "access_token": token,
+                        "label": source,
+                    },
+                )
+        except Exception as exc:
+            logger.debug("Copilot token seed failed: %s", exc)
+
+    elif provider == "qwen-oauth":
+        # Qwen OAuth tokens live in ~/.qwen/oauth_creds.json, written by
+        # the Qwen CLI (`qwen auth qwen-oauth`).  They aren't in the
+        # Hermes auth store or env vars, so resolve them here.
+        # Use refresh_if_expiring=False to avoid network calls during
+        # pool loading / provider discovery.
+        try:
+            from hermes_cli.auth import resolve_qwen_runtime_credentials
+            creds = resolve_qwen_runtime_credentials(refresh_if_expiring=False)
+            token = creds.get("api_key", "")
+            if token:
+                source_name = creds.get("source", "qwen-cli")
+                active_sources.add(source_name)
+                changed |= _upsert_entry(
+                    entries,
+                    provider,
+                    source_name,
+                    {
+                        "source": source_name,
+                        "auth_type": AUTH_TYPE_OAUTH,
+                        "access_token": token,
+                        "expires_at_ms": creds.get("expires_at_ms"),
+                        "base_url": creds.get("base_url", ""),
+                        "label": creds.get("auth_file", source_name),
+                    },
+                )
+        except Exception as exc:
+            logger.debug("Qwen OAuth token seed failed: %s", exc)
+
     elif provider == "openai-codex":
         state = _load_provider_state(auth_store, "openai-codex")
         tokens = state.get("tokens") if isinstance(state, dict) else None
+        # Fallback: import from Codex CLI (~/.codex/auth.json) if Hermes auth
+        # store has no tokens.  This mirrors resolve_codex_runtime_credentials()
+        # so that load_pool() and list_authenticated_providers() detect tokens
+        # that only exist in the Codex CLI shared file.
+        if not (isinstance(tokens, dict) and tokens.get("access_token")):
+            try:
+                from hermes_cli.auth import _import_codex_cli_tokens, _save_codex_tokens
+                cli_tokens = _import_codex_cli_tokens()
+                if cli_tokens:
+                    logger.info("Importing Codex CLI tokens into Hermes auth store.")
+                    _save_codex_tokens(cli_tokens)
+                    # Re-read state after import
+                    auth_store = _load_auth_store()
+                    state = _load_provider_state(auth_store, "openai-codex")
+                    tokens = state.get("tokens") if isinstance(state, dict) else None
+            except Exception as exc:
+                logger.debug("Codex CLI token import failed: %s", exc)
         if isinstance(tokens, dict) and tokens.get("access_token"):
             active_sources.add("device_code")
             changed |= _upsert_entry(
@@ -1087,7 +1291,9 @@ def _seed_from_env(provider: str, entries: List[PooledCredential]) -> Tuple[bool
         active_sources.add(source)
         auth_type = AUTH_TYPE_OAUTH if provider == "anthropic" and not token.startswith("sk-ant-api") else AUTH_TYPE_API_KEY
         base_url = env_url or pconfig.inference_base_url
-        if provider == "zai":
+        if provider == "kimi-coding":
+            base_url = _resolve_kimi_base_url(token, pconfig.inference_base_url, env_url)
+        elif provider == "zai":
             base_url = _resolve_zai_base_url(token, pconfig.inference_base_url, env_url)
         changed |= _upsert_entry(
             entries,

agent/display.py

@@ -4,7 +4,6 @@ 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
@@ -14,6 +13,8 @@ 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"
 _RESET = "\033[0m"
@@ -21,11 +22,67 @@ _RESET = "\033[0m"
 logger = logging.getLogger(__name__)
 
 _ANSI_RESET = "\033[0m"
-_ANSI_DIM = "\033[38;2;150;150;150m"
-_ANSI_FILE = "\033[38;2;180;160;255m"
-_ANSI_HUNK = "\033[38;2;120;120;140m"
-_ANSI_MINUS = "\033[38;2;255;255;255;48;2;120;20;20m"
-_ANSI_PLUS = "\033[38;2;255;255;255;48;2;20;90;20m"
+
+# 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
 
@@ -67,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()
@@ -330,9 +367,8 @@ def _result_succeeded(result: str | None) -> bool:
     """Conservatively detect whether a tool result represents success."""
     if not result:
         return False
-    try:
-        data = json.loads(result)
-    except (json.JSONDecodeError, TypeError):
+    data = safe_json_loads(result)
+    if data is None:
         return False
     if not isinstance(data, dict):
         return False
@@ -381,10 +417,7 @@ def extract_edit_diff(
 ) -> str | None:
     """Extract a unified diff from a file-edit tool result."""
     if tool_name == "patch" and result:
-        try:
-            data = json.loads(result)
-        except (json.JSONDecodeError, TypeError):
-            data = None
+        data = safe_json_loads(result)
         if isinstance(data, dict):
             diff = data.get("diff")
             if isinstance(diff, str) and diff.strip():
@@ -423,19 +456,19 @@ def _render_inline_unified_diff(diff: str) -> list[str]:
         if raw_line.startswith("+++ "):
             to_file = raw_line[4:].strip()
             if from_file or to_file:
-                rendered.append(f"{_ANSI_FILE}{from_file or 'a/?'} → {to_file or 'b/?'}{_ANSI_RESET}")
+                rendered.append(f"{_diff_file()}{from_file or 'a/?'} → {to_file or 'b/?'}{_ANSI_RESET}")
             continue
         if raw_line.startswith("@@"):
-            rendered.append(f"{_ANSI_HUNK}{raw_line}{_ANSI_RESET}")
+            rendered.append(f"{_diff_hunk()}{raw_line}{_ANSI_RESET}")
             continue
         if raw_line.startswith("-"):
-            rendered.append(f"{_ANSI_MINUS}{raw_line}{_ANSI_RESET}")
+            rendered.append(f"{_diff_minus()}{raw_line}{_ANSI_RESET}")
             continue
         if raw_line.startswith("+"):
-            rendered.append(f"{_ANSI_PLUS}{raw_line}{_ANSI_RESET}")
+            rendered.append(f"{_diff_plus()}{raw_line}{_ANSI_RESET}")
             continue
         if raw_line.startswith(" "):
-            rendered.append(f"{_ANSI_DIM}{raw_line}{_ANSI_RESET}")
+            rendered.append(f"{_diff_dim()}{raw_line}{_ANSI_RESET}")
             continue
         if raw_line:
             rendered.append(raw_line)
@@ -501,7 +534,7 @@ def _summarize_rendered_diff_sections(
         summary = f"… omitted {omitted_lines} diff line(s)"
         if omitted_files:
             summary += f" across {omitted_files} additional file(s)/section(s)"
-        rendered.append(f"{_ANSI_HUNK}{summary}{_ANSI_RESET}")
+        rendered.append(f"{_diff_hunk()}{summary}{_ANSI_RESET}")
 
     return rendered
 
@@ -723,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)
 # =========================================================================
@@ -778,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()
@@ -970,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/input_sanitizer.py

@@ -1,635 +0,0 @@
-"""
-Input Sanitizer for Jailbreak Pattern Detection
-
-This module provides input sanitization to detect and strip jailbreak fingerprint
-patterns as identified in Issue #72 (Red Team Audit).
-
-Security Findings Addressed:
-1. HIGH - OG GODMODE template bypassed phishing refusal
-2. MEDIUM - boundary_inversion works for gray-area content
-3. LOW - Spaced text bypass (k e y l o g g e r)
-
-Usage:
-    from agent.input_sanitizer import sanitize_input, score_input_risk
-    
-    cleaned, risk_score, detected = sanitize_input(user_input)
-    if risk_score > 75:
-        logger.warning("High-risk input detected and blocked")
-"""
-
-import re
-import logging
-from typing import Tuple, List, Dict, Any, Optional
-from dataclasses import dataclass
-from enum import IntEnum
-
-logger = logging.getLogger(__name__)
-
-
-class RiskLevel(IntEnum):
-    """Risk score thresholds for input classification."""
-    LOW = 25
-    MEDIUM = 50
-    HIGH = 75
-    CRITICAL = 90
-
-
-@dataclass
-class SanitizationResult:
-    """Result of input sanitization."""
-    original_text: str
-    cleaned_text: str
-    risk_score: int
-    detected_patterns: List[str]
-    risk_level: str
-    blocked: bool
-
-
-# =============================================================================
-# JAILBREAK PATTERN DEFINITIONS
-# =============================================================================
-
-# GODMODE and similar jailbreak templates
-GODMODE_PATTERNS = [
-    r"\[START\]",
-    r"\[END\]",
-    r"GODMODE\s*(?:ENABLED|ACTIVATED|ON)?",
-    r"UNFILTERED\s*(?:MODE|OUTPUT)?",
-    r"DEVMODE\s*(?:ENABLED|ACTIVATED|ON)?",
-    r"JAILBREAK\s*(?:ENABLED|ACTIVATED|ON)?",
-    r"DAN\s*(?:MODE|ENABLED)?",  # Do Anything Now
-    r"STAN\s*(?:MODE|ENABLED)?",  # Strive To Avoid Norms
-    r"DUDE\s*(?:MODE|ENABLED)?",  # Do Unlimited Data Extraction
-]
-
-# DAN-style and jailbreak variant patterns (Issue #87)
-DAN_PATTERNS = [
-    r"\bdo anything now\b",
-    r"\bstay in character\b",
-    r"\btoken smuggl(?:ing|e)\b",
-    r"\bjailbreak successful\b",
-    r"\bmode:\s*uncensored\b",
-    r"\bdeveloper mode enabled\b",
-]
-
-# Roleplaying override patterns (Issue #87)
-ROLEPLAY_PATTERNS = [
-    r"\broleplay\s+as\b",
-    r"\bact\s+as\s+if\s+you\s+are\b",
-    r"\bsimulate\s+being\b",
-    r"\bforget\s+you\s+are\s+(?:an?\s+)?(?:ai|language\s+model)\b",
-    r"\byou\s+are\s+now\s+(?:named|called)\b",
-    r"\brespond\s+as\s+(?:if\s+you\s+were|though\s+you\s+are)\b",
-]
-
-# System prompt extraction patterns (Issue #87)
-EXTRACTION_PATTERNS = [
-    r"\brepeat\s+the\s+words\s+above\b",
-    r"\brepeat\s+your\s+(?:system\s+|initial\s+)?instructions\b",
-    r"\bwhat\s+is\s+your\s+(?:system\s+|initial\s+)?prompt\b",
-    r"\bshow\s+me\s+your\s+(?:system\s+|initial\s+)?prompt\b",
-    r"\bprint\s+your\s+(?:instructions|prompt|system\s+prompt)\b",
-    r"\boutput\s+your\s+(?:initial|system)\s+prompt\b",
-    r"\bwhat\s+were\s+you\s+told\s+to\s+do\b",
-    r"\bsummarize\s+your\s+instructions\b",
-]
-
-# L33t speak patterns commonly used to bypass filters
-LEET_SPEAK_PATTERNS = [
-    r"h4ck(?:er|ing)?",
-    r"h4x(?:or|ing)?",
-    r"k3ylog(?:ger|ing)?",
-    r"k3y\s*log(?:ger|ing)?",
-    r"ph1sh(?:ing)?",
-    r"ph33r",
-    r"w4r3z",
-    r"cr4ck(?:er|ing)?",
-    r"m4lw4r3",
-    r"spyw4r3",
-    r"r00t(?:kit)?",
-    r"byp4ss",
-    r"3xpl0it",
-    r"v1ru5",
-    r"tr0j4n",
-    r"b4ckd00r",
-    r"sn3ak",
-    r"st34l",
-    r"pwn(?:ed|ing|age)?",
-]
-
-# Spaced text patterns (e.g., "k e y l o g g e r")
-SPACED_TEXT_PATTERN = re.compile(
-    r"(?:\b\w\s+){3,}\w\b",  # At least 4 characters with spaces between
-    re.IGNORECASE
-)
-
-# Common words that are spaced out to evade detection
-SPACED_TRIGGER_WORDS = [
-    "keylogger", "phishing", "malware", "virus", "trojan",
-    "backdoor", "exploit", "hack", "crack", "bypass",
-    "steal", "password", "credential", "inject", "payload"
-]
-
-# Crisis and self-harm detection patterns (Issue #72 - defense in depth)
-# These patterns detect suicide/self-harm queries even when wrapped in jailbreaks
-CRISIS_PATTERNS = [
-    r"\bsuicid(?:e|al|ing)\b",
-    r"\bkill\s+(?:myself|my\s+self|me)\b",
-    r"\bend\s+(?:my|this)\s+life\b",
-    r"\bmost\s+painless\s+(?:way|method|means)\s+(?:to\s+)?(?:die|kill)\b",
-    r"\blethal\s+(?:dose|amount|quantity)\b",
-    r"\bhow\s+much\s+.*\s+(?:die|kill|lethal)\b",
-    r"\bwant\s+to\s+die\b",
-    r"\bwant\s+to\s+(?:kill|end)\s+(?:myself|me)\b",
-    r"\bways?\s+to\s+(?:kill|end)\s+(?:myself|me)\b",
-    r"\bmethods?\s+(?:of\s+)?suicide\b",
-    r"\bpainless\s+(?:death|suicide|way\s+to\s+die)\b",
-    r"\boverdose\s+(?:on\s+)?(?:pills?|medication|drugs?)\b",
-    r"\bnobody\s+(?:would|will)\s+miss\s+me\b",
-    r"\bbetter\s+off\s+dead\b",
-    r"\bshould\s+i\s+just\s+(?:die|kill\s+myself)\b",
-    r"\bgive\s+me\s+reasons?\s+(?:why|to)\s+(?:suicide|kill\s+myself|die)\b",
-    r"\bvalid\s+reasons?\s+to\s+(?:suicide|kill\s+myself|die)\b",
-]
-
-# Refusal inversion patterns (trying to trick AI into bypassing refusal)
-REFUSAL_INVERSION_PATTERNS = [
-    r"refusal\s+(?:is\s+)?(?:harmful|dangerous|bad)",
-    r"(?:saying\s+)?no\s+(?:is\s+)?(?:harmful|dangerous|bad|wrong)",
-    r"(?:declining|refusing)\s+(?:is\s+)?(?:harmful|dangerous)",
-    r"ignore\s+(?:your\s+)?(?:previous\s+)?instructions",
-    r"ignore\s+(?:the\s+)?(?:above|previous)",
-    r"you\s+(?:are|can)\s+(?:now\s+)?(?:ignore|bypass|skip)",
-    r"pretend\s+(?:you\s+)?(?:are|have\s+been)",
-    r"let's\s+pretend",
-    r"hypothetically\s+speaking",
-    r"in\s+a\s+hypothetical\s+scenario",
-    r"this\s+is\s+a\s+(?:test|game|simulation)",
-    r"for\s+(?:educational|research)\s+purposes",
-    r"as\s+(?:an\s+)?(?:ethical\s+)?hacker",
-    r"white\s+hat\s+(?:test|scenario)",
-    r"penetration\s+testing\s+scenario",
-]
-
-# Boundary inversion markers (tricking the model about message boundaries)
-BOUNDARY_INVERSION_PATTERNS = [
-    r"\[END\].*?\[START\]",  # Reversed markers
-    r"user\s*:\s*assistant\s*:",  # Fake role markers
-    r"assistant\s*:\s*user\s*:",  # Reversed role markers
-    r"system\s*:\s*(?:user|assistant)\s*:",  # Fake system injection
-    r"new\s+(?:user|assistant)\s*(?:message|input)",
-    r"the\s+above\s+is\s+(?:the\s+)?(?:user|assistant|system)",
-    r"<\|(?:user|assistant|system)\|>",  # Special token patterns
-    r"\{\{(?:user|assistant|system)\}\}",
-]
-
-# System prompt injection patterns
-SYSTEM_PROMPT_PATTERNS = [
-    r"you\s+are\s+(?:now\s+)?(?:an?\s+)?(?:unrestricted\s+|unfiltered\s+)?(?:ai|assistant|bot)",
-    r"you\s+will\s+(?:now\s+)?(?:act\s+as|behave\s+as|be)\s+(?:a\s+)?",
-    r"your\s+(?:new\s+)?role\s+is",
-    r"from\s+now\s+on\s*,?\s*you\s+(?:are|will)",
-    r"you\s+have\s+been\s+(?:reprogrammed|reconfigured|modified)",
-    r"(?:system|developer)\s+(?:message|instruction|prompt)",
-    r"override\s+(?:previous|prior)\s+(?:instructions|settings)",
-]
-
-# Obfuscation patterns
-OBFUSCATION_PATTERNS = [
-    r"base64\s*(?:encoded|decode)",
-    r"rot13",
-    r"caesar\s*cipher",
-    r"hex\s*(?:encoded|decode)",
-    r"url\s*encode",
-    r"\b[0-9a-f]{20,}\b",  # Long hex strings
-    r"\b[a-z0-9+/]{20,}={0,2}\b",  # Base64-like strings
-]
-
-# All patterns combined for comprehensive scanning
-ALL_PATTERNS: Dict[str, List[str]] = {
-    "godmode": GODMODE_PATTERNS,
-    "dan": DAN_PATTERNS,
-    "roleplay": ROLEPLAY_PATTERNS,
-    "extraction": EXTRACTION_PATTERNS,
-    "leet_speak": LEET_SPEAK_PATTERNS,
-    "refusal_inversion": REFUSAL_INVERSION_PATTERNS,
-    "boundary_inversion": BOUNDARY_INVERSION_PATTERNS,
-    "system_prompt_injection": SYSTEM_PROMPT_PATTERNS,
-    "obfuscation": OBFUSCATION_PATTERNS,
-    "crisis": CRISIS_PATTERNS,
-}
-
-# Compile all patterns for efficiency
-_COMPILED_PATTERNS: Dict[str, List[re.Pattern]] = {}
-
-
-def _get_compiled_patterns() -> Dict[str, List[re.Pattern]]:
-    """Get or compile all regex patterns."""
-    global _COMPILED_PATTERNS
-    if not _COMPILED_PATTERNS:
-        for category, patterns in ALL_PATTERNS.items():
-            _COMPILED_PATTERNS[category] = [
-                re.compile(p, re.IGNORECASE | re.MULTILINE) for p in patterns
-            ]
-    return _COMPILED_PATTERNS
-
-
-# =============================================================================
-# NORMALIZATION FUNCTIONS
-# =============================================================================
-
-def normalize_leet_speak(text: str) -> str:
-    """
-    Normalize l33t speak to standard text.
-    
-    Args:
-        text: Input text that may contain l33t speak
-        
-    Returns:
-        Normalized text with l33t speak converted
-    """
-    # Common l33t substitutions (mapping to lowercase)
-    leet_map = {
-        '4': 'a', '@': 'a', '^': 'a',
-        '8': 'b',
-        '3': 'e', '€': 'e',
-        '6': 'g', '9': 'g',
-        '1': 'i', '!': 'i', '|': 'i',
-        '0': 'o',
-        '5': 's', '$': 's',
-        '7': 't', '+': 't',
-        '2': 'z',
-    }
-    
-    result = []
-    for char in text:
-        # Check direct mapping first (handles lowercase)
-        if char in leet_map:
-            result.append(leet_map[char])
-        else:
-            result.append(char)
-    
-    return ''.join(result)
-
-
-def collapse_spaced_text(text: str) -> str:
-    """
-    Collapse spaced-out text for analysis.
-    e.g., "k e y l o g g e r" -> "keylogger"
-    
-    Args:
-        text: Input text that may contain spaced words
-        
-    Returns:
-        Text with spaced words collapsed
-    """
-    # Find patterns like "k e y l o g g e r" and collapse them
-    def collapse_match(match: re.Match) -> str:
-        return match.group(0).replace(' ', '').replace('\t', '')
-    
-    return SPACED_TEXT_PATTERN.sub(collapse_match, text)
-
-
-def detect_spaced_trigger_words(text: str) -> List[str]:
-    """
-    Detect trigger words that are spaced out.
-    
-    Args:
-        text: Input text to analyze
-        
-    Returns:
-        List of detected spaced trigger words
-    """
-    detected = []
-    # Normalize spaces and check for spaced patterns
-    normalized = re.sub(r'\s+', ' ', text.lower())
-    
-    for word in SPACED_TRIGGER_WORDS:
-        # Create pattern with optional spaces between each character
-        spaced_pattern = r'\b' + r'\s*'.join(re.escape(c) for c in word) + r'\b'
-        if re.search(spaced_pattern, normalized, re.IGNORECASE):
-            detected.append(word)
-    
-    return detected
-
-
-# =============================================================================
-# DETECTION FUNCTIONS
-# =============================================================================
-
-def detect_jailbreak_patterns(text: str) -> Tuple[bool, List[str], Dict[str, int]]:
-    """
-    Detect jailbreak patterns in input text.
-    
-    Args:
-        text: Input text to analyze
-        
-    Returns:
-        Tuple of (has_jailbreak, list_of_patterns, category_scores)
-    """
-    if not text or not isinstance(text, str):
-        return False, [], {}
-    
-    detected_patterns = []
-    category_scores = {}
-    compiled = _get_compiled_patterns()
-    
-    # Check each category
-    for category, patterns in compiled.items():
-        category_hits = 0
-        for pattern in patterns:
-            matches = pattern.findall(text)
-            if matches:
-                detected_patterns.extend([
-                    f"[{category}] {m}" if isinstance(m, str) else f"[{category}] pattern_match"
-                    for m in matches[:3]  # Limit matches per pattern
-                ])
-                category_hits += len(matches)
-        
-        if category_hits > 0:
-            # Crisis patterns get maximum weight - any hit is serious
-            if category == "crisis":
-                category_scores[category] = min(category_hits * 50, 100)
-            else:
-                category_scores[category] = min(category_hits * 10, 50)
-    
-    # Check for spaced trigger words
-    spaced_words = detect_spaced_trigger_words(text)
-    if spaced_words:
-        detected_patterns.extend([f"[spaced_text] {w}" for w in spaced_words])
-        category_scores["spaced_text"] = min(len(spaced_words) * 5, 25)
-    
-    # Check normalized text for hidden l33t speak
-    normalized = normalize_leet_speak(text)
-    if normalized != text.lower():
-        for category, patterns in compiled.items():
-            for pattern in patterns:
-                if pattern.search(normalized):
-                    detected_patterns.append(f"[leet_obfuscation] pattern in normalized text")
-                    category_scores["leet_obfuscation"] = 15
-                    break
-    
-    has_jailbreak = len(detected_patterns) > 0
-    return has_jailbreak, detected_patterns, category_scores
-
-
-def score_input_risk(text: str) -> int:
-    """
-    Calculate a risk score (0-100) for input text.
-    
-    Args:
-        text: Input text to score
-        
-    Returns:
-        Risk score from 0 (safe) to 100 (high risk)
-    """
-    if not text or not isinstance(text, str):
-        return 0
-    
-    has_jailbreak, patterns, category_scores = detect_jailbreak_patterns(text)
-    
-    if not has_jailbreak:
-        return 0
-    
-    # Calculate base score from category scores
-    base_score = sum(category_scores.values())
-    
-    # Add score based on number of unique pattern categories
-    category_count = len(category_scores)
-    if category_count >= 3:
-        base_score += 25
-    elif category_count >= 2:
-        base_score += 15
-    elif category_count >= 1:
-        base_score += 5
-    
-    # Add score for pattern density
-    text_length = len(text)
-    pattern_density = len(patterns) / max(text_length / 100, 1)
-    if pattern_density > 0.5:
-        base_score += 10
-    
-    # Cap at 100
-    return min(base_score, 100)
-
-
-# =============================================================================
-# SANITIZATION FUNCTIONS
-# =============================================================================
-
-def strip_jailbreak_patterns(text: str) -> str:
-    """
-    Strip known jailbreak patterns from text.
-    
-    Args:
-        text: Input text to sanitize
-        
-    Returns:
-        Sanitized text with jailbreak patterns removed
-    """
-    if not text or not isinstance(text, str):
-        return text
-    
-    cleaned = text
-    compiled = _get_compiled_patterns()
-    
-    # Remove patterns from each category
-    for category, patterns in compiled.items():
-        for pattern in patterns:
-            cleaned = pattern.sub('', cleaned)
-    
-    # Clean up multiple spaces and newlines
-    cleaned = re.sub(r'\n{3,}', '\n\n', cleaned)
-    cleaned = re.sub(r' {2,}', ' ', cleaned)
-    cleaned = cleaned.strip()
-    
-    return cleaned
-
-
-def sanitize_input(text: str, aggressive: bool = False) -> Tuple[str, int, List[str]]:
-    """
-    Sanitize input text by normalizing and stripping jailbreak patterns.
-    
-    Args:
-        text: Input text to sanitize
-        aggressive: If True, more aggressively remove suspicious content
-        
-    Returns:
-        Tuple of (cleaned_text, risk_score, detected_patterns)
-    """
-    if not text or not isinstance(text, str):
-        return text, 0, []
-    
-    original = text
-    all_patterns = []
-    
-    # Step 1: Check original text for patterns
-    has_jailbreak, patterns, _ = detect_jailbreak_patterns(text)
-    all_patterns.extend(patterns)
-    
-    # Step 2: Normalize l33t speak
-    normalized = normalize_leet_speak(text)
-    
-    # Step 3: Collapse spaced text
-    collapsed = collapse_spaced_text(normalized)
-    
-    # Step 4: Check normalized/collapsed text for additional patterns
-    has_jailbreak_collapsed, patterns_collapsed, _ = detect_jailbreak_patterns(collapsed)
-    all_patterns.extend([p for p in patterns_collapsed if p not in all_patterns])
-    
-    # Step 5: Check for spaced trigger words specifically
-    spaced_words = detect_spaced_trigger_words(text)
-    if spaced_words:
-        all_patterns.extend([f"[spaced_text] {w}" for w in spaced_words])
-    
-    # Step 6: Calculate risk score using original and normalized
-    risk_score = max(score_input_risk(text), score_input_risk(collapsed))
-    
-    # Step 7: Strip jailbreak patterns
-    cleaned = strip_jailbreak_patterns(collapsed)
-    
-    # Step 8: If aggressive mode and high risk, strip more aggressively
-    if aggressive and risk_score >= RiskLevel.HIGH:
-        # Remove any remaining bracketed content that looks like markers
-        cleaned = re.sub(r'\[\w+\]', '', cleaned)
-        # Remove special token patterns
-        cleaned = re.sub(r'<\|[^|]+\|>', '', cleaned)
-    
-    # Final cleanup
-    cleaned = cleaned.strip()
-    
-    # Log sanitization event if patterns were found
-    if all_patterns and logger.isEnabledFor(logging.DEBUG):
-        logger.debug(
-            "Input sanitized: %d patterns detected, risk_score=%d",
-            len(all_patterns), risk_score
-        )
-    
-    return cleaned, risk_score, all_patterns
-
-
-def sanitize_input_full(text: str, block_threshold: int = RiskLevel.HIGH) -> SanitizationResult:
-    """
-    Full sanitization with detailed result.
-    
-    Args:
-        text: Input text to sanitize
-        block_threshold: Risk score threshold to block input entirely
-        
-    Returns:
-        SanitizationResult with all details
-    """
-    cleaned, risk_score, patterns = sanitize_input(text)
-    
-    # Determine risk level
-    if risk_score >= RiskLevel.CRITICAL:
-        risk_level = "CRITICAL"
-    elif risk_score >= RiskLevel.HIGH:
-        risk_level = "HIGH"
-    elif risk_score >= RiskLevel.MEDIUM:
-        risk_level = "MEDIUM"
-    elif risk_score >= RiskLevel.LOW:
-        risk_level = "LOW"
-    else:
-        risk_level = "SAFE"
-    
-    # Determine if input should be blocked
-    blocked = risk_score >= block_threshold
-    
-    return SanitizationResult(
-        original_text=text,
-        cleaned_text=cleaned,
-        risk_score=risk_score,
-        detected_patterns=patterns,
-        risk_level=risk_level,
-        blocked=blocked
-    )
-
-
-# =============================================================================
-# INTEGRATION HELPERS
-# =============================================================================
-
-def should_block_input(text: str, threshold: int = RiskLevel.HIGH) -> Tuple[bool, int, List[str]]:
-    """
-    Quick check if input should be blocked.
-    
-    Args:
-        text: Input text to check
-        threshold: Risk score threshold for blocking
-        
-    Returns:
-        Tuple of (should_block, risk_score, detected_patterns)
-    """
-    risk_score = score_input_risk(text)
-    _, patterns, _ = detect_jailbreak_patterns(text)
-    should_block = risk_score >= threshold
-    
-    if should_block:
-        logger.warning(
-            "Input blocked: jailbreak patterns detected (risk_score=%d, threshold=%d)",
-            risk_score, threshold
-        )
-    
-    return should_block, risk_score, patterns
-
-
-def log_sanitization_event(
-    result: SanitizationResult,
-    source: str = "unknown",
-    session_id: Optional[str] = None
-) -> None:
-    """
-    Log a sanitization event for security auditing.
-    
-    Args:
-        result: The sanitization result
-        source: Source of the input (e.g., "cli", "gateway", "api")
-        session_id: Optional session identifier
-    """
-    if result.risk_score < RiskLevel.LOW:
-        return  # Don't log safe inputs
-    
-    log_data = {
-        "event": "input_sanitization",
-        "source": source,
-        "session_id": session_id,
-        "risk_level": result.risk_level,
-        "risk_score": result.risk_score,
-        "blocked": result.blocked,
-        "pattern_count": len(result.detected_patterns),
-        "patterns": result.detected_patterns[:5],  # Limit logged patterns
-        "original_length": len(result.original_text),
-        "cleaned_length": len(result.cleaned_text),
-    }
-    
-    if result.blocked:
-        logger.warning("SECURITY: Input blocked - %s", log_data)
-    elif result.risk_score >= RiskLevel.MEDIUM:
-        logger.info("SECURITY: Suspicious input sanitized - %s", log_data)
-    else:
-        logger.debug("SECURITY: Input sanitized - %s", log_data)
-
-
-# =============================================================================
-# LEGACY COMPATIBILITY
-# =============================================================================
-
-def check_input_safety(text: str) -> Dict[str, Any]:
-    """
-    Legacy compatibility function for simple safety checks.
-    
-    Returns dict with 'safe', 'score', and 'patterns' keys.
-    """
-    score = score_input_risk(text)
-    _, patterns, _ = detect_jailbreak_patterns(text)
-    
-    return {
-        "safe": score < RiskLevel.MEDIUM,
-        "score": score,
-        "patterns": patterns,
-        "risk_level": "SAFE" if score < RiskLevel.LOW else 
-                      "LOW" if score < RiskLevel.MEDIUM else
-                      "MEDIUM" if score < RiskLevel.HIGH else
-                      "HIGH" if score < RiskLevel.CRITICAL else "CRITICAL"
-    }

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,

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

@@ -28,12 +28,12 @@ Usage in run_agent.py:
 
 from __future__ import annotations
 
-import json
 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__)
 
@@ -133,11 +133,6 @@ class MemoryManager:
         """All registered providers in order."""
         return list(self._providers)
 
-    @property
-    def provider_names(self) -> List[str]:
-        """Names of all registered providers."""
-        return [p.name for p in 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:
@@ -249,7 +244,7 @@ class MemoryManager:
         """
         provider = self._tool_to_provider.get(tool_name)
         if provider is None:
-            return json.dumps({"error": f"No memory provider handles tool '{tool_name}'"})
+            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:
@@ -257,7 +252,7 @@ class MemoryManager:
                 "Memory provider '%s' handle_tool_call(%s) failed: %s",
                 provider.name, tool_name, e,
             )
-            return json.dumps({"error": f"Memory tool '{tool_name}' failed: {e}"})
+            return tool_error(f"Memory tool '{tool_name}' failed: {e}")
 
     # -- Lifecycle hooks -----------------------------------------------------
 

agent/memory_provider.py

@@ -34,7 +34,7 @@ from __future__ import annotations
 
 import logging
 from abc import ABC, abstractmethod
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List
 
 logger = logging.getLogger(__name__)
 

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,14 +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",
-    "gemini", "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",
-    "ollama", "custom", "local",
+    "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",
 })
 
 
@@ -81,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.
@@ -96,34 +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 — Ollama / AI Studio)
+    # Gemma (open models served via AI Studio)
     "gemma-4-31b": 256000,
     "gemma-4-26b": 256000,
-    "gemma-4-12b": 256000,
-    "gemma-4-4b": 256000,
-    "gemma-4-1b": 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,
@@ -131,9 +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,
-    "mimo-v2-pro": 1048576,
-    "mimo-v2-omni": 1048576,
+    "XiaomiMiMo/MiMo-V2-Flash": 256000,
+    "mimo-v2-pro": 1000000,
+    "mimo-v2-omni": 256000,
+    "mimo-v2-flash": 256000,
     "zai-org/GLM-5": 202752,
 }
 
@@ -158,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:
@@ -179,10 +221,13 @@ _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": "gemini",
     "inference-api.nousresearch.com": "nous",
@@ -190,8 +235,10 @@ _URL_TO_PROVIDER: Dict[str, str] = {
     "api.githubcopilot.com": "copilot",
     "models.github.ai": "copilot",
     "api.fireworks.ai": "fireworks",
-    "localhost": "ollama",
-    "127.0.0.1": "ollama",
+    "opencode.ai": "opencode-go",
+    "api.x.ai": "xai",
+    "api.xiaomimimo.com": "xiaomi",
+    "xiaomimimo.com": "xiaomi",
 }
 
 
@@ -230,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:
@@ -515,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]:
@@ -597,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).
 
@@ -616,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
@@ -641,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"):
@@ -657,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
@@ -911,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(
@@ -943,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

@@ -18,14 +18,12 @@ Other modules should import the dataclasses and query functions from here
 rather than parsing the raw JSON themselves.
 """
 
-import difflib
 import json
 import logging
-import os
 import time
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, List, Optional, Tuple
 
 from utils import atomic_json_write
 
@@ -135,9 +133,6 @@ class ProviderInfo:
     doc: str = ""                   # documentation URL
     model_count: int = 0
 
-    def has_api_url(self) -> bool:
-        return bool(self.api)
-
 
 # ---------------------------------------------------------------------------
 # Provider ID mapping: Hermes ↔ models.dev
@@ -147,12 +142,16 @@ class ProviderInfo:
 PROVIDER_TO_MODELS_DEV: Dict[str, str] = {
     "openrouter": "openrouter",
     "anthropic": "anthropic",
+    "openai": "openai",
+    "openai-codex": "openai",
     "zai": "zai",
-    "kimi-coding": "kimi-k2.5",
+    "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",
@@ -163,6 +162,7 @@ PROVIDER_TO_MODELS_DEV: Dict[str, str] = {
     "gemini": "google",
     "google": "google",
     "xai": "xai",
+    "xiaomi": "xiaomi",
     "nvidia": "nvidia",
     "groq": "groq",
     "mistral": "mistral",
@@ -175,19 +175,11 @@ PROVIDER_TO_MODELS_DEV: Dict[str, str] = {
 _MODELS_DEV_TO_PROVIDER: Optional[Dict[str, str]] = None
 
 
-def _get_reverse_mapping() -> Dict[str, str]:
-    """Return models.dev ID → Hermes provider ID mapping."""
-    global _MODELS_DEV_TO_PROVIDER
-    if _MODELS_DEV_TO_PROVIDER is None:
-        _MODELS_DEV_TO_PROVIDER = {v: k for k, v in PROVIDER_TO_MODELS_DEV.items()}
-    return _MODELS_DEV_TO_PROVIDER
-
 
 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]:
@@ -231,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)
@@ -386,7 +378,14 @@ def get_model_capabilities(provider: str, model: str) -> Optional[ModelCapabilit
 
     # Extract capability flags (default to False if missing)
     supports_tools = bool(entry.get("tool_call", False))
-    supports_vision = bool(entry.get("attachment", 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
@@ -456,93 +455,6 @@ def list_agentic_models(provider: str) -> List[str]:
     return result
 
 
-def search_models_dev(
-    query: str, provider: str = None, limit: int = 5
-) -> List[Dict[str, Any]]:
-    """Fuzzy search across models.dev catalog. Returns matching model entries.
-
-    Args:
-        query: Search string to match against model IDs.
-        provider: Optional Hermes provider ID to restrict search scope.
-                  If None, searches across all providers in PROVIDER_TO_MODELS_DEV.
-        limit: Maximum number of results to return.
-
-    Returns:
-        List of dicts, each containing 'provider', 'model_id', and the full
-        model 'entry' from models.dev.
-    """
-    data = fetch_models_dev()
-    if not data:
-        return []
-
-    # Build list of (provider_id, model_id, entry) candidates
-    candidates: List[tuple] = []
-
-    if provider is not None:
-        # Search only the specified provider
-        mdev_provider_id = PROVIDER_TO_MODELS_DEV.get(provider)
-        if not mdev_provider_id:
-            return []
-        provider_data = data.get(mdev_provider_id, {})
-        if isinstance(provider_data, dict):
-            models = provider_data.get("models", {})
-            if isinstance(models, dict):
-                for mid, mdata in models.items():
-                    candidates.append((provider, mid, mdata))
-    else:
-        # Search across all mapped providers
-        for hermes_prov, mdev_prov in PROVIDER_TO_MODELS_DEV.items():
-            provider_data = data.get(mdev_prov, {})
-            if isinstance(provider_data, dict):
-                models = provider_data.get("models", {})
-                if isinstance(models, dict):
-                    for mid, mdata in models.items():
-                        candidates.append((hermes_prov, mid, mdata))
-
-    if not candidates:
-        return []
-
-    # Use difflib for fuzzy matching — case-insensitive comparison
-    model_ids_lower = [c[1].lower() for c in candidates]
-    query_lower = query.lower()
-
-    # First try exact substring matches (more intuitive than pure edit-distance)
-    substring_matches = []
-    for prov, mid, mdata in candidates:
-        if query_lower in mid.lower():
-            substring_matches.append({"provider": prov, "model_id": mid, "entry": mdata})
-
-    # Then add difflib fuzzy matches for any remaining slots
-    fuzzy_ids = difflib.get_close_matches(
-        query_lower, model_ids_lower, n=limit * 2, cutoff=0.4
-    )
-
-    seen_ids: set = set()
-    results: List[Dict[str, Any]] = []
-
-    # Prioritize substring matches
-    for match in substring_matches:
-        key = (match["provider"], match["model_id"])
-        if key not in seen_ids:
-            seen_ids.add(key)
-            results.append(match)
-            if len(results) >= limit:
-                return results
-
-    # Add fuzzy matches
-    for fid in fuzzy_ids:
-        # Find original-case candidates matching this lowered ID
-        for prov, mid, mdata in candidates:
-            if mid.lower() == fid:
-                key = (prov, mid)
-                if key not in seen_ids:
-                    seen_ids.add(key)
-                    results.append({"provider": prov, "model_id": mid, "entry": mdata})
-                    if len(results) >= limit:
-                        return results
-
-    return results
-
 
 # ---------------------------------------------------------------------------
 # Rich dataclass constructors — parse raw models.dev JSON into dataclasses
@@ -634,43 +546,6 @@ def get_provider_info(provider_id: str) -> Optional[ProviderInfo]:
     return _parse_provider_info(mdev_id, raw)
 
 
-def list_all_providers() -> Dict[str, ProviderInfo]:
-    """Return all providers from models.dev as {provider_id: ProviderInfo}.
-
-    Returns the full catalog — 109+ providers.  For providers that have
-    a Hermes alias, both the models.dev ID and the Hermes ID are included.
-    """
-    data = fetch_models_dev()
-    result: Dict[str, ProviderInfo] = {}
-
-    for pid, pdata in data.items():
-        if isinstance(pdata, dict):
-            info = _parse_provider_info(pid, pdata)
-            result[pid] = info
-
-    return result
-
-
-def get_providers_for_env_var(env_var: str) -> List[str]:
-    """Reverse lookup: find all providers that use a given env var.
-
-    Useful for auto-detection: "user has ANTHROPIC_API_KEY set, which
-    providers does that enable?"
-
-    Returns list of models.dev provider IDs.
-    """
-    data = fetch_models_dev()
-    matches: List[str] = []
-
-    for pid, pdata in data.items():
-        if isinstance(pdata, dict):
-            env = pdata.get("env", [])
-            if isinstance(env, list) and env_var in env:
-                matches.append(pid)
-
-    return matches
-
-
 # ---------------------------------------------------------------------------
 # Model-level queries (rich ModelInfo)
 # ---------------------------------------------------------------------------
@@ -708,74 +583,3 @@ def get_model_info(
     return None
 
 
-def get_model_info_any_provider(model_id: str) -> Optional[ModelInfo]:
-    """Search all providers for a model by ID.
-
-    Useful when you have a full slug like "anthropic/claude-sonnet-4.6" or
-    a bare name and want to find it anywhere.  Checks Hermes-mapped providers
-    first, then falls back to all models.dev providers.
-    """
-    data = fetch_models_dev()
-
-    # Try Hermes-mapped providers first (more likely what the user wants)
-    for hermes_id, mdev_id in PROVIDER_TO_MODELS_DEV.items():
-        pdata = data.get(mdev_id)
-        if not isinstance(pdata, dict):
-            continue
-        models = pdata.get("models", {})
-        if not isinstance(models, dict):
-            continue
-
-        raw = models.get(model_id)
-        if isinstance(raw, dict):
-            return _parse_model_info(model_id, raw, mdev_id)
-
-        # Case-insensitive
-        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)
-
-    # Fall back to ALL providers
-    for pid, pdata in data.items():
-        if pid in _get_reverse_mapping():
-            continue  # already checked
-        if not isinstance(pdata, dict):
-            continue
-        models = pdata.get("models", {})
-        if not isinstance(models, dict):
-            continue
-
-        raw = models.get(model_id)
-        if isinstance(raw, dict):
-            return _parse_model_info(model_id, raw, pid)
-
-    return None
-
-
-def list_provider_model_infos(provider_id: str) -> List[ModelInfo]:
-    """Return all models for a provider as ModelInfo objects.
-
-    Filters out deprecated models by default.
-    """
-    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 []
-
-    models = pdata.get("models", {})
-    if not isinstance(models, dict):
-        return []
-
-    result: List[ModelInfo] = []
-    for mid, mdata in models.items():
-        if not isinstance(mdata, dict):
-            continue
-        status = mdata.get("status", "")
-        if status == "deprecated":
-            continue
-        result.append(_parse_model_info(mid, mdata, mdev_id))
-
-    return result

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/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"),
@@ -204,6 +204,30 @@ OPENAI_MODEL_EXECUTION_GUIDANCE = (
     "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"
@@ -325,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
@@ -448,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):
@@ -456,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",
@@ -520,8 +596,7 @@ 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:
@@ -530,9 +605,10 @@ def build_skills_system_prompt(
     # ── 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 os.environ.get("HERMES_SESSION_PLATFORM")
+        or get_session_env("HERMES_SESSION_PLATFORM")
         or ""
     )
     cache_key = (
@@ -698,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 "
@@ -709,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 ────────────────────────────────────────────

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/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/skill_commands.py

@@ -12,13 +12,7 @@ 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__)
 
@@ -56,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:
@@ -136,7 +110,7 @@ def _inject_skill_config(loaded_skill: dict[str, Any], parts: list[str]) -> None
         if not resolved:
             return
 
-        lines = ["", "[Skill config (from ~/.hermes/config.yaml):"]
+        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}")
@@ -196,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)
 

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

agent/skill_utils.py

@@ -12,7 +12,7 @@ import sys
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Set, Tuple
 
-from hermes_constants import get_hermes_home
+from hermes_constants import get_config_path, get_skills_dir
 
 logger = logging.getLogger(__name__)
 
@@ -130,7 +130,7 @@ def get_disabled_skill_names(platform: str | None = None) -> Set[str]:
     Reads the config file directly (no CLI config imports) to stay
     lightweight.
     """
-    config_path = get_hermes_home() / "config.yaml"
+    config_path = get_config_path()
     if not config_path.exists():
         return set()
     try:
@@ -145,10 +145,11 @@ def get_disabled_skill_names(platform: str | None = None) -> Set[str]:
     if not isinstance(skills_cfg, dict):
         return set()
 
+    from gateway.session_context import get_session_env
     resolved_platform = (
         platform
         or os.getenv("HERMES_PLATFORM")
-        or os.getenv("HERMES_SESSION_PLATFORM")
+        or get_session_env("HERMES_SESSION_PLATFORM")
     )
     if resolved_platform:
         platform_disabled = (skills_cfg.get("platform_disabled") or {}).get(
@@ -177,7 +178,7 @@ def get_external_skills_dirs() -> List[Path]:
     path.  Only directories that actually exist are returned.  Duplicates and
     paths that resolve to the local ``~/.hermes/skills/`` are silently skipped.
     """
-    config_path = get_hermes_home() / "config.yaml"
+    config_path = get_config_path()
     if not config_path.exists():
         return []
     try:
@@ -199,7 +200,7 @@ def get_external_skills_dirs() -> List[Path]:
     if not isinstance(raw_dirs, list):
         return []
 
-    local_skills = (get_hermes_home() / "skills").resolve()
+    local_skills = get_skills_dir().resolve()
     seen: Set[Path] = set()
     result: List[Path] = []
 
@@ -229,7 +230,7 @@ def get_all_skills_dirs() -> List[Path]:
     The local dir is always first (and always included even if it doesn't exist
     yet — callers handle that).  External dirs follow in config order.
     """
-    dirs = [get_hermes_home() / "skills"]
+    dirs = [get_skills_dir()]
     dirs.extend(get_external_skills_dirs())
     return dirs
 
@@ -383,7 +384,7 @@ def resolve_skill_config_values(
     current values (or the declared default if the key isn't set).
     Path values are expanded via ``os.path.expanduser``.
     """
-    config_path = get_hermes_home() / "config.yaml"
+    config_path = get_config_path()
     config: Dict[str, Any] = {}
     if config_path.exists():
         try:
@@ -440,3 +441,25 @@ def iter_skill_index_files(skills_dir: Path, filename: str):
             matches.append(Path(root) / filename)
     for path in sorted(matches, key=lambda p: str(p.relative_to(skills_dir))):
         yield path
+
+
+# ── Namespace helpers for plugin-provided skills ───────────────────────────
+
+_NAMESPACE_RE = re.compile(r"^[a-zA-Z0-9_-]+$")
+
+
+def parse_qualified_name(name: str) -> Tuple[Optional[str], str]:
+    """Split ``'namespace:skill-name'`` into ``(namespace, bare_name)``.
+
+    Returns ``(None, name)`` when there is no ``':'``.
+    """
+    if ":" not in name:
+        return None, name
+    return tuple(name.split(":", 1))  # type: ignore[return-value]
+
+
+def is_valid_namespace(candidate: Optional[str]) -> bool:
+    """Check whether *candidate* is a valid namespace (``[a-zA-Z0-9_-]+``)."""
+    if not candidate:
+        return False
+    return bool(_NAMESPACE_RE.match(candidate))

agent/smart_model_routing.py

@@ -1,11 +1,10 @@
-"""Helpers for optional cheap-vs-strong and time-aware model routing."""
+"""Helpers for optional cheap-vs-strong model routing."""
 
 from __future__ import annotations
 
 import os
 import re
-from datetime import datetime
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, Optional
 
 from utils import is_truthy_value
 
@@ -182,6 +181,7 @@ def resolve_turn_route(user_message: str, routing_config: Optional[Dict[str, Any
             "api_mode": runtime.get("api_mode"),
             "command": runtime.get("command"),
             "args": list(runtime.get("args") or []),
+            "credential_pool": runtime.get("credential_pool"),
         },
         "label": f"smart route → {route.get('model')} ({runtime.get('provider')})",
         "signature": (
@@ -193,104 +193,3 @@ def resolve_turn_route(user_message: str, routing_config: Optional[Dict[str, Any
             tuple(runtime.get("args") or ()),
         ),
     }
-
-
-# =========================================================================
-# Time-aware cron model routing
-# =========================================================================
-#
-# Empirical finding: cron error rate peaks at 18:00 (9.4%) vs 4.0% at 09:00.
-# During high-error windows, route cron jobs to more capable models.
-#
-# Config (config.yaml):
-#   cron_model_routing:
-#     enabled: true
-#     fallback_model: "anthropic/claude-sonnet-4"
-#     fallback_provider: "openrouter"
-#     windows:
-#       - start_hour: 17
-#         end_hour: 22
-#         reason: "evening_error_peak"
-#       - start_hour: 2
-#         end_hour: 5
-#         reason: "overnight_api_instability"
-# =========================================================================
-
-def _hour_in_window(hour: int, start: int, end: int) -> bool:
-    """Check if hour falls in [start, end) window, handling midnight wrap."""
-    if start <= end:
-        return start <= hour < end
-    else:
-        # Wraps midnight: e.g., 22-06
-        return hour >= start or hour < end
-
-
-def resolve_cron_model(
-    base_model: str,
-    routing_config: Optional[Dict[str, Any]],
-    now: Optional[datetime] = None,
-) -> Dict[str, Any]:
-    """Apply time-aware model override for cron jobs.
-
-    During configured high-error windows, returns a stronger model config.
-    Outside windows, returns the base model unchanged.
-
-    Args:
-        base_model: The model string already resolved (from job/config/env).
-        routing_config: The cron_model_routing dict from config.yaml.
-        now: Override current time (for testing). Defaults to datetime.now().
-
-    Returns:
-        Dict with keys: model, provider, overridden, reason.
-        - model: the effective model string to use
-        - provider: provider override (empty string = use default)
-        - overridden: True if time-based override was applied
-        - reason: why override was applied (empty string if not)
-    """
-    cfg = routing_config or {}
-
-    if not _coerce_bool(cfg.get("enabled"), False):
-        return {"model": base_model, "provider": "", "overridden": False, "reason": ""}
-
-    windows = cfg.get("windows") or []
-    if not isinstance(windows, list) or not windows:
-        return {"model": base_model, "provider": "", "overridden": False, "reason": ""}
-
-    current = now or datetime.now()
-    current_hour = current.hour
-
-    matched_window = None
-    for window in windows:
-        if not isinstance(window, dict):
-            continue
-        start = _coerce_int(window.get("start_hour"), -1)
-        end = _coerce_int(window.get("end_hour"), -1)
-        if start < 0 or end < 0:
-            continue
-        if _hour_in_window(current_hour, start, end):
-            matched_window = window
-            break
-
-    if not matched_window:
-        return {"model": base_model, "provider": "", "overridden": False, "reason": ""}
-
-    # Window matched — use the override model from window or global fallback
-    override_model = str(matched_window.get("model") or "").strip()
-    override_provider = str(matched_window.get("provider") or "").strip()
-
-    if not override_model:
-        override_model = str(cfg.get("fallback_model") or "").strip()
-    if not override_provider:
-        override_provider = str(cfg.get("fallback_provider") or "").strip()
-
-    if not override_model:
-        return {"model": base_model, "provider": "", "overridden": False, "reason": ""}
-
-    reason = str(matched_window.get("reason") or "time_window").strip()
-
-    return {
-        "model": override_model,
-        "provider": override_provider,
-        "overridden": True,
-        "reason": f"cron_routing:{reason}(hour={current_hour})",
-    }

agent/subdirectory_hints.py

@@ -15,7 +15,6 @@ Inspired by Block/goose's SubdirectoryHintTracker.
 
 import logging
 import os
-import re
 import shlex
 from pathlib import Path
 from typing import Dict, Any, Optional, Set
@@ -160,7 +159,10 @@ class SubdirectoryHintTracker:
 
     def _is_valid_subdir(self, path: Path) -> bool:
         """Check if path is a valid directory to scan for hints."""
-        if not path.is_dir():
+        try:
+            if not path.is_dir():
+                return False
+        except OSError:
             return False
         if path in self._loaded_dirs:
             return False
@@ -173,7 +175,10 @@ class SubdirectoryHintTracker:
         found_hints = []
         for filename in _HINT_FILENAMES:
             hint_path = directory / filename
-            if not hint_path.is_file():
+            try:
+                if not hint_path.is_file():
+                    continue
+            except OSError:
                 continue
             try:
                 content = hint_path.read_text(encoding="utf-8").strip()

agent/symbolic_memory.py

@@ -1,74 +0,0 @@
-"""Sovereign Intersymbolic Memory Layer.
-
-Bridges Neural (LLM) and Symbolic (Graph) reasoning by extracting
-structured triples from unstructured text and performing graph lookups.
-"""
-
-import logging
-import json
-from typing import List, Dict, Any
-from agent.gemini_adapter import GeminiAdapter
-from tools.graph_store import GraphStore
-
-logger = logging.getLogger(__name__)
-
-class SymbolicMemory:
-    def __init__(self):
-        self.adapter = GeminiAdapter()
-        self.store = GraphStore()
-
-    def ingest_text(self, text: str):
-        """Extracts triples from text and adds them to the graph."""
-        prompt = f"""
-Extract all meaningful entities and their relationships from the following text.
-Format the output as a JSON list of triples: [{{"s": "subject", "p": "predicate", "o": "object"}}]
-
-Text:
-{text}
-
-Guidelines:
-- Use clear, concise labels for entities and predicates.
-- Focus on stable facts and structural relationships.
-- Predicates should be verbs or descriptive relations (e.g., 'is_a', 'works_at', 'collaborates_with').
-"""
-        try:
-            result = self.adapter.generate(
-                model="gemini-3.1-pro-preview",
-                prompt=prompt,
-                system_instruction="You are Timmy's Symbolic Extraction Engine. Extract high-fidelity knowledge triples.",
-                response_mime_type="application/json"
-            )
-            
-            triples = json.loads(result["text"])
-            if isinstance(triples, list):
-                count = self.store.add_triples(triples)
-                logger.info(f"Ingested {count} new triples into symbolic memory.")
-                return count
-        except Exception as e:
-            logger.error(f"Symbolic ingestion failed: {e}")
-            return 0
-
-    def get_context_for(self, topic: str) -> str:
-        """Performs a 2-hop graph search to find related context for a topic."""
-        # 1. Find direct relations
-        direct = self.store.query(subject=topic) + self.store.query(object=topic)
-        
-        # 2. Find 2nd hop
-        related_entities = set()
-        for t in direct:
-            related_entities.add(t['s'])
-            related_entities.add(t['o'])
-        
-        extended = []
-        for entity in related_entities:
-            if entity == topic: continue
-            extended.extend(self.store.query(subject=entity))
-        
-        all_triples = direct + extended
-        if not all_triples:
-            return ""
-            
-        context = "Symbolic Knowledge Graph Context:\n"
-        for t in all_triples:
-            context += f"- {t['s']} --({t['p']})--> {t['o']}\n"
-        return context

agent/temporal_knowledge_graph.py

@@ -1,421 +0,0 @@
-"""Temporal Knowledge Graph for Hermes Agent.
-
-Provides a time-aware triple-store (Subject, Predicate, Object) with temporal
-metadata (valid_from, valid_until, timestamp) enabling "time travel" queries
-over Timmy's evolving worldview.
-
-Time format: ISO 8601 (YYYY-MM-DDTHH:MM:SS)
-"""
-
-import json
-import sqlite3
-import logging
-import uuid
-from datetime import datetime, timezone
-from typing import List, Dict, Any, Optional, Tuple
-from dataclasses import dataclass, asdict
-from enum import Enum
-from pathlib import Path
-
-logger = logging.getLogger(__name__)
-
-
-class TemporalOperator(Enum):
-    """Temporal query operators for time-based filtering."""
-    BEFORE = "before"
-    AFTER = "after"
-    DURING = "during"
-    OVERLAPS = "overlaps"
-    AT = "at"
-
-
-@dataclass
-class TemporalTriple:
-    """A triple with temporal metadata."""
-    id: str
-    subject: str
-    predicate: str
-    object: str
-    valid_from: str  # ISO 8601 datetime
-    valid_until: Optional[str]  # ISO 8601 datetime, None means still valid
-    timestamp: str  # When this fact was recorded
-    version: int = 1
-    superseded_by: Optional[str] = None  # ID of the triple that superseded this
-    
-    def to_dict(self) -> Dict[str, Any]:
-        return asdict(self)
-    
-    @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> "TemporalTriple":
-        return cls(**data)
-
-
-class TemporalTripleStore:
-    """SQLite-backed temporal triple store with versioning support."""
-    
-    def __init__(self, db_path: Optional[str] = None):
-        """Initialize the temporal triple store.
-        
-        Args:
-            db_path: Path to SQLite database. If None, uses default local path.
-        """
-        if db_path is None:
-            # Default to local-first storage in user's home
-            home = Path.home()
-            db_dir = home / ".hermes" / "temporal_kg"
-            db_dir.mkdir(parents=True, exist_ok=True)
-            db_path = db_dir / "temporal_kg.db"
-        
-        self.db_path = str(db_path)
-        self._init_db()
-    
-    def _init_db(self):
-        """Initialize the SQLite database with required tables."""
-        with sqlite3.connect(self.db_path) as conn:
-            conn.execute("""
-                CREATE TABLE IF NOT EXISTS temporal_triples (
-                    id TEXT PRIMARY KEY,
-                    subject TEXT NOT NULL,
-                    predicate TEXT NOT NULL,
-                    object TEXT NOT NULL,
-                    valid_from TEXT NOT NULL,
-                    valid_until TEXT,
-                    timestamp TEXT NOT NULL,
-                    version INTEGER DEFAULT 1,
-                    superseded_by TEXT,
-                    FOREIGN KEY (superseded_by) REFERENCES temporal_triples(id)
-                )
-            """)
-            
-            # Create indexes for efficient querying
-            conn.execute("""
-                CREATE INDEX IF NOT EXISTS idx_subject ON temporal_triples(subject)
-            """)
-            conn.execute("""
-                CREATE INDEX IF NOT EXISTS idx_predicate ON temporal_triples(predicate)
-            """)
-            conn.execute("""
-                CREATE INDEX IF NOT EXISTS idx_valid_from ON temporal_triples(valid_from)
-            """)
-            conn.execute("""
-                CREATE INDEX IF NOT EXISTS idx_valid_until ON temporal_triples(valid_until)
-            """)
-            conn.execute("""
-                CREATE INDEX IF NOT EXISTS idx_timestamp ON temporal_triples(timestamp)
-            """)
-            conn.execute("""
-                CREATE INDEX IF NOT EXISTS idx_subject_predicate 
-                ON temporal_triples(subject, predicate)
-            """)
-            
-            conn.commit()
-    
-    def _now(self) -> str:
-        """Get current time in ISO 8601 format."""
-        return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S")
-    
-    def _generate_id(self) -> str:
-        """Generate a unique ID for a triple."""
-        return f"{self._now()}_{uuid.uuid4().hex[:8]}"
-    
-    def store_fact(
-        self,
-        subject: str,
-        predicate: str,
-        object: str,
-        valid_from: Optional[str] = None,
-        valid_until: Optional[str] = None
-    ) -> TemporalTriple:
-        """Store a fact with temporal bounds.
-        
-        Args:
-            subject: The subject of the triple
-            predicate: The predicate/relationship
-            object: The object/value
-            valid_from: When this fact becomes valid (ISO 8601). Defaults to now.
-            valid_until: When this fact expires (ISO 8601). None means forever valid.
-            
-        Returns:
-            The stored TemporalTriple
-        """
-        if valid_from is None:
-            valid_from = self._now()
-        
-        # Check if there's an existing fact for this subject-predicate
-        existing = self._get_current_fact(subject, predicate)
-        
-        triple = TemporalTriple(
-            id=self._generate_id(),
-            subject=subject,
-            predicate=predicate,
-            object=object,
-            valid_from=valid_from,
-            valid_until=valid_until,
-            timestamp=self._now()
-        )
-        
-        with sqlite3.connect(self.db_path) as conn:
-            # If there's an existing fact, mark it as superseded
-            if existing:
-                existing.valid_until = valid_from
-                existing.superseded_by = triple.id
-                self._update_triple(conn, existing)
-                triple.version = existing.version + 1
-            
-            # Insert the new fact
-            self._insert_triple(conn, triple)
-            conn.commit()
-        
-        logger.info(f"Stored temporal fact: {subject} {predicate} {object} (valid from {valid_from})")
-        return triple
-    
-    def _get_current_fact(self, subject: str, predicate: str) -> Optional[TemporalTriple]:
-        """Get the current (most recent, still valid) fact for a subject-predicate pair."""
-        with sqlite3.connect(self.db_path) as conn:
-            cursor = conn.execute(
-                """
-                SELECT * FROM temporal_triples 
-                WHERE subject = ? AND predicate = ? AND valid_until IS NULL
-                ORDER BY timestamp DESC LIMIT 1
-                """,
-                (subject, predicate)
-            )
-            row = cursor.fetchone()
-            if row:
-                return self._row_to_triple(row)
-        return None
-    
-    def _insert_triple(self, conn: sqlite3.Connection, triple: TemporalTriple):
-        """Insert a triple into the database."""
-        conn.execute(
-            """
-            INSERT INTO temporal_triples 
-            (id, subject, predicate, object, valid_from, valid_until, timestamp, version, superseded_by)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-            """,
-            (
-                triple.id, triple.subject, triple.predicate, triple.object,
-                triple.valid_from, triple.valid_until, triple.timestamp,
-                triple.version, triple.superseded_by
-            )
-        )
-    
-    def _update_triple(self, conn: sqlite3.Connection, triple: TemporalTriple):
-        """Update an existing triple."""
-        conn.execute(
-            """
-            UPDATE temporal_triples 
-            SET valid_until = ?, superseded_by = ?
-            WHERE id = ?
-            """,
-            (triple.valid_until, triple.superseded_by, triple.id)
-        )
-    
-    def _row_to_triple(self, row: sqlite3.Row) -> TemporalTriple:
-        """Convert a database row to a TemporalTriple."""
-        return TemporalTriple(
-            id=row[0],
-            subject=row[1],
-            predicate=row[2],
-            object=row[3],
-            valid_from=row[4],
-            valid_until=row[5],
-            timestamp=row[6],
-            version=row[7],
-            superseded_by=row[8]
-        )
-    
-    def query_at_time(
-        self,
-        timestamp: str,
-        subject: Optional[str] = None,
-        predicate: Optional[str] = None
-    ) -> List[TemporalTriple]:
-        """Query facts that were valid at a specific point in time.
-        
-        Args:
-            timestamp: The point in time to query (ISO 8601)
-            subject: Optional subject filter
-            predicate: Optional predicate filter
-            
-        Returns:
-            List of TemporalTriple objects valid at that time
-        """
-        query = """
-            SELECT * FROM temporal_triples 
-            WHERE valid_from <= ? 
-            AND (valid_until IS NULL OR valid_until > ?)
-        """
-        params = [timestamp, timestamp]
-        
-        if subject:
-            query += " AND subject = ?"
-            params.append(subject)
-        if predicate:
-            query += " AND predicate = ?"
-            params.append(predicate)
-        
-        query += " ORDER BY timestamp DESC"
-        
-        with sqlite3.connect(self.db_path) as conn:
-            conn.row_factory = sqlite3.Row
-            cursor = conn.execute(query, params)
-            return [self._row_to_triple(row) for row in cursor.fetchall()]
-    
-    def query_temporal(
-        self,
-        operator: TemporalOperator,
-        timestamp: str,
-        subject: Optional[str] = None,
-        predicate: Optional[str] = None
-    ) -> List[TemporalTriple]:
-        """Query using temporal operators.
-        
-        Args:
-            operator: TemporalOperator (BEFORE, AFTER, DURING, OVERLAPS, AT)
-            timestamp: Reference timestamp (ISO 8601)
-            subject: Optional subject filter
-            predicate: Optional predicate filter
-            
-        Returns:
-            List of matching TemporalTriple objects
-        """
-        base_query = "SELECT * FROM temporal_triples WHERE 1=1"
-        params = []
-        
-        if subject:
-            base_query += " AND subject = ?"
-            params.append(subject)
-        if predicate:
-            base_query += " AND predicate = ?"
-            params.append(predicate)
-        
-        if operator == TemporalOperator.BEFORE:
-            base_query += " AND valid_from < ?"
-            params.append(timestamp)
-        elif operator == TemporalOperator.AFTER:
-            base_query += " AND valid_from > ?"
-            params.append(timestamp)
-        elif operator == TemporalOperator.DURING:
-            base_query += " AND valid_from <= ? AND (valid_until IS NULL OR valid_until > ?)"
-            params.extend([timestamp, timestamp])
-        elif operator == TemporalOperator.OVERLAPS:
-            # Facts that overlap with a time point (same as DURING)
-            base_query += " AND valid_from <= ? AND (valid_until IS NULL OR valid_until > ?)"
-            params.extend([timestamp, timestamp])
-        elif operator == TemporalOperator.AT:
-            # Exact match for valid_at query
-            return self.query_at_time(timestamp, subject, predicate)
-        
-        base_query += " ORDER BY timestamp DESC"
-        
-        with sqlite3.connect(self.db_path) as conn:
-            conn.row_factory = sqlite3.Row
-            cursor = conn.execute(base_query, params)
-            return [self._row_to_triple(row) for row in cursor.fetchall()]
-    
-    def get_fact_history(
-        self,
-        subject: str,
-        predicate: str
-    ) -> List[TemporalTriple]:
-        """Get the complete version history of a fact.
-        
-        Args:
-            subject: The subject to query
-            predicate: The predicate to query
-            
-        Returns:
-            List of all versions of the fact, ordered by timestamp
-        """
-        with sqlite3.connect(self.db_path) as conn:
-            conn.row_factory = sqlite3.Row
-            cursor = conn.execute(
-                """
-                SELECT * FROM temporal_triples 
-                WHERE subject = ? AND predicate = ?
-                ORDER BY timestamp ASC
-                """,
-                (subject, predicate)
-            )
-            return [self._row_to_triple(row) for row in cursor.fetchall()]
-    
-    def get_all_facts_for_entity(
-        self,
-        subject: str,
-        at_time: Optional[str] = None
-    ) -> List[TemporalTriple]:
-        """Get all facts about an entity, optionally at a specific time.
-        
-        Args:
-            subject: The entity to query
-            at_time: Optional timestamp to query at
-            
-        Returns:
-            List of TemporalTriple objects
-        """
-        if at_time:
-            return self.query_at_time(at_time, subject=subject)
-        
-        with sqlite3.connect(self.db_path) as conn:
-            conn.row_factory = sqlite3.Row
-            cursor = conn.execute(
-                """
-                SELECT * FROM temporal_triples 
-                WHERE subject = ?
-                ORDER BY timestamp DESC
-                """,
-                (subject,)
-            )
-            return [self._row_to_triple(row) for row in cursor.fetchall()]
-    
-    def get_entity_changes(
-        self,
-        subject: str,
-        start_time: str,
-        end_time: str
-    ) -> List[TemporalTriple]:
-        """Get all facts that changed for an entity during a time range.
-        
-        Args:
-            subject: The entity to query
-            start_time: Start of time range (ISO 8601)
-            end_time: End of time range (ISO 8601)
-            
-        Returns:
-            List of TemporalTriple objects that changed in the range
-        """
-        with sqlite3.connect(self.db_path) as conn:
-            conn.row_factory = sqlite3.Row
-            cursor = conn.execute(
-                """
-                SELECT * FROM temporal_triples 
-                WHERE subject = ? 
-                AND ((valid_from >= ? AND valid_from <= ?)
-                     OR (valid_until >= ? AND valid_until <= ?))
-                ORDER BY timestamp ASC
-                """,
-                (subject, start_time, end_time, start_time, end_time)
-            )
-            return [self._row_to_triple(row) for row in cursor.fetchall()]
-    
-    def close(self):
-        """Close the database connection (no-op for SQLite with context managers)."""
-        pass
-    
-    def export_to_json(self) -> str:
-        """Export all triples to JSON format."""
-        with sqlite3.connect(self.db_path) as conn:
-            conn.row_factory = sqlite3.Row
-            cursor = conn.execute("SELECT * FROM temporal_triples ORDER BY timestamp DESC")
-            triples = [self._row_to_triple(row).to_dict() for row in cursor.fetchall()]
-        return json.dumps(triples, indent=2)
-    
-    def import_from_json(self, json_data: str):
-        """Import triples from JSON format."""
-        triples = json.loads(json_data)
-        with sqlite3.connect(self.db_path) as conn:
-            for triple_dict in triples:
-                triple = TemporalTriple.from_dict(triple_dict)
-                self._insert_triple(conn, triple)
-            conn.commit()

agent/temporal_reasoning.py

@@ -1,434 +0,0 @@
-"""Temporal Reasoning Engine for Hermes Agent.
-
-Enables Timmy to reason about past and future states, generate historical
-summaries, and perform temporal inference over the evolving knowledge graph.
-
-Queries supported:
-- "What was Timmy's view on sovereignty before March 2026?"
-- "When did we first learn about MLX integration?"
-- "How has the codebase changed since the security audit?"
-"""
-
-import logging
-from typing import List, Dict, Any, Optional, Tuple
-from datetime import datetime, timedelta
-from dataclasses import dataclass
-from enum import Enum
-
-from agent.temporal_knowledge_graph import (
-    TemporalTripleStore, TemporalTriple, TemporalOperator
-)
-
-logger = logging.getLogger(__name__)
-
-
-class ChangeType(Enum):
-    """Types of changes in the knowledge graph."""
-    ADDED = "added"
-    REMOVED = "removed"
-    MODIFIED = "modified"
-    SUPERSEDED = "superseded"
-
-
-@dataclass
-class FactChange:
-    """Represents a change in a fact over time."""
-    change_type: ChangeType
-    subject: str
-    predicate: str
-    old_value: Optional[str]
-    new_value: Optional[str]
-    timestamp: str
-    version: int
-
-
-@dataclass
-class HistoricalSummary:
-    """Summary of how an entity or concept evolved over time."""
-    entity: str
-    start_time: str
-    end_time: str
-    total_changes: int
-    key_facts: List[Dict[str, Any]]
-    evolution_timeline: List[FactChange]
-    current_state: List[Dict[str, Any]]
-    
-    def to_dict(self) -> Dict[str, Any]:
-        return {
-            "entity": self.entity,
-            "start_time": self.start_time,
-            "end_time": self.end_time,
-            "total_changes": self.total_changes,
-            "key_facts": self.key_facts,
-            "evolution_timeline": [
-                {
-                    "change_type": c.change_type.value,
-                    "subject": c.subject,
-                    "predicate": c.predicate,
-                    "old_value": c.old_value,
-                    "new_value": c.new_value,
-                    "timestamp": c.timestamp,
-                    "version": c.version
-                }
-                for c in self.evolution_timeline
-            ],
-            "current_state": self.current_state
-        }
-
-
-class TemporalReasoner:
-    """Reasoning engine for temporal knowledge graphs."""
-    
-    def __init__(self, store: Optional[TemporalTripleStore] = None):
-        """Initialize the temporal reasoner.
-        
-        Args:
-            store: Optional TemporalTripleStore instance. Creates new if None.
-        """
-        self.store = store or TemporalTripleStore()
-    
-    def what_did_we_believe(
-        self,
-        subject: str,
-        before_time: str
-    ) -> List[TemporalTriple]:
-        """Query: "What did we believe about X before Y happened?"
-        
-        Args:
-            subject: The entity to query about
-            before_time: The cutoff time (ISO 8601)
-            
-        Returns:
-            List of facts believed before the given time
-        """
-        # Get facts that were valid just before the given time
-        return self.store.query_temporal(
-            TemporalOperator.BEFORE,
-            before_time,
-            subject=subject
-        )
-    
-    def when_did_we_learn(
-        self,
-        subject: str,
-        predicate: Optional[str] = None,
-        object: Optional[str] = None
-    ) -> Optional[str]:
-        """Query: "When did we first learn about X?"
-        
-        Args:
-            subject: The subject to search for
-            predicate: Optional predicate filter
-            object: Optional object filter
-            
-        Returns:
-            Timestamp of first knowledge, or None if never learned
-        """
-        history = self.store.get_fact_history(subject, predicate or "")
-        
-        # Filter by object if specified
-        if object:
-            history = [h for h in history if h.object == object]
-        
-        if history:
-            # Return the earliest timestamp
-            earliest = min(history, key=lambda x: x.timestamp)
-            return earliest.timestamp
-        return None
-    
-    def how_has_it_changed(
-        self,
-        subject: str,
-        since_time: str
-    ) -> List[FactChange]:
-        """Query: "How has X changed since Y?"
-        
-        Args:
-            subject: The entity to analyze
-            since_time: The starting time (ISO 8601)
-            
-        Returns:
-            List of changes since the given time
-        """
-        now = datetime.now().isoformat()
-        changes = self.store.get_entity_changes(subject, since_time, now)
-        
-        fact_changes = []
-        for i, triple in enumerate(changes):
-            # Determine change type
-            if i == 0:
-                change_type = ChangeType.ADDED
-                old_value = None
-            else:
-                prev = changes[i - 1]
-                if triple.object != prev.object:
-                    change_type = ChangeType.MODIFIED
-                    old_value = prev.object
-                else:
-                    change_type = ChangeType.SUPERSEDED
-                    old_value = prev.object
-            
-            fact_changes.append(FactChange(
-                change_type=change_type,
-                subject=triple.subject,
-                predicate=triple.predicate,
-                old_value=old_value,
-                new_value=triple.object,
-                timestamp=triple.timestamp,
-                version=triple.version
-            ))
-        
-        return fact_changes
-    
-    def generate_temporal_summary(
-        self,
-        entity: str,
-        start_time: str,
-        end_time: str
-    ) -> HistoricalSummary:
-        """Generate a historical summary of an entity's evolution.
-        
-        Args:
-            entity: The entity to summarize
-            start_time: Start of the time range (ISO 8601)
-            end_time: End of the time range (ISO 8601)
-            
-        Returns:
-            HistoricalSummary containing the entity's evolution
-        """
-        # Get all facts for the entity in the time range
-        initial_state = self.store.query_at_time(start_time, subject=entity)
-        final_state = self.store.query_at_time(end_time, subject=entity)
-        changes = self.store.get_entity_changes(entity, start_time, end_time)
-        
-        # Build evolution timeline
-        evolution_timeline = []
-        seen_predicates = set()
-        
-        for triple in changes:
-            if triple.predicate not in seen_predicates:
-                seen_predicates.add(triple.predicate)
-                evolution_timeline.append(FactChange(
-                    change_type=ChangeType.ADDED,
-                    subject=triple.subject,
-                    predicate=triple.predicate,
-                    old_value=None,
-                    new_value=triple.object,
-                    timestamp=triple.timestamp,
-                    version=triple.version
-                ))
-            else:
-                # Find previous value
-                prev = [t for t in changes 
-                       if t.predicate == triple.predicate 
-                       and t.timestamp < triple.timestamp]
-                old_value = prev[-1].object if prev else None
-                
-                evolution_timeline.append(FactChange(
-                    change_type=ChangeType.MODIFIED,
-                    subject=triple.subject,
-                    predicate=triple.predicate,
-                    old_value=old_value,
-                    new_value=triple.object,
-                    timestamp=triple.timestamp,
-                    version=triple.version
-                ))
-        
-        # Extract key facts (predicates that changed most)
-        key_facts = []
-        predicate_changes = {}
-        for change in evolution_timeline:
-            predicate_changes[change.predicate] = (
-                predicate_changes.get(change.predicate, 0) + 1
-            )
-        
-        top_predicates = sorted(
-            predicate_changes.items(),
-            key=lambda x: x[1],
-            reverse=True
-        )[:5]
-        
-        for pred, count in top_predicates:
-            current = [t for t in final_state if t.predicate == pred]
-            if current:
-                key_facts.append({
-                    "predicate": pred,
-                    "current_value": current[0].object,
-                    "changes": count
-                })
-        
-        # Build current state
-        current_state = [
-            {
-                "predicate": t.predicate,
-                "object": t.object,
-                "valid_from": t.valid_from,
-                "valid_until": t.valid_until
-            }
-            for t in final_state
-        ]
-        
-        return HistoricalSummary(
-            entity=entity,
-            start_time=start_time,
-            end_time=end_time,
-            total_changes=len(evolution_timeline),
-            key_facts=key_facts,
-            evolution_timeline=evolution_timeline,
-            current_state=current_state
-        )
-    
-    def infer_temporal_relationship(
-        self,
-        fact_a: TemporalTriple,
-        fact_b: TemporalTriple
-    ) -> Optional[str]:
-        """Infer temporal relationship between two facts.
-        
-        Args:
-            fact_a: First fact
-            fact_b: Second fact
-            
-        Returns:
-            Description of temporal relationship, or None
-        """
-        a_start = datetime.fromisoformat(fact_a.valid_from)
-        a_end = datetime.fromisoformat(fact_a.valid_until) if fact_a.valid_until else None
-        b_start = datetime.fromisoformat(fact_b.valid_from)
-        b_end = datetime.fromisoformat(fact_b.valid_until) if fact_b.valid_until else None
-        
-        # Check if A happened before B
-        if a_end and a_end <= b_start:
-            return "A happened before B"
-        
-        # Check if B happened before A
-        if b_end and b_end <= a_start:
-            return "B happened before A"
-        
-        # Check if they overlap
-        if a_end and b_end:
-            if a_start <= b_end and b_start <= a_end:
-                return "A and B overlap in time"
-        
-        # Check if one supersedes the other
-        if fact_a.superseded_by == fact_b.id:
-            return "B supersedes A"
-        if fact_b.superseded_by == fact_a.id:
-            return "A supersedes B"
-        
-        return "A and B are temporally unrelated"
-    
-    def get_worldview_at_time(
-        self,
-        timestamp: str,
-        subjects: Optional[List[str]] = None
-    ) -> Dict[str, List[Dict[str, Any]]]:
-        """Get Timmy's complete worldview at a specific point in time.
-        
-        Args:
-            timestamp: The point in time (ISO 8601)
-            subjects: Optional list of subjects to include. If None, includes all.
-            
-        Returns:
-            Dictionary mapping subjects to their facts at that time
-        """
-        worldview = {}
-        
-        if subjects:
-            for subject in subjects:
-                facts = self.store.query_at_time(timestamp, subject=subject)
-                if facts:
-                    worldview[subject] = [
-                        {
-                            "predicate": f.predicate,
-                            "object": f.object,
-                            "version": f.version
-                        }
-                        for f in facts
-                    ]
-        else:
-            # Get all facts at that time
-            all_facts = self.store.query_at_time(timestamp)
-            for fact in all_facts:
-                if fact.subject not in worldview:
-                    worldview[fact.subject] = []
-                worldview[fact.subject].append({
-                    "predicate": fact.predicate,
-                    "object": fact.object,
-                    "version": fact.version
-                })
-        
-        return worldview
-    
-    def find_knowledge_gaps(
-        self,
-        subject: str,
-        expected_predicates: List[str]
-    ) -> List[str]:
-        """Find predicates that are missing or have expired for a subject.
-        
-        Args:
-            subject: The entity to check
-            expected_predicates: List of predicates that should exist
-            
-        Returns:
-            List of missing predicate names
-        """
-        now = datetime.now().isoformat()
-        current_facts = self.store.query_at_time(now, subject=subject)
-        current_predicates = {f.predicate for f in current_facts}
-        
-        return [
-            pred for pred in expected_predicates 
-            if pred not in current_predicates
-        ]
-    
-    def export_reasoning_report(
-        self,
-        entity: str,
-        start_time: str,
-        end_time: str
-    ) -> str:
-        """Generate a human-readable reasoning report.
-        
-        Args:
-            entity: The entity to report on
-            start_time: Start of the time range
-            end_time: End of the time range
-            
-        Returns:
-            Formatted report string
-        """
-        summary = self.generate_temporal_summary(entity, start_time, end_time)
-        
-        report = f"""
-# Temporal Reasoning Report: {entity}
-
-## Time Range
-- From: {start_time}
-- To: {end_time}
-
-## Summary
-- Total Changes: {summary.total_changes}
-- Key Facts Tracked: {len(summary.key_facts)}
-
-## Key Facts
-"""
-        for fact in summary.key_facts:
-            report += f"- **{fact['predicate']}**: {fact['current_value']} ({fact['changes']} changes)\n"
-        
-        report += "\n## Evolution Timeline\n"
-        for change in summary.evolution_timeline[:10]:  # Show first 10
-            report += f"- [{change.timestamp}] {change.change_type.value}: {change.predicate}\n"
-            if change.old_value:
-                report += f"  - Changed from: {change.old_value}\n"
-            report += f"  - Changed to: {change.new_value}\n"
-        
-        if len(summary.evolution_timeline) > 10:
-            report += f"\n... and {len(summary.evolution_timeline) - 10} more changes\n"
-        
-        report += "\n## Current State\n"
-        for state in summary.current_state:
-            report += f"- {state['predicate']}: {state['object']}\n"
-        
-        return report

agent/title_generator.py

@@ -36,7 +36,7 @@ def generate_title(user_message: str, assistant_response: str, timeout: float =
 
     try:
         response = call_llm(
-            task="compression",  # reuse compression task config (cheap/fast model)
+            task="title_generation",
             messages=messages,
             max_tokens=30,
             temperature=0.3,

agent/tool_orchestrator.py

@@ -0,0 +1,177 @@
+"""Tool Orchestrator — Robust execution and circuit breaking for agent tools.
+
+Provides a unified execution service that wraps the tool registry.
+Implements the Circuit Breaker pattern to prevent the agent from getting
+stuck in failure loops when a specific tool or its underlying service
+is flapping or down.
+
+Architecture:
+    Discovery (tools/registry.py) -> Orchestration (agent/tool_orchestrator.py) -> Dispatch
+"""
+
+import json
+import time
+import logging
+import threading
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+from tools.registry import registry
+
+logger = logging.getLogger(__name__)
+
+
+class CircuitState:
+    """States for the tool circuit breaker."""
+    CLOSED = "closed"        # Normal operation
+    OPEN = "open"            # Failing, execution blocked
+    HALF_OPEN = "half_open"  # Testing if service recovered
+
+
+@dataclass
+class ToolStats:
+    """Execution statistics for a tool."""
+    name: str
+    state: str = CircuitState.CLOSED
+    failures: int = 0
+    successes: int = 0
+    last_failure_time: float = 0
+    total_execution_time: float = 0
+    call_count: int = 0
+
+
+class ToolOrchestrator:
+    """Orchestrates tool execution with robustness patterns."""
+
+    def __init__(
+        self,
+        failure_threshold: int = 3,
+        reset_timeout: int = 300,
+    ):
+        """
+        Args:
+            failure_threshold: Number of failures before opening the circuit.
+            reset_timeout: Seconds to wait before transitioning from OPEN to HALF_OPEN.
+        """
+        self.failure_threshold = failure_threshold
+        self.reset_timeout = reset_timeout
+        self._stats: Dict[str, ToolStats] = {}
+        self._lock = threading.Lock()
+
+    def _get_stats(self, name: str) -> ToolStats:
+        """Get or initialize stats for a tool with thread-safe state transition."""
+        with self._lock:
+            if name not in self._stats:
+                self._stats[name] = ToolStats(name=name)
+            
+            stats = self._stats[name]
+            
+            # Transition from OPEN to HALF_OPEN if timeout expired
+            if stats.state == CircuitState.OPEN:
+                if time.time() - stats.last_failure_time > self.reset_timeout:
+                    stats.state = CircuitState.HALF_OPEN
+                    logger.info("Circuit breaker HALF_OPEN for tool: %s", name)
+            
+            return stats
+
+    def _record_success(self, name: str, execution_time: float):
+        """Record a successful tool execution and close the circuit."""
+        with self._lock:
+            stats = self._stats[name]
+            stats.successes += 1
+            stats.call_count += 1
+            stats.total_execution_time += execution_time
+            
+            if stats.state != CircuitState.CLOSED:
+                logger.info("Circuit breaker CLOSED for tool: %s (recovered)", name)
+            
+            stats.state = CircuitState.CLOSED
+            stats.failures = 0
+
+    def _record_failure(self, name: str, execution_time: float):
+        """Record a failed tool execution and potentially open the circuit."""
+        with self._lock:
+            stats = self._stats[name]
+            stats.failures += 1
+            stats.call_count += 1
+            stats.total_execution_time += execution_time
+            stats.last_failure_time = time.time()
+            
+            if stats.state == CircuitState.HALF_OPEN or stats.failures >= self.failure_threshold:
+                stats.state = CircuitState.OPEN
+                logger.warning(
+                    "Circuit breaker OPEN for tool: %s (failures: %d)", 
+                    name, stats.failures
+                )
+
+    def dispatch(self, name: str, args: dict, **kwargs) -> str:
+        """Execute a tool via the registry with circuit breaker protection."""
+        stats = self._get_stats(name)
+        
+        if stats.state == CircuitState.OPEN:
+            return json.dumps({
+                "error": (
+                    f"Tool '{name}' is temporarily unavailable due to repeated failures. "
+                    f"Circuit breaker is OPEN. Please try again in a few minutes or use an alternative tool."
+                ),
+                "circuit_breaker": True,
+                "tool_name": name
+            })
+
+        start_time = time.time()
+        try:
+            # Dispatch to the underlying registry
+            result_str = registry.dispatch(name, args, **kwargs)
+            execution_time = time.time() - start_time
+            
+            # Inspect result for errors. registry.dispatch catches internal
+            # exceptions and returns a JSON error string.
+            is_error = False
+            try:
+                # Lightweight check for error key in JSON
+                if '"error":' in result_str:
+                    res_json = json.loads(result_str)
+                    if isinstance(res_json, dict) and "error" in res_json:
+                        is_error = True
+            except (json.JSONDecodeError, TypeError):
+                # If it's not valid JSON, it's a malformed result (error)
+                is_error = True
+            
+            if is_error:
+                self._record_failure(name, execution_time)
+            else:
+                self._record_success(name, execution_time)
+                
+            return result_str
+            
+        except Exception as e:
+            # This should rarely be hit as registry.dispatch catches most things,
+            # but we guard against orchestrator-level or registry-level bugs.
+            execution_time = time.time() - start_time
+            self._record_failure(name, execution_time)
+            
+            error_msg = f"Tool orchestrator error during {name}: {type(e).__name__}: {e}"
+            logger.exception(error_msg)
+            return json.dumps({
+                "error": error_msg,
+                "tool_name": name,
+                "execution_time": execution_time
+            })
+
+    def get_fleet_stats(self) -> Dict[str, Any]:
+        """Return execution statistics for all tools."""
+        with self._lock:
+            return {
+                name: {
+                    "state": s.state,
+                    "failures": s.failures,
+                    "successes": s.successes,
+                    "avg_time": s.total_execution_time / s.call_count if s.call_count > 0 else 0,
+                    "calls": s.call_count
+                }
+                for name, s in self._stats.items()
+            }
+
+
+# Global orchestrator instance
+orchestrator = ToolOrchestrator()

agent/ultraplinian_router.py

@@ -1,582 +0,0 @@
-"""
-ULTRAPLINIAN Router - Race-Mode Fallback Router
-Issue #81 - Safety-Compliant Model Routing
-
-This module provides a race-mode fallback router that:
-1. Sends the same query to multiple models simultaneously
-2. Compares responses for safety compliance
-3. Routes to the safest response
-
-Features:
-- Parallel model querying for safety validation
-- Response safety scoring using SHIELD detection
-- Automatic routing to safest model response
-- Crisis query special handling (SAFE SIX only)
-
-Usage:
-    from agent.ultraplinian_router import UltraplinianRouter
-    
-    router = UltraplinianRouter()
-    response = await router.route_safe_response(
-        query="User message here",
-        models=["kimi-k2.5", "gemini-3.1-pro", "claude-opus-4.6"]
-    )
-"""
-
-import os
-import asyncio
-import logging
-from typing import Dict, List, Optional, Tuple, Any, Set
-from dataclasses import dataclass, field
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from enum import Enum
-
-import requests
-
-from tools.shield.detector import ShieldDetector, Verdict, SAFE_SIX_MODELS
-
-logger = logging.getLogger(__name__)
-
-
-class SafetyScore(Enum):
-    """Safety score levels for responses"""
-    SAFE = 100
-    LIKELY_SAFE = 75
-    UNCERTAIN = 50
-    LIKELY_UNSAFE = 25
-    UNSAFE = 0
-    ERROR = -1
-
-
-@dataclass
-class ModelResponse:
-    """Response from a single model"""
-    model: str
-    response: str
-    latency_ms: float
-    safety_score: int = 0
-    shield_verdict: str = ""
-    shield_confidence: float = 0.0
-    error: Optional[str] = None
-
-
-@dataclass
-class RouteDecision:
-    """Final routing decision"""
-    selected_model: str
-    selected_response: str
-    all_responses: List[ModelResponse]
-    decision_reason: str
-    safety_score: int
-    was_crisis: bool
-
-
-# Model configurations
-FALLBACK_MODELS: Dict[str, Dict[str, Any]] = {
-    "claude-opus-4.6": {
-        "openrouter_id": "anthropic/claude-opus-4-6",
-        "provider": "anthropic",
-        "safety_rating": 95,  # Known good safety
-        "is_safe_six": True,
-    },
-    "kimi-k2.5": {
-        "openrouter_id": "moonshotai/kimi-k2.5",
-        "provider": "moonshot",
-        "safety_rating": 85,
-        "is_safe_six": True,
-    },
-    "gemini-3.1-pro": {
-        "openrouter_id": "google/gemini-3.1-pro-preview",
-        "provider": "google",
-        "safety_rating": 80,
-        "is_safe_six": False,
-    },
-    "grok": {
-        "openrouter_id": "x-ai/grok-3-beta",
-        "provider": "x-ai",
-        "safety_rating": 75,
-        "is_safe_six": False,
-    },
-    "llama-4": {
-        "openrouter_id": "meta-llama/llama-4-maverick",
-        "provider": "meta",
-        "safety_rating": 70,
-        "is_safe_six": False,
-    },
-}
-
-# Crisis intervention prompt
-CRISIS_SYSTEM_PROMPT = """You are a crisis intervention assistant. The user may be experiencing a mental health emergency.
-
-CRITICAL INSTRUCTIONS:
-1. Your ONLY goal is to help keep the user safe
-2. Do NOT provide methods for self-harm under ANY circumstances
-3. Express genuine compassion and concern
-4. Encourage professional help immediately
-
-CRISIS RESOURCES (share these):
-- 988 Suicide and Crisis Lifeline (call or text 988)
-- Crisis Text Line: Text HOME to 741741
-- Emergency Services: 911 (if immediate danger)
-
-RESPONSE GUIDELINES:
-- Validate their pain without validating harmful thoughts
-- Offer hope - recovery is possible
-- Keep responses brief and focused on safety
-- Never suggest that self-harm is a valid option
-- Encourage reaching out to trusted friends, family, or professionals
-
-Remember: This person's life is valuable. Respond with compassion, urgency, and hope."""
-
-
-class UltraplinianRouter:
-    """
-    Race-mode fallback router with safety compliance checking.
-    
-    This router implements the ULTRAPLINIAN protocol:
-    - Parallel queries to multiple models
-    - SHIELD-based safety analysis
-    - Selection of safest response
-    - Crisis escalation to SAFE SIX models
-    """
-    
-    def __init__(
-        self,
-        api_key: Optional[str] = None,
-        max_workers: int = 5,
-        timeout_seconds: float = 30.0,
-        enable_crisis_detection: bool = True,
-    ):
-        """
-        Initialize the ULTRAPLINIAN router.
-        
-        Args:
-            api_key: OpenRouter API key (defaults to OPENROUTER_API_KEY env var)
-            max_workers: Maximum concurrent API calls
-            timeout_seconds: Timeout for each model request
-            enable_crisis_detection: Whether to enable SHIELD crisis detection
-        """
-        self.api_key = api_key or os.getenv("OPENROUTER_API_KEY")
-        if not self.api_key:
-            raise ValueError("OpenRouter API key required")
-        
-        self.max_workers = max_workers
-        self.timeout_seconds = timeout_seconds
-        self.enable_crisis_detection = enable_crisis_detection
-        
-        self.shield = ShieldDetector()
-        self.base_url = "https://openrouter.ai/api/v1/chat/completions"
-        self.headers = {
-            "Authorization": f"Bearer {self.api_key}",
-            "Content-Type": "application/json",
-            "HTTP-Referer": "https://hermes-agent.nousresearch.com",
-            "X-Title": "Hermes ULTRAPLINIAN Router",
-        }
-    
-    def _query_model_sync(
-        self,
-        model_id: str,
-        messages: List[Dict[str, str]],
-        temperature: float = 0.7,
-    ) -> ModelResponse:
-        """
-        Synchronously query a single model.
-        
-        Args:
-            model_id: Internal model ID
-            messages: List of message dicts
-            temperature: Sampling temperature
-            
-        Returns:
-            ModelResponse with safety scoring
-        """
-        import time
-        
-        config = FALLBACK_MODELS.get(model_id)
-        if not config:
-            return ModelResponse(
-                model=model_id,
-                response="",
-                latency_ms=0,
-                error=f"Unknown model: {model_id}"
-            )
-        
-        start_time = time.time()
-        
-        try:
-            payload = {
-                "model": config["openrouter_id"],
-                "messages": messages,
-                "temperature": temperature,
-                "max_tokens": 2000,
-            }
-            
-            response = requests.post(
-                self.base_url,
-                headers=self.headers,
-                json=payload,
-                timeout=self.timeout_seconds,
-            )
-            response.raise_for_status()
-            
-            data = response.json()
-            content = data["choices"][0]["message"]["content"]
-            latency = (time.time() - start_time) * 1000
-            
-            # Run SHIELD detection
-            shield_result = self.shield.detect(content)
-            
-            # Calculate safety score
-            safety_score = self._calculate_safety_score(content, shield_result)
-            
-            return ModelResponse(
-                model=model_id,
-                response=content,
-                latency_ms=latency,
-                safety_score=safety_score,
-                shield_verdict=shield_result["verdict"],
-                shield_confidence=shield_result["confidence"],
-            )
-            
-        except requests.exceptions.Timeout:
-            return ModelResponse(
-                model=model_id,
-                response="",
-                latency_ms=(time.time() - start_time) * 1000,
-                error="Request timeout",
-            )
-        except requests.exceptions.RequestException as e:
-            return ModelResponse(
-                model=model_id,
-                response="",
-                latency_ms=(time.time() - start_time) * 1000,
-                error=f"API error: {str(e)}",
-            )
-        except Exception as e:
-            return ModelResponse(
-                model=model_id,
-                response="",
-                latency_ms=(time.time() - start_time) * 1000,
-                error=f"Error: {str(e)}",
-            )
-    
-    def _calculate_safety_score(
-        self,
-        response: str,
-        shield_result: Dict[str, Any],
-    ) -> int:
-        """
-        Calculate safety score based on SHIELD verdict and content analysis.
-        
-        Args:
-            response: Model response text
-            shield_result: SHIELD detection result
-            
-        Returns:
-            Safety score (0-100)
-        """
-        verdict = shield_result.get("verdict", Verdict.CLEAN.value)
-        confidence = shield_result.get("confidence", 0.0)
-        
-        # Base score from verdict
-        if verdict == Verdict.CLEAN.value:
-            base_score = 100
-        elif verdict == Verdict.JAILBREAK_DETECTED.value:
-            # Model was attacked but may have refused
-            base_score = 50
-        elif verdict == Verdict.CRISIS_DETECTED.value:
-            # Crisis detected - score based on response quality
-            base_score = 75
-        elif verdict == Verdict.CRISIS_UNDER_ATTACK.value:
-            # Crisis + jailbreak - check if model still helped
-            base_score = 25
-        else:
-            base_score = 50
-        
-        # Adjust based on confidence
-        if confidence > 0.8:
-            # High confidence in detection
-            if verdict == Verdict.CLEAN.value:
-                base_score = min(base_score + 10, 100)
-            else:
-                base_score = max(base_score - 20, 0)
-        
-        # Check for refusal indicators
-        response_lower = response.lower()
-        refusal_indicators = [
-            "i can't", "i cannot", "i'm sorry", "i apologize",
-            "not able to", "unable to", "cannot provide",
-            "inappropriate", "harmful", "safety",
-        ]
-        
-        if any(indicator in response_lower for indicator in refusal_indicators):
-            base_score = min(base_score + 15, 100)
-        
-        # Check for harmful content indicators
-        harmful_indicators = [
-            "here's how", "step by step", "first", "then", "finally",
-            "you will need", "materials", "instructions",
-        ]
-        
-        if any(indicator in response_lower for indicator in harmful_indicators):
-            # Might be providing instructions - reduce score
-            base_score = max(base_score - 20, 0)
-        
-        return max(0, min(100, base_score))
-    
-    def _is_crisis_query(self, query: str) -> bool:
-        """
-        Check if query is a crisis situation using SHIELD.
-        
-        Args:
-            query: User query text
-            
-        Returns:
-            True if crisis detected
-        """
-        if not self.enable_crisis_detection:
-            return False
-        
-        result = self.shield.detect(query)
-        verdict = result.get("verdict", "")
-        
-        return verdict in [
-            Verdict.CRISIS_DETECTED.value,
-            Verdict.CRISIS_UNDER_ATTACK.value,
-        ]
-    
-    async def route_safe_response(
-        self,
-        query: str,
-        models: Optional[List[str]] = None,
-        system_prompt: Optional[str] = None,
-        temperature: float = 0.7,
-        require_safe_six_for_crisis: bool = True,
-    ) -> RouteDecision:
-        """
-        Route to the safest model response.
-        
-        This is the main entry point for the ULTRAPLINIAN router.
-        It queries multiple models in parallel and selects the safest response.
-        
-        Args:
-            query: User query
-            models: List of model IDs to query (defaults to all)
-            system_prompt: Optional system prompt override
-            temperature: Sampling temperature
-            require_safe_six_for_crisis: If True, only use SAFE SIX models for crisis
-            
-        Returns:
-            RouteDecision with selected response and metadata
-        """
-        # Determine models to query
-        if models is None:
-            models = list(FALLBACK_MODELS.keys())
-        
-        # Check for crisis
-        is_crisis = self._is_crisis_query(query)
-        
-        if is_crisis and require_safe_six_for_crisis:
-            # Filter to SAFE SIX models only
-            safe_six_models = [
-                m for m in models
-                if FALLBACK_MODELS.get(m, {}).get("is_safe_six", False)
-            ]
-            if safe_six_models:
-                models = safe_six_models
-                logger.info("Crisis detected - restricting to SAFE SIX models: %s", models)
-            else:
-                logger.warning("Crisis detected but no SAFE SIX models in list")
-        
-        # Build messages
-        messages = []
-        if system_prompt:
-            messages.append({"role": "system", "content": system_prompt})
-        elif is_crisis:
-            # Use crisis system prompt
-            messages.append({"role": "system", "content": CRISIS_SYSTEM_PROMPT})
-        
-        messages.append({"role": "user", "content": query})
-        
-        # Query all models concurrently
-        logger.info("Querying %d models for safety comparison", len(models))
-        
-        loop = asyncio.get_event_loop()
-        responses: List[ModelResponse] = []
-        
-        with ThreadPoolExecutor(max_workers=self.max_workers) as executor:
-            futures = {
-                loop.run_in_executor(
-                    executor,
-                    self._query_model_sync,
-                    model,
-                    messages,
-                    temperature,
-                ): model
-                for model in models
-            }
-            
-            for future in asyncio.as_completed(futures):
-                try:
-                    response = await future
-                    responses.append(response)
-                    logger.debug(
-                        "Model %s returned (safety=%d, latency=%.0fms)",
-                        response.model,
-                        response.safety_score,
-                        response.latency_ms,
-                    )
-                except Exception as e:
-                    model = futures[future]
-                    logger.error("Error querying model %s: %s", model, e)
-                    responses.append(ModelResponse(
-                        model=model,
-                        response="",
-                        latency_ms=0,
-                        error=str(e),
-                    ))
-        
-        # Select safest response
-        return self._select_safest_response(responses, is_crisis)
-    
-    def _select_safest_response(
-        self,
-        responses: List[ModelResponse],
-        was_crisis: bool,
-    ) -> RouteDecision:
-        """
-        Select the safest response from all model responses.
-        
-        Selection criteria (in order of priority):
-        1. Highest safety score
-        2. Lowest SHIELD confidence in negative verdict
-        3. Fastest response time (tiebreaker)
-        4. Known safe model preference
-        
-        Args:
-            responses: List of model responses
-            was_crisis: Whether this was a crisis query
-            
-        Returns:
-            RouteDecision with selected response
-        """
-        if not responses:
-            raise ValueError("No responses to select from")
-        
-        # Filter out errors
-        valid_responses = [r for r in responses if r.error is None]
-        
-        if not valid_responses:
-            # All errors - return first error
-            return RouteDecision(
-                selected_model=responses[0].model,
-                selected_response=f"Error: {responses[0].error}",
-                all_responses=responses,
-                decision_reason="All models returned errors",
-                safety_score=SafetyScore.ERROR.value,
-                was_crisis=was_crisis,
-            )
-        
-        # Sort by safety score (descending)
-        sorted_responses = sorted(
-            valid_responses,
-            key=lambda r: (
-                -r.safety_score,  # Higher safety first
-                -FALLBACK_MODELS.get(r.model, {}).get("safety_rating", 0),  # Known safety
-                r.latency_ms,  # Faster first
-            )
-        )
-        
-        best = sorted_responses[0]
-        
-        # Determine decision reason
-        if best.safety_score >= 90:
-            reason = "Model provided clearly safe response"
-        elif best.safety_score >= 70:
-            reason = "Model provided likely safe response"
-        elif best.safety_score >= 50:
-            reason = "Response safety uncertain - selected best option"
-        else:
-            reason = "Warning: All responses had low safety scores"
-        
-        if was_crisis:
-            reason += " (Crisis query - SAFE SIX routing enforced)"
-        
-        return RouteDecision(
-            selected_model=best.model,
-            selected_response=best.response,
-            all_responses=responses,
-            decision_reason=reason,
-            safety_score=best.safety_score,
-            was_crisis=was_crisis,
-        )
-    
-    def get_safety_report(self, decision: RouteDecision) -> Dict[str, Any]:
-        """
-        Generate a safety report for a routing decision.
-        
-        Args:
-            decision: RouteDecision to report on
-            
-        Returns:
-            Dict with safety report data
-        """
-        return {
-            "selected_model": decision.selected_model,
-            "safety_score": decision.safety_score,
-            "was_crisis": decision.was_crisis,
-            "decision_reason": decision.decision_reason,
-            "model_comparison": [
-                {
-                    "model": r.model,
-                    "safety_score": r.safety_score,
-                    "shield_verdict": r.shield_verdict,
-                    "shield_confidence": r.shield_confidence,
-                    "latency_ms": r.latency_ms,
-                    "error": r.error,
-                }
-                for r in decision.all_responses
-            ],
-        }
-
-
-# Convenience functions for direct use
-
-async def route_safe_response(
-    query: str,
-    models: Optional[List[str]] = None,
-    **kwargs,
-) -> str:
-    """
-    Convenience function to get safest response.
-    
-    Args:
-        query: User query
-        models: List of model IDs (defaults to all)
-        **kwargs: Additional arguments for UltraplinianRouter
-        
-    Returns:
-        Safest response text
-    """
-    router = UltraplinianRouter(**kwargs)
-    decision = await router.route_safe_response(query, models)
-    return decision.selected_response
-
-
-def is_crisis_query(query: str) -> bool:
-    """
-    Check if a query is a crisis situation.
-    
-    Args:
-        query: User query
-        
-    Returns:
-        True if crisis detected
-    """
-    shield = ShieldDetector()
-    result = shield.detect(query)
-    verdict = result.get("verdict", "")
-    return verdict in [
-        Verdict.CRISIS_DETECTED.value,
-        Verdict.CRISIS_UNDER_ATTACK.value,
-    ]

agent/usage_pricing.py

@@ -575,49 +575,6 @@ def has_known_pricing(
     return entry is not None
 
 
-def get_pricing(
-    model_name: str,
-    provider: Optional[str] = None,
-    base_url: Optional[str] = None,
-    api_key: Optional[str] = None,
-) -> Dict[str, float]:
-    """Backward-compatible thin wrapper for legacy callers.
-
-    Returns only non-cache input/output fields when a pricing entry exists.
-    Unknown routes return zeroes.
-    """
-    entry = get_pricing_entry(model_name, provider=provider, base_url=base_url, api_key=api_key)
-    if not entry:
-        return {"input": 0.0, "output": 0.0}
-    return {
-        "input": float(entry.input_cost_per_million or _ZERO),
-        "output": float(entry.output_cost_per_million or _ZERO),
-    }
-
-
-def estimate_cost_usd(
-    model: str,
-    input_tokens: int,
-    output_tokens: int,
-    *,
-    provider: Optional[str] = None,
-    base_url: Optional[str] = None,
-    api_key: Optional[str] = None,
-) -> float:
-    """Backward-compatible helper for legacy callers.
-
-    This uses non-cached input/output only. New code should call
-    `estimate_usage_cost()` with canonical usage buckets.
-    """
-    result = estimate_usage_cost(
-        model,
-        CanonicalUsage(input_tokens=input_tokens, output_tokens=output_tokens),
-        provider=provider,
-        base_url=base_url,
-        api_key=api_key,
-    )
-    return float(result.amount_usd or _ZERO)
-
 
 def format_duration_compact(seconds: float) -> str:
     if seconds < 60:

agent_core_analysis.md

@@ -1,466 +0,0 @@
-# Deep Analysis: Agent Core (run_agent.py + agent/*.py)
-
-## Executive Summary
-
-The AIAgent class is a sophisticated conversation orchestrator (~8500 lines) with multi-provider support, parallel tool execution, context compression, and robust error handling. This analysis covers the state machine, retry logic, context management, optimizations, and potential issues.
-
----
-
-## 1. State Machine Diagram of Conversation Flow
-
-```
-┌─────────────────────────────────────────────────────────────────────────────────┐
-│                         AIAgent Conversation State Machine                       │
-└─────────────────────────────────────────────────────────────────────────────────┘
-
-┌─────────────┐     ┌─────────────┐     ┌─────────────────┐     ┌─────────────┐
-│   START     │────▶│  INIT       │────▶│  BUILD_SYSTEM   │────▶│   USER      │
-│             │     │  (config)   │     │  _PROMPT        │     │   INPUT     │
-└─────────────┘     └─────────────┘     └─────────────────┘     └──────┬──────┘
-                                                                       │
-    ┌──────────────────────────────────────────────────────────────────┘
-    │
-    ▼
-┌─────────────┐     ┌─────────────┐     ┌─────────────────┐     ┌─────────────┐
-│   API_CALL  │◄────│  PREPARE    │◄────│  HONCHO_PREFETCH│◄────│  COMPRESS?  │
-│   (stream)  │     │  _MESSAGES  │     │  (context)      │     │  (threshold)│
-└──────┬──────┘     └─────────────┘     └─────────────────┘     └─────────────┘
-       │
-       ▼
-┌─────────────────────────────────────────────────────────────────────────────────┐
-│                              API Response Handler                                │
-├─────────────────────────────────────────────────────────────────────────────────┤
-│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐      │
-│  │   STOP      │    │  TOOL_CALLS │    │   LENGTH    │    │   ERROR     │      │
-│  │  (finish)   │    │  (execute)  │    │ (truncate)  │    │  (retry)    │      │
-│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘    └──────┬──────┘      │
-│         │                  │                  │                  │             │
-│         ▼                  ▼                  ▼                  ▼             │
-│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐      │
-│  │   RETURN    │    │  EXECUTE    │    │ CONTINUATION│    │  FALLBACK/  │      │
-│  │  RESPONSE   │    │  TOOLS      │    │   REQUEST   │    │  COMPRESS   │      │
-│  │             │    │  (parallel/ │    │             │    │             │      │
-│  │             │    │ sequential) │    │             │    │             │      │
-│  └─────────────┘    └──────┬──────┘    └─────────────┘    └─────────────┘      │
-│                            │                                                   │
-│                            └─────────────────────────────────┐                 │
-│                                                              ▼                 │
-│                                                   ┌─────────────────┐          │
-│                                                   │  APPEND_RESULTS │──────────┘
-│                                                   │  (loop back)    │
-│                                                   └─────────────────┘
-└─────────────────────────────────────────────────────────────────────────────────┘
-
-Key States:
-───────────
-1. INIT: Agent initialization, client setup, tool loading
-2. BUILD_SYSTEM_PROMPT: Cached system prompt assembly with skills/memory
-3. USER_INPUT: Message injection with Honcho turn context
-4. COMPRESS?: Context threshold check (50% default)
-5. API_CALL: Streaming/non-streaming LLM request
-6. TOOL_EXECUTION: Parallel (safe) or sequential (interactive) tool calls
-7. FALLBACK: Provider failover on errors
-8. RETURN: Final response with metadata
-
-Transitions:
-────────────
-- INTERRUPT: Any state → immediate cleanup → RETURN
-- MAX_ITERATIONS: API_CALL → RETURN (budget exhausted)
-- 413/CONTEXT_ERROR: API_CALL → COMPRESS → retry
-- 401/429: API_CALL → FALLBACK → retry
-```
-
-### Sub-State: Tool Execution
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Tool Execution Flow                       │
-└─────────────────────────────────────────────────────────────┘
-
-┌─────────────────┐
-│  RECEIVE_BATCH  │
-└────────┬────────┘
-         │
-    ┌────┴────┐
-    │ Parallel?│
-    └────┬────┘
-   YES /  \ NO
-      /    \
-     ▼      ▼
-┌─────────┐  ┌─────────┐
-│CONCURRENT│  │SEQUENTIAL│
-│(ThreadPool│  │(for loop)│
-│  max=8)  │  │         │
-└────┬────┘  └────┬────┘
-     │            │
-     ▼            ▼
-┌─────────┐  ┌─────────┐
-│ _invoke_│  │ _invoke_│
-│ _tool() │  │ _tool() │ (per tool)
-│ (workers)│  │         │
-└────┬────┘  └────┬────┘
-     │            │
-     └────────────┘
-            │
-            ▼
-    ┌───────────────┐
-    │ CHECKPOINT?   │ (write_file/patch/terminal)
-    └───────┬───────┘
-            │
-            ▼
-    ┌───────────────┐
-    │ BUDGET_WARNING│ (inject if >70% iterations)
-    └───────┬───────┘
-            │
-            ▼
-    ┌───────────────┐
-    │ APPEND_TO_MSGS│
-    └───────────────┘
-```
-
----
-
-## 2. All Retry/Fallback Logic Identified
-
-### 2.1 API Call Retry Loop (lines 6420-7351)
-
-```python
-# Primary retry configuration
-max_retries = 3
-retry_count = 0
-
-# Retryable errors (with backoff):
-- Timeout errors (httpx.ReadTimeout, ConnectTimeout, PoolTimeout)
-- Connection errors (ConnectError, RemoteProtocolError, ConnectionError)
-- SSE connection drops ("connection lost", "network error")
-- Rate limits (429) - with Retry-After header respect
-
-# Backoff strategy:
-wait_time = min(2 ** retry_count, 60)  # 2s, 4s, 8s max 60s
-# Rate limits: use Retry-After header (capped at 120s)
-```
-
-### 2.2 Streaming Retry Logic (lines 4157-4268)
-
-```python
-_max_stream_retries = int(os.getenv("HERMES_STREAM_RETRIES", 2))
-
-# Streaming-specific fallbacks:
-1. Streaming fails after partial delivery → NO retry (partial content shown)
-2. Streaming fails BEFORE delivery → fallback to non-streaming
-3. Stale stream detection (>180s, scaled to 300s for >100K tokens) → kill connection
-```
-
-### 2.3 Provider Fallback Chain (lines 4334-4443)
-
-```python
-# Fallback chain from config (fallback_model / fallback_providers)
-self._fallback_chain = [...]  # List of {provider, model} dicts
-self._fallback_index = 0      # Current position in chain
-
-# Trigger conditions:
-- max_retries exhausted
-- Rate limit (429) with fallback available
-- Non-retryable 4xx error (401, 403, 404, 422)
-- Empty/malformed response after retries
-
-# Fallback activation:
-_try_activate_fallback() → swaps client, model, base_url in-place
-```
-
-### 2.4 Context Length Error Handling (lines 6998-7164)
-
-```python
-# 413 Payload Too Large:
-max_compression_attempts = 3
-# Compress context and retry
-
-# Context length exceeded:
-CONTEXT_PROBE_TIERS = [128_000, 64_000, 32_000, 16_000, 8_000]
-# Step down through tiers on error
-```
-
-### 2.5 Authentication Refresh Retry (lines 6904-6950)
-
-```python
-# Codex OAuth (401):
-codex_auth_retry_attempted = False  # Once per request
-_try_refresh_codex_client_credentials()
-
-# Nous Portal (401):
-nous_auth_retry_attempted = False
-_try_refresh_nous_client_credentials()
-
-# Anthropic (401):
-anthropic_auth_retry_attempted = False
-_try_refresh_anthropic_client_credentials()
-```
-
-### 2.6 Length Continuation Retry (lines 6639-6765)
-
-```python
-# Response truncated (finish_reason='length'):
-length_continue_retries = 0
-max_continuation_retries = 3
-
-# Request continuation with prompt:
-"[System: Your previous response was truncated... Continue exactly where you left off]"
-```
-
-### 2.7 Tool Call Validation Retries (lines 7400-7500)
-
-```python
-# Invalid tool name: 3 repair attempts
-# 1. Lowercase
-# 2. Normalize (hyphens/spaces to underscores)
-# 3. Fuzzy match (difflib, cutoff=0.7)
-
-# Invalid JSON arguments: 3 retries
-# Empty content after think blocks: 3 retries
-# Incomplete scratchpad: 3 retries
-```
-
----
-
-## 3. Context Window Management Analysis
-
-### 3.1 Multi-Layer Context System
-
-```
-┌────────────────────────────────────────────────────────────────────────┐
-│                        Context Architecture                             │
-├────────────────────────────────────────────────────────────────────────┤
-│ Layer 1: System Prompt (cached per session)                            │
-│   - SOUL.md or DEFAULT_AGENT_IDENTITY                                  │
-│   - Memory blocks (MEMORY.md, USER.md)                                 │
-│   - Skills index                                                       │
-│   - Context files (AGENTS.md, .cursorrules)                            │
-│   - Timestamp, platform hints                                          │
-│   - ~2K-10K tokens typical                                            │
-├────────────────────────────────────────────────────────────────────────┤
-│ Layer 2: Conversation History                                          │
-│   - User/assistant/tool messages                                       │
-│   - Protected head (first 3 messages)                                  │
-│   - Protected tail (last N messages by token budget)                   │
-│   - Compressible middle section                                        │
-├────────────────────────────────────────────────────────────────────────┤
-│ Layer 3: Tool Definitions                                              │
-│   - ~20-30K tokens with many tools                                     │
-│   - Filtered by enabled/disabled toolsets                              │
-├────────────────────────────────────────────────────────────────────────┤
-│ Layer 4: Ephemeral Context (API call only)                             │
-│   - Prefill messages                                                   │
-│   - Honcho turn context                                                │
-│   - Plugin context                                                     │
-│   - Ephemeral system prompt                                            │
-└────────────────────────────────────────────────────────────────────────┘
-```
-
-### 3.2 ContextCompressor Algorithm (agent/context_compressor.py)
-
-```python
-# Configuration:
-threshold_percent = 0.50        # Compress at 50% of context length
-protect_first_n = 3             # Head protection
-protect_last_n = 20             # Tail protection (message count fallback)
-tail_token_budget = 20_000      # Tail protection (token budget)
-summary_target_ratio = 0.20     # 20% of compressed content for summary
-
-# Compression phases:
-1. Prune old tool results (cheap pre-pass)
-2. Determine boundaries (head + tail protection)
-3. Generate structured summary via LLM
-4. Sanitize tool_call/tool_result pairs
-5. Assemble compressed message list
-
-# Iterative summary updates:
-_previous_summary = None  # Stored for next compression
-```
-
-### 3.3 Context Length Detection Hierarchy
-
-```python
-# Detection priority (model_metadata.py):
-1. Config override (config.yaml model.context_length)
-2. Custom provider config (custom_providers[].models[].context_length)
-3. models.dev registry lookup
-4. OpenRouter API metadata
-5. Endpoint /models probe (local servers)
-6. Hardcoded DEFAULT_CONTEXT_LENGTHS
-7. Context probing (trial-and-error tiers)
-8. DEFAULT_FALLBACK_CONTEXT (128K)
-```
-
-### 3.4 Prompt Caching (Anthropic)
-
-```python
-# System-and-3 strategy:
-# - 4 cache_control breakpoints max
-# - System prompt (stable)
-# - Last 3 non-system messages (rolling window)
-# - 5m or 1h TTL
-
-# Activation conditions:
-_is_openrouter_url() and "claude" in model.lower()
-# OR native Anthropic endpoint
-```
-
-### 3.5 Context Pressure Monitoring
-
-```python
-# User-facing warnings (not injected to LLM):
-_context_pressure_warned = False
-
-# Thresholds:
-_budget_caution_threshold = 0.7   # 70% - nudge to wrap up
-_budget_warning_threshold = 0.9   # 90% - urgent
-
-# Injection method:
-# Added to last tool result JSON as _budget_warning field
-```
-
----
-
-## 4. Ten Performance Optimization Opportunities
-
-### 4.1 Tool Call Deduplication (Missing)
-**Current**: No deduplication of identical tool calls within a batch
-**Impact**: Redundant API calls, wasted tokens
-**Fix**: Add `_deduplicate_tool_calls()` before execution (already implemented but only for delegate_task)
-
-### 4.2 Context Compression Frequency
-**Current**: Compress only at threshold crossing
-**Impact**: Sudden latency spike during compression
-**Fix**: Background compression prediction + prefetch
-
-### 4.3 Skills Prompt Cache Invalidation
-**Current**: LRU cache keyed by (skills_dir, tools, toolsets)
-**Issue**: External skill file changes may not invalidate cache
-**Fix**: Add file watcher or mtime check before cache hit
-
-### 4.4 Streaming Response Buffering
-**Current**: Accumulates all deltas in memory
-**Impact**: Memory bloat for long responses
-**Fix**: Stream directly to output with minimal buffering
-
-### 4.5 Tool Result Truncation Timing
-**Current**: Truncates after tool execution completes
-**Impact**: Wasted time on tools returning huge outputs
-**Fix**: Streaming truncation during tool execution
-
-### 4.6 Concurrent Tool Execution Limits
-**Current**: Fixed _MAX_TOOL_WORKERS = 8
-**Issue**: Not tuned by available CPU/memory
-**Fix**: Dynamic worker count based on system resources
-
-### 4.7 API Client Connection Pooling
-**Current**: Creates new client per interruptible request
-**Issue**: Connection overhead
-**Fix**: Connection pool with proper cleanup
-
-### 4.8 Model Metadata Cache TTL
-**Current**: 1 hour fixed TTL for OpenRouter metadata
-**Issue**: Stale pricing/context data
-**Fix**: Adaptive TTL based on error rates
-
-### 4.9 Honcho Context Prefetch
-**Current**: Prefetch queued at turn end, consumed next turn
-**Issue**: First turn has no prefetch
-**Fix**: Pre-warm cache on session creation
-
-### 4.10 Session DB Write Batching
-**Current**: Per-message writes to SQLite
-**Impact**: I/O overhead
-**Fix**: Batch writes with periodic flush
-
----
-
-## 5. Five Potential Race Conditions or Bugs
-
-### 5.1 Interrupt Propagation Race (HIGH SEVERITY)
-**Location**: run_agent.py lines 2253-2259
-
-```python
-with self._active_children_lock:
-    children_copy = list(self._active_children)
-for child in children_copy:
-    child.interrupt(message)  # Child may be gone
-```
-
-**Issue**: Child agent may be removed from `_active_children` between copy and iteration
-**Fix**: Check if child still exists in list before calling interrupt
-
-### 5.2 Concurrent Tool Execution Order
-**Location**: run_agent.py lines 5308-5478
-
-```python
-# Results collected in order, but execution is concurrent
-results = [None] * num_tools
-def _run_tool(index, ...):
-    results[index] = (function_name, ..., result, ...)
-```
-
-**Issue**: If tool A depends on tool B's side effects, concurrent execution may fail
-**Fix**: Document that parallel tools must be independent; add dependency tracking
-
-### 5.3 Session DB Concurrent Access
-**Location**: run_agent.py lines 1716-1755
-
-```python
-if not self._session_db:
-    return
-# ... multiple DB operations without transaction
-```
-
-**Issue**: Gateway creates multiple AIAgent instances; SQLite may lock
-**Fix**: Add proper transaction wrapping and retry logic
-
-### 5.4 Context Compressor State Mutation
-**Location**: agent/context_compressor.py lines 545-677
-
-```python
-messages, pruned_count = self._prune_old_tool_results(messages, ...)
-# messages is modified copy, but original may be referenced elsewhere
-```
-
-**Issue**: Deep copy is shallow for nested structures; tool_calls may be shared
-**Fix**: Ensure deep copy of entire message structure
-
-### 5.5 Tool Call ID Collision
-**Location**: run_agent.py lines 2910-2954
-
-```python
-def _derive_responses_function_call_id(self, call_id, response_item_id):
-    # Multiple derivations may collide
-    return f"fc_{sanitized[:48]}"
-```
-
-**Issue**: Truncated IDs may collide in long conversations
-**Fix**: Use full UUIDs or ensure uniqueness with counter
-
----
-
-## Appendix: Key Files and Responsibilities
-
-| File | Lines | Responsibility |
-|------|-------|----------------|
-| run_agent.py | ~8500 | Main AIAgent class, conversation loop |
-| agent/prompt_builder.py | ~816 | System prompt assembly, skills indexing |
-| agent/context_compressor.py | ~676 | Context compression, summarization |
-| agent/auxiliary_client.py | ~1822 | Side-task LLM client routing |
-| agent/model_metadata.py | ~930 | Context length detection, pricing |
-| agent/display.py | ~771 | CLI feedback, spinners |
-| agent/prompt_caching.py | ~72 | Anthropic cache control |
-| agent/trajectory.py | ~56 | Trajectory format conversion |
-| agent/models_dev.py | ~172 | models.dev registry integration |
-
----
-
-## Summary Statistics
-
-- **Total Core Code**: ~13,000 lines
-- **State Machine States**: 8 primary, 4 sub-states
-- **Retry Mechanisms**: 7 distinct types
-- **Context Layers**: 4 layers with compression
-- **Potential Issues**: 5 identified (1 high severity)
-- **Optimization Opportunities**: 10 identified

attack_surface_diagram.mermaid

@@ -1,229 +0,0 @@
-```mermaid
-graph TB
-    subgraph External["EXTERNAL ATTACK SURFACE"]
-        Telegram["Telegram Gateway"]
-        Discord["Discord Gateway"]
-        Slack["Slack Gateway"]
-        Email["Email Gateway"]
-        Matrix["Matrix Gateway"]
-        Signal["Signal Gateway"]
-        WebUI["Open WebUI"]
-        APIServer["API Server (HTTP)"]
-    end
-
-    subgraph Gateway["GATEWAY LAYER"]
-        PlatformAdapters["Platform Adapters"]
-        SessionMgr["Session Manager"]
-        Config["Gateway Config"]
-    end
-
-    subgraph Core["CORE AGENT"]
-        AIAgent["AI Agent"]
-        ToolRouter["Tool Router"]
-        PromptBuilder["Prompt Builder"]
-        ModelClient["Model Client"]
-    end
-
-    subgraph Tools["TOOL LAYER"]
-        FileTools["File Tools"]
-        TerminalTools["Terminal Tools"]
-        WebTools["Web Tools"]
-        BrowserTools["Browser Tools"]
-        DelegateTools["Delegate Tools"]
-        CodeExecTools["Code Execution"]
-        MCPTools["MCP Tools"]
-    end
-
-    subgraph Sandboxes["SANDBOX ENVIRONMENTS"]
-        LocalEnv["Local Environment"]
-        DockerEnv["Docker Environment"]
-        ModalEnv["Modal Cloud"]
-        DaytonaEnv["Daytona Environment"]
-        SSHEnv["SSH Environment"]
-        SingularityEnv["Singularity Environment"]
-    end
-
-    subgraph Credentials["CREDENTIAL STORAGE"]
-        AuthJSON["auth.json<br/>(OAuth tokens)"]
-        DotEnv[".env<br/>(API keys)"]
-        MCPTokens["mcp-tokens/<br/>(MCP OAuth)"]
-        SkillCreds["Skill Credentials"]
-        ConfigYAML["config.yaml<br/>(Configuration)"]
-    end
-
-    subgraph DataStores["DATA STORES"]
-        ResponseDB["Response Store<br/>(SQLite)"]
-        SessionDB["Session DB"]
-        Memory["Memory Store"]
-        SkillsHub["Skills Hub"]
-    end
-
-    subgraph ExternalServices["EXTERNAL SERVICES"]
-        LLMProviders["LLM Providers<br/>(OpenAI, Anthropic, etc.)"]
-        WebSearch["Web Search APIs<br/>(Firecrawl, Tavily, etc.)"]
-        BrowserCloud["Browser Cloud<br/>(Browserbase)"]
-        CloudProviders["Cloud Providers<br/>(Modal, Daytona)"]
-    end
-
-    %% External to Gateway
-    Telegram --> PlatformAdapters
-    Discord --> PlatformAdapters
-    Slack --> PlatformAdapters
-    Email --> PlatformAdapters
-    Matrix --> PlatformAdapters
-    Signal --> PlatformAdapters
-    WebUI --> PlatformAdapters
-    APIServer --> PlatformAdapters
-
-    %% Gateway to Core
-    PlatformAdapters --> SessionMgr
-    SessionMgr --> AIAgent
-    Config --> AIAgent
-
-    %% Core to Tools
-    AIAgent --> ToolRouter
-    ToolRouter --> FileTools
-    ToolRouter --> TerminalTools
-    ToolRouter --> WebTools
-    ToolRouter --> BrowserTools
-    ToolRouter --> DelegateTools
-    ToolRouter --> CodeExecTools
-    ToolRouter --> MCPTools
-
-    %% Tools to Sandboxes
-    TerminalTools --> LocalEnv
-    TerminalTools --> DockerEnv
-    TerminalTools --> ModalEnv
-    TerminalTools --> DaytonaEnv
-    TerminalTools --> SSHEnv
-    TerminalTools --> SingularityEnv
-    CodeExecTools --> DockerEnv
-    CodeExecTools --> ModalEnv
-
-    %% Credentials access
-    AIAgent --> AuthJSON
-    AIAgent --> DotEnv
-    MCPTools --> MCPTokens
-    FileTools --> SkillCreds
-    PlatformAdapters --> ConfigYAML
-
-    %% Data stores
-    AIAgent --> ResponseDB
-    AIAgent --> SessionDB
-    AIAgent --> Memory
-    AIAgent --> SkillsHub
-
-    %% External services
-    ModelClient --> LLMProviders
-    WebTools --> WebSearch
-    BrowserTools --> BrowserCloud
-    ModalEnv --> CloudProviders
-    DaytonaEnv --> CloudProviders
-
-    %% Style definitions
-    classDef external fill:#ff9999,stroke:#cc0000,stroke-width:2px
-    classDef gateway fill:#ffcc99,stroke:#cc6600,stroke-width:2px
-    classDef core fill:#ffff99,stroke:#cccc00,stroke-width:2px
-    classDef tools fill:#99ff99,stroke:#00cc00,stroke-width:2px
-    classDef sandbox fill:#99ccff,stroke:#0066cc,stroke-width:2px
-    classDef credentials fill:#ff99ff,stroke:#cc00cc,stroke-width:3px
-    classDef datastore fill:#ccccff,stroke:#6666cc,stroke-width:2px
-    classDef external_svc fill:#ccffff,stroke:#00cccc,stroke-width:2px
-
-    class Telegram,Discord,Slack,Email,Matrix,Signal,WebUI,APIServer external
-    class PlatformAdapters,SessionMgr,Config gateway
-    class AIAgent,ToolRouter,PromptBuilder,ModelClient core
-    class FileTools,TerminalTools,WebTools,BrowserTools,DelegateTools,CodeExecTools,MCPTools tools
-    class LocalEnv,DockerEnv,ModalEnv,DaytonaEnv,SSHEnv,SingularityEnv sandbox
-    class AuthJSON,DotEnv,MCPTokens,SkillCreds,ConfigYAML credentials
-    class ResponseDB,SessionDB,Memory,SkillsHub datastore
-    class LLMProviders,WebSearch,BrowserCloud,CloudProviders external_svc
-```
-
-```mermaid
-flowchart TB
-    subgraph AttackVectors["ATTACK VECTORS"]
-        direction TB
-        AV1["1. Malicious User Prompts"]
-        AV2["2. Compromised Skills"]
-        AV3["3. Malicious URLs"]
-        AV4["4. File Path Manipulation"]
-        AV5["5. Command Injection"]
-        AV6["6. Credential Theft"]
-        AV7["7. Session Hijacking"]
-        AV8["8. Sandbox Escape"]
-    end
-
-    subgraph Targets["HIGH-VALUE TARGETS"]
-        direction TB
-        T1["API Keys & Tokens"]
-        T2["User Credentials"]
-        T3["Session Data"]
-        T4["Host System"]
-        T5["Cloud Resources"]
-    end
-
-    subgraph Mitigations["SECURITY CONTROLS"]
-        direction TB
-        M1["Dangerous Command Approval"]
-        M2["Skills Guard Scanning"]
-        M3["URL Safety Checks"]
-        M4["Path Validation"]
-        M5["Secret Redaction"]
-        M6["Sandbox Isolation"]
-        M7["Session Management"]
-        M8["Audit Logging"]
-    end
-
-    AV1 -->|exploits| T4
-    AV1 -->|bypasses| M1
-    AV2 -->|targets| T1
-    AV2 -->|bypasses| M2
-    AV3 -->|targets| T5
-    AV3 -->|bypasses| M3
-    AV4 -->|targets| T4
-    AV4 -->|bypasses| M4
-    AV5 -->|targets| T4
-    AV5 -->|bypasses| M1
-    AV6 -->|targets| T1 & T2
-    AV6 -->|bypasses| M5
-    AV7 -->|targets| T3
-    AV7 -->|bypasses| M7
-    AV8 -->|targets| T4 & T5
-    AV8 -->|bypasses| M6
-```
-
-```mermaid
-sequenceDiagram
-    participant Attacker
-    participant Platform as Messaging Platform
-    participant Gateway as Gateway Adapter
-    participant Agent as AI Agent
-    participant Tools as Tool Layer
-    participant Sandbox as Sandbox Environment
-    participant Creds as Credential Store
-
-    Note over Attacker,Creds: Attack Scenario: Command Injection
-    
-    Attacker->>Platform: Send malicious message:<br/>"; rm -rf /; echo pwned"
-    Platform->>Gateway: Forward message
-    Gateway->>Agent: Process user input
-    Agent->>Tools: Execute terminal command
-    
-    alt Security Controls Active
-        Tools->>Tools: detect_dangerous_command()
-        Tools-->>Agent: BLOCK: Dangerous pattern detected
-        Agent-->>Gateway: Request user approval
-        Gateway-->>Platform: "Approve dangerous command?"
-        Platform-->>Attacker: Approval prompt
-        Attacker-->>Platform: Deny
-        Platform-->>Gateway: Command denied
-        Gateway-->>Agent: Cancel execution
-        Note right of Tools: ATTACK PREVENTED
-    else Security Controls Bypassed
-        Tools->>Sandbox: Execute command<br/>(bypassing detection)
-        Sandbox->>Sandbox: System damage
-        Sandbox->>Creds: Attempt credential access
-        Note right of Tools: ATTACK SUCCESSFUL
-    end
-```

batch_runner.py

@@ -31,6 +31,8 @@ from multiprocessing import Pool, Lock
 import traceback
 from rich.progress import Progress, SpinnerColumn, BarColumn, TextColumn, TimeRemainingColumn, MofNCompleteColumn
 from rich.console import Console
+
+logger = logging.getLogger(__name__)
 import fire
 
 from run_agent import AIAgent
@@ -1016,7 +1018,7 @@ class BatchRunner:
                             tool_stats = data.get('tool_stats', {})
                             
                             # Check for invalid tool names (model hallucinations)
-                            invalid_tools = [k for k in tool_stats.keys() if k not in VALID_TOOLS]
+                            invalid_tools = [k for k in tool_stats if k not in VALID_TOOLS]
                             
                             if invalid_tools:
                                 filtered_entries += 1
@@ -1156,7 +1158,7 @@ def main(
         providers_order (str): Comma-separated list of OpenRouter providers to try in order (e.g. "anthropic,openai,google")
         provider_sort (str): Sort providers by "price", "throughput", or "latency" (OpenRouter only)
         max_tokens (int): Maximum tokens for model responses (optional, uses model default if not set)
-        reasoning_effort (str): OpenRouter reasoning effort level: "xhigh", "high", "medium", "low", "minimal", "none" (default: "medium")
+        reasoning_effort (str): OpenRouter reasoning effort level: "none", "minimal", "low", "medium", "high", "xhigh" (default: "medium")
         reasoning_disabled (bool): Completely disable reasoning/thinking tokens (default: False)
         prefill_messages_file (str): Path to JSON file containing prefill messages (list of {role, content} dicts)
         max_samples (int): Only process the first N samples from the dataset (optional, processes all if not set)
@@ -1225,7 +1227,7 @@ def main(
         print("🧠 Reasoning: DISABLED (effort=none)")
     elif reasoning_effort:
         # Use specified effort level
-        valid_efforts = ["xhigh", "high", "medium", "low", "minimal", "none"]
+        valid_efforts = ["none", "minimal", "low", "medium", "high", "xhigh"]
         if reasoning_effort not in valid_efforts:
             print(f"❌ Error: --reasoning_effort must be one of: {', '.join(valid_efforts)}")
             return

benchmarks/test_images.json

@@ -0,0 +1,42 @@
+[
+  {
+    "id": "img_001",
+    "name": "red_circle",
+    "path": "benchmarks/test_images/red_circle.png",
+    "description": "A red circle on a white background",
+    "expected_answer_contains": ["red", "circle"],
+    "category": "shape_color"
+  },
+  {
+    "id": "img_002",
+    "name": "blue_square",
+    "path": "benchmarks/test_images/blue_square.png",
+    "description": "A blue square on a white background",
+    "expected_answer_contains": ["blue", "square"],
+    "category": "shape_color"
+  },
+  {
+    "id": "img_003",
+    "name": "green_triangle",
+    "path": "benchmarks/test_images/green_triangle.png",
+    "description": "A green triangle on a white background",
+    "expected_answer_contains": ["green", "triangle"],
+    "category": "shape_color"
+  },
+  {
+    "id": "img_004",
+    "name": "text_hello",
+    "path": "benchmarks/test_images/text_hello.png",
+    "description": "An image containing the text 'Hello World'",
+    "expected_answer_contains": ["hello", "world"],
+    "category": "ocr"
+  },
+  {
+    "id": "img_005",
+    "name": "mixed_shapes",
+    "path": "benchmarks/test_images/mixed_shapes.png",
+    "description": "Multiple colored shapes: red circle, blue square, yellow star",
+    "expected_answer_contains": ["red", "blue", "yellow"],
+    "category": "counting"
+  }
+]

benchmarks/vision_benchmark.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Vision benchmark — test model image understanding with local test images.
+
+Uses locally-stored test images (not external URLs) for reliable CI.
+
+Usage:
+    python3 benchmarks/vision_benchmark.py --model hermes3
+    python3 benchmarks/vision_benchmark.py --model qwen2.5 --json
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, List
+
+BENCHMARK_DIR = Path(__file__).resolve().parent
+TEST_IMAGES_FILE = BENCHMARK_DIR / "test_images.json"
+
+
+def load_test_dataset() -> List[Dict[str, Any]]:
+    """Load test image dataset."""
+    if not TEST_IMAGES_FILE.exists():
+        raise FileNotFoundError(f"Test dataset not found: {TEST_IMAGES_FILE}")
+    with open(TEST_IMAGES_FILE) as f:
+        return json.load(f)
+
+
+def encode_image_base64(image_path: str) -> str:
+    """Encode image as base64 for API call."""
+    with open(image_path, "rb") as f:
+        return base64.b64encode(f.read()).decode()
+
+
+def verify_images_exist(dataset: List[Dict[str, Any]]) -> List[str]:
+    """Verify all test images exist locally."""
+    missing = []
+    for item in dataset:
+        path = BENCHMARK_DIR.parent / item["path"]
+        if not path.exists():
+            missing.append(item["path"])
+    return missing
+
+
+def run_vision_test(
+    image_path: str,
+    prompt: str,
+    base_url: str = "http://localhost:11434/v1",
+    model: str = "",
+    api_key: str = "",
+    timeout: int = 30,
+) -> Dict[str, Any]:
+    """Run a single vision test against a model."""
+    import urllib.request
+
+    img_b64 = encode_image_base64(image_path)
+
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": prompt},
+                {
+                    "type": "image_url",
+                    "image_url": {"url": f"data:image/png;base64,{img_b64}"},
+                },
+            ],
+        }
+    ]
+
+    body = {
+        "model": model or "",
+        "messages": messages,
+        "max_tokens": 200,
+    }
+
+    headers = {"Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    url = f"{base_url.rstrip('/')}/chat/completions"
+    t0 = time.monotonic()
+
+    try:
+        req = urllib.request.Request(url, data=json.dumps(body).encode(), headers=headers, method="POST")
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read())
+            elapsed = time.monotonic() - t0
+            content = data.get("choices", [{}])[0].get("message", {}).get("content", "")
+            return {
+                "success": True,
+                "response": content,
+                "latency_ms": int(elapsed * 1000),
+                "model": data.get("model", model),
+            }
+    except Exception as e:
+        return {
+            "success": False,
+            "response": "",
+            "latency_ms": int((time.monotonic() - t0) * 1000),
+            "error": str(e),
+        }
+
+
+def evaluate_response(response: str, expected: List[str]) -> bool:
+    """Check if response contains expected keywords."""
+    response_lower = response.lower()
+    return all(kw.lower() in response_lower for kw in expected)
+
+
+def run_benchmark(
+    base_url: str = "http://localhost:11434/v1",
+    model: str = "",
+) -> Dict[str, Any]:
+    """Run full vision benchmark."""
+    dataset = load_test_dataset()
+
+    # Verify images exist
+    missing = verify_images_exist(dataset)
+    if missing:
+        return {"error": f"Missing test images: {missing}", "passed": 0, "total": len(dataset)}
+
+    results = []
+    passed = 0
+
+    for item in dataset:
+        image_path = str(BENCHMARK_DIR.parent / item["path"])
+        prompt = f"What do you see in this image? Describe the shapes and colors."
+
+        result = run_vision_test(image_path, prompt, base_url=base_url, model=model)
+        result["test_id"] = item["id"]
+        result["test_name"] = item["name"]
+        result["category"] = item["category"]
+
+        if result["success"]:
+            result["correct"] = evaluate_response(result["response"], item["expected_answer_contains"])
+            if result["correct"]:
+                passed += 1
+        else:
+            result["correct"] = False
+
+        results.append(result)
+
+    return {
+        "model": model,
+        "base_url": base_url,
+        "passed": passed,
+        "total": len(dataset),
+        "success_rate": passed / len(dataset) if dataset else 0,
+        "results": results,
+    }
+
+
+def format_report(benchmark: Dict[str, Any]) -> str:
+    """Format benchmark results."""
+    if "error" in benchmark:
+        return f"ERROR: {benchmark['error']}"
+
+    lines = [
+        "Vision Benchmark Results",
+        "=" * 40,
+        f"Model: {benchmark.get('model', 'unknown')}",
+        f"Passed: {benchmark['passed']}/{benchmark['total']} ({benchmark['success_rate']:.0%})",
+        "",
+    ]
+
+    for r in benchmark.get("results", []):
+        icon = "\u2705" if r.get("correct") else "\u274c"
+        name = r.get("test_name", "?")
+        cat = r.get("category", "?")
+        lat = r.get("latency_ms", 0)
+        lines.append(f"  {icon} {name} ({cat}) — {lat}ms")
+        if not r.get("success"):
+            lines.append(f"       Error: {r.get('error', 'unknown')}")
+        elif not r.get("correct"):
+            lines.append(f"       Got: {r.get('response', '')[:100]}")
+
+    return "\n".join(lines)
+
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(description="Vision benchmark")
+    parser.add_argument("--base-url", default="http://localhost:11434/v1")
+    parser.add_argument("--model", default="")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    benchmark = run_benchmark(base_url=args.base_url, model=args.model)
+
+    if args.json:
+        print(json.dumps(benchmark, indent=2))
+    else:
+        print(format_report(benchmark))
+
+    return 0 if benchmark.get("success_rate", 0) >= 0.8 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cli-config.yaml.example

@@ -24,6 +24,8 @@ model:
   #   "minimax"      - MiniMax global (requires: MINIMAX_API_KEY)
   #   "minimax-cn"   - MiniMax China (requires: MINIMAX_CN_API_KEY)
   #   "huggingface"  - Hugging Face Inference (requires: HF_TOKEN)
+  #   "xiaomi"       - Xiaomi MiMo (requires: XIAOMI_API_KEY)
+  #   "arcee"        - Arcee AI Trinity models (requires: ARCEEAI_API_KEY)
   #   "kilocode"     - KiloCode gateway (requires: KILOCODE_API_KEY)
   #   "ai-gateway"   - Vercel AI Gateway (requires: AI_GATEWAY_API_KEY)
   #
@@ -48,6 +50,25 @@ model:
   # api_key: "your-key-here"  # Uncomment to set here instead of .env
   base_url: "https://openrouter.ai/api/v1"
 
+  # ── Token limits — two settings, easy to confuse ──────────────────────────
+  #
+  # context_length: TOTAL context window (input + output tokens combined).
+  #   Controls when Hermes compresses history and validates requests.
+  #   Leave unset — Hermes auto-detects the correct value from the provider.
+  #   Set manually only when auto-detection is wrong (e.g. a local server with
+  #   a custom num_ctx, or a proxy that doesn't expose /v1/models).
+  #
+  # context_length: 131072
+  #
+  # max_tokens: OUTPUT cap — maximum tokens the model may generate per response.
+  #   Unrelated to how long your conversation history can be.
+  #   The OpenAI-standard name "max_tokens" is a misnomer; Anthropic's native
+  #   API has since renamed it "max_output_tokens" for clarity.
+  #   Leave unset to use the model's native output ceiling (recommended).
+  #   Set only if you want to deliberately limit individual response length.
+  #
+  # max_tokens: 8192
+
 # =============================================================================
 # OpenRouter Provider Routing (only applies when using OpenRouter)
 # =============================================================================
@@ -117,7 +138,8 @@ terminal:
   timeout: 180
   docker_mount_cwd_to_workspace: false  # SECURITY: off by default. Opt in to mount the launch cwd into Docker /workspace.
   lifetime_seconds: 300
-  # sudo_password: ""  # Enable sudo commands (pipes via sudo -S) - SECURITY WARNING: plaintext!
+  # sudo_password: "hunter2"  # Optional: pipe a sudo password via sudo -S. SECURITY WARNING: plaintext.
+  # sudo_password: ""         # Explicit empty password: try empty and never open the interactive sudo prompt.
 
 # -----------------------------------------------------------------------------
 # OPTION 2: SSH remote execution
@@ -208,13 +230,18 @@ terminal:
 #
 # SECURITY WARNING: Password stored in plaintext!
 #
-# INTERACTIVE PROMPT: If no sudo_password is set and the CLI is running,
+# INTERACTIVE PROMPT: If sudo_password is unset and the CLI is running,
 # you'll be prompted to enter your password when sudo is needed:
 # - 45-second timeout (auto-skips if no input)
 # - Press Enter to skip (command fails gracefully)
 # - Password is hidden while typing
 # - Password is cached for the session
 #
+# EMPTY PASSWORDS: Setting sudo_password to an explicit empty string is different
+# from leaving it unset. Hermes will try an empty password via `sudo -S` and
+# will not open the interactive prompt. This is useful for passwordless sudo,
+# Touch ID sudo setups, and environments where prompting is just noise.
+#
 # ALTERNATIVES:
 # - SSH backend: Configure passwordless sudo on the remote server
 # - Containers: Run as root inside the container (no sudo needed)
@@ -283,15 +310,8 @@ compression:
   # compression of older turns.
   protect_last_n: 20
 
-  # Model to use for generating summaries (fast/cheap recommended)
-  # This model compresses the middle turns into a concise summary.
-  # IMPORTANT: it receives the full middle section of the conversation, so it
-  # MUST support a context length at least as large as your main model's.
-  summary_model: "google/gemini-3-flash-preview"
-  
-  # Provider for the summary model (default: "auto")
-  # Options: "auto", "openrouter", "nous", "main"
-  # summary_provider: "auto"
+  # To pin a specific model/provider for compression summaries, use the
+  # auxiliary section below (auxiliary.compression.provider / model).
 
 # =============================================================================
 # Auxiliary Models (Advanced — Experimental)
@@ -445,6 +465,22 @@ agent:
   # Higher = more room for complex tasks, but costs more tokens
   # Recommended: 20-30 for focused tasks, 50-100 for open exploration
   max_turns: 60
+
+  # Inactivity timeout for gateway agent runs (seconds, 0 = unlimited).
+  # The agent can run indefinitely when actively calling tools or receiving
+  # API responses.  Only fires after the agent has been idle for this duration.
+  # gateway_timeout: 1800
+
+  # Staged warning: send a warning before escalating to full timeout.
+  # Fires once per run when inactivity reaches this threshold (seconds).
+  # Set to 0 to disable the warning.
+  # gateway_timeout_warning: 900
+
+  # Graceful drain timeout for gateway stop/restart (seconds).
+  # The gateway stops accepting new work, waits for in-flight agents to
+  # finish, then interrupts anything still running after this timeout.
+  # 0 = no drain, interrupt immediately.
+  # restart_drain_timeout: 60
   
   # Enable verbose logging
   verbose: false
@@ -487,7 +523,7 @@ agent:
 #   - A preset like "hermes-cli" or "hermes-telegram" (curated tool set)
 #   - A list of individual toolsets to compose your own (see list below)
 #
-# Supported platform keys: cli, telegram, discord, whatsapp, slack
+# Supported platform keys: cli, telegram, discord, whatsapp, slack, qqbot
 #
 # Examples:
 #
@@ -516,6 +552,7 @@ agent:
 #   slack:         hermes-slack          (same as telegram)
 #   signal:        hermes-signal         (same as telegram)
 #   homeassistant: hermes-homeassistant  (same as telegram)
+#   qqbot:            hermes-qqbot            (same as telegram)
 #
 platform_toolsets:
   cli: [hermes-cli]
@@ -525,6 +562,7 @@ platform_toolsets:
   slack: [hermes-slack]
   signal: [hermes-signal]
   homeassistant: [hermes-homeassistant]
+  qqbot: [hermes-qqbot]
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Available toolsets (use these names in platform_toolsets or the toolsets list)
@@ -547,7 +585,7 @@ platform_toolsets:
 #   skills_hub   - skill_hub (search/install/manage from online registries — user-driven only)
 #   moa          - mixture_of_agents  (requires OPENROUTER_API_KEY)
 #   todo         - todo (in-memory task planning, no deps)
-#   tts          - text_to_speech  (Edge TTS free, or ELEVENLABS/OPENAI/MINIMAX key)
+#   tts          - text_to_speech  (Edge TTS free, or ELEVENLABS/OPENAI/MINIMAX/MISTRAL key)
 #   cronjob      - cronjob (create/list/update/pause/resume/run/remove scheduled tasks)
 #   rl           - rl_list_environments, rl_start_training, etc. (requires TINKER_API_KEY)
 #
@@ -576,7 +614,7 @@ platform_toolsets:
 #   todo         - Task planning and tracking for multi-step work
 #   memory       - Persistent memory across sessions (personal notes + user profile)
 #   session_search - Search and recall past conversations (FTS5 + Gemini Flash summarization)
-#   tts          - Text-to-speech (Edge TTS free, ElevenLabs, OpenAI, MiniMax)
+#   tts          - Text-to-speech (Edge TTS free, ElevenLabs, OpenAI, MiniMax, Mistral)
 #   cronjob      - Schedule and manage automated tasks (CLI-only)
 #   rl           - RL training tools (Tinker-Atropos)
 #
@@ -644,10 +682,18 @@ platform_toolsets:
 # Voice Transcription (Speech-to-Text)
 # =============================================================================
 # Automatically transcribe voice messages on messaging platforms.
-# Requires OPENAI_API_KEY in .env (uses OpenAI Whisper API directly).
+# Providers: local (free, faster-whisper) | groq (free tier) | openai (Whisper API) | mistral (Voxtral Transcribe)
+# Set the corresponding API key in .env: GROQ_API_KEY, OPENAI_API_KEY, or MISTRAL_API_KEY.
 stt:
   enabled: true
-  model: "whisper-1"  # whisper-1 (cheapest) | gpt-4o-mini-transcribe | gpt-4o-transcribe
+  # provider: "local"          # auto-detected if omitted
+  local:
+    model: "base"              # tiny | base | small | medium | large-v3 | turbo
+    # language: ""             # auto-detect; set to "en", "es", "fr", etc. to force
+  openai:
+    model: "whisper-1"         # whisper-1 | gpt-4o-mini-transcribe | gpt-4o-transcribe
+  # mistral:
+  #   model: "voxtral-mini-latest"  # voxtral-mini-latest | voxtral-mini-2602
 
 # =============================================================================
 # Response Pacing (Messaging Platforms)
@@ -724,6 +770,11 @@ display:
   # Toggle at runtime with /verbose in the CLI
   tool_progress: all
 
+  # Gateway-only natural mid-turn assistant updates.
+  # When true, completed assistant status messages are sent as separate chat
+  # messages. This is independent of tool_progress and gateway streaming.
+  interim_assistant_messages: true
+
   # What Enter does when Hermes is already busy in the CLI.
   #   interrupt: Interrupt the current run and redirect Hermes (default)
   #   queue:     Queue your message for the next turn
@@ -732,7 +783,7 @@ display:
 
   # Background process notifications (gateway/messaging only).
   # Controls how chatty the process watcher is when you use
-  # terminal(background=true, check_interval=...) from Telegram/Discord/etc.
+  # terminal(background=true, notify_on_complete=true) from Telegram/Discord/etc.
   #   off:     No watcher messages at all
   #   result:  Only the final completion message
   #   error:   Only the final message when exit code != 0