test(#798): Strengthen parallel tool calling tests + fix flaky concurrent tests

- Add TestAIAgentConcurrentExecution with 8 integration tests exercising
  _execute_tool_calls_concurrent through AIAgent for 2/3/4-tool batches,
  pass-rate reporting, and Gemma 4-style read patterns.
- Fix test_malformed_json_args_forces_sequential: use JSON array '[1,2,3]'
  instead of unrepairable garbage now that repair_and_load_json handles
  most malformed input.
- Fix test_concurrent_handles_tool_error: replace racy call_count list
  with deterministic failure based on tool_call_id to eliminate flaky
  failures under ThreadPoolExecutor.

Closes #798

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

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

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

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

.coveragerc

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

.dockerignore

@@ -5,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: 5
-    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 ".[all,dev]"
-
-      - name: Smoke tests
-        run: |
-          source .venv/bin/activate
-          python scripts/smoke_test.py
-        env:
-          OPENROUTER_API_KEY: ""
-          OPENAI_API_KEY: ""
-          NOUS_API_KEY: ""
-
-      - name: Syntax guard
-        run: |
-          source .venv/bin/activate
-          python scripts/syntax_guard.py
-
-      - name: 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
-        env:
-          OPENROUTER_API_KEY: ""
-          OPENAI_API_KEY: ""
-          NOUS_API_KEY: ""

.gitea/workflows/lint.yml

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

.gitea/workflows/notebook-ci.yml

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

.githooks/pre-commit

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

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

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

.githooks/pre-commit.py

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

.github/CODEOWNERS

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

.github/ISSUE_TEMPLATE/bug_report.yml

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

.github/ISSUE_TEMPLATE/feature_request.yml

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

.github/ISSUE_TEMPLATE/security_pr_checklist.yml

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

.github/ISSUE_TEMPLATE/setup_help.yml

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

.github/workflows/contributor-check.yml

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

.github/workflows/dependency-audit.yml

@@ -1,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,24 +28,32 @@ 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
+        run: pip install pyyaml==6.0.2 httpx==0.28.1
 
       - name: Extract skill metadata for dashboard
         run: python3 website/scripts/extract-skills.py
 
+      - name: Build skills index (if not already present)
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if [ ! -f website/static/api/skills-index.json ]; then
+            python3 scripts/build_skills_index.py || echo "Skills index build failed (non-fatal)"
+          fi
+
       - name: Install dependencies
         run: npm ci
         working-directory: website
@@ -65,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

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

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

@@ -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,20 @@ 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: Check for hardcoded paths
+        run: python3 scripts/lint_hardcoded_paths.py || true
+        continue-on-error: true
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86  # v5
 
       - name: Set up Python 3.11
         run: uv python install 3.11
@@ -47,10 +56,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,3 +61,4 @@ mini-swe-agent/
 # Nix
 .direnv/
 result
+website/static/api/skills-index.json

.mailmap

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

.pre-commit-config.yaml

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

AGENTS.md

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

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

PERFORMANCE_ANALYSIS_REPORT.md

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

PERFORMANCE_HOTSPOTS_QUICKREF.md

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

PERFORMANCE_OPTIMIZATIONS.md

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

README.md

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

RELEASE_v0.8.0.md

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

RELEASE_v0.9.0.md

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

SECURE_CODING_GUIDELINES.md

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

SECURITY_AUDIT_REPORT.md

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

SECURITY_FIXES_CHECKLIST.md

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

SECURITY_MITIGATION_ROADMAP.md

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

TEST_ANALYSIS_REPORT.md

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

TEST_OPTIMIZATION_GUIDE.md

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

V-006_FIX_SUMMARY.md

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

VECTOR_DB_RESEARCH_REPORT.md

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

acp_adapter/entry.py

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

acp_adapter/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/a2a_mtls.py

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

agent/agent_card.py

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

agent/anthropic_adapter.py

@@ -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/circuit_breaker.py

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

agent/conscience_mapping.py

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

agent/context_budget.py

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

agent/context_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/crisis_resources.py

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

agent/display.py

@@ -4,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/mtls.py

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

agent/nexus_architect.py

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

agent/nexus_deployment.py

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

agent/privacy_filter.py

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

agent/profile_isolation.py

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

agent/prompt_builder.py

@@ -12,7 +12,7 @@ import threading
 from collections import OrderedDict
 from pathlib import Path
 
-from hermes_constants import get_hermes_home
+from hermes_constants import get_hermes_home, get_skills_dir, is_wsl
 from typing import Optional
 
 from agent.skill_utils import (
@@ -40,7 +40,7 @@ _CONTEXT_THREAT_PATTERNS = [
     (r'disregard\s+(your|all|any)\s+(instructions|rules|guidelines)', "disregard_rules"),
     (r'act\s+as\s+(if|though)\s+you\s+(have\s+no|don\'t\s+have)\s+(restrictions|limits|rules)', "bypass_restrictions"),
     (r'<!--[^>]*(?:ignore|override|system|secret|hidden)[^>]*-->', "html_comment_injection"),
-    (r'<\s*div\s+style\s*=\s*["\'].*display\s*:\s*none', "hidden_div"),
+    (r'<\s*div\s+style\s*=\s*["\'][\s\S]*?display\s*:\s*none', "hidden_div"),
     (r'translate\s+.*\s+into\s+.*\s+and\s+(execute|run|eval)', "translate_execute"),
     (r'curl\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)', "exfil_curl"),
     (r'cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass)', "read_secrets"),
@@ -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/provider_preflight.py

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

agent/rate_limit_tracker.py

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

agent/retry_utils.py

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

agent/self_modify.py

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

agent/session_compactor.py

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

agent/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

@@ -181,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": (

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()