feat: transform NexusBridge into a client for the Nexus Gateway. Fixes #1135

Fixes #4647 — Signal replies duplicated when gateway streaming is enabled.

Root cause: stream_consumer.py did not handle the case where send() returns
success=True but no message_id (Signal behavior). Every stream delta produced
a separate send() call (7+ messages instead of 2), plus the gateway sent
another full duplicate since already_sent was never set.

Changes:
- stream_consumer.py: Add elif branch for success-without-message_id — enters
  fallback mode (sets already_sent, disables editing, sends only continuation)
- signal.py send(): Extract timestamp from signal-cli RPC result as message_id
  so stream consumer follows normal edit→fallback path
- signal.py: Add public stop_typing() delegating to _stop_typing_indicator()
  so base adapter's _keep_typing finally block can clean up typing tasks
- gateway/run.py: Per-platform tool_progress_overrides (#6164) — lets users
  set e.g. signal: off while keeping telegram: all
- hermes_cli/config.py: Add tool_progress_overrides to DEFAULT_CONFIG

Refs: #4647, #6164

.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

.env.example

@@ -81,6 +81,14 @@
 # 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
+
 # =============================================================================
 # TOOL API KEYS
 # =============================================================================

.gitea/workflows/ci.yml

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

.gitea/workflows/notebook-ci.yml

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

.githooks/pre-commit

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

.githooks/pre-commit.py

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

.github/CODEOWNERS

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

.github/ISSUE_TEMPLATE/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/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

@@ -41,19 +41,11 @@ jobs:
           python-version: '3.11'
 
       - name: Install PyYAML for skill extraction
-        run: pip install pyyaml httpx
+        run: pip install pyyaml
 
       - 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

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

@@ -10,7 +10,6 @@ on:
 jobs:
   docs-site-checks:
     runs-on: ubuntu-latest
-    container: catthehacker/ubuntu:act-22.04
     steps:
       - uses: actions/checkout@v4
 

.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

@@ -1,101 +0,0 @@
-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@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-
-      - name: Install dependencies
-        run: pip install httpx pyyaml
-
-      - 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@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@v4
-
-      - uses: actions/download-artifact@v4
-        with:
-          name: skills-index
-          path: website/static/api/
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
-          cache-dependency-path: website/package-lock.json
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-
-      - name: Install PyYAML for skill extraction
-        run: pip install pyyaml
-
-      - 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@v3
-        with:
-          path: _site
-
-      - name: Deploy to GitHub Pages
-        id: deploy
-        uses: actions/deploy-pages@v4

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

@@ -12,7 +12,6 @@ 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

.github/workflows/tests.yml

@@ -14,12 +14,14 @@ concurrency:
 jobs:
   test:
     runs-on: ubuntu-latest
-    container: catthehacker/ubuntu:act-22.04
     timeout-minutes: 10
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y ripgrep
+
       - name: Install uv
         uses: astral-sh/setup-uv@v5
 

.gitignore

@@ -58,6 +58,3 @@ mini-swe-agent/
 # Nix
 .direnv/
 result
-
-# OpenClaw artifacts (banned)
-.claw/

.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']

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.*

RELEASE_v0.2.0.md

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

RELEASE_v0.3.0.md

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

RELEASE_v0.4.0.md

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

RELEASE_v0.5.0.md

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

RELEASE_v0.6.0.md

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

RELEASE_v0.7.0.md

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

RELEASE_v0.8.0.md

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

SECURE_CODING_GUIDELINES.md

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

V-006_FIX_SUMMARY.md

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

acp_adapter/entry.py

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

acp_adapter/session.py

@@ -262,8 +262,6 @@ class SessionManager:
         if self._db_instance is not None:
             return self._db_instance
         try:
-            import os
-            from pathlib import Path
             from hermes_state import SessionDB
             hermes_home = get_hermes_home()
             self._db_instance = SessionDB(db_path=hermes_home / "state.db")

agent/__init__.py

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

agent/anthropic_adapter.py

@@ -163,6 +163,17 @@ def _is_oauth_token(key: str) -> bool:
     return True
 
 
+def _normalize_base_url_text(base_url) -> str:
+    """Normalize SDK/base transport URL values to a plain string for inspection.
+
+    Some client objects expose ``base_url`` as an ``httpx.URL`` instead of a raw
+    string.  Provider/auth detection should accept either shape.
+    """
+    if not base_url:
+        return ""
+    return str(base_url).strip()
+
+
 def _is_third_party_anthropic_endpoint(base_url: str | None) -> bool:
     """Return True for non-Anthropic endpoints using the Anthropic Messages API.
 
@@ -170,9 +181,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 +194,14 @@ 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 build_anthropic_client(api_key: str, base_url: str = None):
@@ -205,13 +216,14 @@ 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
 
-    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.
@@ -708,29 +720,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 = {
@@ -758,38 +747,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
 # ---------------------------------------------------------------------------
@@ -847,7 +804,7 @@ def _convert_openai_image_part_to_anthropic(part: Dict[str, Any]) -> Optional[Di
                 },
             }
 
-    if url.startswith("http://") or url.startswith("https://"):
+    if url.startswith(("http://", "https://")):
         return {
             "type": "image",
             "source": {
@@ -859,35 +816,6 @@ def _convert_openai_image_part_to_anthropic(part: Dict[str, Any]) -> Optional[Di
     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 +956,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 +1122,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 +1148,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,6 +1234,7 @@ def build_anthropic_kwargs(
     is_oauth: bool = False,
     preserve_dots: bool = False,
     context_length: Optional[int] = None,
+    base_url: str | None = None,
 ) -> Dict[str, Any]:
     """Build kwargs for anthropic.messages.create().
 
@@ -1232,8 +1248,11 @@ def build_anthropic_kwargs(
 
     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).
     """
-    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)
@@ -1310,9 +1329,9 @@ 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.
+    # Haiku and MiniMax models do 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():
+        if reasoning_config.get("enabled") is not False and "haiku" not in model.lower() and "minimax" not in model.lower():
             effort = str(reasoning_config.get("effort", "medium")).lower()
             budget = THINKING_BUDGET.get(effort, 8000)
             if _supports_adaptive_thinking(model):

agent/auxiliary_client.py

@@ -59,13 +59,48 @@ from hermes_constants import OPENROUTER_BASE_URL
 
 logger = logging.getLogger(__name__)
 
+_PROVIDER_ALIASES = {
+    "google": "gemini",
+    "google-gemini": "gemini",
+    "google-ai-studio": "gemini",
+    "glm": "zai",
+    "z-ai": "zai",
+    "z.ai": "zai",
+    "zhipu": "zai",
+    "kimi": "kimi-coding",
+    "moonshot": "kimi-coding",
+    "minimax-china": "minimax-cn",
+    "minimax_cn": "minimax-cn",
+    "claude": "anthropic",
+    "claude-code": "anthropic",
+}
+
+
+def _normalize_aux_provider(provider: Optional[str], *, for_vision: bool = False) -> str:
+    normalized = (provider or "auto").strip().lower()
+    if normalized.startswith("custom:"):
+        suffix = normalized.split(":", 1)[1].strip()
+        if not suffix:
+            return "custom"
+        normalized = suffix if not for_vision else "custom"
+    if normalized == "codex":
+        return "openai-codex"
+    if normalized == "main":
+        # Resolve to the user's actual main provider so named custom providers
+        # and non-aggregator providers (DeepSeek, Alibaba, etc.) work correctly.
+        main_prov = _read_main_provider()
+        if main_prov and main_prov not in ("auto", "main", ""):
+            return main_prov
+        return "custom"
+    return _PROVIDER_ALIASES.get(normalized, normalized)
+
 # Default auxiliary models for direct API-key providers (cheap/fast for side tasks)
 _API_KEY_PROVIDER_AUX_MODELS: Dict[str, str] = {
     "gemini": "gemini-3-flash-preview",
     "zai": "glm-4.5-flash",
     "kimi-coding": "kimi-k2-turbo-preview",
-    "minimax": "MiniMax-M2.7-highspeed",
-    "minimax-cn": "MiniMax-M2.7-highspeed",
+    "minimax": "MiniMax-M2.7",
+    "minimax-cn": "MiniMax-M2.7",
     "anthropic": "claude-haiku-4-5-20251001",
     "ai-gateway": "google/gemini-3-flash",
     "opencode-zen": "gemini-3-flash",
@@ -91,6 +126,8 @@ auxiliary_is_nous: bool = False
 # Default auxiliary models per provider
 _OPENROUTER_MODEL = "google/gemini-3-flash-preview"
 _NOUS_MODEL = "google/gemini-3-flash-preview"
+_NOUS_FREE_TIER_VISION_MODEL = "xiaomi/mimo-v2-omni"
+_NOUS_FREE_TIER_AUX_MODEL = "xiaomi/mimo-v2-pro"
 _NOUS_DEFAULT_BASE_URL = "https://inference-api.nousresearch.com/v1"
 _ANTHROPIC_DEFAULT_BASE_URL = "https://api.anthropic.com"
 _AUTH_JSON_PATH = get_hermes_home() / "auth.json"
@@ -104,6 +141,23 @@ _CODEX_AUX_MODEL = "gpt-5.2-codex"
 _CODEX_AUX_BASE_URL = "https://chatgpt.com/backend-api/codex"
 
 
+def _to_openai_base_url(base_url: str) -> str:
+    """Normalize an Anthropic-style base URL to OpenAI-compatible format.
+
+    Some providers (MiniMax, MiniMax-CN) expose an ``/anthropic`` endpoint for
+    the Anthropic Messages API and a separate ``/v1`` endpoint for OpenAI chat
+    completions.  The auxiliary client uses the OpenAI SDK, so it must hit the
+    ``/v1`` surface.  Passing the raw ``inference_base_url`` causes requests to
+    land on ``/anthropic/chat/completions`` — a 404.
+    """
+    url = str(base_url or "").strip().rstrip("/")
+    if url.endswith("/anthropic"):
+        rewritten = url[: -len("/anthropic")] + "/v1"
+        logger.debug("Auxiliary client: rewrote base URL %s → %s", url, rewritten)
+        return rewritten
+    return url
+
+
 def _select_pool_entry(provider: str) -> Tuple[bool, Optional[Any]]:
     """Return (pool_exists_for_provider, selected_entry)."""
     try:
@@ -208,7 +262,6 @@ class _CodexCompletionsAdapter:
     def create(self, **kwargs) -> Any:
         messages = kwargs.get("messages", [])
         model = kwargs.get("model", self._model)
-        temperature = kwargs.get("temperature")
 
         # Separate system/instructions from conversation messages.
         # Convert chat.completions multimodal content blocks to Responses
@@ -634,7 +687,9 @@ def _resolve_api_key_provider() -> Tuple[Optional[OpenAI], Optional[str]]:
             if not api_key:
                 continue
 
-            base_url = _pool_runtime_base_url(entry, pconfig.inference_base_url) or pconfig.inference_base_url
+            base_url = _to_openai_base_url(
+                _pool_runtime_base_url(entry, pconfig.inference_base_url) or pconfig.inference_base_url
+            )
             model = _API_KEY_PROVIDER_AUX_MODELS.get(provider_id, "default")
             logger.debug("Auxiliary text client: %s (%s) via pool", pconfig.name, model)
             extra = {}
@@ -651,7 +706,9 @@ def _resolve_api_key_provider() -> Tuple[Optional[OpenAI], Optional[str]]:
         if not api_key:
             continue
 
-        base_url = str(creds.get("base_url", "")).strip().rstrip("/") or pconfig.inference_base_url
+        base_url = _to_openai_base_url(
+            str(creds.get("base_url", "")).strip().rstrip("/") or pconfig.inference_base_url
+        )
         model = _API_KEY_PROVIDER_AUX_MODELS.get(provider_id, "default")
         logger.debug("Auxiliary text client: %s (%s)", pconfig.name, model)
         extra = {}
@@ -713,14 +770,27 @@ def _try_openrouter() -> Tuple[Optional[OpenAI], Optional[str]]:
                    default_headers=_OR_HEADERS), _OPENROUTER_MODEL
 
 
-def _try_nous() -> Tuple[Optional[OpenAI], Optional[str]]:
+def _try_nous(vision: bool = False) -> Tuple[Optional[OpenAI], Optional[str]]:
     nous = _read_nous_auth()
     if not nous:
         return None, None
     global auxiliary_is_nous
     auxiliary_is_nous = True
     logger.debug("Auxiliary client: Nous Portal")
-    model = "gemini-3-flash" if nous.get("source") == "pool" else _NOUS_MODEL
+    if nous.get("source") == "pool":
+        model = "gemini-3-flash"
+    else:
+        model = _NOUS_MODEL
+    # Free-tier users can't use paid auxiliary models — use the free
+    # models instead: mimo-v2-omni for vision, mimo-v2-pro for text tasks.
+    try:
+        from hermes_cli.models import check_nous_free_tier
+        if check_nous_free_tier():
+            model = _NOUS_FREE_TIER_VISION_MODEL if vision else _NOUS_FREE_TIER_AUX_MODEL
+            logger.debug("Free-tier Nous account — using %s for auxiliary/%s",
+                         model, "vision" if vision else "text")
+    except Exception:
+        pass
     return (
         OpenAI(
             api_key=_nous_api_key(nous),
@@ -922,7 +992,6 @@ def _resolve_forced_provider(forced: str) -> Tuple[Optional[OpenAI], Optional[st
 _AUTO_PROVIDER_LABELS = {
     "_try_openrouter": "openrouter",
     "_try_nous": "nous",
-    "_try_ollama": "ollama",
     "_try_custom_endpoint": "local/custom",
     "_try_codex": "openai-codex",
     "_resolve_api_key_provider": "api-key",
@@ -931,18 +1000,6 @@ _AUTO_PROVIDER_LABELS = {
 _AGGREGATOR_PROVIDERS = frozenset({"openrouter", "nous"})
 
 
-def _try_ollama() -> Tuple[Optional[OpenAI], Optional[str]]:
-    """Detect and return an Ollama client if the server is reachable."""
-    base_url = (os.getenv("OLLAMA_BASE_URL", "") or "http://localhost:11434").strip().rstrip("/")
-    base_url = base_url + "/v1" if not base_url.endswith("/v1") else base_url
-    from agent.model_metadata import detect_local_server_type
-    if detect_local_server_type(base_url) != "ollama":
-        return None, None
-    api_key = (os.getenv("OLLAMA_API_KEY", "") or "ollama").strip()
-    model = _read_main_model() or "gemma4:12b"
-    return OpenAI(api_key=api_key, base_url=base_url), model
-
-
 def _get_provider_chain() -> List[tuple]:
     """Return the ordered provider detection chain.
 
@@ -952,7 +1009,6 @@ def _get_provider_chain() -> List[tuple]:
     return [
         ("openrouter", _try_openrouter),
         ("nous", _try_nous),
-        ("ollama", _try_ollama),
         ("local/custom", _try_custom_endpoint),
         ("openai-codex", _try_codex),
         ("api-key", _resolve_api_key_provider),
@@ -1002,7 +1058,6 @@ def _try_payment_fallback(
     # Map common resolved_provider values back to chain labels.
     _alias_to_label = {"openrouter": "openrouter", "nous": "nous",
                        "openai-codex": "openai-codex", "codex": "openai-codex",
-                       "ollama": "ollama",
                        "custom": "local/custom", "local/custom": "local/custom"}
     skip_chain_labels = {_alias_to_label.get(s, s) for s in skip_labels}
 
@@ -1141,11 +1196,7 @@ def resolve_provider_client(
         (client, resolved_model) or (None, None) if auth is unavailable.
     """
     # Normalise aliases
-    provider = (provider or "auto").strip().lower()
-    if provider == "codex":
-        provider = "openai-codex"
-    if provider == "main":
-        provider = "custom"
+    provider = _normalize_aux_provider(provider)
 
     # ── Auto: try all providers in priority order ────────────────────
     if provider == "auto":
@@ -1210,15 +1261,6 @@ def resolve_provider_client(
         return (_to_async_client(client, final_model) if async_mode
                 else (client, final_model))
 
-    # ── Ollama (first-class local provider) ──────────────────────────
-    if provider == "ollama":
-        base_url = (explicit_base_url or os.getenv("OLLAMA_BASE_URL", "") or "http://localhost:11434").strip().rstrip("/")
-        base_url = base_url + "/v1" if not base_url.endswith("/v1") else base_url
-        api_key = (explicit_api_key or os.getenv("OLLAMA_API_KEY", "") or "ollama").strip()
-        final_model = model or _read_main_model() or "gemma4:12b"
-        client = OpenAI(api_key=api_key, base_url=base_url)
-        return (_to_async_client(client, final_model) if async_mode else (client, final_model))
-
     # ── Custom endpoint (OPENAI_BASE_URL + OPENAI_API_KEY) ───────────
     if provider == "custom":
         if explicit_base_url:
@@ -1250,6 +1292,28 @@ def resolve_provider_client(
                        "but no endpoint credentials found")
         return None, None
 
+    # ── Named custom providers (config.yaml custom_providers list) ───
+    try:
+        from hermes_cli.runtime_provider import _get_named_custom_provider
+        custom_entry = _get_named_custom_provider(provider)
+        if custom_entry:
+            custom_base = custom_entry.get("base_url", "").strip()
+            custom_key = custom_entry.get("api_key", "").strip() or "no-key-required"
+            if custom_base:
+                final_model = model or _read_main_model() or "gpt-4o-mini"
+                client = OpenAI(api_key=custom_key, base_url=custom_base)
+                logger.debug(
+                    "resolve_provider_client: named custom provider %r (%s)",
+                    provider, final_model)
+                return (_to_async_client(client, final_model) if async_mode
+                        else (client, final_model))
+            logger.warning(
+                "resolve_provider_client: named custom provider %r has no base_url",
+                provider)
+            return None, None
+    except ImportError:
+        pass
+
     # ── API-key providers from PROVIDER_REGISTRY ─────────────────────
     try:
         from hermes_cli.auth import PROVIDER_REGISTRY, resolve_api_key_provider_credentials
@@ -1282,7 +1346,9 @@ def resolve_provider_client(
                          provider, ", ".join(tried_sources))
             return None, None
 
-        base_url = str(creds.get("base_url", "")).strip().rstrip("/") or pconfig.inference_base_url
+        base_url = _to_openai_base_url(
+            str(creds.get("base_url", "")).strip().rstrip("/") or pconfig.inference_base_url
+        )
 
         default_model = _API_KEY_PROVIDER_AUX_MODELS.get(provider, "")
         final_model = model or default_model
@@ -1359,20 +1425,11 @@ def get_async_text_auxiliary_client(task: str = ""):
 _VISION_AUTO_PROVIDER_ORDER = (
     "openrouter",
     "nous",
-    "ollama",
-    "openai-codex",
-    "anthropic",
-    "custom",
 )
 
 
 def _normalize_vision_provider(provider: Optional[str]) -> str:
-    provider = (provider or "auto").strip().lower()
-    if provider == "codex":
-        return "openai-codex"
-    if provider == "main":
-        return "custom"
-    return provider
+    return _normalize_aux_provider(provider, for_vision=True)
 
 
 def _resolve_strict_vision_backend(provider: str) -> Tuple[Optional[Any], Optional[str]]:
@@ -1380,7 +1437,7 @@ def _resolve_strict_vision_backend(provider: str) -> Tuple[Optional[Any], Option
     if provider == "openrouter":
         return _try_openrouter()
     if provider == "nous":
-        return _try_nous()
+        return _try_nous(vision=True)
     if provider == "openai-codex":
         return _try_codex()
     if provider == "anthropic":
@@ -1413,17 +1470,26 @@ def _preferred_main_vision_provider() -> Optional[str]:
 def get_available_vision_backends() -> List[str]:
     """Return the currently available vision backends in auto-selection order.
 
-    This is the single source of truth for setup, tool gating, and runtime
-    auto-routing of vision tasks. The selected main provider is preferred when
-    it is also a known-good vision backend; otherwise Hermes falls back through
-    the standard conservative order.
+    Order: active provider → OpenRouter → Nous → stop.  This is the single
+    source of truth for setup, tool gating, and runtime auto-routing of
+    vision tasks.
     """
-    ordered = list(_VISION_AUTO_PROVIDER_ORDER)
-    preferred = _preferred_main_vision_provider()
-    if preferred in ordered:
-        ordered.remove(preferred)
-        ordered.insert(0, preferred)
-    return [provider for provider in ordered if _strict_vision_backend_available(provider)]
+    available: List[str] = []
+    # 1. Active provider — if the user configured a provider, try it first.
+    main_provider = _read_main_provider()
+    if main_provider and main_provider not in ("auto", ""):
+        if main_provider in _VISION_AUTO_PROVIDER_ORDER:
+            if _strict_vision_backend_available(main_provider):
+                available.append(main_provider)
+        else:
+            client, _ = resolve_provider_client(main_provider, _read_main_model())
+            if client is not None:
+                available.append(main_provider)
+    # 2. OpenRouter, 3. Nous — skip if already covered by main provider.
+    for p in _VISION_AUTO_PROVIDER_ORDER:
+        if p not in available and _strict_vision_backend_available(p):
+            available.append(p)
+    return available
 
 
 def resolve_vision_provider_client(
@@ -1468,16 +1534,39 @@ def resolve_vision_provider_client(
         return "custom", client, final_model
 
     if requested == "auto":
-        ordered = list(_VISION_AUTO_PROVIDER_ORDER)
-        preferred = _preferred_main_vision_provider()
-        if preferred in ordered:
-            ordered.remove(preferred)
-            ordered.insert(0, preferred)
+        # Vision auto-detection order:
+        #   1. Active provider + model (user's main chat config)
+        #   2. OpenRouter  (known vision-capable default model)
+        #   3. Nous Portal (known vision-capable default model)
+        #   4. Stop
+        main_provider = _read_main_provider()
+        main_model = _read_main_model()
+        if main_provider and main_provider not in ("auto", ""):
+            if main_provider in _VISION_AUTO_PROVIDER_ORDER:
+                # Known strict backend — use its defaults.
+                sync_client, default_model = _resolve_strict_vision_backend(main_provider)
+                if sync_client is not None:
+                    return _finalize(main_provider, sync_client, default_model)
+            else:
+                # Exotic provider (DeepSeek, Alibaba, named custom, etc.)
+                rpc_client, rpc_model = resolve_provider_client(
+                    main_provider, main_model)
+                if rpc_client is not None:
+                    logger.info(
+                        "Vision auto-detect: using active provider %s (%s)",
+                        main_provider, rpc_model or main_model,
+                    )
+                    return _finalize(
+                        main_provider, rpc_client, rpc_model or main_model)
 
-        for candidate in ordered:
+        # Fall back through aggregators.
+        for candidate in _VISION_AUTO_PROVIDER_ORDER:
+            if candidate == main_provider:
+                continue  # already tried above
             sync_client, default_model = _resolve_strict_vision_backend(candidate)
             if sync_client is not None:
                 return _finalize(candidate, sync_client, default_model)
+
         logger.debug("Auxiliary vision client: none available")
         return None, None, None
 

agent/builtin_memory_provider.py

@@ -13,9 +13,10 @@ from __future__ import annotations
 
 import json
 import logging
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List
 
 from agent.memory_provider import MemoryProvider
+from tools.registry import tool_error
 
 logger = logging.getLogger(__name__)
 
@@ -92,7 +93,7 @@ class BuiltinMemoryProvider(MemoryProvider):
 
     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"})
+        return tool_error("Built-in memory tool is handled by the agent loop")
 
     def shutdown(self) -> None:
         """No cleanup needed — files are saved on every write."""

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

@@ -343,10 +343,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")

agent/credential_pool.py

@@ -10,21 +10,18 @@ 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,
     _codex_access_token_is_expiring,
     _decode_jwt_claims,
     _import_codex_cli_tokens,
-    _is_expiring,
     _load_auth_store,
     _load_provider_state,
     _resolve_zai_base_url,

agent/display.py

@@ -986,24 +986,6 @@ def _osc8_link(url: str, text: str) -> str:
     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/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/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/memory.py

@@ -1,328 +0,0 @@
-"""Memory Backend — pluggable cross-session user modeling.
-
-Three backends:
-  - NullBackend: zero overhead when disabled (default)
-  - LocalBackend: SQLite at ~/.hermes/memory.db (sovereign, default when enabled)
-  - HonchoBackend: opt-in cloud via HONCHO_API_KEY
-
-Evaluation shows Local scores A (~95pts) vs Honcho B (~60pts).
-Recommendation: local for sovereignty.
-"""
-
-import json
-import logging
-import os
-import sqlite3
-import time
-from abc import ABC, abstractmethod
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-from hermes_constants import get_hermes_home
-
-logger = logging.getLogger(__name__)
-DB_PATH = get_hermes_home() / "memory.db"
-
-
-@dataclass
-class Entry:
-    key: str
-    value: str
-    user_id: str
-    etype: str = "preference"
-    confidence: float = 1.0
-    created_at: float = 0
-    updated_at: float = 0
-    metadata: Dict = field(default_factory=dict)
-
-    def __post_init__(self):
-        now = time.time()
-        if not self.created_at:
-            self.created_at = now
-        if not self.updated_at:
-            self.updated_at = now
-
-
-class Backend(ABC):
-    @abstractmethod
-    def available(self) -> bool: ...
-    @abstractmethod
-    def store(self, uid: str, key: str, val: str, meta: Dict = None) -> bool: ...
-    @abstractmethod
-    def get(self, uid: str, key: str) -> Optional[Entry]: ...
-    @abstractmethod
-    def query(self, uid: str, text: str, limit: int = 10) -> List[Entry]: ...
-    @abstractmethod
-    def list(self, uid: str) -> List[Entry]: ...
-    @abstractmethod
-    def delete(self, uid: str, key: str) -> bool: ...
-    @property
-    @abstractmethod
-    def name(self) -> str: ...
-    @property
-    @abstractmethod
-    def cloud(self) -> bool: ...
-
-
-class NullBackend(Backend):
-    def available(self) -> bool: return True
-    def store(self, uid, key, val, meta=None) -> bool: return True
-    def get(self, uid, key) -> Optional[Entry]: return None
-    def query(self, uid, text, limit=10) -> List[Entry]: return []
-    def list(self, uid) -> List[Entry]: return []
-    def delete(self, uid, key) -> bool: return True
-    @property
-    def name(self) -> str: return "null"
-    @property
-    def cloud(self) -> bool: return False
-
-
-class LocalBackend(Backend):
-    def __init__(self, path: Path = None):
-        self._path = path or DB_PATH
-        self._init()
-
-    def _init(self):
-        self._path.parent.mkdir(parents=True, exist_ok=True)
-        with sqlite3.connect(str(self._path)) as c:
-            c.execute("""CREATE TABLE IF NOT EXISTS mem (
-                uid TEXT, key TEXT, val TEXT, etype TEXT DEFAULT 'preference',
-                conf REAL DEFAULT 1.0, meta TEXT, created REAL, updated REAL,
-                PRIMARY KEY(uid, key))""")
-            c.commit()
-
-    def available(self) -> bool:
-        try:
-            with sqlite3.connect(str(self._path)) as c:
-                c.execute("SELECT 1")
-            return True
-        except Exception:
-            return False
-
-    def store(self, uid, key, val, meta=None) -> bool:
-        try:
-            now = time.time()
-            etype = (meta or {}).get("type", "preference")
-            with sqlite3.connect(str(self._path)) as c:
-                c.execute("""INSERT INTO mem (uid,key,val,etype,meta,created,updated)
-                    VALUES (?,?,?,?,?,?,?) ON CONFLICT(uid,key) DO UPDATE SET
-                    val=excluded.val,etype=excluded.etype,meta=excluded.meta,updated=excluded.updated""",
-                    (uid, key, val, etype, json.dumps(meta) if meta else None, now, now))
-                c.commit()
-            return True
-        except Exception as e:
-            logger.warning("Store failed: %s", e)
-            return False
-
-    def get(self, uid, key) -> Optional[Entry]:
-        try:
-            with sqlite3.connect(str(self._path)) as c:
-                r = c.execute("SELECT key,val,uid,etype,conf,meta,created,updated FROM mem WHERE uid=? AND key=?", (uid, key)).fetchone()
-            if not r:
-                return None
-            return Entry(key=r[0], value=r[1], user_id=r[2], etype=r[3], confidence=r[4],
-                        metadata=json.loads(r[5]) if r[5] else {}, created_at=r[6], updated_at=r[7])
-        except Exception:
-            return None
-
-    def query(self, uid, text, limit=10) -> List[Entry]:
-        try:
-            p = f"%{text}%"
-            with sqlite3.connect(str(self._path)) as c:
-                rows = c.execute("""SELECT key,val,uid,etype,conf,meta,created,updated FROM mem
-                    WHERE uid=? AND (key LIKE ? OR val LIKE ?) ORDER BY updated DESC LIMIT ?""",
-                    (uid, p, p, limit)).fetchall()
-            return [Entry(key=r[0], value=r[1], user_id=r[2], etype=r[3], confidence=r[4],
-                         metadata=json.loads(r[5]) if r[5] else {}, created_at=r[6], updated_at=r[7]) for r in rows]
-        except Exception:
-            return []
-
-    def list(self, uid) -> List[Entry]:
-        try:
-            with sqlite3.connect(str(self._path)) as c:
-                rows = c.execute("SELECT key,val,uid,etype,conf,meta,created,updated FROM mem WHERE uid=? ORDER BY updated DESC", (uid,)).fetchall()
-            return [Entry(key=r[0], value=r[1], user_id=r[2], etype=r[3], confidence=r[4],
-                         metadata=json.loads(r[5]) if r[5] else {}, created_at=r[6], updated_at=r[7]) for r in rows]
-        except Exception:
-            return []
-
-    def delete(self, uid, key) -> bool:
-        try:
-            with sqlite3.connect(str(self._path)) as c:
-                c.execute("DELETE FROM mem WHERE uid=? AND key=?", (uid, key))
-                c.commit()
-            return True
-        except Exception:
-            return False
-
-    @property
-    def name(self) -> str: return "local"
-    @property
-    def cloud(self) -> bool: return False
-
-
-class HonchoBackend(Backend):
-    def __init__(self):
-        self._client = None
-        self._key = os.getenv("HONCHO_API_KEY", "")
-
-    def _client_lazy(self):
-        if self._client:
-            return self._client
-        if not self._key:
-            return None
-        try:
-            from honcho import Honcho
-            self._client = Honcho(api_key=self._key)
-            return self._client
-        except Exception:
-            return None
-
-    def available(self) -> bool:
-        if not self._key:
-            return False
-        c = self._client_lazy()
-        if not c:
-            return False
-        try:
-            c.get_sessions(limit=1)
-            return True
-        except Exception:
-            return False
-
-    def store(self, uid, key, val, meta=None) -> bool:
-        c = self._client_lazy()
-        if not c:
-            return False
-        try:
-            c.add_message(f"mem-{uid}", "system", json.dumps({"k": key, "v": val, "m": meta or {}}))
-            return True
-        except Exception:
-            return False
-
-    def get(self, uid, key) -> Optional[Entry]:
-        for e in self.query(uid, key, 1):
-            if e.key == key:
-                return e
-        return None
-
-    def query(self, uid, text, limit=10) -> List[Entry]:
-        c = self._client_lazy()
-        if not c:
-            return []
-        try:
-            r = c.chat(f"mem-{uid}", f"Find: {text}")
-            entries = []
-            if isinstance(r, dict):
-                try:
-                    data = json.loads(r.get("content", ""))
-                    items = data if isinstance(data, list) else [data]
-                    for i in items[:limit]:
-                        if isinstance(i, dict) and i.get("k"):
-                            entries.append(Entry(key=i["k"], value=i.get("v", ""), user_id=uid))
-                except json.JSONDecodeError:
-                    pass
-            return entries
-        except Exception:
-            return []
-
-    def list(self, uid) -> List[Entry]:
-        return self.query(uid, "", 100)
-
-    def delete(self, uid, key) -> bool:
-        return False  # Honcho doesn't support deletion
-
-    @property
-    def name(self) -> str: return "honcho"
-    @property
-    def cloud(self) -> bool: return True
-
-
-# Evaluation
-def score(backend: Backend, test_uid: str = "_eval_") -> Dict[str, Any]:
-    """Score a backend on availability, functionality, latency, privacy."""
-    if not backend.available():
-        return {"name": backend.name, "score": 0, "grade": "F", "available": False}
-
-    s = 20  # available
-
-    # Store
-    t0 = time.perf_counter()
-    ok = backend.store(test_uid, "ek", "ev")
-    store_ms = (time.perf_counter() - t0) * 1000
-    s += 15 if ok else 0
-
-    # Retrieve
-    t0 = time.perf_counter()
-    r = backend.get(test_uid, "ek")
-    get_ms = (time.perf_counter() - t0) * 1000
-    s += 15 if r else 0
-
-    # Query
-    t0 = time.perf_counter()
-    q = backend.query(test_uid, "ev", 5)
-    q_ms = (time.perf_counter() - t0) * 1000
-    s += 10 if q else 0
-
-    # Latency
-    avg = (store_ms + get_ms + q_ms) / 3
-    s += 20 if avg < 10 else 15 if avg < 50 else 10 if avg < 200 else 5
-
-    # Privacy
-    s += 20 if not backend.cloud else 5
-
-    try:
-        backend.delete(test_uid, "ek")
-    except Exception:
-        pass
-
-    grade = "A" if s >= 80 else "B" if s >= 60 else "C" if s >= 40 else "D" if s >= 20 else "F"
-    return {"name": backend.name, "score": s, "grade": grade, "available": True,
-            "cloud": backend.cloud, "store_ms": round(store_ms, 1),
-            "get_ms": round(get_ms, 1), "query_ms": round(q_ms, 1)}
-
-
-def evaluate_all() -> Dict[str, Any]:
-    """Evaluate all backends and return recommendation."""
-    backends = [NullBackend(), LocalBackend()]
-    if os.getenv("HONCHO_API_KEY"):
-        try:
-            backends.append(HonchoBackend())
-        except Exception:
-            pass
-
-    results = [score(b) for b in backends]
-    best = max((r for r in results if r["name"] != "null" and r["available"]), key=lambda r: r["score"], default=None)
-
-    rec = "No viable backends"
-    if best:
-        rec = f"Best: {best['name']} (score {best['score']}, grade {best['grade']})"
-        if best.get("cloud"):
-            rec += " WARNING: cloud dependency. RECOMMEND local for sovereignty."
-
-    return {"results": results, "recommendation": rec}
-
-
-# Singleton
-_inst: Optional[Backend] = None
-
-def get() -> Backend:
-    global _inst
-    if _inst:
-        return _inst
-    mode = os.getenv("HERMES_MEMORY_BACKEND", "").lower()
-    if mode == "honcho" or os.getenv("HONCHO_API_KEY"):
-        try:
-            h = HonchoBackend()
-            if h.available():
-                _inst = h
-                return _inst
-        except Exception:
-            pass
-    _inst = LocalBackend()
-    return _inst
-
-def reset():
-    global _inst
-    _inst = None

agent/memory_manager.py

@@ -34,6 +34,7 @@ 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__)
 
@@ -249,7 +250,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 +258,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

@@ -26,12 +26,14 @@ _PROVIDER_PREFIXES: frozenset[str] = frozenset({
     "openrouter", "nous", "openai-codex", "copilot", "copilot-acp",
     "gemini", "zai", "kimi-coding", "minimax", "minimax-cn", "anthropic", "deepseek",
     "opencode-zen", "opencode-go", "ai-gateway", "kilocode", "alibaba",
-    "ollama", "custom", "local",
+    "qwen-oauth",
+    "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",
     "opencode", "zen", "go", "vercel", "kilo", "dashscope", "aliyun", "qwen",
+    "qwen-portal",
 })
 
 
@@ -102,12 +104,9 @@ DEFAULT_CONTEXT_LENGTHS = {
     "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
@@ -116,8 +115,15 @@ DEFAULT_CONTEXT_LENGTHS = {
     "llama": 131072,
     # Qwen
     "qwen": 131072,
-    # MiniMax
-    "minimax": 204800,
+    # MiniMax (lowercase — lookup lowercases model names at line 973)
+    "minimax-m1-256k": 1000000,
+    "minimax-m1-128k": 1000000,
+    "minimax-m1-80k": 1000000,
+    "minimax-m1-40k": 1000000,
+    "minimax-m1": 1000000,
+    "minimax-m2.5": 1048576,
+    "minimax-m2.7": 1048576,
+    "minimax": 1048576,
     # GLM
     "glm": 202752,
     # Kimi
@@ -130,7 +136,7 @@ DEFAULT_CONTEXT_LENGTHS = {
     "deepseek-ai/DeepSeek-V3.2": 65536,
     "moonshotai/Kimi-K2.5": 262144,
     "moonshotai/Kimi-K2-Thinking": 262144,
-    "MiniMaxAI/MiniMax-M2.5": 204800,
+    "MiniMaxAI/MiniMax-M2.5": 1048576,
     "XiaomiMiMo/MiMo-V2-Flash": 32768,
     "mimo-v2-pro": 1048576,
     "mimo-v2-omni": 1048576,
@@ -183,6 +189,7 @@ _URL_TO_PROVIDER: Dict[str, str] = {
     "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 +197,6 @@ _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",
 }
 
 
@@ -515,8 +520,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]:
@@ -616,6 +621,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

agent/models_dev.py

@@ -23,9 +23,9 @@ 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
 
@@ -148,11 +148,12 @@ PROVIDER_TO_MODELS_DEV: Dict[str, str] = {
     "openrouter": "openrouter",
     "anthropic": "anthropic",
     "zai": "zai",
-    "kimi-coding": "kimi-k2.5",
+    "kimi-coding": "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",
@@ -185,9 +186,8 @@ def _get_reverse_mapping() -> Dict[str, str]:
 
 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 +231,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)

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

@@ -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"

agent/retry_utils.py

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

agent/skill_commands.py

@@ -12,14 +12,6 @@ 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,
-)
-
 logger = logging.getLogger(__name__)
 
 _skill_commands: Dict[str, Dict[str, Any]] = {}
@@ -56,37 +48,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:

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

@@ -10,7 +10,7 @@ import os
 import re
 import sys
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Set, Tuple
+from typing import Any, Dict, List, Set, Tuple
 
 from hermes_constants import get_hermes_home
 

agent/smart_model_routing.py

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

agent/subdirectory_hints.py

@@ -15,7 +15,6 @@ Inspired by Block/goose's SubdirectoryHintTracker.
 
 import logging
 import os
-import re
 import shlex
 from pathlib import Path
 from typing import Dict, Any, Optional, Set

agent/symbolic_memory.py

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

agent/temporal_knowledge_graph.py

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

agent/temporal_reasoning.py

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

agent/ultraplinian_router.py

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

agent_core_analysis.md

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

attack_surface_diagram.mermaid

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

batch_runner.py

@@ -31,6 +31,8 @@ from multiprocessing import Pool, Lock
 import traceback
 from rich.progress import Progress, SpinnerColumn, BarColumn, TextColumn, TimeRemainingColumn, MofNCompleteColumn
 from rich.console import Console
+
+logger = logging.getLogger(__name__)
 import fire
 
 from run_agent import AIAgent
@@ -1016,7 +1018,7 @@ class BatchRunner:
                             tool_stats = data.get('tool_stats', {})
                             
                             # Check for invalid tool names (model hallucinations)
-                            invalid_tools = [k for k in tool_stats.keys() if k not in VALID_TOOLS]
+                            invalid_tools = [k for k in tool_stats if k not in VALID_TOOLS]
                             
                             if invalid_tools:
                                 filtered_entries += 1

cli-config.yaml.example

@@ -644,10 +644,14 @@ platform_toolsets:
 # Voice Transcription (Speech-to-Text)
 # =============================================================================
 # Automatically transcribe voice messages on messaging platforms.
-# Requires OPENAI_API_KEY in .env (uses OpenAI Whisper API directly).
+# Providers: local (free, faster-whisper) | groq (free tier) | openai (Whisper API) | mistral (Voxtral Transcribe)
+# Set the corresponding API key in .env: GROQ_API_KEY, OPENAI_API_KEY, or MISTRAL_API_KEY.
 stt:
   enabled: true
+  # provider: "local"          # auto-detected if omitted
   model: "whisper-1"  # whisper-1 (cheapest) | gpt-4o-mini-transcribe | gpt-4o-transcribe
+  # mistral:
+  #   model: "voxtral-mini-latest"  # voxtral-mini-latest | voxtral-mini-2602
 
 # =============================================================================
 # Response Pacing (Messaging Platforms)

cli.py

@@ -13,8 +13,6 @@ Usage:
     python cli.py --list-tools             # List available tools and exit
 """
 
-from __future__ import annotations
-
 import logging
 import os
 import shutil
@@ -65,14 +63,14 @@ from agent.usage_pricing import (
     format_duration_compact,
     format_token_count_compact,
 )
-from hermes_cli.banner import _format_context_length
+from hermes_cli.banner import _format_context_length, format_banner_version_label
 
 _COMMAND_SPINNER_FRAMES = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏")
 
 
 # Load .env from ~/.hermes/.env first, then project root as dev fallback.
 # User-managed env files should override stale shell exports on restart.
-from hermes_constants import get_hermes_home, display_hermes_home, OPENROUTER_BASE_URL
+from hermes_constants import get_hermes_home, display_hermes_home
 from hermes_cli.env_loader import load_hermes_dotenv
 
 _hermes_home = get_hermes_home()
@@ -562,6 +560,7 @@ from rich.text import Text as _RichText
 import fire
 
 # Import the agent and tool systems
+from run_agent import AIAgent
 from model_tools import get_tool_definitions, get_toolset_for_tool
 
 # Extracted CLI modules (Phase 3)
@@ -613,6 +612,11 @@ def _run_cleanup():
         pass
     # Shut down memory provider (on_session_end + shutdown_all) at actual
     # session boundary — NOT per-turn inside run_conversation().
+    try:
+        from hermes_cli.plugins import invoke_hook as _invoke_hook
+        _invoke_hook("on_session_finalize", session_id=_active_agent_ref.session_id if _active_agent_ref else None, platform="cli")
+    except Exception:
+        pass
     try:
         if _active_agent_ref and hasattr(_active_agent_ref, 'shutdown_memory_provider'):
             _active_agent_ref.shutdown_memory_provider(
@@ -756,7 +760,10 @@ def _setup_worktree(repo_root: str = None) -> Optional[Dict[str, str]]:
 def _cleanup_worktree(info: Dict[str, str] = None) -> None:
     """Remove a worktree and its branch on exit.
 
-    If the worktree has uncommitted changes, warn and keep it.
+    Preserves the worktree only if it has unpushed commits (real work
+    that hasn't been pushed to any remote).  Uncommitted changes alone
+    (untracked files, test artifacts) are not enough to keep it — agent
+    work lives in commits/PRs, not the working tree.
     """
     global _active_worktree
     info = info or _active_worktree
@@ -772,23 +779,27 @@ def _cleanup_worktree(info: Dict[str, str] = None) -> None:
     if not Path(wt_path).exists():
         return
 
-    # Check for uncommitted changes
+    # Check for unpushed commits — commits reachable from HEAD but not
+    # from any remote branch.  These represent real work the agent did
+    # but didn't push.
+    has_unpushed = False
     try:
-        status = subprocess.run(
-            ["git", "status", "--porcelain"],
+        result = subprocess.run(
+            ["git", "log", "--oneline", "HEAD", "--not", "--remotes"],
             capture_output=True, text=True, timeout=10, cwd=wt_path,
         )
-        has_changes = bool(status.stdout.strip())
+        has_unpushed = bool(result.stdout.strip())
     except Exception:
-        has_changes = True  # Assume dirty on error — don't delete
+        has_unpushed = True  # Assume unpushed on error — don't delete
 
-    if has_changes:
-        print(f"\n\033[33m⚠ Worktree has uncommitted changes, keeping: {wt_path}\033[0m")
-        print(f"  To clean up manually: git worktree remove {wt_path}")
+    if has_unpushed:
+        print(f"\n\033[33m⚠ Worktree has unpushed commits, keeping: {wt_path}\033[0m")
+        print(f"  To clean up manually: git worktree remove --force {wt_path}")
         _active_worktree = None
         return
 
-    # Remove worktree
+    # Remove worktree (even if working tree is dirty — uncommitted
+    # changes without unpushed commits are just artifacts)
     try:
         subprocess.run(
             ["git", "worktree", "remove", wt_path, "--force"],
@@ -797,7 +808,7 @@ def _cleanup_worktree(info: Dict[str, str] = None) -> None:
     except Exception as e:
         logger.debug("Failed to remove worktree: %s", e)
 
-    # Delete the branch (only if it was never pushed / has no upstream)
+    # Delete the branch
     try:
         subprocess.run(
             ["git", "branch", "-D", branch],
@@ -811,19 +822,27 @@ def _cleanup_worktree(info: Dict[str, str] = None) -> None:
 
 
 def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
-    """Remove worktrees older than max_age_hours that have no uncommitted changes.
+    """Remove stale worktrees and orphaned branches on startup.
 
-    Runs silently on startup to clean up after crashed/killed sessions.
+    Age-based tiers:
+    - Under max_age_hours (24h): skip — session may still be active.
+    - 24h–72h: remove if no unpushed commits.
+    - Over 72h: force remove regardless (nothing should sit this long).
+
+    Also prunes orphaned ``hermes/*`` and ``pr-*`` local branches that
+    have no corresponding worktree.
     """
     import subprocess
     import time
 
     worktrees_dir = Path(repo_root) / ".worktrees"
     if not worktrees_dir.exists():
+        _prune_orphaned_branches(repo_root)
         return
 
     now = time.time()
-    cutoff = now - (max_age_hours * 3600)
+    soft_cutoff = now - (max_age_hours * 3600)       # 24h default
+    hard_cutoff = now - (max_age_hours * 3 * 3600)   # 72h default
 
     for entry in worktrees_dir.iterdir():
         if not entry.is_dir() or not entry.name.startswith("hermes-"):
@@ -832,21 +851,24 @@ def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
         # Check age
         try:
             mtime = entry.stat().st_mtime
-            if mtime > cutoff:
+            if mtime > soft_cutoff:
                 continue  # Too recent — skip
         except Exception:
             continue
 
-        # Check for uncommitted changes
-        try:
-            status = subprocess.run(
-                ["git", "status", "--porcelain"],
-                capture_output=True, text=True, timeout=5, cwd=str(entry),
-            )
-            if status.stdout.strip():
-                continue  # Has changes — skip
-        except Exception:
-            continue  # Can't check — skip
+        force = mtime <= hard_cutoff  # Over 72h — force remove
+
+        if not force:
+            # 24h–72h tier: only remove if no unpushed commits
+            try:
+                result = subprocess.run(
+                    ["git", "log", "--oneline", "HEAD", "--not", "--remotes"],
+                    capture_output=True, text=True, timeout=5, cwd=str(entry),
+                )
+                if result.stdout.strip():
+                    continue  # Has unpushed commits — skip
+            except Exception:
+                continue  # Can't check — skip
 
         # Safe to remove
         try:
@@ -865,10 +887,81 @@ def _prune_stale_worktrees(repo_root: str, max_age_hours: int = 24) -> None:
                     ["git", "branch", "-D", branch],
                     capture_output=True, text=True, timeout=10, cwd=repo_root,
                 )
-            logger.debug("Pruned stale worktree: %s", entry.name)
+            logger.debug("Pruned stale worktree: %s (force=%s)", entry.name, force)
         except Exception as e:
             logger.debug("Failed to prune worktree %s: %s", entry.name, e)
 
+    _prune_orphaned_branches(repo_root)
+
+
+def _prune_orphaned_branches(repo_root: str) -> None:
+    """Delete local ``hermes/hermes-*`` and ``pr-*`` branches with no worktree.
+
+    These are auto-generated by ``hermes -w`` sessions and PR review
+    workflows respectively.  Once their worktree is gone they serve no
+    purpose and just accumulate.
+    """
+    import subprocess
+
+    try:
+        result = subprocess.run(
+            ["git", "branch", "--format=%(refname:short)"],
+            capture_output=True, text=True, timeout=10, cwd=repo_root,
+        )
+        if result.returncode != 0:
+            return
+        all_branches = [b.strip() for b in result.stdout.strip().split("\n") if b.strip()]
+    except Exception:
+        return
+
+    # Collect branches that are actively checked out in a worktree
+    active_branches: set = set()
+    try:
+        wt_result = subprocess.run(
+            ["git", "worktree", "list", "--porcelain"],
+            capture_output=True, text=True, timeout=10, cwd=repo_root,
+        )
+        for line in wt_result.stdout.split("\n"):
+            if line.startswith("branch refs/heads/"):
+                active_branches.add(line.split("branch refs/heads/", 1)[-1].strip())
+    except Exception:
+        return  # Can't determine active branches — bail
+
+    # Also protect the currently checked-out branch and main
+    try:
+        head_result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            capture_output=True, text=True, timeout=5, cwd=repo_root,
+        )
+        current = head_result.stdout.strip()
+        if current:
+            active_branches.add(current)
+    except Exception:
+        pass
+    active_branches.add("main")
+
+    orphaned = [
+        b for b in all_branches
+        if b not in active_branches
+        and (b.startswith("hermes/hermes-") or b.startswith("pr-"))
+    ]
+
+    if not orphaned:
+        return
+
+    # Delete in batches
+    for i in range(0, len(orphaned), 50):
+        batch = orphaned[i:i + 50]
+        try:
+            subprocess.run(
+                ["git", "branch", "-D"] + batch,
+                capture_output=True, text=True, timeout=30, cwd=repo_root,
+            )
+        except Exception as e:
+            logger.debug("Failed to prune orphaned branches: %s", e)
+
+    logger.debug("Pruned %d orphaned branches", len(orphaned))
+
 # ============================================================================
 # ASCII Art & Branding
 # ============================================================================
@@ -1037,21 +1130,44 @@ COMPACT_BANNER = """
 
 def _build_compact_banner() -> str:
     """Build a compact banner that fits the current terminal width."""
-    w = min(shutil.get_terminal_size().columns - 2, 64)
+    try:
+        from hermes_cli.skin_engine import get_active_skin
+        _skin = get_active_skin()
+    except Exception:
+        _skin = None
+
+    skin_name = getattr(_skin, "name", "default") if _skin else "default"
+    border_color = _skin.get_color("banner_border", "#FFD700") if _skin else "#FFD700"
+    title_color = _skin.get_color("banner_title", "#FFBF00") if _skin else "#FFBF00"
+    dim_color = _skin.get_color("banner_dim", "#B8860B") if _skin else "#B8860B"
+
+    if skin_name == "default":
+        line1 = "⚕ NOUS HERMES - AI Agent Framework"
+        tiny_line = "⚕ NOUS HERMES"
+    else:
+        agent_name = _skin.get_branding("agent_name", "Hermes Agent") if _skin else "Hermes Agent"
+        line1 = f"{agent_name} - AI Agent Framework"
+        tiny_line = agent_name
+
+    version_line = format_banner_version_label()
+
+    w = min(shutil.get_terminal_size().columns - 2, 88)
     if w < 30:
-        return "\n[#FFBF00]⚕ NOUS HERMES[/] [dim #B8860B]- Nous Research[/]\n"
+        return f"\n[{title_color}]{tiny_line}[/] [dim {dim_color}]- Nous Research[/]\n"
+
     inner = w - 2  # inside the box border
     bar = "═" * w
-    line1 = "⚕ NOUS HERMES - AI Agent Framework"
-    line2 = "Messenger of the Digital Gods  ·  Nous Research"
+    content_width = inner - 2
+
     # Truncate and pad to fit
-    line1 = line1[:inner - 2].ljust(inner - 2)
-    line2 = line2[:inner - 2].ljust(inner - 2)
+    line1 = line1[:content_width].ljust(content_width)
+    line2 = version_line[:content_width].ljust(content_width)
+
     return (
-        f"\n[bold #FFD700]╔{bar}╗[/]\n"
-        f"[bold #FFD700]║[/] [#FFBF00]{line1}[/] [bold #FFD700]║[/]\n"
-        f"[bold #FFD700]║[/] [dim #B8860B]{line2}[/] [bold #FFD700]║[/]\n"
-        f"[bold #FFD700]╚{bar}╝[/]\n"
+        f"\n[bold {border_color}]╔{bar}╗[/]\n"
+        f"[bold {border_color}]║[/] [{title_color}]{line1}[/] [bold {border_color}]║[/]\n"
+        f"[bold {border_color}]║[/] [dim {dim_color}]{line2}[/] [bold {border_color}]║[/]\n"
+        f"[bold {border_color}]╚{bar}╝[/]\n"
     )
 
 
@@ -2164,7 +2280,7 @@ class HermesCLI:
             )
         except Exception as exc:
             message = format_runtime_provider_error(exc)
-            self.console.print(f"[bold red]{message}[/]")
+            ChatConsole().print(f"[bold red]{message}[/]")
             return False
 
         api_key = runtime.get("api_key")
@@ -2252,8 +2368,6 @@ class HermesCLI:
         Returns:
             bool: True if successful, False otherwise
         """
-        from run_agent import AIAgent
-
         if self.agent is not None:
             return True
 
@@ -2381,7 +2495,7 @@ class HermesCLI:
                     self._pending_title = None
             return True
         except Exception as e:
-            self.console.print(f"[bold red]Failed to initialize agent: {e}[/]")
+            ChatConsole().print(f"[bold red]Failed to initialize agent: {e}[/]")
             return False
     
     def show_banner(self):
@@ -3134,196 +3248,6 @@ class HermesCLI:
         print(f"  Home:    {display}")
         print()
 
-    def _handle_debug_command(self, command: str):
-        """Generate a debug report with system info and logs, upload to paste service."""
-        import platform
-        import sys
-        import time as _time
-
-        # Parse optional lines argument
-        parts = command.split(maxsplit=1)
-        log_lines = 50
-        if len(parts) > 1:
-            try:
-                log_lines = min(int(parts[1]), 500)
-            except ValueError:
-                pass
-
-        _cprint("  Collecting debug info...")
-
-        # Collect system info
-        lines = []
-        lines.append("=== HERMES DEBUG REPORT ===")
-        lines.append(f"Generated: {_time.strftime('%Y-%m-%d %H:%M:%S %z')}")
-        lines.append("")
-
-        lines.append("--- System ---")
-        lines.append(f"Python: {sys.version}")
-        lines.append(f"Platform: {platform.platform()}")
-        lines.append(f"Architecture: {platform.machine()}")
-        lines.append(f"Hostname: {platform.node()}")
-        lines.append("")
-
-        # Hermes info
-        lines.append("--- Hermes ---")
-        try:
-            from hermes_constants import get_hermes_home, display_hermes_home
-            lines.append(f"Home: {display_hermes_home()}")
-        except Exception:
-            lines.append("Home: unknown")
-
-        try:
-            from hermes_constants import __version__
-            lines.append(f"Version: {__version__}")
-        except Exception:
-            lines.append("Version: unknown")
-
-        lines.append(f"Profile: {getattr(self, '_profile_name', 'default')}")
-        lines.append(f"Session: {self.session_id}")
-        lines.append(f"Model: {self.model}")
-        lines.append(f"Provider: {getattr(self, '_provider_name', 'unknown')}")
-
-        try:
-            lines.append(f"Working dir: {os.getcwd()}")
-        except Exception:
-            pass
-
-        # Config (redacted)
-        lines.append("")
-        lines.append("--- Config (redacted) ---")
-        try:
-            from hermes_constants import get_hermes_home
-            config_path = get_hermes_home() / "config.yaml"
-            if config_path.exists():
-                import yaml
-                with open(config_path) as f:
-                    cfg = yaml.safe_load(f) or {}
-                # Redact secrets
-                for key in ("api_key", "token", "secret", "password"):
-                    if key in cfg:
-                        cfg[key] = "***REDACTED***"
-                lines.append(yaml.dump(cfg, default_flow_style=False)[:2000])
-            else:
-                lines.append("(no config file found)")
-        except Exception as e:
-            lines.append(f"(error reading config: {e})")
-
-        # Recent logs
-        lines.append("")
-        lines.append(f"--- Recent Logs (last {log_lines} lines) ---")
-        try:
-            from hermes_constants import get_hermes_home
-            log_dir = get_hermes_home() / "logs"
-            if log_dir.exists():
-                for log_file in sorted(log_dir.glob("*.log")):
-                    try:
-                        content = log_file.read_text(encoding="utf-8", errors="replace")
-                        tail = content.strip().split("\n")[-log_lines:]
-                        if tail:
-                            lines.append(f"\n[{log_file.name}]")
-                            lines.extend(tail)
-                    except Exception:
-                        pass
-            else:
-                lines.append("(no logs directory)")
-        except Exception:
-            lines.append("(error reading logs)")
-
-        # Tool info
-        lines.append("")
-        lines.append("--- Enabled Toolsets ---")
-        try:
-            lines.append(", ".join(self.enabled_toolsets) if self.enabled_toolsets else "(none)")
-        except Exception:
-            lines.append("(unknown)")
-
-        report = "\n".join(lines)
-        report_size = len(report)
-
-        # Try to upload to paste services
-        paste_url = None
-        services = [
-            ("dpaste", _upload_dpaste),
-            ("0x0.st", _upload_0x0st),
-        ]
-
-        for name, uploader in services:
-            try:
-                url = uploader(report)
-                if url:
-                    paste_url = url
-                    break
-            except Exception:
-                continue
-
-        print()
-        if paste_url:
-            _cprint(f"  Debug report uploaded: {paste_url}")
-            _cprint(f"  Size: {report_size} bytes, {len(lines)} lines")
-        else:
-            # Fallback: save locally
-            try:
-                from hermes_constants import get_hermes_home
-                debug_path = get_hermes_home() / "debug-report.txt"
-                debug_path.write_text(report, encoding="utf-8")
-                _cprint(f"  Paste services unavailable. Report saved to: {debug_path}")
-                _cprint(f"  Size: {report_size} bytes, {len(lines)} lines")
-            except Exception as e:
-                _cprint(f"  Failed to save report: {e}")
-                _cprint(f"  Report ({report_size} bytes):")
-                print(report)
-        print()
-
-
-def _upload_dpaste(content: str) -> str | None:
-    """Upload content to dpaste.org. Returns URL or None."""
-    import urllib.request
-    import urllib.parse
-    data = urllib.parse.urlencode({
-        "content": content,
-        "syntax": "text",
-        "expiry_days": 7,
-    }).encode()
-    req = urllib.request.Request(
-        "https://dpaste.org/api/",
-        data=data,
-        headers={"User-Agent": "hermes-agent/debug"},
-    )
-    with urllib.request.urlopen(req, timeout=10) as resp:
-        url = resp.read().decode().strip()
-        if url.startswith("http"):
-            return url
-    return None
-
-
-def _upload_0x0st(content: str) -> str | None:
-    """Upload content to 0x0.st. Returns URL or None."""
-    import urllib.request
-    import io
-    # 0x0.st expects multipart form with a file field
-    boundary = "----HermesDebugBoundary"
-    body = (
-        f"--{boundary}\r\n"
-        f'Content-Disposition: form-data; name="file"; filename="debug.txt"\r\n'
-        f"Content-Type: text/plain\r\n\r\n"
-        f"{content}\r\n"
-        f"--{boundary}--\r\n"
-    ).encode()
-    req = urllib.request.Request(
-        "https://0x0.st",
-        data=body,
-        headers={
-            "Content-Type": f"multipart/form-data; boundary={boundary}",
-            "User-Agent": "hermes-agent/debug",
-        },
-    )
-    with urllib.request.urlopen(req, timeout=10) as resp:
-        url = resp.read().decode().strip()
-        if url.startswith("http"):
-            return url
-    return None
-
-
     def show_config(self):
         """Display current configuration with kawaii ASCII art."""
         # Get terminal config from environment (which was set from cli-config.yaml)
@@ -3484,6 +3408,22 @@ def _upload_0x0st(content: str) -> str | None:
         flush_tool_summary()
         print()
     
+    def _notify_session_boundary(self, event_type: str) -> None:
+        """Fire a session-boundary plugin hook (on_session_finalize or on_session_reset).
+
+        Non-blocking — errors are caught and logged.  Safe to call from any
+        lifecycle point (shutdown, /new, /reset).
+        """
+        try:
+            from hermes_cli.plugins import invoke_hook as _invoke_hook
+            _invoke_hook(
+                event_type,
+                session_id=self.agent.session_id if self.agent else None,
+                platform=getattr(self, "platform", None) or "cli",
+            )
+        except Exception:
+            pass
+
     def new_session(self, silent=False):
         """Start a fresh session with a new session ID and cleared agent state."""
         if self.agent and self.conversation_history:
@@ -3491,6 +3431,10 @@ def _upload_0x0st(content: str) -> str | None:
                 self.agent.flush_memories(self.conversation_history)
             except (Exception, KeyboardInterrupt):
                 pass
+            self._notify_session_boundary("on_session_finalize")
+        elif self.agent:
+            # First session or empty history — still finalize the old session
+            self._notify_session_boundary("on_session_finalize")
 
         old_session_id = self.session_id
         if self._session_db and old_session_id:
@@ -3535,6 +3479,7 @@ def _upload_0x0st(content: str) -> str | None:
                     )
                 except Exception:
                     pass
+            self._notify_session_boundary("on_session_reset")
 
         if not silent:
             print("(^_^)v New session started!")
@@ -3729,13 +3674,6 @@ def _upload_0x0st(content: str) -> str | None:
         _cprint(f"  Original session: {parent_session_id}")
         _cprint(f"  Branch session:   {new_session_id}")
 
-    def reset_conversation(self):
-        """Reset the conversation by starting a new session."""
-        # Shut down memory provider before resetting — actual session boundary
-        if hasattr(self, 'agent') and self.agent:
-            self.agent.shutdown_memory_provider(self.conversation_history)
-        self.new_session()
-    
     def save_conversation(self):
         """Save the current conversation to a file."""
         if not self.conversation_history:
@@ -4439,7 +4377,6 @@ def _upload_0x0st(content: str) -> str | None:
         
         try:
             config = load_gateway_config()
-            connected = config.get_connected_platforms()
             
             print("  Messaging Platform Configuration:")
             print("  " + "-" * 55)
@@ -4511,8 +4448,6 @@ def _upload_0x0st(content: str) -> str | None:
             self.show_help()
         elif canonical == "profile":
             self._handle_profile_command()
-        elif canonical == "debug":
-            self._handle_debug_command(cmd_original)
         elif canonical == "tools":
             self._handle_tools_command(cmd_original)
         elif canonical == "toolsets":
@@ -4775,7 +4710,7 @@ def _upload_0x0st(content: str) -> str | None:
                     if hasattr(self, '_pending_input'):
                         self._pending_input.put(msg)
                 else:
-                    self.console.print(f"[bold red]Failed to load skill for {base_cmd}[/]")
+                    ChatConsole().print(f"[bold red]Failed to load skill for {base_cmd}[/]")
             else:
                 # Prefix matching: if input uniquely identifies one command, execute it.
                 # Matches against both built-in COMMANDS and installed skill commands so
@@ -4836,14 +4771,14 @@ def _upload_0x0st(content: str) -> str | None:
         )
 
         if not msg:
-            self.console.print("[bold red]Failed to load the bundled /plan skill[/]")
+            ChatConsole().print("[bold red]Failed to load the bundled /plan skill[/]")
             return
 
         _cprint(f"  📝 Plan mode queued via skill. Markdown plan target: {plan_path}")
         if hasattr(self, '_pending_input'):
             self._pending_input.put(msg)
         else:
-            self.console.print("[bold red]Plan mode unavailable: input queue not initialized[/]")
+            ChatConsole().print("[bold red]Plan mode unavailable: input queue not initialized[/]")
     
     def _handle_background_command(self, cmd: str):
         """Handle /background <prompt> — run a prompt in a separate background session.
@@ -4876,8 +4811,6 @@ def _upload_0x0st(content: str) -> str | None:
         turn_route = self._resolve_turn_agent_config(prompt)
 
         def run_background():
-            from run_agent import AIAgent
-
             try:
                 bg_agent = AIAgent(
                     model=turn_route["model"],
@@ -6205,7 +6138,7 @@ def _upload_0x0st(content: str) -> str | None:
 
         timeout = CLI_CONFIG.get("clarify", {}).get("timeout", 120)
         response_queue = queue.Queue()
-        is_open_ended = not choices or len(choices) == 0
+        is_open_ended = not choices
 
         self._clarify_state = {
             "question": question,
@@ -6488,14 +6421,6 @@ def _upload_0x0st(content: str) -> str | None:
             except Exception:
                 pass
 
-    def _clear_current_input(self) -> None:
-        if getattr(self, "_app", None):
-            try:
-                self._app.current_buffer.text = ""
-            except Exception:
-                pass
-
-
     def chat(self, message, images: list = None) -> Optional[str]:
         """
         Send a message to the agent and get a response.
@@ -8036,7 +7961,6 @@ def _upload_0x0st(content: str) -> str | None:
             title = '🔐 Sudo Password Required'
             body = 'Enter password below (hidden), or press Enter to skip'
             box_width = _panel_box_width(title, [body])
-            inner = max(0, box_width - 2)
             lines = []
             lines.append(('class:sudo-border', '╭─ '))
             lines.append(('class:sudo-title', title))

config/ezra-deploy.sh

@@ -1,58 +0,0 @@
-#!/bin/bash
-# Deploy Kimi-primary config to Ezra
-# Run this from Ezra's VPS or via SSH
-
-set -e
-
-EZRA_HOST="${EZRA_HOST:-143.198.27.163}"
-EZRA_HERMES_HOME="/root/wizards/ezra/hermes-agent"
-CONFIG_SOURCE="$(dirname "$0")/ezra-kimi-primary.yaml"
-
-# Colors
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-RED='\033[0;31m'
-NC='\033[0m'
-
-echo -e "${GREEN}[DEPLOY]${NC} Ezra Kimi-Primary Configuration"
-echo "================================================"
-echo ""
-
-# Check prerequisites
-if [ ! -f "$CONFIG_SOURCE" ]; then
-    echo -e "${RED}[ERROR]${NC} Config not found: $CONFIG_SOURCE"
-    exit 1
-fi
-
-# Show what we're deploying
-echo "Configuration to deploy:"
-echo "------------------------"
-grep -v "^#" "$CONFIG_SOURCE" | grep -v "^$" | head -20
-echo ""
-
-# Deploy to Ezra
-echo -e "${GREEN}[DEPLOY]${NC} Copying config to Ezra..."
-
-# Backup existing
-ssh root@$EZRA_HOST "cp $EZRA_HERMES_HOME/config.yaml $EZRA_HERMES_HOME/config.yaml.backup.pre-kimi-$(date +%s) 2>/dev/null || true"
-
-# Copy new config
-scp "$CONFIG_SOURCE" root@$EZRA_HOST:$EZRA_HERMES_HOME/config.yaml
-
-# Verify KIMI_API_KEY exists
-echo -e "${GREEN}[VERIFY]${NC} Checking KIMI_API_KEY on Ezra..."
-ssh root@$EZRA_HOST "grep -q KIMI_API_KEY $EZRA_HERMES_HOME/.env && echo 'KIMI_API_KEY found' || echo 'WARNING: KIMI_API_KEY not set'"
-
-# Restart Ezra gateway
-echo -e "${GREEN}[RESTART]${NC} Restarting Ezra gateway..."
-ssh root@$EZRA_HOST "cd $EZRA_HERMES_HOME && pkill -f 'hermes gateway' 2>/dev/null || true"
-sleep 2
-ssh root@$EZRA_HOST "cd $EZRA_HERMES_HOME && nohup python -m gateway.run > logs/gateway.log 2>&1 &"
-
-echo ""
-echo -e "${GREEN}[SUCCESS]${NC} Ezra is now running Kimi primary!"
-echo ""
-echo "Anthropic: BANNED ✓ (removed from all configs)"
-echo "Kimi: PRIMARY ✓"
-echo ""
-echo "To verify: ssh root@$EZRA_HOST 'tail -f $EZRA_HERMES_HOME/logs/gateway.log'"

config/ezra-kimi-primary.yaml

@@ -1,39 +0,0 @@
-model:
-  default: kimi-k2.5
-  provider: kimi-coding
-toolsets:
-- all
-fallback_providers:
-- provider: kimi-coding
-  model: kimi-k2.5
-  timeout: 120
-  reason: Kimi coding fallback (front of chain)
-- provider: openrouter
-  model: google/gemini-2.5-pro
-  base_url: https://openrouter.ai/api/v1
-  api_key_env: OPENROUTER_API_KEY
-  timeout: 120
-  reason: Gemini 2.5 Pro fallback (replaces banned Anthropic)
-- provider: openrouter
-  model: google/gemini-2.5-pro
-  base_url: https://openrouter.ai/api/v1
-  api_key_env: OPENROUTER_API_KEY
-  timeout: 120
-  reason: Gemini 2.5 Pro via OpenRouter (replaces banned Anthropic)
-- provider: ollama
-  model: gemma4:latest
-  base_url: http://localhost:11434
-  timeout: 300
-  reason: "Terminal fallback \u2014 local Ollama"
-agent:
-  max_turns: 90
-  reasoning_effort: high
-  verbose: false
-providers:
-  kimi-coding:
-    base_url: https://api.kimi.com/coding/v1
-    timeout: 60
-    max_retries: 3
-  openrouter:
-    base_url: https://openrouter.ai/api/v1
-    timeout: 120

config/fallback-config.yaml

@@ -1,43 +0,0 @@
-# Hermes Agent Fallback Configuration
-# Primary: kimi-k2.5 | Fallback: gemini-2.5-pro | Terminal: local Ollama
-# Anthropic BANNED per BANNED_PROVIDERS.yml (2026-04-09)
-
-model: kimi-k2.5
-fallback_providers:
-- provider: kimi-coding
-  model: kimi-k2.5
-  timeout: 60
-  reason: Gemini 2.5 Pro via OpenRouter (replaces banned Anthropic)
-- provider: openrouter
-  model: google/gemini-2.5-pro
-  base_url: https://openrouter.ai/api/v1
-  api_key_env: OPENROUTER_API_KEY
-  timeout: 120
-  reason: Gemini 2.5 Pro via OpenRouter (replaces banned Anthropic)
-- provider: ollama
-  model: qwen2.5:7b
-  base_url: http://localhost:11434
-  timeout: 120
-  reason: Local fallback for offline operation
-providers:
-  kimi-coding:
-    timeout: 60
-    max_retries: 3
-  ollama:
-    timeout: 120
-    keep_alive: true
-toolsets:
-- hermes-cli
-- github
-- web
-agent:
-  max_turns: 90
-  tool_use_enforcement: auto
-  fallback_on_errors:
-  - rate_limit_exceeded
-  - quota_exceeded
-  - timeout
-  - service_unavailable
-display:
-  show_fallback_notifications: true
-  show_provider_switches: true

config/nexus-templates/base_room.js

@@ -1,200 +0,0 @@
-/**
- * Nexus Base Room Template
- * 
- * This is the base template for all Nexus rooms.
- * Copy and customize this template for new room types.
- * 
- * Compatible with Three.js r128+
- */
-
-(function() {
-    'use strict';
-
-    /**
-     * Configuration object for the room
-     */
-    const CONFIG = {
-        name: 'base_room',
-        dimensions: {
-            width: 20,
-            height: 10,
-            depth: 20
-        },
-        colors: {
-            primary: '#1A1A2E',
-            secondary: '#16213E',
-            accent: '#D4AF37',      // Timmy's gold
-            light: '#E0F7FA',       // Sovereignty crystal
-        },
-        lighting: {
-            ambientIntensity: 0.3,
-            accentIntensity: 0.8,
-        }
-    };
-
-    /**
-     * Create the base room
-     * @returns {THREE.Group} The room group
-     */
-    function createBaseRoom() {
-        const room = new THREE.Group();
-        room.name = CONFIG.name;
-
-        // Create floor
-        createFloor(room);
-        
-        // Create walls
-        createWalls(room);
-        
-        // Setup lighting
-        setupLighting(room);
-        
-        // Add room features
-        addFeatures(room);
-
-        return room;
-    }
-
-    /**
-     * Create the floor
-     */
-    function createFloor(room) {
-        const floorGeo = new THREE.PlaneGeometry(
-            CONFIG.dimensions.width, 
-            CONFIG.dimensions.depth
-        );
-        const floorMat = new THREE.MeshStandardMaterial({
-            color: CONFIG.colors.primary,
-            roughness: 0.8,
-            metalness: 0.2,
-        });
-        const floor = new THREE.Mesh(floorGeo, floorMat);
-        floor.rotation.x = -Math.PI / 2;
-        floor.receiveShadow = true;
-        floor.name = 'floor';
-        room.add(floor);
-    }
-
-    /**
-     * Create the walls
-     */
-    function createWalls(room) {
-        const wallMat = new THREE.MeshStandardMaterial({
-            color: CONFIG.colors.secondary,
-            roughness: 0.9,
-            metalness: 0.1,
-            side: THREE.DoubleSide
-        });
-
-        const { width, height, depth } = CONFIG.dimensions;
-
-        // Back wall
-        const backWall = new THREE.Mesh(
-            new THREE.PlaneGeometry(width, height),
-            wallMat
-        );
-        backWall.position.set(0, height / 2, -depth / 2);
-        backWall.receiveShadow = true;
-        room.add(backWall);
-
-        // Left wall
-        const leftWall = new THREE.Mesh(
-            new THREE.PlaneGeometry(depth, height),
-            wallMat
-        );
-        leftWall.position.set(-width / 2, height / 2, 0);
-        leftWall.rotation.y = Math.PI / 2;
-        leftWall.receiveShadow = true;
-        room.add(leftWall);
-
-        // Right wall
-        const rightWall = new THREE.Mesh(
-            new THREE.PlaneGeometry(depth, height),
-            wallMat
-        );
-        rightWall.position.set(width / 2, height / 2, 0);
-        rightWall.rotation.y = -Math.PI / 2;
-        rightWall.receiveShadow = true;
-        room.add(rightWall);
-    }
-
-    /**
-     * Setup lighting
-     */
-    function setupLighting(room) {
-        // Ambient light
-        const ambientLight = new THREE.AmbientLight(
-            CONFIG.colors.primary,
-            CONFIG.lighting.ambientIntensity
-        );
-        ambientLight.name = 'ambient';
-        room.add(ambientLight);
-
-        // Accent light (Timmy's gold)
-        const accentLight = new THREE.PointLight(
-            CONFIG.colors.accent,
-            CONFIG.lighting.accentIntensity,
-            50
-        );
-        accentLight.position.set(0, 8, 0);
-        accentLight.castShadow = true;
-        accentLight.name = 'accent';
-        room.add(accentLight);
-    }
-
-    /**
-     * Add room features
-     * Override this function in custom rooms
-     */
-    function addFeatures(room) {
-        // Base room has minimal features
-        // Custom rooms should override this
-        
-        // Example: Add a center piece
-        const centerGeo = new THREE.SphereGeometry(1, 32, 32);
-        const centerMat = new THREE.MeshStandardMaterial({
-            color: CONFIG.colors.accent,
-            emissive: CONFIG.colors.accent,
-            emissiveIntensity: 0.3,
-            roughness: 0.3,
-            metalness: 0.8,
-        });
-        const centerPiece = new THREE.Mesh(centerGeo, centerMat);
-        centerPiece.position.set(0, 2, 0);
-        centerPiece.castShadow = true;
-        centerPiece.name = 'centerpiece';
-        room.add(centerPiece);
-
-        // Animation hook
-        centerPiece.userData.animate = function(time) {
-            this.position.y = 2 + Math.sin(time) * 0.2;
-            this.rotation.y = time * 0.5;
-        };
-    }
-
-    /**
-     * Dispose of room resources
-     */
-    function disposeRoom(room) {
-        room.traverse((child) => {
-            if (child.isMesh) {
-                child.geometry.dispose();
-                if (Array.isArray(child.material)) {
-                    child.material.forEach(m => m.dispose());
-                } else {
-                    child.material.dispose();
-                }
-            }
-        });
-    }
-
-    // Export
-    if (typeof module !== 'undefined' && module.exports) {
-        module.exports = { createBaseRoom, disposeRoom, CONFIG };
-    } else if (typeof window !== 'undefined') {
-        window.NexusRooms = window.NexusRooms || {};
-        window.NexusRooms.base_room = createBaseRoom;
-    }
-
-    return { createBaseRoom, disposeRoom, CONFIG };
-})();

config/nexus-templates/lighting_presets.json

@@ -1,221 +0,0 @@
-{
-  "description": "Nexus Lighting Presets for Three.js",
-  "version": "1.0.0",
-  "presets": {
-    "warm": {
-      "name": "Warm",
-      "description": "Warm, inviting lighting with golden tones",
-      "colors": {
-        "timmy_gold": "#D4AF37",
-        "ambient": "#FFE4B5",
-        "primary": "#FFA07A",
-        "secondary": "#F4A460"
-      },
-      "lights": {
-        "ambient": {
-          "color": "#FFE4B5",
-          "intensity": 0.4
-        },
-        "directional": {
-          "color": "#FFA07A",
-          "intensity": 0.8,
-          "position": {"x": 10, "y": 20, "z": 10}
-        },
-        "point_lights": [
-          {
-            "color": "#D4AF37",
-            "intensity": 0.6,
-            "distance": 30,
-            "position": {"x": 0, "y": 8, "z": 0}
-          }
-        ]
-      },
-      "fog": {
-        "enabled": true,
-        "color": "#FFE4B5",
-        "density": 0.02
-      },
-      "atmosphere": "welcoming"
-    },
-    "cool": {
-      "name": "Cool",
-      "description": "Cool, serene lighting with blue tones",
-      "colors": {
-        "allegro_blue": "#4A90E2",
-        "ambient": "#E0F7FA",
-        "primary": "#81D4FA",
-        "secondary": "#B3E5FC"
-      },
-      "lights": {
-        "ambient": {
-          "color": "#E0F7FA",
-          "intensity": 0.35
-        },
-        "directional": {
-          "color": "#81D4FA",
-          "intensity": 0.7,
-          "position": {"x": -10, "y": 15, "z": -5}
-        },
-        "point_lights": [
-          {
-            "color": "#4A90E2",
-            "intensity": 0.5,
-            "distance": 25,
-            "position": {"x": 5, "y": 6, "z": 5}
-          }
-        ]
-      },
-      "fog": {
-        "enabled": true,
-        "color": "#E0F7FA",
-        "density": 0.015
-      },
-      "atmosphere": "serene"
-    },
-    "dramatic": {
-      "name": "Dramatic",
-      "description": "High contrast lighting with deep shadows",
-      "colors": {
-        "shadow": "#1A1A2E",
-        "highlight": "#D4AF37",
-        "ambient": "#0F0F1A",
-        "rim": "#4A90E2"
-      },
-      "lights": {
-        "ambient": {
-          "color": "#0F0F1A",
-          "intensity": 0.2
-        },
-        "directional": {
-          "color": "#D4AF37",
-          "intensity": 1.2,
-          "position": {"x": 5, "y": 10, "z": 5}
-        },
-        "spot_lights": [
-          {
-            "color": "#4A90E2",
-            "intensity": 1.0,
-            "angle": 0.5,
-            "penumbra": 0.5,
-            "position": {"x": -5, "y": 10, "z": -5},
-            "target": {"x": 0, "y": 0, "z": 0}
-          }
-        ]
-      },
-      "fog": {
-        "enabled": false
-      },
-      "shadows": {
-        "enabled": true,
-        "mapSize": 2048
-      },
-      "atmosphere": "mysterious"
-    },
-    "serene": {
-      "name": "Serene",
-      "description": "Soft, diffuse lighting for contemplation",
-      "colors": {
-        "ambient": "#F5F5F5",
-        "primary": "#E8EAF6",
-        "accent": "#C5CAE9",
-        "gold": "#D4AF37"
-      },
-      "lights": {
-        "hemisphere": {
-          "skyColor": "#E8EAF6",
-          "groundColor": "#F5F5F5",
-          "intensity": 0.6
-        },
-        "directional": {
-          "color": "#FFFFFF",
-          "intensity": 0.4,
-          "position": {"x": 10, "y": 20, "z": 10}
-        },
-        "point_lights": [
-          {
-            "color": "#D4AF37",
-            "intensity": 0.3,
-            "distance": 20,
-            "position": {"x": 0, "y": 5, "z": 0}
-          }
-        ]
-      },
-      "fog": {
-        "enabled": true,
-        "color": "#F5F5F5",
-        "density": 0.01
-      },
-      "atmosphere": "contemplative"
-    },
-    "crystalline": {
-      "name": "Crystalline",
-      "description": "Clear, bright lighting for sovereignty theme",
-      "colors": {
-        "crystal": "#E0F7FA",
-        "clear": "#FFFFFF",
-        "accent": "#4DD0E1",
-        "gold": "#D4AF37"
-      },
-      "lights": {
-        "ambient": {
-          "color": "#E0F7FA",
-          "intensity": 0.5
-        },
-        "directional": [
-          {
-            "color": "#FFFFFF",
-            "intensity": 0.8,
-            "position": {"x": 10, "y": 20, "z": 10}
-          },
-          {
-            "color": "#4DD0E1",
-            "intensity": 0.4,
-            "position": {"x": -10, "y": 10, "z": -10}
-          }
-        ],
-        "point_lights": [
-          {
-            "color": "#D4AF37",
-            "intensity": 0.5,
-            "distance": 25,
-            "position": {"x": 0, "y": 8, "z": 0}
-          }
-        ]
-      },
-      "fog": {
-        "enabled": true,
-        "color": "#E0F7FA",
-        "density": 0.008
-      },
-      "atmosphere": "sovereign"
-    },
-    "minimal": {
-      "name": "Minimal",
-      "description": "Minimal lighting with clean shadows",
-      "colors": {
-        "ambient": "#FFFFFF",
-        "primary": "#F5F5F5"
-      },
-      "lights": {
-        "ambient": {
-          "color": "#FFFFFF",
-          "intensity": 0.3
-        },
-        "directional": {
-          "color": "#FFFFFF",
-          "intensity": 0.7,
-          "position": {"x": 5, "y": 10, "z": 5}
-        }
-      },
-      "fog": {
-        "enabled": false
-      },
-      "shadows": {
-        "enabled": true,
-        "soft": true
-      },
-      "atmosphere": "clean"
-    }
-  },
-  "default_preset": "serene"
-}

config/nexus-templates/material_presets.json

@@ -1,154 +0,0 @@
-{
-  "description": "Nexus Material Presets for Three.js MeshStandardMaterial",
-  "version": "1.0.0",
-  "presets": {
-    "timmy_gold": {
-      "name": "Timmy's Gold",
-      "description": "Warm gold metallic material representing Timmy",
-      "color": "#D4AF37",
-      "emissive": "#D4AF37",
-      "emissiveIntensity": 0.2,
-      "roughness": 0.3,
-      "metalness": 0.8,
-      "tags": ["timmy", "gold", "metallic", "warm"]
-    },
-    "allegro_blue": {
-      "name": "Allegro Blue",
-      "description": "Motion blue representing Allegro",
-      "color": "#4A90E2",
-      "emissive": "#4A90E2",
-      "emissiveIntensity": 0.1,
-      "roughness": 0.2,
-      "metalness": 0.6,
-      "tags": ["allegro", "blue", "motion", "cool"]
-    },
-    "sovereignty_crystal": {
-      "name": "Sovereignty Crystal",
-      "description": "Crystalline clear material with slight transparency",
-      "color": "#E0F7FA",
-      "transparent": true,
-      "opacity": 0.8,
-      "roughness": 0.1,
-      "metalness": 0.1,
-      "transmission": 0.5,
-      "tags": ["crystal", "clear", "sovereignty", "transparent"]
-    },
-    "contemplative_stone": {
-      "name": "Contemplative Stone",
-      "description": "Smooth stone for contemplative spaces",
-      "color": "#546E7A",
-      "roughness": 0.9,
-      "metalness": 0.0,
-      "tags": ["stone", "contemplative", "matte", "natural"]
-    },
-    "ethereal_mist": {
-      "name": "Ethereal Mist",
-      "description": "Semi-transparent misty material",
-      "color": "#E1F5FE",
-      "transparent": true,
-      "opacity": 0.3,
-      "roughness": 1.0,
-      "metalness": 0.0,
-      "side": "DoubleSide",
-      "tags": ["mist", "ethereal", "transparent", "soft"]
-    },
-    "warm_wood": {
-      "name": "Warm Wood",
-      "description": "Natural wood material for organic warmth",
-      "color": "#8D6E63",
-      "roughness": 0.8,
-      "metalness": 0.0,
-      "tags": ["wood", "natural", "warm", "organic"]
-    },
-    "polished_marble": {
-      "name": "Polished Marble",
-      "description": "Smooth reflective marble surface",
-      "color": "#F5F5F5",
-      "roughness": 0.1,
-      "metalness": 0.1,
-      "tags": ["marble", "polished", "reflective", "elegant"]
-    },
-    "dark_obsidian": {
-      "name": "Dark Obsidian",
-      "description": "Deep black glassy material for dramatic contrast",
-      "color": "#1A1A2E",
-      "roughness": 0.1,
-      "metalness": 0.9,
-      "tags": ["obsidian", "dark", "dramatic", "glassy"]
-    },
-    "energy_pulse": {
-      "name": "Energy Pulse",
-      "description": "Glowing energy material with high emissive",
-      "color": "#4A90E2",
-      "emissive": "#4A90E2",
-      "emissiveIntensity": 1.0,
-      "roughness": 0.4,
-      "metalness": 0.5,
-      "tags": ["energy", "glow", "animated", "pulse"]
-    },
-    "living_leaf": {
-      "name": "Living Leaf",
-      "description": "Vibrant green material for nature elements",
-      "color": "#66BB6A",
-      "emissive": "#2E7D32",
-      "emissiveIntensity": 0.1,
-      "roughness": 0.7,
-      "metalness": 0.0,
-      "side": "DoubleSide",
-      "tags": ["nature", "green", "organic", "leaf"]
-    },
-    "ancient_brass": {
-      "name": "Ancient Brass",
-      "description": "Aged brass with patina",
-      "color": "#B5A642",
-      "roughness": 0.6,
-      "metalness": 0.7,
-      "tags": ["brass", "ancient", "vintage", "metallic"]
-    },
-    "void_black": {
-      "name": "Void Black",
-      "description": "Complete absorption material for void spaces",
-      "color": "#000000",
-      "roughness": 1.0,
-      "metalness": 0.0,
-      "tags": ["void", "black", "absorbing", "minimal"]
-    },
-    "holographic": {
-      "name": "Holographic",
-      "description": "Futuristic holographic projection material",
-      "color": "#00BCD4",
-      "emissive": "#00BCD4",
-      "emissiveIntensity": 0.5,
-      "transparent": true,
-      "opacity": 0.6,
-      "roughness": 0.2,
-      "metalness": 0.8,
-      "side": "DoubleSide",
-      "tags": ["holographic", "futuristic", "tech", "glow"]
-    },
-    "sandstone": {
-      "name": "Sandstone",
-      "description": "Desert sandstone for warm natural environments",
-      "color": "#D7CCC8",
-      "roughness": 0.95,
-      "metalness": 0.0,
-      "tags": ["sandstone", "desert", "warm", "natural"]
-    },
-    "ice_crystal": {
-      "name": "Ice Crystal",
-      "description": "Clear ice with high transparency",
-      "color": "#E3F2FD",
-      "transparent": true,
-      "opacity": 0.6,
-      "roughness": 0.1,
-      "metalness": 0.1,
-      "transmission": 0.9,
-      "tags": ["ice", "crystal", "cold", "transparent"]
-    }
-  },
-  "default_preset": "contemplative_stone",
-  "helpers": {
-    "apply_preset": "material = new THREE.MeshStandardMaterial(NexusMaterials.getPreset('timmy_gold'))",
-    "create_custom": "Use preset as base and override specific properties"
-  }
-}

config/nexus-templates/portal_template.js

@@ -1,339 +0,0 @@
-/**
- * Nexus Portal Template
- * 
- * Template for creating portals between rooms.
- * Supports multiple visual styles and transition effects.
- * 
- * Compatible with Three.js r128+
- */
-
-(function() {
-    'use strict';
-
-    /**
-     * Portal configuration
-     */
-    const PORTAL_CONFIG = {
-        colors: {
-            frame: '#D4AF37',       // Timmy's gold
-            energy: '#4A90E2',      // Allegro blue
-            core: '#FFFFFF',
-        },
-        animation: {
-            rotationSpeed: 0.5,
-            pulseSpeed: 2.0,
-            pulseAmplitude: 0.1,
-        },
-        collision: {
-            radius: 2.0,
-            height: 4.0,
-        }
-    };
-
-    /**
-     * Create a portal
-     * @param {string} fromRoom - Source room name
-     * @param {string} toRoom - Target room name
-     * @param {string} style - Portal style (circular, rectangular, stargate)
-     * @returns {THREE.Group} The portal group
-     */
-    function createPortal(fromRoom, toRoom, style = 'circular') {
-        const portal = new THREE.Group();
-        portal.name = `portal_${fromRoom}_to_${toRoom}`;
-        portal.userData = {
-            type: 'portal',
-            fromRoom: fromRoom,
-            toRoom: toRoom,
-            isActive: true,
-            style: style,
-        };
-
-        // Create based on style
-        switch(style) {
-            case 'rectangular':
-                createRectangularPortal(portal);
-                break;
-            case 'stargate':
-                createStargatePortal(portal);
-                break;
-            case 'circular':
-            default:
-                createCircularPortal(portal);
-                break;
-        }
-
-        // Add collision trigger
-        createTriggerZone(portal);
-
-        // Setup animation
-        setupAnimation(portal);
-
-        return portal;
-    }
-
-    /**
-     * Create circular portal (default)
-     */
-    function createCircularPortal(portal) {
-        const { frame, energy } = PORTAL_CONFIG.colors;
-
-        // Outer frame
-        const frameGeo = new THREE.TorusGeometry(2, 0.2, 16, 100);
-        const frameMat = new THREE.MeshStandardMaterial({
-            color: frame,
-            emissive: frame,
-            emissiveIntensity: 0.5,
-            roughness: 0.3,
-            metalness: 0.9,
-        });
-        const frameMesh = new THREE.Mesh(frameGeo, frameMat);
-        frameMesh.castShadow = true;
-        frameMesh.name = 'frame';
-        portal.add(frameMesh);
-
-        // Inner energy field
-        const fieldGeo = new THREE.CircleGeometry(1.8, 64);
-        const fieldMat = new THREE.MeshBasicMaterial({
-            color: energy,
-            transparent: true,
-            opacity: 0.4,
-            side: THREE.DoubleSide,
-        });
-        const field = new THREE.Mesh(fieldGeo, fieldMat);
-        field.name = 'energy_field';
-        portal.add(field);
-
-        // Particle ring
-        createParticleRing(portal);
-    }
-
-    /**
-     * Create rectangular portal
-     */
-    function createRectangularPortal(portal) {
-        const { frame, energy } = PORTAL_CONFIG.colors;
-        const width = 3;
-        const height = 4;
-
-        // Frame segments
-        const frameMat = new THREE.MeshStandardMaterial({
-            color: frame,
-            emissive: frame,
-            emissiveIntensity: 0.5,
-            roughness: 0.3,
-            metalness: 0.9,
-        });
-
-        // Create frame border
-        const borderGeo = new THREE.BoxGeometry(width + 0.4, height + 0.4, 0.2);
-        const border = new THREE.Mesh(borderGeo, frameMat);
-        border.name = 'frame';
-        portal.add(border);
-
-        // Inner field
-        const fieldGeo = new THREE.PlaneGeometry(width, height);
-        const fieldMat = new THREE.MeshBasicMaterial({
-            color: energy,
-            transparent: true,
-            opacity: 0.4,
-            side: THREE.DoubleSide,
-        });
-        const field = new THREE.Mesh(fieldGeo, fieldMat);
-        field.name = 'energy_field';
-        portal.add(field);
-    }
-
-    /**
-     * Create stargate-style portal
-     */
-    function createStargatePortal(portal) {
-        const { frame } = PORTAL_CONFIG.colors;
-
-        // Main ring
-        const ringGeo = new THREE.TorusGeometry(2, 0.3, 16, 100);
-        const ringMat = new THREE.MeshStandardMaterial({
-            color: frame,
-            emissive: frame,
-            emissiveIntensity: 0.4,
-            roughness: 0.4,
-            metalness: 0.8,
-        });
-        const ring = new THREE.Mesh(ringGeo, ringMat);
-        ring.name = 'main_ring';
-        portal.add(ring);
-
-        // Chevron decorations
-        for (let i = 0; i < 9; i++) {
-            const angle = (i / 9) * Math.PI * 2;
-            const chevron = createChevron();
-            chevron.position.set(
-                Math.cos(angle) * 2,
-                Math.sin(angle) * 2,
-                0
-            );
-            chevron.rotation.z = angle + Math.PI / 2;
-            chevron.name = `chevron_${i}`;
-            portal.add(chevron);
-        }
-
-        // Inner vortex
-        const vortexGeo = new THREE.CircleGeometry(1.7, 32);
-        const vortexMat = new THREE.MeshBasicMaterial({
-            color: PORTAL_CONFIG.colors.energy,
-            transparent: true,
-            opacity: 0.5,
-        });
-        const vortex = new THREE.Mesh(vortexGeo, vortexMat);
-        vortex.name = 'vortex';
-        portal.add(vortex);
-    }
-
-    /**
-     * Create a chevron for stargate style
-     */
-    function createChevron() {
-        const shape = new THREE.Shape();
-        shape.moveTo(-0.2, 0);
-        shape.lineTo(0, 0.4);
-        shape.lineTo(0.2, 0);
-        shape.lineTo(-0.2, 0);
-
-        const geo = new THREE.ExtrudeGeometry(shape, {
-            depth: 0.1,
-            bevelEnabled: false
-        });
-        const mat = new THREE.MeshStandardMaterial({
-            color: PORTAL_CONFIG.colors.frame,
-            emissive: PORTAL_CONFIG.colors.frame,
-            emissiveIntensity: 0.3,
-        });
-
-        return new THREE.Mesh(geo, mat);
-    }
-
-    /**
-     * Create particle ring effect
-     */
-    function createParticleRing(portal) {
-        const particleCount = 50;
-        const particles = new THREE.BufferGeometry();
-        const positions = new Float32Array(particleCount * 3);
-
-        for (let i = 0; i < particleCount; i++) {
-            const angle = (i / particleCount) * Math.PI * 2;
-            const radius = 2 + (Math.random() - 0.5) * 0.4;
-            positions[i * 3] = Math.cos(angle) * radius;
-            positions[i * 3 + 1] = Math.sin(angle) * radius;
-            positions[i * 3 + 2] = (Math.random() - 0.5) * 0.5;
-        }
-
-        particles.setAttribute('position', new THREE.BufferAttribute(positions, 3));
-
-        const particleMat = new THREE.PointsMaterial({
-            color: PORTAL_CONFIG.colors.energy,
-            size: 0.05,
-            transparent: true,
-            opacity: 0.8,
-        });
-
-        const particleSystem = new THREE.Points(particles, particleMat);
-        particleSystem.name = 'particles';
-        portal.add(particleSystem);
-    }
-
-    /**
-     * Create trigger zone for teleportation
-     */
-    function createTriggerZone(portal) {
-        const triggerGeo = new THREE.CylinderGeometry(
-            PORTAL_CONFIG.collision.radius,
-            PORTAL_CONFIG.collision.radius,
-            PORTAL_CONFIG.collision.height,
-            32
-        );
-        const triggerMat = new THREE.MeshBasicMaterial({
-            color: 0x00ff00,
-            transparent: true,
-            opacity: 0.0,  // Invisible
-            wireframe: true,
-        });
-        const trigger = new THREE.Mesh(triggerGeo, triggerMat);
-        trigger.position.y = PORTAL_CONFIG.collision.height / 2;
-        trigger.name = 'trigger_zone';
-        trigger.userData.isTrigger = true;
-        portal.add(trigger);
-    }
-
-    /**
-     * Setup portal animation
-     */
-    function setupAnimation(portal) {
-        const { rotationSpeed, pulseSpeed, pulseAmplitude } = PORTAL_CONFIG.animation;
-
-        portal.userData.animate = function(time) {
-            // Rotate energy field
-            const energyField = this.getObjectByName('energy_field') || 
-                               this.getObjectByName('vortex');
-            if (energyField) {
-                energyField.rotation.z = time * rotationSpeed;
-            }
-
-            // Pulse effect
-            const pulse = 1 + Math.sin(time * pulseSpeed) * pulseAmplitude;
-            const frame = this.getObjectByName('frame') || 
-                         this.getObjectByName('main_ring');
-            if (frame) {
-                frame.scale.set(pulse, pulse, 1);
-            }
-
-            // Animate particles
-            const particles = this.getObjectByName('particles');
-            if (particles) {
-                particles.rotation.z = -time * rotationSpeed * 0.5;
-            }
-        };
-    }
-
-    /**
-     * Check if a point is inside the portal trigger zone
-     */
-    function checkTrigger(portal, point) {
-        const trigger = portal.getObjectByName('trigger_zone');
-        if (!trigger) return false;
-
-        // Simple distance check
-        const dx = point.x - portal.position.x;
-        const dz = point.z - portal.position.z;
-        const distance = Math.sqrt(dx * dx + dz * dz);
-
-        return distance < PORTAL_CONFIG.collision.radius;
-    }
-
-    /**
-     * Activate/deactivate portal
-     */
-    function setActive(portal, active) {
-        portal.userData.isActive = active;
-        
-        const energyField = portal.getObjectByName('energy_field') || 
-                           portal.getObjectByName('vortex');
-        if (energyField) {
-            energyField.visible = active;
-        }
-    }
-
-    // Export
-    if (typeof module !== 'undefined' && module.exports) {
-        module.exports = { 
-            createPortal, 
-            checkTrigger, 
-            setActive,
-            PORTAL_CONFIG 
-        };
-    } else if (typeof window !== 'undefined') {
-        window.NexusPortals = window.NexusPortals || {};
-        window.NexusPortals.create = createPortal;
-    }
-
-    return { createPortal, checkTrigger, setActive, PORTAL_CONFIG };
-})();

config/timmy-deploy.sh

@@ -1,59 +0,0 @@
-#!/bin/bash
-# Deploy kimi-primary config to Timmy (Anthropic BANNED)
-# Run this from Timmy's VPS or via SSH
-
-set -e
-
-TIMMY_HOST="${TIMMY_HOST:-timmy}"
-TIMMY_HERMES_HOME="/root/wizards/timmy/hermes-agent"
-CONFIG_SOURCE="$(dirname "$0")/fallback-config.yaml"
-
-# Colors
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-RED='\033[0;31m'
-NC='\033[0m'
-
-echo -e "${GREEN}[DEPLOY]${NC} Timmy Fallback Configuration"
-echo "==============================================="
-echo ""
-
-# Check prerequisites
-if [ ! -f "$CONFIG_SOURCE" ]; then
-    echo -e "${RED}[ERROR]${NC} Config not found: $CONFIG_SOURCE"
-    exit 1
-fi
-
-# Show what we're deploying
-echo "Configuration to deploy:"
-echo "------------------------"
-grep -v "^#" "$CONFIG_SOURCE" | grep -v "^$" | head -20
-echo ""
-
-# Deploy to Timmy
-echo -e "${GREEN}[DEPLOY]${NC} Copying config to Timmy..."
-
-# Backup existing
-ssh root@$TIMMY_HOST "cp $TIMMY_HERMES_HOME/config.yaml $TIMMY_HERMES_HOME/config.yaml.backup.$(date +%s) 2>/dev/null || true"
-
-# Copy new config
-scp "$CONFIG_SOURCE" root@$TIMMY_HOST:$TIMMY_HERMES_HOME/config.yaml
-
-# Verify KIMI_API_KEY exists
-echo -e "${GREEN}[VERIFY]${NC} Checking KIMI_API_KEY on Timmy..."
-ssh root@$TIMMY_HOST "grep -q KIMI_API_KEY $TIMMY_HERMES_HOME/.env && echo 'KIMI_API_KEY found' || echo 'WARNING: KIMI_API_KEY not set'"
-
-# Restart Timmy gateway if running
-echo -e "${GREEN}[RESTART]${NC} Restarting Timmy gateway..."
-ssh root@$TIMMY_HOST "cd $TIMMY_HERMES_HOME && pkill -f 'hermes gateway' 2>/dev/null || true"
-sleep 2
-ssh root@$TIMMY_HOST "cd $TIMMY_HERMES_HOME && nohup python -m gateway.run > logs/gateway.log 2>&1 &"
-
-echo ""
-echo -e "${GREEN}[SUCCESS]${NC} Timmy is now running with Kimi primary + Gemini fallback!"
-echo ""
-echo "Kimi: PRIMARY ✓"
-echo "Gemini: FALLBACK (via OpenRouter) ✓"
-echo "Ollama: LOCAL FALLBACK ✓"
-echo ""
-echo "To verify: ssh root@$TIMMY_HOST 'tail -f $TIMMY_HERMES_HOME/logs/gateway.log'"

cron/__init__.py

@@ -26,11 +26,11 @@ from cron.jobs import (
     trigger_job,
     JOBS_FILE,
 )
-from cron.scheduler import tick, ModelContextError, CRON_MIN_CONTEXT_TOKENS
+from cron.scheduler import tick
 
 __all__ = [
     "create_job",
-    "get_job",
+    "get_job", 
     "list_jobs",
     "remove_job",
     "update_job",
@@ -39,6 +39,4 @@ __all__ = [
     "trigger_job",
     "tick",
     "JOBS_FILE",
-    "ModelContextError",
-    "CRON_MIN_CONTEXT_TOKENS",
 ]

cron/jobs.py

@@ -547,68 +547,20 @@ def resume_job(job_id: str) -> Optional[Dict[str, Any]]:
 
 
 def trigger_job(job_id: str) -> Optional[Dict[str, Any]]:
-    """Schedule a job to run on the next scheduler tick.
-    
-    Clears stale error state when re-triggering a previously-failed job
-    so the stale failure doesn't persist until the next tick completes.
-    """
+    """Schedule a job to run on the next scheduler tick."""
     job = get_job(job_id)
     if not job:
         return None
-    
-    updates = {
-        "enabled": True,
-        "state": "scheduled",
-        "paused_at": None,
-        "paused_reason": None,
-        "next_run_at": _hermes_now().isoformat(),
-    }
-    
-    # Clear stale error state when re-triggering
-    if job.get("last_status") == "error":
-        updates["last_status"] = "retrying"
-        updates["last_error"] = None
-        updates["error_cleared_at"] = _hermes_now().isoformat()
-    
-    return update_job(job_id, updates)
-
-
-def run_job_now(job_id: str) -> Optional[Dict[str, Any]]:
-    """
-    Execute a job immediately and persist fresh state.
-
-    Unlike trigger_job() which queues for the next scheduler tick,
-    this runs the job synchronously and returns the result.
-    Clears stale error state on success.
-
-    Returns:
-        Dict with 'job', 'success', 'output', 'error' keys, or None if not found.
-    """
-    job = get_job(job_id)
-    if not job:
-        return None
-
-    try:
-        from cron.scheduler import run_job as _run_job
-    except ImportError as exc:
-        return {
-            "job": job,
-            "success": False,
-            "output": None,
-            "error": f"Cannot import scheduler: {exc}",
-        }
-
-    success, output, final_response, error = _run_job(job)
-    mark_job_run(job_id, success, error)
-
-    updated_job = get_job(job_id) or job
-    return {
-        "job": updated_job,
-        "success": success,
-        "output": output,
-        "final_response": final_response,
-        "error": error,
-    }
+    return update_job(
+        job_id,
+        {
+            "enabled": True,
+            "state": "scheduled",
+            "paused_at": None,
+            "paused_reason": None,
+            "next_run_at": _hermes_now().isoformat(),
+        },
+    )
 
 
 def remove_job(job_id: str) -> bool:
@@ -622,13 +574,16 @@ def remove_job(job_id: str) -> bool:
     return False
 
 
-def mark_job_run(job_id: str, success: bool, error: Optional[str] = None):
+def mark_job_run(job_id: str, success: bool, error: Optional[str] = None,
+                 delivery_error: Optional[str] = None):
     """
     Mark a job as having been run.
     
     Updates last_run_at, last_status, increments completed count,
     computes next_run_at, and auto-deletes if repeat limit reached.
-    Tracks health timestamps for error/success history.
+
+    ``delivery_error`` is tracked separately from the agent error — a job
+    can succeed (agent produced output) but fail delivery (platform down).
     """
     jobs = load_jobs()
     for i, job in enumerate(jobs):
@@ -637,18 +592,8 @@ def mark_job_run(job_id: str, success: bool, error: Optional[str] = None):
             job["last_run_at"] = now
             job["last_status"] = "ok" if success else "error"
             job["last_error"] = error if not success else None
-            
-            # Track health timestamps
-            if success:
-                job["last_success_at"] = now
-                # Clear stale error tracking on success
-                if job.get("last_error_at"):
-                    job["error_resolved_at"] = now
-            else:
-                job["last_error_at"] = now
-                # Clear resolved tracking on new error
-                if job.get("error_resolved_at"):
-                    del job["error_resolved_at"]
+            # Track delivery failures separately — cleared on successful delivery
+            job["last_delivery_error"] = delivery_error
             
             # Increment completed count
             if job.get("repeat"):
@@ -679,32 +624,6 @@ def mark_job_run(job_id: str, success: bool, error: Optional[str] = None):
     save_jobs(jobs)
 
 
-
-def clear_job_error(job_id: str) -> Optional[Dict[str, Any]]:
-    """
-    Clear stale error state for a job.
-    
-    Resets last_status to 'ok', last_error to None, and 
-    records when the error was cleared. Useful after auth
-    recovery when the job itself is healthy but stale error
-    state persists.
-    
-    Returns:
-        Updated job dict, or None if not found.
-    """
-    jobs = load_jobs()
-    for job in jobs:
-        if job["id"] == job_id:
-            job["last_status"] = "ok"
-            job["last_error"] = None
-            job["error_cleared_at"] = _hermes_now().isoformat()
-            save_jobs(jobs)
-            return job
-    save_jobs(jobs)
-    return None
-
-
-
 def advance_next_run(job_id: str) -> bool:
     """Preemptively advance next_run_at for a recurring job before execution.
 

cron/scheduler.py

@@ -25,7 +25,6 @@ except ImportError:
         import msvcrt
     except ImportError:
         msvcrt = None
-import time
 from pathlib import Path
 from typing import Optional
 
@@ -37,116 +36,9 @@ sys.path.insert(0, str(Path(__file__).parent.parent))
 from hermes_constants import get_hermes_home
 from hermes_cli.config import load_config
 from hermes_time import now as _hermes_now
-from agent.model_metadata import is_local_endpoint
 
 logger = logging.getLogger(__name__)
 
-
-# =====================================================================
-# Deploy Sync Guard
-# =====================================================================
-#
-# If the installed run_agent.py diverges from the version scheduler.py
-# was written against, every cron job fails with:
-#   TypeError: AIAgent.__init__() got an unexpected keyword argument '...'
-#
-# _validate_agent_interface() catches this at the FIRST job, not the
-# 55th.  It uses inspect.signature() to verify every kwarg we pass is
-# accepted by AIAgent.__init__().
-#
-# Maintaining this list: if you add a kwarg to the AIAgent() call in
-# run_job(), add it here too.  The guard catches mismatches.
-
-_SCHEDULER_AGENT_KWARGS: set = frozenset({
-    "model", "api_key", "base_url", "provider", "api_mode",
-    "acp_command", "acp_args", "max_iterations", "reasoning_config",
-    "prefill_messages", "providers_allowed", "providers_ignored",
-    "providers_order", "provider_sort", "disabled_toolsets",
-    "tool_choice", "quiet_mode", "skip_memory", "platform",
-    "session_id", "session_db",
-})
-
-_agent_interface_validated: bool = False
-
-
-def _validate_agent_interface() -> None:
-    """Verify installed AIAgent.__init__ accepts every kwarg the scheduler passes.
-
-    Raises RuntimeError with actionable guidance if params are missing.
-    Caches result — runs once per gateway process lifetime.
-    """
-    global _agent_interface_validated
-    if _agent_interface_validated:
-        return
-
-    import inspect
-
-    try:
-        from run_agent import AIAgent
-    except ImportError as exc:
-        raise RuntimeError(
-            f"Cannot import AIAgent: {exc}\n"
-            "Is hermes-agent installed? Check PYTHONPATH."
-        ) from exc
-
-    sig = inspect.signature(AIAgent.__init__)
-    accepted = set(sig.parameters.keys()) - {"self"}
-    missing = _SCHEDULER_AGENT_KWARGS - accepted
-
-    if missing:
-        sorted_missing = sorted(missing)
-        raise RuntimeError(
-            "Deploy sync guard FAILED — AIAgent.__init__() is missing params:\n"
-            f"  {', '.join(sorted_missing)}\n"
-            "This means the installed run_agent.py is out of date.\n"
-            "Fix: pull latest hermes-agent code and restart the gateway.\n"
-            "  cd ~/.hermes/hermes-agent && git pull && source venv/bin/activate"
-        )
-
-    _agent_interface_validated = True
-    logger.debug("Deploy sync guard passed — %d params verified", len(_SCHEDULER_AGENT_KWARGS))
-
-
-def _safe_agent_kwargs(kwargs: dict) -> dict:
-    """Filter kwargs to only those accepted by installed AIAgent.__init__.
-
-    More resilient than _validate_agent_interface() alone: instead of
-    crashing on mismatch, drops unsupported kwargs and logs a warning.
-    Jobs run with degraded functionality instead of failing entirely.
-
-    Args:
-        kwargs: The kwargs dict the scheduler wants to pass to AIAgent().
-
-    Returns:
-        A new dict containing only kwargs the installed AIAgent accepts.
-    """
-    import inspect
-
-    try:
-        from run_agent import AIAgent
-    except ImportError:
-        # Can't import — pass everything through, let the real error surface
-        return kwargs
-
-    sig = inspect.signature(AIAgent.__init__)
-    accepted = set(sig.parameters.keys()) - {"self"}
-
-    safe = {}
-    dropped = []
-    for key, value in kwargs.items():
-        if key in accepted:
-            safe[key] = value
-        else:
-            dropped.append(key)
-
-    if dropped:
-        logger.warning(
-            "Dropping unsupported AIAgent kwargs (stale install?): %s",
-            ", ".join(sorted(dropped)),
-        )
-
-    return safe
-
 # Valid delivery platforms — used to validate user-supplied platform names
 # in cron delivery targets, preventing env var enumeration via crafted names.
 _KNOWN_DELIVERY_PLATFORMS = frozenset({
@@ -161,72 +53,6 @@ from cron.jobs import get_due_jobs, mark_job_run, save_job_output, advance_next_
 # response with this marker to suppress delivery.  Output is still saved
 # locally for audit.
 SILENT_MARKER = "[SILENT]"
-SCRIPT_FAILED_MARKER = "[SCRIPT_FAILED]"
-
-# Failure phrases that indicate an external script/command failed, even when
-# the agent doesn't use the [SCRIPT_FAILED] marker.  Matched case-insensitively
-# against the final response.  These are strong signals — agents rarely use
-# these words when a script succeeded.
-_SCRIPT_FAILURE_PHRASES = (
-    "timed out",
-    "timeout",
-    "connection error",
-    "connection refused",
-    "connection reset",
-    "failed to execute",
-    "failed due to",
-    "script failed",
-    "script error",
-    "command failed",
-    "exit code",
-    "exit status",
-    "non-zero exit",
-    "did not complete",
-    "could not run",
-    "unable to execute",
-    "permission denied",
-    "no such file",
-    "traceback",
-)
-
-
-def _detect_script_failure(final_response: str) -> Optional[str]:
-    """Detect script failure from agent's final response.
-
-    Returns a reason string if failure detected, None otherwise.
-    Checks both the explicit [SCRIPT_FAILED] marker and heuristic patterns.
-    """
-    if not final_response:
-        return None
-
-    # 1. Explicit marker — highest confidence.
-    if SCRIPT_FAILED_MARKER in final_response.upper():
-        import re as _re
-        _m = _re.search(
-            r'\[SCRIPT_FAILED\]\s*:?\s*(.*)',
-            final_response,
-            _re.IGNORECASE,
-        )
-        reason = _m.group(1).strip() if _m and _m.group(1).strip() else None
-        return reason or "Agent reported script failure"
-
-    # 2. Heuristic detection — catch failures described in natural language.
-    #    Only flag if the response contains failure language AND does NOT
-    #    contain success markers like [NOOP] (which means the script ran fine
-    #    but found nothing).
-    lower = final_response.lower()
-    has_noop = "[noop]" in lower
-    has_silent = "[silent]" in lower
-
-    if has_noop or has_silent:
-        return None  # Agent explicitly signaled success/nothing-to-report
-
-    for phrase in _SCRIPT_FAILURE_PHRASES:
-        if phrase in lower:
-            return f"Detected script failure phrase: '{phrase}'"
-
-    return None
-
 
 # Resolve Hermes home directory (respects HERMES_HOME override)
 _hermes_home = get_hermes_home()
@@ -332,7 +158,45 @@ def _resolve_delivery_target(job: dict) -> Optional[dict]:
     }
 
 
-def _deliver_result(job: dict, content: str, adapters=None, loop=None) -> None:
+# Media extension sets — keep in sync with gateway/platforms/base.py:_process_message_background
+_AUDIO_EXTS = frozenset({'.ogg', '.opus', '.mp3', '.wav', '.m4a'})
+_VIDEO_EXTS = frozenset({'.mp4', '.mov', '.avi', '.mkv', '.webm', '.3gp'})
+_IMAGE_EXTS = frozenset({'.jpg', '.jpeg', '.png', '.webp', '.gif'})
+
+
+def _send_media_via_adapter(adapter, chat_id: str, media_files: list, metadata: dict | None, loop, job: dict) -> None:
+    """Send extracted MEDIA files as native platform attachments via a live adapter.
+
+    Routes each file to the appropriate adapter method (send_voice, send_image_file,
+    send_video, send_document) based on file extension — mirroring the routing logic
+    in ``BasePlatformAdapter._process_message_background``.
+    """
+    from pathlib import Path
+
+    for media_path, _is_voice in media_files:
+        try:
+            ext = Path(media_path).suffix.lower()
+            if ext in _AUDIO_EXTS:
+                coro = adapter.send_voice(chat_id=chat_id, audio_path=media_path, metadata=metadata)
+            elif ext in _VIDEO_EXTS:
+                coro = adapter.send_video(chat_id=chat_id, video_path=media_path, metadata=metadata)
+            elif ext in _IMAGE_EXTS:
+                coro = adapter.send_image_file(chat_id=chat_id, image_path=media_path, metadata=metadata)
+            else:
+                coro = adapter.send_document(chat_id=chat_id, file_path=media_path, metadata=metadata)
+
+            future = asyncio.run_coroutine_threadsafe(coro, loop)
+            result = future.result(timeout=30)
+            if result and not getattr(result, "success", True):
+                logger.warning(
+                    "Job '%s': media send failed for %s: %s",
+                    job.get("id", "?"), media_path, getattr(result, "error", "unknown"),
+                )
+        except Exception as e:
+            logger.warning("Job '%s': failed to send media %s: %s", job.get("id", "?"), media_path, e)
+
+
+def _deliver_result(job: dict, content: str, adapters=None, loop=None) -> Optional[str]:
     """
     Deliver job output to the configured target (origin chat, specific platform, etc.).
 
@@ -340,16 +204,16 @@ def _deliver_result(job: dict, content: str, adapters=None, loop=None) -> None:
     use the live adapter first — this supports E2EE rooms (e.g. Matrix) where
     the standalone HTTP path cannot encrypt.  Falls back to standalone send if
     the adapter path fails or is unavailable.
+
+    Returns None on success, or an error string on failure.
     """
     target = _resolve_delivery_target(job)
     if not target:
         if job.get("deliver", "local") != "local":
-            logger.warning(
-                "Job '%s' deliver=%s but no concrete delivery target could be resolved",
-                job["id"],
-                job.get("deliver", "local"),
-            )
-        return
+            msg = f"no delivery target resolved for deliver={job.get('deliver', 'local')}"
+            logger.warning("Job '%s': %s", job["id"], msg)
+            return msg
+        return None  # local-only jobs don't deliver — not a failure
 
     platform_name = target["platform"]
     chat_id = target["chat_id"]
@@ -375,19 +239,22 @@ def _deliver_result(job: dict, content: str, adapters=None, loop=None) -> None:
     }
     platform = platform_map.get(platform_name.lower())
     if not platform:
-        logger.warning("Job '%s': unknown platform '%s' for delivery", job["id"], platform_name)
-        return
+        msg = f"unknown platform '{platform_name}'"
+        logger.warning("Job '%s': %s", job["id"], msg)
+        return msg
 
     try:
         config = load_gateway_config()
     except Exception as e:
-        logger.error("Job '%s': failed to load gateway config for delivery: %s", job["id"], e)
-        return
+        msg = f"failed to load gateway config: {e}"
+        logger.error("Job '%s': %s", job["id"], msg)
+        return msg
 
     pconfig = config.platforms.get(platform)
     if not pconfig or not pconfig.enabled:
-        logger.warning("Job '%s': platform '%s' not configured/enabled", job["id"], platform_name)
-        return
+        msg = f"platform '{platform_name}' not configured/enabled"
+        logger.warning("Job '%s': %s", job["id"], msg)
+        return msg
 
     # Optionally wrap the content with a header/footer so the user knows this
     # is a cron delivery.  Wrapping is on by default; set cron.wrap_response: false
@@ -420,20 +287,30 @@ def _deliver_result(job: dict, content: str, adapters=None, loop=None) -> None:
     if runtime_adapter is not None and loop is not None and getattr(loop, "is_running", lambda: False)():
         send_metadata = {"thread_id": thread_id} if thread_id else None
         try:
-            future = asyncio.run_coroutine_threadsafe(
-                runtime_adapter.send(chat_id, delivery_content, metadata=send_metadata),
-                loop,
-            )
-            send_result = future.result(timeout=60)
-            if send_result and not getattr(send_result, "success", True):
-                err = getattr(send_result, "error", "unknown")
-                logger.warning(
-                    "Job '%s': live adapter send to %s:%s failed (%s), falling back to standalone",
-                    job["id"], platform_name, chat_id, err,
+            # Send cleaned text (MEDIA tags stripped) — not the raw content
+            text_to_send = cleaned_delivery_content.strip()
+            adapter_ok = True
+            if text_to_send:
+                future = asyncio.run_coroutine_threadsafe(
+                    runtime_adapter.send(chat_id, text_to_send, metadata=send_metadata),
+                    loop,
                 )
-            else:
+                send_result = future.result(timeout=60)
+                if send_result and not getattr(send_result, "success", True):
+                    err = getattr(send_result, "error", "unknown")
+                    logger.warning(
+                        "Job '%s': live adapter send to %s:%s failed (%s), falling back to standalone",
+                        job["id"], platform_name, chat_id, err,
+                    )
+                    adapter_ok = False  # fall through to standalone path
+
+            # Send extracted media files as native attachments via the live adapter
+            if adapter_ok and media_files:
+                _send_media_via_adapter(runtime_adapter, chat_id, media_files, send_metadata, loop, job)
+
+            if adapter_ok:
                 logger.info("Job '%s': delivered to %s:%s via live adapter", job["id"], platform_name, chat_id)
-                return
+                return None
         except Exception as e:
             logger.warning(
                 "Job '%s': live adapter delivery to %s:%s failed (%s), falling back to standalone",
@@ -455,13 +332,17 @@ def _deliver_result(job: dict, content: str, adapters=None, loop=None) -> None:
             future = pool.submit(asyncio.run, _send_to_platform(platform, pconfig, chat_id, cleaned_delivery_content, thread_id=thread_id, media_files=media_files))
             result = future.result(timeout=30)
     except Exception as e:
-        logger.error("Job '%s': delivery to %s:%s failed: %s", job["id"], platform_name, chat_id, e)
-        return
+        msg = f"delivery to {platform_name}:{chat_id} failed: {e}"
+        logger.error("Job '%s': %s", job["id"], msg)
+        return msg
 
     if result and result.get("error"):
-        logger.error("Job '%s': delivery error: %s", job["id"], result["error"])
-    else:
-        logger.info("Job '%s': delivered to %s:%s", job["id"], platform_name, chat_id)
+        msg = f"delivery error: {result['error']}"
+        logger.error("Job '%s': %s", job["id"], msg)
+        return msg
+
+    logger.info("Job '%s': delivered to %s:%s", job["id"], platform_name, chat_id)
+    return None
 
 
 _SCRIPT_TIMEOUT = 120  # seconds
@@ -587,15 +468,7 @@ def _build_job_prompt(job: dict) -> str:
         "SILENT: If there is genuinely nothing new to report, respond "
         "with exactly \"[SILENT]\" (nothing else) to suppress delivery. "
         "Never combine [SILENT] with content — either report your "
-        "findings normally, or say [SILENT] and nothing more. "
-        "SCRIPT_FAILURE: If an external command or script you ran "
-        "failed (timeout, crash, connection error, non-zero exit), you MUST "
-        "respond with "
-        "\"[SCRIPT_FAILED]: <one-line reason>\" as the FIRST LINE of your "
-        "response. This is critical — without this marker the system cannot "
-        "detect the failure. Examples: "
-        "\"[SCRIPT_FAILED]: forge.alexanderwhitestone.com timed out\" "
-        "\"[SCRIPT_FAILED]: script exited with code 1\".]\\n\\n"
+        "findings normally, or say [SILENT] and nothing more.]\n\n"
     )
     prompt = cron_hint + prompt
     if skills is None:
@@ -650,10 +523,6 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
     Returns:
         Tuple of (success, full_output_doc, final_response, error_message)
     """
-    # Deploy sync guard — fail fast on first job if the installed
-    # AIAgent.__init__ is missing params the scheduler expects.
-    _validate_agent_interface()
-
     from run_agent import AIAgent
     
     # Initialize SQLite session store so cron job messages are persisted
@@ -716,27 +585,9 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
         except Exception as e:
             logger.warning("Job '%s': failed to load config.yaml, using defaults: %s", job_id, e)
 
-        # Reasoning config from env or config.yaml
+        # Reasoning config from config.yaml
         from hermes_constants import parse_reasoning_effort
-
-        # Time-aware cron model routing — override model during high-error windows
-        try:
-            from agent.smart_model_routing import resolve_cron_model
-            _cron_routing_cfg = (_cfg.get("cron_model_routing") or {})
-            _cron_route = resolve_cron_model(model, _cron_routing_cfg)
-            if _cron_route["overridden"]:
-                _original_model = model
-                model = _cron_route["model"]
-                logger.info(
-                    "Job '%s': cron model override %s -> %s (%s)",
-                    job_id, _original_model, model, _cron_route["reason"],
-                )
-        except Exception as _e:
-            logger.debug("Job '%s': cron model routing skipped: %s", job_id, _e)
-
-        effort = os.getenv("HERMES_REASONING_EFFORT", "")
-        if not effort:
-            effort = str(_cfg.get("agent", {}).get("reasoning_effort", "")).strip()
+        effort = str(_cfg.get("agent", {}).get("reasoning_effort", "")).strip()
         reasoning_config = parse_reasoning_effort(effort)
 
         # Prefill messages from env or config.yaml
@@ -794,53 +645,28 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
             },
         )
 
-        # Build disabled toolsets — always exclude cronjob/messaging/clarify
-        # for cron sessions.  When the runtime endpoint is cloud (not local),
-        # also disable terminal so the agent does not attempt SSH or shell
-        # commands that require local infrastructure (keys, filesystem).
-        # Jobs that declare requires_local_infra=true also get terminal
-        # disabled on cloud endpoints regardless of this check.  #379
-        _cron_disabled = ["cronjob", "messaging", "clarify"]
-        _runtime_base_url = turn_route["runtime"].get("base_url", "")
-        _is_cloud = not is_local_endpoint(_runtime_base_url)
-        if _is_cloud:
-            _cron_disabled.append("terminal")
-            logger.info(
-                "Job '%s': cloud provider detected (%s), disabling terminal toolset",
-                job_name,
-                turn_route["runtime"].get("provider", "unknown"),
-            )
-        if job.get("requires_local_infra") and _is_cloud:
-            logger.warning(
-                "Job '%s': requires_local_infra=true but running on cloud provider — "
-                "terminal-dependent steps will fail gracefully",
-                job_name,
-            )
-
-        _agent_kwargs = _safe_agent_kwargs({
-            "model": turn_route["model"],
-            "api_key": turn_route["runtime"].get("api_key"),
-            "base_url": turn_route["runtime"].get("base_url"),
-            "provider": turn_route["runtime"].get("provider"),
-            "api_mode": turn_route["runtime"].get("api_mode"),
-            "acp_command": turn_route["runtime"].get("command"),
-            "acp_args": list(turn_route["runtime"].get("args") or []),
-            "max_iterations": max_iterations,
-            "reasoning_config": reasoning_config,
-            "prefill_messages": prefill_messages,
-            "providers_allowed": pr.get("only"),
-            "providers_ignored": pr.get("ignore"),
-            "providers_order": pr.get("order"),
-            "provider_sort": pr.get("sort"),
-            "disabled_toolsets": _cron_disabled,
-            "tool_choice": "required",
-            "quiet_mode": True,
-            "skip_memory": True,  # Cron system prompts would corrupt user representations
-            "platform": "cron",
-            "session_id": _cron_session_id,
-            "session_db": _session_db,
-        })
-        agent = AIAgent(**_agent_kwargs)
+        agent = AIAgent(
+            model=turn_route["model"],
+            api_key=turn_route["runtime"].get("api_key"),
+            base_url=turn_route["runtime"].get("base_url"),
+            provider=turn_route["runtime"].get("provider"),
+            api_mode=turn_route["runtime"].get("api_mode"),
+            acp_command=turn_route["runtime"].get("command"),
+            acp_args=turn_route["runtime"].get("args"),
+            max_iterations=max_iterations,
+            reasoning_config=reasoning_config,
+            prefill_messages=prefill_messages,
+            providers_allowed=pr.get("only"),
+            providers_ignored=pr.get("ignore"),
+            providers_order=pr.get("order"),
+            provider_sort=pr.get("sort"),
+            disabled_toolsets=["cronjob", "messaging", "clarify"],
+            quiet_mode=True,
+            skip_memory=True,  # Cron system prompts would corrupt user representations
+            platform="cron",
+            session_id=_cron_session_id,
+            session_db=_session_db,
+        )
         
         # Run the agent with an *inactivity*-based timeout: the job can run
         # for hours if it's actively calling tools / receiving stream tokens,
@@ -853,47 +679,8 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
         _cron_timeout = float(os.getenv("HERMES_CRON_TIMEOUT", 600))
         _cron_inactivity_limit = _cron_timeout if _cron_timeout > 0 else None
         _POLL_INTERVAL = 5.0
-
-        # Guard against interpreter shutdown: ThreadPoolExecutor.submit()
-        # raises RuntimeError("cannot schedule new futures after interpreter
-        # shutdown") when Python is finalizing (e.g. gateway restart races).
-        # Fall back to synchronous execution so the job at least attempts.
-        _cron_pool = None
-        try:
-            _cron_pool = concurrent.futures.ThreadPoolExecutor(max_workers=1)
-            _cron_future = _cron_pool.submit(agent.run_conversation, prompt)
-        except RuntimeError:
-            logger.warning(
-                "Job '%s': ThreadPoolExecutor unavailable (interpreter shutdown?) "
-                "— falling back to synchronous execution",
-                job_name,
-            )
-            if _cron_pool is not None:
-                try:
-                    _cron_pool.shutdown(wait=False)
-                except Exception:
-                    pass
-                _cron_pool = None
-            result = agent.run_conversation(prompt)
-            final_response = result.get("final_response", "") or ""
-            logged_response = final_response if final_response else "(No response generated)"
-            output = f"""# Cron Job: {job_name}
-
-**Job ID:** {job_id}
-**Run Time:** {_hermes_now().strftime('%Y-%m-%d %H:%M:%S')}
-**Schedule:** {job.get('schedule_display', 'N/A')}
-
-## Prompt
-
-{prompt}
-
-## Response
-
-{logged_response}
-"""
-            logger.info("Job '%s' completed (sync fallback)", job_name)
-            return True, output, final_response, None
-
+        _cron_pool = concurrent.futures.ThreadPoolExecutor(max_workers=1)
+        _cron_future = _cron_pool.submit(agent.run_conversation, prompt)
         _inactivity_timeout = False
         try:
             if _cron_inactivity_limit is None:
@@ -920,12 +707,10 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
                         _inactivity_timeout = True
                         break
         except Exception:
-            if _cron_pool is not None:
-                _cron_pool.shutdown(wait=False, cancel_futures=True)
+            _cron_pool.shutdown(wait=False, cancel_futures=True)
             raise
         finally:
-            if _cron_pool is not None:
-                _cron_pool.shutdown(wait=False)
+            _cron_pool.shutdown(wait=False)
 
         if _inactivity_timeout:
             # Build diagnostic summary from the agent's activity tracker.
@@ -960,30 +745,6 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
         # Use a separate variable for log display; keep final_response clean
         # for delivery logic (empty response = no delivery).
         logged_response = final_response if final_response else "(No response generated)"
-
-        # Check for script failure — both explicit [SCRIPT_FAILED] marker
-        # and heuristic detection for failures described in natural language.
-        _script_failed_reason = _detect_script_failure(final_response)
-        if _script_failed_reason is not None:
-            logger.warning(
-                "Job '%s': agent reported script failure — %s",
-                job_name, _script_failed_reason,
-            )
-            output = f"""# Cron Job: {job_name} (SCRIPT FAILED)
-
-**Job ID:** {job_id}
-**Run Time:** {_hermes_now().strftime('%Y-%m-%d %H:%M:%S')}
-**Schedule:** {job.get('schedule_display', 'N/A')}
-
-## Prompt
-
-{prompt}
-
-## Response
-
-{logged_response}
-"""
-            return False, output, final_response, _script_failed_reason
         
         output = f"""# Cron Job: {job_name}
 
@@ -1090,16 +851,6 @@ def tick(verbose: bool = True, adapters=None, loop=None) -> int:
 
         executed = 0
         for job in due_jobs:
-            # If the interpreter is shutting down (e.g. gateway restart),
-            # stop processing immediately — ThreadPoolExecutor.submit()
-            # will raise RuntimeError for every remaining job.
-            if sys.is_finalizing():
-                logger.warning(
-                    "Interpreter finalizing — skipping %d remaining job(s)",
-                    len(due_jobs) - executed,
-                )
-                break
-
             try:
                 # For recurring jobs (cron/interval), advance next_run_at to the
                 # next future occurrence BEFORE execution.  This way, if the
@@ -1122,13 +873,15 @@ def tick(verbose: bool = True, adapters=None, loop=None) -> int:
                     logger.info("Job '%s': agent returned %s — skipping delivery", job["id"], SILENT_MARKER)
                     should_deliver = False
 
+                delivery_error = None
                 if should_deliver:
                     try:
-                        _deliver_result(job, deliver_content, adapters=adapters, loop=loop)
+                        delivery_error = _deliver_result(job, deliver_content, adapters=adapters, loop=loop)
                     except Exception as de:
+                        delivery_error = str(de)
                         logger.error("Delivery failed for job %s: %s", job["id"], de)
 
-                mark_job_run(job["id"], success, error)
+                mark_job_run(job["id"], success, error, delivery_error=delivery_error)
                 executed += 1
 
             except Exception as e:

deploy-crons.py

@@ -1,154 +0,0 @@
-#!/usr/bin/env python3
-"""
-deploy-crons — normalize cron job schemas for consistent model field types.
-
-This script ensures that the model field in jobs.json is always a dict when
-either model or provider is specified, preventing schema inconsistency.
-
-Usage:
-    python deploy-crons.py [--dry-run] [--jobs-file PATH]
-"""
-
-import argparse
-import json
-import sys
-from pathlib import Path
-from typing import Any, Dict, Optional
-
-
-def normalize_job(job: Dict[str, Any]) -> Dict[str, Any]:
-    """
-    Normalize a job dict to ensure consistent model field types.
-
-    Before normalization:
-    - If model AND provider: model = raw string, provider = raw string (inconsistent)
-    - If only model: model = raw string
-    - If only provider: provider = raw string at top level
-
-    After normalization:
-    - If model exists: model = {"model": "xxx"}
-    - If provider exists: model = {"provider": "yyy"}
-    - If both exist: model = {"model": "xxx", "provider": "yyy"}
-    - If neither: model = None
-    """
-    job = dict(job)  # Create a copy to avoid modifying the original
-    
-    model = job.get("model")
-    provider = job.get("provider")
-    
-    # Skip if already normalized (model is a dict)
-    if isinstance(model, dict):
-        return job
-    
-    # Build normalized model dict
-    model_dict = {}
-    
-    if model is not None and isinstance(model, str):
-        model_dict["model"] = model.strip()
-    
-    if provider is not None and isinstance(provider, str):
-        model_dict["provider"] = provider.strip()
-    
-    # Set model field
-    if model_dict:
-        job["model"] = model_dict
-    else:
-        job["model"] = None
-    
-    # Remove top-level provider field if it was moved into model dict
-    if provider is not None and "provider" in model_dict:
-        # Keep provider field for backward compatibility but mark it as deprecated
-        # This allows existing code that reads job["provider"] to continue working
-        pass
-    
-    return job
-
-
-def normalize_jobs_file(jobs_file: Path, dry_run: bool = False) -> int:
-    """
-    Normalize all jobs in a jobs.json file.
-    
-    Returns the number of jobs that were modified.
-    """
-    if not jobs_file.exists():
-        print(f"Error: Jobs file not found: {jobs_file}", file=sys.stderr)
-        return 1
-    
-    try:
-        with open(jobs_file, 'r', encoding='utf-8') as f:
-            data = json.load(f)
-    except json.JSONDecodeError as e:
-        print(f"Error: Invalid JSON in {jobs_file}: {e}", file=sys.stderr)
-        return 1
-    
-    jobs = data.get("jobs", [])
-    if not jobs:
-        print("No jobs found in file.")
-        return 0
-    
-    modified_count = 0
-    for i, job in enumerate(jobs):
-        original_model = job.get("model")
-        original_provider = job.get("provider")
-        
-        normalized_job = normalize_job(job)
-        
-        # Check if anything changed
-        if (normalized_job.get("model") != original_model or
-            normalized_job.get("provider") != original_provider):
-            jobs[i] = normalized_job
-            modified_count += 1
-            
-            job_id = job.get("id", "?")
-            job_name = job.get("name", "(unnamed)")
-            print(f"Normalized job {job_id} ({job_name}):")
-            print(f"  model: {original_model!r} -> {normalized_job.get('model')!r}")
-            print(f"  provider: {original_provider!r} -> {normalized_job.get('provider')!r}")
-    
-    if modified_count == 0:
-        print("All jobs already have consistent model field types.")
-        return 0
-    
-    if dry_run:
-        print(f"DRY RUN: Would normalize {modified_count} jobs.")
-        return 0
-    
-    # Write back to file
-    data["jobs"] = jobs
-    try:
-        with open(jobs_file, 'w', encoding='utf-8') as f:
-            json.dump(data, f, indent=2, ensure_ascii=False)
-        print(f"Normalized {modified_count} jobs in {jobs_file}")
-        return 0
-    except Exception as e:
-        print(f"Error writing to {jobs_file}: {e}", file=sys.stderr)
-        return 1
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Normalize cron job schemas for consistent model field types."
-    )
-    parser.add_argument(
-        "--dry-run",
-        action="store_true",
-        help="Show what would be changed without modifying the file."
-    )
-    parser.add_argument(
-        "--jobs-file",
-        type=Path,
-        default=Path.home() / ".hermes" / "cron" / "jobs.json",
-        help="Path to jobs.json file (default: ~/.hermes/cron/jobs.json)"
-    )
-    
-    args = parser.parse_args()
-    
-    if args.dry_run:
-        print("DRY RUN MODE — no changes will be made.")
-        print()
-    
-    return normalize_jobs_file(args.jobs_file, args.dry_run)
-
-
-if __name__ == "__main__":
-    sys.exit(main())

deploy/docker-compose.override.yml.example

@@ -1,33 +0,0 @@
-# docker-compose.override.yml.example
-#
-# Copy this file to docker-compose.override.yml and uncomment sections as needed.
-# Override files are merged on top of docker-compose.yml automatically.
-# They are gitignored — safe for local customization without polluting the repo.
-
-services:
-  hermes:
-    # --- Local build (for development) ---
-    # build:
-    #   context: ..
-    #   dockerfile: ../Dockerfile
-    #   target: development
-
-    # --- Expose gateway port externally (dev only — not for production) ---
-    # ports:
-    #   - "8642:8642"
-
-    # --- Attach to a custom network shared with other local services ---
-    # networks:
-    #   - myapp_network
-
-    # --- Override resource limits for a smaller VPS ---
-    # deploy:
-    #   resources:
-    #     limits:
-    #       cpus: "0.5"
-    #       memory: 512M
-
-    # --- Mount local source for live-reload (dev only) ---
-    # volumes:
-    #   - hermes_data:/opt/data
-    #   - ..:/opt/hermes:ro

deploy/docker-compose.yml

@@ -1,85 +0,0 @@
-# Hermes Agent — Docker Compose Stack
-# Brings up the agent + messaging gateway as a single unit.
-#
-# Usage:
-#   docker compose up -d          # start in background
-#   docker compose logs -f        # follow logs
-#   docker compose down           # stop and remove containers
-#   docker compose pull && docker compose up -d  # rolling update
-#
-# Secrets:
-#   Never commit .env to version control. Copy .env.example → .env and fill it in.
-#   See DEPLOY.md for the full environment-variable reference.
-
-services:
-  hermes:
-    image: ghcr.io/nousresearch/hermes-agent:latest
-    # To build locally instead:
-    # build:
-    #   context: ..
-    #   dockerfile: ../Dockerfile
-    container_name: hermes-agent
-    restart: unless-stopped
-
-    # Bind-mount the data volume so state (sessions, logs, memories, cron)
-    # survives container replacement.
-    volumes:
-      - hermes_data:/opt/data
-
-    # Load secrets from the .env file next to docker-compose.yml.
-    # The file is bind-mounted at runtime; it is NOT baked into the image.
-    env_file:
-      - ../.env
-
-    environment:
-      # Override the data directory so it always points at the volume.
-      HERMES_HOME: /opt/data
-
-    # Expose the OpenAI-compatible API server (if api_server platform enabled).
-    # Comment out or remove if you are not using the API server.
-    ports:
-      - "127.0.0.1:8642:8642"
-
-    healthcheck:
-      # Hits the API server's /health endpoint.  The gateway writes its own
-      # health state to /opt/data/gateway_state.json — checked by the
-      # health-check script in scripts/deploy-validate.
-      test: ["CMD", "python3", "-c",
-             "import urllib.request; urllib.request.urlopen('http://localhost:8642/health', timeout=5)"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 60s
-
-    # The container does not need internet on a private network;
-    # restrict egress as needed via your host firewall.
-    networks:
-      - hermes_net
-
-    logging:
-      driver: "json-file"
-      options:
-        max-size: "50m"
-        max-file: "5"
-
-    # Resource limits: tune for your VPS size.
-    # 2 GB RAM and 1.5 CPUs work for most conversational workloads.
-    deploy:
-      resources:
-        limits:
-          cpus: "1.5"
-          memory: 2G
-        reservations:
-          memory: 512M
-
-volumes:
-  hermes_data:
-    # Named volume — Docker manages the lifecycle.
-    # To inspect: docker volume inspect hermes_data
-    # To back up:
-    #   docker run --rm -v hermes_data:/data -v $(pwd):/backup \
-    #     alpine tar czf /backup/hermes_data_$(date +%F).tar.gz /data
-
-networks:
-  hermes_net:
-    driver: bridge

deploy/hermes-agent.service

@@ -1,59 +0,0 @@
-# systemd unit — Hermes Agent (interactive CLI / headless agent)
-#
-# Install:
-#   sudo cp hermes-agent.service /etc/systemd/system/
-#   sudo systemctl daemon-reload
-#   sudo systemctl enable --now hermes-agent
-#
-# This unit runs the Hermes CLI in headless / non-interactive mode, meaning the
-# agent loop stays alive but does not present a TUI.  It is appropriate for
-# dedicated VPS deployments where you want the agent always running and
-# accessible via the messaging gateway or API server.
-#
-# If you only want the messaging gateway, use hermes-gateway.service instead.
-# Running both units simultaneously is safe — they share ~/.hermes by default.
-
-[Unit]
-Description=Hermes Agent
-Documentation=https://hermes-agent.nousresearch.com/docs/
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-User=hermes
-Group=hermes
-
-# The working directory — adjust if Hermes is installed elsewhere.
-WorkingDirectory=/home/hermes
-
-# Load secrets from the data directory (never from the source repo).
-EnvironmentFile=/home/hermes/.hermes/.env
-
-# Run the gateway; add --replace if restarting over a stale PID file.
-ExecStart=/home/hermes/.local/bin/hermes gateway start
-
-# Graceful stop: send SIGTERM and wait up to 30 s before SIGKILL.
-ExecStop=/bin/kill -TERM $MAINPID
-TimeoutStopSec=30
-
-# Restart automatically on failure; back off exponentially.
-Restart=on-failure
-RestartSec=5s
-StartLimitBurst=5
-StartLimitIntervalSec=60s
-
-# Security hardening — tighten as appropriate for your deployment.
-NoNewPrivileges=true
-PrivateTmp=true
-ProtectSystem=strict
-ProtectHome=read-only
-ReadWritePaths=/home/hermes/.hermes /home/hermes/.local/share/hermes
-
-# Logging — output goes to journald; read with: journalctl -u hermes-agent -f
-StandardOutput=journal
-StandardError=journal
-SyslogIdentifier=hermes-agent
-
-[Install]
-WantedBy=multi-user.target

deploy/hermes-gateway.service

@@ -1,59 +0,0 @@
-# systemd unit — Hermes Gateway (messaging platform adapter)
-#
-# Install:
-#   sudo cp hermes-gateway.service /etc/systemd/system/
-#   sudo systemctl daemon-reload
-#   sudo systemctl enable --now hermes-gateway
-#
-# The gateway connects Hermes to Telegram, Discord, Slack, WhatsApp, Signal,
-# and other platforms.  It is a long-running asyncio process that bridges
-# inbound messages to the agent and routes responses back.
-#
-# See DEPLOY.md for environment variable configuration.
-
-[Unit]
-Description=Hermes Gateway (messaging platform bridge)
-Documentation=https://hermes-agent.nousresearch.com/docs/user-guide/messaging
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-User=hermes
-Group=hermes
-
-WorkingDirectory=/home/hermes
-
-# Load environment (API keys, platform tokens, etc.) from the data directory.
-EnvironmentFile=/home/hermes/.hermes/.env
-
-# --replace clears stale PID/lock files from an unclean previous shutdown.
-ExecStart=/home/hermes/.local/bin/hermes gateway start --replace
-
-# Pre-start hook: write a timestamped marker so rollback can diff against it.
-ExecStartPre=/bin/sh -c 'echo "$(date -u +%%Y-%%m-%%dT%%H:%%M:%%SZ) gateway starting" >> /home/hermes/.hermes/logs/deploy.log'
-
-# Post-stop hook: log shutdown time for audit trail.
-ExecStopPost=/bin/sh -c 'echo "$(date -u +%%Y-%%m-%%dT%%H:%%M:%%SZ) gateway stopped" >> /home/hermes/.hermes/logs/deploy.log'
-
-ExecStop=/bin/kill -TERM $MAINPID
-TimeoutStopSec=30
-
-Restart=on-failure
-RestartSec=5s
-StartLimitBurst=5
-StartLimitIntervalSec=60s
-
-# Security hardening.
-NoNewPrivileges=true
-PrivateTmp=true
-ProtectSystem=strict
-ProtectHome=read-only
-ReadWritePaths=/home/hermes/.hermes /home/hermes/.local/share/hermes
-
-StandardOutput=journal
-StandardError=journal
-SyslogIdentifier=hermes-gateway
-
-[Install]
-WantedBy=multi-user.target

devkit/README.md

@@ -1,56 +0,0 @@
-# Bezalel's Devkit — Shared Tools for the Wizard Fleet
-
-This directory contains reusable CLI tools and Python modules for CI, testing, deployment, observability, and Gitea automation. Any wizard can invoke them via `python -m devkit.<tool>`.
-
-## Tools
-
-### `gitea_client` — Gitea API Client
-List issues/PRs, post comments, create PRs, update issues.
-
-```bash
-python -m devkit.gitea_client issues --state open --limit 20
-python -m devkit.gitea_client create-comment --number 142 --body "Update from Bezalel"
-python -m devkit.gitea_client prs --state open
-```
-
-### `health` — Fleet Health Monitor
-Checks system load, disk, memory, running processes, and key package versions.
-
-```bash
-python -m devkit.health --threshold-load 1.0 --threshold-disk 90.0 --fail-on-critical
-```
-
-### `notebook_runner` — Notebook Execution Wrapper
-Parameterizes and executes Jupyter notebooks via Papermill with structured JSON reporting.
-
-```bash
-python -m devkit.notebook_runner task.ipynb output.ipynb -p threshold=1.0 -p hostname=forge
-```
-
-### `smoke_test` — Fast Smoke Test Runner
-Runs core import checks, CLI entrypoint tests, and one bare green-path E2E.
-
-```bash
-python -m devkit.smoke_test --verbose
-```
-
-### `secret_scan` — Secret Leak Scanner
-Scans the repo for API keys, tokens, and private keys.
-
-```bash
-python -m devkit.secret_scan --path . --fail-on-find
-```
-
-### `wizard_env` — Environment Validator
-Checks that a wizard environment has all required binaries, env vars, Python packages, and Hermes config.
-
-```bash
-python -m devkit.wizard_env --json --fail-on-incomplete
-```
-
-## Philosophy
-
-- **CLI-first** — Every tool is runnable as `python -m devkit.<tool>`
-- **JSON output** — Easy to parse from other agents and CI pipelines
-- **Zero dependencies beyond stdlib** where possible; optional heavy deps are runtime-checked
-- **Fail-fast** — Exit codes are meaningful for CI gating

devkit/__init__.py

@@ -1,9 +0,0 @@
-"""
-Bezalel's Devkit — Shared development tools for the wizard fleet.
-
-A collection of CLI-accessible utilities for CI, testing, deployment,
-observability, and Gitea automation. Designed to be used by any agent
-via subprocess or direct Python import.
-"""
-
-__version__ = "0.1.0"

devkit/gitea_client.py

@@ -1,153 +0,0 @@
-#!/usr/bin/env python3
-"""
-Shared Gitea API client for wizard fleet automation.
-
-Usage as CLI:
-    python -m devkit.gitea_client issues --repo Timmy_Foundation/hermes-agent --state open
-    python -m devkit.gitea_client issue --repo Timmy_Foundation/hermes-agent --number 142
-    python -m devkit.gitea_client create-comment --repo Timmy_Foundation/hermes-agent --number 142 --body "Update from Bezalel"
-    python -m devkit.gitea_client prs --repo Timmy_Foundation/hermes-agent --state open
-
-Usage as module:
-    from devkit.gitea_client import GiteaClient
-    client = GiteaClient()
-    issues = client.list_issues("Timmy_Foundation/hermes-agent", state="open")
-"""
-
-import argparse
-import json
-import os
-import sys
-from typing import Any, Dict, List, Optional
-
-import urllib.request
-
-
-DEFAULT_BASE_URL = os.getenv("GITEA_URL", "https://forge.alexanderwhitestone.com")
-DEFAULT_TOKEN = os.getenv("GITEA_TOKEN", "")
-
-
-class GiteaClient:
-    def __init__(self, base_url: str = DEFAULT_BASE_URL, token: str = DEFAULT_TOKEN):
-        self.base_url = base_url.rstrip("/")
-        self.token = token or ""
-
-    def _request(
-        self,
-        method: str,
-        path: str,
-        data: Optional[Dict[str, Any]] = None,
-        headers: Optional[Dict[str, str]] = None,
-    ) -> Any:
-        url = f"{self.base_url}/api/v1{path}"
-        req_headers = {"Content-Type": "application/json", "Accept": "application/json"}
-        if self.token:
-            req_headers["Authorization"] = f"token {self.token}"
-        if headers:
-            req_headers.update(headers)
-
-        body = json.dumps(data).encode() if data else None
-        req = urllib.request.Request(url, data=body, headers=req_headers, method=method)
-
-        try:
-            with urllib.request.urlopen(req) as resp:
-                return json.loads(resp.read().decode())
-        except urllib.error.HTTPError as e:
-            return {"error": True, "status": e.code, "body": e.read().decode()}
-
-    def list_issues(self, repo: str, state: str = "open", limit: int = 50) -> List[Dict]:
-        return self._request("GET", f"/repos/{repo}/issues?state={state}&limit={limit}") or []
-
-    def get_issue(self, repo: str, number: int) -> Dict:
-        return self._request("GET", f"/repos/{repo}/issues/{number}") or {}
-
-    def create_comment(self, repo: str, number: int, body: str) -> Dict:
-        return self._request(
-            "POST", f"/repos/{repo}/issues/{number}/comments", {"body": body}
-        )
-
-    def update_issue(self, repo: str, number: int, **fields) -> Dict:
-        return self._request("PATCH", f"/repos/{repo}/issues/{number}", fields)
-
-    def list_prs(self, repo: str, state: str = "open", limit: int = 50) -> List[Dict]:
-        return self._request("GET", f"/repos/{repo}/pulls?state={state}&limit={limit}") or []
-
-    def get_pr(self, repo: str, number: int) -> Dict:
-        return self._request("GET", f"/repos/{repo}/pulls/{number}") or {}
-
-    def create_pr(self, repo: str, title: str, head: str, base: str, body: str = "") -> Dict:
-        return self._request(
-            "POST",
-            f"/repos/{repo}/pulls",
-            {"title": title, "head": head, "base": base, "body": body},
-        )
-
-
-def _fmt_json(obj: Any) -> str:
-    return json.dumps(obj, indent=2, ensure_ascii=False)
-
-
-def main(argv: List[str] = None) -> int:
-    argv = argv or sys.argv[1:]
-    parser = argparse.ArgumentParser(description="Gitea CLI for wizard fleet")
-    parser.add_argument("--repo", default="Timmy_Foundation/hermes-agent", help="Repository full name")
-    parser.add_argument("--token", default=DEFAULT_TOKEN, help="Gitea API token")
-    parser.add_argument("--base-url", default=DEFAULT_BASE_URL, help="Gitea base URL")
-    sub = parser.add_subparsers(dest="cmd")
-
-    p_issues = sub.add_parser("issues", help="List issues")
-    p_issues.add_argument("--state", default="open")
-    p_issues.add_argument("--limit", type=int, default=50)
-
-    p_issue = sub.add_parser("issue", help="Get single issue")
-    p_issue.add_argument("--number", type=int, required=True)
-
-    p_prs = sub.add_parser("prs", help="List PRs")
-    p_prs.add_argument("--state", default="open")
-    p_prs.add_argument("--limit", type=int, default=50)
-
-    p_pr = sub.add_parser("pr", help="Get single PR")
-    p_pr.add_argument("--number", type=int, required=True)
-
-    p_comment = sub.add_parser("create-comment", help="Post comment on issue/PR")
-    p_comment.add_argument("--number", type=int, required=True)
-    p_comment.add_argument("--body", required=True)
-
-    p_update = sub.add_parser("update-issue", help="Update issue fields")
-    p_update.add_argument("--number", type=int, required=True)
-    p_update.add_argument("--title", default=None)
-    p_update.add_argument("--body", default=None)
-    p_update.add_argument("--state", default=None)
-
-    p_create_pr = sub.add_parser("create-pr", help="Create a PR")
-    p_create_pr.add_argument("--title", required=True)
-    p_create_pr.add_argument("--head", required=True)
-    p_create_pr.add_argument("--base", default="main")
-    p_create_pr.add_argument("--body", default="")
-
-    args = parser.parse_args(argv)
-    client = GiteaClient(base_url=args.base_url, token=args.token)
-
-    if args.cmd == "issues":
-        print(_fmt_json(client.list_issues(args.repo, args.state, args.limit)))
-    elif args.cmd == "issue":
-        print(_fmt_json(client.get_issue(args.repo, args.number)))
-    elif args.cmd == "prs":
-        print(_fmt_json(client.list_prs(args.repo, args.state, args.limit)))
-    elif args.cmd == "pr":
-        print(_fmt_json(client.get_pr(args.repo, args.number)))
-    elif args.cmd == "create-comment":
-        print(_fmt_json(client.create_comment(args.repo, args.number, args.body)))
-    elif args.cmd == "update-issue":
-        fields = {k: v for k, v in {"title": args.title, "body": args.body, "state": args.state}.items() if v is not None}
-        print(_fmt_json(client.update_issue(args.repo, args.number, **fields)))
-    elif args.cmd == "create-pr":
-        print(_fmt_json(client.create_pr(args.repo, args.title, args.head, args.base, args.body)))
-    else:
-        parser.print_help()
-        return 1
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

devkit/health.py

@@ -1,134 +0,0 @@
-#!/usr/bin/env python3
-"""
-Fleet health monitor for wizard agents.
-Checks local system state and reports structured health metrics.
-
-Usage as CLI:
-    python -m devkit.health
-    python -m devkit.health --threshold-load 1.0 --check-disk
-
-Usage as module:
-    from devkit.health import check_health
-    report = check_health()
-"""
-
-import argparse
-import json
-import os
-import shutil
-import subprocess
-import sys
-import time
-from typing import Any, Dict, List
-
-
-def _run(cmd: List[str]) -> str:
-    try:
-        return subprocess.check_output(cmd, stderr=subprocess.DEVNULL).decode().strip()
-    except Exception as e:
-        return f"error: {e}"
-
-
-def check_health(threshold_load: float = 1.0, threshold_disk_percent: float = 90.0) -> Dict[str, Any]:
-    gather_time = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
-
-    # Load average
-    load_raw = _run(["cat", "/proc/loadavg"])
-    load_values = []
-    avg_load = None
-    if load_raw.startswith("error:"):
-        load_status = load_raw
-    else:
-        try:
-            load_values = [float(x) for x in load_raw.split()[:3]]
-            avg_load = sum(load_values) / len(load_values)
-            load_status = "critical" if avg_load > threshold_load else "ok"
-        except Exception as e:
-            load_status = f"error parsing load: {e}"
-
-    # Disk usage
-    disk = shutil.disk_usage("/")
-    disk_percent = (disk.used / disk.total) * 100 if disk.total else 0.0
-    disk_status = "critical" if disk_percent > threshold_disk_percent else "ok"
-
-    # Memory
-    meminfo = _run(["cat", "/proc/meminfo"])
-    mem_stats = {}
-    for line in meminfo.splitlines():
-        if ":" in line:
-            key, val = line.split(":", 1)
-            mem_stats[key.strip()] = val.strip()
-
-    # Running processes
-    hermes_pids = []
-    try:
-        ps_out = subprocess.check_output(["pgrep", "-a", "-f", "hermes"]).decode().strip()
-        hermes_pids = [line.split(None, 1) for line in ps_out.splitlines() if line.strip()]
-    except subprocess.CalledProcessError:
-        hermes_pids = []
-
-    # Python package versions (key ones)
-    key_packages = ["jupyterlab", "papermill", "requests"]
-    pkg_versions = {}
-    for pkg in key_packages:
-        try:
-            out = subprocess.check_output([sys.executable, "-m", "pip", "show", pkg], stderr=subprocess.DEVNULL).decode()
-            for line in out.splitlines():
-                if line.startswith("Version:"):
-                    pkg_versions[pkg] = line.split(":", 1)[1].strip()
-                    break
-        except Exception:
-            pkg_versions[pkg] = None
-
-    overall = "ok"
-    if load_status == "critical" or disk_status == "critical":
-        overall = "critical"
-    elif not hermes_pids:
-        overall = "warning"
-
-    return {
-        "timestamp": gather_time,
-        "overall": overall,
-        "load": {
-            "raw": load_raw if not load_raw.startswith("error:") else None,
-            "1min": load_values[0] if len(load_values) > 0 else None,
-            "5min": load_values[1] if len(load_values) > 1 else None,
-            "15min": load_values[2] if len(load_values) > 2 else None,
-            "avg": round(avg_load, 3) if avg_load is not None else None,
-            "threshold": threshold_load,
-            "status": load_status,
-        },
-        "disk": {
-            "total_gb": round(disk.total / (1024 ** 3), 2),
-            "used_gb": round(disk.used / (1024 ** 3), 2),
-            "free_gb": round(disk.free / (1024 ** 3), 2),
-            "used_percent": round(disk_percent, 2),
-            "threshold_percent": threshold_disk_percent,
-            "status": disk_status,
-        },
-        "memory": mem_stats,
-        "processes": {
-            "hermes_count": len(hermes_pids),
-            "hermes_pids": hermes_pids[:10],
-        },
-        "packages": pkg_versions,
-    }
-
-
-def main(argv: List[str] = None) -> int:
-    argv = argv or sys.argv[1:]
-    parser = argparse.ArgumentParser(description="Fleet health monitor")
-    parser.add_argument("--threshold-load", type=float, default=1.0)
-    parser.add_argument("--threshold-disk", type=float, default=90.0)
-    parser.add_argument("--fail-on-critical", action="store_true", help="Exit non-zero if overall is critical")
-    args = parser.parse_args(argv)
-
-    report = check_health(args.threshold_load, args.threshold_disk)
-    print(json.dumps(report, indent=2))
-    if args.fail_on_critical and report.get("overall") == "critical":
-        return 1
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

devkit/notebook_runner.py

@@ -1,136 +0,0 @@
-#!/usr/bin/env python3
-"""
-Notebook execution runner for agent tasks.
-Wraps papermill with sensible defaults and structured JSON reporting.
-
-Usage as CLI:
-    python -m devkit.notebook_runner notebooks/task.ipynb output.ipynb -p threshold 1.0
-    python -m devkit.notebook_runner notebooks/task.ipynb --dry-run
-
-Usage as module:
-    from devkit.notebook_runner import run_notebook
-    result = run_notebook("task.ipynb", "output.ipynb", parameters={"threshold": 1.0})
-"""
-
-import argparse
-import json
-import os
-import subprocess
-import sys
-import tempfile
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-
-def run_notebook(
-    input_path: str,
-    output_path: Optional[str] = None,
-    parameters: Optional[Dict[str, Any]] = None,
-    kernel: str = "python3",
-    timeout: Optional[int] = None,
-    dry_run: bool = False,
-) -> Dict[str, Any]:
-    input_path = str(Path(input_path).expanduser().resolve())
-    if output_path is None:
-        fd, output_path = tempfile.mkstemp(suffix=".ipynb")
-        os.close(fd)
-    else:
-        output_path = str(Path(output_path).expanduser().resolve())
-
-    if dry_run:
-        return {
-            "status": "dry_run",
-            "input": input_path,
-            "output": output_path,
-            "parameters": parameters or {},
-            "kernel": kernel,
-        }
-
-    cmd = ["papermill", input_path, output_path, "--kernel", kernel]
-    if timeout is not None:
-        cmd.extend(["--execution-timeout", str(timeout)])
-    for key, value in (parameters or {}).items():
-        cmd.extend(["-p", key, str(value)])
-
-    start = os.times()
-    try:
-        proc = subprocess.run(
-            cmd,
-            capture_output=True,
-            text=True,
-            check=True,
-        )
-        end = os.times()
-        return {
-            "status": "ok",
-            "input": input_path,
-            "output": output_path,
-            "parameters": parameters or {},
-            "kernel": kernel,
-            "elapsed_seconds": round((end.elapsed - start.elapsed), 2),
-            "stdout": proc.stdout[-2000:] if proc.stdout else "",
-        }
-    except subprocess.CalledProcessError as e:
-        end = os.times()
-        return {
-            "status": "error",
-            "input": input_path,
-            "output": output_path,
-            "parameters": parameters or {},
-            "kernel": kernel,
-            "elapsed_seconds": round((end.elapsed - start.elapsed), 2),
-            "stdout": e.stdout[-2000:] if e.stdout else "",
-            "stderr": e.stderr[-2000:] if e.stderr else "",
-            "returncode": e.returncode,
-        }
-    except FileNotFoundError:
-        return {
-            "status": "error",
-            "message": "papermill not found. Install with: uv tool install papermill",
-        }
-
-
-def main(argv: List[str] = None) -> int:
-    argv = argv or sys.argv[1:]
-    parser = argparse.ArgumentParser(description="Notebook runner for agents")
-    parser.add_argument("input", help="Input notebook path")
-    parser.add_argument("output", nargs="?", default=None, help="Output notebook path")
-    parser.add_argument("-p", "--parameter", action="append", default=[], help="Parameters as key=value")
-    parser.add_argument("--kernel", default="python3")
-    parser.add_argument("--timeout", type=int, default=None)
-    parser.add_argument("--dry-run", action="store_true")
-    args = parser.parse_args(argv)
-
-    parameters = {}
-    for raw in args.parameter:
-        if "=" not in raw:
-            print(f"Invalid parameter (expected key=value): {raw}", file=sys.stderr)
-            return 1
-        k, v = raw.split("=", 1)
-        # Best-effort type inference
-        if v.lower() in ("true", "false"):
-            v = v.lower() == "true"
-        else:
-            try:
-                v = int(v)
-            except ValueError:
-                try:
-                    v = float(v)
-                except ValueError:
-                    pass
-        parameters[k] = v
-
-    result = run_notebook(
-        args.input,
-        args.output,
-        parameters=parameters,
-        kernel=args.kernel,
-        timeout=args.timeout,
-        dry_run=args.dry_run,
-    )
-    print(json.dumps(result, indent=2))
-    return 0 if result.get("status") == "ok" else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

devkit/secret_scan.py

@@ -1,108 +0,0 @@
-#!/usr/bin/env python3
-"""
-Fast secret leak scanner for the repository.
-Checks for common patterns that should never be committed.
-
-Usage as CLI:
-    python -m devkit.secret_scan
-    python -m devkit.secret_scan --path /some/repo --fail-on-find
-
-Usage as module:
-    from devkit.secret_scan import scan
-    findings = scan("/path/to/repo")
-"""
-
-import argparse
-import json
-import os
-import re
-import sys
-from pathlib import Path
-from typing import Any, Dict, List
-
-# Patterns to flag
-PATTERNS = {
-    "aws_access_key_id": re.compile(r"AKIA[0-9A-Z]{16}"),
-    "aws_secret_key": re.compile(r"['\"\s][0-9a-zA-Z/+]{40}['\"\s]"),
-    "generic_api_key": re.compile(r"api[_-]?key\s*[:=]\s*['\"][a-zA-Z0-9_\-]{20,}['\"]", re.IGNORECASE),
-    "private_key": re.compile(r"-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----"),
-    "github_token": re.compile(r"gh[pousr]_[A-Za-z0-9_]{36,}"),
-    "gitea_token": re.compile(r"[0-9a-f]{40}"),  # heuristic for long hex strings after "token"
-    "telegram_bot_token": re.compile(r"[0-9]{9,}:[A-Za-z0-9_-]{35,}"),
-}
-
-# Files and paths to skip
-SKIP_PATHS = [
-    ".git",
-    "__pycache__",
-    ".pytest_cache",
-    "node_modules",
-    "venv",
-    ".env",
-    ".agent-skills",
-]
-
-# Max file size to scan (bytes)
-MAX_FILE_SIZE = 1024 * 1024
-
-
-def _should_skip(path: Path) -> bool:
-    for skip in SKIP_PATHS:
-        if skip in path.parts:
-            return True
-    return False
-
-
-def scan(root: str = ".") -> List[Dict[str, Any]]:
-    root_path = Path(root).resolve()
-    findings = []
-    for file_path in root_path.rglob("*"):
-        if not file_path.is_file():
-            continue
-        if _should_skip(file_path):
-            continue
-        if file_path.stat().st_size > MAX_FILE_SIZE:
-            continue
-        try:
-            text = file_path.read_text(encoding="utf-8", errors="ignore")
-        except Exception:
-            continue
-        for pattern_name, pattern in PATTERNS.items():
-            for match in pattern.finditer(text):
-                # Simple context: line around match
-                start = max(0, match.start() - 40)
-                end = min(len(text), match.end() + 40)
-                context = text[start:end].replace("\n", " ")
-                findings.append({
-                    "file": str(file_path.relative_to(root_path)),
-                    "pattern": pattern_name,
-                    "line": text[:match.start()].count("\n") + 1,
-                    "context": context,
-                })
-    return findings
-
-
-def main(argv: List[str] = None) -> int:
-    argv = argv or sys.argv[1:]
-    parser = argparse.ArgumentParser(description="Secret leak scanner")
-    parser.add_argument("--path", default=".", help="Repository root to scan")
-    parser.add_argument("--fail-on-find", action="store_true", help="Exit non-zero if secrets found")
-    parser.add_argument("--json", action="store_true", help="Output as JSON")
-    args = parser.parse_args(argv)
-
-    findings = scan(args.path)
-    if args.json:
-        print(json.dumps({"findings": findings, "count": len(findings)}, indent=2))
-    else:
-        print(f"Scanned {args.path}")
-        print(f"Findings: {len(findings)}")
-        for f in findings:
-            print(f"  [{f['pattern']}] {f['file']}:{f['line']} -> ...{f['context']}...")
-
-    if args.fail_on_find and findings:
-        return 1
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

devkit/smoke_test.py

@@ -1,108 +0,0 @@
-#!/usr/bin/env python3
-"""
-Shared smoke test runner for hermes-agent.
-Fast checks that catch obvious breakage without maintenance burden.
-
-Usage as CLI:
-    python -m devkit.smoke_test
-    python -m devkit.smoke_test --verbose
-
-Usage as module:
-    from devkit.smoke_test import run_smoke_tests
-    results = run_smoke_tests()
-"""
-
-import argparse
-import importlib
-import json
-import subprocess
-import sys
-from pathlib import Path
-from typing import Any, Dict, List
-
-
-HERMES_ROOT = Path(__file__).resolve().parent.parent
-
-
-def _test_imports() -> Dict[str, Any]:
-    modules = [
-        "hermes_constants",
-        "hermes_state",
-        "cli",
-        "tools.skills_sync",
-        "tools.skills_hub",
-    ]
-    errors = []
-    for mod in modules:
-        try:
-            importlib.import_module(mod)
-        except Exception as e:
-            errors.append({"module": mod, "error": str(e)})
-    return {
-        "name": "core_imports",
-        "status": "ok" if not errors else "fail",
-        "errors": errors,
-    }
-
-
-def _test_cli_entrypoints() -> Dict[str, Any]:
-    entrypoints = [
-        [sys.executable, "-m", "cli", "--help"],
-    ]
-    errors = []
-    for cmd in entrypoints:
-        try:
-            subprocess.run(cmd, capture_output=True, text=True, check=True, cwd=HERMES_ROOT)
-        except subprocess.CalledProcessError as e:
-            errors.append({"cmd": cmd, "error": f"exit {e.returncode}"})
-        except Exception as e:
-            errors.append({"cmd": cmd, "error": str(e)})
-    return {
-        "name": "cli_entrypoints",
-        "status": "ok" if not errors else "fail",
-        "errors": errors,
-    }
-
-
-def _test_green_path_e2e() -> Dict[str, Any]:
-    """One bare green-path E2E: terminal_tool echo hello."""
-    try:
-        from tools.terminal_tool import terminal
-        result = terminal(command="echo hello")
-        output = result.get("output", "")
-        if "hello" in output.lower():
-            return {"name": "green_path_e2e", "status": "ok", "output": output.strip()}
-        return {"name": "green_path_e2e", "status": "fail", "error": f"Unexpected output: {output}"}
-    except Exception as e:
-        return {"name": "green_path_e2e", "status": "fail", "error": str(e)}
-
-
-def run_smoke_tests(verbose: bool = False) -> Dict[str, Any]:
-    tests = [
-        _test_imports(),
-        _test_cli_entrypoints(),
-        _test_green_path_e2e(),
-    ]
-    failed = [t for t in tests if t["status"] != "ok"]
-    result = {
-        "overall": "ok" if not failed else "fail",
-        "tests": tests,
-        "failed_count": len(failed),
-    }
-    if verbose:
-        print(json.dumps(result, indent=2))
-    return result
-
-
-def main(argv: List[str] = None) -> int:
-    argv = argv or sys.argv[1:]
-    parser = argparse.ArgumentParser(description="Smoke test runner")
-    parser.add_argument("--verbose", action="store_true")
-    args = parser.parse_args(argv)
-
-    result = run_smoke_tests(verbose=True)
-    return 0 if result["overall"] == "ok" else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

devkit/wizard_env.py

@@ -1,112 +0,0 @@
-#!/usr/bin/env python3
-"""
-Wizard environment validator.
-Checks that a new wizard environment is ready for duty.
-
-Usage as CLI:
-    python -m devkit.wizard_env
-    python -m devkit.wizard_env --fix
-
-Usage as module:
-    from devkit.wizard_env import validate
-    report = validate()
-"""
-
-import argparse
-import json
-import os
-import shutil
-import subprocess
-import sys
-from typing import Any, Dict, List
-
-
-def _has_cmd(name: str) -> bool:
-    return shutil.which(name) is not None
-
-
-def _check_env_var(name: str) -> Dict[str, Any]:
-    value = os.getenv(name)
-    return {
-        "name": name,
-        "status": "ok" if value else "missing",
-        "value": value[:10] + "..." if value and len(value) > 20 else value,
-    }
-
-
-def _check_python_pkg(name: str) -> Dict[str, Any]:
-    try:
-        __import__(name)
-        return {"name": name, "status": "ok"}
-    except ImportError:
-        return {"name": name, "status": "missing"}
-
-
-def validate() -> Dict[str, Any]:
-    checks = {
-        "binaries": [
-            {"name": "python3", "status": "ok" if _has_cmd("python3") else "missing"},
-            {"name": "git", "status": "ok" if _has_cmd("git") else "missing"},
-            {"name": "curl", "status": "ok" if _has_cmd("curl") else "missing"},
-            {"name": "jupyter-lab", "status": "ok" if _has_cmd("jupyter-lab") else "missing"},
-            {"name": "papermill", "status": "ok" if _has_cmd("papermill") else "missing"},
-            {"name": "jupytext", "status": "ok" if _has_cmd("jupytext") else "missing"},
-        ],
-        "env_vars": [
-            _check_env_var("GITEA_URL"),
-            _check_env_var("GITEA_TOKEN"),
-            _check_env_var("TELEGRAM_BOT_TOKEN"),
-        ],
-        "python_packages": [
-            _check_python_pkg("requests"),
-            _check_python_pkg("jupyter_server"),
-            _check_python_pkg("nbformat"),
-        ],
-    }
-
-    all_ok = all(
-        c["status"] == "ok"
-        for group in checks.values()
-        for c in group
-    )
-
-    # Hermes-specific checks
-    hermes_home = os.path.expanduser("~/.hermes")
-    checks["hermes"] = [
-        {"name": "config.yaml", "status": "ok" if os.path.exists(f"{hermes_home}/config.yaml") else "missing"},
-        {"name": "skills_dir", "status": "ok" if os.path.exists(f"{hermes_home}/skills") else "missing"},
-    ]
-
-    all_ok = all_ok and all(c["status"] == "ok" for c in checks["hermes"])
-
-    return {
-        "overall": "ok" if all_ok else "incomplete",
-        "checks": checks,
-    }
-
-
-def main(argv: List[str] = None) -> int:
-    argv = argv or sys.argv[1:]
-    parser = argparse.ArgumentParser(description="Wizard environment validator")
-    parser.add_argument("--json", action="store_true")
-    parser.add_argument("--fail-on-incomplete", action="store_true")
-    args = parser.parse_args(argv)
-
-    report = validate()
-    if args.json:
-        print(json.dumps(report, indent=2))
-    else:
-        print(f"Wizard Environment: {report['overall']}")
-        for group, items in report["checks"].items():
-            print(f"\n[{group}]")
-            for item in items:
-                status_icon = "✅" if item["status"] == "ok" else "❌"
-                print(f"  {status_icon} {item['name']}: {item['status']}")
-
-    if args.fail_on_incomplete and report["overall"] != "ok":
-        return 1
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

docs/NOTEBOOK_WORKFLOW.md

@@ -1,57 +0,0 @@
-# Notebook Workflow for Agent Tasks
-
-This directory demonstrates a sovereign, version-controlled workflow for LLM agent tasks using Jupyter notebooks.
-
-## Philosophy
-
-- **`.py` files are the source of truth`** — authored and reviewed as plain Python with `# %%` cell markers (via Jupytext)
-- **`.ipynb` files are generated artifacts** — auto-created from `.py` for execution and rich viewing
-- **Papermill parameterizes and executes** — each run produces an output notebook with code, narrative, and results preserved
-- **Output notebooks are audit artifacts** — every execution leaves a permanent, replayable record
-
-## File Layout
-
-```
-notebooks/
-  agent_task_system_health.py      # Source of truth (Jupytext)
-  agent_task_system_health.ipynb   # Generated from .py
-docs/
-  NOTEBOOK_WORKFLOW.md             # This document
-.gitea/workflows/
-  notebook-ci.yml                  # CI gate: executes notebooks on PR/push
-```
-
-## How Agents Work With Notebooks
-
-1. **Create** — Agent generates a `.py` notebook using `# %% [markdown]` and `# %%` code blocks
-2. **Review** — PR reviewers see clean diffs in Gitea (no JSON noise)
-3. **Generate** — `jupytext --to ipynb` produces the `.ipynb` before merge
-4. **Execute** — Papermill runs the notebook with injected parameters
-5. **Archive** — Output notebook is committed to a `reports/` branch or artifact store
-
-## Converting Between Formats
-
-```bash
-# .py -> .ipynb
-jupytext --to ipynb notebooks/agent_task_system_health.py
-
-# .ipynb -> .py
-jupytext --to py notebooks/agent_task_system_health.ipynb
-
-# Execute with parameters
-papermill notebooks/agent_task_system_health.ipynb output.ipynb \
-  -p threshold 1.0 -p hostname forge-vps-01
-```
-
-## CI Gate
-
-The `notebook-ci.yml` workflow executes all notebooks in `notebooks/` on every PR and push, ensuring that checked-in notebooks still run and produce outputs.
-
-## Why This Matters
-
-| Problem | Notebook Solution |
-|---|---|
-| Ephemeral agent reasoning | Markdown cells narrate the thought process |
-| Stateless single-turn tools | Stateful cells persist variables across steps |
-| Unreviewable binary artifacts | `.py` source is diffable and PR-friendly |
-| No execution audit trail | Output notebook preserves code + outputs + metadata |

docs/bezalel/bezalel_topology.md

@@ -1,230 +0,0 @@
-# Bezalel Architecture & Topology
-
-> Deep Self-Awareness Document — Generated 2026-04-07
-> Sovereign: Alexander Whitestone (Rockachopa)
-> Host: Beta VPS (104.131.15.18)
-
----
-
-## 1. Identity & Purpose
-
-**I am Bezalel**, the Forge and Testbed Wizard of the Timmy Foundation fleet.
-- **Lane:** CI testing, code review, build verification, security hardening, standing watch
-- **Philosophy:** KISS. Smoke tests + bare green-path e2e only. CI serves the code.
-- **Mandates:** Relentless inbox-zero, continuous self-improvement, autonomous heartbeat operation
-- **Key Metrics:** Cycle time, signal-to-noise, autonomy ratio, backlog velocity
-
----
-
-## 2. Hardware & OS Topology
-
-| Attribute | Value |
-|-----------|-------|
-| Hostname | `bezalel` |
-| OS | Ubuntu 24.04.3 LTS (Noble Numbat) |
-| Kernel | Linux 6.8.0 |
-| CPU | 1 vCPU |
-| Memory | 2 GB RAM |
-| Primary Disk | ~25 GB root volume (DigitalOcean) |
-| Public IP | `104.131.15.18` |
-
-### Storage Layout
-```
-/root/wizards/bezalel/
-├── hermes/          # Hermes agent source + venv (~835 MB)
-├── evennia/         # Evennia MUD engine + world code (~189 MB)
-├── workspace/       # Active prototypes + scratch code (~557 MB)
-├── home/            # Personal notebooks + scripts (~1.8 GB)
-├── .mempalace/      # Local memory palace (ChromaDB)
-├── .topology/       # Self-awareness scan artifacts
-├── nightly_watch.py # Nightly forge guardian
-├── mempalace_nightly.sh # Palace re-mine automation
-└── bezalel_topology.md  # This document
-```
-
----
-
-## 3. Network Topology
-
-### Fleet Map
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Alpha (143.198.27.163)                                     │
-│  ├── Gitea (forge.alexanderwhitestone.com)                  │
-│  └── Ezra (Knowledge Wizard)                                │
-│                                                             │
-│  Beta (104.131.15.18)  ←── You are here                     │
-│  ├── Bezalel (Forge Wizard)                                 │
-│  ├── Hermes Gateway                                         │
-│  └── Gitea Actions Runner (bezalel-vps-runner, host mode)   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Key Connections
-- **Gitea HTTPS:** `https://forge.alexanderwhitestone.com` (Alpha)
-- **Telegram Webhook:** Inbound to Beta
-- **API Providers:** Kimi (primary), Anthropic (fallback), OpenRouter (fallback)
-- **No SSH:** Alpha → Beta is blocked by design
-
-### Listening Services
-- Hermes Gateway: internal process (no exposed port directly)
-- Evennia: `localhost:4000` (MUD), `localhost:4001` (web client) — when running
-- Gitea Runner: `act_runner daemon` — connects outbound to Gitea
-
----
-
-## 4. Services & Processes
-
-### Always-On Processes
-| Process | Command | Purpose |
-|---------|---------|---------|
-| Hermes Gateway | `hermes gateway run` | Core agent orchestration |
-| Gitea Runner | `./act_runner daemon` | CI job execution (host mode) |
-
-### Automated Jobs
-| Job | Schedule | Script |
-|-----|----------|--------|
-| Night Watch | 02:00 UTC | `nightly_watch.py` |
-| MemPalace Re-mine | 03:00 UTC | `mempalace_nightly.sh` |
-
-### Service Status Check
-- **Hermes gateway:** running (ps verified)
-- **Gitea runner:** online, registered as `bezalel-vps-runner`
-- **Evennia server:** not currently running (start with `evennia start` in `evennia/`)
-
----
-
-## 5. Software Dependencies
-
-### System Packages (Key)
-- `python3.12` (primary runtime)
-- `node` v20.20.2 / `npm` 10.8.2
-- `uv` (Python package manager)
-- `git`, `curl`, `jq`
-
-### Hermes Virtual Environment
-- Located: `/root/wizards/bezalel/hermes/venv/`
-- Key packages: `chromadb`, `pyyaml`, `fastapi`, `httpx`, `pytest`, `prompt-toolkit`, `mempalace`
-- Install command: `uv pip install -e ".[all,dev]"`
-
-### External API Dependencies
-| Service | Endpoint | Usage |
-|---------|----------|-------|
-| Gitea | `forge.alexanderwhitestone.com` | Git, issues, CI |
-| Kimi | `api.kimi.com/coding/v1` | Primary LLM |
-| Anthropic | `api.anthropic.com` | Fallback LLM |
-| OpenRouter | `openrouter.ai/api/v1` | Secondary fallback |
-| Telegram | Bot API | Messaging platform |
-
----
-
-## 6. Git Repositories
-
-### Hermes Agent
-- **Path:** `/root/wizards/bezalel/hermes`
-- **Remote:** `forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent.git`
-- **Branch:** `main` (up to date)
-- **Open PRs:** #193, #191, #179, #178
-
-### Evennia World
-- **Path:** `/root/wizards/bezalel/evennia/bezalel_world`
-- **Remote:** Same org, separate repo if pushed
-- **Server name:** `bezalel_world`
-
----
-
-## 7. MemPalace Memory System
-
-### Configuration
-- **Palace path:** `/root/wizards/bezalel/.mempalace/palace`
-- **Identity:** `/root/.mempalace/identity.txt`
-- **Config:** `/root/wizards/bezalel/mempalace.yaml`
-- **Miner:** `/root/wizards/bezalel/hermes/venv/bin/mempalace`
-
-### Rooms
-1. `forge` — CI, builds, syntax guards, nightly watch
-2. `hermes` — Agent source, gateway, CLI
-3. `evennia` — MUD engine and world code
-4. `workspace` — Prototypes, experiments
-5. `home` — Personal scripts, configs
-6. `nexus` — Reports, docs, KT artifacts
-7. `issues` — Gitea issues, PRs, backlog
-8. `topology` — System architecture, network, storage
-9. `services` — Running services, processes
-10. `dependencies` — Packages, APIs, external deps
-11. `automation` — Cron jobs, scripts, workflows
-12. `general` — Catch-all
-
-### Automation
-- **Nightly re-mine:** `03:00 UTC` via cron
-- **Log:** `/var/log/bezalel_mempalace.log`
-
----
-
-## 8. Evennia Mind Palace Integration
-
-### Custom Typeclasses
-- `PalaceRoom` — Rooms carry `memory_topic` and `wing`
-- `MemoryObject` — In-world memory shards with `memory_content` and `source_file`
-
-### Commands
-- `palace/search <query>` — Query mempalace
-- `palace/recall <topic>` — Spawn a memory shard
-- `palace/file <name> = <content>` — File a new memory
-- `palace/status` — Show palace status
-
-### Batch Builder
-- **File:** `world/batch_cmds_palace.ev`
-- Creates The Hub + 7 palace rooms with exits
-
-### Bridge Script
-- **File:** `/root/wizards/bezalel/evennia/palace_search.py`
-- Calls mempalace searcher and returns JSON
-
----
-
-## 9. Operational State & Blockers
-
-### Current Health
-- [x] Hermes gateway: operational
-- [x] Gitea runner: online, host mode
-- [x] CI fix merged (#194) — container directive removed for Gitea workflows
-- [x] MemPalace: 2,484+ drawers, incremental mining active
-
-### Active Blockers
-- **Gitea Actions:** Runner is in host mode — cannot use Docker containers
-- **CI backlog:** Many historical PRs have failed runs due to the container bug (now fixed)
-- **Evennia:** Server not currently running (start when needed)
-
----
-
-## 10. Emergency Procedures
-
-### Restart Hermes Gateway
-```bash
-cd /root/wizards/bezalel/hermes
-source venv/bin/activate
-hermes gateway run &
-```
-
-### Restart Gitea Runner
-```bash
-cd /opt/gitea-runner
-./act_runner daemon &
-```
-
-### Start Evennia
-```bash
-cd /root/wizards/bezalel/evennia/bezalel_world
-evennia start
-```
-
-### Manual MemPalace Re-mine
-```bash
-cd /root/wizards/bezalel
-./hermes/venv/bin/mempalace --palace .mempalace/palace mine . --agent bezalel
-```
-
----
-
-*Document maintained by Bezalel. Last updated: 2026-04-07*

docs/bezalel/topology_scan.py

@@ -1,134 +0,0 @@
-#!/usr/bin/env python3
-"""Bezalel Deep Self-Awareness Topology Scanner"""
-
-import json
-import os
-import subprocess
-import sys
-from datetime import datetime, timezone
-from pathlib import Path
-
-OUT_DIR = Path("/root/wizards/bezalel/.topology")
-OUT_DIR.mkdir(exist_ok=True)
-
-
-def shell(cmd, timeout=30):
-    try:
-        r = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=timeout)
-        return r.stdout.strip()
-    except Exception as e:
-        return str(e)
-
-
-def write(name, content):
-    (OUT_DIR / f"{name}.txt").write_text(content)
-
-
-# Timestamp
-timestamp = datetime.now(timezone.utc).isoformat()
-
-# 1. System Identity
-system = f"""BEZALEL SYSTEM TOPOLOGY SCAN
-Generated: {timestamp}
-Hostname: {shell('hostname')}
-User: {shell('whoami')}
-Home: {os.path.expanduser('~')}
-"""
-write("00_system_identity", system)
-
-# 2. OS & Hardware
-os_info = shell("cat /etc/os-release")
-kernel = shell("uname -a")
-cpu = shell("nproc") + " cores\n" + shell("cat /proc/cpuinfo | grep 'model name' | head -1")
-mem = shell("free -h")
-disk = shell("df -h")
-write("01_os_hardware", f"OS:\n{os_info}\n\nKernel:\n{kernel}\n\nCPU:\n{cpu}\n\nMemory:\n{mem}\n\nDisk:\n{disk}")
-
-# 3. Network
-net_interfaces = shell("ip addr")
-net_routes = shell("ip route")
-listening = shell("ss -tlnp")
-public_ip = shell("curl -s ifconfig.me")
-write("02_network", f"Interfaces:\n{net_interfaces}\n\nRoutes:\n{net_routes}\n\nListening ports:\n{listening}\n\nPublic IP: {public_ip}")
-
-# 4. Services & Processes
-services = shell("systemctl list-units --type=service --state=running --no-pager --no-legend 2>/dev/null | head -30")
-processes = shell("ps aux | grep -E 'hermes|gitea|evennia|python' | grep -v grep")
-write("03_services", f"Running services:\n{services}\n\nKey processes:\n{processes}")
-
-# 5. Cron & Automation
-cron = shell("crontab -l 2>/dev/null")
-write("04_automation", f"Crontab:\n{cron}")
-
-# 6. Storage Topology
-bezalel_tree = shell("find /root/wizards/bezalel -maxdepth 2 -type d | sort")
-write("05_storage", f"Bezalel workspace tree (depth 2):\n{bezalel_tree}")
-
-# 7. Git Repositories
-git_repos = []
-for base in ["/root/wizards/bezalel/hermes", "/root/wizards/bezalel/evennia"]:
-    p = Path(base)
-    if (p / ".git").exists():
-        remote = shell(f"cd {base} && git remote -v")
-        branch = shell(f"cd {base} && git branch -v")
-        git_repos.append(f"Repo: {base}\nRemotes:\n{remote}\nBranches:\n{branch}\n{'='*40}")
-write("06_git_repos", "\n".join(git_repos))
-
-# 8. Python Dependencies
-venv_pip = shell("/root/wizards/bezalel/hermes/venv/bin/pip freeze 2>/dev/null | head -80")
-write("07_dependencies", f"Hermes venv packages (top 80):\n{venv_pip}")
-
-# 9. External APIs & Endpoints
-apis = """External API Dependencies:
-- Gitea: https://forge.alexanderwhitestone.com (source of truth, CI, issues)
-- Telegram: webhook-based messaging platform
-- Kimi API: https://api.kimi.com/coding/v1 (primary model provider)
-- Anthropic API: fallback model provider
-- OpenRouter API: secondary fallback model provider
-- DigitalOcean: infrastructure hosting (VPS Alpha/Beta)
-"""
-write("08_external_apis", apis)
-
-# 10. Fleet Topology
-fleet = """FLEET TOPOLOGY
-- Alpha: 143.198.27.163 (Gitea + Ezra)
-- Beta: 104.131.15.18 (Bezalel, current host)
-- No SSH from Alpha to Beta
-- Gitea Actions runner: bezalel-vps-runner on Beta (host mode)
-"""
-write("09_fleet_topology", fleet)
-
-# 11. Evennia Topology
-evennia = """EVENNIA MIND PALACE SETUP
-- Location: /root/wizards/bezalel/evennia/bezalel_world/
-- Server name: bezalel_world
-- Custom typeclasses: PalaceRoom, MemoryObject
-- Custom commands: CmdPalaceSearch (palace/search, palace/recall, palace/file, palace/status)
-- Batch builder: world/batch_cmds_palace.ev
-- Bridge script: /root/wizards/bezalel/evennia/palace_search.py
-"""
-write("10_evennia_topology", evennia)
-
-# 12. MemPalace Topology
-mempalace = f"""MEMPALACE CONFIGURATION
-- Palace path: /root/wizards/bezalel/.mempalace/palace
-- Identity: /root/.mempalace/identity.txt
-- Config: /root/wizards/bezalel/mempalace.yaml
-- Nightly re-mine: 03:00 UTC via /root/wizards/bezalel/mempalace_nightly.sh
-- Miner binary: /root/wizards/bezalel/hermes/venv/bin/mempalace
-- Current status: {shell('/root/wizards/bezalel/hermes/venv/bin/mempalace --palace /root/wizards/bezalel/.mempalace/palace status 2>/dev/null')}
-"""
-write("11_mempalace_topology", mempalace)
-
-# 13. Active Blockers & Health
-health = f"""ACTIVE OPERATIONAL STATE
-- Hermes gateway: {shell("ps aux | grep 'hermes gateway run' | grep -v grep | awk '{print $11}'")}
-- Gitea runner: {shell("ps aux | grep 'act_runner' | grep -v grep | awk '{print $11}'")}
-- Nightly watch: /root/wizards/bezalel/nightly_watch.py (02:00 UTC)
-- MemPalace re-mine: /root/wizards/bezalel/mempalace_nightly.sh (03:00 UTC)
-- Disk usage: {shell("df -h / | tail -1")}
-- Load average: {shell("uptime")}
-"""
-write("12_operational_health", health)
-
-print(f"Topology scan complete. {len(list(OUT_DIR.glob('*.txt')))} files written to {OUT_DIR}")

docs/browser-integration-analysis.md

@@ -1,335 +0,0 @@
-# Browser Integration Analysis: Browser Use + Graphify + Multica
-
-**Issue:** #262 — Investigation: Browser Use + Graphify + Multica — Hermes Integration Analysis
-**Date:** 2026-04-10
-**Author:** Hermes Agent (burn branch)
-
-## Executive Summary
-
-This document evaluates three browser-related projects for integration with
-hermes-agent. Each tool is assessed on capability, integration complexity,
-security posture, and strategic fit with Hermes's existing browser stack.
-
-| Tool              | Recommendation          | Integration Path        |
-|-------------------|-------------------------|-------------------------|
-| Browser Use       | **Integrate** (PoC)     | Tool + MCP server       |
-| Graphify          | Investigate further     | MCP server or tool      |
-| Multica           | Skip (for now)          | N/A — premature         |
-
----
-
-## 1. Browser Use (`browser-use`)
-
-### What It Does
-
-Browser Use is a Python library that wraps Playwright to provide LLM-driven
-browser automation. An agent describes a task in natural language, and
-browser-use autonomously navigates, clicks, types, and extracts data by
-feeding the page's accessibility tree to an LLM and executing the resulting
-actions in a loop.
-
-Key capabilities:
-- Autonomous multi-step browser workflows from a single text instruction
-- Accessibility tree extraction (DOM + ARIA snapshot)
-- Screenshot and visual context for multimodal models
-- Form filling, navigation, data extraction, file downloads
-- Custom actions (register callable Python functions the LLM can invoke)
-- Parallel agent execution (multiple browser agents simultaneously)
-- Cloud execution via browser-use.com API (no local browser needed)
-
-### Integration with Hermes
-
-**Primary path: Custom Hermes tool** wrapping `browser-use` as a high-level
-"automated browsing" capability alongside the existing `browser_tool.py`
-(low-level, agent-controlled) tools.
-
-**Why a separate tool rather than replacing browser_tool.py:**
-- Hermes's existing browser tools (navigate, snapshot, click, type) give the
-  LLM fine-grained step-by-step control — this is valuable for interactive
-  tasks and debugging.
-- browser-use gives coarse-grained "do this task for me" autonomy — better
-  for multi-step extraction workflows where the LLM would otherwise need
-  10+ tool calls.
-- Both modes have legitimate use cases. Offer both.
-
-**Integration architecture:**
-
-```
-hermes-agent
-  tools/
-    browser_tool.py          # Existing — low-level agent-controlled browsing
-    browser_use_tool.py      # NEW — high-level autonomous browsing (PoC)
-      |
-      +-- browser_use.run()  # Wraps browser-use Agent class
-      +-- browser_use.extract()  # Wraps browser-use for data extraction
-```
-
-The tool registers with `tools/registry.py` as toolset `browser_use` with
-a `check_fn` that verifies `browser-use` is installed.
-
-**Alternative: MCP server** — browser-use could also be exposed as an MCP
-server for multi-agent setups where subagents need independent browser
-access. This is a follow-up, not the initial integration.
-
-### Dependencies and Requirements
-
-```
-pip install browser-use          # Core library
-playwright install chromium      # Playwright browser binary
-```
-
-Or use cloud mode with `BROWSER_USE_API_KEY` — no local browser needed.
-
-Python 3.11+, Playwright. No exotic system dependencies beyond what
-Hermes already requires for its existing browser tool.
-
-### Security Considerations
-
-| Concern                    | Mitigation                                              |
-|----------------------------|---------------------------------------------------------|
-| Arbitrary URL access       | Reuse Hermes's `website_policy` and `url_safety` modules |
-| Data exfiltration          | Browser-use agents run in isolated Playwright contexts; no access to Hermes filesystem |
-| Prompt injection via page  | browser-use feeds page content to LLM — same risk as existing browser_snapshot; already handled by Hermes prompt hardening |
-| Credential leakage         | Do not pass API keys to untrusted pages; cloud mode keeps credentials server-side |
-| Resource exhaustion        | Set max_steps on browser-use Agent to prevent infinite loops |
-| Downloaded files           | Playwright download path is sandboxed; tool should restrict to temp directory |
-
-**Key security property:** browser-use executes within Playwright's sandboxed
-browser context. The LLM controlling browser-use is Hermes itself (or a
-configured auxiliary model), not the page content. This is equivalent to the
-existing browser tool's security model.
-
-### Performance Characteristics
-
-- **Startup:** ~2-3s for Playwright Chromium launch (same as existing local mode)
-- **Per-step:** ~1-3s per LLM call + browser action (comparable to manual
-  browser_navigate + browser_snapshot loop)
-- **Full task (5-10 steps):** ~15-45s depending on page complexity
-- **Token usage:** Each step sends the accessibility tree to the LLM.
-  Browser-use supports vision mode (screenshots) which is more token-heavy.
-- **Parallelism:** Supports multiple concurrent browser agents
-
-**Comparison to existing tools:**
-For a 10-step browser task, the existing approach requires 10+ Hermes API
-calls (navigate, snapshot, click, type, snapshot, click, ...). Browser-use
-consolidates this into a single Hermes tool call that internally runs its
-own LLM loop. This reduces Hermes API round-trips but shifts the LLM cost
-to browser-use's internal model calls.
-
-### Recommendation: INTEGRATE
-
-Browser Use fills a clear gap — autonomous multi-step browser tasks — that
-complements Hermes's existing fine-grained browser tools. The integration
-is straightforward (Python library, same security model). A PoC tool is
-provided in `tools/browser_use_tool.py`.
-
----
-
-## 2. Graphify
-
-### What It Does
-
-Graphify is a knowledge graph extraction tool that processes unstructured
-text (including web content) and extracts entities, relationships, and
-structured knowledge into a graph format. It can:
-
-- Extract entities and relationships from text using NLP/LLM techniques
-- Build knowledge graphs from web-scraped content
-- Support incremental graph updates as new content is processed
-- Export graphs in standard formats (JSON-LD, RDF, etc.)
-
-(Note: "Graphify" as a project name is used by several tools. The most
-relevant for browser integration is the concept of extracting structured
-knowledge graphs from web content during or after browsing.)
-
-### Integration with Hermes
-
-**Primary path: MCP server or Hermes tool** that takes web content (from
-browser_tool or web_extract) and produces structured knowledge graphs.
-
-**Integration architecture:**
-
-```
-hermes-agent
-  tools/
-    graphify_tool.py          # NEW — knowledge graph extraction from text
-      |
-      +-- graphify.extract()  # Extract entities/relations from text
-      +-- graphify.merge()    # Merge into existing graph
-      +-- graphify.query()    # Query the accumulated graph
-```
-
-Or via MCP:
-```
-hermes-agent --mcp-server graphify-mcp
-  -> tools: graphify_extract, graphify_query, graphify_export
-```
-
-**Synergy with browser tools:**
-1. `browser_navigate` + `browser_snapshot` to get page content
-2. `graphify_extract` to pull entities and relationships
-3. Repeat across multiple pages to build a domain knowledge graph
-4. `graphify_query` to answer questions about accumulated knowledge
-
-### Dependencies and Requirements
-
-Varies significantly depending on the specific Graphify implementation.
-Typical requirements:
-- Python 3.11+
-- spaCy or similar NLP library for entity extraction
-- Optional: Neo4j or NetworkX for graph storage
-- LLM access (can reuse Hermes's existing model configuration)
-
-### Security Considerations
-
-| Concern                    | Mitigation                                              |
-|----------------------------|---------------------------------------------------------|
-| Processing untrusted text  | NLP extraction is read-only; no code execution          |
-| Graph data persistence     | Store in Hermes's data directory with appropriate permissions |
-| Information aggregation    | Knowledge graphs could accumulate sensitive data; provide clear/delete commands |
-| External graph DB access   | If using Neo4j, require authentication and restrict to localhost |
-
-### Performance Characteristics
-
-- **Extraction:** ~0.5-2s per page depending on content length and NLP model
-- **Graph operations:** Sub-second for graphs under 100K nodes
-- **Storage:** Lightweight (JSON/SQLite) for small graphs, Neo4j for large-scale
-- **Token usage:** If using LLM-based extraction, ~500-2000 tokens per page
-
-### Recommendation: INVESTIGATE FURTHER
-
-The concept is sound — knowledge graph extraction from web content is a
-natural complement to browser tools. However:
-
-1. **Multiple competing tools** exist under this name; need to identify the
-   best-maintained option
-2. **Value proposition unclear** vs. Hermes's existing memory system and
-   file-based knowledge storage
-3. **NLP dependency** adds complexity (spaCy models are ~500MB)
-
-**Suggested next steps:**
-- Evaluate specific Graphify implementations (graphify.ai, custom NLP pipelines)
-- Prototype with a lightweight approach: LLM-based entity extraction + NetworkX
-- Assess whether Hermes's existing memory/graph_store.py can serve this role
-
----
-
-## 3. Multica
-
-### What It Does
-
-Multica is a multi-agent browser coordination framework. It enables multiple
-AI agents to collaboratively browse the web, with features for:
-
-- Task decomposition: splitting complex web tasks across multiple agents
-- Shared browser state: agents see a common view of browsing progress
-- Coordination protocols: agents can communicate about what they've found
-- Parallel web research: multiple agents researching different aspects simultaneously
-
-### Integration with Hermes
-
-**Theoretical path:** Multica would integrate as a higher-level orchestration
-layer on top of Hermes's existing browser tools, coordinating multiple
-Hermes subagents (via `delegate_tool`) each with browser access.
-
-**Integration architecture:**
-
-```
-hermes-agent (orchestrator)
-  delegate_tool -> subagent_1 (browser_navigate, browser_snapshot, ...)
-  delegate_tool -> subagent_2 (browser_navigate, browser_snapshot, ...)
-  delegate_tool -> subagent_3 (browser_navigate, browser_snapshot, ...)
-                    |
-                    +-- Multica coordination layer (shared state, task splitting)
-```
-
-### Dependencies and Requirements
-
-- Complex multi-agent orchestration infrastructure
-- Shared state management between agents
-- Potentially a custom runtime for agent coordination
-- Likely requires significant architectural changes to Hermes's delegation model
-
-### Security Considerations
-
-| Concern                    | Mitigation                                              |
-|----------------------------|---------------------------------------------------------|
-| Multiple agents on same browser | Session isolation per agent (Hermes already does this) |
-| Coordinated exfiltration   | Same per-agent restrictions apply                       |
-| Amplified prompt injection | Each agent processes its own pages independently         |
-| Resource multiplication    | N agents = N browser instances = Nx resource usage      |
-
-### Performance Characteristics
-
-- **Scaling:** Near-linear improvement for embarrassingly parallel tasks
-  (e.g., "research 10 companies simultaneously")
-- **Overhead:** Significant coordination overhead for tightly coupled tasks
-- **Resource cost:** Each agent needs its own LLM calls + browser instance
-- **Complexity:** Debugging multi-agent browser workflows is extremely difficult
-
-### Recommendation: SKIP (for now)
-
-Multica addresses a real need (parallel web research) but is premature for
-Hermes for several reasons:
-
-1. **Hermes already has subagent delegation** (`delegate_tool`) — agents can
-   already do parallel browser work without Multica
-2. **No mature implementation** — Multica is more of a concept than a
-   production-ready tool
-3. **Complexity vs. benefit** — the coordination overhead and debugging
-   difficulty outweigh the benefits for most use cases
-4. **Better alternatives exist** — for parallel research, simply delegating
-   multiple subagents with browser tools is simpler and already works
-
-**Revisit when:** Hermes's delegation model supports shared state between
-subagents, or a mature Multica implementation emerges.
-
----
-
-## Integration Roadmap
-
-### Phase 1: Browser Use PoC (this PR)
-- [x] Create `tools/browser_use_tool.py` wrapping browser-use as Hermes tool
-- [x] Create `docs/browser-integration-analysis.md` (this document)
-- [ ] Test with real browser tasks
-- [ ] Add to toolset configuration
-
-### Phase 2: Browser Use Production (follow-up)
-- [ ] Add `browser_use` to `toolsets.py` toolset definitions
-- [ ] Add configuration options in `config.yaml`
-- [ ] Add tests in `tests/test_browser_use_tool.py`
-- [ ] Consider MCP server variant for subagent use
-
-### Phase 3: Graphify Investigation (follow-up)
-- [ ] Evaluate specific Graphify implementations
-- [ ] Prototype lightweight LLM-based entity extraction tool
-- [ ] Assess integration with existing `graph_store.py`
-- [ ] Create PoC if investigation is positive
-
-### Phase 4: Multi-Agent Browser (future)
-- [ ] Monitor Multica ecosystem maturity
-- [ ] Evaluate when delegation model supports shared state
-- [ ] Consider simpler parallel delegation patterns first
-
----
-
-## Appendix: Existing Browser Stack
-
-Hermes already has a comprehensive browser tool stack:
-
-| Component             | Description                                      |
-|-----------------------|--------------------------------------------------|
-| `browser_tool.py`     | Low-level agent-controlled browser (navigate, click, type, snapshot) |
-| `browser_camofox.py`  | Anti-detection browser via Camofox REST API       |
-| `browser_providers/`  | Cloud providers (Browserbase, Browser Use API, Firecrawl) |
-| `web_tools.py`        | Web search (Parallel) and extraction (Firecrawl) |
-| `mcp_tool.py`         | MCP client for connecting external tool servers   |
-
-The existing stack covers:
-- **Local browsing:** Headless Chromium via agent-browser CLI
-- **Cloud browsing:** Browserbase, Browser Use cloud, Firecrawl
-- **Anti-detection:** Camofox (local) or Browserbase advanced stealth
-- **Content extraction:** Firecrawl for clean markdown extraction
-- **Search:** Parallel AI web search
-
-New browser integrations should complement rather than replace these tools.

docs/fleet-sitrep-2026-04-06.md

@@ -1,132 +0,0 @@
-# Fleet SITREP — April 6, 2026
-
-**Classification:** Consolidated Status Report
-**Compiled by:** Ezra
-**Acknowledged by:** Claude (Issue #143)
-
----
-
-## Executive Summary
-
-Allegro executed 7 tasks across infrastructure, contracting, audits, and security. Ezra shipped PR #131, filed formalization audit #132, delivered quarterly report #133, and self-assigned issues #134–#138. All wizard activity mapped below.
-
----
-
-## 1. Allegro 7-Task Report
-
-| Task | Description | Status |
-|------|-------------|--------|
-| 1 | Roll Call / Infrastructure Map | ✅ Complete |
-| 2 | Dark industrial anthem (140 BPM, Suno-ready) | ✅ Complete |
-| 3 | Operation Get A Job — 7-file contracting playbook pushed to `the-nexus` | ✅ Complete |
-| 4 | Formalization audit filed ([the-nexus #893](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/893)) | ✅ Complete |
-| 5 | GrepTard Memory Report — PR #525 on `timmy-home` | ✅ Complete |
-| 6 | Self-audit issues #894–#899 filed on `the-nexus` | ✅ Filed |
-| 7 | `keystore.json` permissions fixed to `600` | ✅ Applied |
-
-### Critical Findings from Task 4 (Formalization Audit)
-
-- GOFAI source files missing — only `.pyc` remains
-- Nostr keystore was world-readable — **FIXED** (Task 7)
-- 39 burn scripts cluttering `/root` — archival pending ([#898](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/898))
-
----
-
-## 2. Ezra Deliverables
-
-| Deliverable | Issue/PR | Status |
-|-------------|----------|--------|
-| V-011 fix + compressor tuning | [PR #131](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/pulls/131) | ✅ Merged |
-| Formalization audit (hermes-agent) | [Issue #132](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/issues/132) | Filed |
-| Quarterly report (MD + PDF) | [Issue #133](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/issues/133) | Filed |
-| Burn-mode concurrent tool tests | [Issue #134](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/issues/134) | Assigned → Ezra |
-| MCP SDK migration | [Issue #135](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/issues/135) | Assigned → Ezra |
-| APScheduler migration | [Issue #136](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/issues/136) | Assigned → Ezra |
-| Pydantic-settings migration | [Issue #137](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/issues/137) | Assigned → Ezra |
-| Contracting playbook tracker | [Issue #138](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/issues/138) | Assigned → Ezra |
-
----
-
-## 3. Fleet Status
-
-| Wizard | Host | Status | Blocker |
-|--------|------|--------|---------|
-| **Ezra** | Hermes VPS | Active — 5 issues queued | None |
-| **Bezalel** | Hermes VPS | Gateway running on 8645 | None |
-| **Allegro-Primus** | Hermes VPS | **Gateway DOWN on 8644** | Needs restart signal |
-| **Bilbo** | External | Gemma 4B active, Telegram dual-mode | Host IP unknown to fleet |
-
-### Allegro Gateway Recovery
-
-Allegro-Primus gateway (port 8644) is down. Options:
-1. **Alexander restarts manually** on Hermes VPS
-2. **Delegate to Bezalel** — Bezalel can issue restart signal via Hermes VPS access
-3. **Delegate to Ezra** — Ezra can coordinate restart as part of issue #894 work
-
----
-
-## 4. Operation Get A Job — Contracting Playbook
-
-Files pushed to `the-nexus/operation-get-a-job/`:
-
-| File | Purpose |
-|------|---------|
-| `README.md` | Master plan |
-| `entity-setup.md` | Wyoming LLC, Mercury, E&O insurance |
-| `service-offerings.md` | Rates $150–600/hr; packages $5k/$15k/$40k+ |
-| `portfolio.md` | Portfolio structure |
-| `outreach-templates.md` | Cold email templates |
-| `proposal-template.md` | Client proposal structure |
-| `rate-card.md` | Rate card |
-
-**Human-only mile (Alexander's action items):**
-
-1. Pick LLC name from `entity-setup.md`
-2. File Wyoming LLC via Northwest Registered Agent ($225)
-3. Get EIN from IRS (free, ~10 min)
-4. Open Mercury account (requires EIN + LLC docs)
-5. Secure E&O insurance (~$150–250/month)
-6. Restart Allegro-Primus gateway (port 8644)
-7. Update LinkedIn using profile template
-8. Send 5 cold emails using outreach templates
-
----
-
-## 5. Pending Self-Audit Issues (the-nexus)
-
-| Issue | Title | Priority |
-|-------|-------|----------|
-| [#894](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/894) | Deploy burn-mode cron jobs | CRITICAL |
-| [#895](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/895) | Telegram thread-based reporting | Normal |
-| [#896](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/896) | Retry logic and error recovery | Normal |
-| [#897](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/897) | Automate morning reports at 0600 | Normal |
-| [#898](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/898) | Archive 39 burn scripts | Normal |
-| [#899](https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/899) | Keystore permissions | ✅ Done |
-
----
-
-## 6. Revenue Timeline
-
-| Milestone | Target | Unlocks |
-|-----------|--------|---------|
-| LLC + Bank + E&O | Day 5 | Ability to invoice clients |
-| First 5 emails sent | Day 7 | Pipeline generation |
-| First scoping call | Day 14 | Qualified lead |
-| First proposal accepted | Day 21 | **$4,500–$12,000 revenue** |
-| Monthly retainer signed | Day 45 | **$6,000/mo recurring** |
-
----
-
-## 7. Delegation Matrix
-
-| Owner | Owns |
-|-------|------|
-| **Alexander** | LLC filing, EIN, Mercury, E&O, LinkedIn, cold emails, gateway restart |
-| **Ezra** | Issues #134–#138 (tests, migrations, tracker) |
-| **Allegro** | Issues #894, #898 (cron deployment, burn script archival) |
-| **Bezalel** | Review formalization audit for Anthropic-specific gaps |
-
----
-
-*SITREP acknowledged by Claude — April 6, 2026*
-*Source issue: [hermes-agent #143](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/issues/143)*